@opengamehq/cli 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/AGENTS.md +238 -0
  2. package/CHANGELOG.md +22 -0
  3. package/README.md +129 -2
  4. package/dist/cli.mjs +1432 -0
  5. package/dist/opengame-global.js +49 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +20 -0
  8. package/dist/runtime-builder.mjs +800 -0
  9. package/dist/runtime-catalog.json +1 -0
  10. package/dist/runtime-catalog.sha256 +1 -0
  11. package/dist/runtime-shells/runtime-shell.html +4 -0
  12. package/dist/runtime-shells/runtime-shell.js +91 -0
  13. package/dist/safe-fs.py +242 -0
  14. package/dist/skills/manifest.json +516 -0
  15. package/dist/skills/opengame-accessibility/SKILL.md +90 -0
  16. package/dist/skills/opengame-api/SKILL.md +85 -0
  17. package/dist/skills/opengame-assets/SKILL.md +124 -0
  18. package/dist/skills/opengame-assets/references/pipeline.md +97 -0
  19. package/dist/skills/opengame-audio/SKILL.md +154 -0
  20. package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
  21. package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
  22. package/dist/skills/opengame-capture/SKILL.md +108 -0
  23. package/dist/skills/opengame-capture/references/pipeline.md +82 -0
  24. package/dist/skills/opengame-capture/references/threejs.md +145 -0
  25. package/dist/skills/opengame-characters/SKILL.md +129 -0
  26. package/dist/skills/opengame-characters/references/integration.md +144 -0
  27. package/dist/skills/opengame-characters/references/player-og.md +160 -0
  28. package/dist/skills/opengame-cli/SKILL.md +118 -0
  29. package/dist/skills/opengame-deploy/SKILL.md +207 -0
  30. package/dist/skills/opengame-deploy/references/json-events.md +62 -0
  31. package/dist/skills/opengame-deploy/references/manifest.md +83 -0
  32. package/dist/skills/opengame-deploy/references/packaging.md +117 -0
  33. package/dist/skills/opengame-depth/SKILL.md +130 -0
  34. package/dist/skills/opengame-enemies/SKILL.md +103 -0
  35. package/dist/skills/opengame-enemies/references/threejs.md +134 -0
  36. package/dist/skills/opengame-front-end/SKILL.md +143 -0
  37. package/dist/skills/opengame-front-end/references/launch.md +50 -0
  38. package/dist/skills/opengame-front-end/references/menus.md +47 -0
  39. package/dist/skills/opengame-game-feel/SKILL.md +137 -0
  40. package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
  41. package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
  42. package/dist/skills/opengame-jam/SKILL.md +103 -0
  43. package/dist/skills/opengame-lighting/SKILL.md +94 -0
  44. package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
  45. package/dist/skills/opengame-loading/SKILL.md +99 -0
  46. package/dist/skills/opengame-loading/references/threejs.md +116 -0
  47. package/dist/skills/opengame-look/SKILL.md +114 -0
  48. package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
  49. package/dist/skills/opengame-mobile/SKILL.md +90 -0
  50. package/dist/skills/opengame-performance/SKILL.md +140 -0
  51. package/dist/skills/opengame-performance/references/measuring.md +72 -0
  52. package/dist/skills/opengame-production/SKILL.md +131 -0
  53. package/dist/skills/opengame-production/references/templates.md +63 -0
  54. package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
  55. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
  56. package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
  57. package/dist/skills/opengame-router/SKILL.md +51 -0
  58. package/dist/skills/opengame-router/references/process.md +38 -0
  59. package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
  60. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
  61. package/dist/skills/opengame-sdk/SKILL.md +270 -0
  62. package/dist/skills/opengame-sdk/references/engines.md +93 -0
  63. package/dist/skills/opengame-sdk/references/frame.md +107 -0
  64. package/dist/skills/opengame-sdk/references/identity.md +112 -0
  65. package/dist/skills/opengame-sdk/references/leaderboards.md +105 -0
  66. package/dist/skills/opengame-sdk/references/radio.md +71 -0
  67. package/dist/skills/opengame-stability/SKILL.md +84 -0
  68. package/dist/skills/opengame-verification/SKILL.md +136 -0
  69. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  70. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  71. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  72. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  73. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  74. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  75. package/package.json +38 -4
