Docs

.claude/rpg/cutscene.md

@@ -0,0 +1,149 @@
+# Cutscenes
+
+Two distinct layers: a low-level engine sequencer (`src/dusk/cutscene/`) and a higher-level RPG wrapper (`src/dusk/rpg/cutscene/`). Almost all game code works with the RPG layer.
+
+---
+
+## Engine sequencer (`src/dusk/cutscene/`)
+
+`cutscene_t CUTSCENE` is a minimal event runner with up to `CUTSCENE_EVENT_COUNT_MAX` (16) `cutsceneevent_t` slots. Each event has three callbacks:
+
+```c
+typedef struct {
+  errorret_t (*onStart)(void);
+  errorret_t (*onUpdate)(void);
+  errorret_t (*onEnd)(void);
+} cutsceneevent_t;
+```
+
+API:
+```c
+cutscenePlay(events, count);   // copy events array and start from index 0
+cutsceneAdvance();             // end current event, start next (deactivates after last)
+cutsceneStop();                // abort immediately
+cutsceneIsActive();            // bool
+```
+
+This layer is primarily used by the RPG cutscene system — game code doesn't normally touch it directly.
+
+---
+
+## RPG cutscene layer (`src/dusk/rpg/cutscene/`)
+
+### Data structures
+
+A `cutscene_t` is just a pointer to an item array and a count:
+
+```c
+typedef struct cutscene_s {
+  const cutsceneitem_t *items;
+  uint8_t itemCount;
+} cutscene_t;
+```
+
+A `cutsceneitem_t` is a tagged union of all item types:
+
+```c
+typedef struct cutsceneitem_s {
+  cutsceneitemtype_t type;
+  union {
+    cutscenetext_t    text;      // display text in textbox
+    cutscenecallback_t callback; // call a void(*)(void) function
+    cutscenewait_t    wait;      // pause for a fixed_t duration (seconds)
+    const cutscene_t *cutscene;  // nest another cutscene
+  };
+} cutsceneitem_t;
+```
+
+### Item types
+
+| Type constant | Payload | Behaviour |
+|---|---|---|
+| `CUTSCENE_ITEM_TYPE_TEXT` | `cutscenetext_t` — `text[256]` + `rpgtextboxpos_t position` | Shows textbox; advances on player confirm input |
+| `CUTSCENE_ITEM_TYPE_CALLBACK` | `cutscenecallback_t` (function pointer) | Calls the function once, then immediately advances |
+| `CUTSCENE_ITEM_TYPE_WAIT` | `cutscenewait_t` (a `fixed_t` in seconds) | Counts down `animTime` each frame, then advances |
+| `CUTSCENE_ITEM_TYPE_CUTSCENE` | `const cutscene_t *` | Plays the nested cutscene before continuing |
+
+### Runtime state
+
+`cutscenesystem_t CUTSCENE_SYSTEM` tracks:
+- `scene` — pointer to the active `cutscene_t`
+- `currentItem` — index into `scene->items[]`
+- `data` — per-item runtime data (`cutsceneitemdata_t`, currently just `cutscenewaitdata_t`)
+- `mode` — the current `cutscenemode_t`
+
+API:
+```c
+cutsceneSystemStartCutscene(cutscene);   // begin playing a cutscene
+cutsceneSystemNext();                    // advance to next item
+cutsceneSystemUpdate();                  // called each frame from rpgUpdate
+cutsceneSystemGetCurrentItem();          // inspect active item
+```
+
+### Cutscene mode (`cutscenemode.h`)
+
+Each item can run in one of three modes:
+
+```c
+CUTSCENE_MODE_NONE           // no cutscene active
+CUTSCENE_MODE_FULL_FREEZE    // pause everything (not yet used)
+CUTSCENE_MODE_INPUT_FREEZE   // player input blocked (default: CUTSCENE_MODE_INITIAL)
+CUTSCENE_MODE_GAMEPLAY       // player can still move during cutscene
+```
+
+`cutsceneModeIsInputAllowed()` is checked by `entityUpdate()` before invoking the movement callback — the player cannot walk when in INPUT_FREEZE mode.
+
+### Defining a cutscene
+
+Cutscenes are defined as `static const` arrays in header files under `rpg/cutscene/scene/`. Example (`testcutscene.h`):
+
+```c
+static const cutsceneitem_t MY_CUTSCENE_ITEMS[] = {
+  {
+    .type = CUTSCENE_ITEM_TYPE_TEXT,
+    .text = { .text = "Hello!", .position = RPG_TEXTBOX_POS_BOTTOM }
+  },
+  {
+    .type = CUTSCENE_ITEM_TYPE_WAIT,
+    .wait = FIXED(1.5f)
+  },
+  {
+    .type = CUTSCENE_ITEM_TYPE_CUTSCENE,
+    .cutscene = &ANOTHER_CUTSCENE
+  },
+};
+
+static const cutscene_t MY_CUTSCENE = {
+  .items = MY_CUTSCENE_ITEMS,
+  .itemCount = sizeof(MY_CUTSCENE_ITEMS) / sizeof(cutsceneitem_t)
+};
+```
+
+Attach to an NPC via its interact component:
+```c
+entity->interact.type = ENTITY_INTERACT_CUTSCENE;
+entity->interact.data.cutscene = &MY_CUTSCENE;
+```
+
+---
+
+## Textbox (`src/dusk/rpg/rpgtextbox.h`)
+
+`rpgtextbox_t RPG_TEXTBOX` is the global textbox state:
+
+```c
+typedef struct {
+  rpgtextboxpos_t position;      // RPG_TEXTBOX_POS_TOP or RPG_TEXTBOX_POS_BOTTOM
+  bool_t visible;
+  char_t text[RPG_TEXTBOX_MAX_CHARS];   // 256 chars
+} rpgtextbox_t;
+```
+
+API:
+```c
+rpgTextboxShow(position, text);   // copies text, sets visible = true
+rpgTextboxHide();                 // sets visible = false
+rpgTextboxIsVisible();            // bool
+```
+
+The textbox state is read by `ui/uitextbox.c` during the UI render pass to draw the dialogue box on screen. `rpgtextbox.c` itself does no rendering.

