whale-town-front/claude.md

# 🎯 CLAUDE.md - WhaleTown Project Instructions

## 1. Project Vision & Context
- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
- **Engine**: Godot 4.5+ (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: `camelCase` (e.g., `var moveSpeed`, `func updateMovement()`). Constants: `UPPER_CASE`.
  - Private members: Prefix with underscore `_` (e.g., `var _velocity: Vector2`).
- **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**:
  ```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. Standard Development Workflow (MANDATORY)

**CRITICAL**: When performing ANY development task (implementing features, fixing bugs, creating scenes), you MUST follow this 7-step standardized workflow:

### Quick Start: Use the Skill (Recommended) ⭐
```bash
/whaletown-developer [任务描述]
```
Example: `/whaletown-developer 实现玩家二段跳功能`

The skill automates the entire 7-step process and enforces all quality standards.

### The 7-Step Workflow

```
Step 1: Architecture Analysis    → Read docs/02-开发规范/架构与通信规范.md
Step 2: Implementation           → Follow layered architecture, type safety, EventSystem
Step 3: Comment Validation       → Read docs/02-开发规范/代码注释规范.md
Step 4: Naming Validation        → Read docs/02-开发规范/命名规范.md
Step 5: Test Writing             → Read docs/03-技术实现/测试指南.md
Step 6: Test Execution           → Run: godot --headless -s addons/gut/gut_cmdline.gd
Step 7: Git Commit               → Read docs/02-开发规范/Git提交规范.md
```

### Workflow Enforcement Rules

1. **Never Skip Steps**: All 7 steps are mandatory for every development task
2. **Read Specs First**: Each step requires reading the corresponding specification document
3. **Use TodoWrite**: Track progress through all 7 steps using TodoWrite tool
4. **Mark Completed**: Mark each step as completed immediately after finishing
5. **Quality Gates**: Cannot proceed to next step until current step passes validation

### Naming Convention Clarification

**IMPORTANT**: The project uses **camelCase** for variables/functions, NOT snake_case:
- ✅ Correct: `var moveSpeed: float`, `func updateMovement()`
- ❌ Incorrect: `var move_speed: float`, `func update_movement()`

See `docs/02-开发规范/命名规范.md` for complete details.

### Quality Checklist (Every Development Task)

- [ ] File location follows layered architecture (_Core, scenes, UI)
- [ ] Uses EventSystem for cross-module communication
- [ ] Event names added to EventNames.gd
- [ ] All variables/functions have type annotations
- [ ] Naming: PascalCase (classes), camelCase (vars/funcs), UPPER_CASE (constants)
- [ ] File header comment complete
- [ ] Public functions have complete documentation
- [ ] Unit tests created and passing
- [ ] Git commit message follows specification
- [ ] No Godot 3.x syntax (await not yield, @onready cached)

### Reference Documents

- **Full Workflow**: `docs/AI_docs/workflows/standard_development_workflow.md`
- **Quick Checklist**: `.claude/skills/whaletown-developer/references/checklist.md`
- **Skill Definition**: `.claude/skills/whaletown-developer/SKILL.md`

**Remember**: Consistency through automation. Use `/whaletown-developer` to ensure no steps are missed.

## 9. 🧘 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.

## 10. 📝 Code Template (Entity Pattern)
```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()