@@ -0,0 +1,145 @@
1
+ # Capture in three.js
2
+
3
+ Each section matches a rule in `SKILL.md`. API names were checked against three.js r185;
4
+ check the version the game pins before copying.
5
+
6
+ ## Drive the clock yourself
7
+
8
+ Every system takes `dt` from one function. Nothing reads `performance.now()`, `Date.now()`
9
+ or a `THREE.Clock` on its own.
10
+
11
+ ```js
12
+ const sim = { time: 0, scale: 1 }
13
+
14
+ function step(dt) {
15
+ const scaled = dt * sim.scale
16
+ sim.time += scaled
17
+ physics.step(scaled) // fixed internal step, sub-stepped, see below
18
+ mixer.update(scaled) // AnimationMixer takes the delta you give it
19
+ effects.uniforms.uTime.value = sim.time
20
+ cameraRig.update(scaled) // smoothing reads the same delta
21
+ audioDirector.update(sim.time) // cues are logged in simulation time
22
+ }
23
+
24
+ if (!captureMode) {
25
+ const timer = new THREE.Timer() // core since recent releases; older ones ship three/addons/misc/Timer.js
26
+ renderer.setAnimationLoop((now) => { timer.update(now); step(timer.getDelta()); renderer.render(scene, camera) })
27
+ } else {
28
+ window.__capture = {
29
+ ready, // the promise from "Ready means resident"
30
+ async frame(dt) { step(dt); renderer.render(scene, camera); return readFrame() },
31
+ }
32
+ }
33
+ ```
34
+
35
+ - Slow motion is a smaller `dt` passed to `frame`, so a 1/240 step at 60 output fps is
36
+ 0.25x. Keep `sim.scale` for gameplay effects such as hitstop, and turn those off with the
37
+ cinematic flag.
38
+ - Physics: Rapier's `world.timestep` and `world.step()`, or cannon-es `world.step(fixed, dt,
39
+ maxSubSteps)`. Interpolate body transforms for render so a step smaller than the physics
40
+ step does not hold a pose and then jump.
41
+ - Shaders: feed effects a time uniform you own. TSL's built-in `time` and `deltaTime` nodes
42
+ follow the renderer's own frame timing, not your step.
43
+ - Seeds: replace `Math.random()` in game systems with a seeded generator per system,
44
+ derived from one global seed. `THREE.MathUtils.seededRandom(seed)` exists for quick use;
45
+ a small PRNG per system (mulberry32 or similar) keeps systems from consuming each other's
46
+ numbers.
47
+ - Code you do not own: replace `performance.now`, `Date.now` and `requestAnimationFrame`
48
+ with Playwright's `page.addInitScript` before the game loads, and prepend the same shim
49
+ to every worker script. OC found that a page-level fake clock froze timers and that
50
+ virtual time did not reach workers, so workers need their own shim.
51
+
52
+ ## Cuts and temporal effects
53
+
54
+ - `TAARenderPass` (`three/addons/postprocessing/TAARenderPass.js`): set
55
+ `accumulateIndex = -1` on a cut to restart accumulation.
56
+ - Other temporal passes (TRAA, SSR or SSAO history, temporal upscalers): clear the history
57
+ render target on a cut. Read the pass's source to find it; there is no shared reset call.
58
+ - Velocity-based motion blur: on a cut, copy the current camera and object matrices into
59
+ the previous-frame matrices so velocity is zero for that frame. Tie the shutter to the
60
+ step: OC set blur strength to 60 times the step in seconds.
61
+ - Auto exposure: set the adapted luminance straight to the new shot's target.
62
+ - Clean feed: put world markers on their own layer and hide them with
63
+ `camera.layers.disable(n)`. Give each DOM HUD element a `data-hud` name and hide by mask
64
+ with a class on the root.
65
+
66
+ ## Ready
67
+
68
+ ```js
69
+ const ready = (async () => {
70
+ await assetsLoaded // your loader's promise, or DefaultLoadingManager.onLoad
71
+ for (const texture of allTextures) renderer.initTexture(texture) // upload before the first frame
72
+ await renderer.compileAsync(scene, camera) // pipelines and programs
73
+ await soundBanksDecoded
74
+ quality.lock() // no dynamic resolution while capturing
75
+ return { build: BUILD_ID }
76
+ })()
77
+ ```
78
+
79
+ With `WebGPURenderer`, `await renderer.init()` before any of this.
80
+
81
+ ## Probe
82
+
83
+ After `scene.updateMatrixWorld()`, `bone.getWorldPosition(v)` gives the joint the skinning
84
+ used this frame. `v.clone().project(camera)` gives normalised device coordinates; map to
85
+ pixels with the drawing buffer size. Draw those points over the captured frame on day one.
86
+
87
+ ## Reading frames
88
+
89
+ - WebGL: `new THREE.WebGLRenderer({ preserveDrawingBuffer: true })` keeps the last frame
90
+ readable after the browser composites. It is set at context creation and can cost
91
+ performance, so choose it at boot from the capture flag. Without it, read in the same task
92
+ right after `renderer.render()`.
93
+ - WebGPU: `await renderer.readRenderTargetPixelsAsync(target, x, y, w, h)` from a render
94
+ target, or build a `VideoFrame` from the canvas right after rendering. If you configure the
95
+ canvas context yourself, add `GPUTextureUsage.COPY_SRC` to its usage; OC read its swapchain
96
+ with `copyTextureToBuffer` and `mapAsync` in 30.4 ms at 4K.
97
+ - `canvas.captureStream(0)` with `track.requestFrame()` after each render feeds a
98
+ `MediaRecorder`. Its timestamps are wall time, so use it for real-time previews only.
99
+ - Refuse a software rasteriser. WebGL: read `UNMASKED_RENDERER_WEBGL` through
100
+ `WEBGL_debug_renderer_info` and stop on SwiftShader or llvmpipe. WebGPU: inspect
101
+ `adapter.info`, including `isFallbackAdapter` where the browser reports it.
102
+ - Headless runs: Playwright with `viewport: { width: 3840, height: 2160 }` and
103
+ `deviceScaleFactor: 1` for native 4K.
104
+
105
+ ## Encoding with WebCodecs
106
+
107
+ ```js
108
+ const config = {
109
+ codec: 'hvc1.1.6.L153.B0', width: 3840, height: 2160, // HEVC Main, level 5.1
110
+ bitrate: 300_000_000, framerate: 60, hardwareAcceleration: 'prefer-hardware',
111
+ }
112
+ if (!(await VideoEncoder.isConfigSupported(config)).supported) throw new Error('encoder config not supported')
113
+ const encoder = new VideoEncoder({ output: (chunk, meta) => muxer.addVideoChunk(chunk, meta), error: (e) => { throw e } })
114
+ encoder.configure(config)
115
+
116
+ // per stepped frame i
117
+ const frame = new VideoFrame(nv12, {
118
+ format: 'NV12', codedWidth: 3840, codedHeight: 2160,
119
+ timestamp: Math.round(i * 1e6 / 60), duration: Math.round(1e6 / 60),
120
+ colorSpace: { primaries: 'bt709', transfer: 'bt709', matrix: 'bt709', fullRange: false },
121
+ })
122
+ encoder.encode(frame, { keyFrame: i % 120 === 0 })
123
+ frame.close()
124
+ while (encoder.encodeQueueSize > 4) await new Promise((r) => setTimeout(r, 0))
125
+ ```
126
+
127
+ - `nv12` is a buffer you produce with a GPU pass that converts the rendered RGB to NV12 with
128
+ the BT.709 matrix. A `VideoFrame` built straight from the canvas lets the encoder pick the
129
+ matrix, and OC's came out tagged BT.601.
130
+ - Mux with a library such as Mediabunny. Timestamps come from the frame index, never from
131
+ the clock, which is what makes a slow capture play back at full speed.
132
+ - Check the file with `ffprobe -show_streams`: size, rate, `color_space=bt709`,
133
+ `color_transfer=bt709`, `color_primaries=bt709`.
134
+
135
+ ## Audio
136
+
137
+ three.js audio runs on a real-time `AudioContext`, which cannot be stepped.
138
+
139
+ - 1x takes: connect the master gain to a `MediaStreamAudioDestinationNode` and record it, or
140
+ tap it with an `AudioWorklet`, then trim the output latency against a sync cue.
141
+ - Stepped and slow-motion takes: keep the cue log (cue id, simulation time, gain, position
142
+ relative to the camera) and render it afterwards in an `OfflineAudioContext`, which runs
143
+ faster than real time and gives the same result every run. This is a suggestion for
144
+ three.js; OC drained its own mixer's ring buffer instead, `sampleRate * step` samples per
145
+ frame.
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: opengame-characters
3
+ description: Bring generated or imported 3D characters into a browser game so they hold up in play. Covers skin checks against pinched waists, eased gait choice against third-person jitter, authored locomotion over procedural, thumb-and-mitten hands on the posed gun, canon sheets against drift, instant customisation, gated stages and real grips. Use when the character T-poses, jitters, bends wrong, feet slide, hands clip the gun, it drifts from the art, customising is slow, or a game shows the player's OG.
4
+ metadata:
5
+ version: "1.1.0"
6
+ ---
7
+
8
+ # Characters
9
+
10
+ A character is finished when it is right in the live spawn path, from the gameplay
11
+ camera, while moving, including from behind. A model that loads, a rig that binds and
12
+ a clip that plays are three separate facts, and none of them proves the visible
13
+ character is correct.
14
+
15
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes.
16
+ Generation and Meshy specifics are in `opengame-assets`.
17
+
18
+ ## Rules
19
+
20
+ ### Bodies keep their volume in every clip
21
+ - **Invariant:** No character or creature pinches, hourglasses, splits or bends wrong at the waist, hips, shoulders or neck in any clip, and this is checked when the asset is imported and again in motion.
22
+ - **Technique:** At import, pose every clip offline and measure the posed waist width against the bind waist. Check that no thigh weight reaches above the hip or crosses to the other leg, that hoods and collars are not weighted into the head, that skirts and aprons follow the hips, that normals agree with face winding, and that left and right parts match. Spread twist over several torso bones. Then watch a turntable of every clip, because the numbers pass before the eye does.
23
+ - **Reference configuration:** OC passes a waist at 0.95 or more of rest, and below 0.90 is a visible pinch. Two zombie types sat at 0.81 and 0.79; after reweighting all 20 heroes reached 0.957 or more and the zombies 0.97 to 0.99. A bind waist at 63 to 65% of hip depth reads as an hourglass even with good weights. One waist kept 65% of its width before the fix and 98% after; an apron weighted to the thighs filled the gap between the legs; a hook was weighted to the thigh instead of the hand; one shoe was 27% longer than its pair. The owner sent three messages in about 30 minutes ("we cant have that on any character or creature!"), and the defect was declared fixed by numbers while screenshots still showed it.
24
+ - **Applies when:** Every skinned character or creature, generated or bought.
25
+ - **Verify:** The import report lists the waist ratio per clip for every body, and a turntable of each clip in play shows no pinch.
26
+
27
+ ### No pose weight ever changes in one frame
28
+ - **Invariant:** Gait choice, direction switches and layer weights ease over time, so a third-person body never pops, flips or jitters while running, strafing, stopping or idling.
29
+ - **Technique:** Pick the locomotion clip from a smoothed speed, never the raw one. Damp every blend weight, add hysteresis to direction thresholds, unwrap angle channels before clamping, cross-fade loop joins, and sample gait keys on a spline. Replace every boolean pose gate (grounded, armed, aiming) with an eased weight. When a body jitters, measure the body on its own before touching the camera or world (see `opengame-game-feel`).
30
+ - **Reference configuration:** OC's third-person jitter, raised 6 or more times over 3.5 days, came from a gait clip picked on raw speed; an ease of about 80 ms and spline-sampled gait keys ended it. A toe-yaw clamp flipped 51 degrees in 2 to 3 frames; a strafe switch without hysteresis turned the legs 137 degrees in one frame; a grounded gate dropped the hips 3 cm in one frame and an armed gate popped the arms on every swap; the idle loop's join was 68 times the median frame step.
31
+ - **Applies when:** Every animated character seen in third person or by other players.
32
+ - **Verify:** Record running, stopping, strafing and idling at the display rate; plot the second difference of root and head and the body's screen position per frame, and flag arm jumps over the game's threshold.
33
+
34
+ ### Locomotion is authored; procedural motion is a small layer
35
+ - **Invariant:** Walking, running, idling and actions come from authored or captured clips blended by speed, with feet planted and legs still at idle; procedural passes add small corrections on top and never replace a limb's pose.
36
+ - **Technique:** Buy or capture a locomotion set before writing procedural legs or arms. Blend clips by measured speed with matched phase, set cadence from distance travelled, and fix bad channels in the clip data at the source. Audit each procedural pass by turning it off and comparing.
37
+ - **Reference configuration:** OC: mocap clips at walk 1.4, jog 3.4, run 4.8 and sprint 6.2 m/s, crossfades of at least 0.15 s; 40 clips cost about $2.40. Cadence by distance (1.05 m per walking cycle) cut foot skate from 84% to 30%. The "mannequin arms" the owner disliked came from a procedural arm pass that pulled the arms level. A knee and foot channel swap was fixed in 11 clips at the source. The owner asked 7 to 10 times, including "not even moving and my characters legs are moving".
38
+ - **Applies when:** Every walking character. A stylised procedural walk is a style choice, made once and checked against the concept.
39
+ - **Verify:** Stand still, walk, run and sprint in play and record the feet: planted feet do not slide and idle legs do not move. Turn each procedural layer off and confirm the base clip already reads right.
40
+
41
+ ### Hands are a thumb and a mitten, fixed to the posed gun
42
+ - **Invariant:** First-person and held-item hands are simple closed shapes that rig and pose easily, attach to the item's posed transform, never pass into it, and never cover the sight.
43
+ - **Technique:** Model the hand as a thumb plus a single mitten body, cuff-wide, as one closed mesh, unless the game's style needs fingers. Parent it to the gun's posed transform, not the unposed one. Test penetration numerically per reload phase (`opengame-weapons` has the check) and keep sleeves from stretching to reach.
44
+ - **Reference configuration:** The owner on OC: "basically a thumb and then a blob for hands ... It should be easier to then rig it and animate it with the guns versus having five fingers", and later "We don't need five fingers. If anything you just need a thumb". Before that it took 4 first-person passes and 5 glove redesigns. OC's sleeves are about 0.17 m across. A hold constant stretched sleeves 16%; a glove covered 35% of one gun's aimed centre.
45
+ - **Applies when:** First-person games and any character holding tools, unless the art style calls for articulated fingers.
46
+ - **Verify:** Capture hip, aimed and every reload for each gun; measure penetration and the covered share of the aimed centre.
47
+
48
+ ### One canon sheet per character stops drift
49
+ - **Invariant:** Each character's identity (proportions, head count, eyes, outfit, colours) comes from one canon sheet of turnarounds, scene paintings guide composition and light only, and every round compares the build with the sheet.
50
+ - **Technique:** Write the canon on day one, with turnarounds, measured proportions, the eye and face rules and the materials. Generate 3D only from the turnarounds, never from scene paintings. Put a side-by-side of build and canon in every round's report, measured where it can be.
51
+ - **Reference configuration:** OC's canon doc said 2.2 heads tall while the measured turnaround was 2.7. Scene concepts had invented different outfits, helms and horns, and assets generated from scene frames inherited the drift. Eyes: an open eye is a black oval with a small white oval at the bottom and a glint, no rim; a closed eye is a thick tapered lid; eye-white albedo about 0.02. Several eye shader edits never reached the build. All five early character sheets were rejected; after the canon pass the harsher canon critic rose from 3.6 to 5.3. The owner: "make sure we dont drift like that".
52
+ - **Applies when:** Every game with designed characters, above all when generating them.
53
+ - **Verify:** A sheet per character per round, canon beside build at the same angles, with the head-count ratio and eye crop measured.
54
+
55
+ ### Customisation shows on the next frame
56
+ - **Invariant:** Every customisation choice appears on the next frame, on the first click, in any order, and the screen never shows a wrong or half-built character while it loads.
57
+ - **Technique:** Make colour and eyes material parameters over a baked mask. Build shapes and outfits from parts imported ahead of time into a small resident pool, preload the neighbours of the current choice, and spread imports over frames so preloading does not stutter. Keep the previous complete character on screen until the exact new one is ready. Persist the last avatar and show it on the title, select and spawn.
58
+ - **Reference configuration:** OC's target was every row within about 0.1 s. At one point a change took 1.2 to 12.8 s; colour later took 2 to 86 ms and heads 51 to 135 ms, and outfits still took 0.8 to 2.8 s at the end. A pool of 4 pre-imported looks hit in 15 to 31 ms within 24 MB; three background workers were the limit (five slowed imports 2.5x); warm imports paused for 20 frames after any change; eager preloading caused 38 hitches against 16. Head bakes took 1.7 to 2.7 s each. The owner, 5 or more times: "customizing OGs MUST be instant!" and "it cant be that fucking hard".
59
+ - **Applies when:** Games with character creators, outfit pickers or loadout previews.
60
+ - **Verify:** Reload the page, then click every row cold in a random order with a frame recording; time each click to its final frame and count hitched frames.
61
+
62
+ ### Gate every stage
63
+ - **Invariant:** Each stage of a character (reference, mesh, remesh, rig, skin check, clips, sockets, play) is inspected and passed before the next one is paid for.
64
+ - **Technique:** Keep a short stage list per character with the evidence for each: the reference image, a turntable of the mesh, the polygon count after remesh, a rest-pose capture of the rig, a stretch pose for skinning, each clip looped three times, each socket with its equipment, and a capture in play.
65
+ - **Reference configuration:** ST gates characters this way, and MC found that two soldiers generated with identical parameters came back at different quality, so each one is checked rather than assumed.
66
+ - **Applies when:** Every generated or imported rigged character.
67
+ - **Verify:** The stage list has evidence for every stage of every character in the game.
68
+
69
+ ### Pilot two bodies before making many
70
+ - **Invariant:** The pipeline is proven on two anatomically different characters before it runs for the rest.
71
+ - **Technique:** Pick the two most different bodies the game needs (a heavy and a slight one, a biped and a creature) and take both all the way to play first. Rigs from one generator are not interchangeable; budget a per-character solve for stances, grips and contact.
72
+ - **Reference configuration:** ST pilots two before forty. MC found its generator's rigs were not interchangeable between soldiers and that stance correction was a third per-soldier solve.
73
+ - **Applies when:** Any game with more than a couple of characters.
74
+ - **Verify:** Both pilots pass every gate in play before a batch is started.
75
+
76
+ ### No T-poses, no primitive stand-ins
77
+ - **Invariant:** No character is ever seen in its bind pose, and nothing a character holds is a primitive.
78
+ - **Technique:** Start every character in an idle clip before its first render; give held items their own models with grip markers. A missing clip falls back to idle, never to the bind pose.
79
+ - **Reference configuration:** Our originals require a rig and at minimum idle, locomotion and the game's one signature action on every character mesh. ST's review fails a T-pose anywhere.
80
+ - **Applies when:** Every game with characters.
81
+ - **Verify:** Capture every character on its first visible frame after spawn and after a respawn.
82
+
83
+ ### One owner of movement
84
+ - **Invariant:** The controller moves the character's root through the world; animation never moves it, so the body, the collision capsule and the equipment stay together.
85
+ - **Technique:** Strip net horizontal travel from locomotion clips while keeping bob and sway, normalise rest height and forward once, and use a positive uniform scale on animated ancestors. Correct gait clips only, never actions, jumps or deaths.
86
+ - **Reference configuration:** AW rebases the hips of its mocap; ST's `prepareLocomotionClip` removes travel and checks three loops for drift. SR's death clip moves the hips more than two metres, so SR samples it once to set a conservative bound and culling stays on.
87
+ - **Applies when:** Every animated character driven by a controller.
88
+ - **Verify:** Loop each gait three times in place: no drift, no snap at the loop, no separation from the capsule.
89
+
90
+ ### Gaits blend by phase and speed
91
+ - **Invariant:** Feet do not slide or pop: transitions blend, a new gait starts where the old one's feet were, and playback speed matches ground speed.
92
+ - **Technique:** Crossfade every transition, starting the new clip at the old clip's normalised phase. Set playback rate from displacement after collision, divided by stride over clip length, clamped per clip. Pick the gait from measured motion relative to facing, not from the key pressed.
93
+ - **Reference configuration:** SR and MC crossfade 0.14 to 0.16 s, ladders and mantles 0.22 to 0.30 s. Gait thresholds walk above 0.4 m/s and run above 6 m/s. DK varies each actor's idle speed (0.55 + (id % 7) * 0.04) so a horde never moves in lockstep. OC crossfades in at least 0.15 s at a matched phase and sets `timeScale` from velocity.
94
+ - **Applies when:** Every walking character.
95
+ - **Verify:** Record feet against the ground at slow, normal and sprint speed, against a wall and on stairs; no foot moves while planted.
96
+
97
+ ### Hands hold the real grip
98
+ - **Invariant:** A held weapon or tool follows the animated body, both hands sit on its real grips through movement, aim, recoil and reload, and the shot leaves from its real muzzle.
99
+ - **Technique:** Attach rigid equipment to a bone with the inverse of the bone's rest transform so it keeps its fitted pose. Author grip and muzzle markers on the actual model, animate a pivot rather than the frozen carry matrix, then solve each arm as a two-bone chain to its grip with a stable elbow pole, clamping unreachable targets rather than stretching.
100
+ - **Reference configuration:** MC's weapon IK, AW's hand-on-weapon validator, SR's weapon mount and DK's gear attachment by inverse rest matrix. SR validated 540 hand-grip poses across four outfits and every weapon. OC's default IK pole gave a 52 degree elbow where 17 to 18 was the target, and its third-person gun canted left twice.
101
+ - **Applies when:** Characters that hold things, in third person or in any view that shows them from outside.
102
+ - **Verify:** Capture both palms against the grips at several aim angles and through a reload; muzzle flash and shot origin coincide.
103
+
104
+ ### Judge from the gameplay camera
105
+ - **Invariant:** A character is accepted on how it looks in play, from the camera the player uses, from every side the player sees.
106
+ - **Technique:** Capture rest, movement, the signature action and its return, from the gameplay camera, including rear views, and compare against the concept at the same camera. Judge motion as a frame sequence, not a still.
107
+ - **Reference configuration:** ST compares player-camera captures with the selected concept and sends actual pixels to an adversarial reviewer; SR's character review lists native shoulder-camera appearance as outstanding until it is seen in play. OC's third-person gun was "hidden behind the body in every follow view"; the owner asked to see the hold "in EVERY camera hangle".
108
+ - **Applies when:** Every game with characters.
109
+ - **Verify:** A reviewer with fresh context passes the captures, rear views included.
110
+
111
+ ### Fair bodies and fair budgets
112
+ - **Invariant:** Hitboxes are fair across characters, and every character fits the game's frame budget.
113
+ - **Technique:** Normalise heights so a tall character is not easier to hit, keep the hit capsule independent of cosmetic equipment, set polygon counts before rigging, and share geometry and materials across instances. Clone skinned characters with `SkeletonUtils.clone` so each owns its bones.
114
+ - **Reference configuration:** ST budgets 150k triangles per character and 30k per prop. MC sets a 22,000 target before rigging so its rig does not bind to a mesh that is later remeshed. SR's four outfits add 1,140 to 1,320 triangles each and one mesh per actor without changing the hit capsule.
115
+ - **Applies when:** Games with several characters on screen, competitive games above all.
116
+ - **Verify:** Read triangle counts and draw calls with the busiest crowd on screen; compare hit capsules across characters.
117
+
118
+ ### The player's OG is theirs, read fresh and never kept
119
+ - **Invariant:** A game that offers the player's OpenGame OG builds it from `og.player.avatar` each session, never stores it or anything built from it, asks for it or relays it to other players, falls back to its own default for anything missing or unknown, and shows the same OG as "Your OG" in every scene and point of view.
120
+ - **Technique:** Remembering that the player picked "Your OG" is fine; the recipe is not. Read it through `watchAvatar` from `@opengamehq/sdk/avatar`, which names the parts with the shared layout (`readAvatar` does the same for one recipe); never split the recipe by position. Map each part through the game's own table with a default per part, and draw it to `AVATAR-SPEC.md` in the SDK package, or start from the SDK's Three.js example in `examples/avatar-threejs`. For a menu, a scoreboard or a 2D game, `portraitUrl(avatar)` gives the head as OpenGame draws it. Start building the model off the main thread as soon as the SDK names the player, under the loading screen, and import it only in menus. List "Your OG" first, labelled, equipped once loaded, removed after sign-out. Give first person separate sleeves and hands in the same colors as the third-person OG rather than a shrunken body, keep a shoulder camera's OG to one side, give every OG the same hitbox in competitive play, and light menus separately from the level. The recipe format, the portrait, the 21-joint contract, the page-bake pattern and each view's settings are in [references/player-og.md](references/player-og.md).
121
+ - **Reference configuration:** OG Clash bakes the OG to a GLB in a Web Worker and drops it into its Kaigen engine; its shoulder camera sits 2.6 m back and 1.15 m right with a 58 degree lens and keeps the OG's center within 0.30 of the frame width from the left. Shrinking the body's head and arms for first person spread white shards under the camera, live portraits in a list froze the game at the 39th quick switch, and opening "Your OG" with 4 to 8 workers added 861 MB and crashed an iPhone.
122
+ - **Applies when:** Any game on OpenGame that shows the player as a character.
123
+ - **Verify:** Capture every view as a guest and with `?og-dev-player=signed-in`, including first person looking down while downed, then grep the game for any write of the recipe, or of a model or image built from it, to storage, network or logs.
124
+
125
+ ## Further reading
126
+
127
+ Meshy's rig skeleton, animation library and the traps MC hit integrating them are in
128
+ `opengame-assets`. Root-motion, carry-frame, grip, skin-check, eased gait and customise-pool code sketches:
129
+ [references/integration.md](references/integration.md).
@@ -0,0 +1,144 @@
1
+ # Integration sketches
2
+
3
+ Adapted from the Studio's character integration notes (ST), which were written from
4
+ World at War, Modern Claudefare, Skybreak and Der Koloss. Adjust bone names to the
5
+ actual skeleton; names such as `Hips` and `RightHand` are not universal.
6
+
7
+ ## Cadence from real motion
8
+
9
+ ```js
10
+ // World positions, dt > 0. Reset `previous` on spawn, teleport and resume.
11
+ const speed = Math.hypot(current.x - previous.x, current.z - previous.z) / dt
12
+ const rate = THREE.MathUtils.clamp(speed * clip.duration / strideMetres, minRate, maxRate)
13
+ walk.setEffectiveTimeScale(rate) // strideMetres: measured full-cycle foot travel
14
+ previous.copy(current)
15
+ ```
16
+
17
+ Use separate authored walk and run clips. A clamped rate cannot repair a wrong stride.
18
+
19
+ ## Equipment on a bone, keeping its fitted pose
20
+
21
+ ```js
22
+ function attachBone(THREE, bone, object) {
23
+ for (let p = bone; p; p = p.parent) if (p === object) throw Error('Attachment cycle')
24
+ bone.updateWorldMatrix(true, false)
25
+ object.updateWorldMatrix(true, false)
26
+ const det = bone.matrixWorld.determinant()
27
+ if (!Number.isFinite(det) || det === 0) throw Error('Singular bone frame')
28
+ const local = bone.matrixWorld.clone().invert().multiply(object.matrixWorld)
29
+ bone.add(object)
30
+ object.matrix.copy(local)
31
+ object.matrixAutoUpdate = false // keep the exact inverse; do not decompose shear
32
+ object.matrixWorldNeedsUpdate = true
33
+ }
34
+ ```
35
+
36
+ Call it once, at rest. Put the weapon under a pivot inside a carry group attached to the
37
+ chest, animate the pivot, and throw if the model has no grip markers:
38
+
39
+ ```js
40
+ const grips = ['grip_right', 'grip_left'].map(name => weapon.getObjectByName(name))
41
+ if (grips.some(grip => !grip)) throw Error('Author both grip markers on the actual model')
42
+ ```
43
+
44
+ ## Order of operations each frame
45
+
46
+ ```js
47
+ controller.step(dt) // collision-resolved root transform
48
+ selectGaitAndCadence(dt) // from actual distance, keeping gait phase
49
+ mixer.update(dt) // the authored base pose for this frame
50
+ applyTorsoAimAndWeaponPose(dt) // carry follows chest; aim and recoil on the pivot
51
+ actorRoot.updateMatrixWorld(true)
52
+ solveArmsToWeaponGrips(grips) // two-bone chains; update matrices after each joint
53
+ orientWristsAndPoseFingers() // grip shape, not just hand position
54
+ actorRoot.updateMatrixWorld(true)
55
+ ```
56
+
57
+ Restore procedural bone overlays before the next mixer step if the clip does not write
58
+ those bones. Never accumulate IK or recoil into yesterday's pose: MC's spazzing head was
59
+ an additive layer that was not idempotent.
60
+
61
+ ## Contact and rendering
62
+
63
+ - A bone's axis is not the sole of the shoe. Verify foot contact on the final skinned
64
+ mesh against the ground, per motion phase.
65
+ - Base colour and emissive textures in sRGB; normal, roughness, metalness and occlusion
66
+ linear. Texture factors must not erase their maps.
67
+ - Judge imported and procedural surfaces together under the game's own lighting, at the
68
+ size they appear on screen.
69
+ - MC's floating corpse came from a ground-lock solver that could only push up. Test the
70
+ death pose on slopes and stairs.
71
+
72
+ ## Waist check at import (OC)
73
+
74
+ Pose each clip offline and compare the waist's width with the bind pose. OC passes 0.95
75
+ and treats anything under 0.90 as a visible pinch.
76
+
77
+ ```js
78
+ // mesh: THREE.SkinnedMesh; waist: indices of vertices in a band at waist height
79
+ function waistWidth(mesh, waist) {
80
+ const v = new THREE.Vector3()
81
+ let min = Infinity, max = -Infinity
82
+ for (const i of waist) {
83
+ mesh.getVertexPosition(i, v) // skinned position in the mesh's local space
84
+ v.applyMatrix4(mesh.matrixWorld)
85
+ min = Math.min(min, v.x); max = Math.max(max, v.x)
86
+ }
87
+ return max - min
88
+ }
89
+ mesh.skeleton.pose(); root.updateMatrixWorld(true) // the bind pose
90
+ const bind = waistWidth(mesh, waist)
91
+ for (let t = 0; t < clip.duration; t += 1 / 30) {
92
+ mixer.setTime(t)
93
+ root.updateMatrixWorld(true) // bones' world matrices drive getVertexPosition
94
+ if (waistWidth(mesh, waist) / bind < 0.95) report(clip.name, t)
95
+ }
96
+ ```
97
+
98
+ Run the same loop for depth as well as width; an hourglass can show in either. Also
99
+ report thigh weights on vertices above the hip and weights that cross from one leg to the
100
+ other.
101
+
102
+ ## Gait choice from smoothed speed (OC)
103
+
104
+ ```js
105
+ // Raw speed picked the clip in OC and the body jittered; about 80 ms of easing ended it.
106
+ const k = 1 / 0.08
107
+ smoothSpeed += (rawSpeed - smoothSpeed) * (1 - Math.exp(-k * dt))
108
+ const want = pickGait(smoothSpeed, current) // thresholds with hysteresis around `current`
109
+ if (want !== current) {
110
+ next = actions[want]
111
+ next.reset().setEffectiveWeight(1).play()
112
+ next.time = (actions[current].time / actions[current].getClip().duration) * next.getClip().duration
113
+ actions[current].crossFadeTo(next, 0.2, false)
114
+ current = want
115
+ }
116
+ ```
117
+
118
+ Never write `action.weight = grounded ? 1 : 0`. Ease every such weight toward its target
119
+ with the same exponential.
120
+
121
+ ## A customise pool that does not stutter (OC)
122
+
123
+ ```js
124
+ // Parts are parsed ahead of time and kept hidden; a change swaps visibility.
125
+ const pool = new Map() // partId -> Object3D, parsed and compiled
126
+ const queue = [] // parts to warm, nearest choices first
127
+ let quietFrames = 0
128
+
129
+ function onChoice(partId) {
130
+ const part = pool.get(partId)
131
+ if (part) show(part) // next frame
132
+ else keepCurrentAndQueue(partId) // the old complete figure stays on screen
133
+ quietFrames = 20 // OC paused warm imports 20 frames after a change
134
+ }
135
+
136
+ function tick() { // once per frame
137
+ if (quietFrames > 0) { quietFrames--; return }
138
+ const job = queue.shift()
139
+ if (job) warmOne(job) // one part per frame: loadAsync, clone, compileAsync
140
+ }
141
+ ```
142
+
143
+ Colours and eyes are uniforms over a baked mask, never a rebuild. Clone skinned parts with
144
+ `SkeletonUtils.clone` and bind them to the character's skeleton.
@@ -0,0 +1,160 @@
1
+ # The player's OG
2
+
3
+ How a game shows the player's OpenGame character. The docs page "Draw the player's
4
+ OG" (`/guides/characters`) is the long version, and `AVATAR-SPEC.md` in the
5
+ `@opengamehq/sdk` package is the style spec: every part's shape, size and color, well
6
+ enough to draw an OG in any engine and art style. This is what an agent needs while
7
+ writing the code. Numbers marked OG Clash worked in that game, a single-player Kaigen
8
+ first- and third-person shooter; measure your own.
9
+
10
+ ## Read it
11
+
12
+ ```js
13
+ import { og } from '@opengamehq/sdk'
14
+ import { watchAvatar } from '@opengamehq/sdk/avatar'
15
+
16
+ await og.init()
17
+ watchAvatar(og, avatar => {
18
+ if (!avatar) return useDefaultCharacter() // guest, sharing off, preview, signed out
19
+ prepareYourOg(avatar) // avatar.head, avatar.outfit (null: default body)
20
+ })
21
+ ```
22
+
23
+ - `og.player.avatar` is `{ seed, palette, look?, character? }`. `look` is the head
24
+ (`shape.eyes.color[.accessory[.identity]]`). `character` is the body and clothes
25
+ (`c3.body.legs.shirt.bottoms.accessory.shoes.shirtColor.bottomsColor.shoesColor.accessoryColor`;
26
+ `c4` joins several accessories with `-`; `c1` and `c2` are older saves).
27
+ - `@opengamehq/sdk/avatar` names each part and gives a hex per color in the SDK's table. It
28
+ takes the layout from `packages/shared`, so do not split the strings yourself: a
29
+ positional split turns `cape-watch` into one accessory.
30
+ - `avatar` and `match` colors follow the head (`followsHead`); their `hex` is the
31
+ head's unshaded swatch, and OpenGame renders `avatar` darker by garment. `head.finish`
32
+ marks patterned, metallic, neon and glass colors whose `hex` is an approximation. `mono` is black on
33
+ light pages and white on dark ones. `identity` picks a face set: do not use it for
34
+ gender, pronouns or voice.
35
+ - Ids are not checked against a catalogue. Map each part through a table in your game and
36
+ fall back to your default for any id the table lacks; an outfit in an unknown
37
+ version comes back as `outfit: null`, so put their head on your default body.
38
+ - `portraitUrl(avatar, { size, theme })` gives the address of the player's head as a
39
+ transparent PNG, drawn by OpenGame, or null when there is no OG. The address is keyed
40
+ by the look alone and names nobody, and the image never changes, so cache it. `size`
41
+ rounds up to one OpenGame draws (`64`, `128`, `256`, `512` pixels; the default
42
+ is 256). `theme: 'dark'` draws the inks for a dark
43
+ page. Any origin may load it, so set `crossOrigin = 'anonymous'` and use it as a WebGL
44
+ texture too.
45
+ - No bundler: copy the SDK's `dist/avatar.js` (no imports) and load it from a module
46
+ script with `OpenGame.og`. Native engines get raw recipes from the bridge's
47
+ `player()`; call `readAvatar` in the page and pass the JSON in.
48
+ - Local: `?og-dev-player=signed-in` or `og.init({ dev: { player: 'signed-in' } })`
49
+ gives look `circle.classic.white` and a `c4` hoodie, jeans, cape and watch.
50
+
51
+ ## Do not
52
+
53
+ - Store the recipe or any part of it (local storage, saves, your server, analytics,
54
+ error reports), or anything built from it: a cached model, a baked GLB (OG Clash
55
+ writes both recipes into the GLB metadata), a replay. Log unknown ids to the console only.
56
+ Remembering that the player chose "Your OG" is fine.
57
+ - Share an image of their OG except when the player chooses to share it.
58
+ - Ask the player to type or pick their OG.
59
+ - Send one player's recipe to another. A recipe relayed by a client is unverified and
60
+ beyond what the player agreed to.
61
+ - Change the head, colors or accessories and still call it "Your OG". Scale, lighting,
62
+ a team outline or badge, and a prop to hold are fine.
63
+ - Draw a stand-in OG when there is no recipe. Use your default character.
64
+
65
+ ## Build it
66
+
67
+ | Game | Model |
68
+ | --- | --- |
69
+ | Three.js | `examples/avatar-threejs` in the SDK package. Copy `og-model.js` and `og-spec.js`, call `buildOg(avatar)` with `readAvatar`'s result, and call the old group's `userData.dispose()` before you replace it |
70
+ | Other JS engine | Your art drawn to `AVATAR-SPEC.md`, or the Three.js example on a separate canvas for menus and the title |
71
+ | Native (Unity, Godot, Kaigen, C/C++) | A GLB baked in the page with a painted face (OG Clash wrote one), or your art drawn to `AVATAR-SPEC.md` |
72
+ | 2D, lists, scoreboards | `portraitUrl(avatar)`: the head as OpenGame draws it |
73
+ | Custom art | `readAvatar` parts mapped to your meshes or sprites |
74
+
75
+ The Three.js example builds the figure from primitives only (spheres, capsules, lathes
76
+ and discs) at 1 unit per H, standing on y = 0 and facing +z. `og-spec.js` holds the
77
+ spec's lengths and catalogue colors as data and is generated from the same catalogue as
78
+ `AVATAR-SPEC.md`. Change the style freely: the spec's "What makes it an OG" list is what
79
+ has to survive. A part the example does not know is drawn with the spec's default.
80
+
81
+ OG Clash's bake paints the face into a texture: built in a Web Worker, merged to 1
82
+ skinned mesh, 1 PBR material, 1024 px atlas, 12-expression eye sheet; 2.01 m,
83
+ about 100,000 triangles, 4.4 MB; about 2 s in Node on a desktop Mac, 3.7 s first bake in
84
+ the browser; the worker bundle is 748 KB before compression. Built under the loading
85
+ screen as soon as OpenGame names the player (phones and tablets wait for the title, since
86
+ the engine's load is their memory peak), held until the menus, dropped on the canvas as
87
+ `og_custom_<hash>.glb`; it checks 21 joint names,
88
+ a metadata block with sizes in range, and the file name. Kaigen's side:
89
+ `/engines/kaigen#play-as-your-own-og`.
90
+
91
+ OG Clash's joint contract, 21 joints. `_r` is the OG's right (-X), on your left when
92
+ the OG faces you: `root`, `trunk`, `thigh_r`, `shin_r`, `foot_r` and the mirror, `arm_r`,
93
+ `forearm_r`, `wrist_r`, `finger_r0..2` and the mirror, `head`. Meters, +Y up, facing +Z,
94
+ feet at 0. Arms and the head hang off `trunk`, legs off the root. The bake carries no
95
+ joint scale; if your rig scales a parent, copy local quaternions, not world matrices or
96
+ Euler angles. One torso joint, so a twist happens at the hips; OG Clash capped chest
97
+ twist at about 45 degrees.
98
+
99
+ ## Points of view (OG Clash's numbers)
100
+
101
+ - **First person, exploring (OpenGame's 3D world):** body shown, head and collar hidden;
102
+ for hand actions the arms swap to a 0.78-size set through a 58 degree lens; world lens
103
+ 74 degrees, near 0.04 m, eye moved forward when looking down.
104
+ - **First person, shooting:** separate sleeves in the shirt color and hands on the
105
+ gun's posed transform; third-person body hidden, not
106
+ shrunk (a shrunk head and shrunk limbs spread white shards under the camera). Same hand
107
+ color as third person: OpenGame's hands are the head color, and OG Clash's white
108
+ first-person mittens on "Your OG" do not match the third-person hands. Viewmodel lens
109
+ 68 degrees over a 66 degree world; fill light, no viewmodel shadows. Fade OGs inside
110
+ 0.65 m, to 30% at 0.3 m. Capture looking down while downed too.
111
+ - **Third person, shoulder:** OG on one side (OG Clash: left, at the owner's request).
112
+ 2.6 m back, 1.15 m right, pivot 1.5 m, 58 degree lens; aiming 2.5 m and 1.0 m. Center
113
+ at most 0.30 of frame width from the left; head 0.12 to 0.17 of frame width. Distances
114
+ scale with OG height / 2, clamped 0.8 to 1.2. Aim along the camera ray, then check the
115
+ gun-to-target line for walls. Carry long guns low and right, muzzle
116
+ dropped; raise to the collar to aim, top tipped about 0.16 rad outward. Include hats in clearance. Hide the body when a
117
+ wall pushes the camera inside it. Offer few views.
118
+ - **Fair play:** OGs differ in height and head size. In a competitive game give all
119
+ players the same hitbox, capsule, eye height and speed. OG Clash, single-player, sets
120
+ first-person eye height per OG.
121
+ - **Top-down:** the head is the identity; keep the head color and accessory readable, add a
122
+ label or ring.
123
+ - **2D and side view:** `portraitUrl` gives the head in OpenGame's pixel style. Draw it
124
+ at a whole multiple of its size with `image-rendering: pixelated`, or draw the head
125
+ yourself from `AVATAR-SPEC.md`.
126
+ - **Menus:** turntable, menu-specific light (warm key, cyan rim), the old figure until
127
+ the new one loads then a 0.24 s scale-in, still images in lists (live portraits stalled
128
+ OG Clash at the 39th quick switch), eyes forced open in stills, the pose checked
129
+ against the head.
130
+ - **Title and results:** the player's OG in the shot, about 0.27 to 0.30 of frame height
131
+ on the title and 0.37 to 0.39 in victory; check each staged camera is not inside
132
+ geometry and aims at the OG's real height.
133
+ - **HUD:** `@handle (You)` from `og.player.handle`; with no handle, the character's name
134
+ and `(You)`, or `You` on "Your OG".
135
+
136
+ ## "Your OG" in the roster
137
+
138
+ First in the list, with a label; equipped once loaded unless the player picked another
139
+ this session; outfit options that would replace it locked with a reason; changes wait
140
+ for menus (a sign-in during a run waits); sign-out removes it at the next menu; a guest
141
+ gets only the roster; one OG chosen once and used in all scenes.
142
+
143
+ ## Fallbacks
144
+
145
+ No look: default character. Look, no outfit or unknown outfit version: their head on the
146
+ default body. Unknown part: default part. Failed or slow build: default character, log
147
+ the reason to the console, retry at the next menu (OG Clash: 90 s). Still building: the
148
+ previous figure, not an empty stage or gray stand-in.
149
+
150
+ ## Memory
151
+
152
+ Boot does not wait for the OG beyond a short hold at the title for a build already under
153
+ way (OG Clash: 4 s at most), and the builder's download counts too. Few workers,
154
+ stopped when the character screen closes: OG Clash's desktop build runs a warm worker and a
155
+ spare and found 3 the limit (5 slowed imports), and phones get 1. Opening "Your OG" once added 861 MB to OG Clash's page (4 to 8 workers, builds
156
+ in advance, caches) and crashed an iPhone; the light mode for phones, tablets and
157
+ devices reporting 4 GB or less uses 1 worker, no builds in advance, a 24 MB model cache
158
+ instead of 96 MB, textures up to 1024 px. Import cost 144 to 188 ms over 5 frames, so
159
+ import only in menus. Change color and eyes as material parameters, not rebuilds. Test
160
+ in Safari on a real phone.