.claude/rpg/entity.md

@@ -0,0 +1,140 @@
+# Entities
+
+Source: `src/dusk/rpg/entity/`
+
+---
+
+## Storage
+
+Entities live in a single fixed global array:
+
+```c
+entity_t ENTITIES[ENTITY_COUNT];   // ENTITY_COUNT = 64
+```
+
+A slot is "empty" when `entity->type == ENTITY_TYPE_NULL`. Never allocate entity memory dynamically — always find a free slot with `entityGetAvailable()`, which returns its index (`0xFF` if none free).
+
+---
+
+## `entity_t` structure
+
+```c
+typedef struct entity_s {
+  uint8_t id;                  // index in ENTITIES[]
+  entitytype_t type;           // ENTITY_TYPE_NULL / PLAYER / NPC
+  entitytypedata_t data;       // union: player_t | npc_t
+
+  entitydir_t direction;       // facing direction (N/S/E/W)
+  fixed_t position[3];         // current sub-tile position (x, y, z)
+  fixed_t lastPosition[3];     // position before last move (for interpolation)
+
+  entityanim_t animation;      // IDLE / TURN / WALK
+  fixed_t animTime;            // countdown timer for current animation
+
+  entityinteract_t interact;   // optional interact component
+} entity_t;
+```
+
+---
+
+## Type system
+
+Entity types are defined in `entitytype.h` using the enum+integer-typedef pattern:
+
+```c
+typedef enum { ENTITY_TYPE_NULL, ENTITY_TYPE_PLAYER, ENTITY_TYPE_NPC, ENTITY_TYPE_COUNT } entitytype_enum_t;
+typedef uint8_t entitytype_t;
+```
+
+Each type has a `entitycallback_t` entry in the `ENTITY_CALLBACKS[ENTITY_TYPE_COUNT]` static table:
+
+```c
+typedef struct {
+  void (*init)(entity_t *entity);
+  void (*movement)(entity_t *entity);
+  bool_t (*interact)(entity_t *player, entity_t *entity);
+} entitycallback_t;
+```
+
+Callbacks not applicable to a type are `NULL`; `entityUpdate()` guards against this before calling.
+
+Type-specific data sits in `entitytypedata_t` (a union of `player_t` and `npc_t`). Currently both are stubs (`void *nothing`).
+
+---
+
+## Direction (`entitydir.h`)
+
+```c
+ENTITY_DIR_NORTH / EAST / SOUTH / WEST
+```
+
+Aliases: `UP = NORTH`, `DOWN = SOUTH`, `LEFT = WEST`, `RIGHT = EAST`.
+
+Utilities:
+- `entityDirGetOpposite(dir)` — returns the opposite direction.
+- `entityDirGetRelative(dir, &relX, &relY)` — fills in the ±1 XY delta for that direction.
+- `assertValidEntityDir(dir, msg)` — assertion macro.
+
+---
+
+## Animation (`entityanim.h`)
+
+```c
+ENTITY_ANIM_IDLE   // standing still
+ENTITY_ANIM_TURN   // turning to a new direction (ENTITY_ANIM_TURN_DURATION = FIXED(0.06))
+ENTITY_ANIM_WALK   // mid-step (ENTITY_ANIM_WALK_DURATION = FIXED(0.1))
+```
+
+`entityAnimUpdate(entity)` decrements `animTime` each frame and transitions back to `IDLE` when it reaches zero.
+
+`entityCanWalk(entity)` / `entityCanTurn(entity)` both return true only when `animation == ENTITY_ANIM_IDLE`.
+
+The renderer interpolates between `lastPosition` and `position` using `animTime / WALK_DURATION` to produce smooth motion even at low frame rates.
+
+---
+
+## Movement
+
+`entityWalk(entity, direction)`:
+
+1. Converts `entity->position` to a `worldpos_t` (truncates fractional part).
+2. Applies the directional delta to get `newPos`.
+3. Checks the current and target tiles for ramp raise/fall logic (see [world.md](world.md)).
+4. Checks `ENTITIES[]` for another entity occupying `newPos` — blocks if found.
+5. On success: copies `position` to `lastPosition`, updates `position` to `newPos` (via `worldPosToFixed`), sets `animation = ENTITY_ANIM_WALK`.
+
+`entityTurn(entity, direction)`: sets `direction` and starts a brief turn animation.
+
+---
+
+## Interaction (`entityinteract.h`)
+
+The `entityinteract_t` component is embedded in every entity. It is optional — set `type = ENTITY_INTERACT_NULL` for non-interactable entities.
+
+```c
+typedef enum {
+  ENTITY_INTERACT_NULL,
+  ENTITY_INTERACT_CUTSCENE,   // plays a cutscene_t *
+  ENTITY_INTERACT_PRINT,      // prints a short message[32]
+} entityinteracttype_t;
+```
+
+`entityInteractWith(player, target)` dispatches:
+1. If the interact component's `type != NULL`, handles it (starts the cutscene or prints the message).
+2. Otherwise falls back to `ENTITY_CALLBACKS[type].interact` if set.
+
+---
+
+## Player (`player.h` / `player.c`)
+
+`playerInit()` is called via `ENTITY_CALLBACKS[ENTITY_TYPE_PLAYER].init`.
+
+`playerInput(entity)` is the movement callback. It reads `PLAYER_INPUT_DIR_MAP[]` — a static table mapping input actions (`INPUT_ACTION_UP/DOWN/LEFT/RIGHT`) to entity directions — and calls `entityWalk` or `entityTurn` accordingly.
+
+The player entity is normally `ENTITIES[0]` but there is no hardcoded assumption about its index beyond being initialized with `ENTITY_TYPE_PLAYER`.
+
+---
+
+## NPC (`npc.h` / `npc.c`)
+
+`npcInit()`, `npcMovement()`, and `npcInteract()` provide the NPC type callbacks. Currently stubs; movement does nothing, interact returns false.

