dusk/ROADMAP.md

Dusk Roadmap

Tracking upcoming milestones for the engine. See PSP_OPTIMIZATION_PLAN.md for a memory/CPU optimization survey specifically targeting the PSP build (milestone 4 below is its Priority 3).

Upcoming milestones

1. Add a very basic physics engine, moving away from the current tile-based movement.
2. Give entities full freedom of movement (no longer locked to tile grid positions).
3. Update entity interaction, triggers, chunk management, and other systems that currently assume tile-based positioning so they work with the new 3D positioning/movement code.
4. Investigate and fix poor UI rendering performance. First pass done (2026-07-31): slider/tab/frame/textbox now cache their sprite geometry instead of rebuilding it every frame, and the console's vertex buffer is fixed-size instead of alloc/free churn (see STATUS.md's "UI rendering performance" note for detail). Still open: per-widget material/color changes still force a sprite-batch flush each time (color is per-material, not per-vertex), so a row of alternating highlighted widgets still costs one draw call per widget.
5. Create UI elements for displaying status indicators, e.g. network connection state and save-in-progress.
6. Fully test saving end-to-end on all supported platforms.
7. Remove the tile system from chunks in favor of meshes, with dynamic hitboxes per chunk loaded in from the chunk file data.
8. Create UI elements for network status: a connecting modal, an error state, and a connected flag. Retire the test HTTP request once these are in place.
9. Build the socket server and client implementation, including handlers for the different packet types.
10. Add a dedicated multiplayer entity type, clientplayer, alongside the existing npc and player types. Limit to 16 (defined constant, see SERVER_CLIENT_COUNT_MAX/CLIENT_COUNT_MAX in src/dusk/network/socket/) for now.
11. Send and receive clientplayer position over the network.
12. Create a UI menu for creating a server and joining a server. For now, join IPs are hard-coded (testing against a fixed IP of 10.0.0.94).
13. Create "handshake" packets. For now, just send the username, enforced to be under 10 characters long.
14. Server tracks all players' positions and broadcasts them to all connected clients.
15. Server sends disconnect packets for users who leave.
16. Server assigns each client a UUID; all clients know every other client's UUID (used to reference them across position updates, disconnect packets, etc).
17. Server notifies all clients (by UUID) when a user joins, leaves, or is disconnected, so clients can spawn or remove the corresponding clientplayer entity in the world.

Infrastructure / debt backlog

Found during a full-codebase inventory pass (2026-07-30, see STATUS.md for the full survey). These aren't new feature milestones so much as loose ends worth closing, roughly in order of how cheap/safe they are to fix:

1. Re-enable test/item (currently commented out in test/CMakeLists.txt) -- confirm it still passes and turn it back on.
2. Restore itemgive.c/h in src/duskrpg/item/CMakeLists.txt -- the textbox UI dependency it was waiting on (ui/textbox/) is already back.
3. Decide the fate of the vita target: scripts/build-vita.sh and docker/vita/ reference -DDUSK_TARGET_SYSTEM=vita, but no cmake/targets/vita.cmake exists, so the build is currently broken. Either implement it or remove the dangling scripts/Dockerfile.
4. Per-PR CI build coverage for non-Linux targets: first pass added 2026-07-31 as run-tests-gamecube-dolphin/run-tests-wii-dolphin (build the ISO, boot it in Dolphin under Xvfb) and run-tests-psp-ppsspp (build the EBOOT, boot it in PPSSPPHeadless) in .github/workflows/test.yml, plus matching scripts/test-*-dolphin.sh/scripts/test-psp-ppsspp.sh (+ -docker variants). Marked continue-on-error: true since none of these have actually been exercised on a real runner yet -- verify they pass before relying on them, and drop the flag once they do. Knulli still has no per-PR coverage at all.
5. Milestone 4 above (poor UI rendering performance) has a first pass in (2026-07-31, see STATUS.md) -- remaining concrete lead: sprite batch flushes are keyed on shader+material (including tint color), so per-widget color changes (e.g. focus highlight) still force a flush per widget; moving tint to per-vertex color would let a whole row of widgets batch into one draw call regardless of highlight state.
6. Revisit the GameCube/Wii networking static-IP workaround in networkdolphin.c -- it's standing in for an unresolved suspected memory-corruption bug in if_config()'s DHCP path.
7. Decide whether the PSP dialog-based network connect UI needs to come back -- it was removed entirely (not fixed) when the original dialog-tearing bug proved hard to resolve.
8. Backfill unit tests for the biggest untested surfaces: ui/ (whole widget framework), save/, script/ (JerryScript bindings), event/.

Principles

• Never trust the network implicitly. Neither side (server or client) should assume the other's packets are well-formed or benign -- validate all incoming packet data defensively, since either side may send garbage or malicious data. Use errorret_t / errorThrow() for these runtime checks, not assert macros -- asserts are debug-only and won't guard release builds against malformed or malicious packet data.