castle-web-cli 0.4.204 → 0.4.205

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 (125) hide show
  1. package/dist/agent-failures.d.ts +3 -1
  2. package/dist/agent-failures.js +19 -0
  3. package/dist/agent-prompts.js +2 -1
  4. package/dist/agent.d.ts +3 -2
  5. package/dist/agent.js +19 -10
  6. package/dist/castle-host/host.d.ts +17 -0
  7. package/dist/castle-host/host.js +551 -4
  8. package/dist/devSessionStorage.js +65 -4
  9. package/dist/effortSupport.d.ts +7 -0
  10. package/dist/effortSupport.js +31 -0
  11. package/dist/init.js +13 -3
  12. package/dist/platformDoc.js +6 -1
  13. package/dist/serve.js +35 -2
  14. package/dist/shell/assets/{index-DHzA0-Sj.js → index-hWQTC8q6.js} +5 -5
  15. package/dist/shell/index.html +1 -1
  16. package/dist/vitePlugins.js +19 -1
  17. package/kits/base/CLAUDE.md +2 -0
  18. package/kits/base/castle.json +1 -1
  19. package/kits/base/sdk/README.md +131 -0
  20. package/kits/base/sdk/agent.d.ts +6 -0
  21. package/kits/base/sdk/agent.js +70 -0
  22. package/kits/base/sdk/castle.d.ts +4 -0
  23. package/kits/base/sdk/castle.js +2 -0
  24. package/kits/base/sdk/commands.d.ts +106 -0
  25. package/kits/base/sdk/commands.js +21 -0
  26. package/kits/base/sdk/decks.d.ts +7 -0
  27. package/kits/base/sdk/decks.js +31 -0
  28. package/kits/base/sdk/runtime.d.ts +4 -2
  29. package/kits/base/sdk/runtime.js +51 -40
  30. package/kits/base/sdk/server/storage.d.ts +44 -0
  31. package/kits/base/sdk/server/storage.js +54 -0
  32. package/kits/base/sdk/transport.d.ts +5 -1
  33. package/kits/base/sdk/transport.js +106 -23
  34. package/kits/multiplayer-2d/castle.json +4 -4
  35. package/kits/multiplayer-2d/code/client/poses.js +7 -0
  36. package/kits/multiplayer-2d/code/server/limits.js +3 -0
  37. package/kits/multiplayer-2d/code/server/ownership.js +36 -8
  38. package/kits/multiplayer-2d/code/systems/multiplayer.js +23 -2
  39. package/kits/multiplayer-3d/CLAUDE.md +12 -1
  40. package/kits/multiplayer-3d/castle.json +4 -4
  41. package/kits/multiplayer-3d/code/client/avatars.js +7 -1
  42. package/kits/multiplayer-3d/code/client/poses.js +61 -1
  43. package/kits/multiplayer-3d/code/client/steer.js +383 -0
  44. package/kits/multiplayer-3d/code/server/limits.js +3 -0
  45. package/kits/multiplayer-3d/code/server/ownership.js +114 -18
  46. package/kits/multiplayer-3d/code/server/world.js +12 -4
  47. package/kits/multiplayer-3d/code/systems/multiplayer.js +315 -34
  48. package/kits/physics-3d/CLAUDE.md +65 -7
  49. package/kits/physics-3d/castle.json +3 -3
  50. package/kits/physics-3d/docs/pxmodel-format.md +916 -15
  51. package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
  52. package/kits/physics-3d/engine3d/artobjects.js +218 -0
  53. package/kits/physics-3d/engine3d/blob.js +1058 -0
  54. package/kits/physics-3d/engine3d/branches.js +300 -0
  55. package/kits/physics-3d/engine3d/cage.js +496 -0
  56. package/kits/physics-3d/engine3d/cageops.js +516 -0
  57. package/kits/physics-3d/engine3d/frame.js +669 -0
  58. package/kits/physics-3d/engine3d/look.js +675 -0
  59. package/kits/physics-3d/engine3d/materialpresets.js +486 -0
  60. package/kits/physics-3d/engine3d/modelEditorWorld.js +3 -2
  61. package/kits/physics-3d/engine3d/modelrefs.js +120 -0
  62. package/kits/physics-3d/engine3d/motion.js +560 -0
  63. package/kits/physics-3d/engine3d/objtext.js +37 -0
  64. package/kits/physics-3d/engine3d/optimize.js +1083 -0
  65. package/kits/physics-3d/engine3d/paint.js +674 -0
  66. package/kits/physics-3d/engine3d/partgeometry.js +467 -0
  67. package/kits/physics-3d/engine3d/paths.js +324 -0
  68. package/kits/physics-3d/engine3d/pxmodel.js +429 -26
  69. package/kits/physics-3d/engine3d/scatter.js +102 -0
  70. package/kits/physics-3d/engine3d/sculpt.js +1148 -0
  71. package/kits/physics-3d/engine3d/surfacedetail.js +267 -0
  72. package/kits/physics-3d/engine3d/sweep.js +480 -0
  73. package/kits/physics-3d/engine3d/thumbnails.js +6 -4
  74. package/kits/physics-3d/engine3d/world3d.js +119 -17
  75. package/kits/physics-3d/eslint.config.js +13 -0
  76. package/kits/physics-3d/models/parts/axe.pxmodel +40 -0
  77. package/kits/physics-3d/models/parts/backpack.pxmodel +47 -0
  78. package/kits/physics-3d/models/parts/barrel.pxmodel +22 -0
  79. package/kits/physics-3d/models/parts/bedroll.pxmodel +28 -0
  80. package/kits/physics-3d/models/parts/belt-pouch.pxmodel +22 -0
  81. package/kits/physics-3d/models/parts/bolt.pxmodel +10 -0
  82. package/kits/physics-3d/models/parts/bracer.pxmodel +26 -0
  83. package/kits/physics-3d/models/parts/chain-span.pxmodel +12 -0
  84. package/kits/physics-3d/models/parts/chimney.pxmodel +11 -0
  85. package/kits/physics-3d/models/parts/crate.pxmodel +44 -0
  86. package/kits/physics-3d/models/parts/crystal.pxmodel +22 -0
  87. package/kits/physics-3d/models/parts/door-arched.pxmodel +12 -0
  88. package/kits/physics-3d/models/parts/engine-block.pxmodel +39 -0
  89. package/kits/physics-3d/models/parts/exhaust-pipe.pxmodel +30 -0
  90. package/kits/physics-3d/models/parts/fence-span.pxmodel +10 -0
  91. package/kits/physics-3d/models/parts/fender.pxmodel +19 -0
  92. package/kits/physics-3d/models/parts/headlight.pxmodel +24 -0
  93. package/kits/physics-3d/models/parts/hood.pxmodel +17 -0
  94. package/kits/physics-3d/models/parts/horned-helmet.pxmodel +37 -0
  95. package/kits/physics-3d/models/parts/jerry-can.pxmodel +26 -0
  96. package/kits/physics-3d/models/parts/ladder.pxmodel +10 -0
  97. package/kits/physics-3d/models/parts/lamp.pxmodel +20 -0
  98. package/kits/physics-3d/models/parts/lantern.pxmodel +30 -0
  99. package/kits/physics-3d/models/parts/leaf-cluster.pxmodel +21 -0
  100. package/kits/physics-3d/models/parts/offroad-tire.pxmodel +48 -0
  101. package/kits/physics-3d/models/parts/pauldron.pxmodel +26 -0
  102. package/kits/physics-3d/models/parts/rivet.pxmodel +8 -0
  103. package/kits/physics-3d/models/parts/rock.pxmodel +21 -0
  104. package/kits/physics-3d/models/parts/roll-bar-light.pxmodel +26 -0
  105. package/kits/physics-3d/models/parts/round-shield.pxmodel +31 -0
  106. package/kits/physics-3d/models/parts/saddlebag.pxmodel +30 -0
  107. package/kits/physics-3d/models/parts/spoked-wheel.pxmodel +39 -0
  108. package/kits/physics-3d/models/parts/staff.pxmodel +33 -0
  109. package/kits/physics-3d/models/parts/stepping-stones.pxmodel +8 -0
  110. package/kits/physics-3d/models/parts/stone-base.pxmodel +10 -0
  111. package/kits/physics-3d/models/parts/sword.pxmodel +33 -0
  112. package/kits/physics-3d/models/parts/window-lit.pxmodel +13 -0
  113. package/kits/physics-3d/models/parts/wizard-hat.pxmodel +28 -0
  114. package/kits/physics-3d/models/templates/biped-stout.pxmodel +59 -0
  115. package/kits/physics-3d/models/templates/biped-tall.pxmodel +63 -0
  116. package/kits/physics-3d/models/templates/quadruped.pxmodel +52 -0
  117. package/kits/physics-3d/scripts/render/filmstrip.js +217 -0
  118. package/kits/physics-3d/scripts/render/index.html +20 -0
  119. package/kits/physics-3d/scripts/render/sheet.js +411 -0
  120. package/kits/physics-3d/scripts/render.mjs +646 -0
  121. package/kits/real-time/castle.json +2 -2
  122. package/kits/real-time/code/client/ownership.js +14 -4
  123. package/kits/real-time/code/client/smooth.js +2 -2
  124. package/kits/real-time/code/server/session.js +20 -4
  125. package/package.json +2 -2
