forked from datawhale/whale-town-front
b9182bbc2e
## 🎯 主要改进 ### 1. 明确项目定位 - 清晰定义 "WhaleTown" 为 2D 俯视像素风 RPG - 指定 Godot 4.2+ 引擎（禁止 3.x 语法） - 强调分层架构：`_Core`（框架）、`Scenes`（玩法）、`UI`（界面） ### 2. 完善开发规范 - ✅ 添加 Input Map 配置（WASD、交互键、暂停键） - ✅ 明确文件路径规则（STRICT LOWERCASE） - ✅ 添加 EventNames.gd 示例代码 - ✅ 完善测试代码示例（GUT 框架） - ✅ 优化代码模板（分区注释） ### 3. 强化技术约束 - 📋 严格类型系统（强制静态类型） - 🏛 事件驱动架构（EventSystem 解耦） - 🚫 禁止模式列表（yield、Linear Filter 等） - ✅ 必须测试覆盖（所有 Core 管理器） ### 4. 代码模板改进 - 添加结构化注释（Exports、References、Lifecycle、Methods） - 展示最佳实践（@onready、%UniqueName、私有方法前缀） - 包含完整的玩家移动示例 ### 5. AI 指令优化 - 直接对 AI 说话（"Claude: Root folders MUST be lowercase"） - 明确的优先级（STRICT、The Law、MANDATORY） - 提供决策指南（Area2D vs Body、Enum vs StateChart） ## 📊 文档结构 - 90 行，精炼完整 - Emoji 视觉层级（🛠 命令、📂 文件、📋 标准、🏛 架构） - 覆盖：文件组织、编码标准、架构设计、测试要求、代码模板 ## ✨ 质量提升 - 统一路径大小写（tests/ 而非 Tests/） - 添加 EventNames.gd 完整示例 - 完善测试代码（watch_signals、assert_signal_emitted） - 明确 Godot 版本约束（4.2+） ## 🎯 目标 为 AI 提供清晰、严格、可执行的开发规范， 确保代码质量和架构一致性。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# 🎯 CLAUDE.md - WhaleTown Project Instructions
|
|
|
|
## 1. Project Vision & Context
|
|
- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
|
|
- **Engine**: Godot 4.2+ (Strictly NO Godot 3.x syntax).
|
|
- **Architecture**: Strictly layered: `_Core` (Framework), `Scenes` (Gameplay), `UI` (Interface).
|
|
- **Core Principle**: "Signal Up, Call Down". High decoupling via `EventSystem`.
|
|
|
|
## 2. 🛠 Command Reference & Setup
|
|
- **Input Map (Required Configuration)**:
|
|
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / Arrows)
|
|
- `interact` (E Key / Space)
|
|
- `pause` (ESC)
|
|
- **Run Game**: `godot --path .`
|
|
- **Run Tests (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
|
- **Init Structure**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
|
|
|
## 3. 📂 File Path Rules (STRICT LOWERCASE)
|
|
*Claude: Root folders MUST be lowercase. Scripts and Scenes MUST stay together.*
|
|
- **Core Managers**: `_Core/managers/[Name].gd`
|
|
- **Core Systems**: `_Core/systems/[Name].gd`
|
|
- **Entities**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (Script `.gd` in same folder).
|
|
- **Maps**: `Scenes/Maps/[map_name].tscn`
|
|
- **Components**: `Scenes/Components/[ComponentName].gd` (Reusable logic nodes).
|
|
- **UI Windows**: `UI/Windows/[WindowName].tscn`
|
|
- **Tests**: `tests/[unit|integration]/test_[name].gd` (Folder is lowercase `tests`).
|
|
|
|
## 4. 📋 Coding Standards (The Law)
|
|
- **Type Safety**: ALWAYS use strict static typing: `var speed: float = 100.0`, `func _ready() -> void`.
|
|
- **Naming Conventions**:
|
|
- `class_name PascalCase` at the top of every script.
|
|
- Variables/Functions: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
|
|
- Private members: Prefix with underscore `_` (e.g., `var _health: int`).
|
|
- **Node Access**: Use `%UniqueName` for UI and internal scene components.
|
|
- **Signals**: Use "Signal Up, Call Down". Parent calls child methods; Child emits signals.
|
|
- **Forbidden Patterns**:
|
|
- ❌ NO `yield()` -> Use `await`.
|
|
- ❌ NO `get_node()` in `_process` -> Cache with `@onready`.
|
|
- ❌ NO Linear Filter -> All Sprite2D/TileMap resources MUST use **Nearest** filter.
|
|
|
|
## 5. 🏛 Architecture & Communication
|
|
- **EventSystem**: Use `_Core/systems/EventSystem.gd` for cross-module messaging.
|
|
- **Event Registry**: Use `class_name EventNames` in `_Core/EventNames.gd`.
|
|
```gdscript
|
|
class_name EventNames
|
|
const PLAYER_MOVED = "player_moved"
|
|
const INTERACT_PRESSED = "interact_pressed"
|
|
const NPC_TALKED = "npc_talked"
|
|
Singletons: Only GameManager, SceneManager, EventSystem allowed as Autoloads.
|
|
Decoupling: Low-level entities MUST NOT reference GameManager. Use events.
|
|
6. 🏗 Implementation Details
|
|
Player: CharacterBody2D. Must include Camera2D with position_smoothing_enabled = true.
|
|
NPC/Interactables: Use Area2D named InteractionArea. Trigger via EventSystem.
|
|
TileMap Layers:
|
|
Layer 0: Ground (No collision).
|
|
Layer 1: Obstacles (Physics Layer enabled).
|
|
Layer 2: Decoration (Y-Sort enabled).
|
|
Camera: Must auto-calculate limits via TileMap.get_used_rect().
|
|
7. 🧪 Testing Requirements (MANDATORY)
|
|
Coverage: Every Manager/System in _Core/ MUST have a GUT test.
|
|
Naming: Test files must start with test_ and extend GutTest.
|
|
Example:
|
|
code
|
|
Gdscript
|
|
extends GutTest
|
|
func test_event_emission():
|
|
var sender = Node.new()
|
|
watch_signals(EventSystem)
|
|
EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
|
|
assert_signal_emitted(EventSystem, "event_raised")
|
|
8. 🧘 The Zen of Development
|
|
Juice or Death: Every interaction (UI popup, NPC talk) MUST have a Tween placeholder.
|
|
Zero Magic Numbers: All speeds/timers MUST be @export or defined in Config/.
|
|
Simplicity: If a function does two things, split it.
|
|
Back of the Fence: Hidden logic (like ResponseHandler.gd) must be as clean as the HUD.
|
|
9. 📝 Code Template (Entity Pattern)
|
|
code
|
|
Gdscript
|
|
extends CharacterBody2D
|
|
class_name Player
|
|
|
|
# 1. Exports & Constants
|
|
@export var move_speed: float = 200.0
|
|
|
|
# 2. Node References
|
|
@onready var sprite: Sprite2D = %Sprite2D
|
|
|
|
# 3. Lifecycle
|
|
func _physics_process(delta: float) -> void:
|
|
_move(delta)
|
|
|
|
# 4. Private Methods
|
|
func _move(_delta: float) -> void:
|
|
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
velocity = dir * move_speed
|
|
move_and_slide() |