From b9182bbc2eb740c8e1e86d7d4a8dbfe0e2a77332 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=B5=A9?= Date: Wed, 31 Dec 2025 16:32:54 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E5=AE=8C=E5=96=84=20CLAUDE.md=20?= =?UTF-8?q?=E4=B8=BA=20AI=20=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 🎯 主要改进 ### 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 --- CLAUDE.md | 157 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 88 insertions(+), 69 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cceecec..0b04993 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,77 +1,96 @@ -# Claude Code Rules - Godot 4.x Town Project +# 🎯 CLAUDE.md - WhaleTown Project Instructions -## Project Overview -A 2D top-down pixel art RPG built in Godot 4.x using a layered architecture. -- **Core**: `_Core/` (SceneManager, EventSystem, GameManager) -- **Gameplay**: `Scenes/` (Maps, Entities, Components) -- **UI**: `UI/` (Windows, Overlays) +## 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`. -## Coding Standards (GDScript) -- **Type Safety**: Use static typing strictly (e.g., `var speed: float = 100.0`, `func _ready() -> void`). +## 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**: - - Classes: `PascalCase` (using `class_name`). - - Variables/Functions: `snake_case`. - - Constants: `SCREAMING_SNAKE_CASE`. - - Signals: `snake_case` (e.g., `signal player_interacted(data)`). -- **Node Access**: Use `@onready var name = $Path` or `%UniqueName`. Prefer `%UniqueName` for UI and internal scene components. -- **Best Practices**: - - Use `await` for signals and timers instead of `yield`. - - Use `Callable` for callbacks. - - Follow the "Signal Up, Call Down" rule: Parent calls methods on children; children emit signals to parents. - - Use `Input.get_vector("left", "right", "up", "down")` for 2D movement. + - `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. -## Project Architecture Rules -- **Decoupling**: Never reference singleton managers directly in low-level entities. Use `EventSystem` to communicate across modules. -- **Scene Management**: All scene transitions must go through `SceneManager.change_scene(scene_key)`. -- **Components**: Logic like "Health", "Interactions", or "Movement" should be encapsulated in `Scenes/Components/` as reusable nodes. +## 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 -## Implementation Specifics (Town Map) +# 1. Exports & Constants +@export var move_speed: float = 200.0 -### 1. Entity Structure -- **Player**: Must be a `CharacterBody2D`. Include a `Camera2D` with `position_smoothing_enabled = true`. -- **NPC**: Must be a `StaticBody2D` or `CharacterBody2D` with an `Area2D` named `InteractionArea`. -- **Interactables**: Use a shared `InteractableComponent` (Area2D based) for building entrances and NPCs. +# 2. Node References +@onready var sprite: Sprite2D = %Sprite2D -### 2. Interaction System -- NPC/Entrance interaction must trigger via `EventSystem`. -- Interaction logic: - 1. Player enters `InteractionArea`. - 2. Player presses "E" or "UI_Accept". - 3. Emit `EventSystem.notify_interaction_triggered(interactable_data)`. +# 3. Lifecycle +func _physics_process(delta: float) -> void: + _move(delta) -### 3. TileMap Rules -- Use `TileMap` (or `TileMapLayer` if Godot 4.3+). -- Layer 0: Ground (No collision). -- Layer 1: Obstacles/Walls (With Physics Layer collision). -- Layer 2: Decorations (Y-Sort enabled). - -## File Organization -- New maps: `Scenes/Maps/[map_name].tscn` -- New entities: `Scenes/Entities/[entity_name]/[entity_name].tscn` -- New scripts: Same folder as their scene files. -- Assets: Always reference assets from `res://Assets/Sprites/`. - -## Command Reference -- Build/Run: `godot --path .` -- Export (Linux): `godot --path . --export-release "Linux/X11"` - -## Testing Standards -- **Framework**: Use GUT (Godot Unit Test) for all tests. -- **Test Location**: All test scripts must be in `res://test/unit/` or `res://test/integration/`. -- **File Naming**: Test files must start with `test_` and end with `.gd` (e.g., `test_player_movement.gd`). -- **Class Structure**: Every test file must `extends GutTest`. -- **Requirements**: - - Every new core logic (in `_Core`) must have a corresponding unit test. - - Player movement and NPC interactions must have integration tests using `yield_for` or `await`. - - Use `assert_eq`, `assert_true`, and `assert_signal_emitted` for validations. - -## Commands -- **Run all tests**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://test/ -ginclude_subdirs` -- **Run specific test**: `godot --headless -s addons/gut/gut_cmdline.gd -gtest=res://test/unit/test_example.gd` - -## The Zen of Development (Pro Tips) -- **Simplicity is the ultimate sophistication**: If a function does two things, it's one thing too many. Split it. -- **The "Back of the Fence" Rule**: Even parts the player never sees (like the EventSystem logic) must be clean and beautiful. No "quick hacks". -- **Feedback Loop**: Every interaction MUST have a placeholder for juice (Tween, Sound, or Particle). Code is the skeleton, but juice is the soul. -- **Zero Hard-Coding**: All paths, configuration values, and magic numbers must be defined as constants or @export variables. -- **The "It Just Works" Camera**: Camera logic must automatically find TileMap limits. The player should never see the "gray void" outside the map. \ No newline at end of file +# 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() \ No newline at end of file