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.