From 642a99970cc7a5c4bf1b0f5f209e09083976a949 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=B5=A9?= Date: Wed, 31 Dec 2025 16:07:54 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E6=B7=BB=E5=8A=A0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= =?UTF-8?q?=20CLAUDE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 📋 新增内容 添加了完整的 Claude Code 开发规范文档，包括： ### 核心规范 - **项目概述**: 2D 俯视像素风 RPG 游戏架构 - **编码标准**: - 严格类型系统 - 统一命名规范（PascalCase, snake_case, SCREAMING_SNAKE_CASE） - 节点访问规范（@onready, %UniqueName） - 最佳实践（await, Callable, Signal Up/Call Down） ### 架构规则 - **解耦原则**: 低层级实体通过 EventSystem 通信 - **场景管理**: 统一使用 SceneManager.change_scene() - **组件化**: 可复用逻辑封装到 Scenes/Components/ ### 实现规范 - **实体结构**: - Player: CharacterBody2D + Camera2D - NPC: StaticBody2D/CharacterBody2D + InteractionArea - Interactables: 共享 InteractableComponent - **交互系统**: 通过 EventSystem.notify_interaction_triggered() - **TileMap 规则**: 分层设计（地面、障碍、装饰） ### 文件组织 - 地图: Scenes/Maps/[map_name].tscn - 实体: Scenes/Entities/[entity_name]/[entity_name].tscn - 脚本: 与场景文件同目录 - 资源: res://Assets/Sprites/ ### 测试标准 - 使用 GUT 测试框架 - 测试文件位置: res://test/unit/ 或 res://test/integration/ - 文件命名: test_*.gd - 核心逻辑必须有单元测试 - 玩家移动和 NPC 交互需要集成测试 ### 开发理念 - 简约至上：函数单一职责 - "栅栏后规则": 即使不可见的代码也要干净优美 - 反馈循环：每个交互都要有特效/音效占位 - 零硬编码：所有路径和配置使用常量或 @export - "自动工作"的相机：自动检测 TileMap 边界 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cceecec --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# Claude Code Rules - Godot 4.x Town Project + +## 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) + +## Coding Standards (GDScript) +- **Type Safety**: Use static typing strictly (e.g., `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. + +## 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. + +## Implementation Specifics (Town Map) + +### 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. 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. 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