castle-web-cli 0.4.230 → 0.4.231

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 (69) hide show
  1. package/dist/castle-host/host.js +81 -0
  2. package/dist/devSaveStorage.d.ts +36 -0
  3. package/dist/devSaveStorage.js +469 -0
  4. package/dist/devSessionChild.js +22 -12
  5. package/dist/devSessionServer.js +8 -2
  6. package/dist/devSessionStorage.d.ts +9 -0
  7. package/dist/devSessionStorage.js +66 -1
  8. package/dist/init.js +1 -1
  9. package/dist/serve.js +5 -1
  10. package/kits/base/castle.json +1 -1
  11. package/kits/base/sdk/README.md +148 -1
  12. package/kits/base/sdk/castle.d.ts +4 -0
  13. package/kits/base/sdk/castle.js +2 -0
  14. package/kits/base/sdk/commands.d.ts +15 -0
  15. package/kits/base/sdk/multiplayer.js +52 -4
  16. package/kits/base/sdk/save.d.ts +197 -0
  17. package/kits/base/sdk/save.js +525 -0
  18. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  19. package/kits/base/sdk/saveCoordinator.js +252 -0
  20. package/kits/base/sdk/server/storage.d.ts +3 -2
  21. package/kits/base/sdk/server/storage.js +25 -5
  22. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  23. package/kits/base/sdk/server/wrapper.js +2 -0
  24. package/kits/base/sdk/store.d.ts +3 -2
  25. package/kits/base/sdk/store.js +5 -0
  26. package/kits/hub-game/CLAUDE.md +4 -1
  27. package/kits/hub-game/code/client/chrome.js +43 -9
  28. package/kits/hub-game/code/client/grab.js +142 -7
  29. package/kits/hub-game/code/client/hookLayer.js +7 -1
  30. package/kits/hub-game/code/client/state.js +13 -1
  31. package/kits/hub-game/code/client/talk.js +10 -36
  32. package/kits/hub-game/code/client/tiers.js +480 -0
  33. package/kits/hub-game/code/client/together.js +78 -3
  34. package/kits/hub-game/code/server/grab.js +3 -2
  35. package/kits/hub-game/code/server/hub.js +99 -5
  36. package/kits/hub-game/code/server/manifest.js +34 -7
  37. package/kits/hub-game/code/server/npcs.js +21 -33
  38. package/kits/hub-game/code/server/party.js +64 -6
  39. package/kits/hub-game/code/systems/hub.js +133 -16
  40. package/kits/hub-game/docs/contract.md +84 -14
  41. package/kits/hub-game/package.json +1 -1
  42. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  43. package/kits/hub-game/scripts/test-hub-trip.mjs +208 -0
  44. package/kits/hub-game/scripts/test-manifest.mjs +47 -1
  45. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  46. package/kits/hub-game/scripts/test-party.mjs +87 -4
  47. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  48. package/kits/hub-game/scripts/test-together.mjs +33 -1
  49. package/kits/physics-2d/CLAUDE.md +2 -0
  50. package/kits/physics-2d/castle.json +2 -2
  51. package/kits/physics-2d/engine/scene.js +92 -0
  52. package/kits/physics-2d/package.json +1 -1
  53. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  54. package/kits/physics-3d/CLAUDE.md +279 -0
  55. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  56. package/kits/physics-3d/castle.json +3 -3
  57. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +1 -1
  58. package/kits/physics-3d/engine3d/actornode.js +253 -0
  59. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  60. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  61. package/kits/physics-3d/engine3d/world3d.js +465 -7
  62. package/kits/physics-3d/package.json +1 -1
  63. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  64. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  65. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  66. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  67. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  68. package/kits/physics-3d/systems/physics3d.js +182 -3
  69. package/package.json +1 -1
@@ -58,6 +58,285 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
58
58
  or stood on: whatever is not on an actor falls (pits, lava, sky islands).
59
59
  `Shape.artRepeat: [u, v]` tiles a texture across a
60
60
  face so long walls don't stretch.
