castle-web-cli 0.4.231 → 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 (55) hide show
  1. package/dist/serverBundle.js +5 -3
  2. package/kits/hub-game/CLAUDE.md +26 -4
  3. package/kits/hub-game/code/client/avatar.js +39 -0
  4. package/kits/hub-game/code/client/chat.js +12 -0
  5. package/kits/hub-game/code/client/chrome.js +194 -4
  6. package/kits/hub-game/code/client/grab.js +31 -7
  7. package/kits/hub-game/code/client/hats.js +26 -0
  8. package/kits/hub-game/code/client/hookLayer.js +30 -3
  9. package/kits/hub-game/code/client/hudClear.js +126 -0
  10. package/kits/hub-game/code/client/state.js +22 -0
  11. package/kits/hub-game/code/client/tiers.js +31 -6
  12. package/kits/hub-game/code/client/together.js +66 -1
  13. package/kits/hub-game/code/client/wear.js +96 -14
  14. package/kits/hub-game/code/server/actors.js +5 -0
  15. package/kits/hub-game/code/server/grab.js +296 -11
  16. package/kits/hub-game/code/server/hub.js +63 -2
  17. package/kits/hub-game/code/server/manifest.js +48 -3
  18. package/kits/hub-game/code/server/party.js +11 -0
  19. package/kits/hub-game/code/server/say.js +8 -2
  20. package/kits/hub-game/code/server/wear.js +116 -11
  21. package/kits/hub-game/code/systems/hub.js +253 -5
  22. package/kits/hub-game/docs/contract.md +204 -8
  23. package/kits/hub-game/package.json +1 -1
  24. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  25. package/kits/hub-game/scripts/test-grab-client.mjs +186 -3
  26. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  27. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  28. package/kits/hub-game/scripts/test-hub-trip.mjs +513 -0
  29. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  30. package/kits/hub-game/scripts/test-manifest.mjs +75 -0
  31. package/kits/hub-game/scripts/test-party.mjs +22 -1
  32. package/kits/hub-game/scripts/test-say.mjs +59 -2
  33. package/kits/hub-game/scripts/test-tiers.mjs +190 -2
  34. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  35. package/kits/physics-2d/castle.json +1 -1
  36. package/kits/physics-2d/engine/scene.js +35 -0
  37. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +44 -0
  38. package/kits/physics-3d/CLAUDE.md +252 -0
  39. package/kits/physics-3d/behaviors/Player.jsx +363 -2
  40. package/kits/physics-3d/castle.json +2 -2
  41. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  42. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -0
  43. package/kits/physics-3d/engine3d/optimize.js +49 -0
  44. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  45. package/kits/physics-3d/engine3d/world3d.js +81 -25
  46. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  47. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  48. package/kits/physics-3d/scripts/test-camera-follow.mjs +12 -2
  49. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  50. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  51. package/kits/physics-3d/scripts/test-static-actors.mjs +6 -1
  52. package/kits/physics-3d/scripts/test-static-passes.mjs +1 -1
  53. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  54. package/kits/physics-3d/systems/physics3d.js +91 -6
  55. package/package.json +1 -1
@@ -68,7 +68,7 @@
68
68
  "onUpdate": "scripts/onUpdate.mjs",
69
69
  "title": "physics-2d",
70
70
  "description": "Scene Editor. Works like classic Castle: actors, blueprints, behaviors and drawing tools, with physics built in.",
