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.

  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:

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

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

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

10. 🔄 Plan Mode Protocol (MANDATORY)

• Planning Phase:
  • Whenever using Plan Mode to outline a task, a TODO list MUST be outputted to docs/ai_docs/plan/[feature_name].md.
• Execution & Reporting:
  • Every time a TODO item is completed, the corresponding .md document MUST be updated.
  • After updating the document, report to the user with the following:
    1. Completed Items: What was just finished.
    2. User Acceptance Rules: Instructions on how the user can test/verify the current progress.
    3. Next Step: The next TODO item to be tackled.
• Strict Confirmation:
  • After reporting progress, Claude MUST stop and wait.
  • Do NOT proceed to the next TODO until the user has replied with confirmation/approval.