forked from datawhale/whale-town-front
642a99970c
## 📋 新增内容 添加了完整的 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 <noreply@anthropic.com>
77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
# 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. |