castle-web-cli 0.4.230 → 0.4.232

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 (92) 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/dist/serverBundle.js +5 -3
  11. package/kits/base/castle.json +1 -1
  12. package/kits/base/sdk/README.md +148 -1
  13. package/kits/base/sdk/castle.d.ts +4 -0
  14. package/kits/base/sdk/castle.js +2 -0
  15. package/kits/base/sdk/commands.d.ts +15 -0
  16. package/kits/base/sdk/multiplayer.js +52 -4
  17. package/kits/base/sdk/save.d.ts +197 -0
  18. package/kits/base/sdk/save.js +525 -0
  19. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  20. package/kits/base/sdk/saveCoordinator.js +252 -0
  21. package/kits/base/sdk/server/storage.d.ts +3 -2
  22. package/kits/base/sdk/server/storage.js +25 -5
  23. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  24. package/kits/base/sdk/server/wrapper.js +2 -0
  25. package/kits/base/sdk/store.d.ts +3 -2
  26. package/kits/base/sdk/store.js +5 -0
  27. package/kits/hub-game/CLAUDE.md +29 -4
  28. package/kits/hub-game/code/client/avatar.js +39 -0
  29. package/kits/hub-game/code/client/chat.js +12 -0
  30. package/kits/hub-game/code/client/chrome.js +237 -13
  31. package/kits/hub-game/code/client/grab.js +166 -7
  32. package/kits/hub-game/code/client/hats.js +26 -0
  33. package/kits/hub-game/code/client/hookLayer.js +36 -3
  34. package/kits/hub-game/code/client/hudClear.js +126 -0
  35. package/kits/hub-game/code/client/state.js +35 -1
  36. package/kits/hub-game/code/client/talk.js +10 -36
  37. package/kits/hub-game/code/client/tiers.js +505 -0
  38. package/kits/hub-game/code/client/together.js +144 -4
  39. package/kits/hub-game/code/client/wear.js +96 -14
  40. package/kits/hub-game/code/server/actors.js +5 -0
  41. package/kits/hub-game/code/server/grab.js +299 -13
  42. package/kits/hub-game/code/server/hub.js +162 -7
  43. package/kits/hub-game/code/server/manifest.js +80 -8
  44. package/kits/hub-game/code/server/npcs.js +21 -33
  45. package/kits/hub-game/code/server/party.js +75 -6
  46. package/kits/hub-game/code/server/say.js +8 -2
  47. package/kits/hub-game/code/server/wear.js +116 -11
  48. package/kits/hub-game/code/systems/hub.js +386 -21
  49. package/kits/hub-game/docs/contract.md +285 -19
  50. package/kits/hub-game/package.json +1 -1
  51. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  52. package/kits/hub-game/scripts/test-grab-client.mjs +511 -0
  53. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  54. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  55. package/kits/hub-game/scripts/test-hub-trip.mjs +721 -0
  56. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  57. package/kits/hub-game/scripts/test-manifest.mjs +122 -1
  58. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  59. package/kits/hub-game/scripts/test-party.mjs +108 -4
  60. package/kits/hub-game/scripts/test-say.mjs +59 -2
  61. package/kits/hub-game/scripts/test-tiers.mjs +854 -0
  62. package/kits/hub-game/scripts/test-together.mjs +33 -1
  63. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  64. package/kits/physics-2d/CLAUDE.md +2 -0
  65. package/kits/physics-2d/castle.json +2 -2
  66. package/kits/physics-2d/engine/scene.js +127 -0
  67. package/kits/physics-2d/package.json +1 -1
  68. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +298 -0
  69. package/kits/physics-3d/CLAUDE.md +531 -0
  70. package/kits/physics-3d/behaviors/Player.jsx +437 -3
  71. package/kits/physics-3d/castle.json +3 -3
  72. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  73. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -1
  74. package/kits/physics-3d/engine3d/actornode.js +253 -0
  75. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  76. package/kits/physics-3d/engine3d/optimize.js +49 -0
  77. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  78. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  79. package/kits/physics-3d/engine3d/world3d.js +525 -11
  80. package/kits/physics-3d/package.json +1 -1
  81. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  82. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  83. package/kits/physics-3d/scripts/test-camera-follow.mjs +543 -0
  84. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  85. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  86. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  87. package/kits/physics-3d/scripts/test-static-actors.mjs +667 -0
  88. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  89. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  90. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  91. package/kits/physics-3d/systems/physics3d.js +273 -9
  92. package/package.json +1 -1
@@ -52,6 +52,45 @@ function applyHover(phys, actor, t, dims, dt) {
52
52
  return grounded;
53
53
  }
54
54
 
