dusk/.claude/optimization.md

Optimization Guidelines

Dusk must run well on severely resource-constrained hardware. The PSP has 32 MB of RAM and a 333 MHz MIPS CPU. The GameCube has 24 MB of RAM and a 485 MHz PowerPC CPU with no FPU for integer paths. Optimization is not an afterthought -- it is a first-class design constraint.

General principles

• Measure before optimizing. Don't guess where bottlenecks are. Profile on the actual target hardware when possible.
• Data-oriented design. The ECS exists to enable cache-friendly iteration over components. Keep hot data tightly packed (SoA over AoS where it matters).
• Minimize allocations. Dynamic allocation at runtime is expensive and causes fragmentation. Prefer fixed-size pools, arenas, and pre-allocated arrays.
• Avoid per-frame allocations. Anything allocated and freed every tick is a red flag. Use scratch buffers or static pools.
• Avoid recursion on constrained targets -- stack is small.

Memory

Platform	Total RAM	Notes
GameCube	24 MB	16 MB main + 8 MB "Aram" (audio)
Wii	88 MB	24 MB MEM1 + 64 MB MEM2
PSP	32 MB	4 MB reserved for OS
Vita	512 MB	Much more headroom
Linux	Host RAM	Effectively unlimited

Treat the GameCube 16 MB main RAM as the worst-case constraint when designing data structures and budgets.

Always use memoryAllocate / memoryFree -- never malloc / free. The engine allocator tracks usage and can enforce budgets per platform.

Math

• Prefer integer math over floating-point on platforms without an FPU.
• Use fixed-point arithmetic (int32_t with a known scale) for physics and animation on PSP/GameCube where FPU throughput is limited.
• SIMD / VFPU (PSP) and paired-singles (GameCube) are available but require platform-guarded code paths under #ifdef DUSK_PSP etc.
• Avoid double entirely -- use float_t (32-bit) throughout.

Rendering

• Batch draw calls aggressively. Every draw call has overhead on all platforms; consoles are especially sensitive.
• Minimize state changes (texture binds, shader switches, etc.).
• Use display lists (GameCube/Wii) and vertex buffer objects (OpenGL) to offload geometry to GPU memory.
• Keep texture sizes powers of two. Non-PoT textures are unsupported or have penalties on PSP and GameCube.

Asset loading

• Assets are loaded asynchronously via the asset loader system. Do not block the game loop waiting for assets.
• Compress textures to the native format for each platform at build time, not at runtime.
• Stream large assets from the filesystem rather than loading them all at startup.

Platform-specific notes

PSP

• The Media Engine (ME) is a second CPU core -- use it for audio and background decompression, not general logic.
• VFPU gives 4-wide SIMD floats; use it for matrix and vector math.
• Keep the uncached scratchpad (4 KB at 0x00010000) in mind for hot temporary data.

GameCube / Wii

• The GX display list pipeline is the primary rendering path; avoid immediate-mode GX calls in the hot path.
• Texture Compression (CMPR / S3TC equivalent) halves texture memory.
• Wii: prefer MEM1 for GPU-accessed data; MEM2 for CPU-only buffers.

PSP / Vita

• OpenGL ES has a subset of desktop OpenGL. Avoid extensions and features that are not in the ES 1.1 / ES 2.0 core.