.claude/rpg/index.md

@@ -0,0 +1,18 @@
+# RPG Layer
+
+The RPG layer lives in `src/dusk/rpg/` and is the game-logic tier above the engine. It is initialized and ticked by `engine.c` via `rpgInit` / `rpgUpdate` / `rpgDispose`. The `rpg_t` struct is currently a stub; all meaningful state lives in the subsystems below.
+
+## Contents
+
+- [world.md](world.md) — scene manager, overworld map, chunks, tiles, coordinate system, camera
+- [entity.md](entity.md) — entity pool, types, direction, animation, interaction, player, NPC
+- [cutscene.md](cutscene.md) — cutscene system, item types, mode control, textbox
+- [story.md](story.md) — story flags, items, inventory, backpack, save system
+
+## Scene system
+
+The scene manager (`src/dusk/scene/`) sits above the RPG layer and owns the single active scene. Scenes are identified by `scenetype_t` and registered in `SCENE_TYPES[]` (`scene/scenetype.c`) as `scenecallbacks_t` (init / update / render / dispose).
+
+`scenedata_t` is a union so all scene structs share memory. `sceneSet(type)` defers the transition — the old scene disposes before the new one inits.
+
+Currently the only scene is `SCENE_TYPE_OVERWORLD` → `src/dusk/scene/overworld/sceneoverworld.c`.

