# 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.