dusk/PSP_OPTIMIZATION_PLAN.md

PSP Optimization Plan

A survey of concrete memory and CPU (especially floating-point) optimization opportunities for the PSP target, done 2026-07-31 on branch ac2 at commit e61914ba + this session's scripting work. Point-in-time findings, not a substitute for reading the referenced source before acting on it.

Why this exists

The PSP (Allegrex MIPS CPU, 222-333MHz, single core, 32-64MB main RAM, 2MB eDRAM, 16KB I-cache / 16KB D-cache, no virtual memory or memory protection) is the tightest-constrained target this engine ships to. Two rules guide everything below, both already correctly applied in one place in this codebase (entityposition_t caching its transform matrices instead of recomputing them from position/rotation/scale every read — see "Already correct" below):

• Memory is finite and cannot be compacted. No VM means a fragmented heap after a few minutes of play can fail an allocation even with "enough" total free bytes. Prefer static/pool allocation over malloc/free churn; prefer trading memory for CPU only when the memory cost is bounded and paid once.
• CPU is finite and floating-point math is not free, especially trig/sqrt on the plain scalar FPU. Prefer caching a computed result behind a dirty flag over recomputing it unconditionally; prefer avoiding a sqrt via squared-distance comparison wherever only a yes/no or ordering result is needed.

Priority 1 — Entity/component memory: a union tax paid on every slot, times 4 scenes

The single biggest finding. entitymanager_t (src/dusk/entity/entitymanager.h:11-15) is a flat, statically-sized struct:

typedef struct entitymanager_t {
  entity_t entities[ENTITY_COUNT_MAX];                              // 64
  component_t components[ENTITY_COUNT_MAX * ENTITY_COMPONENT_COUNT_MAX]; // 64*16 = 1024
  componentid_t entitiesWithComponent[COMPONENT_TYPE_COUNT * ENTITY_COUNT_MAX];
} entitymanager_t;

component_t (src/dusk/entity/component.h:69-72) holds a tagged union (componentdata_t) sized to its largest variant. That variant is entityrenderable_t's spritebatch payload (entityrenderable.h:25-66): spritebatchsprite_t sprites[64] at 40 bytes each (vec3 min + vec3 max + vec2 uvMin + vec2 uvMax) = 2560 bytes, versus ~28-300 bytes for every other component type (camera, physics, animation, position, trigger).

Because the union is embedded by value in a flat array — not behind a pointer, not sparse — every one of the 1024 component slots in every entity manager costs ~2580 bytes, whether it holds a 28-byte camera or nothing at all. 1024 * 2580 ≈ 2.52MB per entitymanager_t, confirmed by the engine's own startup log every run: Entity manager size: 2684992 bytes (2622.06 KB).

scene_t (src/dusk/scene/scene.h:14-18) embeds entitymanager_t by value too, and SCENE_COUNT_MAX = 4 (scene/scenebase.h:11) with SCENE_MANAGER declared as a plain global (scene/scene.c:20) — so this ~2.52MB exists as static BSS from process start for all 4 scene slots, used or not. Total: ~10.1MB reserved permanently for entity storage alone — 16-31% of PSP main RAM — before a single texture, mesh, or audio asset is loaded.

Options to fix (roughly increasing effort/risk):

1. Pull entityrenderablespritebatch_t out of the component union entirely — store spritebatch entities via a pointer/handle into a separate, smaller fixed pool sized to how many spritebatch-renderable entities actually coexist (almost certainly far fewer than 64 per entity, and far fewer entities need spritebatch at all vs. mesh/material rendering). This alone would shrink the union's dominant variant from ~2560 bytes to whatever the next-largest variant is (~300 bytes, entitytrigger_t) — an ~88% reduction, dropping the ~10.1MB down to roughly ~1.2MB.
2. Reduce SCENE_COUNT_MAX from 4 if 4 concurrent scenes were never a deliberate requirement (check with the project owner — this may just be a round-number default nobody revisited), or make scene storage pointer-based/lazily allocated so unused scene slots cost ~0 instead of a full entitymanager_t.
3. Reduce ENTITY_COMPONENT_COUNT_MAX (16) if entities realistically use far fewer distinct component types simultaneously — check actual usage across entityprefablist.h/gameprefablist.h prefabs.

Do (1) first — it's the highest-leverage, most contained change (touches entityrenderable.h's data layout and its render/dispose paths, not the general entity/component system), and re-measure via the same startup log line before deciding whether (2)/(3) are still worth doing.

Priority 2 — VFPU is completely unused; all vec/mat math is scalar

