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.
- package/dist/agent-prompts.d.ts +2 -0
- package/dist/agent-prompts.js +16 -8
- package/dist/agent.d.ts +2 -0
- package/dist/agent.js +21 -21
- package/dist/api.d.ts +28 -2
- package/dist/api.js +74 -16
- package/dist/castle-host/host.d.ts +91 -0
- package/dist/castle-host/host.js +860 -3
- package/dist/castleJson.d.ts +44 -0
- package/dist/castleJson.js +131 -0
- package/dist/check.js +27 -1
- package/dist/contentPack.d.ts +49 -0
- package/dist/contentPack.js +273 -0
- package/dist/devExperiments.d.ts +21 -0
- package/dist/devExperiments.js +139 -0
- package/dist/devHub.d.ts +55 -0
- package/dist/devHub.js +187 -0
- package/dist/devSaveStorage.d.ts +36 -0
- package/dist/devSaveStorage.js +469 -0
- package/dist/devSessionChild.js +25 -13
- package/dist/devSessionServer.d.ts +14 -1
- package/dist/devSessionServer.js +237 -46
- package/dist/devSessionStorage.d.ts +9 -0
- package/dist/devSessionStorage.js +66 -1
- package/dist/experimentAssignment.d.ts +15 -0
- package/dist/experimentAssignment.js +41 -0
- package/dist/importCheckHook.d.ts +40 -0
- package/dist/importCheckHook.js +171 -0
- package/dist/importRegression.d.ts +15 -0
- package/dist/importRegression.js +100 -0
- package/dist/importTrust.d.ts +2 -0
- package/dist/importTrust.js +27 -0
- package/dist/importUpdateHook.d.ts +18 -0
- package/dist/importUpdateHook.js +31 -8
- package/dist/importUpdateHookRunner.js +19 -7
- package/dist/imports.d.ts +16 -0
- package/dist/imports.js +141 -31
- package/dist/index.js +3 -1
- package/dist/init.d.ts +3 -0
- package/dist/init.js +126 -9
- package/dist/install.js +4 -1
- package/dist/localPaths.js +4 -0
- package/dist/login.js +2 -2
- package/dist/platformDoc.js +3 -8
- package/dist/playPagePolicy.js +3 -1
- package/dist/remix.js +5 -0
- package/dist/routerTaskReport.d.ts +28 -0
- package/dist/routerTaskReport.js +56 -0
- package/dist/save-deck.d.ts +18 -0
- package/dist/save-deck.js +142 -6
- package/dist/serve.d.ts +8 -0
- package/dist/serve.js +99 -14
- package/dist/serverBundle.d.ts +1 -1
- package/dist/serverBundle.js +5 -1
- package/dist/webSourceSync.d.ts +2 -0
- package/dist/webSourceSync.js +2 -0
- package/kits/base/CLAUDE.md +2 -3
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +406 -53
- package/kits/base/sdk/agent.js +4 -4
- package/kits/base/sdk/avatar.d.ts +12 -0
- package/kits/base/sdk/avatar.js +23 -0
- package/kits/base/sdk/castle.d.ts +9 -0
- package/kits/base/sdk/castle.js +5 -0
- package/kits/base/sdk/commands.d.ts +223 -0
- package/kits/base/sdk/commands.js +16 -0
- package/kits/base/sdk/context.d.ts +6 -0
- package/kits/base/sdk/experiments.d.ts +15 -0
- package/kits/base/sdk/experiments.js +83 -0
- package/kits/base/sdk/hub.d.ts +85 -0
- package/kits/base/sdk/hub.js +107 -0
- package/kits/base/sdk/multiplayer.d.ts +45 -1
- package/kits/base/sdk/multiplayer.js +158 -8
- package/kits/base/sdk/save.d.ts +197 -0
- package/kits/base/sdk/save.js +525 -0
- package/kits/base/sdk/saveCoordinator.d.ts +39 -0
- package/kits/base/sdk/saveCoordinator.js +252 -0
- package/kits/base/sdk/server/hub.d.ts +169 -0
- package/kits/base/sdk/server/hub.js +125 -0
- package/kits/base/sdk/server/platformHandle.d.ts +42 -1
- package/kits/base/sdk/server/storage.d.ts +58 -4
- package/kits/base/sdk/server/storage.js +25 -5
- package/kits/base/sdk/server/wrapper.d.ts +36 -2
- package/kits/base/sdk/server/wrapper.js +92 -11
- package/kits/base/sdk/store.d.ts +3 -2
- package/kits/base/sdk/store.js +5 -0
- package/kits/base/sdk/transport.d.ts +2 -1
- package/kits/base/sdk/transport.js +13 -1
- package/kits/hub-game/.prettierrc +5 -0
- package/kits/hub-game/CLAUDE.md +149 -0
- package/kits/hub-game/blueprints/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
- package/kits/hub-game/castle.json +96 -0
- package/kits/hub-game/code/client/attention.js +133 -0
- package/kits/hub-game/code/client/avatar.js +288 -0
- package/kits/hub-game/code/client/cabinets.js +90 -0
- package/kits/hub-game/code/client/chat.js +135 -0
- package/kits/hub-game/code/client/chrome.js +1035 -0
- package/kits/hub-game/code/client/doorFrame.js +15 -0
- package/kits/hub-game/code/client/firstJoin.js +14 -0
- package/kits/hub-game/code/client/grab.js +376 -0
- package/kits/hub-game/code/client/hookLayer.js +236 -0
- package/kits/hub-game/code/client/idle.js +326 -0
- package/kits/hub-game/code/client/keys.js +48 -0
- package/kits/hub-game/code/client/pack.js +232 -0
- package/kits/hub-game/code/client/packFormat.js +397 -0
- package/kits/hub-game/code/client/say.js +127 -0
- package/kits/hub-game/code/client/sha256.js +80 -0
- package/kits/hub-game/code/client/sound.js +147 -0
- package/kits/hub-game/code/client/state.js +143 -0
- package/kits/hub-game/code/client/talk.js +233 -0
- package/kits/hub-game/code/client/tiers.js +480 -0
- package/kits/hub-game/code/client/together.js +440 -0
- package/kits/hub-game/code/client/wear.js +149 -0
- package/kits/hub-game/code/server/actors.js +627 -0
- package/kits/hub-game/code/server/blocks.js +103 -0
- package/kits/hub-game/code/server/cabinets.js +309 -0
- package/kits/hub-game/code/server/game.js +137 -0
- package/kits/hub-game/code/server/grab.js +248 -0
- package/kits/hub-game/code/server/history.js +96 -0
- package/kits/hub-game/code/server/hub.js +1998 -0
- package/kits/hub-game/code/server/idle.js +412 -0
- package/kits/hub-game/code/server/index.js +64 -0
- package/kits/hub-game/code/server/labels.js +59 -0
- package/kits/hub-game/code/server/manifest.js +554 -0
- package/kits/hub-game/code/server/npcs.js +733 -0
- package/kits/hub-game/code/server/party.js +439 -0
- package/kits/hub-game/code/server/place.js +43 -0
- package/kits/hub-game/code/server/say.js +83 -0
- package/kits/hub-game/code/server/wear.js +142 -0
- package/kits/hub-game/code/systems/hub.js +2347 -0
- package/kits/hub-game/docs/content-pack.md +151 -0
- package/kits/hub-game/docs/contract.md +1209 -0
- package/kits/hub-game/docs/style.md +137 -0
- package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
- package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
- package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
- package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
- package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
- package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
- package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
- package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
- package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
- package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
- package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
- package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
- package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
- package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
- package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
- package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
- package/kits/hub-game/eslint.config.js +20 -0
- package/kits/hub-game/fonts.generated.js +9 -0
- package/kits/hub-game/index.html +22 -0
- package/kits/hub-game/main.jsx +6 -0
- package/kits/hub-game/models/avatar-0.pxmodel +21 -0
- package/kits/hub-game/models/avatar-1.pxmodel +24 -0
- package/kits/hub-game/models/avatar-2.pxmodel +27 -0
- package/kits/hub-game/models/avatar-3.pxmodel +22 -0
- package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
- package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
- package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
- package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
- package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
- package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
- package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
- package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
- package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
- package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
- package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
- package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
- package/kits/hub-game/package-lock.json +365 -0
- package/kits/hub-game/package.json +32 -0
- package/kits/hub-game/scenes/main.scene +318 -0
- package/kits/hub-game/scripts/check.mjs +339 -0
- package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
- package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
- package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
- package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
- package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
- package/kits/hub-game/scripts/pack.mjs +192 -0
- package/kits/hub-game/scripts/test-actors.mjs +666 -0
- package/kits/hub-game/scripts/test-attention.mjs +103 -0
- package/kits/hub-game/scripts/test-avatar.mjs +472 -0
- package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
- package/kits/hub-game/scripts/test-blocks.mjs +351 -0
- package/kits/hub-game/scripts/test-chat.mjs +98 -0
- package/kits/hub-game/scripts/test-classic.mjs +590 -0
- package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
- package/kits/hub-game/scripts/test-door.mjs +56 -0
- package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
- package/kits/hub-game/scripts/test-grab.mjs +331 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
- package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
- package/kits/hub-game/scripts/test-idle.mjs +518 -0
- package/kits/hub-game/scripts/test-interest.mjs +413 -0
- package/kits/hub-game/scripts/test-keys.mjs +50 -0
- package/kits/hub-game/scripts/test-manifest.mjs +270 -0
- package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
- package/kits/hub-game/scripts/test-npcs.mjs +724 -0
- package/kits/hub-game/scripts/test-pack.mjs +424 -0
- package/kits/hub-game/scripts/test-party.mjs +369 -0
- package/kits/hub-game/scripts/test-say.mjs +149 -0
- package/kits/hub-game/scripts/test-tiers.mjs +666 -0
- package/kits/hub-game/scripts/test-together.mjs +215 -0
- package/kits/hub-game/theme.style +3 -0
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/avatars.js +101 -1
- package/kits/multiplayer-3d/code/server/players.js +4 -1
- package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
- package/kits/multiplayer-3d/code/server/world.js +20 -7
- package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
- package/kits/physics-2d/CLAUDE.md +2 -0
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/art.js +13 -0
- package/kits/physics-2d/engine/assets.js +4 -2
- package/kits/physics-2d/engine/scene.js +117 -5
- package/kits/physics-2d/package.json +1 -1
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
- package/kits/physics-3d/CLAUDE.md +285 -1
- package/kits/physics-3d/behaviors/Player.jsx +74 -1
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
- package/kits/physics-3d/engine3d/actornode.js +253 -0
- package/kits/physics-3d/engine3d/artobjects.js +2 -2
- package/kits/physics-3d/engine3d/materials.js +29 -1
- package/kits/physics-3d/engine3d/nearshadows.js +600 -0
- package/kits/physics-3d/engine3d/unchanged.js +153 -0
- package/kits/physics-3d/engine3d/world3d.js +527 -5
- package/kits/physics-3d/package.json +1 -1
- package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
- package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
- package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
- package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
- package/kits/physics-3d/systems/physics3d.js +187 -5
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/connection.js +77 -7
- package/kits/real-time/code/client/gameHooks.js +63 -3
- package/kits/real-time/code/client/messages.js +7 -0
- package/kits/real-time/code/server/gameHooks.js +24 -0
- package/kits/real-time/code/server/session.js +390 -22
- 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). `
|
|
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-
|
|
53
|
+
"version": "2026-10-04T22:43:17.146Z"
|
|
54
54
|
},
|
|
55
55
|
"castle.base": {
|
|
56
56
|
"deckId": "yRcmH4_aYllE",
|
|
57
|
-
"version": "2026-
|
|
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-
|
|
64
|
+
"publishedVersion": "2026-10-04T22:44:03.895Z"
|
|
65
65
|
}
|