125 lines
3.7 KiB
Markdown
125 lines
3.7 KiB
Markdown
# 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.
|