61
+ - `"engine": { "skipUnchangedActors": true }` at the scene file's top level,
62
+ beside `ground`, asks the engine not to redo, every frame, work whose answer
63
+ cannot have changed. The terms:
64
+ > With the key absent, a scene runs the engine exactly as before. With the key
65
+ > present, each frame equals what the engine would have produced without it
66
+ > PROVIDED the scene's components are plain stored data (no accessors, Proxies,
67
+ > toJSON, custom iterators) and three.js objects under actors are changed only
68
+ > through position/rotation/quaternion/scale/visible/parenting. A scene that does
69
+ > not meet that is unsupported under the key and must not set it.
70
+
71
+ It is read when the scene loads, so it follows a scene switch, and a mounted
72
+ pack's scene decides for itself. What is skipped for an actor nothing has
73
+ touched: building the signatures that decide whether its mesh and its
74
+ physics body need rebuilding, recomputing its node's matrices, and sorting
75
+ the actor list. Behaviors run exactly as without the key. Each skipped piece
76
+ is skipped only after reading its inputs and finding them as they were, so
77
+ nothing has to be marked dirty: an actor still follows a change on the very
78
+ next frame -- a component's stored field written in place, a component
79
+ added, removed or replaced, a spawn or despawn, physics, the editor, the
80
+ network, its node posed from `scene.three`. Opt in when a scene is several
81
+ hundred actors that mostly stand still and frame time on a slow phone is
82
+ script, not drawing; a small scene gains nothing.
83
+ How it stays right when deck code runs in the middle of the engine's own
84
+ work (`engine3d/world3d.js` has the rule and the code):
85
+ > Fast-path state (snapshots, pass marks, cached signatures) is trusted only
86
+ > across a span in which no code outside the engine has run. A pass in which
87
+ > the engine calls out (any callback), is re-entered, or sees the scene
88
+ > change, finishes exactly as main would and leaves no fast-path state
89
+ > behind.
90
+
91
+ The engine moves a counter before it does anything, inside a pass over the
92
+ actors, that can run code that is not its own; it does not work out
93
+ afterwards whether something ran. The places, all of them:
94
+ `scene.three.scene.userData.groundHeight`, called while a walking model is
95
+ animated; and three.js listeners (`added`, `removed`, `childadded`,
96
+ `childremoved`, `dispose`) on the scene, a node, a geometry or a material,
97
+ told when a node is built, rebuilt or released, when the scene changes, when
98
+ the ground is dressed anew, and when an instanced mesh is replaced; and
99
+ `syncActors` called again from inside any of those. From that point the
100
+ pass does each actor the old way and writes nothing down, and when it ends,
101
+ or if it throws, everything written down before is dropped. So:
102
+ - a frame in which any actor's mesh is built, rebuilt or released costs what
103
+ it costs without the key, and the frame after it reads every actor once
104
+ more before skipping resumes;
105
+ - a scene with a `groundHeight` callback, or with `instanceModels` on, runs
106
+ every pass the old way and keeps only the matrix saving;
107
+ - the physics pass calls nothing outside the engine until its collision
108
+ callbacks, which come last;
109
+ - a component nested more than 32 levels deep is compared the old way every
110
+ frame.
111
+
112
+ What is written down lives in the world's own maps (`world.snapshots`,
113
+ `world.modelSigs`) and in the physics system's (`remembered`), never on a
114
+ node entry or a body entry, and is dropped by replacing or clearing those.
115
+ The one thing on a node, an ActorNode's `computedFrom`, is numbers only and
116
+ refers to no object.
117
+ A world being disposed never skips: `disposeWorld` drops what was written
118
+ down before it releases the nodes and again after their `dispose` listeners
119
+ have run, so a listener that syncs the world again leaves nothing.
120
+ - Within the terms, these are followed: any stored field of a Shape, Model,
121
+ Body or Transform changed, added, removed or reordered, at any depth; art
122
+ loading or being replaced; a model file, or a model it references, edited;
123
+ a node's, or any object under it's, position, rotation (angles or order),
124
+ quaternion, scale or visibility set; children added, removed, reordered,
125
+ or moved to another parent and back; a body's type changed through
126
+ `scene.physics3d.bodyOf`.
127
+ - Outside the terms the result is not promised. The engine does notice some
128
+ of it and then does the old work for that actor, as protection, not as a
129
+ guarantee to build on: a component with an accessor, a `toJSON` or a class
130
+ of its own found when it is first read; an object under a node with
131
+ `matrixAutoUpdate` off or an `updateMatrixWorld` of its own (a camera, a
132
+ skinned mesh); a world matrix written by hand; a transform changed, used
133
+ and put back between frames.
134
+ - It does not notice, among others: a `Proxy` in place of a component, of
135
+ `actor.components` or of the `sprites` / `files` tables; a getter on
136
+ `Transform`, on `Shape.solid`, or on `actor.components` itself; a stored
137
+ field redefined as a getter after the engine has read it; an object's
138
+ local `matrix` written by hand while its `matrixAutoUpdate` is on (set
139
+ `position` / `quaternion` / `scale` instead); three.js private fields
140
+ written directly (`rotation._order`, `quaternion._x`).
141
+ - `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
142
+ (the same `engine` object) asks the engine to draw the sun's shadows where
143
+ they can be seen, near the camera, rather than in the sun's fixed box.
144
+ Without it the sun's shadow camera is a fixed 150 x 120 m box round the
145
+ origin, so every caster under the box is drawn a second time each frame
146
+ wherever the player stands, and a scene larger than the box has no shadows
147
+ outside it. The terms:
148
+ > With the key absent, a scene is drawn exactly as before: the same shadow
149
+ > camera, map, `castShadow` flags and render calls. On a frame the mode
150
+ > draws, everything the camera sees within `distance` metres (measured along
151
+ > the way it looks) is shadowed as it would be under a box that covered it,
152
+ > with texels exactly the size the sun's own are and the same softness and
153
+ > bias. Shadows are complete out to `distance` for casters inside the depth
154
+ > range below; a point farther off may or may not be shadowed, and nothing
155
+ > cuts shadows off there.
156
+
157
+ The depth range is the sun's own `near` and `far` along the light, measured
158
+ from the engine's shadow camera, which stands as far from the middle of the
159
+ view's sphere (taken along the light to the height of the sun's target) as
160
+ the sun does from its target. For the engine's sun (19.9 m from its target,
161
+ near 0.5, far 50) that is casters up to 19.4 m toward the sun and 30.1 m
162
+ away from it, from the ground under the middle of the view. It is what the
163
+ sun's own camera draws for a view round its target: there too a caster 25 m
164
+ up the light from a point on the ground is not drawn.
165
+
166
+ How it stays out of the scene's way (`engine3d/nearshadows.js` has the rule
167
+ and the code):
168
+ > The scene's sun, its shadow object, its shadow camera, its map and its
169
+ > target are never written by this mode. What the mode needs is its own
170
+ > objects, attached only for the duration of one renderer.render call
171
+ > inside try/finally. Outside that call the world is as main leaves it, so
172
+ > there is nothing to restore on a scene change, a throw, a dispose or a
173
+ > keyless frame.
174
+
175
+ Who the key is for:
176
+ > The key is for a scene whose deck leaves the renderer's shadow settings
177
+ > and the drawing of the world to the engine. A deck must not set the key if
178
+ > any of its code, in any scene played in the same world, changes
179
+ > renderer.shadowMap.type, .enabled, .autoUpdate or .needsUpdate after the
180
+ > world is made; calls renderer.render or the composer itself, inside or
181
+ > between the engine's frames; calls renderWorld from inside a frame; or
182
+ > gives the world's renderer to another world. In a deck that does, shadows
183
+ > may be drawn wrongly with the key, and three.js's shadow bookkeeping for
184
+ > the sun's own map (its filter, its size) may differ from a world that
185
+ > never had the key until the world is disposed. A deck that never sets the
186
+ > key is unaffected whatever it does.
187
+
188
+ (three.js keeps the shadow pass's state, the type it last drew with and the
189
+ frustum it culls by, inside the renderer, where the engine can neither read
190
+ it nor put it back. Nothing in the kits does any of the above after
191
+ `makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
192
+
193
+ Within that, the mode draws a frame only when all of these hold; otherwise
194
+ the frame is drawn exactly as without the key. They are cheap protection,
195
+ looked at every frame, not promises about a deck outside the condition
196
+ above. After any `renderWorld` call returns, either the mode drew that
197
+ frame or nothing of the mode's is allocated: every way out of the mode (a
198
+ frame drawn plain for any term, a re-entry, a throw, a dispose) frees its
199
+ map at that moment:
200
+ 1. the scene now playing asked, with a finite distance above 0
201
+ (`runtime.nearShadowDistance`, read when the scene loads), the frame is
202
+ the player's (the scene and model editors give `renderWorld` no runtime),
203
+ and the world is not being disposed;
204
+ 2. `renderWorld` was not entered from inside another `renderWorld` of this
205
+ world that had anything of the mode's to do, keyed or not, and no frame
206
+ of this world has been entered that way before. The call inside is drawn
207
+ plain; the sun has its own shadow back before that call draws, and still
208
+ has it when the call returns, whatever the call did, disposing the world
209
+ included; the mode is off for this world from then until the world is
210
+ disposed (`world.nearShadows.off`); and the frame that was re-entered,
211
+ whose map is freed under it, may have wrong or missing shadows, that
212
+ once;
213
+ 3. read at the start of the frame, `renderer.shadowMap.type` is
214
+ `PCFSoftShadowMap` and `.enabled` and `.autoUpdate` are on, which is how
215
+ the engine makes the renderer; and the frame before was also a frame
216
+ with the key that found the same and was drawn to the end
217
+ (`world.nearShadows.lastType`). So the first frame with the key, after a
218
+ load or after any frame without it, is drawn plain, and three.js
219
+ allocates and configures the sun's own map as it would have; and so is
220
+ the frame after one that threw, and after one the mode drew that ended
221
+ with no map on the engine's shadow (three.js drew nothing: a lost
222
+ context). The engine's shadow never has a blur map;
223
+ 4. the sun (`world.sun`, the light whose bias the engine fits) is still a
224
+ child of the scene, is the first directional light there that casts, has
225
+ `castShadow` on, is visible and on the camera's layers, and its own
226
+ shadow is a directional light's, has `autoUpdate` on and has its map.
227
+ Looked at every frame: a sun removed or replaced means plain frames, in
228
+ which a replacement draws its own box as without the key;
229
+ 5. the camera is a perspective camera, and the sun's own box and map size
230
+ give a texel size: its shadow camera has zoom 1 and no view offset.
231
+
232
+ All of the mode's work in a `renderWorld` call (deciding the terms, fitting
233
+ the bias, allocating, swapping, rendering, leaving, disposing) happens
234
+ inside one outermost try/finally, counted on the world
235
+ (`world.nearShadows.depth`). A call that arrives while the count is up
236
+ draws plain, puts the mode off and makes nothing. The finally establishes
237
+ the postcondition itself: unless the mode drew this frame to the end, on a
238
+ world not disposed, with the mode not off and a map on its shadow, nothing
239
+ of the mode's is allocated and the sun has its own shadow. Its order is
240
+ what makes that hold through a `dispose` listener that throws: first the
241
+ sun gets its own shadow back (an assignment, which calls no one), then what
242
+ is freed is detached and only then disposed, and looked at again after the
243
+ callbacks; the count comes down in a finally of its own that nothing skips.
244
+ A world with no mode state playing a scene without the key does not enter
245
+ any of it: `renderWorld` runs its two statements (fit the bias, render)
246
+ with no counter and no try, as it always did.
247
+
248
+ On such a frame `renderWorld` fits the bias of the sun's own shadow as
249
+ always, puts the engine's shadow on the sun (`sun.shadow`), renders, and
250
+ puts the sun's own back in a `finally`; that assignment is the only write,
251
+ and it is undone only by the frame that made it (a frame that finds the
252
+ world disposed, its state replaced or itself re-entered touches nothing).
253
+ three.js keeps nothing per shadow object (the shadow pass and the light
254
+ uniforms read `light.shadow` afresh every render), so the next plain render
255
+ reads the sun's own as if nothing had happened. The engine's shadow
256
+ (`world.nearShadows.shadow`, a DirectionalLightShadow with its own camera,
257
+ map, matrix and frustum), each frame:
258
+ - looks along the sun's direction, from as far as the sun is from its
259
+ target, with the sun's own near and far, round the smallest sphere that
260
+ holds the camera's view out to `distance`: one size whichever way the
261
+ camera turns (it changes only with the canvas's shape or the camera's
262
+ lens). It sits a whole number of texels along each of its axes, so a
263
+ shadow's edge does not crawl as the camera moves. The light does not move;
264
+ - has texels exactly the size of the sun's own (the sun's box over its map
265
+ size, read each frame), so its box is `map size x texel` and it copies the
266
+ bias `fitShadowBias` fitted to the sun's own, with its intensity and
267
+ radius: 40 m on a portrait phone is a 710 x 888 map. Its map is never
268
+ larger than the sun's own in area (2048 x 2048) nor than the renderer's
269
+ largest texture on a side; a `distance` that would need more is drawn as
270
+ the largest that fits (about 100 m in portrait, 38 m at 32:9) rather than
271
+ with larger texels;
272
+ - hands three.js a frustum to cull casters with (`getFrustum`) that is its
273
+ box narrowed to the view's outline, out to `distance`, as the sun sees it,
274
+ pushed out by everything three.js's shader moves a shadow lookup by across
275
+ the light: the normal bias drawn with that frame (the lookup is made at
276
+ `position + normal * normalBias`) and four texels for the soft filter's
277
+ taps. The box is wider by the same. Every caster whose shadow
278
+ can land on something the view sees within `distance` is drawn into the
279
+ map; one whose shadow cannot is not. No `castShadow` flag is changed and
280
+ nothing is cached: every caster that is drawn is drawn every frame, so a
281
+ moving thing's shadow moves with it as before.
282
+
283
+ A frame without the key drops what the mode holds, all but `off`;
284
+ `disposeWorld` drops it all. The engine's map (and a blur map, were there
285
+ one) is taken off its shadow before it is disposed, once.
286
+
287
+ What a deck that works on the sun sees under the key: the sun's own
288
+ `shadow.camera` box, `mapSize` and any `getFrustum` of its own are left as
289
+ they are and not used for drawing on the frames the mode draws (a sun whose
290
+ `shadow.autoUpdate` the deck turned off gets plain frames, term 4),
291
+ except that the box over the map size gives the texel size and `near`/`far`,
292
+ `bias`, `normalBias`, `intensity` and `radius` are copied each frame;
293
+ three.js does not draw the sun's own shadow on those frames, so its map and
294
+ its shadow camera's matrices stay as the last plain frame left them; a sun
295
+ moved or re-aimed is followed (its direction is read each frame). Without
296
+ the key such a deck works exactly as before. What differs on screen with
297
+ the key: shadows no longer end at the fixed box's edge, so a scene larger
298
+ than that box gains shadows where it had none; beyond `distance` from the
299
+ camera they thin out and, past the engine's box (which reaches somewhat
300
+ farther than `distance`), end, with a hard edge if the camera can see that
301
+ far (pick a distance past the ground the camera can see). Opt in when a
302
+ scene is wide enough that most of its casters are out of sight; a scene
303
+ that fits the view gains nothing.
304
+ - `"engine": { "camera": { "follow": "rigid" } }` at the scene file's top
305
+ level (the same `engine` object) asks the `Player` behavior for a follow
306
+ camera that moves with the player instead of easing after it. Without it
307
+ the camera eases its whole position toward its place behind the player, so
308
+ how far it trails a walking player depends on how long each frame is: on
309
+ frames of uneven length (a page missing every other vsync) the distance
310
+ changes every frame and the view judders, which reads as an up-and-down
311
+ shake walking forward, since the camera looks down. The terms:
312
+ > With the key absent, the camera is placed exactly as before: the same
313
+ > code, in the same place in the frame. With the key present, the camera's
314
+ > offset from the player (its angle and height) and the player's height are
315
+ > eased at the rate the old camera eases, with an easing that trails a
316
+ > steadily moving target by the same distance however the frames are cut;
317
+ > the player's ground position is not eased. So a steady walk leaves the
318
+ > player at one place on screen, a turn swings the camera round as before,
319
+ > and a jump lifts the player on screen while the camera follows smoothly.
320
+ > A teleport (more than 3 m in a frame, or the camera more than 20 m off)
321
+ > still snaps it, and it still looks at the player.
322
+
323
+ Where it is placed: behaviors run before physics, so the Player sees the
324
+ position the last frame drew. Under the key it asks for its camera instead
325
+ (`scene.followCamera`: its actor id and the scene data it asked in), every
326
+ frame, whether physics is ready or not, and the physics system places it
327
+ last in its `afterBehaviors`, after this frame's positions are written back
328
+ and the collision callbacks have run, on the position the frame is drawn
329
+ with; on a frame physics cannot step (rapier still loading, or the first
330
+ frame after a load) it is placed all the same. The player is looked up as
331
+ the scene has it then: one a callback despawned gets no camera, and a
332
+ request made before a load is not used after it (a load and a dispose drop
333
+ it). Systems registered after physics (the hub's) see the camera already
334
+ placed. The offset is read each frame from where the camera is, against
335
+ the point it followed the frame before, so a camera something else placed
336
+ (a hub trip's camera, a cutscene) is eased on from wherever it was put.
337
+ The play panel and a published deck play the scene through the same
338
+ runtime, so both follow the scene's key; the scene editor's own orbit
339
+ camera is not a follow camera and is not affected.
61
340
  - `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
62
341
  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
63
342
  stage to place), orbit camera (drag orbits, wheel zooms), click to select /
@@ -96,6 +96,76 @@ function updateCamera(scene, t, rt, props, dt) {
96
96
  cam.lookAt(t.x, t.y + 0.5, t.z);
97
97
  }
98
98
 
99
+ // How fast the rigid follow camera's offset and height catch up: the rate of
100
+ // updateCamera's lerp, so an orbit (Q/E, or turning) swings as it does there.
101
+ const FOLLOW_RATE = 12;
102
+
103
+ // One frame of `x' = FOLLOW_RATE * (target - x)` for a target that moved from
104
+ // `from` to `to` at a steady rate over the frame, solved exactly. A target that
105
+ // moves steadily is trailed by the same distance however the frames are cut,
106
+ // and one that stands still is reached as updateCamera's lerp reaches it.
107
+ function settle(value, from, to, dt) {
108
+ if (!(dt > 0)) return value;
109
+ const lag = (to - from) / (dt * FOLLOW_RATE);
110
+ return to - lag + (value - from + lag) * Math.exp(-FOLLOW_RATE * dt);
111
+ }
112
+
113
+ // The follow camera of a scene that set `"engine": { "camera": { "follow":
114
+ // "rigid" } }` (the kit's CLAUDE.md has the terms). It moves with the player
115
+ // as one piece: the offset from the player (its angle and height) and the
116
+ // player's height are eased, the player's ground position is not, so a steady
117
+ // walk leaves the player at one place on screen whatever the frame lengths.
118
+ // It is placed at the end of the frame (`placeFollowing`), on the position the
119
+ // frame is drawn with.
120
+ function followRigidly(scene, t, per, rt, props, dt) {
121
+ const cam = scene.three?.camera;
122
+ if (!cam) return;
123
+ const ox = -props.camDistance * Math.sin(per.camAngle);
124
+ const oy = props.camHeight;
125
+ const oz = props.camDistance * Math.cos(per.camAngle);
126
+ const last = per.camLastAt;
127
+ const jumped = last && Math.hypot(t.x - last.x, t.z - last.z) > TELEPORT_PER_FRAME;
128
+ per.camLastAt = { x: t.x, z: t.z };
129
+ // The offset is read each frame from where the camera is, against the
130
+ // point it followed last frame, so a camera something else moved since (a
131
+ // trip's camera, a cutscene) is eased on from where it was left.
132
+ const at = cam.position;
133
+ const f = (rt.camFollow ??= { from: { x: t.x, y: t.y, z: t.z }, to: null });
134
+ let x = at.x - f.from.x;
135
+ let y = at.y - f.from.y;
136
+ let z = at.z - f.from.z;
137
+ let height = f.from.y;
138
+ const to = f.to ?? { x: ox, y: oy, z: oz, height: t.y };
139
+ if (jumped || Math.hypot(t.x + ox - at.x, t.z + oz - at.z) > 20) {
140
+ [x, y, z, height] = [ox, oy, oz, t.y];
141
+ } else {
142
+ x = settle(x, to.x, ox, dt);
143
+ y = settle(y, to.y, oy, dt);
144
+ z = settle(z, to.z, oz, dt);
145
+ height = settle(height, to.height, t.y, dt);
146
+ }
147
+ f.to = { x: ox, y: oy, z: oz, height: t.y };
148
+ f.from = { x: t.x, y: height, z: t.z };
149
+ cam.position.set(t.x + x, height + y, t.z + z);
150
+ cam.lookAt(t.x, t.y + 0.5, t.z);
151
+ }
152
+
153
+ // Under the key, Player.update asks for its camera by the actor's id and the
154
+ // scene data it was made for (`scene.followCamera`), every frame, physics
155
+ // ready or not; the physics system calls this at the end of the frame, after
156
+ // it has written this frame's positions back (or at once, when it could not
157
+ // step), if the same scene is still loaded. The player is looked up as the
158
+ // scene has it then: one despawned or turned off since gets no camera.
159
+ function placeFollowing(scene, id, dt) {
160
+ const actor = scene.getActor(id);
161
+ const t = actor?.components.Transform;
162
+ const props = actor?.components.Player;
163
+ if (!t || !props || props.$enabled === false) return;
164
+ const per = (scene.persistent ??= {});
165
+ if (per.camAngle === undefined) per.camAngle = Math.PI / 4;
166
+ followRigidly(scene, t, per, actor.runtime, props, dt);
167
+ }
168
+
99
169
  // The nearest Lookable the player is facing, within its range.
100
170
  function findLookText(scene, actor, t, facing) {
101
171
  const fx = Math.sin(facing);
@@ -134,6 +204,9 @@ export class Player {
134
204
  }
135
205
 
136
206
  update(actor, scene, dt) {
207
+ if (scene.cameraFollowsRigidly === true) {
208
+ scene.followCamera = { id: actor.id, data: scene.data, dt, place: placeFollowing };
209
+ }
137
210
  const phys = scene.physics3d;
138
211
  if (!phys?.ready()) return;
139
212
  const t = actor.components.Transform;
@@ -178,7 +251,7 @@ export class Player {
178
251
  if (vel.y < 1) phys.applyImpulse(actor, { x: 0, y: -14 * phys.mass(actor) * dt, z: 0 });
179
252
  }
180
253
 
181
- updateCamera(scene, t, per, this.props, dt);
254
+ if (scene.cameraFollowsRigidly !== true) updateCamera(scene, t, per, this.props, dt);
182
255
  const remaining = scene.actorsWith('Pickup').length;
183
256
  const total = per.score + remaining;
184
257
  const score =
@@ -50,16 +50,16 @@
50
50
  "imports": {
51
51
  "castle.physics-2d": {
52
52
  "deckId": "ckRZGFW4iPrx",
53
- "version": "2026-10-03T04:25:18.207Z"
53
+ "version": "2026-10-04T22:43:17.146Z"
54
54
  },
55
55
  "castle.base": {
56
56
  "deckId": "yRcmH4_aYllE",
57
- "version": "2026-10-03T08:41:46.002Z"
57
+ "version": "2026-10-04T22:42:38.248Z"
58
58
  }
59
59
  },
60
60
  "main": "main.jsx",
61
61
  "autoUpdateWhenImported": true,
62
62
  "deckId": "JH0SclbPVP0y",
63
63
  "cardId": "eXfAaUdbSU5A",
64
- "publishedVersion": "2026-10-03T09:17:32.572Z"
64
+ "publishedVersion": "2026-10-04T22:44:03.895Z"
65
65
  }
@@ -214,7 +214,7 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
214
214
  }
215
215
  syncActors(world, runtime, runtime.sprites ?? sprites, dt);
216
216
  if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());
217
- renderWorld(world);
217
+ renderWorld(world, runtime);
218
218
  updateHud(runtime, hudRefs);
219
219
  } catch (err) {
220
220
  onError?.(err);
@@ -0,0 +1,253 @@
1
+ // The terms of `"engine": { "skipUnchangedActors": true }`:
2
+ //
3
+ // With the key absent, a scene runs the engine exactly as before. With the key
4
+ // present, each frame equals what the engine would have produced without it
5
+ // PROVIDED the scene's components are plain stored data (no accessors, Proxies,
6
+ // toJSON, custom iterators) and three.js objects under actors are changed only
7
+ // through position/rotation/quaternion/scale/visible/parenting. A scene that does
8
+ // not meet that is unsupported under the key and must not set it.
9
+ //
10
+ // The three.js group an actor is drawn under in a scene that set
11
+ // `"engine": { "skipUnchangedActors": true }`. It is a THREE.Group whose
12
+ // `updateMatrixWorld` does nothing when doing it would change nothing.
13
+ //
14
+ // three.js recomputes the local and the world matrix of every object under
15
+ // the scene on every render, whether or not anything moved. For a scene of
16
+ // several hundred actors that stand still that is most of a frame's script
17
+ // time. An ActorNode remembers, as numbers, what its subtree's matrices were
18
+ // last computed from and what they came out as: its parent's id and world
19
+ // matrix, the ids of the objects under it in order, each one's position,
20
+ // quaternion and scale, and each one's world matrix. While all of that reads
21
+ // the same, the matrices three.js would compute are the ones already there,
22
+ // so the walk is skipped. The moment any of it differs, by anyone's hand,
23
+ // three.js's own `updateMatrixWorld` runs for the whole subtree, exactly as it
24
+ // always did. That covers a world matrix written directly, a child moved to
25
+ // another parent and back between two renders, and a transform changed, used
26
+ // and put back: each leaves a matrix that is not the remembered one.
27
+ //
28
+ // Nothing about the objects is changed: `matrixAutoUpdate` stays on, so every
29
+ // other three.js path (`updateWorldMatrix`, a clone, a child moved under
30
+ // another parent) behaves as it does under a plain Group. A subtree holding
31
+ // anything that manages its own matrices (`matrixAutoUpdate` or
32
+ // `matrixWorldAutoUpdate` off, an `updateMatrix` or `updateMatrixWorld` of its
33
+ // own such as a camera's or a skinned mesh's, an object of another copy of
34
+ // three.js) is never skipped.
35
+ //
36
+ // `skipping` is the world's `{ on }`, shared by every node of the world: while
37
+ // it is off (the scene now playing did not ask), a node left from a scene
38
+ // that did is a plain Group again, after one test, and drops its record.
39
+ import * as THREE from 'three';
40
+
41
+ const baseUpdateMatrix = THREE.Object3D.prototype.updateMatrix;
42
+ const baseUpdateMatrixWorld = THREE.Object3D.prototype.updateMatrixWorld;
43
+
44
+ // Numbers remembered per object: position, quaternion and scale, then the
45
+ // local matrix and the world matrix they came out as.
46
+ const INPUTS = 10;
47
+ const STRIDE = INPUTS + 16;
48
+
49
+ const OFF = { on: false };
50
+ const NO_PARENT = -1;
51
+
52
+ export class ActorNode extends THREE.Group {
53
+ constructor(skipping = OFF) {
54
+ super();
55
+ this.skipping = skipping ?? OFF;
56
+ // What the subtree's matrices were last computed from, or null when they
57
+ // must be computed again whatever reads the same.
58
+ this.computedFrom = null;
59
+ }
60
+
61
+ updateMatrixWorld(force) {
62
+ // While the scene playing did not ask it is Group's method, after one
63
+ // test; a record left from a scene that did is dropped on the way.
64
+ if (!this.skipping.on) {
65
+ if (this.computedFrom !== null) this.computedFrom = null;
66
+ super.updateMatrixWorld(force);
67
+ return;
68
+ }
69
+ const from = this.computedFrom;
70
+ if (from !== null && unchanged(this, from)) {
71
+ return;
72
+ }
73
+ super.updateMatrixWorld(force);
74
+ this.computedFrom = remember(this, from);
75
+ }
76
+ }
77
+
78
+ // The record (`computedFrom`) holds numbers and nothing else: the parent's id
79
+ // and world matrix, and for each object of the subtree, in the order three.js
80
+ // walks it, its id, how many objects its own subtree has, and its position,
81
+ // quaternion, scale and world matrix. It refers to no object, so it can keep
82
+ // nothing alive, whoever holds the node and for however long.
83
+
84
+ // Where the walk below has got to in the record.
85
+ let at = 0;
86
+
87
+ // Whether three.js's walk of the subtree would leave every matrix as it is.
88
+ function unchanged(node, from) {
89
+ if (!sameParent(node.parent, from)) {
90
+ return false;
91
+ }
92
+ at = 0;
93
+ return sameSubtree(node, true, from) && at === from.ids.length;
94
+ }
95
+
96
+ // Whether `object` is the next object of the record, reads as recorded, and
97
+ // has under it exactly the subtree recorded for it.
98
+ function sameSubtree(object, isRoot, from) {
99
+ const index = at;
100
+ if (index >= from.ids.length || from.ids[index] !== object.id) {
101
+ return false;
102
+ }
103
+ if (
104
+ !computesItself(object, isRoot) ||
105
+ object.matrixWorldNeedsUpdate !== false ||
106
+ !sameNumbers(object, from.numbers, index * STRIDE)
107
+ ) {
108
+ return false;
109
+ }
110
+ at = index + 1;
111
+ const children = object.children;
112
+ for (let c = 0; c < children.length; c++) {
113
+ if (!sameSubtree(children[c], false, from)) {
114
+ return false;
115
+ }
116
+ }
117
+ return at === index + from.sizes[index];
118
+ }
119
+
120
+ function sameParent(parent, from) {
121
+ if ((parent === null ? NO_PARENT : parent.id) !== from.parentId) {
122
+ return false;
123
+ }
124
+ if (parent === null) {
125
+ return true;
126
+ }
127
+ const now = parent.matrixWorld.elements;
128
+ const was = from.parentWorld;
129
+ for (let i = 0; i < 16; i++) {
130
+ if (!Object.is(now[i], was[i])) {
131
+ return false;
132
+ }
133
+ }
134
+ return true;
135
+ }
136
+
137
+ // `Object.is`, not `===`: a matrix composed from -0 differs from one composed
138
+ // from 0 in the sign of its zeros, and the two must not pass for each other.
139
+ function sameNumbers(object, numbers, k) {
140
+ const p = object.position;
141
+ const q = object.quaternion;
142
+ const s = object.scale;
143
+ return (
144
+ sameMatrix(object.matrixWorld.elements, numbers, k + INPUTS) &&
145
+ Object.is(p.x, numbers[k]) &&
146
+ Object.is(p.y, numbers[k + 1]) &&
147
+ Object.is(p.z, numbers[k + 2]) &&
148
+ Object.is(q.x, numbers[k + 3]) &&
149
+ Object.is(q.y, numbers[k + 4]) &&
150
+ Object.is(q.z, numbers[k + 5]) &&
151
+ Object.is(q.w, numbers[k + 6]) &&
152
+ Object.is(s.x, numbers[k + 7]) &&
153
+ Object.is(s.y, numbers[k + 8]) &&
154
+ Object.is(s.z, numbers[k + 9])
155
+ );
156
+ }
157
+
158
+ // Whether the object's world matrix is still the one the last walk left.
159
+ function sameMatrix(world, numbers, k) {
160
+ for (let i = 0; i < 16; i++) {
161
+ if (!Object.is(world[i], numbers[k + i])) {
162
+ return false;
163
+ }
164
+ }
165
+ return true;
166
+ }
167
+
168
+ // An object whose matrices three.js's plain walk computes from its position,
169
+ // quaternion and scale, and nothing else.
170
+ function computesItself(object, isRoot) {
171
+ return (
172
+ object.matrixAutoUpdate === true &&
173
+ object.matrixWorldAutoUpdate === true &&
174
+ object.updateMatrix === baseUpdateMatrix &&
175
+ (isRoot || object.updateMatrixWorld === baseUpdateMatrixWorld)
176
+ );
177
+ }
178
+
179
+ function everyObjectComputesItself(object, isRoot) {
180
+ if (!computesItself(object, isRoot)) {
181
+ return false;
182
+ }
183
+ const children = object.children;
184
+ for (let i = 0; i < children.length; i++) {
185
+ if (!everyObjectComputesItself(children[i], false)) {
186
+ return false;
187
+ }
188
+ }
189
+ return true;
190
+ }
191
+
192
+ function countObjects(object) {
193
+ let count = 1;
194
+ const children = object.children;
195
+ for (let i = 0; i < children.length; i++) {
196
+ count += countObjects(children[i]);
197
+ }
198
+ return count;
199
+ }
200
+
201
+ // What the walk that just ran computed the subtree from. `from` is the last
202
+ // record; its arrays are written over when the subtree has as many objects as
203
+ // before, so an actor that moves every frame allocates nothing.
204
+ function remember(node, from) {
205
+ if (!everyObjectComputesItself(node, true)) {
206
+ return null;
207
+ }
208
+ const count = countObjects(node);
209
+ const record =
210
+ from !== null && from.ids.length === count
211
+ ? from
212
+ : {
213
+ parentId: NO_PARENT,
214
+ parentWorld: new Float64Array(16),
215
+ ids: new Int32Array(count),
216
+ sizes: new Int32Array(count),
217
+ numbers: new Float64Array(count * STRIDE),
218
+ };
219
+ record.parentId = node.parent === null ? NO_PARENT : node.parent.id;
220
+ if (node.parent !== null) {
221
+ record.parentWorld.set(node.parent.matrixWorld.elements);
222
+ }
223
+ at = 0;
224
+ write(node, record);
225
+ return record;
226
+ }
227
+
228
+ function write(object, record) {
229
+ const index = at;
230
+ at = index + 1;
231
+ const { numbers } = record;
232
+ const k = index * STRIDE;
233
+ const p = object.position;
234
+ const q = object.quaternion;
235
+ const s = object.scale;
236
+ record.ids[index] = object.id;
237
+ numbers[k] = p.x;
238
+ numbers[k + 1] = p.y;
239
+ numbers[k + 2] = p.z;
240
+ numbers[k + 3] = q.x;
241
+ numbers[k + 4] = q.y;
242
+ numbers[k + 5] = q.z;
243
+ numbers[k + 6] = q.w;
244
+ numbers[k + 7] = s.x;
245
+ numbers[k + 8] = s.y;
246
+ numbers[k + 9] = s.z;
247
+ numbers.set(object.matrixWorld.elements, k + INPUTS);
248
+ const children = object.children;
249
+ for (let c = 0; c < children.length; c++) {
250
+ write(children[c], record);
251
+ }
252
+ record.sizes[index] = at - index;
253
+ }