castle-web-cli 0.4.229 → 0.4.231

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (259) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +860 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -0,0 +1,254 @@
1
+ // In the runtime (`engine/scene.js`) a scene that sets
2
+ // `"engine": { "skipUnchangedActors": true }` differs in one thing: `getActors`
3
+ // does not sort a list already in order. So every scenario here runs twice,
4
+ // once each way, and the hooks called and the order of the actors after each
5
+ // step must be equal. The runtime is loaded by itself, with the modules that
6
+ // need the bundler (the deck's files, fonts, systems, art) stood in for.
7
+ //
8
+ // `npm run check` runs it. node scripts/test-skip-unchanged.mjs
9
+ // OTHER=<file in engine/> compares against another copy of the runtime instead
10
+ // of against the key; ONLY=<part of a scenario's name> runs those alone.
11
+ import assert from 'node:assert/strict';
12
+ import { register } from 'node:module';
13
+
14
+ const stubs = {
15
+ 'castle-web-sdk': `export const resolveDeckFile = (name) => String(name).replace(/^\\.\\//, '');
16
+ export const deckPrefixOf = () => ''; export const IMPORTS_DIR = 'imports'; export const IMPORTS_PREFIX = 'imports/';`,
17
+ './files': `export const initialFiles = {}; export const parseJsonFile = (path, text) => ({ value: JSON.parse(text) });
18
+ export const formatJson = (value) => JSON.stringify(value);`,
19
+ './blueprint': `export const actorUsesBlueprint = () => false; export const getBlueprintTemplate = () => null;
20
+ export const mergeComponents = (template, own) => ({ ...(template ?? {}), ...(own ?? {}) });`,
21
+ './collider': `export const getColliderRect = () => null; export const intersects = () => false; export const spriteIsEmpty = () => false;`,
22
+ './systemRegistry': `export const systemInstallers = [];`,
23
+ './fonts': `export const deckFontFamily = 'sans-serif';`,
24
+ };
25
+ const hooks = `
26
+ const stubs = ${JSON.stringify(stubs)};
27
+ export async function resolve(specifier, context, next) {
28
+ if (context.parentURL?.includes('/physics-2d/engine/')) {
29
+ if (stubs[specifier]) return { url: 'stub:' + specifier, shortCircuit: true };
30
+ if (specifier.startsWith('.') && !/\\.m?js$/.test(specifier)) return next(specifier + '.js', context);
31
+ }
32
+ return next(specifier, context);
33
+ }
34
+ export async function load(url, context, next) {
35
+ if (url.startsWith('stub:')) return { format: 'module', source: stubs[url.slice(5)], shortCircuit: true };
36
+ return next(url, context);
37
+ }`;
38
+ register(`data:text/javascript,${encodeURIComponent(hooks)}`);
39
+ const { SceneRuntime } = await import('../engine/scene.js');
40
+ const Other = process.env.OTHER ? (await import(`../engine/${process.env.OTHER}`)).SceneRuntime : null;
41
+
42
+ // A scenario builds its scene data and returns the steps to take; each step
43
+ // gets the runtime. `log` collects what the behaviours were called with.
44
+ function run(scenario, skip) {
45
+ const log = [];
46
+ const made = scenario(log);
47
+ const data = structuredClone(made.data);
48
+ if (skip) data.engine = { skipUnchangedActors: true };
49
+ const scene = new (skip && Other ? Other : SceneRuntime)(data, made.classes, {}, {});
50
+ if (!Other) assert.equal(scene.skipsUnchangedActors, skip);
51
+ for (const step of made.steps) {
52
+ try {
53
+ step(scene);
54
+ } catch (error) {
55
+ log.push(`threw ${error.message}`);
56
+ }
57
+ log.push(`order ${scene.getActors().map((actor) => actor.id).join(',')}`);
58
+ }
59
+ return log;
60
+ }
61
+
62
+ let scenarios = 0;
63
+ function sameBothWays(name, scenario, mustHave) {
64
+ if (process.env.ONLY && !name.includes(process.env.ONLY)) return;
65
+ const plain = run(scenario, false);
66
+ const skipping = run(scenario, true);
67
+ assert.deepEqual(skipping, plain, `${name}: the hooks differ with skipUnchangedActors`);
68
+ if (mustHave) assert.ok(plain.some((line) => line.includes(mustHave)), `${name}: the scenario never reached "${mustHave}"`);
69
+ scenarios += 1;
70
+ }
71
+
72
+ const behavior = (log, name, version = 1, more = {}) =>
73
+ class {
74
+ static behaviorName = name;
75
+ static defaultProps = {};
76
+ constructor(props) {
77
+ this.props = props;
78
+ log.push(`${name}v${version} ctor`);
79
+ }
80
+ update(actor, scene) {
81
+ log.push(`${name}v${version} update ${actor.id}`);
82
+ more.update?.(actor, scene, this);
83
+ }
84
+ onEnable(actor) {
85
+ log.push(`${name}v${version} enable ${actor.id}`);
86
+ more.onEnable?.(actor);
87
+ }
88
+ onDisable(actor) {
89
+ log.push(`${name}v${version} disable ${actor.id}`);
90
+ more.onDisable?.(actor);
91
+ }
92
+ };
93
+ const frames = (n) => Array.from({ length: n }, () => (scene) => scene.update(1 / 60));
94
+ const actor = (id, components) => ({ id, components });
95
+
96
+ // The plain run of things: updates, a switch off and on, a component added
97
+ // and removed, Style first, a spawn and a despawn.
98
+ sameBothWays(
99
+ 'ordinary frames',
100
+ (log) => ({
101
+ classes: [behavior(log, 'A'), behavior(log, 'B'), behavior(log, 'Style')],
102
+ data: { actors: [actor('one', { A: {}, Style: {}, B: {} }), actor('two', { B: {}, Unknown: {} })] },
103
+ steps: [
104
+ ...frames(3),
105
+ (s) => { s.getActor('one').components.B.$enabled = false; },
106
+ ...frames(2),
107
+ (s) => { delete s.getActor('one').components.B.$enabled; },
108
+ ...frames(2),
109
+ (s) => { s.getActor('two').components.A = {}; },
110
+ ...frames(2),
111
+ (s) => { delete s.getActor('two').components.B; },
112
+ ...frames(2),
113
+ (s) => { s.spawnActor(actor('three', { A: {} })); },
114
+ ...frames(2),
115
+ (s) => { s.despawnActor('one'); },
116
+ ...frames(2),
117
+ ],
118
+ }),
119
+ 'B v1 enable one'.replace('B v1', 'Bv1'),
120
+ );
121
+
122
+ // An update that updates again from inside a behavior (a review's case, from
123
+ // when the key also changed the update loop): B is switched off, the scene is
124
+ // updated from within A's update, and B is switched back on. Both hooks are
125
+ // called, as they are without the key. With the key the loop is the same loop,
126
+ // so this holds by construction; it is here so it stays so.
127
+ sameBothWays(
128
+ 'an update from inside an update',
129
+ (log) => {
130
+ let frame = 0;
131
+ let inside = false;
132
+ return {
133
+ classes: [
134
+ behavior(log, 'A', 1, {
135
+ update(a, scene) {
136
+ if (inside) return;
137
+ frame += 1;
138
+ if (frame !== 3) return;
139
+ scene.behavior(a, 'B').enabled = false;
140
+ inside = true;
141
+ scene.update(0);
142
+ inside = false;
143
+ scene.behavior(a, 'B').enabled = true;
144
+ },
145
+ }),
146
+ behavior(log, 'B'),
147
+ ],
148
+ data: { actors: [actor('one', { A: {}, B: {} })] },
149
+ steps: frames(6),
150
+ };
151
+ },
152
+ 'Bv1 enable one',
153
+ );
154
+
155
+ // A Layout z that is computed when read is left to the sort, which reads it
156
+ // in the sort's own order (a review's case).
157
+ sameBothWays('a z that counts its reads', () => {
158
+ let reads = 0;
159
+ const counting = () => Object.defineProperty({ x: 0, y: 0 }, 'z', { get: () => ++reads, enumerable: true });
160
+ return {
161
+ classes: [],
162
+ data: { actors: [actor('a', {}), actor('b', {})] },
163
+ steps: [
164
+ (s) => {
165
+ s.getActor('a').components.Layout = counting();
166
+ s.getActor('b').components.Layout = counting();
167
+ },
168
+ ...frames(2),
169
+ ],
170
+ };
171
+ });
172
+
173
+ // z of every other kind: in order, out of order, equal, changed in place,
174
+ // NaN, a string, missing, carried by a prototype.
175
+ sameBothWays('Layout z of every kind', (log) => ({
176
+ classes: [behavior(log, 'A')],
177
+ data: {
178
+ actors: [
179
+ actor('a', { A: {}, Layout: { z: 3 } }),
180
+ actor('b', { A: {}, Layout: { z: 1 } }),
181
+ actor('c', { A: {} }),
182
+ actor('d', { A: {}, Layout: { z: 1 } }),
183
+ actor('e', { A: {}, Layout: {} }),
184
+ ],
185
+ },
186
+ steps: [
187
+ ...frames(2),
188
+ (s) => { s.getActor('a').components.Layout.z = -4; },
189
+ ...frames(1),
190
+ (s) => { s.getActor('b').components.Layout.z = NaN; },
191
+ ...frames(1),
192
+ (s) => { s.getActor('b').components.Layout.z = '2'; },
193
+ ...frames(1),
194
+ (s) => { s.getActor('b').components.Layout.z = Infinity; },
195
+ ...frames(1),
196
+ (s) => { s.getActor('b').components.Layout = Object.create({ z: -9 }); },
197
+ ...frames(1),
198
+ (s) => { s.getActor('d').components.Layout = null; },
199
+ ...frames(1),
200
+ ],
201
+ }));
202
+
203
+ // The scene is reloaded, with and without the key: the switch follows the
204
+ // data that was loaded, and nothing is carried over.
205
+ if (!Other && !process.env.ONLY) {
206
+ const log = [];
207
+ const classes = [behavior(log, 'A')];
208
+ const data = { actors: [actor('one', { A: {} })] };
209
+ const scene = new SceneRuntime(data, classes, {}, {});
210
+ assert.equal(scene.skipsUnchangedActors, false, 'off unless the scene says so');
211
+ assert.ok(Object.getPrototypeOf(scene.behaviors) === Map.prototype, 'the registry is a plain Map');
212
+ scene.load({ ...data, engine: { skipUnchangedActors: true } });
213
+ assert.equal(scene.skipsUnchangedActors, true);
214
+ assert.deepEqual(scene.serialize().engine, { skipUnchangedActors: true }, 'the key is kept in the scene data');
215
+ assert.equal(scene.clone().skipsUnchangedActors, true, 'and by a clone');
216
+ scene.update(0);
217
+ scene.load(data);
218
+ assert.equal(scene.skipsUnchangedActors, false, 'and is off again for a scene without it');
219
+ for (const not of [{ engine: {} }, { engine: { skipUnchangedActors: 1 } }, { engine: null }, { engine: 'yes' }]) {
220
+ assert.equal(new SceneRuntime({ ...data, ...not }, classes, {}, {}).skipsUnchangedActors, false);
221
+ }
222
+ // `engine.shadows.distance`, which the 3d kit reads: latched the same way.
223
+ const far = (engine) => new SceneRuntime({ ...data, engine }, classes, {}, {}).nearShadowDistance;
224
+ assert.equal(scene.nearShadowDistance, 0, 'off unless the scene says so');
225
+ assert.equal(far({ skipUnchangedActors: true }), 0);
226
+ assert.equal(far({ shadows: { distance: 40 } }), 40);
227
+ for (const not of [true, {}, { distance: '40' }, { distance: 0 }, { distance: -3 }, { distance: Infinity }, { distance: NaN }, { distance: null }]) {
228
+ assert.equal(far({ shadows: not }), 0, JSON.stringify(not));
229
+ }
230
+ scene.load({ ...data, engine: { shadows: { distance: 25 } } });
231
+ scene.data.engine.shadows.distance = 99;
232
+ assert.equal(scene.nearShadowDistance, 25, 'read when the scene loads');
233
+ assert.equal(scene.skipsUnchangedActors, false, 'and the one key does not set the other');
234
+ scene.load(data);
235
+ assert.equal(scene.nearShadowDistance, 0, 'and is off again for a scene without it');
236
+ // `engine.camera.follow`, which the 3d kit's Player reads: latched the same way.
237
+ const rigid = (engine) => new SceneRuntime({ ...data, engine }, classes, {}, {}).cameraFollowsRigidly;
238
+ assert.equal(scene.cameraFollowsRigidly, false, 'off unless the scene says so');
239
+ assert.equal(rigid({ skipUnchangedActors: true, shadows: { distance: 40 } }), false);
240
+ assert.equal(rigid({ camera: { follow: 'rigid' } }), true);
241
+ for (const not of [true, 'rigid', {}, { follow: true }, { follow: 'Rigid' }, { follow: 'smooth' }, { follow: null }, null]) {
242
+ assert.equal(rigid({ camera: not }), false, JSON.stringify(not));
243
+ }
244
+ scene.load({ ...data, engine: { camera: { follow: 'rigid' } } });
245
+ assert.equal(scene.clone().cameraFollowsRigidly, true, 'and by a clone');
246
+ scene.data.engine.camera.follow = 'smooth';
247
+ assert.equal(scene.cameraFollowsRigidly, true, 'read when the scene loads');
248
+ assert.equal(scene.skipsUnchangedActors, false, 'and the one key does not set the others');
249
+ assert.equal(scene.nearShadowDistance, 0);
250
+ scene.load(data);
251
+ assert.equal(scene.cameraFollowsRigidly, false, 'and is off again for a scene without it');
252
+ }
253
+
254
+ console.log(`skip unchanged: ${scenarios} scenarios call the same hooks with and without the key`);
@@ -49,10 +49,294 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
49
49
  load rebuilds the physics world and resets the scene to its authored state;