.claude/rpg/story.md

@@ -0,0 +1,124 @@
+# Story, Items & Save
+
+---
+
+## Story flags (`src/dusk/rpg/story/`)
+
+Story flags are the primary mechanism for tracking game-world state (quest progress, one-time events, unlocks). Each flag is a `uint8_t` value (`storyflagvalue_t`), so they can hold booleans or small counts.
+
+### Defining flags
+
+Flags are defined in `src/dusk/rpg/story/storyflag.csv`:
+
+```
+id,description,initial
+test,"Test flag for debugging purposes",1
+```
+
+The build tool generates:
+- A `storyflag_t` enum (e.g. `STORY_FLAG_TEST`) in the generated header.
+- `STORY_FLAG_VALUES[]` — the runtime array, pre-populated with the `initial` column values.
+
+To add a flag: add a row to the CSV. The build re-runs the Python tool automatically on the next CMake build.
+
+### Access
+
+```c
+storyflagvalue_t v = storyFlagGet(STORY_FLAG_TEST);   // macro: array read
+storyFlagSet(STORY_FLAG_TEST, 1);                      // function: also marks save dirty
+```
+
+`storyFlagGet` is a macro that directly indexes `STORY_FLAG_VALUES[]` — no function call overhead.
+
+---
+
+## Items (`src/dusk/rpg/item/`)
+
+### Item definitions
+
+Items are defined in `src/dusk/rpg/item/item.csv`. The build tool generates `itemid_t` enum values and item metadata. `itemid_t` is a generated `uint8_t` typedef.
+
+### Inventory (`inventory.h`)
+
+`inventory_t` is a generic container backed by a caller-supplied `inventorystack_t` array:
+
+```c
+typedef struct {
+  itemid_t item;
+  uint8_t quantity;        // max ITEM_STACK_QUANTITY_MAX (255)
+} inventorystack_t;
+
+typedef struct {
+  inventorystack_t *storage;
+  uint8_t storageSize;
+} inventory_t;
+```
+
+Key operations:
+
+```c
+inventoryInit(&inv, storageArray, size);
+inventoryAdd(&inv, ITEM_POTION, 3);
+inventoryRemove(&inv, ITEM_POTION);
+inventorySet(&inv, ITEM_POTION, 10);
+inventoryGetCount(&inv, ITEM_POTION);   // returns 0 if not present
+inventoryItemExists(&inv, ITEM_POTION);
+inventoryIsFull(&inv);
+inventorySort(&inv, INVENTORY_SORT_BY_ID, false);
+```
+
+`inventory_t` itself holds no data — the backing array is always external. This avoids fixed-size struct limits and lets different inventories (backpack, shop, chest) share the same logic.
+
+### Backpack (`backpack.h`)
+
+The player's inventory is the global `BACKPACK` instance:
+
+```c
+extern inventorystack_t BACKPACK_STORAGE[BACKPACK_STORAGE_SIZE_MAX];  // 20 slots
+extern inventory_t BACKPACK;
+
+backpackInit();   // wires BACKPACK_STORAGE into BACKPACK
+```
+
+---
+
+## Save system (`src/dusk/save/`)
+
+The save system is stubbed out — it exists and compiles but is commented out of engine init (`engine.c`). What follows describes the design as implemented.
+
+### Slots
+
+`save_t SAVE` holds `SAVE_FILE_COUNT_MAX` slots:
+
+```c
+typedef struct {
+  savefile_t files[SAVE_FILE_COUNT_MAX];
+  saveplatform_t platform;   // platform-specific state (paths, card handles)
+} save_t;
+```
+
+### Streams
+
+`savestream_t` (`save/savestream.h`) is a raw byte cursor used to serialize/deserialize `savefile_t`. Platform backends in `src/dusk{platform}/save/` implement the actual I/O:
+- Linux: filesystem files in a save directory.
+- GameCube/Wii: memory card via libogc.
+
+### API
+
+```c
+saveInit();
+saveLoad(slot);     // reads platform storage → savefile_t
+saveWrite(slot);    // writes savefile_t → platform storage
+saveDelete(slot);
+saveExists(slot);   // bool
+saveGet(slot);      // returns savefile_t *
+saveDispose();
+```
+
+---
+
+## Locale / i18n (`src/dusk/locale/`)
+
+Translations are loaded from `.po` files in `assets/locale/` (e.g. `en_US.po`). `localemanager.c` manages the active locale and exposes a key→string lookup. `assetlocaleloader.c` parses the PO format via the asset system.
+
+All player-visible strings must go through the locale system rather than being hardcoded. The locale is loaded asynchronously via the asset system so it is available before the first scene renders.