@@ -20,7 +20,10 @@ const DEG = Math.PI / 180;
20
20
  // world the rapier world
21
21
  // bodies actor id -> rapier body, for every scene actor with a shape
22
22
  // objects actor id -> { body, home, claimable, fast, owner, reportedAt,
23
- // claimedAt }
23
+ // claimedAt, epoch, ack }. `epoch` counts the object's
24
+ // handovers; `ack` is the acknowledgement of its owner's last
25
+ // report, waiting for the next broadcast, or null
26
+ // staleReports how many owner reports were dropped for an old epoch
24
27
  // doors [{ body, props, baseY, openT }]
25
28
  // players playerId -> { body, at, facing, clamped, movedAt }
26
29
  // spawn where players come in
@@ -40,6 +43,7 @@ function emptySim() {
40
43
  template: null,
41
44
  acc: 0,
42
45
  timeMs: 0,
46
+ staleReports: 0,
43
47
  };
44
48
  }
45
49
 
@@ -105,6 +109,8 @@ function buildScene(sim) {
105
109
  owner: null,
106
110
  reportedAt: 0,
107
111
  claimedAt: 0,
112
+ epoch: 0,
113
+ ack: null,
108
114
  });
109
115
  }
110
116
  }
@@ -300,12 +306,14 @@ function driveDoor(sim, door, dt) {
300
306
  // Reading it out
301
307
  //
302
308
 
303
- // Pack every indexed dynamic or kinematic object's current Rapier pose.
304
- // `server/index.js` filters unchanged entries before broadcasting a STATE delta.
309
+ // Pack every indexed dynamic or kinematic object's current Rapier pose, followed
310
+ // by its epoch. A client drops a pose from an epoch older than the newest
311
+ // handover it has seen for the object. The session filters unchanged entries
312
+ // before broadcasting a STATE delta, and a new epoch counts as a change.
305
313
  export function objectPoses(sim) {
306
314
  const out = [];
307
315
  for (const [id, entry] of sim.objects) {
308
- out.push([id, ...packPose(entry.body.translation(), entry.body.rotation())]);
316
+ out.push([id, ...packPose(entry.body.translation(), entry.body.rotation()), entry.epoch]);
309
317
  }
310
318
  return out;
311
319
  }
@@ -1,6 +1,11 @@
1
1
  // Engine system that connects a deck runtime to the shared multiplayer session.
2
2
  // It receives timestamped state, draws other players' actors and objects, reconciles the
3
3
  // local player, and reports locally simulated poses after engine behaviors run.
4
+ //
5
+ // A shared object is in one of three states on this client. An owned object is
6
+ // simulated here and reported. A live object near this player runs as a local
7
+ // body steered toward the network's present (`client/steer.js`). Any other
8
+ // object is drawn from interpolated network poses a render delay behind.
4
9
 
5
10
  import * as Avatars from '../client/avatars.js';
6
11
  import * as Clock from '@imports/castle.real-time/code/client/clock.js';
@@ -8,6 +13,7 @@ import * as Interpolate from '@imports/castle.real-time/code/client/interpolate.
8
13
  import * as Ownership from '@imports/castle.real-time/code/client/ownership.js';
9
14
  import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js';
10
15
  import * as Poses from '../client/poses.js';
16
+ import * as Steer from '../client/steer.js';
11
17
  import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
12
18
  import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
13
19
  import { showJoinOverlay } from '@imports/castle.real-time/code/client/joinOverlay.js';
@@ -23,6 +29,19 @@ import { game } from '@imports/castle.real-time/code/client/gameHooks.js';
23
29
  const CLAMP_EASE = 0.25;
24
30
  const CLAMP_SNAP = 4;
25
31
 
32
+ // A new owner of an object that was not live starts it at its newest network
33
+ // pose moved forward by its velocity to the present. A sample older than this
34
+ // is used where it is.
35
+ const PROJECT_CAP_MS = 150;
36
+
37
+ // An interpolated body within this of the pose last written to it is not
38
+ // written again.
39
+ const WRITTEN_SLACK = 0.005;
40
+
41
+ // A moving object in the WORLD snapshot also gets a pose this far back along
42
+ // its velocity, so interpolation has two poses to move it between at once.
43
+ const JOIN_BACK_MS = 250;
44
+
26
45
  // A deck may provide its own multiplayer system. The engine registry permits
27
46
  // duplicate systems, which would create duplicate session connections, so these
28
47
  // lazy globs detect deck-owned files without evaluating them. Vite excludes the
@@ -66,10 +85,31 @@ class MultiplayerSystem {
66
85
  // The clock maps page time to delayed server simulation time.
67
86
  this.clock = Clock.makeClock();
68
87
 
69
- // Ownership records objects currently simulated by this client.
88
+ // Ownership records objects currently simulated by this client. `granted`
89
+ // holds each new grant's velocity until its body is placed, and `releasing`
90
+ // holds the final report of an object let go of until a movement packet
91
+ // carries it.
70
92
  this.own = Ownership.makeOwnership();
71
-
72
- // Smoothing retains the pose displayed for each network-drawn id.
93
+ this.granted = new Map();
94
+ this.releasing = new Map();
95
+
96
+ // The newest handover seen for each object, `{ velocity, epoch, asleep }`,
97
+ // and the newest acknowledgement of this client's reports on each object,
98
+ // `[epoch, lastSeq, tAck, ageApplied, vetoedSeq]`. `moveSeq` numbers the
99
+ // movement packets sent, and `staleSamples` counts object poses dropped
100
+ // for an old epoch.
101
+ this.handed = new Map();
102
+ this.acks = new Map();
103
+ this.moveSeq = 0;
104
+ this.staleSamples = 0;
105
+
106
+ // `live` holds the steering state of each live object and each owned one,
107
+ // which is live once it is let go. `written` holds the pose last written to
108
+ // each interpolated object.
109
+ this.live = new Map();
110
+ this.written = new Map();
111
+
112
+ // Smoothing retains the pose displayed for each interpolated id.
73
113
  this.shown = Smoothing.makeSmoothing();
74
114
 
75
115
  // Avatar state maps other players to spawned actors and name tags.
@@ -132,7 +172,7 @@ class MultiplayerSystem {
132
172
  // timestamp establishes a clock offset.
133
173
  const at = Clock.ready(this.clock) ? Clock.renderTime(this.clock, performance.now()) : null;
134
174
  if (at !== null) {
135
- this.applyObjectPoses(scene, at, dt);
175
+ this.applyObjectPoses(scene, at, dt, local);
136
176
  this.applyPlayerPoses(scene, at, dt);
137
177
  }
138
178
 
@@ -211,7 +251,9 @@ class MultiplayerSystem {
211
251
 
212
252
  // Apply ownership first so an object granted this tick stops receiving
213
253
  // network poses on the same frame local simulation begins.
214
- Ownership.applyHandovers(this.own, msg.own, selfId);
254
+ Ownership.applyHandovers(this.own, msg.own, selfId, performance.now());
255
+ noteGrants(this.granted, msg.own, selfId);
256
+ this.noteHandovers(msg);
215
257
  for (const [id, x, y, z, facing, clamped] of msg.ps ?? []) {
216
258
  if (id !== selfId) {
217
259
  sample(this.players, msg, id, [x, y, z, facing]);
@@ -225,46 +267,220 @@ class MultiplayerSystem {
225
267
  this.clampedTo = { x, y, z };
226
268
  }
227
269
  }
228
- for (const [id, ...pose] of msg.os ?? []) {
229
- sample(this.objects, msg, id, pose);
270
+ for (const [id, ...row] of msg.os ?? []) {
271
+ this.sampleObject(msg, id, row);
272
+ }
273
+ for (const [id, ...ack] of msg.ack ?? []) {
274
+ this.acks.set(id, ack);
230
275
  }
231
276
 
232
277
  // Let the deck read its added fields after kit poses and handovers are
233
278
  // available through the system state.
234
279
  game.state?.(scene, msg, this);
235
280
  }
281
+ this.placeGrants(scene);
282
+ }
283
+
284
+ // Record the newest handover of each object. A handover row is `[id, owner,
285
+ // vx, vy, vz, wx, wy, wz, epoch]`, and a WORLD row adds 1 when the object is
286
+ // asleep. `simMs` is the handover's simulation time. After the snapshot, a
287
+ // handover also starts the object's track over from where it is drawn, so no
288
+ // pose from the previous holder is blended with the next holder's.
289
+ noteHandovers(msg) {
290
+ for (const [id, , ...rest] of msg.own ?? []) {
291
+ // A server from before epochs sends the owner alone.
292
+ if (rest.length < 7) {
293
+ continue;
294
+ }
295
+ this.handed.set(id, {
296
+ velocity: rest.slice(0, 6),
297
+ epoch: rest[6],
298
+ asleep: rest[7] === 1,
299
+ simMs: msg.t,
300
+ });
301
+ if (msg.k !== WORLD) {
302
+ this.restartTrack(id);
303
+ }
304
+ }
305
+ }
306
+
307
+ // Replace an object's track with one sample, the pose drawn now at the render
308
+ // time. The next pose to arrive is blended from there. A live or owned object
309
+ // is not drawn from its track, and its track is emptied.
310
+ restartTrack(id) {
311
+ const drawn = this.shown.get(id);
312
+ if (!drawn || !Clock.ready(this.clock)) {
313
+ this.objects.delete(id);
314
+ return;
315
+ }
316
+ const track = Interpolate.makeTrack();
317
+ const at = Clock.renderTime(this.clock, performance.now());
318
+ Interpolate.pushSample(track, at, drawn.slice(), Poses.same);
319
+ this.objects.set(id, track);
320
+ }
321
+
322
+ // File one object pose. A row is the pose followed by the epoch it was sent
323
+ // under, and a pose from before the newest handover seen is dropped.
324
+ sampleObject(msg, id, row) {
325
+ const pose = row.slice(0, 7);
326
+ const handed = this.handed.get(id);
327
+ if (row[7] < handed?.epoch) {
328
+ this.staleSamples += 1;
329
+ return;
330
+ }
331
+ if (msg.k !== WORLD) {
332
+ sample(this.objects, msg, id, pose);
333
+ return;
334
+ }
335
+
336
+ // A snapshot replaces the track. A moving object gets a pose projected back
337
+ // along its velocity first.
338
+ const track = Interpolate.makeTrack();
339
+ if (handed && !handed.asleep) {
340
+ const back = Poses.project(pose, handed.velocity, -JOIN_BACK_MS / 1000);
341
+ Interpolate.pushSample(track, msg.t - JOIN_BACK_MS, back, Poses.same);
342
+ }
343
+ Interpolate.pushSample(track, msg.t, pose, Poses.same);
344
+ this.objects.set(id, track);
345
+ }
346
+
347
+ // Place the body of each object granted this frame, before the next physics
348
+ // step, and give it the handover's velocity. A live body is already at the
349
+ // present, and carries on from where it is. Any other starts at the newest
350
+ // network pose moved forward by the handover's velocity, which is where the
351
+ // last owner had it, so this client's reports carry on from that owner's.
352
+ placeGrants(scene) {
353
+ const now = performance.now();
354
+ for (const [id, velocity] of this.granted) {
355
+ const body = scene.physics3d?.bodyOf(id);
356
+ const transform = scene.getActor(id)?.components.Transform;
357
+ const newest = this.objects.get(id)?.samples.at(-1);
358
+ if (!body || !transform) {
359
+ continue;
360
+ }
361
+ if (newest?.pose.length === 7 && !this.live.has(id)) {
362
+ const age = Clock.ready(this.clock)
363
+ ? Clock.renderTime(this.clock, now) + this.clock.delay - newest.simMs
364
+ : Infinity;
365
+ const seed =
366
+ age >= 0 && age <= PROJECT_CAP_MS
367
+ ? Poses.project(newest.pose, velocity, age / 1000)
368
+ : newest.pose;
369
+ body.setTranslation({ x: seed[0], y: seed[1], z: seed[2] }, true);
370
+ body.setRotation(Poses.quatOf(seed), true);
371
+
372
+ // The Transform follows the body at the next physics step. It is moved
373
+ // now so this frame's reach checks and report read the seed as well.
374
+ Poses.applyPose(transform, seed);
375
+ }
376
+ const [vx, vy, vz, wx, wy, wz] = velocity;
377
+ body.setLinvel({ x: vx, y: vy, z: vz }, true);
378
+ body.setAngvel({ x: wx, y: wy, z: wz }, true);
379
+ }
380
+ this.granted.clear();
236
381
  }
237
382
 
238
383
  //
239
384
  // Applying the room state
240
385
  //
241
386
 
242
- // Apply server-simulated scene object poses at one delayed simulation timestamp.
243
- applyObjectPoses(scene, at, dt) {
387
+ // Apply the network's object poses. `at` is the delayed render time, and the
388
+ // server's present is one render delay after it.
389
+ applyObjectPoses(scene, at, dt, local) {
244
390
  const phys = scene.physics3d;
391
+ const now = performance.now();
392
+ const me = this.placedTo ?? local?.components.Transform ?? null;
393
+
394
+ // The engine's physics system keeps its rapier world on `world`. Its
395
+ // `scene.physics3d` API has no shape casts, which steering needs.
396
+ const world = scene.systems.find((system) => system.world?.castShape)?.world ?? null;
397
+ const player = (local && phys?.bodyOf(local)) ?? null;
245
398
  for (const [id, track] of this.objects) {
246
- // Skip locally owned objects. Applying the older server pose would
247
- // overwrite local Rapier motion and prevent a local push from taking effect.
399
+ const actor = scene.getActor(id);
400
+ const transform = actor?.components.Transform;
401
+ if (!transform) {
402
+ continue;
403
+ }
404
+ const body = phys?.bodyOf(actor);
405
+ const dynamic = Boolean(body?.isDynamic());
406
+
407
+ // An owned object is simulated here, and is live once it is let go.
408
+ // Writing the older network pose over it would undo a local push.
248
409
  if (this.own.mine.has(id)) {
410
+ if (dynamic) {
411
+ this.live.set(id, Steer.makeState());
412
+ }
249
413
  Smoothing.forget(this.shown, id);
414
+ this.written.delete(id);
250
415
  continue;
251
416
  }
252
- const actor = scene.getActor(id);
417
+ const network = dynamic
418
+ ? Steer.sweep(
419
+ world,
420
+ body,
421
+ Steer.networkAt(track, this.handed.get(id), at + this.clock.delay),
422
+ player,
423
+ )
424
+ : null;
425
+ if (network && this.isLive(id, network, body, transform, me)) {
426
+ Steer.steer(body, network, this.live.get(id), dt, now, world, player);
427
+ } else if (!this.live.has(id)) {
428
+ this.drawInterpolated(id, track, actor, body, at, dt);
429
+ }
430
+ }
431
+ }
253
432
 
254
- // Sample between the two history entries bracketing the render time.
255
- const sampled = actor?.components.Transform && Interpolate.sampleAt(track, at, Poses.blend);
256
- if (!sampled) {
257
- continue;
433
+ // Whether an object runs as a live body this frame, moving it between live and
434
+ // interpolated where that is allowed. At rest, an object is live within
435
+ // `Steer.LIVE_RADIUS` of this player and interpolated beyond it. A moving
436
+ // object keeps its state, except that one within claim reach, or one not yet
437
+ // drawn, becomes live.
438
+ isLive(id, network, body, transform, me) {
439
+ const distance = me ? Poses.flatDistance(me, transform) : Infinity;
440
+ if (this.live.has(id)) {
441
+ if (distance > Steer.LIVE_RADIUS && network.resting && Steer.resting(body)) {
442
+ this.live.delete(id);
443
+ return false;
258
444
  }
445
+ return true;
446
+ }
447
+ const near = distance <= Steer.LIVE_RADIUS;
448
+ const fresh = !this.shown.has(id);
449
+ if (distance > Poses.REACH.radius && !(near && (network.resting || fresh))) {
450
+ return false;
451
+ }
259
452
 
260
- // Smooth the sampled target to absorb small steps from uneven delivery.
261
- const pose = Smoothing.smooth(this.shown, id, sampled, dt, Poses);
262
- Poses.applyPose(actor.components.Transform, pose);
453
+ // The body starts at the network's present. An object the snapshot said was
454
+ // asleep is left asleep.
455
+ Steer.place(body, network.pose, network.velocity, !this.handed.get(id)?.asleep);
456
+ Smoothing.forget(this.shown, id);
457
+ this.written.delete(id);
458
+ this.live.set(id, Steer.makeState());
459
+ return true;
460
+ }
461
+
462
+ // Draw an object from its track at the render time `at`, on both its Transform
463
+ // and its rapier body. A pose already written, with the body still there, is
464
+ // not written again, so a body at rest can sleep.
465
+ drawInterpolated(id, track, actor, body, at, dt) {
466
+ const sampled = Interpolate.sampleAt(track, at, Poses.blend);
467
+ if (!sampled) {
468
+ return;
469
+ }
263
470
 
264
- // Write both engine representations. Rapier copies a dynamic body pose back
265
- // over its Transform each frame, so changing only the Transform is temporary.
266
- writeBody(phys?.bodyOf(actor), pose);
471
+ // Smooth the sampled target to absorb small steps from uneven delivery.
472
+ const pose = Smoothing.smooth(this.shown, id, sampled, dt, Poses);
473
+ const written = this.written.get(id);
474
+ if (written && Poses.same(written, pose) && bodyAt(body, pose)) {
475
+ return;
267
476
  }
477
+ Poses.applyPose(actor.components.Transform, pose);
478
+
479
+ // Write both engine representations. Rapier copies a dynamic body pose back
480
+ // over its Transform each frame, so changing only the Transform is temporary.
481
+ // The first write leaves a body asleep when the snapshot said it was.
482
+ writeBody(body, pose, Boolean(written) || !this.handed.get(id)?.asleep);
483
+ this.written.set(id, pose.slice());
268
484
  }
269
485
 
270
486
  // Apply each other player's pose, spawning its avatar and name tag when needed.
@@ -368,30 +584,67 @@ class MultiplayerSystem {
368
584
  now,
369
585
  Poses.REACH,
370
586
  );
371
- const releases = Ownership.toRelease(this.own, objects, me, Poses.REACH);
372
587
 
373
588
  // Include only granted objects because the server rejects poses for other ids.
374
- const owned = [];
589
+ // Each pose is read from the Rapier body, and the velocity after it is what
590
+ // the object keeps when handed on. Poses are collected before releases so
591
+ // an object let go of this frame still sends where it was.
592
+ const owned = new Map();
375
593
  for (const [id, transform] of objects) {
376
- if (this.own.mine.has(id)) {
377
- owned.push([id, ...Poses.poseOf(transform)]);
594
+ if (!this.own.mine.has(id)) {
595
+ continue;
596
+ }
597
+ const body = scene.physics3d?.bodyOf(id);
598
+ const pose = body
599
+ ? Poses.packPose(body.translation(), body.rotation())
600
+ : Poses.poseOf(transform);
601
+ const velocity = body
602
+ ? Poses.packVelocity(body.linvel(), body.angvel())
603
+ : [0, 0, 0, 0, 0, 0];
604
+ owned.set(id, [id, ...pose, ...velocity, ...this.reportTail(id)]);
605
+ }
606
+ const releases = Ownership.toRelease(this.own, objects, me, Poses.REACH, now);
607
+ for (const id of releases) {
608
+ if (owned.has(id)) {
609
+ this.releasing.set(id, owned.get(id));
378
610
  }
379
611
  }
380
612
 
613
+ // A released object's final report goes out with the release, which may
614
+ // be several frames later when the send rate holds it.
615
+ for (const [id, entry] of this.releasing) {
616
+ owned.set(id, entry);
617
+ }
618
+
381
619
  // `sendMove` only goes out at MOVE_HZ; claims are held until it does. The
382
620
  // transport takes a packed pose, so the Transform is encoded here.
383
621
  // The state block rides in a move packet when it changed since the last one
384
622
  // that went out.
385
623
  const stateJson = JSON.stringify(scene.persistent ?? {});
386
624
  const state = stateJson === this.sentState ? undefined : (scene.persistent ?? {});
387
- if (this.net.sendMove(Poses.packMove(me), owned, claims, releases, state) && state) {
388
- this.sentState = stateJson;
625
+ if (this.net.sendMove(Poses.packMove(me), [...owned.values()], claims, releases, state)) {
626
+ this.moveSeq += 1;
627
+ this.releasing.clear();
628
+ if (state) {
629
+ this.sentState = stateJson;
630
+ }
389
631
  }
390
632
  Avatars.showSelf(this.avatars, scene, local, this.net.status().you, me, {
391
633
  userId: this.net.userId(this.net.selfId()),
392
634
  });
393
635
  }
394
636
 
637
+ // The end of an owned object's report: the epoch of this client's grant, the
638
+ // number of the packet it goes out in, and the last number the server
639
+ // acknowledged under that epoch. The epoch is null when this client has not
640
+ // seen one.
641
+ reportTail(id) {
642
+ const epoch = this.handed.get(id)?.epoch ?? null;
643
+ const ack = this.acks.get(id);
644
+ const base = ack && ack[0] === epoch ? ack[1] : 0;
645
+ return [epoch, this.moveSeq + 1, base];
646
+ }
647
+
395
648
  // Return `[id, Transform]` for every scene object known from server snapshots.
396
649
  // The default report uses this same set for claims, releases, and owned poses.
397
650
  claimable(scene) {
@@ -448,6 +701,8 @@ class MultiplayerSystem {
448
701
  delay: Math.round(this.clock.delay),
449
702
  ready: Clock.ready(this.clock),
450
703
  mine: [...this.own.mine],
704
+ live: [...this.live.keys()].filter((id) => !this.own.mine.has(id)),
705
+ stale: this.staleSamples,
451
706
  me: me ? [me.x, me.y, me.z] : null,
452
707
  players,
453
708
  objects,
@@ -474,6 +729,12 @@ class MultiplayerSystem {
474
729
  this.players.clear();
475
730
  this.objects.clear();
476
731
  this.own = Ownership.makeOwnership();
732
+ this.granted.clear();
733
+ this.releasing.clear();
734
+ this.handed.clear();
735
+ this.acks.clear();
736
+ this.live.clear();
737
+ this.written.clear();
477
738
  this.shown = Smoothing.makeSmoothing();
478
739
  this.clampedTo = null;
479
740
  this.placedTo = null;
@@ -571,14 +832,34 @@ function sample(tracks, msg, id, pose) {
571
832
  Interpolate.pushSample(track, msg.t, pose, Poses.same);
572
833
  }
573
834
 
835
+ // Record the velocity each handover to this player carries, for `placeGrants`.
836
+ function noteGrants(granted, handovers, selfId) {
837
+ for (const [id, playerId, ...rest] of handovers ?? []) {
838
+ if (playerId === selfId && rest.length >= 6) {
839
+ granted.set(id, rest.slice(0, 6));
840
+ }
841
+ }
842
+ }
843
+
574
844
  // Apply a full object pose directly to Rapier and clear residual velocities. A
575
- // later network sample supplies the next position and orientation.
576
- function writeBody(body, pose) {
845
+ // later network sample supplies the next position and orientation. `wake`
846
+ // false leaves a sleeping body asleep.
847
+ function writeBody(body, pose, wake) {
577
848
  if (!body || pose.length !== 7) {
578
849
  return;
579
850
  }
580
- body.setTranslation({ x: pose[0], y: pose[1], z: pose[2] }, true);
581
- body.setRotation(Poses.quatOf(pose), true);
582
- body.setLinvel({ x: 0, y: 0, z: 0 }, true);
583
- body.setAngvel({ x: 0, y: 0, z: 0 }, true);
851
+ body.setTranslation({ x: pose[0], y: pose[1], z: pose[2] }, wake);
852
+ body.setRotation(Poses.quatOf(pose), wake);
853
+ body.setLinvel({ x: 0, y: 0, z: 0 }, wake);
854
+ body.setAngvel({ x: 0, y: 0, z: 0 }, wake);
855
+ }
856
+
857
+ // Whether a body is within WRITTEN_SLACK of a pose's position. With no body,
858
+ // there is nothing to move back.
859
+ function bodyAt(body, pose) {
860
+ if (!body) {
861
+ return true;
862
+ }
863
+ const p = body.translation();
864
+ return Math.hypot(p.x - pose[0], p.y - pose[1], p.z - pose[2]) < WRITTEN_SLACK;
584
865
  }
@@ -64,13 +64,28 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
64
64
  - Blueprint thumbnails in the hotbar / inspector are live 3d corner-view
65
65
  renders of each template (engine3d/thumbnails.js) -- no icon data needed on
66
66
  the blueprint.
67
- - 3d models are `.pxmodel` files under `models/` -- part-based JSON (named
68
- primitive parts with hierarchy, per-part material/art), spec in
69
- docs/pxmodel-format.md. A `Model` behavior (`{ file, scale, yOffset }`)
70
- renders one instead of the Shape mesh; part ids legL/legR/armL/armR/torso
71
- walk-animate automatically from observed motion. `.pxmodel` opens in the
72
- kit's model editor (parts list, gizmos, part inspector, walk preview);
73
- `scenes/model-lab.scene` is an all-model scene for trying it.
67
+ - 3d models are `.pxmodel` files under `models/`: JSON parts in a hierarchy,
68
+ each of a kind -- `blob` (spheres and capsules melted into one surface) for
69
+ bodies, heads and anything organic; `mesh` from inline OBJ text for a
70
+ custom shape; lathe, extrude, tube, sweep, loft, torus, frame, branches and
71
+ rounded boxes for built things. Spec in docs/pxmodel-format.md; see Making
72
+ a model below. A `Model` behavior (`{ file, scale, yOffset }`) draws one
73
+ on an actor. `.pxmodel` opens in the kit's model editor;
74
+ `scenes/model-lab.scene` is an all-model scene for trying one.
75
+ - The kit ships character templates in
76
+ `imports/castle.physics-3d/models/templates/` (`biped-stout`, `biped-tall`,
77
+ `quadruped`) and a parts library in `models/parts/` (wheels, weapons,
78
+ helmets, hats, packs, lanterns, barrels, crates, doors, windows, fences),
79
+ used by reference: `{ "kind": "model", "src":
80
+ "@imports/castle.physics-3d/models/parts/<name>.pxmodel" }`.
81
+ - `npm run render -- models/<name>.pxmodel [more ...]` renders each model to
82
+ `.castle/render/<name>.png`: the game camera at game size plus eight
83
+ labeled views on a 1 m grid. It prints the model's cost (triangles against
84
+ the budget, draw calls, heaviest parts), which the sheet's header repeats.
85
+ `--motion` renders its animation as a filmstrip instead.
86
+ Read the png after every change to a model, the last change included;
87
+ about 7 s per call. A new model takes three or more renders: block-in,
88
+ fixes, then details.
74
89
  - Controls are tank-style: W/S (or up/down) walk forward/back along facing,
75
90
  A/D (or left/right) turn; a pointer/touch drag is a virtual stick where the
76
91
  drag angle blends walking and turning. Space jumps.
@@ -79,6 +94,41 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
79
94
  - After a coherent change: `npm run check` (lint + duplicate gate +
80
95
  single-file bundle) must pass.
81
96
 
97
+ ## Making a model
98
+
99
+ Read all of `docs/pxmodel-format.md` before writing a model. Then:
100
+
101
+ 1. Decide what makes this one distinctive: its silhouette and two or three
102
+ details that carry it.
103
+ 2. Block in the main forms. A character starts from a template: copy its
104
+ parts, keep their ids (they drive the walk), and reshape the blob shapes.
105
+ A template is a plain grey body; the face, hair, clothes and colors are
106
+ yours to add. Set the model's `height` and a `triangles` budget (props
107
+ 300-1500, characters 1500-8000, buildings 2500-6000).
108
+ 3. Render, and read every view. Fix what floats, clips, leaves a gap, shows
109
+ inside out or is out of proportion. A part can look right from the front
110
+ and wrong from the side or top.
111
+ 4. Add a few details, then render and fix again. Put detail on the
112
+ silhouette -- hems, rims, straps, pouches -- where it reads at game size.
113
+ Fill template slots and use library parts before modeling a wheel, a
114
+ helmet or a lantern yourself. Repeat this step two or three times.
115
+ 5. Animate with part ids the walk already moves, `motion` for loops (a tail,
116
+ a flame, a spinning wheel) and `clips` for actions; check with
117
+ `npm run render -- --motion`.
118
+ 6. Finish on a render taken after the last edit, with every view clean and
119
+ the triangle count within the budget. A finished model has been rendered
120
+ at least three times.
121
+
122
+ `npm run render` prints each model's triangles against its budget and its
123
+ five heaviest parts. The kit already builds the heaviest parts as coarse as
124
+ game size allows, so a model still over has too many parts or too much fine
125
+ detail: many copies of a detailed part, fine paint on large parts. Cut those,
126
+ or raise `triangles` when the model needs the detail.
127
+
128
+ One part per form: melt a body's spheres and capsules into one `blob`, and
129
+ give a curved accessory its own kind (a lathe for a pot, a sweep for a
130
+ strap, OBJ text for a blade).
131
+
82
132
  ## What lives where
83
133
 
84
134
  - `engine3d/` -- the renderer (`world3d.js`, vase-style rig: PCFSoft shadows,
@@ -108,3 +158,11 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
108
158
  facing.
109
159
  - Space is bound to jump in this kit (unlike physics-2d, where the editor
110
160
  reserves it).
161
+
162
+ ## Platform
163
+
164
+ The rules every Castle deck plays by -- the card and touch, assets and
165
+ formats, imports, reloading, editors -- are the Castle CLI's, not this deck's.
166
+ The serve writes them fresh at every start to `.castle/docs/platform.md`, loaded here:
167
+
168
+ @.castle/docs/platform.md
@@ -49,16 +49,16 @@
49
49
  "imports": {
50
50
  "castle.physics-2d": {
51
51
  "deckId": "ckRZGFW4iPrx",
52
- "version": "2026-09-22T19:49:07.246Z"
52
+ "version": "2026-09-23T02:16:34.231Z"
53
53
  },
54
54
  "castle.base": {
55
55
  "deckId": "yRcmH4_aYllE",
56
- "version": "2026-09-22T19:48:55.642Z"
56
+ "version": "2026-09-23T05:44:46.889Z"
57
57
  }
58
58
  },
59
59
  "main": "main.jsx",
60
60
  "autoUpdateWhenImported": true,
61
61
  "deckId": "JH0SclbPVP0y",
62
62
  "cardId": "eXfAaUdbSU5A",
63
- "publishedVersion": "2026-09-22T19:49:18.182Z"
63
+ "publishedVersion": "2026-09-24T18:05:44.539Z"
64
64
  }