Files

王浩 b9182bbc2e docs：完善 CLAUDE.md 为 AI 开发规范文档

## 🎯 主要改进

### 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>

2025-12-31 16:32:54 +08:00

4.2 KiB

Raw Blame History

🎯 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.

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()

4.2 KiB Raw Blame History