Add claude docs

2026-06-16 10:15:59 -05:00
parent 8131bcd4d4
commit ed5c60ac30
32 changed files with 3781 additions and 13 deletions
@@ -0,0 +1,83 @@
+# 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.