dusk/STATUS.md

# Dusk Engine - Status Snapshot

This is a point-in-time inventory of the codebase's maturity, test coverage,
and known gaps. It is not auto-maintained -- re-survey periodically (or
whenever picking a new roadmap milestone) rather than trusting it blindly.
See `ROADMAP.md` for the ordered feature milestones this status feeds into,
and `CLAUDE.md` for coding conventions.

Last surveyed: 2026-07-30, at commit `e61914ba`.

## Core engine (`src/dusk/`)

| Subsystem  | Maturity                          | Notes |
|------------|------------------------------------|-------|
| asset      | Mature, fully wired                | Model loading's "async" path is actually synchronous (`assetmodelloader.h`) -- only real stub found in core. |
| script     | Mature for its current scope       | Registered modules: `modulePlatform`, `moduleComponent`, `moduleEntity`, `moduleScene` only. No typed per-component JS wrappers (all components go through the generic `Component`). No unit tests. |
| entity     | Mature                             | Engine-level prefab lists are empty sentinels; all real prefabs live in `duskrpg`. |
| scene      | Mature                             | Same prefab-delegation pattern as entity. No JSON serialize/deserialize (removed by design). |
| save       | Mature, but undocumented           | Slot-based, yyjson + CRC32, platform stream hooks. Not covered in `CLAUDE.md`, no tests. |
| network    | Connection-state layer only        | HTTP client + connection state machine; no multiplayer/replication protocol (expected -- that's roadmap items 8-17). Not covered in `CLAUDE.md`, has HTTP tests only. |
| physics    | Mature, recently churned           | Recent revert/re-disable of "old ent code" suggests component wiring around physics isn't fully settled. Well tested. |
| animation  | Early/mid-stage                    | Keyframes + easing only, no blend trees or state machines. Terse commit history ("ANIM") suggests still iterating. |
| display    | Most mature/battle-tested          | Backbone of the engine; dominated by platform optimization commits. |
| ui         | Actively churning                  | Widget framework has had features added and ripped out repeatedly (story/battle UI added then removed). Rendering path is the likely root cause of roadmap item 4 (see below). No tests at all. |
| console    | Small, finished for its scope      | Already has the cached-mesh optimization pattern the rest of `ui/` lacks. |
| event      | Clean, small, finished             | Pub/sub, rebuilt to replace the old input system. |
| game       | Intentionally header-only          | Real implementation lives in `duskrpg/game/game.c`. |

### UI rendering performance (roadmap item 4)
Confirmed root-cause candidate: `src/dusk/ui/debug/uiconsole.c` caches a
persistent mesh and only rebuilds on dirty/scroll change. The rest of the
widget framework (`uiframe.c`, `uilabel.c`, buttons, menus, settings
screens) still goes through `spriteBatchBuffer`/`spriteBatchFlush` and
re-uploads vertex data via `meshFlush` every frame, with a full flush
forced on every shader/material change. This is almost certainly what
"tanks framerate" on PSP. Fix direction: extend the console's cached-mesh
pattern to the general widget path (rebuild only on dirty, not every
frame).

## Game layer (`src/duskrpg/`)

Actively maintained, not orphaned (despite an old "remove rpg" commit deep
in history) -- last touched the same day as this survey.

- **cutscene/** -- actively developed, matches `CLAUDE.md`'s documented
  recipe exactly. 16 registered item types.
- **entity/, scene/** -- overworld player/camera/interactable components
  and prefabs, active.
- **item/** -- `item.c`/`inventory.c`/`backpack.c` built via a working
  `item.json` -> `itemdef.h` codegen pipeline. `itemgive.c/h` exist on
  disk but are explicitly excluded from the CMake build pending textbox
  UI restoration -- **that UI (`ui/textbox/`) is already restored**, so
  this looks like an overdue follow-up, not a real blocker.
- **input/** -- headers only, no implementation. Contains the one
  genuine TODO found in the whole `duskrpg` tree: `// TODO: Wiimote, USB
  Keyboard, probably more.`
- **ui/** -- textbox restored and built; `uitestlabel.c/h` is an
  intentional smoke-test scaffold, not dead code.

## Platform layers

| Platform     | Status |
|--------------|--------|
| duskgl / dusksdl2 | Complete, shared by Linux/Knulli/PSP, no gaps found. |
| dusklinux    | Complete, well-trodden. |
| duskpsp      | Complete for current design. The historical dialog/tearing bug (see memory `project_psp_dialog_tearing` etc.) was **not fixed -- the dialog-based connect UI was removed entirely** (commit `d7982599`, "Simplified PSP network") in favor of a silent profile-based connect. Revisit if the dialog UX is still wanted. |
| duskdolphin (GameCube/Wii) | Functional, not a stub -- real GX-based display/mesh/shader/texture. Wii input uses only the GameCube `PAD_*` library; no WPAD/Wiimote support (`inputdolphin.h` has `#error "Wii not implemented"` gated behind macros that are never defined, so currently dormant, not a live build break). `networkdolphin.c` hardcodes a static IP as an explicit temporary workaround for a suspected DHCP-related memory-corruption bug in `if_config()` -- root cause still open. |
| vita         | **Referenced by `scripts/build-vita.sh` and `docker/vita/` but no `cmake/targets/vita.cmake` exists** -- the build target is broken/unfinished at the CMake level. |

### CI coverage gap
`.github/workflows/test.yml` only builds+tests Linux, on PRs to `main`.
`build.yml` builds all other platforms (PSP, Knulli, GameCube, Wii +
ISO variants) but **only on tag push** (release time). Vita and Dolphin
aren't in CI at all. Net effect: regressions on 4+ platforms can land
silently until a release tag is cut.

## Test coverage gaps

Core `src/dusk/` subsystems with **zero** unit tests: `console`,
`engine`, `event`, `game`, `input`, `log`, `save`, `script` (+ all JS
module bindings), `system`, `ui` (entire widget framework).

`src/duskrpg/` has almost no test coverage: `test/item/test_inventory.c`
exists but **`add_subdirectory(item)` is commented out in
`test/CMakeLists.txt`**, so even that one test never runs. `cutscene`,
`entity`, `game`, `input`, `scene`, `ui` under `duskrpg` have no tests at
all.

No stale tests were found referencing deleted systems (old JSON
serialize/deserialize, old event/cutscene modules) -- the test suite is
internally consistent with current code, just incomplete in coverage.

## Build/tooling gaps worth knowing about

- `assetsraw/` -> `assets/` (chunk JSON -> `.dcf`) is a manual/editor-only
  step (`tools.asset.chunk`), not part of the CMake build -- committed
  `.dcf` files can silently drift from their raw source.
- Several Python tool packages exist but aren't wired into any build:
  `tools/color/csv/`, `tools/asset/chunk_json/`, `tools/asset/dmf/`,
  `tools/asset/tiles/`, `tools/input/csv/`. Some may be superseded by
  `tools/color.py`/`tools/item.py`; worth a pass to confirm which are
  live vs leftover.