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-31, at commit 8f8fa8f8.

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/moduleComponentList (typed Position/Physics/Renderable wrappers), moduleEntity, moduleScene (with Scene.set() module lifecycle), moduleMesh, moduleTime, moduleRequire (CommonJS-style require()/module.exports). Entry point is scripts/init.js, which does require('./overworldscene.js') + Scene.set(). Has unit tests (test/script/).
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, perf pass done	Widget framework has had features added and ripped out repeatedly (story/battle UI added then removed). No JS bindings yet (from-scratch surface if that's picked up). Sprite-cache pass landed for slider/tab/frame/textbox (see roadmap item 4 below); still no scripted pointer/hit-testing. Has unit tests for the new caching logic (test/ui/), but nothing exercises actual draw calls -- see below.
console	Small, finished for its scope	Fixed-size cached mesh (no more alloc/free churn), same pattern the rest of ui/ now follows.
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)

First pass landed 2026-07-31: uislider/uitab now cache their non-text quads (track/fill/markers, tab background) relative to origin and only rebuild on state change, translating into position at draw time. uiframe.c grew uiFrameDrawCached(), which skips rebuilding its 9-slice sprites when x/y/width/height match the last call; wired into the confirm dialog, settings panel, and textbox (each owns its own uiframecache_t). uitextbox no longer does one spriteBatchBuffer call per visible glyph -- it builds a per-page glyph cache once and slices a prefix by scroll each frame. uiconsole dropped its alloc/free vertex buffer for a fixed 512-glyph array. uifps skips its label rebuild when the formatted FPS string hasn't changed.

Still open: every widget still issues its own spriteBatchBuffer call per material/color, so a row of alternating highlighted/plain widgets still forces a GPU flush per widget (color is applied via material, not per-vertex) -- that's the next real win if PSP framerate is still an issue. No scripted pointer/hit-testing exists either; input is still 100% gamepad/keyboard directional-focus (ui/focus/).

Test coverage caveat: test/ui/ and test/display/test_spritebatchsprite.c cover the new caching logic (geometry math, exercised by constructing widget structs directly) but cannot exercise uiXxxDraw()/uiFrameDraw() themselves -- those need FONT_DEFAULT/UI_FRAME's GL texture, which needs a live GL context this test binary doesn't have (confirmed: calling fontInitDefault() in a test asserts in texturegl.c). This is true of the whole rendering layer, not something newly introduced -- there's no GL-backed test harness anywhere in the repo yet.

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.