130 lines
5.5 KiB
Markdown
130 lines
5.5 KiB
Markdown
# Dawn Godot — Claude Code Guide
|
||
|
||
## Project
|
||
|
||
Godot 4.4 RPG prototype, GDScript only. Viewport 480×270 (scaled 3× to 1440×810), GL Compatibility renderer.
|
||
|
||
---
|
||
|
||
## Code Style
|
||
|
||
### Naming
|
||
- **camelCase** for variables and functions: `fighterMap`, `startBattle()`, `getFullParty()`
|
||
- **PascalCase** for class names, enums, and enum values: `BattleFighter`, `FighterTeam`, `ALLY`
|
||
- **SCREAMING_SNAKE_CASE** for constants and static data: `CUTSCENE_CONTINUE`, `ITEM_DATA`, `PARTY_JOHN`
|
||
- **No** trailing underscores on private methods — use a leading underscore only for internal helpers that shouldn't be called externally: `_onConversationInteract()`, `_applyGravity()`
|
||
|
||
### Formatting
|
||
- 2-space indent (not 4, not tabs)
|
||
- Type annotations on all variable declarations and function signatures: `var health:int`, `func damage(amount:int, crit:bool) -> void:`
|
||
- No space between variable name and type: `var foo:int` not `var foo : int`
|
||
- Blank lines between logical sections within a file; comment headers (`# Health`, `# Signals`) to label groups
|
||
|
||
### General Rules
|
||
- `assert()` for invariants and preconditions — prefer it over silent failures
|
||
- `params:Dictionary` pattern for multi-argument constructors/callables; access with `.get('key', default)` or `.has('key')` guards
|
||
- `match` for enum dispatch; `if/elif` chains for non-exhaustive checks
|
||
- `continue` / early `return` to reduce nesting rather than deep else-branches
|
||
- Avoid long inline lambdas; extract named static functions where logic is non-trivial
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
### Singletons (Autoloads)
|
||
All globally accessible by their handle. Never instantiate these — access via the global name.
|
||
|
||
| Handle | Role |
|
||
|---|---|
|
||
| `SCENE` | Current scene state; call `SCENE.setScene(SceneSingleton.SceneType.X)` to switch |
|
||
| `TRANSITION` | Fade in/out; `TRANSITION.fade(FadeType, duration, color)` |
|
||
| `BATTLE` | Battle state and fighter map |
|
||
| `PARTY` | Party members (`PARTY.getFullParty()`) and `PARTY.BACKPACK` inventory |
|
||
| `OVERWORLD` | Map switching with threaded loading |
|
||
| `COOKING` | Cooking mini-game lifecycle |
|
||
| `SAVE` | Persistence (stub) |
|
||
| `QUEST` | Quest management (stub) |
|
||
| `CUTSCENE` | Cutscene global (stub) |
|
||
| `UI` | Root UI accessor — `UI.TEXTBOX`, `UI.DEBUG_MENU` |
|
||
|
||
### Scene Graph
|
||
```
|
||
RootScene (Node3D)
|
||
└─ overworld / battle / cooking / initial ← one shown at a time
|
||
RootUI (Control, always visible)
|
||
└─ VNTextbox, DebugMenu
|
||
```
|
||
|
||
`RootScene` listens to `SCENE.sceneChanged` and shows/hides the appropriate sub-tree.
|
||
|
||
### Cutscene / Event Queue
|
||
`Cutscene` is the universal sequencing engine. It holds an `Array[Dictionary]` queue; each entry has a `"function": Callable` plus arbitrary data keys.
|
||
|
||
**Return codes from a callable:**
|
||
- `Cutscene.CUTSCENE_CONTINUE` — advance to next item
|
||
- `Cutscene.CUTSCENE_END` — stop the cutscene
|
||
- An integer index — jump to that position
|
||
|
||
**Position constants when adding:**
|
||
- `Cutscene.CUTSCENE_ADD_END` — append (default)
|
||
- `Cutscene.CUTSCENE_ADD_NEXT` — insert immediately after current
|
||
|
||
**Callable pattern** — every action class exposes a pair:
|
||
```gdscript
|
||
# The actual callable (static, takes params:Dictionary, returns int)
|
||
static func myCallable(params:Dictionary) -> int:
|
||
...
|
||
return Cutscene.CUTSCENE_CONTINUE
|
||
|
||
# Factory that builds the dictionary for addCallable()
|
||
static func getMyCallable(arg) -> Dictionary:
|
||
return { "function": myCallable, "myArg": arg }
|
||
```
|
||
|
||
### Data Registry Pattern
|
||
Static registries (Item, Recipe) follow this pattern:
|
||
1. `enum Id { NULL, ... }` — typed identifier
|
||
2. `static var DATA:Array = []` — indexed by Id value
|
||
3. `static func define(params) -> Dictionary` — called at class load to populate `DATA`
|
||
4. `static var FOO = define({...})` — registers the entry as a static var
|
||
5. `static func get*(id) -> *` — typed accessors
|
||
|
||
### `_init(params:Dictionary)` Pattern
|
||
Non-Node data classes (`BattleFighter`, `BattleDecision`, `ItemStack`, etc.) use a single `params` dictionary constructor with `.get('key', default)` for optional fields.
|
||
|
||
---
|
||
|
||
## System Conventions
|
||
|
||
### Battle
|
||
- Fighters live in `BATTLE.fighterMap: Dictionary[BattlePosition, BattleFighter]`
|
||
- `BattleFighter` is pure data (no Node); `BattleFighterScene` is the 3D visual
|
||
- Battle flow is driven by `BattleCutsceneAction.playerDecisionCallable` which loops via `CUTSCENE_ADD_END`
|
||
- New moves go in [battle/fighter/BattleMove.gd](battle/fighter/BattleMove.gd) as static presets; add corresponding `perform()` logic in [battle/action/BattleMove.gd](battle/action/BattleMove.gd)
|
||
|
||
### Entities (Overworld)
|
||
- All interactable world objects extend `Entity` (CharacterBody3D)
|
||
- Interaction type is set via `@export var interactType:InteractType`
|
||
- Interaction routing lives in `EntityInteractableArea.onInteract()` — add new `InteractType` values there
|
||
|
||
### Items
|
||
- Register new items in [item/Item.gd](item/Item.gd) — add to `Id` enum and call `itemDefine()`
|
||
- Item ID order in the enum must match insertion order into `ITEM_DATA`
|
||
|
||
### UI
|
||
- `UI.TEXTBOX.setTextAndWait(text)` — show dialogue and await player dismiss (use `await`)
|
||
- Movement is blocked automatically when `UI.TEXTBOX` is visible (`EntityMovement._canMove()` checks this)
|
||
- Menus extend `ClosableMenu` for open/close/toggle + `closed`/`opened` signals
|
||
|
||
---
|
||
|
||
## What's Incomplete / Stub
|
||
- `Save.gd` — no actual serialization yet
|
||
- `Quest.gd` — empty singleton
|
||
- `CutsceneSingleton.gd` — minimal stub
|
||
- `BattleFighter.getAIDecision()` — always returns `null`
|
||
- `BattleDecision.execute()` — stub
|
||
- `BattleItem.perform()` — stub
|
||
- `CookingScene.tscn` — placeholder UI only
|
||
- `Pause.gd` — commented-out logic
|