nova64 0.2.5 → 0.2.7

package/dist/docs/BENCHMARK.md

@@ -0,0 +1,77 @@
+# Nova64 Performance Benchmarks
+
+> Results captured on Apple Silicon (M-series). Run `pnpm bench` to reproduce.
+
+## Running Benchmarks
+
+```bash
+# Full suite (default 1000 iterations)
+pnpm bench
+
+# Individual suites
+pnpm bench:material
+pnpm bench:instancing
+pnpm bench:mesh
+
+# Custom iteration count
+node tests/bench.js --iterations=5000
+
+# Specific suite with custom count
+node tests/bench.js --suite=instancing --iterations=500
+```
+
+## Results (iterations = 1000)
+
+### Material Caching
+
+| Scenario       | avg (ms) | ops/s        |
+| -------------- | -------- | ------------ |
+| Cache **hit**  | 0.0020   | ~490 000     |
+| Cache **miss** | 0.0023   | ~435 000     |
+| **Speedup**    | —        | **1.1–1.2×** |
+
+Material caching provides modest but consistent gains. The bigger win is GPU-side: reusing a `MeshStandardMaterial` eliminates shader recompilation per object type.
+
+### Mesh Creation Throughput
+
+| Primitive        | avg (ms) | ops/s    |
+| ---------------- | -------- | -------- |
+| `createCube`     | 0.0020   | ~510 000 |
+| `createSphere`   | 0.0020   | ~505 000 |
+| `createPlane`    | 0.0022   | ~455 000 |
+| `createCylinder` | 0.0023   | ~435 000 |
+
+All primitives create at ~450–530K/s in Node (headless, mock GPU). In the browser with a real WebGL context, geometry upload is the primary cost — instancing eliminates that per call.
+
+### Instancing vs Individual Meshes
+
+| Approach                                      | avg (ms) | ops/s  | Ratio           |
+| --------------------------------------------- | -------- | ------ | --------------- |
+| 1000 × `createCube` (individual)              | 1.20     | ~830   | 1×              |
+| `createInstancedMesh(1000)` + 1000 transforms | 0.22     | ~4 500 | **5–6× faster** |
+
+**Instancing reduces setup cost 5–6× for 1000-object batches.** More importantly, it collapses 1000 draw calls into 1 — measured GPU speedup in the browser ranges from 10× to 100× depending on object complexity and hardware.
+
+### Per-Frame Transform Update (500 instances)
+
+| Operation                                          | avg (ms) | ops/s   |
+| -------------------------------------------------- | -------- | ------- |
+| 500 × `setInstanceTransform` + `finalizeInstances` | 0.082    | ~12 000 |
+
+At 60 fps you have ~16.6 ms per frame. Updating 500 instance transforms takes **< 0.1 ms** of CPU time, leaving ample headroom for game logic.
+
+### Mesh Cleanup
+
+| Operation     | avg (ms) | ops/s      |
+| ------------- | -------- | ---------- |
+| `destroyMesh` | 0.0005   | ~1 900 000 |
+
+Cleanup is negligible — geometry and material disposal is O(1).
+
+---
+
+## Notes
+
+- **LOD benchmarking** requires a real WebGL context (Three.js `LOD` builds real `BufferGeometry` objects). Run `examples/instancing-demo` in the browser and use the DevTools **Performance** panel to measure LOD overhead.
+- **Frustum culling** benefits are render-thread only and not measurable in Node; in the browser, culling reduces GPU fragment work for off-screen objects.
+- **Material cache** gains compound with scene complexity: a scene with 1000 cubes of 10 distinct colours allocates 10 materials instead of 1000 — 100× fewer GPU shader instances.

package/dist/docs/CHEATSHEET.md