.claude/rpg/world.md

@@ -0,0 +1,114 @@
+# World
+
+Source: `src/dusk/rpg/overworld/`
+
+---
+
+## Coordinate system
+
+Three nested coordinate spaces, each defined in `worldpos.h`:
+
+| Type | Description | Unit |
+|---|---|---|
+| `worldpos_t` | Tile-level absolute position `{x, y, z}` | `worldunit_t` (int16) |
+| `chunkpos_t` | Chunk-grid position `{x, y, z}` | `chunkunit_t` (int16) |
+| `fixed_t[3]` | Smooth sub-tile position used by entities | Q24.8 fixed-point |
+
+One chunk = `CHUNK_WIDTH × CHUNK_HEIGHT × CHUNK_DEPTH` tiles (16 × 16 × 8).
+The loaded world window = `MAP_CHUNK_WIDTH × MAP_CHUNK_HEIGHT × MAP_CHUNK_DEPTH` chunks (5 × 5 × 3).
+
+Conversion helpers (all in `worldpos.c`):
+
+```c
+worldPosToChunkPos(&worldPos, &chunkPos);   // tile → chunk grid
+chunkPosToWorldPos(&chunkPos, &worldPos);   // chunk grid → tile origin
+worldPosToChunkTileIndex(&worldPos);        // tile → index within its chunk
+chunkPosToIndex(&chunkPos);                 // chunk grid → linear index in MAP.chunks[]
+worldPosToFixed(&worldPos, fixedOut);       // tile → entity fixed position
+fixedToWorldPos(fixedPos);                  // entity fixed → tile (truncates frac)
+```
+
+---
+
+## Tiles
+
+Defined in `tile.h` as a plain `tile_t` enum:
+
+```
+TILE_SHAPE_NULL    — empty / unloaded
+TILE_SHAPE_GROUND  — solid flat tile
+TILE_SHAPE_RAMP_*  — directional ramps (N/S/E/W + diagonals NE/NW/SE/SW)
+```
+
+Key predicates:
+- `tileIsWalkable(tile)` — true for GROUND and all ramp shapes.
+- `tileIsRamp(tile)` — true only for ramp shapes.
+
+Entity walk code (`entity.c`) checks both the current tile and the target tile to decide whether the entity steps forward flat, raises one Z level (walking up a ramp), or falls one Z level (stepping onto a downward ramp from above).
+
+---
+
+## Chunks
+
+`chunk_t` (`chunk.h`) holds:
+- `position` — its `chunkpos_t` in the world grid
+- `tiles[CHUNK_TILE_COUNT]` — flat array of `tile_t`, indexed by `chunkGetTileIndex()`
+- `vertices[CHUNK_VERTEX_COUNT]` / `mesh` — pre-baked mesh uploaded to GPU on load
+- `entities[CHUNK_ENTITY_COUNT_MAX]` — indices into `ENTITIES[]` currently in this chunk (sentinel `0xFF`)
+- `testColor` — temporary debug color (checkerboard), will be replaced by real tileset data
+
+Tile layout within a chunk is `z * W*H + y * W + x` (Z-major, row-major in XY).
+
+---
+
+## Map
+
+`map_t MAP` (`map.h`) is the single global map instance.
+
+```c
+chunk_t chunks[MAP_CHUNK_COUNT];         // flat storage — index is NOT world position
+chunk_t *chunkOrder[MAP_CHUNK_COUNT];    // draw-order sorted pointers into chunks[]
+chunkpos_t chunkPosition;               // world-grid origin of the loaded window
+bool_t loaded;
+```
+
+### Load / unload
+
+`mapInit()` allocates chunk meshes and performs the initial load of all chunks in the starting window.
+
+`mapPositionSet(newPos)` shifts the window:
+1. Determines which of the `MAP_CHUNK_COUNT` slots remain within the new window vs. fall outside it.
+2. Calls `mapChunkUnload()` on every chunk that falls outside (nulls its entity slots, zeroes `vertCount`).
+3. Reuses freed slots for newly-in-range chunks; calls `mapChunkLoad()` on each.
+4. Rebuilds `chunkOrder[]` in XYZ order for the new position.
+
+### Chunk load (current stub)
+
+`mapChunkLoad()` currently:
+- Fills all tiles with `TILE_SHAPE_GROUND`
+- Assigns a checkerboard debug color based on chunk XY parity
+- Bakes a flat sprite-batch quad mesh for the z=0 layer and uploads it via `meshFlush()`
+- Skips mesh generation for z > 0 chunks (they're empty)
+
+### Tile lookup
+
+```c
+tile_t mapGetTile(const worldpos_t position);
+```
+
+Converts `position` to its chunk, looks up the chunk in `chunkOrder`, then indexes into `chunk->tiles[]`. Returns `TILE_SHAPE_NULL` for any out-of-bounds position or when the map is not loaded.
+
+---
+
+## Camera
+
+`rpgcamera_t RPG_CAMERA` (`rpgcamera.h`) has two modes:
+
+```c
+RPG_CAMERA_MODE_FREE            // free worldpos; camera.free holds the position
+RPG_CAMERA_MODE_FOLLOW_ENTITY   // tracks ENTITIES[followEntityId]
+```
+
+`rpgCameraGetPosition()` returns the active world tile position in either mode.
+
+The scene renderer (`sceneoverworld.c`) uses `rpgCameraGetPosition()` to build the `glm_lookat` view matrix. When following an entity, it sub-tile interpolates between `entity->lastPosition` and `entity->position` using `entity->animTime / ENTITY_ANIM_WALK_DURATION` to smooth movement.