50
50
  `scene.persistent` survives loads -- the player's score, collected-pickup
51
51
  memory, and camera angle live there, so they cross scenes.
52
+ `scene.residentScenes` (a Set of scene paths) keeps those scenes' built
53
+ meshes parked while another scene plays, so coming back to one redraws it
54
+ without rebuilding them; anything not named is released on the load.
52
55
  - A scene can dress the ground: `"ground": { "art": "drawings/floor.sprite",
53
56
  "tile": 2, "color": "#..." }` at the scene file's top level (`tile` = meters
54
- per texture repeat). `Shape.artRepeat: [u, v]` tiles a texture across a
57
+ per texture repeat). `"ground": { "none": true }` has no ground at all, drawn
58
+ or stood on: whatever is not on an actor falls (pits, lava, sky islands).
59
+ `Shape.artRepeat: [u, v]` tiles a texture across a
55
60
  face so long walls don't stretch.
61
+ - `"engine": { "skipUnchangedActors": true }` at the scene file's top level,
62
+ beside `ground`, asks the engine not to redo, every frame, work whose answer
63
+ cannot have changed. The terms:
64
+ > With the key absent, a scene runs the engine exactly as before. With the key
65
+ > present, each frame equals what the engine would have produced without it
66
+ > PROVIDED the scene's components are plain stored data (no accessors, Proxies,
67
+ > toJSON, custom iterators) and three.js objects under actors are changed only
68
+ > through position/rotation/quaternion/scale/visible/parenting. A scene that does
69
+ > not meet that is unsupported under the key and must not set it.
70
+
71
+ It is read when the scene loads, so it follows a scene switch, and a mounted
72
+ pack's scene decides for itself. What is skipped for an actor nothing has
73
+ touched: building the signatures that decide whether its mesh and its
74
+ physics body need rebuilding, recomputing its node's matrices, and sorting
75
+ the actor list. Behaviors run exactly as without the key. Each skipped piece
76
+ is skipped only after reading its inputs and finding them as they were, so
77
+ nothing has to be marked dirty: an actor still follows a change on the very
78
+ next frame -- a component's stored field written in place, a component
79
+ added, removed or replaced, a spawn or despawn, physics, the editor, the
80
+ network, its node posed from `scene.three`. Opt in when a scene is several
81
+ hundred actors that mostly stand still and frame time on a slow phone is
82
+ script, not drawing; a small scene gains nothing.
83
+ How it stays right when deck code runs in the middle of the engine's own
84
+ work (`engine3d/world3d.js` has the rule and the code):
85
+ > Fast-path state (snapshots, pass marks, cached signatures) is trusted only
86
+ > across a span in which no code outside the engine has run. A pass in which
87
+ > the engine calls out (any callback), is re-entered, or sees the scene
88
+ > change, finishes exactly as main would and leaves no fast-path state
89
+ > behind.
90
+
91
+ The engine moves a counter before it does anything, inside a pass over the
92
+ actors, that can run code that is not its own; it does not work out
93
+ afterwards whether something ran. The places, all of them:
94
+ `scene.three.scene.userData.groundHeight`, called while a walking model is
95
+ animated; and three.js listeners (`added`, `removed`, `childadded`,
96
+ `childremoved`, `dispose`) on the scene, a node, a geometry or a material,
97
+ told when a node is built, rebuilt or released, when the scene changes, when
98
+ the ground is dressed anew, and when an instanced mesh is replaced; and
99
+ `syncActors` called again from inside any of those. From that point the
100
+ pass does each actor the old way and writes nothing down, and when it ends,
101
+ or if it throws, everything written down before is dropped. So:
102
+ - a frame in which any actor's mesh is built, rebuilt or released costs what
103
+ it costs without the key, and the frame after it reads every actor once
104
+ more before skipping resumes;
105
+ - a scene with a `groundHeight` callback, or with `instanceModels` on, runs
106
+ every pass the old way and keeps only the matrix saving;
107
+ - the physics pass calls nothing outside the engine until its collision
108
+ callbacks, which come last;
109
+ - a component nested more than 32 levels deep is compared the old way every
110
+ frame.
111
+
112
+ What is written down lives in the world's own maps (`world.snapshots`,
113
+ `world.modelSigs`) and in the physics system's (`remembered`), never on a
114
+ node entry or a body entry, and is dropped by replacing or clearing those.
115
+ The one thing on a node, an ActorNode's `computedFrom`, is numbers only and
116
+ refers to no object.
117
+ A world being disposed never skips: `disposeWorld` drops what was written
118
+ down before it releases the nodes and again after their `dispose` listeners
119
+ have run, so a listener that syncs the world again leaves nothing.
120
+ - Within the terms, these are followed: any stored field of a Shape, Model,
121
+ Body or Transform changed, added, removed or reordered, at any depth; art
122
+ loading or being replaced; a model file, or a model it references, edited;
123
+ a node's, or any object under it's, position, rotation (angles or order),
124
+ quaternion, scale or visibility set; children added, removed, reordered,
125
+ or moved to another parent and back; a body's type changed through
126
+ `scene.physics3d.bodyOf`.
127
+ - Outside the terms the result is not promised. The engine does notice some
128
+ of it and then does the old work for that actor, as protection, not as a
129
+ guarantee to build on: a component with an accessor, a `toJSON` or a class
130
+ of its own found when it is first read; an object under a node with
131
+ `matrixAutoUpdate` off or an `updateMatrixWorld` of its own (a camera, a
132
+ skinned mesh); a world matrix written by hand; a transform changed, used
133
+ and put back between frames.
134
+ - It does not notice, among others: a `Proxy` in place of a component, of
135
+ `actor.components` or of the `sprites` / `files` tables; a getter on
136
+ `Transform`, on `Shape.solid`, or on `actor.components` itself; a stored
137
+ field redefined as a getter after the engine has read it; an object's
138
+ local `matrix` written by hand while its `matrixAutoUpdate` is on (set
139
+ `position` / `quaternion` / `scale` instead); three.js private fields
140
+ written directly (`rotation._order`, `quaternion._x`).
141
+ - `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
142
+ (the same `engine` object) asks the engine to draw the sun's shadows where
143
+ they can be seen, near the camera, rather than in the sun's fixed box.
144
+ Without it the sun's shadow camera is a fixed 150 x 120 m box round the
145
+ origin, so every caster under the box is drawn a second time each frame
146
+ wherever the player stands, and a scene larger than the box has no shadows
147
+ outside it. The terms:
148
+ > With the key absent, a scene is drawn exactly as before: the same shadow
149
+ > camera, map, `castShadow` flags and render calls. On a frame the mode
150
+ > draws, everything the camera sees within `distance` metres (measured along
151
+ > the way it looks) is shadowed as it would be under a box that covered it,
152
+ > with texels exactly the size the sun's own are and the same softness and
153
+ > bias. Shadows are complete out to `distance` for casters inside the depth
154
+ > range below; a point farther off may or may not be shadowed, and nothing
155
+ > cuts shadows off there.
156
+
157
+ The depth range is the sun's own `near` and `far` along the light, measured
158
+ from the engine's shadow camera, which stands as far from the middle of the
159
+ view's sphere (taken along the light to the height of the sun's target) as
160
+ the sun does from its target. For the engine's sun (19.9 m from its target,
161
+ near 0.5, far 50) that is casters up to 19.4 m toward the sun and 30.1 m
162
+ away from it, from the ground under the middle of the view. It is what the
163
+ sun's own camera draws for a view round its target: there too a caster 25 m
164
+ up the light from a point on the ground is not drawn.
165
+
166
+ How it stays out of the scene's way (`engine3d/nearshadows.js` has the rule
167
+ and the code):
168
+ > The scene's sun, its shadow object, its shadow camera, its map and its
169
+ > target are never written by this mode. What the mode needs is its own
170
+ > objects, attached only for the duration of one renderer.render call
171
+ > inside try/finally. Outside that call the world is as main leaves it, so
172
+ > there is nothing to restore on a scene change, a throw, a dispose or a
173
+ > keyless frame.
174
+
175
+ Who the key is for:
176
+ > The key is for a scene whose deck leaves the renderer's shadow settings
177
+ > and the drawing of the world to the engine. A deck must not set the key if
178
+ > any of its code, in any scene played in the same world, changes
179
+ > renderer.shadowMap.type, .enabled, .autoUpdate or .needsUpdate after the
180
+ > world is made; calls renderer.render or the composer itself, inside or
181
+ > between the engine's frames; calls renderWorld from inside a frame; or
182
+ > gives the world's renderer to another world. In a deck that does, shadows
183
+ > may be drawn wrongly with the key, and three.js's shadow bookkeeping for
184
+ > the sun's own map (its filter, its size) may differ from a world that
185
+ > never had the key until the world is disposed. A deck that never sets the
186
+ > key is unaffected whatever it does.
187
+
188
+ (three.js keeps the shadow pass's state, the type it last drew with and the
189
+ frustum it culls by, inside the renderer, where the engine can neither read
190
+ it nor put it back. Nothing in the kits does any of the above after
191
+ `makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
192
+
193
+ Within that, the mode draws a frame only when all of these hold; otherwise
194
+ the frame is drawn exactly as without the key. They are cheap protection,
195
+ looked at every frame, not promises about a deck outside the condition
196
+ above. After any `renderWorld` call returns, either the mode drew that
197
+ frame or nothing of the mode's is allocated: every way out of the mode (a
198
+ frame drawn plain for any term, a re-entry, a throw, a dispose) frees its
199
+ map at that moment:
200
+ 1. the scene now playing asked, with a finite distance above 0
201
+ (`runtime.nearShadowDistance`, read when the scene loads), the frame is
202
+ the player's (the scene and model editors give `renderWorld` no runtime),
203
+ and the world is not being disposed;
204
+ 2. `renderWorld` was not entered from inside another `renderWorld` of this
205
+ world that had anything of the mode's to do, keyed or not, and no frame
206
+ of this world has been entered that way before. The call inside is drawn
207
+ plain; the sun has its own shadow back before that call draws, and still
208
+ has it when the call returns, whatever the call did, disposing the world
209
+ included; the mode is off for this world from then until the world is
210
+ disposed (`world.nearShadows.off`); and the frame that was re-entered,
211
+ whose map is freed under it, may have wrong or missing shadows, that
212
+ once;
213
+ 3. read at the start of the frame, `renderer.shadowMap.type` is
214
+ `PCFSoftShadowMap` and `.enabled` and `.autoUpdate` are on, which is how
215
+ the engine makes the renderer; and the frame before was also a frame
216
+ with the key that found the same and was drawn to the end
217
+ (`world.nearShadows.lastType`). So the first frame with the key, after a
218
+ load or after any frame without it, is drawn plain, and three.js
219
+ allocates and configures the sun's own map as it would have; and so is
220
+ the frame after one that threw, and after one the mode drew that ended
221
+ with no map on the engine's shadow (three.js drew nothing: a lost
222
+ context). The engine's shadow never has a blur map;
223
+ 4. the sun (`world.sun`, the light whose bias the engine fits) is still a
224
+ child of the scene, is the first directional light there that casts, has
225
+ `castShadow` on, is visible and on the camera's layers, and its own
226
+ shadow is a directional light's, has `autoUpdate` on and has its map.
227
+ Looked at every frame: a sun removed or replaced means plain frames, in
228
+ which a replacement draws its own box as without the key;
229
+ 5. the camera is a perspective camera, and the sun's own box and map size
230
+ give a texel size: its shadow camera has zoom 1 and no view offset.
231
+
232
+ All of the mode's work in a `renderWorld` call (deciding the terms, fitting
233
+ the bias, allocating, swapping, rendering, leaving, disposing) happens
234
+ inside one outermost try/finally, counted on the world
235
+ (`world.nearShadows.depth`). A call that arrives while the count is up
236
+ draws plain, puts the mode off and makes nothing. The finally establishes
237
+ the postcondition itself: unless the mode drew this frame to the end, on a
238
+ world not disposed, with the mode not off and a map on its shadow, nothing
239
+ of the mode's is allocated and the sun has its own shadow. Its order is
240
+ what makes that hold through a `dispose` listener that throws: first the
241
+ sun gets its own shadow back (an assignment, which calls no one), then what
242
+ is freed is detached and only then disposed, and looked at again after the
243
+ callbacks; the count comes down in a finally of its own that nothing skips.
244
+ A world with no mode state playing a scene without the key does not enter
245
+ any of it: `renderWorld` runs its two statements (fit the bias, render)
246
+ with no counter and no try, as it always did.
247
+
248
+ On such a frame `renderWorld` fits the bias of the sun's own shadow as
249
+ always, puts the engine's shadow on the sun (`sun.shadow`), renders, and
250
+ puts the sun's own back in a `finally`; that assignment is the only write,
251
+ and it is undone only by the frame that made it (a frame that finds the
252
+ world disposed, its state replaced or itself re-entered touches nothing).
253
+ three.js keeps nothing per shadow object (the shadow pass and the light
254
+ uniforms read `light.shadow` afresh every render), so the next plain render
255
+ reads the sun's own as if nothing had happened. The engine's shadow
256
+ (`world.nearShadows.shadow`, a DirectionalLightShadow with its own camera,
257
+ map, matrix and frustum), each frame:
258
+ - looks along the sun's direction, from as far as the sun is from its
259
+ target, with the sun's own near and far, round the smallest sphere that
260
+ holds the camera's view out to `distance`: one size whichever way the
261
+ camera turns (it changes only with the canvas's shape or the camera's
262
+ lens). It sits a whole number of texels along each of its axes, so a
263
+ shadow's edge does not crawl as the camera moves. The light does not move;
264
+ - has texels exactly the size of the sun's own (the sun's box over its map
265
+ size, read each frame), so its box is `map size x texel` and it copies the
266
+ bias `fitShadowBias` fitted to the sun's own, with its intensity and
267
+ radius: 40 m on a portrait phone is a 710 x 888 map. Its map is never
268
+ larger than the sun's own in area (2048 x 2048) nor than the renderer's
269
+ largest texture on a side; a `distance` that would need more is drawn as
270
+ the largest that fits (about 100 m in portrait, 38 m at 32:9) rather than
271
+ with larger texels;
272
+ - hands three.js a frustum to cull casters with (`getFrustum`) that is its
273
+ box narrowed to the view's outline, out to `distance`, as the sun sees it,
274
+ pushed out by everything three.js's shader moves a shadow lookup by across
275
+ the light: the normal bias drawn with that frame (the lookup is made at
276
+ `position + normal * normalBias`) and four texels for the soft filter's
277
+ taps. The box is wider by the same. Every caster whose shadow
278
+ can land on something the view sees within `distance` is drawn into the
279
+ map; one whose shadow cannot is not. No `castShadow` flag is changed and
280
+ nothing is cached: every caster that is drawn is drawn every frame, so a
281
+ moving thing's shadow moves with it as before.
282
+
283
+ A frame without the key drops what the mode holds, all but `off`;
284
+ `disposeWorld` drops it all. The engine's map (and a blur map, were there
285
+ one) is taken off its shadow before it is disposed, once.
286
+
287
+ What a deck that works on the sun sees under the key: the sun's own
288
+ `shadow.camera` box, `mapSize` and any `getFrustum` of its own are left as
289
+ they are and not used for drawing on the frames the mode draws (a sun whose
290
+ `shadow.autoUpdate` the deck turned off gets plain frames, term 4),
291
+ except that the box over the map size gives the texel size and `near`/`far`,
292
+ `bias`, `normalBias`, `intensity` and `radius` are copied each frame;
293
+ three.js does not draw the sun's own shadow on those frames, so its map and
294
+ its shadow camera's matrices stay as the last plain frame left them; a sun
295
+ moved or re-aimed is followed (its direction is read each frame). Without
296
+ the key such a deck works exactly as before. What differs on screen with
297
+ the key: shadows no longer end at the fixed box's edge, so a scene larger
298
+ than that box gains shadows where it had none; beyond `distance` from the
299
+ camera they thin out and, past the engine's box (which reaches somewhat
300
+ farther than `distance`), end, with a hard edge if the camera can see that
301
+ far (pick a distance past the ground the camera can see). Opt in when a
302
+ scene is wide enough that most of its casters are out of sight; a scene
303
+ that fits the view gains nothing.
304
+ - `"engine": { "camera": { "follow": "rigid" } }` at the scene file's top
305
+ level (the same `engine` object) asks the `Player` behavior for a follow
306
+ camera that moves with the player instead of easing after it. Without it
307
+ the camera eases its whole position toward its place behind the player, so
308
+ how far it trails a walking player depends on how long each frame is: on
309
+ frames of uneven length (a page missing every other vsync) the distance
310
+ changes every frame and the view judders, which reads as an up-and-down
311
+ shake walking forward, since the camera looks down. The terms:
312
+ > With the key absent, the camera is placed exactly as before: the same
313
+ > code, in the same place in the frame. With the key present, the camera's
314
+ > offset from the player (its angle and height) and the player's height are
315
+ > eased at the rate the old camera eases, with an easing that trails a
316
+ > steadily moving target by the same distance however the frames are cut;
317
+ > the player's ground position is not eased. So a steady walk leaves the
318
+ > player at one place on screen, a turn swings the camera round as before,
319
+ > and a jump lifts the player on screen while the camera follows smoothly.
320
+ > A teleport (more than 3 m in a frame, or the camera more than 20 m off)
321
+ > still snaps it, and it still looks at the player.
322
+
323
+ Where it is placed: behaviors run before physics, so the Player sees the
324
+ position the last frame drew. Under the key it asks for its camera instead
325
+ (`scene.followCamera`: its actor id and the scene data it asked in), every
326
+ frame, whether physics is ready or not, and the physics system places it
327
+ last in its `afterBehaviors`, after this frame's positions are written back
328
+ and the collision callbacks have run, on the position the frame is drawn
329
+ with; on a frame physics cannot step (rapier still loading, or the first
330
+ frame after a load) it is placed all the same. The player is looked up as
331
+ the scene has it then: one a callback despawned gets no camera, and a
332
+ request made before a load is not used after it (a load and a dispose drop
333
+ it). Systems registered after physics (the hub's) see the camera already
334
+ placed. The offset is read each frame from where the camera is, against
335
+ the point it followed the frame before, so a camera something else placed
336
+ (a hub trip's camera, a cutscene) is eased on from wherever it was put.
337
+ The play panel and a published deck play the scene through the same
338
+ runtime, so both follow the scene's key; the scene editor's own orbit
339
+ camera is not a follow camera and is not affected.
56
340
  - `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
57
341
  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
58
342
  stage to place), orbit camera (drag orbits, wheel zooms), click to select /
@@ -96,6 +96,76 @@ function updateCamera(scene, t, rt, props, dt) {
96
96
  cam.lookAt(t.x, t.y + 0.5, t.z);
97
97
  }
98
98
 
99
+ // How fast the rigid follow camera's offset and height catch up: the rate of
100
+ // updateCamera's lerp, so an orbit (Q/E, or turning) swings as it does there.
101
+ const FOLLOW_RATE = 12;
102
+
103
+ // One frame of `x' = FOLLOW_RATE * (target - x)` for a target that moved from
104
+ // `from` to `to` at a steady rate over the frame, solved exactly. A target that
105
+ // moves steadily is trailed by the same distance however the frames are cut,
106
+ // and one that stands still is reached as updateCamera's lerp reaches it.
107
+ function settle(value, from, to, dt) {
108
+ if (!(dt > 0)) return value;
109
+ const lag = (to - from) / (dt * FOLLOW_RATE);
110
+ return to - lag + (value - from + lag) * Math.exp(-FOLLOW_RATE * dt);
111
+ }
112
+
113
+ // The follow camera of a scene that set `"engine": { "camera": { "follow":
114
+ // "rigid" } }` (the kit's CLAUDE.md has the terms). It moves with the player
115
+ // as one piece: the offset from the player (its angle and height) and the
116
+ // player's height are eased, the player's ground position is not, so a steady
117
+ // walk leaves the player at one place on screen whatever the frame lengths.
118
+ // It is placed at the end of the frame (`placeFollowing`), on the position the
119
+ // frame is drawn with.
120
+ function followRigidly(scene, t, per, rt, props, dt) {
121
+ const cam = scene.three?.camera;
122
+ if (!cam) return;
123
+ const ox = -props.camDistance * Math.sin(per.camAngle);
124
+ const oy = props.camHeight;
125
+ const oz = props.camDistance * Math.cos(per.camAngle);
126
+ const last = per.camLastAt;
127
+ const jumped = last && Math.hypot(t.x - last.x, t.z - last.z) > TELEPORT_PER_FRAME;
128
+ per.camLastAt = { x: t.x, z: t.z };
129
+ // The offset is read each frame from where the camera is, against the
130
+ // point it followed last frame, so a camera something else moved since (a
131
+ // trip's camera, a cutscene) is eased on from where it was left.
132
+ const at = cam.position;
133
+ const f = (rt.camFollow ??= { from: { x: t.x, y: t.y, z: t.z }, to: null });
134
+ let x = at.x - f.from.x;
135
+ let y = at.y - f.from.y;
136
+ let z = at.z - f.from.z;
137
+ let height = f.from.y;
138
+ const to = f.to ?? { x: ox, y: oy, z: oz, height: t.y };
139
+ if (jumped || Math.hypot(t.x + ox - at.x, t.z + oz - at.z) > 20) {
140
+ [x, y, z, height] = [ox, oy, oz, t.y];
141
+ } else {
142
+ x = settle(x, to.x, ox, dt);
143
+ y = settle(y, to.y, oy, dt);
144
+ z = settle(z, to.z, oz, dt);
145
+ height = settle(height, to.height, t.y, dt);
146
+ }
147
+ f.to = { x: ox, y: oy, z: oz, height: t.y };
148
+ f.from = { x: t.x, y: height, z: t.z };
149
+ cam.position.set(t.x + x, height + y, t.z + z);
150
+ cam.lookAt(t.x, t.y + 0.5, t.z);
151
+ }
152
+
153
+ // Under the key, Player.update asks for its camera by the actor's id and the
154
+ // scene data it was made for (`scene.followCamera`), every frame, physics
155
+ // ready or not; the physics system calls this at the end of the frame, after
156
+ // it has written this frame's positions back (or at once, when it could not
157
+ // step), if the same scene is still loaded. The player is looked up as the
158
+ // scene has it then: one despawned or turned off since gets no camera.
159
+ function placeFollowing(scene, id, dt) {
160
+ const actor = scene.getActor(id);
161
+ const t = actor?.components.Transform;
162
+ const props = actor?.components.Player;
163
+ if (!t || !props || props.$enabled === false) return;
164
+ const per = (scene.persistent ??= {});
165
+ if (per.camAngle === undefined) per.camAngle = Math.PI / 4;
166
+ followRigidly(scene, t, per, actor.runtime, props, dt);
167
+ }
168
+
99
169
  // The nearest Lookable the player is facing, within its range.
100
170
  function findLookText(scene, actor, t, facing) {
101
171
  const fx = Math.sin(facing);
@@ -134,6 +204,9 @@ export class Player {
134
204
  }
135
205
 
136
206
  update(actor, scene, dt) {
207
+ if (scene.cameraFollowsRigidly === true) {
208
+ scene.followCamera = { id: actor.id, data: scene.data, dt, place: placeFollowing };
209
+ }
137
210
  const phys = scene.physics3d;
138
211
  if (!phys?.ready()) return;
139
212
  const t = actor.components.Transform;
@@ -178,7 +251,7 @@ export class Player {
178
251
  if (vel.y < 1) phys.applyImpulse(actor, { x: 0, y: -14 * phys.mass(actor) * dt, z: 0 });
179
252
  }
180
253
 
181
- updateCamera(scene, t, per, this.props, dt);
254
+ if (scene.cameraFollowsRigidly !== true) updateCamera(scene, t, per, this.props, dt);
182
255
  const remaining = scene.actorsWith('Pickup').length;
183
256
  const total = per.score + remaining;
184
257
  const score =
@@ -50,16 +50,16 @@
50
50
  "imports": {
51
51
  "castle.physics-2d": {
52
52
  "deckId": "ckRZGFW4iPrx",
53
- "version": "2026-09-23T02:16:34.231Z"
53
+ "version": "2026-10-04T22:43:17.146Z"
54
54
  },
55
55
  "castle.base": {
56
56
  "deckId": "yRcmH4_aYllE",
57
- "version": "2026-09-24T21:25:28.679Z"
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-09-25T17:46:00.903Z"
64
+ "publishedVersion": "2026-10-04T22:44:03.895Z"
65
65
  }