The PSP's Allegrex CPU has a VFPU (vector floating-point unit) capable of fast SIMD-style 4-wide float ops and hardware-accelerated matrix operations, exposed by pspsdk's pspvfpu/GU "Geometry Utility" (gum_*) helpers. This engine links pspvfpu (cmake/targets/psp.cmake) but never calls into it — confirmed via a zero-hit grep for vfpu|pspmath|gum_|vcst|gu_matrix across src/duskpsp/ and src/duskgl/.

All vector/matrix math instead goes through cglm (glm_vec3_*, glm_mat4_*), which auto-detects SIMD only for x86 (CGLM_SSE2/AVX) or ARM (CGLM_NEON) — neither applies to MIPS, and no CGLM_* macros are set anywhere in this repo (confirmed zero hits). Every glm_mat4_mul, every position/rotation rebuild, every physics vector op runs on the plain scalar MIPS FPU with the VFPU sitting idle.

This is the single largest available CPU win identified in this survey — larger than any specific hot-path fix below, because it's a multiplier on all of them. Concretely: route entityposition.c's matrix rebuild/multiply path and physicsworld.c's per-body vector math through pspvfpu/gum_* on the PSP build specifically (behind #ifdef DUSK_PSP, matching the project's existing platform-guard convention), while keeping cglm as the portable fallback for Linux/Knulli/GameCube/Wii. This is a genuinely large effort (new platform-specific math backend, careful correctness verification since VFPU has its own quirks around pipelining/hazards) — scope it as its own project, not a quick pass.

Priority 3 — UI/spritebatch rebuilds and redraws every vertex, every frame

Already flagged in STATUS.md/ROADMAP.md (item 4/5) as a known open issue; this session's research adds concrete numbers. meshvertex_t (display/mesh/meshvertex.h:14-17) is { float uv[2]; float pos[3]; } = 20 bytes/vertex, no packing. SPRITEBATCH_SPRITES_MAX = 512, SPRITEBATCH_FLUSH_COUNT = 16 → 32 sprites/flush = 192 vertices = 3,840 bytes rebuilt and redrawn per flush, with a flush forced on every shader/material change (spritebatch.c:38-50) and used unconditionally by every widget except uiconsole.c (uitab.c:56, uislider.c:183/199/231, final flush in ui.c:51). A UI screen with ~50-100 sprites and 2-3 material changes costs an estimated 8-15KB of vertex rebuild + GU submission every single frame, regardless of whether the UI changed since the last frame.

Confirmed on the PSP legacy-GL path specifically: there's no GPU buffer re-upload cost (meshFlushGL is a literal no-op comment: "we use the glClientState stuff" — meshgl.c:91-93; meshDrawGL just points glVertexPointer at the CPU-side array each call), so the real cost is (a) the CPU-side per-sprite vertex rewrite every frame and (b) GU re-transforming the full vertex stream from RAM on every draw with no skip for unchanged geometry.