71
- "publishedVersion": "2026-10-04T22:43:17.146Z",
71
+ "publishedVersion": "2026-10-05T08:03:43.791Z",
72
72
  "imports": {
73
73
  "castle.base": {
74
74
  "deckId": "yRcmH4_aYllE",
@@ -120,6 +120,14 @@ function sceneNearShadowDistance(data) {
120
120
  return typeof distance === 'number' && Number.isFinite(distance) && distance > 0 ? distance : 0;
121
121
  }
122
122
 
123
+ // `"engine": { "dropEmptyParts": true }` at a scene file's top level: the
124
+ // scene asks the 3d kit to leave out of a placed model the groups that draw
125
+ // nothing (its CLAUDE.md has the terms). Off unless a scene says so with
126
+ // exactly `true`. Nothing in this kit reads it.
127
+ function sceneDropsEmptyParts(data) {
128
+ return data?.engine?.dropEmptyParts === true;
129
+ }
130
+
123
131
  // `"engine": { "camera": { "follow": "rigid" } }` at a scene file's top level:
124
132
  // the scene asks the 3d kit's Player for a follow camera that moves with the
125
133
  // player rather than easing after it (its CLAUDE.md has the terms). Off unless
@@ -128,6 +136,15 @@ function sceneCameraFollowsRigidly(data) {
128
136
  return data?.engine?.camera?.follow === 'rigid';
129
137
  }
130
138
 
139
+ // `"engine": { "camera": { "follow": "rigid", "control": "orbit" } }`: the
140
+ // scene asks the 3d kit's Player for a camera the player turns, tilts and
141
+ // zooms (its CLAUDE.md has the terms). 'orbit' only when the scene says
142
+ // exactly "orbit" beside exactly `"follow": "rigid"`; null otherwise. Nothing
143
+ // in this kit reads it.
144
+ function sceneCameraControl(data) {
145
+ return sceneCameraFollowsRigidly(data) && data.engine.camera.control === 'orbit' ? 'orbit' : null;
146
+ }
147
+
131
148
  // Whether a Layout's z is plain data: its own stored value, or absent
132
149
  // altogether. One that is computed when read (an accessor, or carried by a
133
150
  // prototype) is left to the sort, which reads it in the sort's own order.
@@ -180,6 +197,14 @@ export class SceneRuntime {
180
197
  return this.#nearShadowDistance;
181
198
  }
182
199
 
200
+ // Whether the loaded scene asked for `engine.dropEmptyParts`. Set by `load`,
201
+ // as `skipsUnchangedActors` is.
202
+ #dropsEmptyParts = false;
203
+
204
+ get dropsEmptyParts() {
205
+ return this.#dropsEmptyParts;
206
+ }
207
+
183
208
  // Whether the loaded scene asked for `engine.camera.follow: "rigid"`. Set
184
209
  // by `load`, as `skipsUnchangedActors` is.
185
210
  #cameraFollowsRigidly = false;
@@ -188,6 +213,14 @@ export class SceneRuntime {
188
213
  return this.#cameraFollowsRigidly;
189
214
  }
190
215
 
216
+ // What the loaded scene asked for with `engine.camera.control` ('orbit' or
217
+ // null). Set by `load`, as `skipsUnchangedActors` is.
218
+ #cameraControl = null;
219
+
220
+ get cameraControl() {
221
+ return this.#cameraControl;
222
+ }
223
+
191
224
  // `files` is the live deck files map (path -> text), used to resolve every
192
225
  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
193
226
  // a load-time snapshot -- so a blueprint edit propagates to every scene that
@@ -322,7 +355,9 @@ export class SceneRuntime {
322
355
  this.data = structuredClone(sceneData);
323
356
  this.#skipUnchanged = sceneSkipsUnchangedActors(this.data);
324
357
  this.#nearShadowDistance = sceneNearShadowDistance(this.data);
358
+ this.#dropsEmptyParts = sceneDropsEmptyParts(this.data);
325
359
  this.#cameraFollowsRigidly = sceneCameraFollowsRigidly(this.data);
360
+ this.#cameraControl = sceneCameraControl(this.data);
326
361
  this.actors = new Map();
327
362
  for (const actor of this.data.actors ?? []) {
328
363
  this.#initActor(actor);
@@ -233,6 +233,23 @@ if (!Other && !process.env.ONLY) {
233
233
  assert.equal(scene.skipsUnchangedActors, false, 'and the one key does not set the other');
234
234
  scene.load(data);
235
235
  assert.equal(scene.nearShadowDistance, 0, 'and is off again for a scene without it');
236
+ // `engine.dropEmptyParts`, which the 3d kit reads: latched the same way.
237
+ const drops = (engine) => new SceneRuntime({ ...data, engine }, classes, {}, {}).dropsEmptyParts;
238
+ assert.equal(scene.dropsEmptyParts, false, 'off unless the scene says so');
239
+ assert.equal(drops({ skipUnchangedActors: true, shadows: { distance: 40 }, camera: { follow: 'rigid' } }), false);
240
+ assert.equal(drops({ dropEmptyParts: true }), true);
241
+ for (const not of [false, 1, 'true', {}, [], null, undefined]) {
242
+ assert.equal(drops({ dropEmptyParts: not }), false, JSON.stringify(not));
243
+ }
244
+ assert.equal(new SceneRuntime({ ...data, dropEmptyParts: true }, classes, {}, {}).dropsEmptyParts, false, 'only under `engine`');
245
+ scene.load({ ...data, engine: { dropEmptyParts: true } });
246
+ assert.equal(scene.clone().dropsEmptyParts, true, 'and by a clone');
247
+ scene.data.engine.dropEmptyParts = false;
248
+ assert.equal(scene.dropsEmptyParts, true, 'read when the scene loads');
249
+ assert.equal(scene.skipsUnchangedActors, false, 'and the one key does not set the others');
250
+ assert.equal(scene.nearShadowDistance, 0);
251
+ scene.load(data);
252
+ assert.equal(scene.dropsEmptyParts, false, 'and is off again for a scene without it');
236
253
  // `engine.camera.follow`, which the 3d kit's Player reads: latched the same way.
237
254
  const rigid = (engine) => new SceneRuntime({ ...data, engine }, classes, {}, {}).cameraFollowsRigidly;
238
255
  assert.equal(scene.cameraFollowsRigidly, false, 'off unless the scene says so');
@@ -249,6 +266,33 @@ if (!Other && !process.env.ONLY) {
249
266
  assert.equal(scene.nearShadowDistance, 0);
250
267
  scene.load(data);
251
268
  assert.equal(scene.cameraFollowsRigidly, false, 'and is off again for a scene without it');
269
+ // `engine.camera.control`, which the 3d kit's Player and input read:
270
+ // latched the same way, and only beside `follow: "rigid"`.
271
+ const made = (engine) => new SceneRuntime({ ...data, engine }, classes, {}, {});
272
+ const control = (camera) => made({ camera }).cameraControl;
273
+ assert.equal(scene.cameraControl, null, 'off unless the scene says so');
274
+ assert.equal(made({ skipUnchangedActors: true, shadows: { distance: 40 } }).cameraControl, null);
275
+ assert.equal(control({ follow: 'rigid', control: 'orbit' }), 'orbit');
276
+ assert.equal(control({ follow: 'rigid' }), null, 'the rigid camera alone is not the orbit one');
277
+ assert.equal(made({ camera: { follow: 'rigid' } }).cameraFollowsRigidly, true);
278
+ assert.equal(made({ camera: { follow: 'rigid', control: 'orbit' } }).cameraFollowsRigidly, true, 'and the orbit one is still rigid');
279
+ for (const not of [true, 'orbit', {}, null, { control: 'orbit' }, { follow: 'smooth', control: 'orbit' }, { follow: true, control: 'orbit' }, { follow: 'rigid', control: true }, { follow: 'rigid', control: 'Orbit' }, { follow: 'rigid', control: 'free' }, { follow: 'rigid', control: null }, { follow: 'rigid', control: ['orbit'] }]) {
280
+ assert.equal(control(not), null, JSON.stringify(not));
281
+ }
282
+ scene.load({ ...data, engine: { camera: { follow: 'rigid', control: 'orbit' } } });
283
+ assert.equal(scene.clone().cameraControl, 'orbit', 'and by a clone');
284
+ scene.data.engine.camera.control = 'free';
285
+ scene.data.engine.camera.follow = 'smooth';
286
+ assert.equal(scene.cameraControl, 'orbit', 'read when the scene loads');
287
+ assert.equal(scene.skipsUnchangedActors, false, 'and the key does not set the others');
288
+ assert.equal(scene.nearShadowDistance, 0);
289
+ scene.load({ ...data, engine: { camera: { follow: 'rigid' } } });
290
+ assert.equal(scene.cameraControl, null, 'off again for a scene with the rigid camera alone');
291
+ assert.equal(scene.cameraFollowsRigidly, true);
292
+ scene.load({ ...data, engine: { camera: { follow: 'rigid', control: 'orbit' } } });
293
+ assert.equal(scene.cameraControl, 'orbit', 'on again for a scene that says so');
294
+ scene.load(data);
295
+ assert.equal(scene.cameraControl, null, 'and off again for a scene without it');
252
296
  }
253
297
 
254
298
  console.log(`skip unchanged: ${scenarios} scenarios call the same hooks with and without the key`);
@@ -33,6 +33,9 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
33
33
  - Motion goes through `scene.physics3d`, never by writing a dynamic actor's
34
34
  Transform: `setVelocity(actor, {x,y,z})`, `applyImpulse`, `getVelocity`,
35
35
  `mass`, `castRay(origin, dir, maxToi, excludeActor)` (rays skip sensors).
36
+ `addForce(actor, {x,y,z})` pushes through this frame's physics steps only
37
+ (ask every frame from `update` for a steady push; `resetForces(actor)`
38
+ drops what the frame asked): the camera section below has the rule.
36
39
  Fixed/kinematic actors ARE moved by writing their Transform.
37
40
  - The scene has the lighting rig built in (hemisphere + ambient + one
38
41
  shadow-casting sun, ground plane at y=0); meshes cast and receive shadows
@@ -138,6 +141,65 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
138
141
  local `matrix` written by hand while its `matrixAutoUpdate` is on (set
139
142
  `position` / `quaternion` / `scale` instead); three.js private fields
140
143
  written directly (`rotation._order`, `quaternion._x`).
144
+ - `"engine": { "dropEmptyParts": true }` at the scene file's top level (the
145
+ same `engine` object) asks the engine to place models without the groups
146
+ that draw nothing. A placed model is a game build: its meshes are merged
147
+ into a few draw calls, but every part keeps its own three.js group, most of
148
+ them then empty, and three.js and the engine visit every object under the
149
+ scene on every frame. A town of a few hundred models is two thirds such
150
+ groups. The terms:
151
+ > With the key absent, a model is built and placed exactly as before: the
152
+ > same objects, the same shared build, the same node. With the key present,
153
+ > every object that is drawn (a mesh, its outline, anything that is not a
154
+ > plain group) is the same object with the same geometry, material and
155
+ > world matrix as without it, on every frame, and walks, `motion`, clips and
156
+ > glow play the same. What a deck must not rely on under the key is finding
157
+ > the group of a part that draws nothing unless that part is one that
158
+ > stays.
159
+
160
+ What goes: a group with nothing drawn on it or anywhere under it -- no
161
+ mesh, line, points, sprite, light or camera. That includes the group of a
162
+ part that IS drawn when its mesh was merged into a batch on the model's
163
+ root or on a moving part: the picture keeps the part, `modelParts` does
164
+ not. What always stays, with every group above it:
165
+ - a part marked `keep: true` (docs/pxmodel-format.md: "for a deck that
166
+ reaches for it by id"), with its own mesh as before;
167
+ - a part named `slot-...`. The format's docs let a deck "parent your own
168
+ parts to it", and nothing says that happens only in the model file, so a
169
+ slot is never dropped: a deck may hang a mesh on one at runtime and it is
170
+ drawn where it would be without the key;
171
+ - a part the walk moves (`legL`, `legR`, `armL`, `armR`, `torso`) or the
172
+ model's `motion`, gait or `clips` move, drawn or not, and every copy of
173
+ one;
174
+ - anything a kept part or slot holds that is not another part.
175
+
176
+ An actor whose model draws nothing at all (an invisible collider placing an
177
+ empty model) gets no rig group under its node: the node is there, with
178
+ `userData.modelParts` an empty Map and no children.
179
+ So under the key:
180
+ - `scene.three.nodes.get(id).node.userData.modelParts` holds only the parts
181
+ that stayed. `modelParts.get('door')` for a part that draws nothing and
182
+ is none of the above is `undefined`, where without the key it is an empty
183
+ group. To reach for an empty part as a locator (a muzzle, a hand), mark
184
+ it `keep: true` or name it `slot-...`; it then stands exactly where it
185
+ did.
186
+ - code that walks a node's tree counts fewer objects, and a node's first
187
+ child is its rig only when its model draws something.
188
+ - nothing else changes: which actors have nodes, `userData.actorId`, the
189
+ rig's `yOffset` and `scale`, physics, picking, shadows (casters are
190
+ culled by their own meshes' bounds), `instanceModels`.
191
+
192
+ It is read when the scene loads, as `skipUnchangedActors` is, and each
193
+ scene decides for itself: a node and a shared model build made for a scene
194
+ that asked are never used for one that did not, or the other way round (a
195
+ resident scene parked while another plays, a pack mounted in a town, a door
196
+ trip, a scene file reloaded with the key changed -- every node is then
197
+ built again). The scene editor and the play panel draw a scene through the
198
+ same engine, so both follow the scene's key; the editor selects actors, not
199
+ parts, and is not affected. The model editor and `npm run render` build a
200
+ model for themselves, with every part's group, whatever any scene says.
201
+ Opt in with `skipUnchangedActors` when a scene is hundreds of placed
202
+ models; a scene of a few gains nothing.
141
203
  - `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
142
204
  (the same `engine` object) asks the engine to draw the sun's shadows where
143
205
  they can be seen, near the camera, rather than in the sun's fixed box.
@@ -337,6 +399,196 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
337
399
  The play panel and a published deck play the scene through the same
338
400
  runtime, so both follow the scene's key; the scene editor's own orbit
339
401
  camera is not a follow camera and is not affected.
402
+
403
+ The key means "the player is held steady on screen", so it also changes
404
+ how the `Player` hovers. Without it the hover spring (and the fall-faster
405
+ pull) is an impulse, pushed once per drawn frame, while gravity pulls once
406
+ per fixed 1/60 physics step, and a frame takes none, one or two steps: on
407
+ a frame that is not exactly one step the player is kicked up or let drop,
408
+ a bob of 0.6 to 2 cm walking on a phone, which a camera that holds the
409
+ player still would show as the whole view bobbing. The terms:
410
+ > With the key absent, the Player makes the calls on `scene.physics3d` it
411
+ > made before, with the same arguments, in the same order. With the key
412
+ > present, the hover and the fall-faster pull are forces
413
+ > (`scene.physics3d.addForce`), which act once per physics step as gravity
414
+ > does: walking on flat ground the player's height does not move, whatever
415
+ > the frame lengths. The spring is the same one (160 and 18), resting
416
+ > 1.38 cm higher (`STEADY_REST`) so that the kit's player (gravity scale
417
+ > 2) stands where it does without the key, 0.7412 m, to within 0.01 mm; a
418
+ > jump reaches 2.348 m (2.347 on alternating frames) where without the key
419
+ > it reaches 2.347 to 2.354 m depending on the frames. A player with
420
+ > another gravity scale stands 0.69 cm per unit of scale off its keyless
421
+ > height. The walk push is an impulse either way (it leaves the height
422
+ > alone, and the rigid camera does not show its unevenness).
423
+
424
+ The rule for forces: **a force is for the frame it was asked in.** rapier
425
+ keeps a force on a body until it is reset, so nothing outside the physics
426
+ system puts one on a body. `addForce(actor, v)` writes down what was asked
427
+ (asking again in the frame adds; `resetForces(actor)` drops it: the
428
+ Player does that on the frame of a jump, or the frame's lift would add
429
+ 11 cm to it); the physics pass puts the forces on their bodies just before
430
+ the frame's fixed steps and takes them off straight after, in a `finally`
431
+ (`stepForced`, systems/physics3d.js), however many steps there were. So
432
+ between frames no body carries a force, and each of these leaves none: the
433
+ Player not running (turned off, physics not ready) asks for nothing; a
434
+ player despawned after asking has no body by the pass; a scene load or a
435
+ dispose (`reset`) drops what was asked, so a door trip from a keyed scene
436
+ to one without the key starts clean; the key going away means the next
437
+ frame asks for nothing; a frame that never reached physics, or a force
438
+ asked for after the pass (from a collision callback), is not used in a
439
+ later frame (requests carry the scene time they were asked at). Code that
440
+ places the player through its body (the hub's fall catch, the multiplayer
441
+ kit's placement and clamps: `setTranslation` and a zero velocity, after
442
+ physics) needs nothing new: there is no force to clear. A behavior that
443
+ wants a steady push asks every frame from `update`, and stops by not
444
+ asking. scripts/test-steady-hover.mjs holds all of it, on a stand-in
445
+ rapier and, where rapier is installed, on rapier itself.
446
+ - `"engine": { "camera": { "follow": "rigid", "control": "orbit" } }` (the
447
+ same `camera` object) asks the `Player` behavior for a third-person camera
448
+ the player controls: they turn it, tilt it and zoom it, walking is
449
+ relative to it, and the character turns to face the way it walks. Without
450
+ it the Player drives like a tank (A/D and a sideways drag steer, the
451
+ camera stays behind) and the camera's height and distance are the fixed
452
+ `camHeight` and `camDistance`. The terms:
453
+ > With `control` absent, everything is exactly as before: the same code,
454
+ > the same calls on `scene.physics3d` in the same order, the same camera,
455
+ > the same listeners on the canvas, for a scene with no camera key and for
456
+ > one with `"follow": "rigid"` alone. `control` means something only as
457
+ > exactly `"orbit"` beside exactly `"follow": "rigid"`; anything else, or
458
+ > `"orbit"` without the rigid follow, is as absent. The key is read when
459
+ > the scene loads (`scene.cameraControl`, `'orbit'` or `null`), as the
460
+ > other engine keys are. With the key present the Player hovers, jumps and
461
+ > falls as it does under `"follow": "rigid"` (forces), and the camera
462
+ > moves with the player as that one does: the player's ground position is
463
+ > not eased, its height is.
464
+
465
+ Controls under the key:
466
+ - Touch and pen: a drag that starts in the left half of the canvas is the
467
+ movement stick (the same stick, `scene.moveInput`: 56 px to full
468
+ deflection, analogue). A drag that starts in the right half turns and
469
+ tilts the camera, 0.006 rad per CSS pixel: dragging right swings the
470
+ view right, dragging up looks up (the camera goes lower). The left half
471
+ is the stick's: a finger that lands there is never part of a pinch, so
472
+ a thumb put down to walk while the other looks walks, and two thumbs
473
+ put down together walk and look. Two fingers that both landed in the
474
+ right half (the second while the first is still a tap or turning the
475
+ camera) are a pinch: fingers apart bring the camera nearer; while they
476
+ pinch neither turns the camera, a finger in the left half can still
477
+ take the stick, and the finger left when one lifts does nothing more
478
+ until it lifts too. A second drag in the left half while the stick is
479
+ held does nothing. A short tap that did not move still jumps, anywhere;
480
+ a finger that was part of a pinch, or left spent, never jumps.
481
+ - Mouse: a drag with any button turns and tilts, and is never the stick;
482
+ the wheel zooms, a tenth per notch; the context menu is kept off the
483
+ canvas. A left click that did not move jumps.
484
+ - Keys: W/S and up/down walk away from and toward the camera, A/D
485
+ strafe, left/right swing the camera, Space jumps.
486
+
487
+ What the Player's properties mean under it: `speed` and `jumpSpeed` are
488
+ what they were. `turnSpeed` is how fast left/right swing the camera,
489
+ rad/s; the character itself turns to face its walk at a fixed 12/s.
490
+ The character faces the way it walks; standing still it keeps its
491
+ facing. It starts facing away from the camera (PI - camAngle, as without
492
+ the key). Without the key its facing is always PI - camAngle, so code
493
+ that turns it sets camAngle; under the key the camera and the character
494
+ turn apart, and turning the character is asked for: `scene.faceRequest =
495
+ <radians>`, taken once by the Player's next update (a value that is not
496
+ a finite number is dropped) and dropped by a scene load. The hub asks
497
+ this way beside each of its camAngle writes (its arrival facing, a jump
498
+ to a door); any other deck that turns the player must do the same, since
499
+ a camAngle written without a request turns only the camera. The
500
+ player's own left/right and drags turn the camera only.
501
+ `camDistance` and `camHeight` are where the camera starts: its distance
502
+ from the point it looks at is `hypot(camDistance, camHeight - 0.8)` and
503
+ its tilt `atan2(camHeight - 0.8, camDistance)`, which is where the fixed
504
+ camera sits. It looks at the player 0.8 m above its Transform (the fixed
505
+ cameras look 0.5 m above).
506
+
507
+ Limits: the tilt stays between 5 and 70 degrees above the horizontal and
508
+ the distance between 3 and 12 m; a Player whose numbers start it nearer
509
+ or farther has room to where it starts, and a starting tilt outside the
510
+ limits is brought inside. What is asked is eased in at 20/s.
511
+
512
+ Collision: each frame one ray goes from the point the camera is placed
513
+ from (the player, with its height eased as the camera eases it, 0.8 m
514
+ up) toward where the camera wants to be, as far as its distance and
515
+ 0.25 m past it, against fixed bodies' solid colliders only
516
+ (`scene.physics3d.castRayFixed(origin, dir, maxToi)`: like `castRay`,
517
+ passing through sensors and dynamic and kinematic bodies; other players
518
+ and thrown things do not move the camera). What it finds is a limit on
519
+ how far out the camera may be: 0.25 m in front of the hit, never nearer
520
+ the look point than 0.6 m. A nearer limit is taken at once; a farther
521
+ one, or none, is eased out to at 6/s and let go once the camera is back
522
+ at its distance. The camera sits at the nearer of its eased distance and
523
+ that limit, so zooming in while held in front of a wall brings it no
524
+ nearer until the distance asked is nearer than the wall, and it never
525
+ goes past the player; the view is never inside a wall and never pops
526
+ outward. While a takeover blend lasts (below) the point actually drawn,
527
+ its place plus what is left of the blend, is collided the same way with
528
+ a second ray: pulled in along its own line to 0.25 m in front of what is
529
+ in the way, and the next frame eases on from there. Settled, one ray a
530
+ frame. No ray is cast on a frame physics has no world.
531
+
532
+ There is no return-behind (no swinging the camera back behind a walking
533
+ player when it is left alone): walking forward already keeps the camera
534
+ behind, and chasing a strafe would turn a straight walk into a circle.
535
+
536
+ Where the state is. The yaw is `scene.persistent.camAngle`, with the
537
+ meaning it always had (the camera sits at player + (-d sin, h, d cos) of
538
+ it), so code that reads or sets it (the hub's arrival facing) works as
539
+ before; a yaw set a full turn away is reached the short way round. The
540
+ tilt and distance the player chose are client-only: they are on the
541
+ runtime (`scene.cameraOrbit`), which a scene load does not replace, so
542
+ they carry from scene to scene (a Player with other
543
+ `camDistance`/`camHeight` starts from its own), and are never on
544
+ `scene.persistent`, which the multiplayer kit sends. What the camera is
545
+ doing between frames is on the actor's `runtime`, which a scene load
546
+ rebuilds. `scene.lookInput` (engine3d/orbitinput.js) holds what the
547
+ pointers asked for until the Player takes it, once a frame; it is made
548
+ the first time a pointer goes down under the key or a Player runs under
549
+ it (`scene.orbitInput()`), so a runtime that never meets the key has
550
+ none.
551
+
552
+ When something else has the camera. A teleport (more than 3 m in a
553
+ frame) snaps it, and so does a camera more than 20 m from its place. The
554
+ camera is the player's to steer on a frame only when the Player also
555
+ placed it on the frame before (so a Player turned off, even for a frame
556
+ and even by a collision callback after its update, does not come back to
557
+ a queued drag), the camera is where the Player left it, and the look
558
+ input is not locked. `scene.lookInput.lock()` makes the next take empty
559
+ and drops what was asked; the hub calls it each frame of a door trip
560
+ under the key (beside its `lockInput`), so a drag made during a
561
+ trip neither moves the trip's camera nor turns the view when it ends. On
562
+ any frame the camera is not where the Player left it (a hub trip writes
563
+ it every frame; the first frame of a scene; a Player turned off and on)
564
+ the Player starts again from the chosen tilt and distance and eases on
565
+ from where the camera was put (a twentieth of the way left after 0.3 s).
566
+
567
+ Loads. A scene without the key, loaded after one with it, runs the code
568
+ it always ran from its first frame: the latch is per load, and the
569
+ Player's and the input's branches each read it once. On every scene
570
+ load and on dispose the physics system's `reset` resets the orbit input
571
+ (`scene.lookInput.reset()`, only when it is the one orbitinput.js made:
572
+ `isOrbitLook`): every pointer it holds is let go of (the stick released
573
+ if one of them held it, no tap), what was asked of the camera is
574
+ dropped, and the wheel and context-menu listeners are taken off; a keyed
575
+ scene's Player puts the listeners back on its first frame. A
576
+ `faceRequest` not yet taken is dropped on every load, whether or not the
577
+ orbit input was ever made. A tap already taken as a jump and not yet
578
+ used carries across a load with or without the key, as it always has. A
579
+ runtime that never met the key has no orbit input.
580
+ So a finger held across any load into or out of a keyed scene, or
581
+ between two keyed scenes, does nothing more until it lifts: the old
582
+ handlers do not know it either. A finger the old handlers hold across a
583
+ load into a keyed scene keeps their stick until it lifts or a pointer
584
+ goes down under the key, which lets go of everything they hold; only
585
+ one of the two ever writes the stick. scripts/test-camera-orbit.mjs
586
+ holds all of it, with the Player as it was before the key
587
+ (scripts/Player.before-orbit.mjs) and Scene3DPlayer's `attachInput` as
588
+ it was (scripts/Scene3DPlayer.before-orbit.jsx) as the references for
589
+ the scenes without it, and the loads, the lock and a Player turned off
590
+ and on run through physics-2d's SceneRuntime and Scene3DPlayer's own
591
+ `attachInput`.
340
592
  - `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
341
593
  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
342
594
  stage to place), orbit camera (drag orbits, wheel zooms), click to select /