55
+ // The hover of a scene that set `"engine": { "camera": { "follow": "rigid" } }`
56
+ // (the kit's CLAUDE.md has the terms): the same spring, asked for as a force.
57
+ // `applyHover` pushes once per drawn frame while gravity pulls once per fixed
58
+ // physics step, and a frame takes none, one or two steps, so on a frame that
59
+ // is not exactly one step the player is kicked up or let drop: a bob of a
60
+ // centimetre or two walking, which the rigid camera would show as the view
61
+ // bobbing. A force acts once per step, as gravity does, so the spring and
62
+ // gravity balance on every step whatever the frames are.
63
+ //
64
+ // The spring rests STEADY_REST higher than applyHover's so the player stands
65
+ // where it does without the key. applyHover's push lands at the start of a
66
+ // step and gravity is spread through it, so the velocity it reads standing
67
+ // still is not 0 but a fraction of a step's fall (-0.123 m/s for the kit's
68
+ // player, whose gravity scale is 2), and the spring's damper answers that
69
+ // with lift: 18 * 0.123 / 160 = 1.38 cm. Under a force the velocity at rest
70
+ // is 0. (0.69 cm per unit of gravity scale: a player with another scale
71
+ // stands that much off its keyless height.) What counts as grounded is
72
+ // measured as it is there.
73
+ //
74
+ // The force is the physics system's to drop: `addForce` lasts this frame's
75
+ // physics pass and no longer, so a frame this does not run on has no lift.
76
+ const STEADY_REST = 0.0138;
77
+
78
+ function hoverSteadily(phys, actor, t, dims) {
79
+ const hit = phys.castRay({ x: t.x, y: t.y, z: t.z }, { x: 0, y: -1, z: 0 }, dims.height, actor);
80
+ const hoverHeight = dims.height / 2 + 0.15;
81
+ const vel = phys.getVelocity(actor);
82
+ if (hit && hit.distance < hoverHeight + 0.4 && vel.y <= 1) {
83
+ const accel = 160 * (hoverHeight + STEADY_REST - hit.distance) - 18 * vel.y;
84
+ phys.addForce(actor, { x: 0, y: accel * phys.mass(actor), z: 0 });
85
+ }
86
+ return Boolean(hit && hit.distance < hoverHeight + 0.25);
87
+ }
88
+
89
+ // The fall-faster pull under the same key: a force for the same reason.
90
+ function pullSteadily(phys, actor) {
91
+ phys.addForce(actor, { x: 0, y: -14 * phys.mass(actor), z: 0 });
92
+ }
93
+
55
94
  function applyMove(phys, actor, move, speed, grounded, dt) {
56
95
  const mass = phys.mass(actor);
57
96
  const vel = phys.getVelocity(actor);
@@ -96,6 +135,387 @@ function updateCamera(scene, t, rt, props, dt) {
96
135
  cam.lookAt(t.x, t.y + 0.5, t.z);
97
136
  }
98
137
 
138
+ // How fast the rigid follow camera's offset and height catch up: the rate of
139
+ // updateCamera's lerp, so an orbit (Q/E, or turning) swings as it does there.
140
+ const FOLLOW_RATE = 12;
141
+
142
+ // One frame of `x' = FOLLOW_RATE * (target - x)` for a target that moved from
143
+ // `from` to `to` at a steady rate over the frame, solved exactly. A target that
144
+ // moves steadily is trailed by the same distance however the frames are cut,
145
+ // and one that stands still is reached as updateCamera's lerp reaches it.
146
+ function settle(value, from, to, dt) {
147
+ if (!(dt > 0)) return value;
148
+ const lag = (to - from) / (dt * FOLLOW_RATE);
149
+ return to - lag + (value - from + lag) * Math.exp(-FOLLOW_RATE * dt);
150
+ }
151
+
152
+ // The follow camera of a scene that set `"engine": { "camera": { "follow":
153
+ // "rigid" } }` (the kit's CLAUDE.md has the terms). It moves with the player
154
+ // as one piece: the offset from the player (its angle and height) and the
155
+ // player's height are eased, the player's ground position is not, so a steady
156
+ // walk leaves the player at one place on screen whatever the frame lengths.
157
+ // It is placed at the end of the frame (`placeFollowing`), on the position the
158
+ // frame is drawn with.
159
+ function followRigidly(scene, t, per, rt, props, dt) {
160
+ const cam = scene.three?.camera;
161
+ if (!cam) return;
162
+ const ox = -props.camDistance * Math.sin(per.camAngle);
163
+ const oy = props.camHeight;
164
+ const oz = props.camDistance * Math.cos(per.camAngle);
165
+ const last = per.camLastAt;
166
+ const jumped = last && Math.hypot(t.x - last.x, t.z - last.z) > TELEPORT_PER_FRAME;
167
+ per.camLastAt = { x: t.x, z: t.z };
168
+ // The offset is read each frame from where the camera is, against the
169
+ // point it followed last frame, so a camera something else moved since (a
170
+ // trip's camera, a cutscene) is eased on from where it was left.
171
+ const at = cam.position;
172
+ const f = (rt.camFollow ??= { from: { x: t.x, y: t.y, z: t.z }, to: null });
173
+ let x = at.x - f.from.x;
174
+ let y = at.y - f.from.y;
175
+ let z = at.z - f.from.z;
176
+ let height = f.from.y;
177
+ const to = f.to ?? { x: ox, y: oy, z: oz, height: t.y };
178
+ if (jumped || Math.hypot(t.x + ox - at.x, t.z + oz - at.z) > 20) {
179
+ [x, y, z, height] = [ox, oy, oz, t.y];
180
+ } else {
181
+ x = settle(x, to.x, ox, dt);
182
+ y = settle(y, to.y, oy, dt);
183
+ z = settle(z, to.z, oz, dt);
184
+ height = settle(height, to.height, t.y, dt);
185
+ }
186
+ f.to = { x: ox, y: oy, z: oz, height: t.y };
187
+ f.from = { x: t.x, y: height, z: t.z };
188
+ cam.position.set(t.x + x, height + y, t.z + z);
189
+ cam.lookAt(t.x, t.y + 0.5, t.z);
190
+ }
191
+
192
+ // Under the key, Player.update asks for its camera by the actor's id and the
193
+ // scene data it was made for (`scene.followCamera`), every frame, physics
194
+ // ready or not; the physics system calls this at the end of the frame, after
195
+ // it has written this frame's positions back (or at once, when it could not
196
+ // step), if the same scene is still loaded. The player is looked up as the
197
+ // scene has it then: one despawned or turned off since gets no camera.
198
+ function placeFollowing(scene, id, dt) {
199
+ const actor = scene.getActor(id);
200
+ const t = actor?.components.Transform;
201
+ const props = actor?.components.Player;
202
+ if (!t || !props || props.$enabled === false) return;
203
+ const per = (scene.persistent ??= {});
204
+ if (per.camAngle === undefined) per.camAngle = Math.PI / 4;
205
+ followRigidly(scene, t, per, actor.runtime, props, dt);
206
+ }
207
+
208
+ // ---------------------------------------------------------------------------
209
+ // The camera the player controls: a scene that set `"engine": { "camera": {
210
+ // "follow": "rigid", "control": "orbit" } }` (the kit's CLAUDE.md has the
211
+ // terms). Everything from here to `findLookText` runs under that key only,
212
+ // from the one branch at the top of `Player.update`; nothing above this line
213
+ // calls into it. It restates the steps of `update` that it shares (the
214
+ // persistent defaults, the jump, the fall, the hud) rather than have `update`
215
+ // call out for them, so that without the key `update` is the code it was.
216
+ //
217
+ // Walking is camera-relative (up on the stick, or W, is away from the camera)
218
+ // and the character turns to face the way it walks. The camera's yaw is
219
+ // `scene.persistent.camAngle`, with the meaning it always had: the camera
220
+ // sits at player + (-d sin(yaw), h, d cos(yaw)). Its pitch and distance are
221
+ // the player's own and are not sent anywhere: they are kept on the runtime
222
+ // (`scene.cameraOrbit`), which a scene load does not replace, and never on
223
+ // `scene.persistent`.
224
+
225
+ // The camera looks at the player this far above its Transform.
226
+ const LOOK_HEIGHT = 0.8;
227
+ // The nearest and farthest the player can zoom, metres from that point. A
228
+ // Player whose camDistance/camHeight start it outside these is given room to
229
+ // where it starts.
230
+ const ORBIT_NEAREST = 3;
231
+ const ORBIT_FARTHEST = 12;
232
+ // The lowest and highest the camera tilts, above the horizontal.
233
+ const ORBIT_PITCH_LEAST = 5 * DEG;
234
+ const ORBIT_PITCH_MOST = 70 * DEG;
235
+ // How fast the camera's angle, tilt and distance catch up with what was
236
+ // asked: quick enough to feel direct, slow enough to take the steps out of a
237
+ // finger's drag.
238
+ const ORBIT_RATE = 20;
239
+ // How fast the character turns to face the way it walks.
240
+ const FACE_RATE = 12;
241
+ // The camera stays this far in front of what is between it and the player,
242
+ // and no nearer the point it looks at than CAMERA_NEAREST.
243
+ const CAMERA_MARGIN = 0.25;
244
+ const CAMERA_NEAREST = 0.6;
245
+ // How fast the camera moves back out once nothing is in the way.
246
+ const CAMERA_OUT_RATE = 6;
247
+ // Within this of the distance it wants, a camera let back out is let go.
248
+ const CAMERA_OUT_DONE = 1e-4;
249
+ // A camera something else placed is eased on from where it was left at this
250
+ // rate: a twentieth of the way is left after 0.3 s.
251
+ const TAKEOVER_RATE = 10;
252
+ // The camera was placed on the frame before this one when the scene time it
253
+ // was last placed at is this frame's length ago, to within this (seconds).
254
+ const PLACED_WITHIN = 1e-6;
255
+ // A takeover blend farther than this from the camera's place has its drawn
256
+ // point tested for collision too (a second ray, only while it lasts).
257
+ const BLEND_TESTED = 1e-4;
258
+
259
+ const clamp = (value, least, most) => Math.max(least, Math.min(most, value));
260
+ // The share of the way an easing at `rate` covers in `dt`.
261
+ const eased = (rate, dt) => 1 - Math.exp(-rate * dt);
262
+ // An angle as the shortest way round: -PI..PI.
263
+ function arc(angle) {
264
+ const turns = angle - 2 * Math.PI * Math.floor((angle + Math.PI) / (2 * Math.PI));
265
+ return Number.isFinite(turns) ? turns : 0;
266
+ }
267
+
268
+ function held(keys, plus, minus) {
269
+ return (plus.some((code) => keys.has(code)) ? 1 : 0) - (minus.some((code) => keys.has(code)) ? 1 : 0);
270
+ }
271
+
272
+ // The cross-scene store with the camera's angle in it.
273
+ function persistentOf(scene) {
274
+ const per = (scene.persistent ??= {});
275
+ if (per.camAngle === undefined) per.camAngle = Math.PI / 4;
276
+ return per;
277
+ }
278
+
279
+ // This frame's walk: a direction on the ground no longer than 1, or null
280
+ // standing still. W/S and up/down walk away from and toward the camera, A/D
281
+ // strafe, the stick does both by how far it is pushed; left/right swing the
282
+ // camera at `turnSpeed`. The character's facing eases toward the walk and
283
+ // stays put standing still.
284
+ function driveOrbiting(scene, per, rt, props, dt) {
285
+ const keys = scene.keys;
286
+ per.camAngle += held(keys, ['ArrowRight'], ['ArrowLeft']) * props.turnSpeed * dt;
287
+ let ahead = held(keys, ['KeyW', 'ArrowUp'], ['KeyS', 'ArrowDown']);
288
+ let aside = held(keys, ['KeyD'], ['KeyA']);
289
+ const stick = scene.moveInput;
290
+ if (ahead === 0 && aside === 0 && stick?.active && Math.hypot(stick.x, stick.y) >= 0.15) {
291
+ ahead = -stick.y;
292
+ aside = stick.x;
293
+ }
294
+ const length = Math.hypot(ahead, aside);
295
+ if (length === 0) return null;
296
+ const scale = length > 1 ? 1 / length : 1;
297
+ const sin = Math.sin(per.camAngle);
298
+ const cos = Math.cos(per.camAngle);
299
+ const move = { x: (sin * ahead + cos * aside) * scale, z: (sin * aside - cos * ahead) * scale };
300
+ rt.facing += arc(Math.atan2(move.x, move.z) - rt.facing) * eased(FACE_RATE, dt);
301
+ return move;
302
+ }
303
+
304
+ // The jump and the fall-faster pull, as `update` has them under the camera
305
+ // key (the hover is a force there, and so is the pull).
306
+ function jumpOrbiting(phys, actor, scene, rt, grounded, jumpSpeed, dt) {
307
+ const tapped = scene.moveInput?.consumeJump?.();
308
+ rt.jumpBuffer = tapped ? 0.18 : Math.max(0, (rt.jumpBuffer ?? 0) - dt);
309
+ if (grounded && (rt.jumpBuffer > 0 || keyDown(scene.keys, 'Space'))) {
310
+ rt.jumpBuffer = 0;
311
+ const { x, z } = phys.getVelocity(actor);
312
+ phys.setVelocity(actor, { x, y: jumpSpeed, z });
313
+ phys.resetForces(actor);
314
+ }
315
+ if (!grounded && phys.getVelocity(actor).y < 1) pullSteadily(phys, actor);
316
+ }
317
+
318
+ function hudOrbiting(scene, actor, t, per, facing) {
319
+ const left = scene.actorsWith('Pickup').length;
320
+ const all = per.score + left;
321
+ let score = '';
322
+ if (all !== 0) score = left === 0 ? '◆ all shards found' : `◆ ${per.score}/${all}`;
323
+ scene.hud = { score, look: findLookText(scene, actor, t, facing) };
324
+ }
325
+
326
+ // `Player.update` under the key.
327
+ function updateOrbiting(actor, scene, props, dt) {
328
+ scene.followCamera = { id: actor.id, data: scene.data, dt, place: placeOrbiting };
329
+ scene.orbitInput?.();
330
+ scene.lookInput?.listen?.();
331
+ const rt = actor.runtime;
332
+ // A facing asked for (`scene.faceRequest`, radians: the hub's arrival
333
+ // facing, a jump to a door) is taken once. Without the key the character
334
+ // always faces PI - camAngle, so code written for that sets camAngle;
335
+ // under it the camera and the character turn apart, and turning the
336
+ // character is asked for.
337
+ if (scene.faceRequest !== undefined) {
338
+ if (typeof scene.faceRequest === 'number' && Number.isFinite(scene.faceRequest)) rt.facing = scene.faceRequest;
339
+ scene.faceRequest = undefined;
340
+ }
341
+ const phys = scene.physics3d;
342
+ if (!phys?.ready()) return;
343
+ const t = actor.components.Transform;
344
+ const per = persistentOf(scene);
345
+ if (per.score === undefined) per.score = 0;
346
+ // The first frame of an actor (actor.runtime is rebuilt on a load) faces
347
+ // away from the camera, as the keyless Player does.
348
+ if (typeof rt.facing !== 'number') rt.facing = Math.PI - per.camAngle;
349
+ const shape = actor.components.Shape;
350
+ const grounded = hoverSteadily(phys, actor, t, { radius: shape?.radius ?? 0.35, height: shape?.height ?? 1.4 });
351
+ applyMove(phys, actor, driveOrbiting(scene, per, rt, props, dt), props.speed, grounded, dt);
352
+ t.rotationY = rt.facing / DEG;
353
+ jumpOrbiting(phys, actor, scene, rt, grounded, props.jumpSpeed, dt);
354
+ hudOrbiting(scene, actor, t, per, rt.facing);
355
+ }
356
+
357
+ const finiteOr = (value, otherwise) => (Number.isFinite(value) ? value : otherwise);
358
+
359
+ // The tilt and distance the player has chosen, on the runtime. They start
360
+ // where the Player's camDistance and camHeight put the fixed camera, and
361
+ // start there again for a Player with other numbers.
362
+ function orbitChoice(scene, props) {
363
+ const distance = finiteOr(props.camDistance, 9);
364
+ const height = finiteOr(props.camHeight, 7);
365
+ const chosen = scene.cameraOrbit;
366
+ if (chosen && chosen.distance === distance && chosen.height === height) return chosen;
367
+ const rise = height - LOOK_HEIGHT;
368
+ const range = Math.max(CAMERA_NEAREST, Math.hypot(distance, rise));
369
+ scene.cameraOrbit = {
370
+ distance,
371
+ height,
372
+ range,
373
+ pitch: clamp(Math.atan2(rise, distance), ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST),
374
+ nearest: Math.min(ORBIT_NEAREST, range),
375
+ farthest: Math.max(ORBIT_FARTHEST, range),
376
+ };
377
+ return scene.cameraOrbit;
378
+ }
379
+
380
+ // What the player asked of the camera this frame, onto what it is aimed for.
381
+ function steerOrbit(per, chosen, look) {
382
+ per.camAngle += look.yaw;
383
+ chosen.pitch = clamp(chosen.pitch + look.pitch, ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST);
384
+ chosen.range = clamp(chosen.range * look.zoom, chosen.nearest, chosen.farthest);
385
+ }
386
+
387
+ // The ray from the point the camera looks at (the eased one the camera is
388
+ // placed from) toward where it wants to be: a unit direction.
389
+ const ray = { from: { x: 0, y: 0, z: 0 }, dir: { x: 0, y: 0, z: 0 } };
390
+
391
+ // The farthest the camera may be along `ray` (`state.limit`, +Infinity when
392
+ // nothing holds it): CAMERA_MARGIN in front of the nearest fixed solid within
393
+ // its distance (and the margin past it), never nearer than CAMERA_NEAREST. A nearer limit is taken at
394
+ // once; a farther one, or none, is eased out to at CAMERA_OUT_RATE, and once
395
+ // the camera is back at its distance it is let go. Not asked while physics
396
+ // has no world.
397
+ function limitReach(phys, state, dt) {
398
+ if (!phys?.castRayFixed || !phys.ready()) return;
399
+ const hit = phys.castRayFixed(ray.from, ray.dir, state.range + CAMERA_MARGIN);
400
+ const wall = hit ? Math.max(CAMERA_NEAREST, hit.distance - CAMERA_MARGIN) : Infinity;
401
+ if (wall <= state.limit) {
402
+ state.limit = wall;
403
+ return;
404
+ }
405
+ // Out from where the camera is, not from a limit past its distance.
406
+ const from = Math.min(state.limit, state.range);
407
+ state.limit = from + (Math.min(wall, state.range) - from) * eased(CAMERA_OUT_RATE, dt);
408
+ if (wall === Infinity && state.limit >= state.range - CAMERA_OUT_DONE) state.limit = Infinity;
409
+ }
410
+
411
+ // How far from its place (x, y, z) the camera is drawn this frame: nothing,
412
+ // unless something else placed it (`mine` is false), and then what is left
413
+ // of the way from where it was put (`at`).
414
+ function takenOver(off, at, x, y, z, mine, jumped, dt) {
415
+ if (!mine) {
416
+ // A teleport, or a camera more than 20 m off, snaps as the others do.
417
+ const snap = jumped || Math.hypot(x - at.x, z - at.z) > 20;
418
+ off.x = snap ? 0 : at.x - x;
419
+ off.y = snap ? 0 : at.y - y;
420
+ off.z = snap ? 0 : at.z - z;
421
+ }
422
+ const left = Math.exp(-TAKEOVER_RATE * dt);
423
+ off.x *= left;
424
+ off.y *= left;
425
+ off.z *= left;
426
+ return off;
427
+ }
428
+
429
+ // The point drawn while a takeover blend lasts (its place plus `off`) is
430
+ // collided as its place is: if a fixed solid lies between the look point
431
+ // (`ray.from`) and it, it is pulled in along its own ray to CAMERA_MARGIN
432
+ // in front (never nearer than CAMERA_NEAREST), and the pull is kept in
433
+ // `off`, so the next frame eases on from where it was drawn.
434
+ const drawn = { x: 0, y: 0, z: 0 };
435
+
436
+ function holdBlend(phys, off, x, y, z) {
437
+ if (!phys?.castRayFixed || !phys.ready()) return;
438
+ drawn.x = x + off.x - ray.from.x;
439
+ drawn.y = y + off.y - ray.from.y;
440
+ drawn.z = z + off.z - ray.from.z;
441
+ const length = Math.hypot(drawn.x, drawn.y, drawn.z);
442
+ if (!(length > CAMERA_NEAREST)) return;
443
+ drawn.x /= length;
444
+ drawn.y /= length;
445
+ drawn.z /= length;
446
+ const hit = phys.castRayFixed(ray.from, drawn, length + CAMERA_MARGIN);
447
+ const most = hit ? Math.max(CAMERA_NEAREST, hit.distance - CAMERA_MARGIN) : Infinity;
448
+ if (most >= length) return;
449
+ off.x = ray.from.x + drawn.x * most - x;
450
+ off.y = ray.from.y + drawn.y * most - y;
451
+ off.z = ray.from.z + drawn.z * most - z;
452
+ }
453
+
454
+ // The orbit camera, placed at the end of the frame as the rigid one is
455
+ // (`placeFollowing`): the player's ground position is not eased, its height
456
+ // is, as there. What the camera is doing between frames (`actor.runtime.orbit`)
457
+ // goes with the actor on a scene load. The camera is the player's to steer on
458
+ // a frame only when this also placed it on the frame before, the camera
459
+ // is where this left it, the player did not teleport, and the look input is
460
+ // not locked (the hub locks it through a door trip). Otherwise what was asked
461
+ // of it is dropped; and, all but for the lock, it starts again from what was
462
+ // chosen and eases on from where the camera was put (a hub trip's camera, a
463
+ // cutscene, the first frame, a Player turned off and on).
464
+ function placeOrbiting(scene, id, dt) {
465
+ const actor = scene.getActor(id);
466
+ const props = actor?.components.Player;
467
+ const t = actor?.components.Transform;
468
+ const cam = scene.three?.camera;
469
+ if (!cam || !t || !props || props.$enabled === false) return;
470
+ const rt = actor.runtime;
471
+ const per = persistentOf(scene);
472
+ const chosen = orbitChoice(scene, props);
473
+ const look = scene.lookInput?.consume?.();
474
+ const before = per.camLastAt;
475
+ const jumped = Boolean(before) && Math.hypot(t.x - before.x, t.z - before.z) > TELEPORT_PER_FRAME;
476
+ per.camLastAt = { x: t.x, z: t.z };
477
+ const at = cam.position;
478
+ const state = (rt.orbit ??= { off: { x: 0, y: 0, z: 0 } });
479
+ // Placed on the frame before too: a frame this did not place on (the
480
+ // Player turned off, even by a collision callback after its update)
481
+ // breaks the chain.
482
+ const placed = typeof state.placedAt === 'number' && Math.abs(scene.time - dt - state.placedAt) < PLACED_WITHIN;
483
+ const mine = placed && !jumped && state.x === at.x && state.y === at.y && state.z === at.z;
484
+ if (mine) {
485
+ if (look && !look.locked) steerOrbit(per, chosen, look);
486
+ const k = eased(ORBIT_RATE, dt);
487
+ state.yaw += arc(per.camAngle - state.yaw) * k;
488
+ state.pitch += (chosen.pitch - state.pitch) * k;
489
+ state.range += (chosen.range - state.range) * k;
490
+ state.height = settle(state.height, state.heightTo, t.y, dt);
491
+ } else {
492
+ Object.assign(state, { yaw: per.camAngle, pitch: chosen.pitch, range: chosen.range, height: t.y, limit: Infinity });
493
+ }
494
+ state.heightTo = t.y;
495
+ const flat = Math.cos(state.pitch);
496
+ ray.dir.x = -flat * Math.sin(state.yaw);
497
+ ray.dir.y = Math.sin(state.pitch);
498
+ ray.dir.z = flat * Math.cos(state.yaw);
499
+ // From the point the camera is placed from, so what is tested is the
500
+ // camera that is drawn (less the takeover blend below, which is not).
501
+ ray.from.x = t.x;
502
+ ray.from.y = state.height + LOOK_HEIGHT;
503
+ ray.from.z = t.z;
504
+ limitReach(scene.physics3d, state, dt);
505
+ const reach = Math.max(Math.min(state.range, state.limit), Math.min(CAMERA_NEAREST, state.range), 0);
506
+ const x = ray.from.x + ray.dir.x * reach;
507
+ const y = ray.from.y + ray.dir.y * reach;
508
+ const z = ray.from.z + ray.dir.z * reach;
509
+ const off = takenOver(state.off, at, x, y, z, mine, jumped, dt);
510
+ if (Math.hypot(off.x, off.y, off.z) > BLEND_TESTED) holdBlend(scene.physics3d, off, x, y, z);
511
+ cam.position.set(x + off.x, y + off.y, z + off.z);
512
+ state.placedAt = scene.time;
513
+ state.x = at.x;
514
+ state.y = at.y;
515
+ state.z = at.z;
516
+ cam.lookAt(t.x, t.y + LOOK_HEIGHT, t.z);
517
+ }
518
+
99
519
  // The nearest Lookable the player is facing, within its range.
100
520
  function findLookText(scene, actor, t, facing) {
101
521
  const fx = Math.sin(facing);
@@ -134,6 +554,10 @@ export class Player {
134
554
  }
135
555
 
136
556
  update(actor, scene, dt) {
557
+ if (scene.cameraControl === 'orbit') return updateOrbiting(actor, scene, this.props, dt);
558
+ if (scene.cameraFollowsRigidly === true) {
559
+ scene.followCamera = { id: actor.id, data: scene.data, dt, place: placeFollowing };
560
+ }
137
561
  const phys = scene.physics3d;
138
562
  if (!phys?.ready()) return;
139
563
  const t = actor.components.Transform;
@@ -147,7 +571,11 @@ export class Player {
147
571
 
148
572
  const shape = actor.components.Shape;
149
573
  const dims = { radius: shape?.radius ?? 0.35, height: shape?.height ?? 1.4 };
150
- const grounded = applyHover(phys, actor, t, dims, dt);
574
+ // Under the camera key the player is held steady on screen: the hover
575
+ // and the fall-faster pull are forces (hoverSteadily). Without it every
576
+ // call below is the one made before the key had this meaning.
577
+ const steady = scene.cameraFollowsRigidly === true;
578
+ const grounded = steady ? hoverSteadily(phys, actor, t, dims) : applyHover(phys, actor, t, dims, dt);
151
579
  const drive = readDrive(scene.keys, scene.moveInput);
152
580
  per.camAngle += drive.turn * this.props.turnSpeed * dt;
153
581
  rt.facing = Math.PI - per.camAngle;
@@ -170,15 +598,21 @@ export class Player {
170
598
  rt.jumpBuffer = 0;
171
599
  const vel = phys.getVelocity(actor);
172
600
  phys.setVelocity(actor, { x: vel.x, y: this.props.jumpSpeed, z: vel.z });
601
+ // The jump replaces the velocity the hover was holding; this frame's
602
+ // lift goes too, or it would be added to the jump.
603
+ if (steady) phys.resetForces(actor);
173
604
  }
174
605
  // Fall faster than the rise: extra downward pull past the jump apex kills
175
606
  // the floaty arc.
176
607
  if (!grounded) {
177
608
  const vel = phys.getVelocity(actor);
178
- if (vel.y < 1) phys.applyImpulse(actor, { x: 0, y: -14 * phys.mass(actor) * dt, z: 0 });
609
+ if (vel.y < 1) {
610
+ if (steady) pullSteadily(phys, actor);
611
+ else phys.applyImpulse(actor, { x: 0, y: -14 * phys.mass(actor) * dt, z: 0 });
612
+ }
179
613
  }
180
614
 
181
- updateCamera(scene, t, per, this.props, dt);
615
+ if (scene.cameraFollowsRigidly !== true) updateCamera(scene, t, per, this.props, dt);
182
616
  const remaining = scene.actorsWith('Pickup').length;
183
617
  const total = per.score + remaining;
184
618
  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-05T08:03:43.791Z"
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-05T08:03:58.819Z"
65
65
  }
@@ -672,6 +672,10 @@ time.
672
672
  - `keep: true` on a part keeps it out of merging, with its own mesh and
673
673
  material, for a deck that reaches for it by id. Parts with a `tint` are
674
674
  kept too.
675
+ - In a scene that set `"engine": { "dropEmptyParts": true }` (CLAUDE.md) a
676
+ placed model has no group for a part that draws nothing. `keep: true` is
677
+ also what keeps such a part's group there, for a deck that reaches for an
678
+ empty part as a locator; `slot-...` parts and parts that move always stay.
675
679
  - The same static model placed many times is built once, and in play every
676
680
  copy draws in the same calls.
677
681
  - What costs the most: fine paint over large areas (grime with a `scale`
@@ -12,6 +12,7 @@ import {
12
12
  disposeWorld,
13
13
  updatePhysicsDebug,
14
14
  } from './world3d';
15
+ import { attachOrbitInput } from './orbitinput';
15
16
 
16
17
  export function Scene3DPlayer({
17
18
  sceneData,
@@ -134,7 +135,35 @@ function attachInput(canvas, runtime, world) {
134
135
  move.x = 0;
135
136
  move.y = 0;
136
137
  };
138
+ // A scene that set `"engine": { "camera": { "control": "orbit" } }` beside
139
+ // `"follow": "rigid"`: a pointer that goes down in it is orbitinput.js's
140
+ // from then until it lifts (or a scene loads). It is made the first time
141
+ // a pointer goes down under the key or a Player runs under it
142
+ // (`runtime.orbitInput()`), never in a runtime that does not meet the key.
143
+ // Without the key each handler below reads one property and goes on as it
144
+ // always did.
145
+ let orbit = null;
146
+ runtime.orbitInput = () =>
147
+ (orbit ??= attachOrbitInput(
148
+ canvas,
149
+ runtime,
150
+ move,
151
+ () => {
152
+ jumpPending = true;
153
+ },
154
+ { stickRadius: STICK_RADIUS_PX, tapSlop: TAP_SLOP_PX, tapMs: TAP_MS }
155
+ ));
137
156
  const onPointerDown = (event) => {
157
+ if (runtime.cameraControl === 'orbit') {
158
+ // Fingers that went down before the key (a scene without it was
159
+ // loaded then) are let go of here, so they and orbitinput.js never
160
+ // both write the stick: the handlers below ignore them from now on.
161
+ if (pointers.size > 0 || stickId !== null) {
162
+ pointers.clear();
163
+ clearStick();
164
+ }
165
+ return runtime.orbitInput().down(event);
166
+ }
138
167
  canvas.focus();
139
168
  pointers.set(event.pointerId, {
140
169
  x: event.clientX,
@@ -145,6 +174,7 @@ function attachInput(canvas, runtime, world) {
145
174
  canvas.setPointerCapture(event.pointerId);
146
175
  };
147
176
  const onPointerMove = (event) => {
177
+ if (orbit?.busy && orbit.move(event)) return;
148
178
  const p = pointers.get(event.pointerId);
149
179
  if (!p) return;
150
180
  const dx = event.clientX - p.x;
@@ -163,6 +193,7 @@ function attachInput(canvas, runtime, world) {
163
193
  move.y = ny * scale;
164
194
  };
165
195
  const onPointerUp = (event) => {
196
+ if (orbit?.busy && orbit.up(event)) return;
166
197
  const p = pointers.get(event.pointerId);
167
198
  pointers.delete(event.pointerId);
168
199
  if (stickId === event.pointerId) clearStick();
@@ -183,6 +214,7 @@ function attachInput(canvas, runtime, world) {
183
214
  canvas.removeEventListener('pointermove', onPointerMove);
184
215
  canvas.removeEventListener('pointerup', onPointerUp);
185
216
  canvas.removeEventListener('pointercancel', onPointerUp);
217
+ orbit?.detach();
186
218
  };
187
219
  }
188
220
 
@@ -214,7 +246,7 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
214
246
  }
215
247
  syncActors(world, runtime, runtime.sprites ?? sprites, dt);
216
248
  if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());
217
- renderWorld(world);
249
+ renderWorld(world, runtime);
218
250
  updateHud(runtime, hudRefs);
219
251
  } catch (err) {
220
252
  onError?.(err);