Fix direction (already captured in ROADMAP.md's debt backlog item 5): extend uiconsole.c's cached-mesh, dirty-flag-gated rebuild pattern to the rest of the widget tree. This plan adds one refinement: also consider packing meshvertex_t down (next item) since it multiplies this cost.

Priority 4 — All-float vertex format wastes bandwidth and T&L cost

meshvertex_t uses two float fields (20 bytes) for every mesh and sprite vertex, mesh-wide, with no normal or per-vertex color (color is already handled at the material level, so that part is already optimal). GU natively supports fixed-point 16-bit positions/UVs (GU_VERTEX_16BIT/GU_TEXTURE_16BIT), which would roughly halve per-vertex size and the corresponding vertex-fetch/transform cost, at the cost of position precision (fine for UI/sprite work and most world geometry at this engine's scale; worth checking against the largest world coordinates actually used before committing). Pair with Priority 3 so the packing benefit compounds with the dirty-tracking benefit instead of just reducing the cost of a rebuild that still happens every frame.

Priority 5 — Running gameplay logic in JerryScript has a real per-frame cost on PSP

This is new since last session's work, not a pre-existing issue: assets/ scripts/overworldscene.js's update() is now called every frame via scriptManagerCallGlobal("update") (wired into engine.c's engineUpdate()), replacing what used to be a direct cosf/sinf C callback (entityUpdateAdd). Per call, scriptManagerCallGlobal (scriptmanager.c:91-144) does: a global-object property lookup (key is cached, but the jerry_object_get dispatch still runs), full JS interpreter call dispatch (frame setup, argument marshaling) for what's a two-line function, and an unconditional jerry_value_is_promise check every call even though update() is synchronous. Inside, Math.cos/ Math.sin run as JS builtin calls rather than direct libm calls.

Additionally: this project's JerryScript fork is already patched to use 32-bit float internally (JERRY_NUMBER_TYPE_FLOAT64=0, Findjerryscript.cmake) — a deliberate, already-correct optimization for this exact concern — but the public engine API (jerry_value_as_number()) still returns double, so every native↔JS boundary crossing (every moduleBaseArgFloat, every moduleBaseVec3ToObject) still pays a float→double→float round trip. Also note JERRY_MATH is off, so Math.sin/cos fall through to whatever generic libm the platform provides rather than JerryScript's own fdlibm implementation — worth checking whether turning it on changes anything measurable on PSP.

This is one update() call for one scene-level script today — cheap in absolute terms. It becomes a real problem only if the pattern scales: giving many individual entities their own per-frame JS update callback would multiply all of the above per entity. Recommendation: keep high-frequency, hot per-entity logic (movement, camera math, physics response) in native C update callbacks (entityUpdateAdd, the existing mechanism), and reserve JS for one-time setup, infrequent/event-driven logic, and coarse-grained per-scene orchestration — which is exactly what require() and the typed component wrappers built this session are suited for, not a per-entity-per-frame hot path. This is a design guideline to apply going forward, not a regression to fix in the current overworldscene.js (one scene-level update() call per frame is fine).

Priority 6 — No pooling/arena allocator; plain malloc/free everywhere

memoryAllocate/memoryFree (util/memory.c) are direct malloc/free passthroughs (memoryAlign→memalign, memoryReallocate/memoryResize→ realloc), with the only extra behavior being a global allocation-count tracker used solely for test leak detection. No pool, arena, free-list, or size-class allocator exists anywhere.

This survey found no rogue per-frame heap allocations in the hot paths checked (render dispatch in entityrenderable.c, all of physics/*.c) — so this is not an active bug today. But it's a structural risk for a no-VM platform over a long play session: any future code that does frequent small alloc/free (dynamic lists, string building, temp buffers) will fragment the 32-64MB heap with no OS-level recovery mechanism. Recommendation: before adding any new subsystem that allocates/frees frequently at runtime (not just at load time), default to a fixed-size pool or arena for it, following the same "static, bounded" philosophy already used for ENTITY_COUNT_MAX/ SCENE_COUNT_MAX/ASSET_ENTRY_COUNT_MAX elsewhere in the engine, rather than reaching for memoryAllocate per-instance.

Already correct — don't touch without new evidence

• entityposition_t's matrix caching (the pattern the project owner called out as the reason for writing this plan). Verified: a full "dirty" recompute chain (decompose + rebuild local + rebuild world) is ~10 trig calls (asinf/cosf/atan2f) plus at most one 4x4 matrix multiply, and entityPositionEnsurePRS/EnsureLocal/EnsureWorld (entityposition.c:596-669) all early-return on a flag check, only doing that work when something actually changed. The cache is correct and clearly worth its ~128-byte-per-entity matrix storage cost.
• Physics narrow-phase sqrt avoidance. All three sqrtf call sites in physicstest.c/physicsshapemesh.c already sit behind a squared-distance early-reject and only compute the real (linear) distance once, when actually needed for penetration depth — no further "use squared distance instead" opportunity was found here.
• No allocations in the render/physics hot loop (Priority 6) — this is good and worth preserving as new code is added to those files.
• Asset decompression already runs off the main thread. Assets are DEFLATE-compressed (not stored) in dusk.dsk, so loading pays a real CPU cost for decompression — but every *LoaderAsync function (asset/loader/*/*.c) runs via ASSET.loadThread (assertNotMainThread in asset.c:365), so this cost is already kept off the main thread. Low priority to change; if load-time CPU cost becomes a measured problem later, revisit stored-vs-compressed as a build-time flag rather than assuming compression is free.

Suggested approach

1. Measure before changing. None of the above have been profiled on real PSP hardware in this pass — this is a source-level survey, not a profile. Before investing in Priority 1 or 2 especially, confirm with an actual PSP build/run (or at minimum the existing "Entity manager size" startup log plus a frame-time counter) that these are the real bottlenecks, not just the largest numbers on paper.
2. Priority 1 first — it's the most contained (one component's data layout), has the clearest before/after metric (the startup log line), and doesn't require new platform-specific code.
3. Priority 3 next (extend the console's dirty-tracking pattern to the rest of the UI) — already scoped in ROADMAP.md, no new design needed, just implementation.
4. Priority 2 (VFPU) as a dedicated project, not a quick pass — it's the largest potential win but touches core math plumbing and needs careful correctness verification on real hardware.
5. Treat Priority 5 as a standing design guideline for all future scripting work, not a one-time fix.