@@ -0,0 +1,255 @@
+# Nova64 Cheatsheet
+
+> One-page reference. For full docs see `NOVA64_API_REFERENCE.md`.
+
+---
+
+## Cart structure
+
+```js
+export function init() {
+  // runs once — create objects, set up lighting
+  setCameraPosition(0, 5, 10);
+  setCameraTarget(0, 0, 0);
+}
+
+export function update(dt) {
+  // runs every frame — move things, read input
+  if (key('KeyW')) playerZ -= 5 * dt;
+}
+
+export function draw() {
+  // runs every frame — 3D renders automatically; use this for 2D HUD only
+  print('Score: ' + score, 8, 8, 0xffffff);
+}
+```
+
+---
+
+## Colors
+
+| Context           | Format                         | Example              |
+| ----------------- | ------------------------------ | -------------------- |
+| 3D (color arg)    | `0xRRGGBB` hex                 | `0xff0000` red       |
+| 2D (print/rect/…) | `0xRRGGBB` or `rgba8(r,g,b,a)` | `rgba8(255,0,0,200)` |
+
+---
+
+## 3D Primitives
+
+```js
+createCube(size, color, [x, y, z], opts); // → mesh handle
+createSphere(radius, color, [x, y, z], opts);
+createPlane(w, h, color, [x, y, z], opts);
+createCylinder(rt, rb, h, color, [x, y, z], opts);
+createCone(radius, h, color, [x, y, z], opts);
+createCapsule(radius, h, color, [x, y, z], opts);
+createTorus(radius, tube, color, [x, y, z], opts);
+```
+
+**`opts`** keys: `material` (`'standard'`|`'metallic'`|`'emissive'`|`'holographic'`), `roughness`, `metalness`, `emissive`, `texture`
+
+---
+
+## Transforms
+
+```js
+setPosition(mesh, x, y, z);
+setRotation(mesh, rx, ry, rz); // radians
+setScale(mesh, sx, sy, sz);
+rotateMesh(mesh, rx, ry, rz); // add to current rotation
+removeMesh(mesh); // also: destroyMesh(mesh)
+```
+
+---
+
+## Camera
+
+```js
+setCameraPosition(x, y, z);
+setCameraTarget(x, y, z);
+setCameraFOV(degrees); // default 75
+```
+
+---
+
+## Lighting & Atmosphere
+
+```js
+setAmbientLight(color, intensity); // e.g. 0x334455, 1.0
+setLightDirection(x, y, z);
+setLightColor(color);
+createPointLight(color, intensity, distance, x, y, z); // → light handle
+setFog(color, near, far);
+clearFog();
+```
+
+---
+
+## Skybox
+
+```js
+createSpaceSkybox({ starCount, starSize, nebulae, nebulaColor });
+createGradientSkybox(topColor, bottomColor); // e.g. 0x87ceeb, 0x228b22
+createSolidSkybox(color); // e.g. 0x000000  cave / indoor
+animateSkybox(dt); // call in update() or:
+enableSkyboxAutoAnimate(speed); // engine calls it for you
+setSkyboxSpeed(multiplier); // 0=pause, -1=reverse
+clearSkybox();
+```
+
+---
+
+## Input
+
+```js
+key(code); // held     e.g. key('KeyW'), key('Space'), key('ArrowLeft')
+keyp(code); // just-pressed (one frame)
+btn(index); // gamepad held  (0=A, 1=B, 2=X, 3=Y, 4=LB, 5=RB, 12=↑…)
+btnp(index); // gamepad just-pressed
+```
+
+---
+
+## 2D Overlay (HUD)
+
+```js
+// Clear / pixels
+cls(color);
+pset(x, y, color);
+
+// Shapes
+rectfill(x, y, w, h, color);
+rect(x, y, w, h, color);
+circfill(x, y, r, color);
+circ(x, y, r, color);
+line(x0, y0, x1, y1, color);
+
+// Text
+print(text, x, y, color);
+printCentered(text, y, color); // horizontally centred
+setFont('small' | 'normal' | 'large');
+
+// HUD helpers
+drawProgressBar(x, y, w, h, t, fgColor, bgColor, borderColor);
+drawHealthBar(x, y, w, h, current, max, opts);
+drawCrosshair(cx, cy, size, color, style); // style: 'cross'|'dot'|'circle'
+drawPanel(x, y, w, h, opts);
+
+// Colours
+rgba8(r, g, b, a); // returns color value (0–255 each channel)
+```
+
+---
+
+## Post-processing
+
+```js
+enableBloom(strength, radius, threshold);
+disableBloom();
+enableFXAA(); // anti-aliasing
+enableVignette(darkness, offset);
+enableChromaticAberration();
+enableGlitch(intensity); // screen glitch (scanlines, RGB split, block artifacts)
+disableGlitch();
+setGlitchIntensity(intensity); // adjust live (0-1)
+
+// One-call visual presets
+enableN64Mode(); // flat shading, no bloom, crisp FXAA
+enablePSXMode(); // bloom + vignette + chromatic aberration
+enableLowPolyMode(); // flat shading, subtle bloom
+disablePresetMode(); // restore defaults
+```
+
+---
+
+## Audio
+
+```js
+sfx(preset)          // 0/1/2 or named: 'jump','coin','explosion','laser',
+                     //   'hit','death','select','confirm','error','blip','powerup','land'
+sfx({ wave, freq, dur, vol, sweep })   // custom: wave = 'sine'|'square'|'sawtooth'|'noise'
+setVolume(0..1)      // master volume
+```
+
+---
+
+## Physics
+
+```js
+createBody(x, y, w, h, opts); // opts: vx,vy,restitution,friction
+destroyBody(body);
+stepPhysics(dt); // call in update(dt)
+setGravity(px_per_s2); // default 500
+setCollisionMap(fn); // fn(tx,ty) → true if solid
+// also: setTileSolidFn(fn)
+```
+
+---
+
+## Storage
+
+```js
+saveData(key, value); // persists to localStorage (JSON)
+loadData(key, fallback); // returns parsed value or fallback
+deleteData(key);
+// also: saveJSON / loadJSON as aliases
+```
+
+---
+
+## 5-Minute Patterns
+
+**Spinning cube**
+
+```js
+let cube;
+export function init() {
+  cube = createCube(1, 0x00aaff, [0, 0, -5]);
+}
+export function update(dt) {
+  rotateMesh(cube, 0, dt, 0);
+}
+```
+
+**WASD player**
+
+```js
+const p = { x: 0, z: 0 };
+export function update(dt) {
+  if (key('KeyW')) p.z -= 5 * dt;
+  if (key('KeyS')) p.z += 5 * dt;
+  if (key('KeyA')) p.x -= 5 * dt;
+  if (key('KeyD')) p.x += 5 * dt;
+  setPosition(mesh, p.x, 0, p.z);
+  setCameraPosition(p.x, 4, p.z + 8);
+  setCameraTarget(p.x, 0, p.z);
+}
+```
+
+**Save high score**
+
+```js
+let best = loadData('best', 0);
+if (score > best) {
+  best = score;
+  saveData('best', best);
+}
+```
+
+**Space skybox with auto-rotate**
+
+```js
+export function init() {
+  createSpaceSkybox({ starCount: 1500 });
+  enableSkyboxAutoAnimate(0.5);
+}
+```
+
+**Sunset gradient sky**
+
+```js
+export function init() {
+  createGradientSkybox(0x1a6aa8, 0xf4a460);
+}
+```