@opengamehq/cli 0.0.0-stage → 0.4.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 (74) hide show
  1. package/AGENTS.md +235 -0
  2. package/CHANGELOG.md +9 -0
  3. package/README.md +128 -2
  4. package/dist/cli.mjs +1415 -0
  5. package/dist/opengame-global.js +3 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +13 -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 +512 -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 +204 -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 +254 -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 +83 -0
  66. package/dist/skills/opengame-stability/SKILL.md +84 -0
  67. package/dist/skills/opengame-verification/SKILL.md +136 -0
  68. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  69. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  70. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  71. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  72. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  73. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  74. package/package.json +38 -4
@@ -0,0 +1,169 @@
1
+ # Weapons in three.js
2
+
3
+ The engine-agnostic rules are in `SKILL.md`. This file is how to meet them in three.js.
4
+ Numbers are OC's unless another game is named.
5
+
6
+ ## A separate view model scene and camera
7
+
8
+ Render the world, clear depth, then render the view model with its own camera. The view
9
+ model never clips into walls because the world's depth is gone when it draws, and its
10
+ lens does not follow the FOV slider.
11
+
12
+ ```js
13
+ const viewScene = new THREE.Scene()
14
+ const viewCamera = new THREE.PerspectiveCamera(75, aspect, 0.012, 10) // fixed FOV, tiny near
15
+ renderer.autoClear = false
16
+
17
+ function frame() {
18
+ renderer.clear()
19
+ renderer.render(worldScene, worldCamera) // world FOV from the slider, 65 to 110
20
+ renderer.clearDepth() // the view model ignores world depth
21
+ renderer.render(viewScene, viewCamera)
22
+ }
23
+ ```
24
+
25
+ - Copy the world camera's rotation into the view camera each frame, before sway and kick
26
+ are added to the gun, so shots still leave along the world camera's ray.
27
+ - On resize, update both cameras' `aspect` and call `updateProjectionMatrix()` on both.
28
+ Only the world camera's `fov` follows the settings slider.
29
+ - Aiming changes the view camera's FOV with the gun's own aim time (OC: 75 to 58.5
30
+ degrees), not the world FOV slider.
31
+ - Move the world camera's near plane out (DK used 0.15) once the view model has its own
32
+ near plane; it buys depth precision for the world.
33
+
34
+ ## Depth and post-processing
35
+
36
+ - Run depth-reading world passes (SSAO, depth of field, fog, motion blur) on the world
37
+ scene only, then draw the view model. In `EffectComposer`, add a second `RenderPass`
38
+ for `viewScene` with `clear = false` and `clearDepth = true`, after the world's
39
+ depth-reading passes and before the output pass.
40
+ - Motion blur on the world with the gun sharp is OC's default. Keep the view model out
41
+ of any velocity buffer.
42
+ - Do not let the view model cast shadows into the world. A third-person world model of
43
+ the same gun casts them instead.
44
+ - Bloom runs after both, so clamp the view model's emissive (reticles, wonder glow)
45
+ before tonemapping. A 0.8 mm glowing torus bloomed into a seven-ring flower; draw
46
+ reticles in a shader instead.
47
+
48
+ ## Light and environment for the view model
49
+
50
+ The view model gets its own environment and a small rig so it never goes black in a
51
+ backlit world.
52
+
53
+ ```js
54
+ import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js'
55
+ const pmrem = new THREE.PMREMGenerator(renderer)
56
+ viewScene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture
57
+ viewScene.add(new THREE.HemisphereLight(0xdfe8ff, 0x302820, 0.6))
58
+ ```
59
+
60
+ OC's studio environment gave 41% of the gun's mean brightness, and the two directional
61
+ lights about 3 luma. Clone materials per held gun (`material.clone()`) so a menu preview
62
+ or a camo swap never changes a shared material.
63
+
64
+ ## Coverage masks for view model size
65
+
66
+ Render the view model alone to a small target with a flat override material and count
67
+ the lit pixels. Run it per gun at hip, aimed, sprinting and drawing, at 1280 x 720,
68
+ 1920 x 1080 and 844 x 390.
69
+
70
+ ```js
71
+ const target = new THREE.WebGLRenderTarget(w, h)
72
+ const flat = new THREE.MeshBasicMaterial({ color: 0xffffff })
73
+ viewScene.overrideMaterial = flat
74
+ renderer.setRenderTarget(target)
75
+ renderer.setClearColor(0x000000, 1)
76
+ renderer.clear()
77
+ renderer.render(viewScene, viewCamera)
78
+ renderer.setRenderTarget(null)
79
+ viewScene.overrideMaterial = null
80
+ const pixels = new Uint8Array(w * h * 4)
81
+ renderer.readRenderTargetPixels(target, 0, 0, w, h, pixels)
82
+ let lit = 0
83
+ for (let i = 0; i < pixels.length; i += 4) if (pixels[i] > 127) lit++
84
+ const share = lit / (w * h) // OC hip: pistol ~0.06, SMG ~0.08, rifle ~0.09
85
+ ```
86
+
87
+ The same mask with a central 20% x 20% box gives the aimed-view occlusion share (OC's
88
+ glove case went from 35.29% to 0.04%).
89
+
90
+ ## Aim and sights
91
+
92
+ - Compute the aimed offset from the sight mesh, not a socket: take
93
+ `sight.getWorldPosition(v)`, bring it into the view camera's space, and move the gun so
94
+ that point lands on the camera's axis. OC's socket was 343 mm off the ring, 31 px.
95
+ - Build the gun's aim from yaw and pitch (an `Euler` in `'YXZ'` order) or `lookAt` with a
96
+ fixed up vector. `Quaternion.setFromUnitVectors` takes the shortest arc and added 25 to
97
+ 30 degrees of roll.
98
+ - Ray-test each optic in CI: cast rays from the eye point through the lens area with a
99
+ `Raycaster` against the gun's own meshes; any hit on a "transparent" lens is a defect
100
+ (4 OC rifles blocked 385 of 385 rays).
101
+ - Draw the reticle in a fragment shader on the lens, visible only from the eye side,
102
+ over dark tinted glass with a fresnel edge. Exclude housings from camo materials.
103
+ - Scope tubes need 48 or more radial segments to read round when aimed.
104
+
105
+ ## Load hero models before they can be equipped
106
+
107
+ A gun is equippable only after its full model has loaded and its shaders have compiled.
108
+ Until then the previous gun stays in hand, and a purchase is refused with a message.
109
+
110
+ ```js
111
+ const cache = new Map() // url -> Promise<THREE.Object3D>
112
+ function loadGun(url) {
113
+ if (!cache.has(url)) cache.set(url, (async () => {
114
+ const gltf = await gltfLoader.loadAsync(url)
115
+ const gun = gltf.scene
116
+ gun.traverse(o => { if (o.isMesh) o.material = o.material.clone() })
117
+ await renderer.compileAsync(gun, viewCamera, viewScene)
118
+ return gun
119
+ })())
120
+ return cache.get(url)
121
+ }
122
+
123
+ async function equip(url) {
124
+ const next = await loadGun(url) // the old gun stays in hand while this resolves
125
+ holster(current)
126
+ draw(next)
127
+ current = next
128
+ }
129
+ ```
130
+
131
+ - Preload the guns the player can reach next: the loadout, the box pool, wall buys near
132
+ the player, menu neighbours. OC prewarmed its visible roster of 8 guns, about 28 MB.
133
+ - Gate the buy prompt on `cache.get(url)` having resolved, so a wall gun never charges
134
+ points for a model that is not there.
135
+ - Use KTX2 textures (`KTX2Loader`) and meshopt geometry (`MeshoptDecoder`) for hero guns,
136
+ and upload textures early with `renderer.initTexture(texture)` so the first draw does
137
+ not hitch.
138
+ - Never load a low level of detail as a placeholder. If nothing is resident, show a UI
139
+ loading state.
140
+
141
+ ## Reload beats in one table
142
+
143
+ ```js
144
+ // Exported from the beat spec; animation and audio both read it.
145
+ const reloadRay = [
146
+ { t: 0.00, beat: 'latch', sound: 'ray_latch' },
147
+ { t: 0.28, beat: 'chamber_open', sound: 'ray_open' },
148
+ { t: 0.62, beat: 'cells_out', sound: 'ray_cells_out' },
149
+ // one row per fresh cell in, then snap shut and flicker on
150
+ ]
151
+ ```
152
+
153
+ Drive an `AnimationAction` and schedule each sound from the same row, with
154
+ `AudioContext.currentTime` plus the row's offset from the action's start. The times
155
+ above are an illustration of the format, not OC's values.
156
+
157
+ ## Hand contact check
158
+
159
+ Offline, for each gun and reload phase, pose the arms with `AnimationMixer.setTime`,
160
+ read each hand vertex with `SkinnedMesh.getVertexPosition(i, v)` and transform it to
161
+ world space, then measure how far it sits inside the gun's mesh (a signed distance from
162
+ a BVH such as `three-mesh-bvh`). Flag every phase deeper than 8 mm.
163
+
164
+ ## Other engines
165
+
166
+ - Unity (URP): a base camera for the world and an overlay camera in its camera stack for
167
+ a weapon layer, with the overlay set to clear depth.
168
+ - Godot: render the weapon in a `SubViewport` with its own `Camera3D` and composite it
169
+ over the main view, or give the weapon its own visual layer and a second camera.
@@ -0,0 +1,114 @@
1
+ ---
2
+ name: opengame-world-physics
3
+ description: Make a 3D browser game's world physically coherent for players and AI. Covers colliders that fit what is drawn, stairs walked without jumping, a navigation step that matches the body's step, no tunnelling, bounded depenetration, ragdolls that settle, corpses on deadlines, ray queries on a budget and a fixed step. Use when the person says I walked through a wall, fell through the floor, have to jump up stairs, zombies get stuck on steps, corpses spaz out, or movement feels floaty.
4
+ metadata:
5
+ version: "1.0.0"
6
+ ---
7
+
8
+ # World physics for a walking player
9
+
10
+ What players report as "the physics is broken" is almost always one of a few seams:
11
+ something drawn that the collision layer does not know about, a staircase whose
12
+ collision is a wall of risers, a fast body that skips a thin floor in one frame, or a
13
+ correction that teleports a body out of a corner. Each has a known fix.
14
+
15
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. The
16
+ numbers below are at human scale in metres; scale them with the game.
17
+
18
+ ## Rules
19
+
20
+ ### One placement, two layers
21
+ - **Invariant:** What is drawn and what collides come from the same placements and transforms, and change together.
22
+ - **Technique:** Keep a small world spec (units, floor levels, player clearance, step and slope limits, which objects are solid and which decorative) and build both the visible mesh and its collider from one placement record. A door that opens, a platform that moves or a wall that breaks updates its collider in the same frame as its mesh.
23
+ - **Reference configuration:** DK registers real colliders for solid props from the same seeded placement pass that dresses the map, and runs its clearance audits after decoration so they cover it. AW measures against the same part list it draws.
24
+ - **Applies when:** Every 3D game with a walking body.
25
+ - **Verify:** Run the scene audit's colliders check (`opengame-scene-audit`); then open a door in play and walk through where it was.
26
+
27
+ ### Every visible solid blocks or says why not
28
+ - **Invariant:** A thing that looks solid stops the player, unless it carries an explicit reason it does not.
29
+ - **Technique:** Give every visible mesh either a collider or a `nocollide` reason ("foliage", "decal", "distant scenery"). Fit the collider to the drawn shape, since a box smaller than the mesh lets bodies into its edges. Give decorative clutter a simple proxy shape instead of its render mesh, so small steps over rubble still work. Use nearby candidates or a spatial index for the query, never every render triangle every frame.
30
+ - **Reference configuration:** AW's body-physics gate floods each map with a capsule from its spawns and reports any reachable position inside drawn opaque volume with no collider; it found bodies standing inside floor slabs that every grid check had passed. OC's palisade, fences, railings and roofs had no collider, its building boxes covered 84% of the footprint, and the owner reported walking through props about 7 times. OC's rubble kept its dense collision even when flagged non-solid.
31
+ - **Applies when:** Every 3D game with a walking body.
32
+ - **Verify:** Walk into representative walls, large props, closed doors, corners and the back and side of stairs, straight and diagonally and at full speed.
33
+
34
+ ### A body at real scale
35
+ - **Invariant:** The player's collision body is sized to the world it moves through, so doorways, steps, ledges and cover all work at the scale they are drawn.
36
+ - **Technique:** A capsule or cylinder with a radius, a height and a step height chosen together with the level's door widths, riser heights and cover heights. Mantling has its own maximum height and needs a ledge deep enough to stand on.
37
+ - **Reference configuration:** AW: radius 0.35 m, height 1.80 m, eye at 1.62 m, step 0.42 m, mantle up to 1.35 m onto a ledge at least 0.28 m deep within 0.85 m reach, over 0.55 s. Walk 4.9 m/s, sprint 6.9 m/s, jump velocity 4.5 against gravity 13.5. Bots use the same numbers, so what a player can climb a bot can.
38
+ - **Applies when:** First and third person at human scale. Top-down and side-on games pick their own body and say so in the world spec.
39
+ - **Verify:** Walk the body through the narrowest doorway, onto the tallest step, and mantle the tallest intended ledge; all succeed, and the next height up fails.
40
+
41
+ ### Stairs are walked, never jumped
42
+ - **Invariant:** Every staircase is climbable holding forward only, with no jump, snag, oscillation or launch, and cannot be entered through its side.
43
+ - **Technique:** Either a fitted invisible ramp whose width, slope and joins at the top and bottom match the visible flight, with treads that never block, or a step-aware controller. After a step-up, place the body on the landing rather than letting it hover at the riser. Neither may bridge a real gap.
44
+ - **Reference configuration:** AW and DK both use invisible ramps for flights. AW's validator drives the shipped controller up every flight with forward input only, and one flight once offered no drivable start at all, which a forward-only bot reports and a grid check does not. OC settled on a 0.4 m step-up after the owner raised stairs 3 times ("again these kind of stairs"). Its first controller "stopped dead at the 45° step-on". A capsule that lowered as soon as its centre crossed a curb's lip, with its rear still in the stone, crossed 0 of 64 curbs; after the fix it crossed 64 of 64. In three.js, Rapier's `KinematicCharacterController` has `enableAutostep` and `enableSnapToGround`.
45
+ - **Applies when:** Any game with stairs, steps or ledges a player should walk.
46
+ - **Verify:** The walk bot in `opengame-scene-audit` climbs every flight with no jump input. By hand: approach at walking speed, cross the last riser onto the landing, turn, descend, then repeat diagonally and at sprint speed.
47
+
48
+ ### The navigation step matches the body's step
49
+ - **Invariant:** The navigation mesh's climb height, agent radius, agent height and slope limit match the movement body each AI uses, so every route the planner offers is one that body can walk.
50
+ - **Technique:** Derive the navigation settings and the controller settings from one entry in the world spec. Anything the body must jump or drop down is a link (see `opengame-enemies`), never a walkable step. Snap knockback and hit-stagger to the ground so a hit cannot push a body off its route on a slope. In recast-navigation-js, Recast's `walkableClimb` and `walkableHeight` are counted in cells of height `ch`, so convert from metres and check the units in the version you use. Godot's `NavigationMesh.agent_max_climb` and a Unity agent type's Step Height are the same setting.
51
+ - **Reference configuration:** OC's path map treated steps up to about 1.1 m as walkable while bodies could step 0.4 m, so the planner sent zombies up risers they could not climb, and 22 of 136 zombies were stuck in the fall state. OC's hit-stagger slid zombies down slopes because it had no ground snap.
52
+ - **Applies when:** Any game whose AI moves with a body along a navigation mesh or graph.
53
+ - **Verify:** Read the navigation settings and the controller settings at runtime and compare them. Then drive one AI body along a path over every step height the level has: it stops at no riser the planner called walkable.
54
+
55
+ ### Nothing tunnels
56
+ - **Invariant:** No body passes through a wall or a thin floor at any frame rate the game can run at, including its worst.
57
+ - **Technique:** Sweep or sub-step horizontal and vertical motion so each sub-step is shorter than the thinnest solid, and settle with a few passes per sub-step so corners converge.
58
+ - **Reference configuration:** AW sub-steps at `max(0.05, radius * 0.45)` with up to 8 settle passes, and tests at its own worst frame (`dt` clamped to 0.05 s) as well as at 60 Hz.
59
+ - **Applies when:** Every game with moving bodies and thin geometry.
60
+ - **Verify:** Sprint into a thin wall and drop onto a thin floor with the frame time pinned at the game's clamp; the body stays on the near side.
61
+
62
+ ### Depenetration is bounded
63
+ - **Invariant:** A body found inside geometry is pushed out gently, by the side it entered, never teleported through or across the room.
64
+ - **Technique:** Cap the correction per call and per frame, and share one budget across every sub-step and settle pass in the frame, because a per-call cap does not bound a frame that makes dozens of calls.
65
+ - **Reference configuration:** AW caps depenetration at 0.06 m per call and 0.12 m per frame (about one frame of sprinting). Before the per-frame cap it measured 0.576 m of correction in one frame from capped calls into one pipe bundle, and 0.828 m when a body wedged under a truck.
66
+ - **Applies when:** Every game that resolves overlaps.
67
+ - **Verify:** Spawn a body overlapping a crate and record its position per frame: it leaves by the nearest face in small steps.
68
+
69
+ ### Support after the clamp
70
+ - **Invariant:** The question "what is under the body" is asked at the position the body ends up in, after every clamp and constraint.
71
+ - **Technique:** Resolve bounds and constraints first, then query support at the final position. Test every edge of every walkable zone, not only interiors.
72
+ - **Reference configuration:** AW's player fell under its map at the play boundary because support was resolved before the boundary clamp; every interior-only sweep reported zero on the day a player filmed it.
73
+ - **Applies when:** Any game with play bounds, ledges or walkable zones.
74
+ - **Verify:** Walk the body into every perimeter at the worst frame time and check it ends at rest on a floor, not under one.
75
+
76
+ ### A fixed simulation step
77
+ - **Invariant:** Simulation advances in fixed steps, independent of render rate, with bounded catch-up after a hitch or a hidden tab.
78
+ - **Technique:** An accumulator that runs whole fixed steps and interpolates the render, a cap on steps per frame, and a fresh time baseline after pause or visibility changes.
79
+ - **Reference configuration:** 1/60 s steps in DK, MC and AW; AW clamps a frame to 0.05 s before integrating.
80
+ - **Applies when:** Every game with physics or movement.
81
+ - **Verify:** Run the same input recording at 30, 60 and 144 fps; the body ends in the same place.
82
+
83
+ ### Forgiving jumps
84
+ - **Invariant:** A jump pressed just before landing or just after walking off a ledge still happens.
85
+ - **Technique:** Coyote time after leaving the ground and a jump buffer before landing, both consumed in the simulation step that uses them, never in a render-only frame.
86
+ - **Reference configuration:** AW: coyote 0.12 s, jump buffer 0.16 s.
87
+ - **Applies when:** Games with jumping, platformers above all. Turn it off where precision is the challenge, and say so.
88
+ - **Verify:** Press jump a few frames late off a ledge and a few frames early before landing; both jump.
89
+
90
+ ### Ragdolls settle, then stop
91
+ - **Invariant:** A body that dies falls with weight, comes to rest on real geometry soon after, and does not spin, launch, shake or float.
92
+ - **Technique:** Play a directional death clip first and hand the body to physics near its end. Push the body out of any solid it starts in when the ragdoll activates. Cap and damp angular velocity per part, and check whether the physics engine reads angular velocity in world space or in the body's own frame before writing it. When motion stays under a threshold for a short time, freeze the pose and take the parts out of the solver. Judge the result on side-by-side video as well as spin numbers. In three.js with Rapier use `setAngvel`, `setAngularDamping`, `isSleeping()` and `sleep()`; cannon-es has `allowSleep`, `sleepSpeedLimit` and `angularDamping`.
93
+ - **Reference configuration:** OC cut corpse spin from 25.6 to 3.0 rad/s (R158), against a target of under 3 rad/s by 1.5 s and an 8 rad/s clamp, and cut knee swing-twist from 121 to 17 rad/s and elbow from 132 to 25 (R105 to R107). Its earlier spikes came from a world-space roll written to a body-frame input (limbs at 25.6 rad/s), cached joint impulses (the full rig failed after 13 steps on a flat floor, and held for 600 once reset) and a body that died buried in a solid (188.97 rad/s). OC's plan for the handover was the death clip first, physics for the last 0.15 s, ragdoll time per kill down from 3.8 s to 1.75 s. Raising corpse inertia 8 times improved the spin numbers, looked worse in a blind review, and was reverted. The owner raised spasming corpses about 8 times.
94
+ - **Applies when:** Any game with ragdolls or physics corpses.
95
+ - **Verify:** Kill enemies with each weapon class on flat ground, slopes, stairs and against walls. Log peak angular speed per part and the speed 1.5 s after death, and watch the clips beside the reference game.
96
+
97
+ ### Corpses retire on game-time deadlines
98
+ - **Invariant:** Every corpse and piece of debris leaves within a fixed game-time deadline, and the count of simulated bodies has a cap, whatever the solver does and at any frame rate.
99
+ - **Technique:** Drive corpse timers from the game clock, not from solver step counts. Sink or fade each corpse at its deadline and sweep any that remain. Cap active ragdolls and give far or excess kills a death clip only. Turn off corpse-against-corpse collision. A dead body stops counting as a target the frame it dies.
100
+ - **Reference configuration:** OC sinks corpses by 8 s and sweeps visible ones at 10 s (R183), caps ragdolls at 112 in total, and retires any past 8 active or 30 m away. Its rule after the fact: never tie corpse timers to solver step counts.
101
+ - **Applies when:** Any game that leaves bodies or debris, hordes above all.
102
+ - **Verify:** Run a 10-minute horde at the lowest frame rate the game supports (throttle the CPU) and count live corpses each second: each leaves by its deadline and the count stays under the cap.
103
+
104
+ ### Ray queries are budgeted by length and count
105
+ - **Invariant:** Each frame's ray and shape queries fit a budget, however many enemies there are and wherever the player looks.
106
+ - **Technique:** Clip every ray to the bounds of what it can hit and give it the shortest useful length. Query a broadphase or a bounding volume tree, against simple collider shapes rather than render meshes. Spread searches (camera placement, escape routes, cover) across frames, and back off after a failed search instead of repeating it every frame. Count queries per frame in the profiler. In three.js set `Raycaster.far` and use three-mesh-bvh (`computeBoundsTree`, `acceleratedRaycast`, `firstHitOnly`); Rapier's `castRay` takes a maximum time of impact.
107
+ - **Reference configuration:** OC cast about 670 rays a frame and got 100 to 540 ms frames until the rays were clipped to the collider bounds. Its 11,000-ray camera search ran spread over 16 frames. 88 bodies made 1,000 to 1,600 physics queries a frame.
108
+ - **Applies when:** Any game with aim rays, line of sight, camera collision or AI queries.
109
+ - **Verify:** Log query count and query time per frame through a full horde round and an ending. Aim at the sky, at the farthest wall and into a crowd: the worst frame stays inside the budget.
110
+
111
+ ## Further reading
112
+
113
+ How AW measured its controller, and what each of its checks missed:
114
+ [references/measured-failures.md](references/measured-failures.md).
@@ -0,0 +1,52 @@
1
+ # What AW's physics checks missed, and why
2
+
3
+ World at War (AW) built a headless gate for its maps after a player reported doors that
4
+ led into rock, z-fighting, floating geometry and walking through stairs. On the day that
5
+ gate first reported zero physics findings on all three maps, a player walked through a
6
+ staircase, ended up inside a floor and spawned inside a wall. Six mechanisms let it:
7
+
8
+ 1. **The grid asked a question the controller never asks.** Walkable cells were found
9
+ with a standing-clearance test the shipped controller does not use, so the grid's
10
+ idea of where a body could be was not the controller's.
11
+ 2. **"Feet inside solid" tested a point at the ankles.** A wall through the shoulder, a
12
+ sill through the chest and a slab through the head were all invisible. Testing a
13
+ circle of the body's radius over its whole height found 25 bad spawns on one map, 16
14
+ on another and 5 on a third, where the point test had found none.
15
+ 3. **An exemption was unconditional.** Bullet-only volumes inside a ramp's footprint were
16
+ exempt at any height, which hid a solid block of ground. The rule now asks what the
17
+ body is inside, not where it is standing.
18
+ 4. **Nothing swept.** A grid samples positions; a body that moves fast enough is never
19
+ sampled inside the thin thing it passes through.
20
+ 5. **Published floor levels were never asked whether a body fits on them.**
21
+ 6. **The edge was excluded by construction.** Interior sweeps refuse columns near a lip,
22
+ because stepping off a lip is allowed. Every fall-through a player suffered
23
+ was at exactly those columns.
24
+
25
+ What replaced it: **geometry proposes, the shipped controller disposes.** Flood each map
26
+ with a capsule from its spawn points using the controller's own traversal rules,
27
+ standing then crouched, to get the set of places a body can be. Then press keys on the
28
+ real player controller at that set's frontier (jump, mantle, ladder, slide, crouch) and
29
+ drive its movement function at the game's worst frame time and at 60 Hz.
30
+
31
+ ## Two rules worth taking from it
32
+
33
+ - **A zero and an unexercised check print the same number.** Report how many things each
34
+ check examined, report an arm with no subjects as a failure, and say when a staircase
35
+ offered no drivable start.
36
+ - **Replaying stored findings is a smoke test, not a fix rate.** After a solver change,
37
+ AW replayed 344 stored findings and read 185 as gone; a fresh measurement found 165 of
38
+ those 185 still present at the same place. A solver change perturbs the path, and a
39
+ map edit renumbers parts, so a stored position no longer arrives where it did. Measure
40
+ fresh on both sides of every before and after.
41
+
42
+ ## Tolerances AW settled on
43
+
44
+ | Name | Value | Why |
45
+ | --- | --- | --- |
46
+ | Grid cell | 0.5 m | A body is 0.70 m across, so nothing body-sized hides between samples |
47
+ | Floor agreement | 0.15 m | One riser is about 0.10 m; more than this and the gap shows |
48
+ | On a ramp | one step, 0.42 m | A drawn tread and a straight ramp differ by up to a riser |
49
+ | Doorway width | 0.60 to 3.20 m | Narrower is a crack, wider is a missing wall |
50
+ | Headroom | 1.80 m | The body's height |
51
+ | Ladder landing | 0.20 m | A landing you step onto, not one you fall to |
52
+ | Settle time at an edge | 1.5 s | A body walking off a terrace slides for over a second |
package/package.json CHANGED
@@ -1,6 +1,40 @@
1
1
  {
2
2
  "name": "@opengamehq/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.0",
4
+ "description": "Deploy browser games to OpenGame from the command line.",
5
+ "keywords": [
6
+ "opengame",
7
+ "cli",
8
+ "deploy",
9
+ "browser-games",
10
+ "game-development",
11
+ "webgl",
12
+ "webassembly"
13
+ ],
14
+ "homepage": "https://docs.opengame.io",
15
+ "bugs": {
16
+ "url": "https://github.com/opengamehq/opengame/issues"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/opengamehq/opengame.git",
21
+ "directory": "packages/cli"
22
+ },
23
+ "license": "Apache-2.0",
24
+ "type": "module",
25
+ "bin": {
26
+ "opengame": "dist/cli.mjs"
27
+ },
28
+ "engines": {
29
+ "node": ">=18.17"
30
+ },
31
+ "files": [
32
+ "dist",
33
+ "README.md",
34
+ "AGENTS.md",
35
+ "CHANGELOG.md"
36
+ ],
37
+ "publishConfig": {
38
+ "access": "public"
39
+ }
40
+ }