castle-web-cli 0.4.231 → 0.4.233
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-failures.d.ts +8 -0
- package/dist/agent-failures.js +19 -2
- package/dist/agent-prompts.d.ts +1 -1
- package/dist/agent-prompts.js +10 -3
- package/dist/agent.d.ts +64 -3
- package/dist/agent.js +170 -81
- package/dist/castle-host/host.d.ts +1 -0
- package/dist/castle-host/host.js +51 -3
- package/dist/castleJson.d.ts +4 -2
- package/dist/castleJson.js +2 -0
- package/dist/check.d.ts +3 -1
- package/dist/check.js +11 -1
- package/dist/devSessionStorage.js +47 -1
- package/dist/importPinMismatch.d.ts +22 -0
- package/dist/importPinMismatch.js +77 -0
- package/dist/importRegression.js +3 -15
- package/dist/imports.d.ts +10 -3
- package/dist/imports.js +88 -20
- package/dist/index.js +5 -4
- package/dist/init.js +1 -1
- package/dist/platformDoc.js +22 -0
- package/dist/routerFences.d.ts +5 -0
- package/dist/routerFences.js +12 -2
- package/dist/save-deck.d.ts +5 -0
- package/dist/save-deck.js +37 -4
- package/dist/serve.js +3 -0
- package/dist/serverBundle.js +5 -3
- package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
- package/dist/shell/assets/index-MVLfNYd9.css +1 -0
- package/dist/shell/index.html +2 -2
- package/dist/taskSteer.d.ts +13 -0
- package/dist/taskSteer.js +22 -2
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/README.md +79 -2
- package/kits/base/sdk/avatar.d.ts +6 -2
- package/kits/base/sdk/avatar.js +12 -4
- package/kits/base/sdk/castle.d.ts +1 -1
- package/kits/base/sdk/commands.d.ts +14 -0
- package/kits/base/sdk/hub.d.ts +6 -2
- package/kits/base/sdk/hub.js +13 -0
- package/kits/base/sdk/multiplayer.js +17 -1
- package/kits/base/sdk/save.js +2 -1
- package/kits/base/sdk/server/hub.d.ts +87 -0
- package/kits/base/sdk/server/hub.js +70 -0
- package/kits/base/sdk/server/platformHandle.d.ts +31 -1
- package/kits/base/sdk/server/storage.d.ts +13 -0
- package/kits/base/sdk/server/storage.js +46 -0
- package/kits/base/sdk/server/wrapper.d.ts +36 -5
- package/kits/base/sdk/server/wrapper.js +83 -8
- package/kits/hub-game/CLAUDE.md +352 -12
- package/kits/hub-game/blueprints/avatar-10.scene +28 -0
- package/kits/hub-game/blueprints/avatar-11.scene +28 -0
- package/kits/hub-game/blueprints/avatar-12.scene +28 -0
- package/kits/hub-game/blueprints/avatar-13.scene +28 -0
- package/kits/hub-game/blueprints/avatar-14.scene +28 -0
- package/kits/hub-game/blueprints/avatar-15.scene +28 -0
- package/kits/hub-game/blueprints/avatar-4.scene +28 -0
- package/kits/hub-game/blueprints/avatar-5.scene +28 -0
- package/kits/hub-game/blueprints/avatar-6.scene +28 -0
- package/kits/hub-game/blueprints/avatar-7.scene +28 -0
- package/kits/hub-game/blueprints/avatar-8.scene +28 -0
- package/kits/hub-game/blueprints/avatar-9.scene +28 -0
- package/kits/hub-game/code/client/actorBudget.js +47 -0
- package/kits/hub-game/code/client/attention.js +11 -2
- package/kits/hub-game/code/client/avatar.js +345 -32
- package/kits/hub-game/code/client/avatarCap.js +228 -0
- package/kits/hub-game/code/client/avatarColors.js +70 -0
- package/kits/hub-game/code/client/avatarFaces.js +21 -0
- package/kits/hub-game/code/client/avatarShare.js +251 -0
- package/kits/hub-game/code/client/ballot.js +467 -0
- package/kits/hub-game/code/client/build.js +22 -0
- package/kits/hub-game/code/client/chat.js +12 -0
- package/kits/hub-game/code/client/chrome.js +1334 -50
- package/kits/hub-game/code/client/companion.js +716 -0
- package/kits/hub-game/code/client/companionDress.js +99 -0
- package/kits/hub-game/code/client/decor.js +509 -0
- package/kits/hub-game/code/client/earned.js +131 -0
- package/kits/hub-game/code/client/emoteBubble.js +75 -0
- package/kits/hub-game/code/client/grab.js +363 -20
- package/kits/hub-game/code/client/hats.js +26 -0
- package/kits/hub-game/code/client/hookLayer.js +328 -15
- package/kits/hub-game/code/client/hudClear.js +126 -0
- package/kits/hub-game/code/client/idle.js +163 -22
- package/kits/hub-game/code/client/interestCap.js +81 -0
- package/kits/hub-game/code/client/keys.js +36 -0
- package/kits/hub-game/code/client/labelsNear.js +205 -0
- package/kits/hub-game/code/client/menuIcons.js +34 -0
- package/kits/hub-game/code/client/pack.js +6 -2
- package/kits/hub-game/code/client/packFormat.js +3 -3
- package/kits/hub-game/code/client/rehello.js +167 -0
- package/kits/hub-game/code/client/shot.js +92 -0
- package/kits/hub-game/code/client/sound.js +63 -8
- package/kits/hub-game/code/client/soundscape.js +1151 -0
- package/kits/hub-game/code/client/soundscapeActions.js +99 -0
- package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
- package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
- package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
- package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
- package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
- package/kits/hub-game/code/client/soundscapeCues.js +362 -0
- package/kits/hub-game/code/client/soundscapeMap.js +181 -0
- package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
- package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
- package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
- package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
- package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
- package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
- package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
- package/kits/hub-game/code/client/soundscapeUi.js +211 -0
- package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
- package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
- package/kits/hub-game/code/client/spin.js +101 -0
- package/kits/hub-game/code/client/state.js +131 -1
- package/kits/hub-game/code/client/stuck.js +259 -0
- package/kits/hub-game/code/client/talk.js +538 -47
- package/kits/hub-game/code/client/tiers.js +541 -27
- package/kits/hub-game/code/client/toastBand.js +37 -0
- package/kits/hub-game/code/client/together.js +98 -1
- package/kits/hub-game/code/client/visibility.js +43 -0
- package/kits/hub-game/code/client/wear.js +470 -97
- package/kits/hub-game/code/client/yours.js +199 -0
- package/kits/hub-game/code/companionSpec.js +45 -0
- package/kits/hub-game/code/privateText.js +7 -0
- package/kits/hub-game/code/server/actions.js +133 -0
- package/kits/hub-game/code/server/actors.js +14 -1
- package/kits/hub-game/code/server/ask.js +155 -0
- package/kits/hub-game/code/server/ballot.js +539 -0
- package/kits/hub-game/code/server/cells.js +100 -0
- package/kits/hub-game/code/server/companion.js +82 -0
- package/kits/hub-game/code/server/cues.js +70 -0
- package/kits/hub-game/code/server/decor.js +269 -0
- package/kits/hub-game/code/server/earned.js +461 -0
- package/kits/hub-game/code/server/friendBests.js +166 -0
- package/kits/hub-game/code/server/friendsAmong.js +232 -0
- package/kits/hub-game/code/server/grab.js +296 -11
- package/kits/hub-game/code/server/history.js +5 -0
- package/kits/hub-game/code/server/hub.js +1317 -52
- package/kits/hub-game/code/server/idle.js +30 -11
- package/kits/hub-game/code/server/index.js +2 -2
- package/kits/hub-game/code/server/labels.js +28 -2
- package/kits/hub-game/code/server/manifest.js +424 -8
- package/kits/hub-game/code/server/menu.js +133 -0
- package/kits/hub-game/code/server/npcs.js +830 -80
- package/kits/hub-game/code/server/party.js +13 -2
- package/kits/hub-game/code/server/players.js +22 -0
- package/kits/hub-game/code/server/say.js +8 -2
- package/kits/hub-game/code/server/shot.js +110 -0
- package/kits/hub-game/code/server/standing.js +124 -0
- package/kits/hub-game/code/server/vis.js +113 -0
- package/kits/hub-game/code/server/wear.js +128 -11
- package/kits/hub-game/code/server/yours.js +59 -0
- package/kits/hub-game/code/shared/cues.js +9 -0
- package/kits/hub-game/code/shared/decor.js +41 -0
- package/kits/hub-game/code/shared/shot.js +19 -0
- package/kits/hub-game/code/shared/spin.js +57 -0
- package/kits/hub-game/code/systems/hub.js +1083 -85
- package/kits/hub-game/docs/content-pack.md +1 -1
- package/kits/hub-game/docs/contract.md +2440 -61
- package/kits/hub-game/docs/home-pieces.md +64 -0
- package/kits/hub-game/models/avatar-10.pxmodel +28 -0
- package/kits/hub-game/models/avatar-11.pxmodel +28 -0
- package/kits/hub-game/models/avatar-12.pxmodel +27 -0
- package/kits/hub-game/models/avatar-13.pxmodel +24 -0
- package/kits/hub-game/models/avatar-14.pxmodel +29 -0
- package/kits/hub-game/models/avatar-15.pxmodel +24 -0
- package/kits/hub-game/models/avatar-4.pxmodel +29 -0
- package/kits/hub-game/models/avatar-5.pxmodel +27 -0
- package/kits/hub-game/models/avatar-6.pxmodel +26 -0
- package/kits/hub-game/models/avatar-7.pxmodel +25 -0
- package/kits/hub-game/models/avatar-8.pxmodel +24 -0
- package/kits/hub-game/models/avatar-9.pxmodel +30 -0
- package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
- package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
- package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
- package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
- package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
- package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
- package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
- package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
- package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
- package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
- package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
- package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
- package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
- package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
- package/kits/hub-game/models/hats/cap.pxmodel +162 -0
- package/kits/hub-game/models/hats/captain.pxmodel +178 -0
- package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
- package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
- package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
- package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
- package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
- package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
- package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
- package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
- package/kits/hub-game/models/hats/straw.pxmodel +139 -0
- package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
- package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
- package/kits/hub-game/models/hats/witch.pxmodel +147 -0
- package/kits/hub-game/package-lock.json +2 -0
- package/kits/hub-game/package.json +2 -1
- package/kits/hub-game/scripts/check.mjs +78 -11
- package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
- package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
- package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
- package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
- package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
- package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
- package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
- package/kits/hub-game/scripts/gen-earned.mjs +285 -0
- package/kits/hub-game/scripts/gen-hats.mjs +827 -0
- package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
- package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
- package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
- package/kits/hub-game/scripts/test-actions.mjs +298 -0
- package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
- package/kits/hub-game/scripts/test-actors.mjs +19 -17
- package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
- package/kits/hub-game/scripts/test-ask.mjs +269 -0
- package/kits/hub-game/scripts/test-attention.mjs +10 -1
- package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
- package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
- package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
- package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
- package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
- package/kits/hub-game/scripts/test-avatar.mjs +540 -7
- package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
- package/kits/hub-game/scripts/test-build.mjs +31 -0
- package/kits/hub-game/scripts/test-cells.mjs +71 -0
- package/kits/hub-game/scripts/test-chat.mjs +694 -0
- package/kits/hub-game/scripts/test-classic.mjs +2 -0
- package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
- package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
- package/kits/hub-game/scripts/test-companion.mjs +259 -0
- package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
- package/kits/hub-game/scripts/test-decor.mjs +457 -0
- package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
- package/kits/hub-game/scripts/test-earned.mjs +1194 -0
- package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
- package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
- package/kits/hub-game/scripts/test-grab-client.mjs +186 -3
- package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
- package/kits/hub-game/scripts/test-grab.mjs +864 -3
- package/kits/hub-game/scripts/test-hats.mjs +483 -0
- package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
- package/kits/hub-game/scripts/test-hub-trip.mjs +1228 -1
- package/kits/hub-game/scripts/test-hud-clear.mjs +1000 -0
- package/kits/hub-game/scripts/test-idle.mjs +361 -1
- package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
- package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
- package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
- package/kits/hub-game/scripts/test-keys.mjs +46 -1
- package/kits/hub-game/scripts/test-labels.mjs +596 -0
- package/kits/hub-game/scripts/test-manifest.mjs +282 -0
- package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
- package/kits/hub-game/scripts/test-menu.mjs +296 -0
- package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
- package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
- package/kits/hub-game/scripts/test-pack.mjs +7 -0
- package/kits/hub-game/scripts/test-party.mjs +22 -1
- package/kits/hub-game/scripts/test-picker.mjs +314 -0
- package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
- package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
- package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
- package/kits/hub-game/scripts/test-say.mjs +59 -2
- package/kits/hub-game/scripts/test-shot.mjs +756 -0
- package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
- package/kits/hub-game/scripts/test-spin.mjs +314 -0
- package/kits/hub-game/scripts/test-standing.mjs +416 -0
- package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
- package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
- package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
- package/kits/hub-game/scripts/test-tiers.mjs +666 -3
- package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
- package/kits/hub-game/scripts/test-try-on.mjs +940 -0
- package/kits/hub-game/scripts/test-vis.mjs +343 -0
- package/kits/hub-game/scripts/test-visibility.mjs +134 -0
- package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
- package/kits/hub-game/scripts/test-yours.mjs +372 -0
- package/kits/multiplayer-3d/CLAUDE.md +50 -0
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/avatars.js +7 -0
- package/kits/multiplayer-3d/code/client/gait.js +65 -0
- package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
- package/kits/multiplayer-3d/code/options.js +5 -0
- package/kits/multiplayer-3d/code/server/ownership.js +10 -2
- package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
- package/kits/multiplayer-3d/code/server/world.js +7 -0
- package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
- package/kits/multiplayer-3d/package.json +2 -1
- package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
- package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
- package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
- package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
- package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
- package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
- package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
- package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
- package/kits/physics-2d/CLAUDE.md +9 -0
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/scene.js +288 -1
- package/kits/physics-2d/engine/skyKey.js +129 -0
- package/kits/physics-2d/engine/stillClock.js +106 -0
- package/kits/physics-2d/engine/updateBudget.js +21 -0
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +370 -1
- package/kits/physics-3d/CLAUDE.md +1391 -0
- package/kits/physics-3d/behaviors/Player.jsx +921 -3
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/docs/pxmodel-format.md +12 -0
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +98 -10
- package/kits/physics-3d/engine3d/actornode.js +86 -0
- package/kits/physics-3d/engine3d/animationBudget.js +23 -0
- package/kits/physics-3d/engine3d/editorWorld.js +6 -0
- package/kits/physics-3d/engine3d/emptynodes.js +232 -0
- package/kits/physics-3d/engine3d/framecap.js +96 -0
- package/kits/physics-3d/engine3d/gait.js +118 -0
- package/kits/physics-3d/engine3d/kithooks.js +47 -0
- package/kits/physics-3d/engine3d/look.js +507 -48
- package/kits/physics-3d/engine3d/lookbake.js +208 -0
- package/kits/physics-3d/engine3d/materialpresets.js +2 -0
- package/kits/physics-3d/engine3d/motion.js +39 -10
- package/kits/physics-3d/engine3d/nearshadows.js +37 -19
- package/kits/physics-3d/engine3d/optimize.js +58 -5
- package/kits/physics-3d/engine3d/orbitinput.js +755 -0
- package/kits/physics-3d/engine3d/orbitlens.js +48 -0
- package/kits/physics-3d/engine3d/ownmodel.js +213 -0
- package/kits/physics-3d/engine3d/pxmodel.js +42 -11
- package/kits/physics-3d/engine3d/shadowfade.js +882 -0
- package/kits/physics-3d/engine3d/sky.js +547 -0
- package/kits/physics-3d/engine3d/skylife.js +306 -0
- package/kits/physics-3d/engine3d/unchanged.js +11 -0
- package/kits/physics-3d/engine3d/viewrange.js +52 -0
- package/kits/physics-3d/engine3d/world3d.js +870 -87
- package/kits/physics-3d/main.jsx +5 -0
- package/kits/physics-3d/package.json +1 -1
- package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
- package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
- package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
- package/kits/physics-3d/scripts/test-camera-follow.mjs +12 -2
- package/kits/physics-3d/scripts/test-camera-orbit.mjs +4588 -0
- package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
- package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
- package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
- package/kits/physics-3d/scripts/test-gait.mjs +387 -0
- package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
- package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
- package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
- package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
- package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
- package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
- package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
- package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
- package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +13 -1
- package/kits/physics-3d/scripts/test-static-passes.mjs +1 -1
- package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
- package/kits/physics-3d/scripts/test-steady-hover.mjs +635 -0
- package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
- package/kits/physics-3d/systems/physics3d.js +474 -12
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/server/gameHooks.js +7 -0
- package/kits/real-time/code/server/session.js +97 -19
- package/package.json +2 -2
- package/dist/shell/assets/index-Cf61cNfT.css +0 -1
|
@@ -33,6 +33,9 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
33
33
|
- Motion goes through `scene.physics3d`, never by writing a dynamic actor's
|
|
34
34
|
Transform: `setVelocity(actor, {x,y,z})`, `applyImpulse`, `getVelocity`,
|
|
35
35
|
`mass`, `castRay(origin, dir, maxToi, excludeActor)` (rays skip sensors).
|
|
36
|
+
`addForce(actor, {x,y,z})` pushes through this frame's physics steps only
|
|
37
|
+
(ask every frame from `update` for a steady push; `resetForces(actor)`
|
|
38
|
+
drops what the frame asked): the camera section below has the rule.
|
|
36
39
|
Fixed/kinematic actors ARE moved by writing their Transform.
|
|
37
40
|
- The scene has the lighting rig built in (hemisphere + ambient + one
|
|
38
41
|
shadow-casting sun, ground plane at y=0); meshes cast and receive shadows
|
|
@@ -138,6 +141,299 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
138
141
|
local `matrix` written by hand while its `matrixAutoUpdate` is on (set
|
|
139
142
|
`position` / `quaternion` / `scale` instead); three.js private fields
|
|
140
143
|
written directly (`rotation._order`, `quaternion._x`).
|
|
144
|
+
- `"engine": { "dropEmptyParts": true }` at the scene file's top level (the
|
|
145
|
+
same `engine` object) asks the engine to place models without the groups
|
|
146
|
+
that draw nothing. A placed model is a game build: its meshes are merged
|
|
147
|
+
into a few draw calls, but every part keeps its own three.js group, most of
|
|
148
|
+
them then empty, and three.js and the engine visit every object under the
|
|
149
|
+
scene on every frame. A town of a few hundred models is two thirds such
|
|
150
|
+
groups. The terms:
|
|
151
|
+
> With the key absent, a model is built and placed exactly as before: the
|
|
152
|
+
> same objects, the same shared build, the same node. With the key present,
|
|
153
|
+
> every object that is drawn (a mesh, its outline, anything that is not a
|
|
154
|
+
> plain group) is the same object with the same geometry, material and
|
|
155
|
+
> world matrix as without it, on every frame, and walks, `motion`, clips and
|
|
156
|
+
> glow play the same. What a deck must not rely on under the key is finding
|
|
157
|
+
> the group of a part that draws nothing unless that part is one that
|
|
158
|
+
> stays.
|
|
159
|
+
|
|
160
|
+
What goes: a group with nothing drawn on it or anywhere under it -- no
|
|
161
|
+
mesh, line, points, sprite, light or camera. That includes the group of a
|
|
162
|
+
part that IS drawn when its mesh was merged into a batch on the model's
|
|
163
|
+
root or on a moving part: the picture keeps the part, `modelParts` does
|
|
164
|
+
not. What always stays, with every group above it:
|
|
165
|
+
- a part marked `keep: true` (docs/pxmodel-format.md: "for a deck that
|
|
166
|
+
reaches for it by id"), with its own mesh as before;
|
|
167
|
+
- a part named `slot-...`. The format's docs let a deck "parent your own
|
|
168
|
+
parts to it", and nothing says that happens only in the model file, so a
|
|
169
|
+
slot is never dropped: a deck may hang a mesh on one at runtime and it is
|
|
170
|
+
drawn where it would be without the key;
|
|
171
|
+
- a part the walk moves (`legL`, `legR`, `armL`, `armR`, `torso`) or the
|
|
172
|
+
model's `motion`, gait or `clips` move, drawn or not, and every copy of
|
|
173
|
+
one;
|
|
174
|
+
- anything a kept part or slot holds that is not another part.
|
|
175
|
+
|
|
176
|
+
An actor whose model draws nothing at all (an invisible collider placing an
|
|
177
|
+
empty model) gets no rig group under its node: the node is there, with
|
|
178
|
+
`userData.modelParts` an empty Map and no children.
|
|
179
|
+
So under the key:
|
|
180
|
+
- `scene.three.nodes.get(id).node.userData.modelParts` holds only the parts
|
|
181
|
+
that stayed. `modelParts.get('door')` for a part that draws nothing and
|
|
182
|
+
is none of the above is `undefined`, where without the key it is an empty
|
|
183
|
+
group. To reach for an empty part as a locator (a muzzle, a hand), mark
|
|
184
|
+
it `keep: true` or name it `slot-...`; it then stands exactly where it
|
|
185
|
+
did.
|
|
186
|
+
- code that walks a node's tree counts fewer objects, and a node's first
|
|
187
|
+
child is its rig only when its model draws something.
|
|
188
|
+
- nothing else changes: which actors have nodes, `userData.actorId`, the
|
|
189
|
+
rig's `yOffset` and `scale`, physics, picking, shadows (casters are
|
|
190
|
+
culled by their own meshes' bounds), `instanceModels`.
|
|
191
|
+
|
|
192
|
+
It is read when the scene loads, as `skipUnchangedActors` is, and each
|
|
193
|
+
scene decides for itself: a node and a shared model build made for a scene
|
|
194
|
+
that asked are never used for one that did not, or the other way round (a
|
|
195
|
+
resident scene parked while another plays, a pack mounted in a town, a door
|
|
196
|
+
trip, a scene file reloaded with the key changed -- every node is then
|
|
197
|
+
built again). The scene editor and the play panel draw a scene through the
|
|
198
|
+
same engine, so both follow the scene's key; the editor selects actors, not
|
|
199
|
+
parts, and is not affected. The model editor and `npm run render` build a
|
|
200
|
+
model for themselves, with every part's group, whatever any scene says.
|
|
201
|
+
Opt in with `skipUnchangedActors` when a scene is hundreds of placed
|
|
202
|
+
models; a scene of a few gains nothing.
|
|
203
|
+
- `"engine": { "skipEmptyNodes": true }` at the scene file's top level
|
|
204
|
+
keeps an actor with no children on its three.js node outside the play scene.
|
|
205
|
+
Empty markers, anchors and triggers then cost no scene object. A missing or
|
|
206
|
+
invalid Model with no Shape is empty; a Model that builds a rig is not,
|
|
207
|
+
even if its rig draws nothing. With `dropEmptyParts`, a model reduced to no
|
|
208
|
+
rig is empty too. The key is read on load, and only exactly `true` opts in.
|
|
209
|
+
Without it, nodes, signatures and shared model caches are exactly as before.
|
|
210
|
+
A player whose scenes never ask creates no mode record, system or listeners.
|
|
211
|
+
The player arms the mode only
|
|
212
|
+
after a keyed scene has finished loading; syncs never arm it. The scene
|
|
213
|
+
editor always keeps its nodes.
|
|
214
|
+
|
|
215
|
+
`scene.three.nodes` keeps every entry and its usual Group/ActorNode, with
|
|
216
|
+
position, rotation and world matrix placed by the engine even while detached.
|
|
217
|
+
Move an empty actor through its Transform (or physics), not by writing the
|
|
218
|
+
detached node's position, quaternion, rotation or scale directly: those
|
|
219
|
+
writes are outside this key's contract and do not update its world matrix
|
|
220
|
+
until the node has a child and is attached again.
|
|
221
|
+
No transform properties or methods are wrapped. Adding a
|
|
222
|
+
child queues attachment at the next actor sync; removing its last child
|
|
223
|
+
queues detachment there too, after three.js event dispatch completes.
|
|
224
|
+
Build and child events queue classification for the next outermost sync;
|
|
225
|
+
listeners only mark dirty, and syncs inside event dispatch defer the queue.
|
|
226
|
+
Dispatch depth unwinds even if a listener throws. A load, reset or disposal
|
|
227
|
+
invalidating a pass aborts it before any further placement or attachment.
|
|
228
|
+
Settled frames scan no nodes.
|
|
229
|
+
Only detached empty nodes whose pose changes receive a matrix update; a
|
|
230
|
+
settled static empty actor needs none. Load/reset gives nodes back before
|
|
231
|
+
the next scene runs, leaving keyless sync on its original path.
|
|
232
|
+
Gaining or losing a Model/Shape follows the usual look rebuild, including
|
|
233
|
+
spawn, reload, resident scenes and `staticActors` (call `scene.touch` before
|
|
234
|
+
changing a static actor, as usual). A node deliberately hidden or reparented
|
|
235
|
+
by a consumer stays under that consumer's control. Low-tier bounds and
|
|
236
|
+
hiding, avatar parts and attachments keep using the same entries. Traversing
|
|
237
|
+
the play scene excludes empty actors; traverse `scene.three.nodes` to find
|
|
238
|
+
all actors. If the scene itself has a transform or a parent, nodes stay
|
|
239
|
+
attached so world-space reads retain that transform.
|
|
240
|
+
- `"engine": { "staticActors": true }` at the scene file's top level (the same
|
|
241
|
+
`engine` object), in a scene that also sets `skipUnchangedActors`, asks the
|
|
242
|
+
engine to leave alone the actors the scene file marks as scenery:
|
|
243
|
+
`"static": true` on the actor, beside its `id` and `components`. With
|
|
244
|
+
`skipUnchangedActors` the engine still asks, of every actor on every frame,
|
|
245
|
+
whether anything it is drawn or simulated from has changed; for a town that
|
|
246
|
+
is mostly buildings, that asking is a quarter of a slow phone's frame. A
|
|
247
|
+
marked actor is not asked. The terms:
|
|
248
|
+
> With the key absent, or without `skipUnchangedActors`, a scene runs the
|
|
249
|
+
> engine exactly as before, whatever its actors are marked. With both, a
|
|
250
|
+
> marked actor that is still is drawn and simulated exactly as it was on the
|
|
251
|
+
> last frame the engine looked at it, until the engine is told it is being
|
|
252
|
+
> changed: `scene.touch(actorOrId)`. From the frame of the touch on, the
|
|
253
|
+
> actor is an ordinary one, followed as every actor is under
|
|
254
|
+
> `skipUnchangedActors`, until the next scene load. **A change to a marked
|
|
255
|
+
> actor made without `scene.touch` is not followed**: a component's field
|
|
256
|
+
> written, a component added, removed or switched off (`$enabled`), its
|
|
257
|
+
> node or any object under it moved, hidden or given children. Nothing in a
|
|
258
|
+
> published deck notices such a write.
|
|
259
|
+
|
|
260
|
+
This is the one `engine` key under which "nothing has to be marked dirty"
|
|
261
|
+
stops being true, and only for the actors a scene marks. Mark what nothing
|
|
262
|
+
ever writes; touch before writing anything else.
|
|
263
|
+
|
|
264
|
+
Only actors are marked. What the engine draws that is not an actor -- the
|
|
265
|
+
sun and its shadow camera, the camera, a sky the engine itself draws from
|
|
266
|
+
an `engine` key -- has no `static` to carry and is not
|
|
267
|
+
part of the still set: it is drawn and moved as it always is, every frame,
|
|
268
|
+
whatever the scene marks. A sky that IS an actor (one `Model` on a
|
|
269
|
+
`Transform`, as the hub town's is) is marked like any other scenery.
|
|
270
|
+
|
|
271
|
+
Which marked actors are still. A marked actor is still when it was in the
|
|
272
|
+
scene file at load (a spawned actor never is), has no `Body`, none of its
|
|
273
|
+
components' classes has an `update`, `onEnable` or `onDisable`, its model
|
|
274
|
+
does not walk or move inside itself (the engine finds that out when it has
|
|
275
|
+
built the node, and touches the actor itself), and nothing has touched it
|
|
276
|
+
since the load. Any other marked actor is an ordinary actor; the mark costs
|
|
277
|
+
nothing. `scene.stillActors` is the Set (null in a scene without the key).
|
|
278
|
+
|
|
279
|
+
What tells the engine, so a deck does not have to:
|
|
280
|
+
- `scene.despawnActor`, `scene.load` / `loadFromFile` / `setContent`,
|
|
281
|
+
`scene.setBehaviors` (the still set is reckoned again; what was touched
|
|
282
|
+
stays touched);
|
|
283
|
+
- `scene.physics3d.setVelocity`, `applyImpulse` and `addForce` touch the
|
|
284
|
+
actor they are handed. `bodyOf` does not: asking for a body is not a
|
|
285
|
+
change, and a marked actor's body made dynamic or kinematic through it
|
|
286
|
+
needs a `scene.touch`;
|
|
287
|
+
- the multiplayer-3d kit touches an actor before it writes a network pose
|
|
288
|
+
on it, and hub-game before it hides, shows or tints an actor or swings a
|
|
289
|
+
door (`hub.hide`, `hub.show`, `hub.tint`; `hub.move` arrives as a network
|
|
290
|
+
pose), so a place's server may do those to a marked actor;
|
|
291
|
+
- what marked actors share is watched for all of them at once, and followed
|
|
292
|
+
with no touch: a model file edited (or a file or art it reads), art that
|
|
293
|
+
finishes loading, the look switched, the scene itself
|
|
294
|
+
(`scene.three.scene`) moved, turned or scaled.
|
|
295
|
+
|
|
296
|
+
A behaviour, a collision callback or any other deck code that writes
|
|
297
|
+
another, marked actor calls `scene.touch(id)` first; it is a Set delete,
|
|
298
|
+
safe to call every frame and on any actor, and does nothing in a scene
|
|
299
|
+
without the key. `scene.touch` exists on every scene, so code that may run
|
|
300
|
+
under an older kit calls `scene.touch?.(id)`.
|
|
301
|
+
|
|
302
|
+
What "left alone" means, frame by frame. A still actor is not visited by
|
|
303
|
+
`scene.update` (it has nothing to update), by the pass that builds and
|
|
304
|
+
places nodes, or by the physics pass (its body is fixed and where it was
|
|
305
|
+
put); and its node's `updateMatrixWorld` returns at once, so its matrices
|
|
306
|
+
are not recomputed or even compared. three.js still walks its objects to
|
|
307
|
+
cull and draw them, and rapier still collides with its body. So:
|
|
308
|
+
- `scene.getActors()`, `getActor`, `actorWith` and the node map
|
|
309
|
+
(`scene.three.nodes`) are unchanged: a still actor is in all of them, with
|
|
310
|
+
its node, and the node's `position` is its Transform's;
|
|
311
|
+
- a still actor's node may be taken out of the scene and put back under the
|
|
312
|
+
same parent by deck code (hub-game's low picture does, by distance): it
|
|
313
|
+
comes back drawn where it was, with no touch. Putting it under another
|
|
314
|
+
parent is a change to it;
|
|
315
|
+
- a frame on which the still set changes (a touch, a despawn), and the one
|
|
316
|
+
after, visit every actor once, as a frame under `skipUnchangedActors`
|
|
317
|
+
alone does, before the rest are left alone again; so does a frame on
|
|
318
|
+
which a node is built, rebuilt or released. Touching a different actor
|
|
319
|
+
every frame gives the key's saving away: such actors should not be
|
|
320
|
+
marked.
|
|
321
|
+
|
|
322
|
+
Where the key does nothing: without `skipUnchangedActors`; in the scene
|
|
323
|
+
editor, which changes actors as it pleases; and in a world with
|
|
324
|
+
`instanceModels` on. In a scene with a
|
|
325
|
+
`scene.three.scene.userData.groundHeight` callback no node is frozen (every
|
|
326
|
+
pass there runs the old way, as under `skipUnchangedActors`), though still
|
|
327
|
+
actors are still left out of `update` and the physics pass.
|
|
328
|
+
|
|
329
|
+
How it stays right (`engine3d/world3d.js` has the rule and the code):
|
|
330
|
+
> A pass is ordinary (every actor, as the skipping pass runs it) unless the
|
|
331
|
+
> still set and the things its actors share read as they did when the last
|
|
332
|
+
> ordinary pass that ended alone adopted them; then a still actor is left
|
|
333
|
+
> exactly as that pass left it.
|
|
334
|
+
>
|
|
335
|
+
> The still set is adopted only after an ordinary pass has completed
|
|
336
|
+
> without throwing. While any ordinary pass, or anything a pass calls back
|
|
337
|
+
> into, is running, nothing is frozen and no still state is trusted. Any
|
|
338
|
+
> interruption leaves the next pass ordinary.
|
|
339
|
+
|
|
340
|
+
The second paragraph is one mechanism, used the same way in the three
|
|
341
|
+
places that leave still actors out (the runtime's `update`, the pass that
|
|
342
|
+
places nodes, the physics pass): each has a keeper
|
|
343
|
+
(physics-2d `engine/stillClock.js` `StillKeeper`) that counts every entry
|
|
344
|
+
into its pass, settled or ordinary, by any runtime, nested or not. A pass
|
|
345
|
+
may be settled only on an adoption made, or last confirmed, at the count
|
|
346
|
+
as it stood just before the pass entered, for the very version of the still
|
|
347
|
+
set the runtime has now; otherwise the adoption is dropped there, before
|
|
348
|
+
the pass does anything. A new adoption is recorded only at the very end of
|
|
349
|
+
the whole operation (for `update`: after the behaviours and every system;
|
|
350
|
+
for the physics pass: after the step, the write-back and the collision
|
|
351
|
+
callbacks), and only if the pass returned, nobody else entered, and the
|
|
352
|
+
still set is unmoved. Nothing is ever put back. So code that walks, draws,
|
|
353
|
+
syncs or updates the scene from inside a pass, settled or not, sees what
|
|
354
|
+
it sees without the key; a behaviour, a system, a node being built or
|
|
355
|
+
released, rapier's step or a collision callback that throws leaves nothing
|
|
356
|
+
adopted; and a pass entered from inside another, by the same runtime or a
|
|
357
|
+
different one, whether it returns or throws and is caught, leaves the pass
|
|
358
|
+
around it unable to adopt, and the next pass ordinary. The keeper of a
|
|
359
|
+
world, and of a physics system, sees every pass of every kind from the
|
|
360
|
+
moment it exists, not only those of scenes that ask: a scene without
|
|
361
|
+
`skipUnchangedActors` played on the same world or the same physics system
|
|
362
|
+
(a pack mounted in a town, a callback that syncs another scene) drops what
|
|
363
|
+
was adopted when it enters and adopts nothing.
|
|
364
|
+
|
|
365
|
+
World disposal, standalone ground replacement, physics-debug updates,
|
|
366
|
+
resizing and the editor's orbit-lens return are counted for their whole
|
|
367
|
+
duration by `outsideCall`: `keeper.begin(NOT_STILL)`, adoption dropped and
|
|
368
|
+
nodes thawed, then `keeper.end(pass, false)` in a `finally`. While this pass
|
|
369
|
+
is running, no listener's nested sync can adopt or freeze, including between
|
|
370
|
+
two listeners or two disposable targets. Near shadows use the same bracket
|
|
371
|
+
across both map and blur-map disposal, only when a non-null map is released
|
|
372
|
+
(a fit size change, mode leave, or world disposal). Their callback is made
|
|
373
|
+
once per world and reused across frames and mode recreation. Unchanged
|
|
374
|
+
near-shadow frames keep their adoption and frozen nodes. The sky uses the
|
|
375
|
+
same bracket for each record release (prepare, settle, load or world
|
|
376
|
+
disposal), across every texture, geometry and material listener, and for
|
|
377
|
+
the textures shed after a step. Its callback is acquired only when a sky
|
|
378
|
+
record is made, stored on the world and reused by later records. Unchanged
|
|
379
|
+
sky frames keep their adoption and frozen nodes. On return or throw
|
|
380
|
+
the bracket exits with nothing adopted; the next actor pass is ordinary and
|
|
381
|
+
later passes may settle. A disposed world never adopts again.
|
|
382
|
+
World disposal returns the orbit lens, releases the sky, drops near shadows
|
|
383
|
+
and disposes nodes in that order, each cleanup in the previous one's
|
|
384
|
+
`finally`. All four run even if the lens or an earlier listener throws;
|
|
385
|
+
the first thrown value wins, including a falsy value such as `0`.
|
|
386
|
+
Sky preparation reads engine art through own data-property descriptors,
|
|
387
|
+
never through an accessor, so these reads need no call-out bracket and do
|
|
388
|
+
not drop static adoption on unchanged frames.
|
|
389
|
+
|
|
390
|
+
Before a world has a keeper, `outsideCall` uses `world.unkept` exactly as a
|
|
391
|
+
plain `syncActors` pass does: increment before the operation and decrement
|
|
392
|
+
in a `finally`. A keeper made by a listener sees this count, so none of its
|
|
393
|
+
nested passes can settle or adopt while the operation runs. On exit, if a
|
|
394
|
+
keeper was made, its adoption is dropped and nodes thawed again, leaving
|
|
395
|
+
the next pass ordinary even when the operation throws.
|
|
396
|
+
|
|
397
|
+
Key-absent inventory of the added statements at these call-outs: with no
|
|
398
|
+
`stillKeeper`, `disposeWorld` and `resizeWorld` each add a keeper test, an
|
|
399
|
+
`unkept` increment, a `try/finally`, a decrement and an exit keeper test;
|
|
400
|
+
`updatePhysicsDebug` does the same when buffers exist, `syncGround` when
|
|
401
|
+
the ground changes, and the editor's orbit-lens return when a lens exists.
|
|
402
|
+
Near shadows add no keeper test or new callback allocation on an unchanged frame:
|
|
403
|
+
they reuse the world's lazy callback. A release adds the same `unkept`
|
|
404
|
+
bracket for the entire operation, only when a map or blur map exists. The
|
|
405
|
+
sky allocates its callback only for an actual sky record: a world that never
|
|
406
|
+
has one makes none. Unchanged sky frames do not test or call the hook; a
|
|
407
|
+
record release or a nonempty shed-texture disposal adds the same bracket.
|
|
408
|
+
Rare operations pass a closure to `outsideCall`; with no keeper it runs
|
|
409
|
+
inside this count. Only a keeper made during the call adds `dropStill` on exit.
|
|
410
|
+
None makes a keeper with the key absent.
|
|
411
|
+
|
|
412
|
+
The runtime keeps the still set and a number that moves whenever the set
|
|
413
|
+
changes (`scene.stillActors`, `scene.stillVersion`; one sequence of
|
|
414
|
+
numbers for every scene, so no two states share one); the world and the
|
|
415
|
+
physics system each keep the number they adopted, and a pass decides from
|
|
416
|
+
its own runtime, at its start, whether it may leave anything out. A node is
|
|
417
|
+
frozen by two numbers on it, matched against one on the world that only
|
|
418
|
+
ever moves on, so every frozen node of a world thaws at once with nothing
|
|
419
|
+
to visit. Between passes a frozen node guards itself, on every walk of the
|
|
420
|
+
scene, whoever walks it: it is frozen only while no scene's still set has
|
|
421
|
+
changed since it froze (so `scene.touch` thaws at once: an actor touched
|
|
422
|
+
and then posed by its node is followed by the very next draw), and only
|
|
423
|
+
while it is under the parent it froze under and that parent's world matrix
|
|
424
|
+
is the one three.js has just computed for it (so the scene moved, by its
|
|
425
|
+
position, its matrix written by hand, or a parent of its own, is followed
|
|
426
|
+
by the next walk).
|
|
427
|
+
|
|
428
|
+
For QA, never in play: `scene.three.auditStatic = n` checks `n` still
|
|
429
|
+
actors a frame, in turn, the way an ordinary frame would have (and every
|
|
430
|
+
still body), writes what it finds changed to
|
|
431
|
+
`scene.three.staticAuditFailures` as `{ id, what }`, warns once an actor,
|
|
432
|
+
and touches it. Set it to `Infinity` to check every still actor every
|
|
433
|
+
frame: a deck that marks actors should be played that way once with
|
|
434
|
+
nothing reported.
|
|
435
|
+
Opt in when a scene is hundreds of actors that are never written; a scene
|
|
436
|
+
whose scenery is a dozen actors gains nothing.
|
|
141
437
|
- `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
|
|
142
438
|
(the same `engine` object) asks the engine to draw the sun's shadows where
|
|
143
439
|
they can be seen, near the camera, rather than in the sun's fixed box.
|
|
@@ -154,6 +450,127 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
154
450
|
> range below; a point farther off may or may not be shadowed, and nothing
|
|
155
451
|
> cuts shadows off there.
|
|
156
452
|
|
|
453
|
+
Past `distance` on a frame the mode draws, a point may or may not be
|
|
454
|
+
shadowed (a caster kept for a nearer point shadows farther ones too), and
|
|
455
|
+
past the edge of the mode's box nothing is: three.js leaves a point
|
|
456
|
+
outside the shadow map lit, and the sun's own shadow is not drawn on such
|
|
457
|
+
a frame. Under a fixed camera looking down that edge is off screen.
|
|
458
|
+
|
|
459
|
+
Under the orbit camera key as well (below), which tilts the camera to the
|
|
460
|
+
horizontal where that edge would be a hard line across the ground, a frame
|
|
461
|
+
the mode draws fades the sun's shadow out toward it
|
|
462
|
+
(`engine3d/shadowfade.js`): whole up to 0.75 of the mode's reach (the
|
|
463
|
+
distance it could fit, along the way the camera looks), gone at the reach,
|
|
464
|
+
smoothstep between, to full sun, which is what lies beyond. How:
|
|
465
|
+
> The fade writes no material, not even for a moment, and the scene's,
|
|
466
|
+
> the faded meshes' and the faded materials' own callbacks never meet a
|
|
467
|
+
> variant. What gets one: a material whose class is exactly one of
|
|
468
|
+
> three's own lit ones (standard, physical, lambert, phong, toon; a
|
|
469
|
+
> subclass is not faded), alone on its mesh (a mesh with an array of
|
|
470
|
+
> materials is not faded), whose hooks, listeners and mesh are plain
|
|
471
|
+
> data (read from property descriptors: one behind a deck's accessor is
|
|
472
|
+
> not faded, and the fade never calls a getter), and whose `onBeforeCompile`,
|
|
473
|
+
> `customProgramCacheKey` and `onBeforeRender` are three's own or the
|
|
474
|
+
> kit's (`engine3d/kithooks.js`: look.js, optimize.js,
|
|
475
|
+
> materialpresets.js), on a mesh that receives shadows and has no
|
|
476
|
+
> `onBeforeRender` or `onAfterRender` of its own; and a frame is faded
|
|
477
|
+
> only when the scene has no `onBeforeRender` of its own. Anything else
|
|
478
|
+
> is drawn as it is, unfaded. A variant is a separate material object to
|
|
479
|
+
> the renderer whose every property, read or written, is the original's:
|
|
480
|
+
> its prototype, shared per material class, has a forwarding accessor for
|
|
481
|
+
> each property and accessor of the class, over a proxy that answers
|
|
482
|
+
> anything else from the original; so deck code inside the frame that
|
|
483
|
+
> reaches a variant (an LOD's `update`, a callback installed mid-frame and
|
|
484
|
+
> handed the material three listed) and three's own side flip and version
|
|
485
|
+
> bumps write the original as they would without the key. Its events and
|
|
486
|
+
> `dispose` are the original's too; only the renderer's own dispose
|
|
487
|
+
> listener for the variant's program (known by its function, learned
|
|
488
|
+
> once per renderer by compiling a private material and finishing its
|
|
489
|
+
> program's first-use initialization before disposing it) is held by the
|
|
490
|
+
> variant (and added to
|
|
491
|
+
> the original, where the renderer drawing it would have it), and the
|
|
492
|
+
> variant's program is let go of when the variant is disposed or dropped
|
|
493
|
+
> or the original is disposed (seen by a dispose listener gone from the
|
|
494
|
+
> original, or by the renderer's own entry for the original replaced,
|
|
495
|
+
> when the world's renderer also draws it elsewhere). Its own: an id, that listener, and the
|
|
496
|
+
> shader hooks held as they were when it was made (the held
|
|
497
|
+
> `onBeforeCompile` then the fade; the held key plus
|
|
498
|
+
> `|near-shadow-fade`). Before each faded frame it is drawn in it is
|
|
499
|
+
> dropped if the original has other hooks or is no longer one to fade. A
|
|
500
|
+
> hook the original is given inside a frame is never run for the
|
|
501
|
+
> variant: it compiles with the held hook under a key of its own and is
|
|
502
|
+
> dropped next frame. A property defined on a variant reaches the
|
|
503
|
+
> original after the frame; deck code that compares a variant by
|
|
504
|
+
> identity with its original, asks it `key in` or deletes through it sees
|
|
505
|
+
> another object. The fade's
|
|
506
|
+
> uniform is on the variants only. The variants go on the meshes right
|
|
507
|
+
> before the mode's one render call, and come off in a hook on the world
|
|
508
|
+
> renderer's `shadowMap.render`, which three calls on every render after
|
|
509
|
+
> listing the draws and before drawing any, whatever the shadow
|
|
510
|
+
> settings; the hook comes off when the sun gets its own shadow back,
|
|
511
|
+
> whatever the render did (one a deck replaced meanwhile stays replaced,
|
|
512
|
+
> and ours, if it still calls it, only calls the pass it had). So the
|
|
513
|
+
> frame's own draws use the variants and every render after its list of
|
|
514
|
+
> draws sees the originals. Accepted, inside the keyed world's own frame
|
|
515
|
+
> only: a deck's own sort comparator (`renderer.setOpaqueSort` /
|
|
516
|
+
> `setTransparentSort`) is handed render items holding the variants. A
|
|
517
|
+
> variant not drawn for 60 faded frames is disposed; all are disposed on
|
|
518
|
+
> a scene load, an editor frame, any frame of a scene without both keys
|
|
519
|
+
> and `disposeWorld`. The fade is for the first casting directional
|
|
520
|
+
> light, and a frame is faded only when that is the sun. Not covered: a
|
|
521
|
+
> hook or callback that changes in place an object the original holds by
|
|
522
|
+
> reference (its colour, a texture, its defines) changes it for every
|
|
523
|
+
> world, as it would without the key. A material that is itself a Proxy
|
|
524
|
+
> can observe the fade's reads through its traps. Deck getters with side
|
|
525
|
+
> effects on properties three reads during a render (`isMesh`, `visible`,
|
|
526
|
+
> `children`, `matrixWorld`, `layers`, ...) may run extra times in a
|
|
527
|
+
> faded frame. A mesh whose `material` is not its own writable,
|
|
528
|
+
> configurable data property (read-only, an accessor, or inherited from
|
|
529
|
+
> its prototype) is drawn unfaded, and so is a frame whose
|
|
530
|
+
> renderer's `shadowMap.render` cannot take the hook (it goes on before
|
|
531
|
+
> any variant does). A deck that makes `shadowMap.render` read-only
|
|
532
|
+
> during a keyed frame has it put back (redefined) if it is still
|
|
533
|
+
> configurable; one it also makes non-configurable keeps the fade's
|
|
534
|
+
> hook, inert from then on: it only calls the pass it had. A deck
|
|
535
|
+
> setter on a mesh's `material` that throws when the material is put
|
|
536
|
+
> back holds that mesh, as below. Giving the meshes their materials back is total:
|
|
537
|
+
> each mesh on its own. A deck that redefines or locks its own mesh's
|
|
538
|
+
> `material` during a keyed render gets the best the fade can do without
|
|
539
|
+
> calling its getter: a data property made read-only but configurable
|
|
540
|
+
> is redefined with the deck's attributes and the original's value; an
|
|
541
|
+
> accessor with a setter has the original set through it once; anything
|
|
542
|
+
> else (read-only and not configurable, an accessor without a setter)
|
|
543
|
+
> keeps its variant, which reads and writes the original, and is tried
|
|
544
|
+
> again at every frame boundary while the fade lasts. Once the fade is
|
|
545
|
+
> dropped such a variant is inert: it keys and compiles exactly as its
|
|
546
|
+
> original, so later keyless frames draw the original's program. Its
|
|
547
|
+
> programs are not freed by a later `dispose()` of the original (that
|
|
548
|
+
> would take a listener on the shared material): on such a mesh only,
|
|
549
|
+
> each dispose and recompile leaves one program behind.
|
|
550
|
+
> Two more limits, inside the keyed world's own frame: a variant's
|
|
551
|
+
> properties live on its prototype (the forwarders), so deck code run
|
|
552
|
+
> during that frame (an LOD's `update`, a draw callback) that copies a
|
|
553
|
+
> mesh's material with a spread, `Object.keys` or own-property checks
|
|
554
|
+
> sees none of them, and whatever it writes from that copy differs from
|
|
555
|
+
> without the key (on a material shared with a keyless world, that world
|
|
556
|
+
> draws the write too). And a deck that defines a read-only, non-configurable
|
|
557
|
+
> property on one of three's own material prototypes, then shadows it on
|
|
558
|
+
> a material, makes a read of that property through a variant throw a
|
|
559
|
+
> `TypeError` (the forwarder is a Proxy, which must report the
|
|
560
|
+
> prototype's value). Neither happens in a world without the keys.
|
|
561
|
+
|
|
562
|
+
Without both keys nothing of this runs: the same materials, programs,
|
|
563
|
+
program keys, shader sources and draws as before
|
|
564
|
+
(scripts/test-orbit-shadow-fade.mjs, on three.js's own WebGLRenderer over
|
|
565
|
+
a context that draws nothing, also with a keyed and a keyless world
|
|
566
|
+
sharing materials). Under both keys the first faded frame compiles one
|
|
567
|
+
program per distinct lit program in view (a hitch, once), and each faded
|
|
568
|
+
frame walks the scene's visible objects and swaps each receiving lit
|
|
569
|
+
mesh's material twice, and three reads each variant's properties through
|
|
570
|
+
the forwarders. In node over a context that draws nothing, 500 receiving
|
|
571
|
+
meshes on 40 materials take about 2.7 ms a frame with the fade against
|
|
572
|
+
about 1.8 ms with near shadows alone (the JavaScript side only).
|
|
573
|
+
|
|
157
574
|
The depth range is the sun's own `near` and `far` along the light, measured
|
|
158
575
|
from the engine's shadow camera, which stands as far from the middle of the
|
|
159
576
|
view's sphere (taken along the light to the height of the sun's target) as
|
|
@@ -189,6 +606,9 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
189
606
|
frustum it culls by, inside the renderer, where the engine can neither read
|
|
190
607
|
it nor put it back. Nothing in the kits does any of the above after
|
|
191
608
|
`makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
|
|
609
|
+
(With the orbit key as well, the far-edge fade below puts a hook on the
|
|
610
|
+
world renderer's `shadowMap.render` for the one render call, and takes
|
|
611
|
+
it off after.)
|
|
192
612
|
|
|
193
613
|
Within that, the mode draws a frame only when all of these hold; otherwise
|
|
194
614
|
the frame is drawn exactly as without the key. They are cheap protection,
|
|
@@ -337,6 +757,960 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
337
757
|
The play panel and a published deck play the scene through the same
|
|
338
758
|
runtime, so both follow the scene's key; the scene editor's own orbit
|
|
339
759
|
camera is not a follow camera and is not affected.
|
|
760
|
+
|
|
761
|
+
The key means "the player is held steady on screen", so it also changes
|
|
762
|
+
how the `Player` hovers. Without it the hover spring (and the fall-faster
|
|
763
|
+
pull) is an impulse, pushed once per drawn frame, while gravity pulls once
|
|
764
|
+
per fixed 1/60 physics step, and a frame takes none, one or two steps: on
|
|
765
|
+
a frame that is not exactly one step the player is kicked up or let drop,
|
|
766
|
+
a bob of 0.6 to 2 cm walking on a phone, which a camera that holds the
|
|
767
|
+
player still would show as the whole view bobbing. The terms:
|
|
768
|
+
> With the key absent, the Player makes the calls on `scene.physics3d` it
|
|
769
|
+
> made before, with the same arguments, in the same order. With the key
|
|
770
|
+
> present, the hover and the fall-faster pull are forces
|
|
771
|
+
> (`scene.physics3d.addForce`), which act once per physics step as gravity
|
|
772
|
+
> does: walking on flat ground the player's height does not move, whatever
|
|
773
|
+
> the frame lengths. The spring is the same one (160 and 18), resting
|
|
774
|
+
> 1.38 cm higher (`STEADY_REST`) so that the kit's player (gravity scale
|
|
775
|
+
> 2) stands where it does without the key, 0.7412 m, to within 0.01 mm; a
|
|
776
|
+
> jump reaches 2.348 m (2.347 on alternating frames) where without the key
|
|
777
|
+
> it reaches 2.347 to 2.354 m depending on the frames. A player with
|
|
778
|
+
> another gravity scale stands 0.69 cm per unit of scale off its keyless
|
|
779
|
+
> height. The walk push is an impulse either way (it leaves the height
|
|
780
|
+
> alone, and the rigid camera does not show its unevenness).
|
|
781
|
+
|
|
782
|
+
The rule for forces: **a force is for the frame it was asked in.** rapier
|
|
783
|
+
keeps a force on a body until it is reset, so nothing outside the physics
|
|
784
|
+
system puts one on a body. `addForce(actor, v)` writes down what was asked
|
|
785
|
+
(asking again in the frame adds; `resetForces(actor)` drops it: the
|
|
786
|
+
Player does that on the frame of a jump, or the frame's lift would add
|
|
787
|
+
11 cm to it); the physics pass puts the forces on their bodies just before
|
|
788
|
+
the frame's fixed steps and takes them off straight after, in a `finally`
|
|
789
|
+
(`stepForced`, systems/physics3d.js), however many steps there were. So
|
|
790
|
+
between frames no body carries a force, and each of these leaves none: the
|
|
791
|
+
Player not running (turned off, physics not ready) asks for nothing; a
|
|
792
|
+
player despawned after asking has no body by the pass; a scene load or a
|
|
793
|
+
dispose (`reset`) drops what was asked, so a door trip from a keyed scene
|
|
794
|
+
to one without the key starts clean; the key going away means the next
|
|
795
|
+
frame asks for nothing; a frame that never reached physics, or a force
|
|
796
|
+
asked for after the pass (from a collision callback), is not used in a
|
|
797
|
+
later frame (requests carry the scene time they were asked at). Code that
|
|
798
|
+
places the player through its body (the hub's fall catch, the multiplayer
|
|
799
|
+
kit's placement and clamps: `setTranslation` and a zero velocity, after
|
|
800
|
+
physics) needs nothing new: there is no force to clear. A behavior that
|
|
801
|
+
wants a steady push asks every frame from `update`, and stops by not
|
|
802
|
+
asking. scripts/test-steady-hover.mjs holds all of it, on a stand-in
|
|
803
|
+
rapier and, where rapier is installed, on rapier itself.
|
|
804
|
+
- `"engine": { "view": { "far": 80, "fogFrom": 60, "fogColor": "#bfe3f2" } }`
|
|
805
|
+
limits the world camera's view distance independently of the camera keys.
|
|
806
|
+
`far` is metres, a number in 20..1000; absent or invalid means the whole
|
|
807
|
+
view key is ignored. Each keyed frame sets the camera's far plane and
|
|
808
|
+
updates its projection only if it changed, and sets linear `THREE.Fog`
|
|
809
|
+
ending at `far`. `fogFrom` is optional (default `0.75 * far`); finite
|
|
810
|
+
numbers clamp to 0..just below far, other values use the default.
|
|
811
|
+
`fogColor` must be `#rrggbb`. Otherwise fog follows the visible kit sky:
|
|
812
|
+
the texture row nearest the horizon, averaged across bearings, or the
|
|
813
|
+
zone's flat colour if its texture cannot be read, blended as the sky fades
|
|
814
|
+
between zones. Without a kit sky it uses a colour Three scene background,
|
|
815
|
+
then a `#rrggbb` scene-data `background`, or neutral `#808080`. Horizon
|
|
816
|
+
sampling happens once per art entry and only under this key. The kit sky
|
|
817
|
+
ignores fog and its vertex shader places it
|
|
818
|
+
on the far plane, so reducing the view distance never cuts it off.
|
|
819
|
+
|
|
820
|
+
Lifecycle is the orbit lens's: remember the original far and exact fog
|
|
821
|
+
object on the first keyed frame; give both back on physics reset/load,
|
|
822
|
+
an editor frame (no runtime), and world disposal. Keyed after keyed takes
|
|
823
|
+
them anew. A world that never meets a valid key has no record, allocates
|
|
824
|
+
nothing, and writes no camera or fog properties (engine3d/viewrange.js;
|
|
825
|
+
scripts/test-view-range.mjs, run by check).
|
|
826
|
+
|
|
827
|
+
Materials: kit physical/standard materials and basic outline hulls keep
|
|
828
|
+
Three's fog chunks. The rim/AO, glow, vertex-finish and near-shadow fade
|
|
829
|
+
hooks preserve them; nearshadows itself only changes the shadow pass.
|
|
830
|
+
The sole custom ShaderMaterial is the sky, intentionally `fog: false`.
|
|
831
|
+
No world surface needs a shader change. Deck-supplied shaders must handle
|
|
832
|
+
fog themselves. Turning fog on selects fog-enabled shader programs once;
|
|
833
|
+
expect a one-off compile stall of tens to hundreds of milliseconds on a
|
|
834
|
+
phone with several variants (an estimate, not a device measurement).
|
|
835
|
+
Changing fog distances or colours does not recompile those programs.
|
|
836
|
+
|
|
837
|
+
- `"engine": { "camera": { "follow": "rigid", "control": "orbit" } }` (the
|
|
838
|
+
same `camera` object) asks the `Player` behavior for a third-person camera
|
|
839
|
+
the player controls: they turn it, tilt it and zoom it, walking is
|
|
840
|
+
relative to it, and the character turns to face the way it walks. Without
|
|
841
|
+
it the Player drives like a tank (A/D and a sideways drag steer, the
|
|
842
|
+
camera stays behind) and the camera's height and distance are the fixed
|
|
843
|
+
`camHeight` and `camDistance`. The terms:
|
|
844
|
+
> With `control` absent, everything is exactly as before: the same code,
|
|
845
|
+
> the same calls on `scene.physics3d` in the same order, the same camera,
|
|
846
|
+
> the same listeners on the canvas, for a scene with no camera key and for
|
|
847
|
+
> one with `"follow": "rigid"` alone. `control` means something only as
|
|
848
|
+
> exactly `"orbit"` beside exactly `"follow": "rigid"`; anything else, or
|
|
849
|
+
> `"orbit"` without the rigid follow, is as absent. The key is read when
|
|
850
|
+
> the scene loads (`scene.cameraControl`, `'orbit'` or `null`), as the
|
|
851
|
+
> other engine keys are. With the key present the Player hovers, jumps and
|
|
852
|
+
> falls as it does under `"follow": "rigid"` (forces), and the camera
|
|
853
|
+
> moves with the player as that one does: the player's ground position is
|
|
854
|
+
> not eased, its height is.
|
|
855
|
+
|
|
856
|
+
Controls under the key:
|
|
857
|
+
- Touch and pen: a drag that starts in the left half of the canvas is the
|
|
858
|
+
movement stick (the same stick, `scene.moveInput`: 56 px to full
|
|
859
|
+
deflection, analogue). A drag that starts in the right half turns and
|
|
860
|
+
tilts the camera, 0.006 rad per CSS pixel: dragging right swings the
|
|
861
|
+
view right, dragging up looks up (the camera goes lower). The left half
|
|
862
|
+
is the stick's: a finger that lands there is never part of a pinch, so
|
|
863
|
+
a thumb put down to walk while the other looks walks, and two thumbs
|
|
864
|
+
put down together walk and look. Two fingers that both landed in the
|
|
865
|
+
right half (the second while the first is still a tap or turning the
|
|
866
|
+
camera) are a pinch: fingers apart bring the camera nearer; while they
|
|
867
|
+
pinch neither turns the camera, a finger in the left half can still
|
|
868
|
+
take the stick, and the finger left when one lifts does nothing more
|
|
869
|
+
until it lifts too. A second drag in the left half while the stick is
|
|
870
|
+
held does nothing. A short tap that did not move still jumps, anywhere;
|
|
871
|
+
a finger that was part of a pinch, or left spent, never jumps.
|
|
872
|
+
- Mouse: a drag with any button turns and tilts, and is never the stick;
|
|
873
|
+
the wheel zooms, a tenth per notch; the context menu is kept off the
|
|
874
|
+
canvas. A left click that did not move jumps.
|
|
875
|
+
On a desktop a drag holds the pointer lock (Roblox's right-drag), so
|
|
876
|
+
the cursor hides and stays put while turning. A right press asks for
|
|
877
|
+
it at once. A left or middle drag asks once it passes the tap slop, or
|
|
878
|
+
when a second button is pressed while it is still a tap, so a click
|
|
879
|
+
never locks. While locked the turn comes from movementX/Y at the same
|
|
880
|
+
`LOOK_RAD_PER_PX`. The lock ends with the drag: the last button up, a
|
|
881
|
+
pointermove with no button down, the window's blur, the page hidden,
|
|
882
|
+
a scene load, or detach. Per the Pointer Lock spec the browser puts
|
|
883
|
+
the cursor back where the lock began. When the browser ends it
|
|
884
|
+
(Escape, or the host page taking focus), the drag ends with no tap. A
|
|
885
|
+
lock of ours that lands after the release, while the next press is
|
|
886
|
+
still a tap, or after a scene load, is let go of as soon as it is
|
|
887
|
+
known. A lock that lands takes the capture of every pointer down on
|
|
888
|
+
the canvas (the spec's implicit release), and no capture can be taken
|
|
889
|
+
while it is on. So every pointer down on the canvas gets its capture
|
|
890
|
+
back when a lock of ours ends, however it ends: under the key or
|
|
891
|
+
without it, mouse or touch, including a touch put down during the lock.
|
|
892
|
+
The captures are given back when our unlock's pointerlockchange
|
|
893
|
+
arrives, not when pointerLockElement clears. Chromium clears it inside
|
|
894
|
+
exitPointerLock and sends the event later. While a request of ours is
|
|
895
|
+
out, the lock is ours, or that event has not arrived, the document
|
|
896
|
+
listens (capture phase) for pointerup and pointercancel. A held
|
|
897
|
+
pointer lifted beyond the canvas in that window has its own event
|
|
898
|
+
handed to its own handler (Scene3DPlayer's pointerup handler, keyless
|
|
899
|
+
or not), so the stick stops and a tap still jumps, as origin/main's
|
|
900
|
+
capture would have done. A pointer whose lift was never seen and that
|
|
901
|
+
cannot be captured again is let go of as a pointercancel would be.
|
|
902
|
+
Scene3DPlayer's keyless handlers report their pointers to the orbit
|
|
903
|
+
input (`orbit?.pointer(event)`) in a runtime that has met the key; one
|
|
904
|
+
that never met it has no orbit input, and nothing changes. A lost pointerup never leaves a mouse pointer held: the next
|
|
905
|
+
press, a move with no button down, or a blur ends it. If
|
|
906
|
+
requestPointerLock is missing (iOS), throws, rejects (Chrome refuses a
|
|
907
|
+
re-lock about 1 s after Escape) or fires pointerlockerror, that drag
|
|
908
|
+
goes on unlocked on the pointer capture taken at the press, as before
|
|
909
|
+
the lock, and the next drag asks again. A drag request that returns a
|
|
910
|
+
promise is followed by the promise alone, and a pointerlockerror is
|
|
911
|
+
never taken for ours then. Old Safari returns no promise, so there an
|
|
912
|
+
error might be another element's, and our request stays watched for
|
|
913
|
+
1 s after one. Touch and pen never lock. Listeners: blur and
|
|
914
|
+
visibilitychange while a mouse button is down under the key;
|
|
915
|
+
pointerlockchange while a drag has asked or our exit's event has not
|
|
916
|
+
come (a scene load between or not, so the captures can be given back);
|
|
917
|
+
the document's pointerup and pointercancel while a request is out, the
|
|
918
|
+
lock is ours, or that event has not come; and pointerlockchange and pointerlockerror while an
|
|
919
|
+
event-only request is out. A scene load with a request out leaves
|
|
920
|
+
only the document's pointerup and pointercancel listeners when the
|
|
921
|
+
request returns a promise, plus the request's own two when it does
|
|
922
|
+
not, until it is answered and any lock it brings has been let go of. Nothing at all without the key (engine3d/orbitinput.js
|
|
923
|
+
`makeMouseLock`;
|
|
924
|
+
scripts/test-camera-orbit.mjs `mouseLock`). castle.xyz's DeckPlayer
|
|
925
|
+
iframe is sandboxed with `allow-pointer-lock`.
|
|
926
|
+
On a desktop (`(hover: hover) and (pointer: fine)`, with pointer lock
|
|
927
|
+
supported), Shift or the small lock button at the bottom right toggles
|
|
928
|
+
shift lock. It starts off and is never saved. A repeated Shift keydown,
|
|
929
|
+
or one in an editable field, does not toggle; Shift still reaches
|
|
930
|
+
`scene.keys`. The button is made lazily beside the canvas under the
|
|
931
|
+
orbit key only, hidden on every scene load until a keyed scene plays
|
|
932
|
+
again, and removed on detach. Clicking it gives focus back to the canvas.
|
|
933
|
+
The mode is on only once the pointer lock lands; a refused or missing
|
|
934
|
+
lock leaves it off. While on, every mouse move turns and tilts from
|
|
935
|
+
movementX/Y at `LOOK_RAD_PER_PX`, with no button needed. A quick left
|
|
936
|
+
click still jumps, presses never start a look-drag or take or release
|
|
937
|
+
the lock, and the wheel still zooms. Shift again, Escape or any browser
|
|
938
|
+
unlock, blur, the page hidden, every scene load, and detach end it,
|
|
939
|
+
with no look or stick left held. Held pointers get their captures back
|
|
940
|
+
through the same lock-end path as a drag. Touch and pen keep their
|
|
941
|
+
controls, and touch-only devices get no button. Nothing is made in a
|
|
942
|
+
runtime that never meets the orbit key. This changes only input: no
|
|
943
|
+
character facing or camera offset (scripts/test-orbit-shift-lock.mjs).
|
|
944
|
+
- Keys: W/S and up/down walk away from and toward the camera, A/D
|
|
945
|
+
strafe, left/right swing the camera, Space jumps.
|
|
946
|
+
|
|
947
|
+
What the Player's properties mean under it: `speed` and `jumpSpeed` are
|
|
948
|
+
what they were. `turnSpeed` is how fast left/right swing the camera,
|
|
949
|
+
rad/s; the character itself turns to face its walk at a fixed 12/s.
|
|
950
|
+
The character faces the way it walks; standing still it keeps its
|
|
951
|
+
facing. It starts facing away from the camera (PI - camAngle, as without
|
|
952
|
+
the key). Without the key its facing is always PI - camAngle, so code
|
|
953
|
+
that turns it sets camAngle; under the key the camera and the character
|
|
954
|
+
turn apart, and turning the character is asked for: `scene.faceRequest =
|
|
955
|
+
<radians>`, taken once by the Player's next update (a value that is not
|
|
956
|
+
a finite number is dropped) and dropped by a scene load. The hub asks
|
|
957
|
+
this way beside each of its camAngle writes (its arrival facing, a jump
|
|
958
|
+
to a door); any other deck that turns the player must do the same, since
|
|
959
|
+
a camAngle written without a request turns only the camera. The
|
|
960
|
+
player's own left/right and drags turn the camera only.
|
|
961
|
+
The camera is Roblox's default (Classic) third-person camera at our
|
|
962
|
+
scale. A Roblox character is 5 studs tall; the kit's avatar
|
|
963
|
+
(player.pxmodel on its 1.4 m capsule, the hub's) is 1.46 m from its soles
|
|
964
|
+
to the top of its cap, so one stud is 0.292 m (`STUD`), and every Roblox
|
|
965
|
+
distance below is that many studs:
|
|
966
|
+
|
|
967
|
+
| | Roblox | here |
|
|
968
|
+
| --- | --- | --- |
|
|
969
|
+
| look point | root part + 1.5 studs | Transform + 0.438 m (`LOOK_HEIGHT`): the Transform is the capsule's middle, which is the torso's middle as Roblox's root part is; 1.5 studs up is the neck |
|
|
970
|
+
| starting distance | 12.5 studs | `engine.camera.distance` in metres, clamped to 1.5..37.376 m; default 3.65 m (`ORBIT_START`), two and a half character heights |
|
|
971
|
+
| starting tilt | behind, slightly down | `engine.camera.pitch` in degrees down from horizontal (positive looks down), clamped to -80..80; default 15 degrees down (`ORBIT_PITCH_START`) |
|
|
972
|
+
| zoom | 0.5 to 128 studs | 1.5 m (`ORBIT_NEAREST`) to 37.4 m (`ORBIT_FARTHEST`, 128 studs): 0.5 studs is first person, and an avatar hides itself from a camera within about 1 m |
|
|
973
|
+
| tilt | 80 degrees either way | 80 degrees above to 80 below the horizontal (`ORBIT_PITCH_MOST`, `ORBIT_PITCH_LEAST`) |
|
|
974
|
+
| field of view | 70 degrees, vertical | 70 degrees, or the scene's `engine.camera.fov` (below) |
|
|
975
|
+
| occlusion (Popper) | snaps in front of what is in the way, eases back out | the same (Collision, below) |
|
|
976
|
+
|
|
977
|
+
`engine.camera.distance` and `engine.camera.pitch` are optional starting
|
|
978
|
+
values only, read only under the orbit key. Each absent, non-finite or
|
|
979
|
+
non-number value keeps its default exactly: 3.65 m or 15 degrees down.
|
|
980
|
+
They do not limit the player's zoom or tilt: the full limits above still
|
|
981
|
+
apply. `camDistance` and `camHeight` do not move the orbit camera. A
|
|
982
|
+
change to either of them or either starting key (a deck edit or a scene
|
|
983
|
+
with different values) reapplies both starting values; unchanged values
|
|
984
|
+
keep what the player chose throughout play. It looks at the player
|
|
985
|
+
0.438 m above its Transform (the fixed cameras look 0.5 m above). Below
|
|
986
|
+
the horizontal the camera is lower than the point it looks at, looking
|
|
987
|
+
up, and the ground holds it above itself as a wall holds it in front
|
|
988
|
+
(Collision); a scene with `"ground": { "none": true }` has no drawn
|
|
989
|
+
ground to go under, and its floors are fixed solids that hold it alike.
|
|
990
|
+
|
|
991
|
+
Moment shots. Deck client code can set the player's runtime scene
|
|
992
|
+
(the `scene` passed to `Player`) to
|
|
993
|
+
`scene.orbitShot = { look: { x, y, z }, distance, pitch, yaw }`.
|
|
994
|
+
Distance is metres, greater than zero; pitch and yaw are degrees in the
|
|
995
|
+
orbit's sense (positive pitch puts the camera above the look point,
|
|
996
|
+
looking down). Pitches past 89 degrees in either direction are drawn at
|
|
997
|
+
89 degrees in that direction; the blend also stays within those limits
|
|
998
|
+
to retain the view's azimuth. Its position is `look + distance * direction`,
|
|
999
|
+
where
|
|
1000
|
+
`direction = { x: -cos(pitch)*sin(yaw), y: sin(pitch), z: cos(pitch)*cos(yaw) }`
|
|
1001
|
+
with the angles converted to radians. Position and look point ease from
|
|
1002
|
+
the drawn view at 10/s (`TAKEOVER_RATE`), then hold until changed or
|
|
1003
|
+
cleared. The position eases in yaw (shortest arc), pitch and distance
|
|
1004
|
+
around the drawn look point, so opposing shots swing round it. A settled
|
|
1005
|
+
shot holds its exact pose. A changed shot eases from the current view;
|
|
1006
|
+
an equal assignment continues it. After another system moves or turns
|
|
1007
|
+
the camera or a frame without placement, a shot starts from its current
|
|
1008
|
+
direction; an interrupted hand-back drops its look offset and looks at
|
|
1009
|
+
the player.
|
|
1010
|
+
The lens stays the orbit lens. The shot is drawn as given,
|
|
1011
|
+
without collision: the deck author must place it clear of solids.
|
|
1012
|
+
Clearing with `undefined` or `null`, or supplying an invalid shot
|
|
1013
|
+
(missing look, non-finite numbers, distance <= 0), gives back the player's
|
|
1014
|
+
chosen orbit through its usual takeover blend and collision handling;
|
|
1015
|
+
the look point's offset from the player decays at 10/s, without a rotation
|
|
1016
|
+
snap or trailing a walking player. Below 0.1 mm it returns to the exact
|
|
1017
|
+
player look; a teleport clears the offset at once.
|
|
1018
|
+
Look input is consumed and dropped during a shot; walking is
|
|
1019
|
+
untouched. The player's camAngle, zoom and tilt are kept. Shot state
|
|
1020
|
+
lives on actor.runtime, per player; without the orbit key it is never
|
|
1021
|
+
read, and a scene that never sets it keeps its camera and movement.
|
|
1022
|
+
Checked by scripts/test-orbit-shot.mjs, also run by test-camera-orbit.mjs.
|
|
1023
|
+
|
|
1024
|
+
The lens. The world camera is 50 degrees tall (`makeWorld3D`), and no
|
|
1025
|
+
scene key changes it without the orbit key. Under the key it is
|
|
1026
|
+
`engine.camera.fov` degrees (the same `camera` object: a number from 10
|
|
1027
|
+
to 120; anything else, or none, is 70, Roblox's), read from the scene the
|
|
1028
|
+
runtime loaded, set on the world camera with `updateProjectionMatrix` by
|
|
1029
|
+
`renderWorld` on each keyed frame (engine3d/orbitlens.js). The lens the
|
|
1030
|
+
camera had when the key first met it is kept (`world.orbitLens`) and
|
|
1031
|
+
given back exactly, projection and all, when the keyed scene goes, before
|
|
1032
|
+
any code of what follows runs: at every scene load (the physics system's
|
|
1033
|
+
`reset`, which `load` runs before the new scene's data is in), on an
|
|
1034
|
+
editor's frame and on `disposeWorld`. So a keyless scene after a keyed
|
|
1035
|
+
one (a door to a keyless deck in the same world) starts from the lens the
|
|
1036
|
+
camera had, and whatever field of view its own code sets stands, 70
|
|
1037
|
+
included: no keyless frame looks at the camera. A keyed scene after a
|
|
1038
|
+
keyed one takes the lens again on its first frame. A world that never
|
|
1039
|
+
plays the key never touches the camera. The editors have their own worlds
|
|
1040
|
+
and cameras. (Instanced copies are culled before `renderWorld`, with the
|
|
1041
|
+
lens of the frame before: on a keyed scene's first frame they are culled
|
|
1042
|
+
with 50 degrees.)
|
|
1043
|
+
|
|
1044
|
+
Limits: the tilt stays between 80 degrees below and 80 above the
|
|
1045
|
+
horizontal and the distance between 1.5 and 37.376 m. What is asked is
|
|
1046
|
+
eased in at 20/s.
|
|
1047
|
+
|
|
1048
|
+
Collision (Roblox's Popper, with a ball): each frame a ball of the
|
|
1049
|
+
margin's radius (below) is swept from the point the camera is placed
|
|
1050
|
+
from (the player, with its height eased as the camera eases it, 0.438 m
|
|
1051
|
+
up) toward where the camera wants to be, as far as its distance, against
|
|
1052
|
+
fixed bodies' solid colliders only (`scene.physics3d.castBallFixed(origin,
|
|
1053
|
+
dir, maxToi, radius)`, rapier's `castShape` with a `Ball` and the filter
|
|
1054
|
+
of `castRayFixed(origin, dir, maxToi)`: sensors and dynamic and kinematic
|
|
1055
|
+
bodies are passed through, so other players and thrown things do not move
|
|
1056
|
+
the camera). Where it first touches something (its time of impact) is a
|
|
1057
|
+
limit on how far out along that line the camera may be. A ball that far
|
|
1058
|
+
out is the margin off whatever stopped it and off everything it passed,
|
|
1059
|
+
square to the surface, however the line meets it: a wall at a grazing
|
|
1060
|
+
angle, a box's edge or corner, the ground seen along at a low angle, a
|
|
1061
|
+
second wall in a corner. The margin is 0.25 m, or, for a wider lens, the
|
|
1062
|
+
distance from the camera to the near plane's corners, near * sqrt(1 +
|
|
1063
|
+
tan^2(fov/2) + (aspect * tan(fov/2))^2), plus 0.05 m, whichever is more
|
|
1064
|
+
(`lensMargin`, from the scene's lens and the camera's near and aspect):
|
|
1065
|
+
0.25 m at 70 degrees on 20:9 (corners 0.198 m off), 0.484 m at 120
|
|
1066
|
+
degrees on 20:9, 0.265 m at 120 on 9:20. So the whole near plane stays in
|
|
1067
|
+
front of every surface at every lens from 10 to 120 degrees, any aspect,
|
|
1068
|
+
every tilt and zoom. A nearer limit is taken at once; a farther one, or
|
|
1069
|
+
none, is eased out to at 6/s, never past what this frame's ball touched,
|
|
1070
|
+
and let go once the camera is back at its distance. The ease is measured
|
|
1071
|
+
from the look point, from how far from it the camera was drawn last
|
|
1072
|
+
frame, and turned into a distance along this frame's line from this
|
|
1073
|
+
frame's start (`alongRay`): the start moves as the player nears or leaves
|
|
1074
|
+
a wall, so last frame's limit along its own line is not where the camera
|
|
1075
|
+
was (review 7: a wall 0.5 m off removed let the camera out 1.161 m in a
|
|
1076
|
+
frame where easing at 6/s allows 1.139). It eases whatever drew the
|
|
1077
|
+
camera short of its distance, a start moved off a wall as well as a ball
|
|
1078
|
+
that held it (review 8: a box beside the look point removed let the camera
|
|
1079
|
+
out 0.062 m where 0.006 m is allowed); only the player's zoom moves it at
|
|
1080
|
+
the zoom's own pace (a zoom in past where it is held takes it in at once).
|
|
1081
|
+
The ball is swept only as far as the camera will be drawn this frame, so
|
|
1082
|
+
the place drawn is the place whose end the sweep checks. The camera is drawn at the nearer of its eased distance and the
|
|
1083
|
+
limit, so zooming in while held in front of a wall brings it no nearer
|
|
1084
|
+
until the distance asked is nearer than the wall, the view is never
|
|
1085
|
+
inside a wall and never pops outward, and an easing camera never passes
|
|
1086
|
+
something the ball touches (review 5: the axis-ray push and line pull-in
|
|
1087
|
+
of reviews 3 and 4 left a camera 8 mm off a box at a grazing angle, and a
|
|
1088
|
+
pull-in made for one frame alone let the eased limit run on, so the
|
|
1089
|
+
camera jumped 3.985 m out in a frame when it stopped).
|
|
1090
|
+
|
|
1091
|
+
Rapier's answer for a swept ball is off by an amount that changes from
|
|
1092
|
+
place to place (short by centimetres against the ground and tens of
|
|
1093
|
+
centimetres along a wall met at a grazing angle; past the surface by up
|
|
1094
|
+
to 2 cm, or missing it, when the ball starts within a few centimetres of
|
|
1095
|
+
one; in a corner it can name the second solid instead of the first), so
|
|
1096
|
+
`castBallFixed` puts the ball where it touches the plane that touches the
|
|
1097
|
+
solid where it was met (exact on a face; a convex solid is all behind it
|
|
1098
|
+
at an edge or a corner) and checks that place with an overlap query, the
|
|
1099
|
+
ball 0.05 mm smaller; another solid in the way there is swept against
|
|
1100
|
+
alone and the ball put where it touches that one, three times at most.
|
|
1101
|
+
Rapier can also miss a solid outright (review 8: a box the ball passes
|
|
1102
|
+
through, at one radius and not a millimetre more), so its answer is only
|
|
1103
|
+
where to look: with no hit the ball's end (the place the camera will be
|
|
1104
|
+
drawn) is checked all the same, a ray along the line keeps the line of
|
|
1105
|
+
sight, and a place still not clear is found by halving between the start
|
|
1106
|
+
(clear) and it with overlap queries, to 1 mm in 16 halvings at most.
|
|
1107
|
+
`castBallFixed` is three rapier queries as a rule (sweep, ray, overlap)
|
|
1108
|
+
and 25 at most. Rapier does not answer a ball that
|
|
1109
|
+
starts touching something either, so the ball starts clear: every fixed
|
|
1110
|
+
surface within the margin and 0.05 m of the start
|
|
1111
|
+
(`scene.physics3d.nearFixed(point, within)`, each solid's nearest point and
|
|
1112
|
+
normal) gives a plane touching its solid there (a convex solid all behind
|
|
1113
|
+
it), and the start is the look point moved the least way that puts it
|
|
1114
|
+
that far in front of every plane found so far, all together (the nearest
|
|
1115
|
+
point of the half-spaces' intersection), then looked around again, eight
|
|
1116
|
+
times at most. Together, a corner's walls do not undo each other's moves
|
|
1117
|
+
(review 6: one wall at a time, a 60 degree corner left the camera 8.66 mm
|
|
1118
|
+
off a wall with the near plane through it). The move grows from nothing as
|
|
1119
|
+
the player comes nearer, so the camera does not jump. Where no place near
|
|
1120
|
+
the look point is that far off every plane (a gap narrower than twice the
|
|
1121
|
+
margin) the place that falls least short is taken and the ball made that
|
|
1122
|
+
much smaller (in a gap 0.7 m wide, its middle, the camera 0.3 m off both
|
|
1123
|
+
walls), no smaller than 0.02 m. There the lens cuts into the walls: the
|
|
1124
|
+
camera point stays out of them, but no place keeps the near plane out
|
|
1125
|
+
(at 120 degrees on 20:9 its corners are 0.434 m from the camera), so the
|
|
1126
|
+
view shows the inside of a wall at its edges. This is accepted, as
|
|
1127
|
+
Roblox's camera clips there too; the near plane is not shrunk. Only a look point inside a solid falls back to the ray the
|
|
1128
|
+
camera had before the ball (`onRay`, with `castRayFixedNormal`, which is
|
|
1129
|
+
`castRayFixed` with the surface's normal): a margin short of the hit, no
|
|
1130
|
+
nearer the look point than 0.6 m, never past a real surface (then 0.01 m
|
|
1131
|
+
short of it). `castRayFixed` itself is what it was: `{ distance, actorId }`.
|
|
1132
|
+
While a takeover blend lasts (below) the point actually drawn, its place
|
|
1133
|
+
plus what is left of the blend, is swept toward the same way: pulled in
|
|
1134
|
+
along its own line to where the ball stopped, and the pull is kept in the
|
|
1135
|
+
blend, so the next frame eases on from there. Once a wall has held a
|
|
1136
|
+
blend in, it is let out at the collision pace for the rest of that blend:
|
|
1137
|
+
no farther from the look point than easing at 6/s from where it was drawn
|
|
1138
|
+
toward where the camera rests this frame (review 9: a wall removed under a
|
|
1139
|
+
held blend let its 10/s carry the camera 0.246 m out in a frame where
|
|
1140
|
+
0.179 m is allowed), and let go within 0.1 mm of it. Where it rests, not
|
|
1141
|
+
its distance: a start moved off a wall can put the camera farther out
|
|
1142
|
+
than its distance, and easing toward the distance held such a blend open
|
|
1143
|
+
for good (review 10: 0.093 m short after 20 s, a sweep more every frame).
|
|
1144
|
+
A blend no wall has held keeps its own pace. Tests
|
|
1145
|
+
(scripts/test-camera-orbit.mjs): `grounded` on a stand-in plane and on
|
|
1146
|
+
rapier's own ground, `wideLens` on a stand-in wall, `grazing` on rapier
|
|
1147
|
+
(the review 3 case at 120 degrees, 20:9, level, yaw -3, farthest zoom; a
|
|
1148
|
+
sweep near grazing on 20:9 and 9:20 at 70 and 120 degrees, a player 0.8 m
|
|
1149
|
+
from the wall and against it; a corner of two walls over the ground;
|
|
1150
|
+
review 4's post, 240 settled frames whose line to the player meets
|
|
1151
|
+
nothing and that do not move), `popClear` and `popSteady` (review 5 on
|
|
1152
|
+
rapier: two boxes beside the line and a blocker removed; every frame
|
|
1153
|
+
after, the camera is the margin off each box and the ground, measured on
|
|
1154
|
+
the boxes, and moves out no faster than easing at 6/s allows), `corners`
|
|
1155
|
+
(review 6 on rapier: the player pressed into corners of 30 to 150
|
|
1156
|
+
degrees, two square walls under a ceiling and a 60 degree corner under
|
|
1157
|
+
one, the camera turned every way: every frame the margin off every solid,
|
|
1158
|
+
less 0.1 mm, and no near-plane corner inside one), `narrowGapStable`
|
|
1159
|
+
(walls 0.7 m apart: only that the camera point is never inside a wall,
|
|
1160
|
+
nothing is NaN and a settled camera stays put; the lens does cut the
|
|
1161
|
+
walls there) and `releaseEase` (review 7: walls 0.36 to 0.6 m off at four
|
|
1162
|
+
angles, removed; no frame moves the camera out from the look point
|
|
1163
|
+
faster than easing at 6/s allows).
|
|
1164
|
+
Also `releaseBeside` (review 8: a box beside the look point removed, eased
|
|
1165
|
+
out at 6/s), `randomBoxes` (review 8: 120 seeded cases of one or two
|
|
1166
|
+
boxes turned any way, mostly in the camera's way, 70 and 120 degrees on
|
|
1167
|
+
16:9 and 20:9; every frame the camera the margin off each box less 1 mm
|
|
1168
|
+
and no point of a 21 x 21 near-plane grid inside one; the review's case
|
|
1169
|
+
is the first), `ballMisses` (rapier's sweep made to miss: the ball
|
|
1170
|
+
still stops its radius off the wall) and `blendRelease` (review 9: blends
|
|
1171
|
+
handed back from three places, a wall at two distances removed or kept,
|
|
1172
|
+
no wall, and (review 10) a wall and a corner 0.4 m off at 70 and 120
|
|
1173
|
+
degrees: eased out at 6/s once released, every blend ends and is no
|
|
1174
|
+
longer held, one sweep a frame after, the camera stays, and with no wall
|
|
1175
|
+
it is about there in 0.3 s). Queries a frame: one `nearFixed` in
|
|
1176
|
+
the open, two by a wall or in a corner (eight at most), and one sweep, one
|
|
1177
|
+
more while a takeover blend lasts; a sweep is three rapier queries as a
|
|
1178
|
+
rule and 25 at most. As a rule 4 in the open and 5 by a wall; the worst
|
|
1179
|
+
case is 8 + 2 * 25 = 58 (a blend, a slanted corner, and rapier missing
|
|
1180
|
+
solids in both sweeps); none on a
|
|
1181
|
+
frame physics has no world. Popped in near the player the camera
|
|
1182
|
+
is within an avatar's own hiding distance, as Roblox's goes through its
|
|
1183
|
+
character when pressed close, and the model is hidden (below).
|
|
1184
|
+
A frame whose final camera (after anything else placed it) is within
|
|
1185
|
+
1 m of the player's own model (in world space, the segment from its
|
|
1186
|
+
node's origin 0.8 m up, to the top of its head; once hidden, until 1.2 m) is drawn without that model, so
|
|
1187
|
+
the view is not the inside of the avatar (engine3d/ownmodel.js). The
|
|
1188
|
+
Player names its actor for the frame's draw (`scene.orbitOwnModel`, set
|
|
1189
|
+
by each placement, taken by the draw, dropped by `reset`), and the play
|
|
1190
|
+
loop sets that node's `visible` to false for the one render (only a node
|
|
1191
|
+
that was shown), inside try/finally, and back to true after it if it is
|
|
1192
|
+
still false; nothing else is put on the node, so a deck's own hide, a
|
|
1193
|
+
rebuilt node and a Player turned off or removed need nothing. Positions
|
|
1194
|
+
are measured as WebGLRenderer.render will draw them (`world.scene`
|
|
1195
|
+
updated when its `matrixWorldAutoUpdate` is on, cached when off; a
|
|
1196
|
+
parentless camera by its own flag), writing no matrix; a node not under
|
|
1197
|
+
`world.scene` is not hidden. A `false` a deck writes from inside the
|
|
1198
|
+
render of a hidden frame is shown again after it. Accepted: anything
|
|
1199
|
+
that copies the node from inside that render (clone, copy, toJSON, its
|
|
1200
|
+
own or a parent's) copies `visible: false`, as for any node a deck hides
|
|
1201
|
+
for a frame; three.js treats `visible` as plain state. Also accepted: the
|
|
1202
|
+
decision is made before the render, so a camera a deck moves from
|
|
1203
|
+
`scene.onBeforeRender` (which three.js calls after the matrices, before
|
|
1204
|
+
the render list) is judged where it was before that callback; under the
|
|
1205
|
+
key the Player places the camera, and catching that callback would mean
|
|
1206
|
+
putting something on the scene. Only the
|
|
1207
|
+
local player is hidden; nothing is sent. While hidden it casts no
|
|
1208
|
+
shadow; a model drawn as shared instances (`instanceModels`) is not
|
|
1209
|
+
hidden. Without the key the field is never set and the loop calls
|
|
1210
|
+
`renderWorld` as before.
|
|
1211
|
+
|
|
1212
|
+
`scene.three.ownModelWith` is a `Set<Object3D>` for extras that should hide
|
|
1213
|
+
with the own model, such as multiplayer-3d's own name-tag sprite. Add an
|
|
1214
|
+
object while it belongs to the player and delete it when disposed or
|
|
1215
|
+
replaced. The set is read only in a render that actually hides the model;
|
|
1216
|
+
keyless frames never read it. Only shown, writable objects under
|
|
1217
|
+
`world.scene` are hidden, with the same try/finally visibility contract as
|
|
1218
|
+
the model; anything other than a Set there is ignored. Detaching or unregistering one during the render still restores
|
|
1219
|
+
it if its visibility is still false; an already hidden object is left alone.
|
|
1220
|
+
|
|
1221
|
+
There is no return-behind (no swinging the camera back behind a walking
|
|
1222
|
+
player when it is left alone): walking forward already keeps the camera
|
|
1223
|
+
behind, and chasing a strafe would turn a straight walk into a circle.
|
|
1224
|
+
|
|
1225
|
+
Where the state is. The yaw is `scene.persistent.camAngle`, with the
|
|
1226
|
+
meaning it always had (the camera sits at player + (-d sin, h, d cos) of
|
|
1227
|
+
it), so code that reads or sets it (the hub's arrival facing) works as
|
|
1228
|
+
before; a yaw set a full turn away is reached the short way round. The
|
|
1229
|
+
tilt and distance the player chose are client-only: they are on the
|
|
1230
|
+
runtime (`scene.cameraOrbit`), which a scene load does not replace, so
|
|
1231
|
+
they carry from scene to scene (a Player with other
|
|
1232
|
+
`camDistance`/`camHeight` starts from its own), and are never on
|
|
1233
|
+
`scene.persistent`, which the multiplayer kit sends. What the camera is
|
|
1234
|
+
doing between frames is on the actor's `runtime`, which a scene load
|
|
1235
|
+
rebuilds. `scene.lookInput` (engine3d/orbitinput.js) holds what the
|
|
1236
|
+
pointers asked for until the Player takes it, once a frame; it is made
|
|
1237
|
+
the first time a pointer goes down under the key or a Player runs under
|
|
1238
|
+
it (`scene.orbitInput()`), so a runtime that never meets the key has
|
|
1239
|
+
none.
|
|
1240
|
+
|
|
1241
|
+
When something else has the camera. A teleport (more than 3 m in a
|
|
1242
|
+
frame) snaps it, and so does a camera more than 20 m from its place. The
|
|
1243
|
+
camera is the player's to steer on a frame only when the Player also
|
|
1244
|
+
placed it on the frame before (so a Player turned off, even for a frame
|
|
1245
|
+
and even by a collision callback after its update, does not come back to
|
|
1246
|
+
a queued drag), the camera is where the Player left it, and the look
|
|
1247
|
+
input is not locked. `scene.lookInput.lock()` makes the next take empty
|
|
1248
|
+
and drops what was asked; the hub calls it each frame of a door trip
|
|
1249
|
+
under the key (beside its `lockInput`), so a drag made during a
|
|
1250
|
+
trip neither moves the trip's camera nor turns the view when it ends. On
|
|
1251
|
+
any frame the camera is not where the Player left it (a hub trip writes
|
|
1252
|
+
it every frame; the first frame of a scene; a Player turned off and on)
|
|
1253
|
+
the Player starts again from the chosen tilt and distance and eases on
|
|
1254
|
+
from where the camera was put (a twentieth of the way left after 0.3 s).
|
|
1255
|
+
|
|
1256
|
+
Loads. A scene without the key, loaded after one with it, runs the code
|
|
1257
|
+
it always ran from its first frame: the latch is per load, and the
|
|
1258
|
+
Player's and the input's branches each read it once. On every scene
|
|
1259
|
+
load and on dispose the physics system's `reset` resets the orbit input
|
|
1260
|
+
(`scene.lookInput.reset()`, only when it is the one orbitinput.js made:
|
|
1261
|
+
`isOrbitLook`): every pointer it holds is let go of (the stick released
|
|
1262
|
+
if one of them held it, no tap), what was asked of the camera is
|
|
1263
|
+
dropped, and the wheel and context-menu listeners are taken off; a keyed
|
|
1264
|
+
scene's Player puts the listeners back on its first frame. A
|
|
1265
|
+
`faceRequest` not yet taken is dropped on every load, whether or not the
|
|
1266
|
+
orbit input was ever made. A tap already taken as a jump and not yet
|
|
1267
|
+
used carries across a load with or without the key, as it always has. A
|
|
1268
|
+
runtime that never met the key has no orbit input.
|
|
1269
|
+
So a finger held across any load into or out of a keyed scene, or
|
|
1270
|
+
between two keyed scenes, does nothing more until it lifts: the old
|
|
1271
|
+
handlers do not know it either. A finger the old handlers hold across a
|
|
1272
|
+
load into a keyed scene keeps their stick until it lifts or a pointer
|
|
1273
|
+
goes down under the key, which lets go of everything they hold; only
|
|
1274
|
+
one of the two ever writes the stick. scripts/test-camera-orbit.mjs
|
|
1275
|
+
holds all of it, with the Player as it was before the key
|
|
1276
|
+
(scripts/Player.before-orbit.mjs) and Scene3DPlayer's `attachInput` as
|
|
1277
|
+
it was (scripts/Scene3DPlayer.before-orbit.jsx) as the references for
|
|
1278
|
+
the scenes without it, and the loads, the lock and a Player turned off
|
|
1279
|
+
and on run through physics-2d's SceneRuntime and Scene3DPlayer's own
|
|
1280
|
+
`attachInput`.
|
|
1281
|
+
- `"engine": { "look": { "bake": "deferred" } }` at the scene file's top
|
|
1282
|
+
level (the same `engine` object) asks the engine to draw the scene's models
|
|
1283
|
+
before their look is baked. Building a model bakes two things into it
|
|
1284
|
+
(`engine3d/look.js`): its soft shading, by casting rays from every vertex
|
|
1285
|
+
through a grid of the model's surfaces, and the attributes its outline is
|
|
1286
|
+
pushed out by. That is most of what a model costs to build, and all of it
|
|
1287
|
+
happens before the first frame: on a slow phone, several seconds of a
|
|
1288
|
+
town's load. With the key a model is drawn at once without them, and they
|
|
1289
|
+
are baked a little after each frame, nearest the camera first, about 6 ms a
|
|
1290
|
+
frame. What a player sees: the scene appears sooner, flat-shaded where
|
|
1291
|
+
parts meet and with no outlines, and over the first seconds the shading
|
|
1292
|
+
and the outlines come in, model by model. The terms:
|
|
1293
|
+
> With the key absent, a model is built exactly as before: the same code,
|
|
1294
|
+
> baked before `syncActors` returns. With the key present, a model is built
|
|
1295
|
+
> in the same shape, with the same meshes, materials and shader programs
|
|
1296
|
+
> (nothing is recompiled when the baking lands), its occlusion all 1
|
|
1297
|
+
> (nothing occludes it) and its outline hulls there and not drawn (their
|
|
1298
|
+
> material's `visible` is off); once its baking has run, every attribute of
|
|
1299
|
+
> every geometry holds what baking at once would have put there, and the
|
|
1300
|
+
> hulls are drawn.
|
|
1301
|
+
|
|
1302
|
+
Any other value of `bake`, or none, is the key absent. It is read when the
|
|
1303
|
+
scene loads (`runtime.bakesLookLater`), so it follows a scene switch, and
|
|
1304
|
+
it applies to models `syncActors` builds while that scene plays, in the
|
|
1305
|
+
play panel, a published deck and the scene editor alike; the model editor
|
|
1306
|
+
and thumbnails build their own and always bake at once. A model already
|
|
1307
|
+
baked (built for a scene without the key, or one whose baking has run) is
|
|
1308
|
+
never unbaked. The other way round, a model built under the key and still
|
|
1309
|
+
waiting when a scene without it places the same model in the same world is
|
|
1310
|
+
the same shared build: it is drawn unbaked there too until its baking has
|
|
1311
|
+
run, which goes on whichever scene plays. Whether a pass bakes later is
|
|
1312
|
+
written on the world when `syncActors` starts (`world.bakesLookLater`), so
|
|
1313
|
+
a `syncActors` for another runtime entered from inside a pass leaves its
|
|
1314
|
+
own answer there for the rest of the outer one: models the outer pass
|
|
1315
|
+
builds after it are baked as the inner runtime's scene asked. They end
|
|
1316
|
+
the same either way.
|
|
1317
|
+
|
|
1318
|
+
It goes with `"dropEmptyParts": true`: that key takes the empty groups out
|
|
1319
|
+
of a shared build after its look was applied and its baking queued, and the
|
|
1320
|
+
baking was written down as geometries and matrices, so with both keys a
|
|
1321
|
+
scene ends as it does with `dropEmptyParts` alone.
|
|
1322
|
+
|
|
1323
|
+
How it goes (`engine3d/lookbake.js` has the queue, the end of `look.js`
|
|
1324
|
+
what is queued): one task per model built, cut into steps (the grid, each
|
|
1325
|
+
surface marked into it, the rays of 128 vertices, a stretch of 384
|
|
1326
|
+
vertices or triangle corners of a geometry's outline attributes, part by
|
|
1327
|
+
part for merged parts). After each frame is drawn
|
|
1328
|
+
(`renderWorld`), steps are started until 6 ms have gone; a step is never
|
|
1329
|
+
interrupted, so a long one overruns and nothing starts after it that frame.
|
|
1330
|
+
The frame the queue is first seen bakes nothing, so the first frame is on
|
|
1331
|
+
screen first. Tasks are put nearest first whenever the queue has grown, by
|
|
1332
|
+
the distance from the camera to the nearest actor placing the model as
|
|
1333
|
+
things stood then; they are not re-sorted as the player walks. A task
|
|
1334
|
+
bakes from what was written down when the model was built (each surface's
|
|
1335
|
+
geometry and where it stood), so a model moved or animated since bakes the
|
|
1336
|
+
same. Models sharing a parsed model file share one bake, as before, and a
|
|
1337
|
+
geometry is baked once however many copies draw it.
|
|
1338
|
+
|
|
1339
|
+
`scene.three.lookBake` is null in a world that never built a model under
|
|
1340
|
+
the key; otherwise it is the queue: `shown` (true once a frame has been
|
|
1341
|
+
drawn with nothing left to bake, false again from the moment a model is
|
|
1342
|
+
queued), `pending` (models still to bake), `ms` (time spent baking),
|
|
1343
|
+
`baked` and `dropped` (tasks that ran to the end and left the whole of the
|
|
1344
|
+
baking in every geometry not disposed, and tasks that did not: the model
|
|
1345
|
+
went first, or a geometry was left that could not be written to), and
|
|
1346
|
+
`budgetMs`, which a deck may set. **A harness, a screenshot or
|
|
1347
|
+
a cover waits for `lookBake === null || lookBake.shown`, not for `pending`
|
|
1348
|
+
to reach 0**: the baking is done after the frame is drawn, so the frame
|
|
1349
|
+
that brings `pending` to 0 was drawn without the last of it, and it is the
|
|
1350
|
+
next one that is the complete picture. A model released, rebuilt (its
|
|
1351
|
+
file, its art or the look switch changed) or disposed with its world before
|
|
1352
|
+
its task ran is dropped: the task listens for its geometries' `dispose` and
|
|
1353
|
+
never writes to one that has been disposed.
|
|
1354
|
+
|
|
1355
|
+
A geometry replaced while it waits: a copy made with `geometry.clone()`
|
|
1356
|
+
waits with the geometry it was copied from, and is given the same occlusion
|
|
1357
|
+
and outline attributes when the task runs (in arrays of its own, as a copy
|
|
1358
|
+
of a baked geometry has), so a mesh and its outline hull given the copy,
|
|
1359
|
+
the first geometry disposed, end as they would in a scene without the key.
|
|
1360
|
+
That holds whenever the copy is made (before the task begins or part way
|
|
1361
|
+
through it) and whatever it is made from (the geometry, a copy, or either
|
|
1362
|
+
one disposed and never written): a task counted in `baked` left every
|
|
1363
|
+
geometry of its model that is not disposed, copies included, fully baked.
|
|
1364
|
+
The engine does this itself for a part that glows. While it waits a
|
|
1365
|
+
geometry has a `clone` of its own for this; it goes when the task ends, and
|
|
1366
|
+
a `clone` kept hold of and called afterwards is the ordinary one.
|
|
1367
|
+
Anything else put in a waiting geometry's place (a geometry built
|
|
1368
|
+
separately, `copy()` into another one, or a copy whose vertices were then
|
|
1369
|
+
replaced by a different number) is not written to: it keeps the occlusion
|
|
1370
|
+
it came with, and an outline hull drawn from it has no outline attributes.
|
|
1371
|
+
A task that ends with such a copy not disposed counts in `dropped`.
|
|
1372
|
+
When the waiting geometry and every copy of it are gone before the task
|
|
1373
|
+
runs, the hull's material is left not `visible`, so that hull has no
|
|
1374
|
+
outline rather than a wrong one; a deck that swaps in its own geometry
|
|
1375
|
+
under the key bakes it itself (`addOutlineAttributes`, engine3d/look.js)
|
|
1376
|
+
and shows the hull. And a waiting geometry disposed while a mesh still
|
|
1377
|
+
draws it is never baked, where without the key it would already have been.
|
|
1378
|
+
|
|
1379
|
+
`scripts/test-look-bake.mjs` holds all of it, and holds what a build
|
|
1380
|
+
without the key gives to a number (`BAKED_AT_ONCE`, a digest from
|
|
1381
|
+
`scripts/look-baseline.mjs` of every kit model built at once): change it
|
|
1382
|
+
only in a commit that means to change what the look bakes into a model.
|
|
1383
|
+
|
|
1384
|
+
Do not set it if deck code reads `lookOcclusion`, `lookOutlineNormal` or
|
|
1385
|
+
`lookOutlineReach`, or sets `visible` on an outline hull's material, in the
|
|
1386
|
+
first seconds of a scene; and a screenshot or cover taken before
|
|
1387
|
+
`lookBake.shown` is true shows the unbaked picture. Opt in when a
|
|
1388
|
+
scene is many models and the load on a slow phone matters more than the
|
|
1389
|
+
first seconds' polish; a small scene gains nothing.
|
|
1390
|
+
- `"engine": { "sky": { ... } }` at the scene file's top level (the same
|
|
1391
|
+
`engine` object) asks the engine to draw a sky behind everything: the sky of
|
|
1392
|
+
the zone the player stands in, turning into the next zone's when they walk
|
|
1393
|
+
into it. Without it the engine clears to black, and a camera that looks
|
|
1394
|
+
above the horizon looks into black.
|
|
1395
|
+
|
|
1396
|
+
```jsonc
|
|
1397
|
+
"sky": {
|
|
1398
|
+
"fade": 1.5, // optional: seconds one zone's sky takes to turn into another's (above 0, at most 10)
|
|
1399
|
+
"edge": 0.75, // optional: metres past a zone's box a player is still in it (0 to 10)
|
|
1400
|
+
"below": 8, // optional: degrees under the horizon an image's last row is (0 to 45)
|
|
1401
|
+
"zones": [ // 1 to 16; exactly one has no box
|
|
1402
|
+
{ "id": "square", "color": "#bfe3f2", "art": "drawings/sky-square.webp" },
|
|
1403
|
+
{ "id": "hollow", "color": "#3d3a5c", "art": "drawings/sky-hollow.webp", "box": [-95, -17, -17, 17] }
|
|
1404
|
+
]
|
|
1405
|
+
}
|
|
1406
|
+
```
|
|
1407
|
+
|
|
1408
|
+
The terms:
|
|
1409
|
+
> With the key absent, a scene is drawn exactly as before: the same scene
|
|
1410
|
+
> graph, the same render calls, the same clear to black; nothing of the
|
|
1411
|
+
> sky's is made. With the key present, every pixel no opaque thing covers is
|
|
1412
|
+
> the sky of one zone, or of two while one turns into the other, and
|
|
1413
|
+
> everything else is drawn as it would be without the key: the sky is not
|
|
1414
|
+
> lit, casts and takes no shadow, is not an actor, and is in the scene graph
|
|
1415
|
+
> only while a frame of its scene is being drawn.
|
|
1416
|
+
|
|
1417
|
+
A zone is `id`, `color` (`#rrggbb`), optionally `art` and optionally `box`
|
|
1418
|
+
(`[x0, z0, x1, z1]`, metres). The zone with no box is the sky of a point in
|
|
1419
|
+
no box; a point in two boxes is in the one listed first.
|
|
1420
|
+
|
|
1421
|
+
**The shape is exact** (`physics-2d` `engine/skyKey.js` reads it at each
|
|
1422
|
+
scene load). A key it does not name, a number out of range, a colour that is
|
|
1423
|
+
not six hex digits, two zones with one id, no zone without a box or more
|
|
1424
|
+
than one: the scene has no sky, the key reads as absent, and the console
|
|
1425
|
+
gets one warning that says what was wrong. So a scene written for a later
|
|
1426
|
+
engine that knows more keys has no sky on this one, rather than half of one.
|
|
1427
|
+
|
|
1428
|
+
**A zone's picture** is a deck image (png, jpg, webp: `art` is its path in
|
|
1429
|
+
the deck). It enters through the bundler like every deck image and is a
|
|
1430
|
+
`data:` URI in a published deck; nothing is fetched. Across, it is the
|
|
1431
|
+
bearing: north (-z) at the left edge, east (+x) a quarter of the way along,
|
|
1432
|
+
its right edge meeting its left. Down, it is the height: straight overhead
|
|
1433
|
+
in the first row, `below` degrees under the horizon in the last, and the
|
|
1434
|
+
last row again below that. So the first row is one point of the sky and
|
|
1435
|
+
should be one colour. It is drawn with linear filtering and no smaller
|
|
1436
|
+
copies, as the whole sky whichever way the camera looks. A texture is made
|
|
1437
|
+
when its zone is first drawn, and at most two are held (the zone drawn and
|
|
1438
|
+
the one it is turning into). Where a zone has no `art`, or its image has not
|
|
1439
|
+
arrived, failed, or is not an image (a `.sprite`), the sky is the zone's
|
|
1440
|
+
`color`.
|
|
1441
|
+
|
|
1442
|
+
**Which zone** is decided each frame from the local Player's Transform (the
|
|
1443
|
+
first actor with a `Player` component), never the camera: a player is in a
|
|
1444
|
+
box from its edge and stays in it until `edge` metres outside, so standing
|
|
1445
|
+
on a line does not flicker. With no Player, the zone with no box.
|
|
1446
|
+
|
|
1447
|
+
**The fade** takes `fade` seconds by the clock (a frame longer than a
|
|
1448
|
+
quarter of a second counts as a quarter). A player who turns back mid-fade
|
|
1449
|
+
sees it run backwards from where it is; one who walks on into a third zone
|
|
1450
|
+
sees the fade under way finish, then the next. Nothing fades on a scene's
|
|
1451
|
+
first frame, or when the player is somewhere else at once (more than 8 m
|
|
1452
|
+
from where the frame before had them: a door, a put): the sky is simply
|
|
1453
|
+
that zone's.
|
|
1454
|
+
|
|
1455
|
+
**`scene.skyZone`** says it, to read: `{ id, blend, from, to }`. `id` is
|
|
1456
|
+
the zone the player is in; the sky drawn is `from`'s turning into `to`'s,
|
|
1457
|
+
`blend` of the way there, 0 to 1 (at rest `from` and `to` are both `id` and
|
|
1458
|
+
`blend` is 0). It is the same object from one scene load to the next, kept
|
|
1459
|
+
current as frames are drawn (it is one frame behind inside an `update`),
|
|
1460
|
+
and it cannot be written. Before a frame is drawn, and after the scene's
|
|
1461
|
+
world is disposed, it names the zone with no box. For a scene without the
|
|
1462
|
+
key it is `null`, and nothing works it out. A system that fades something
|
|
1463
|
+
else with the sky (a zone's sound) reads `from`, `to` and `blend`.
|
|
1464
|
+
|
|
1465
|
+
What it costs: one draw call in the colour pass (none in the shadow pass),
|
|
1466
|
+
under 500 triangles, one texture read for each pixel of sky (two during a
|
|
1467
|
+
fade), and no overdraw: it is drawn after every opaque thing, on the far
|
|
1468
|
+
plane, so only the pixels they left are shaded. A zone test and a few
|
|
1469
|
+
uniforms each frame.
|
|
1470
|
+
|
|
1471
|
+
How it stays out of the scene's way, and how long it lasts
|
|
1472
|
+
(`engine3d/skylife.js` has the rule and all of the code that attaches,
|
|
1473
|
+
detaches or disposes anything):
|
|
1474
|
+
> The dome and its resources are attached, detached and disposed only by
|
|
1475
|
+
> the outermost render of their world, or with no render of that world in
|
|
1476
|
+
> progress. Nothing a callback does (re-enter, throw, load, dispose) can
|
|
1477
|
+
> leave a dome in the scene graph, a disposed resource in a render list,
|
|
1478
|
+
> or a sky record alive past its key.
|
|
1479
|
+
|
|
1480
|
+
Every frame of a world with the key goes one way (`skyFrame`): counted in,
|
|
1481
|
+
prepared, drawn, counted out, and, if it was the outermost, settled. The
|
|
1482
|
+
settling alone enforces this, from what is true at that moment:
|
|
1483
|
+
> After the outermost frame of a world returns or throws, EITHER
|
|
1484
|
+
> `world.sky` is null, OR it is a record whose key is the key the frame's
|
|
1485
|
+
> runtime has NOW for THIS world, with its dome out of the scene graph,
|
|
1486
|
+
> and neither that frame nor any frame drawn from inside it threw.
|
|
1487
|
+
|
|
1488
|
+
The key a runtime has for a world is its `sky`, unless the world is
|
|
1489
|
+
disposed or the runtime draws in another world (its `three` is set and is
|
|
1490
|
+
not this one): then it has none, and no sky is drawn for it there. A frame
|
|
1491
|
+
from inside another, or from inside a disposal, never makes, steps,
|
|
1492
|
+
attaches, detaches or disposes; a dome in the scene graph that is not of
|
|
1493
|
+
its runtime's key is hidden for that draw. Errors are data: a step or a
|
|
1494
|
+
disposal that throws does not stop the frame, which is drawn with no sky;
|
|
1495
|
+
every release that is due still runs; the first error is thrown at the
|
|
1496
|
+
frame's one exit, the frame's own over a kept one.
|
|
1497
|
+
|
|
1498
|
+
Its mesh, material and textures are the mode's own, kept on `world.sky`,
|
|
1499
|
+
one record for one load of one scene. The mesh is in the scene graph only
|
|
1500
|
+
while a frame of that scene is being drawn, put there and taken out by
|
|
1501
|
+
writing `parent` and `children` directly, so no three.js event is
|
|
1502
|
+
dispatched and no listener of a deck's runs. So `skipUnchangedActors`,
|
|
1503
|
+
`dropEmptyParts`, the look bake, a deck's own walk of `scene.three.scene`,
|
|
1504
|
+
picking, and hub-game's Low tier never meet it; the orbit camera's reach is
|
|
1505
|
+
physics, where it has no collider.
|
|
1506
|
+
|
|
1507
|
+
What ends a record: the scene loaded again or another loaded
|
|
1508
|
+
(`SceneRuntime.load`, through the physics system's `reset`; a load ends
|
|
1509
|
+
only the record of the key it replaces), a frame of another scene or of
|
|
1510
|
+
one without the key, an editor's frame (the editors give `renderWorld` no
|
|
1511
|
+
runtime, and draw no sky), `disposeWorld`, the runtime pointed at another
|
|
1512
|
+
world, and any frame that throws, or has a frame inside it throw, whether
|
|
1513
|
+
or not what called that catches the error. It is disposed at once when no
|
|
1514
|
+
frame of the world is being drawn, and otherwise by the outermost frame as
|
|
1515
|
+
it settles. Every resource is disposed once, each in a guard of its own; a
|
|
1516
|
+
disposal counts as a frame in progress, so a frame drawn from inside a
|
|
1517
|
+
`dispose` listener is a frame from inside: it has no sky and makes
|
|
1518
|
+
nothing. The next frame of a keyed scene starts from nothing, with no
|
|
1519
|
+
fade. Two worlds keep their own.
|
|
1520
|
+
`leaveSky` returns `null` only on success. World disposal and physics reset
|
|
1521
|
+
propagate its first error with `failed !== null`, so a listener's `throw 0`
|
|
1522
|
+
is preserved too. A failed reset stops the load before the new scene is
|
|
1523
|
+
installed, after the sky's resources have been released.
|
|
1524
|
+
|
|
1525
|
+
When `staticActors` is on too, every record release and each nonempty
|
|
1526
|
+
shed-texture disposal runs through the world's `outsideCall` hook. The
|
|
1527
|
+
entire disposal block is counted, so every texture, geometry and material
|
|
1528
|
+
listener sees no recorded adoption and no frozen node, and a listener's
|
|
1529
|
+
nested sync cannot adopt between resources or listeners. The callback is
|
|
1530
|
+
made once per world, lazily when a record is actually made, and reused on
|
|
1531
|
+
later records; unchanged frames do not test or call it. With no hook the
|
|
1532
|
+
same block runs directly. This bracket changes neither the sky's ordering
|
|
1533
|
+
nor its depth count or handling of errors: each listener still runs in its
|
|
1534
|
+
own guard, the first error stays data, and it is thrown at the frame's one
|
|
1535
|
+
exit after settling. The next actor pass is ordinary; later passes may
|
|
1536
|
+
settle, unless the world was disposed.
|
|
1537
|
+
|
|
1538
|
+
`runtime.sprites` and its entries are engine-made art data, the same records
|
|
1539
|
+
the engine's other drawing reads. The sky reads the slot and `kind`,
|
|
1540
|
+
`ready`, `failed` and `image` only with `Object.getOwnPropertyDescriptor`,
|
|
1541
|
+
and uses only a data property's `value`:
|
|
1542
|
+
> the sky reads art records only through own data properties, so a getter never runs
|
|
1543
|
+
|
|
1544
|
+
An accessor slot or field, or an entry that is not a plain object (an
|
|
1545
|
+
ordinary object or one with a null prototype), is not usable: the zone
|
|
1546
|
+
shows its flat colour, with one warning naming the zone and art path per
|
|
1547
|
+
world, including across sky record recreation. These reads run without
|
|
1548
|
+
`outsideCall`, so unchanged sky frames preserve static adoption. A Proxy
|
|
1549
|
+
replacing `runtime.sprites` itself is outside the contract: the deck
|
|
1550
|
+
replaced an engine object. The descriptor and prototype checks, and the
|
|
1551
|
+
small `{ art, image }` snapshot for a usable entry, run only with the sky
|
|
1552
|
+
key on, once for each of the at most two textures drawn; there is no new
|
|
1553
|
+
per-frame work with the sky key absent, whether or not static actors are on.
|
|
1554
|
+
|
|
1555
|
+
**This relies on three.js's EventDispatcher internals, on purpose.** For a
|
|
1556
|
+
texture, a geometry and a material, three.js's `dispose()` is
|
|
1557
|
+
`dispatchEvent({ type: 'dispose' })` and nothing else, and `dispatchEvent`
|
|
1558
|
+
stops at the first listener that throws. The renderer's own cleanup of the
|
|
1559
|
+
GPU's copy is one of those listeners, added when the thing is first drawn
|
|
1560
|
+
and so after any a deck added before that: one deck listener that throws
|
|
1561
|
+
would leave the texture, the buffers or the program allocated for good,
|
|
1562
|
+
whatever is caught round `dispose()`. So for the sky's own resources
|
|
1563
|
+
`skylife.js` does not call `dispose()`: it reads the resource's
|
|
1564
|
+
`_listeners.dispose` (EventDispatcher's own array), copies it, and calls
|
|
1565
|
+
each listener in a try of its own with the event three.js would send. If
|
|
1566
|
+
that array is not there in that shape it calls `dispose()` instead, in a
|
|
1567
|
+
guard. `test-sky.mjs` fails if three.js keeps listeners elsewhere or its
|
|
1568
|
+
`dispose()` comes to do more than dispatch: when it does after a three.js
|
|
1569
|
+
upgrade, read `disposed` in `skylife.js` again before changing the test.
|
|
1570
|
+
|
|
1571
|
+
While a record's resources are disposed, `world.sky` is a marker that is
|
|
1572
|
+
not a record and owns nothing (`{ releasing: true }`), so that any frame a
|
|
1573
|
+
`dispose` listener draws, an editor's or a keyless scene's included, is a
|
|
1574
|
+
frame from inside: it makes nothing, and if it throws, the frame round the
|
|
1575
|
+
disposal keeps no record. The marker is gone when the disposal ends.
|
|
1576
|
+
|
|
1577
|
+
With the key absent, what runs that did not before: `load` reads
|
|
1578
|
+
`data.engine.sky` once and stores null, and the physics system's `reset`
|
|
1579
|
+
reads `world.sky` (null) once; each `renderWorld` reads that null and
|
|
1580
|
+
`world.sky` and calls the frame it always was; `disposeWorld` reads
|
|
1581
|
+
`world.sky` once. No call-out hook is acquired or allocated for a world
|
|
1582
|
+
that never has a sky record.
|
|
1583
|
+
- `"engine": { "maxFps": 60 }` at the scene file's top level (the same
|
|
1584
|
+
`engine` object) asks the play loop (`engine3d/Scene3DPlayer.jsx`) not to
|
|
1585
|
+
run its frame more often than that on a display that refreshes faster.
|
|
1586
|
+
Without it the loop runs a whole frame (behaviours, physics, drawing) on
|
|
1587
|
+
every animation frame the browser gives it, 120 a second on a 120 Hz
|
|
1588
|
+
display; a scene that costs most of a frame there runs a core flat out and
|
|
1589
|
+
drops every other frame. The terms:
|
|
1590
|
+
> With the key absent, the loop runs exactly as before: every animation
|
|
1591
|
+
> frame, handed the time since the last one, at most 0.033 s. With the key
|
|
1592
|
+
> present, an animation frame runs the whole frame only when at least 78%
|
|
1593
|
+
> of 1/maxFps seconds has passed since the last frame that ran, and is
|
|
1594
|
+
> handed all of that time, at most 0.05 s, so nothing skipped is lost:
|
|
1595
|
+
> a key pressed and let go, or a drag begun and ended, while frames were
|
|
1596
|
+
> skipped is seen by the next frame that runs, as one frame would have
|
|
1597
|
+
> seen it without the key. An animation frame that does not run does
|
|
1598
|
+
> nothing at all. The first frame always runs.
|
|
1599
|
+
|
|
1600
|
+
0.05 s is three of physics' 1/60 s steps: physics takes at most four a
|
|
1601
|
+
frame and drops what is left after four, so a longer frame (with what it
|
|
1602
|
+
carries over) could leave physics behind the behaviours' clock; at most
|
|
1603
|
+
0.05 s a frame, the two keep the same time to within the one step physics
|
|
1604
|
+
carries. That is why a cap is at least 30: a cap's frames are 1/maxFps
|
|
1605
|
+
apart, under 0.05 s from 30 up, so the cut falls only on a late frame, as
|
|
1606
|
+
0.033 s does without the key. How input is lent (`engine3d/framecap.js`,
|
|
1607
|
+
`updateLending`): the key handlers write down, under a cap only, every key
|
|
1608
|
+
that went down and the stick's last direction while a drag held it; the
|
|
1609
|
+
next frame that runs has each such key that is no longer held in
|
|
1610
|
+
`runtime.keys` for its update, and that stick direction in
|
|
1611
|
+
`runtime.moveInput` when no drag holds it now, and both are taken back
|
|
1612
|
+
after the update. A key held across is seen as held, as always. A tap's
|
|
1613
|
+
jump (`consumeJump`), the hub's grab key and its buttons keep their own
|
|
1614
|
+
latches or act at once, and lose nothing.
|
|
1615
|
+
|
|
1616
|
+
It goes by the time between frames, never by counting them; no frame is
|
|
1617
|
+
made up after a late one. A browser only hands out frames on the display's
|
|
1618
|
+
refresh, so the rule picks a whole number of refreshes per frame, and the
|
|
1619
|
+
78% is chosen so that each display gets one steady cadence at 60: every
|
|
1620
|
+
refresh at 60 Hz (even with timestamps up to 1.8 ms early or late) and at
|
|
1621
|
+
75 Hz; every second at 90, 120 and 144 Hz (45, 60 and 72 fps); every
|
|
1622
|
+
third at 165 and 180 Hz (55, 60); every fourth at 240 Hz (60). A cap is a
|
|
1623
|
+
finite number from 30 to 240; anything else is no cap. It is read when
|
|
1624
|
+
the scene loads (`runtime.maxFps`) and looked at every animation frame,
|
|
1625
|
+
so going to a scene without it takes the cap off from the next frame on.
|
|
1626
|
+
The scene and model editors run their own loops and are never capped.
|
|
1627
|
+
Opt in when a scene costs enough that a fast display keeps the loop busy
|
|
1628
|
+
all the time; a cheap scene loses smoothness on such a display and
|
|
1629
|
+
gains nothing.
|
|
1630
|
+
|
|
1631
|
+
The cap also changes how the `Player` hovers, as the camera key does:
|
|
1632
|
+
under it the hover spring and the fall-faster pull are forces
|
|
1633
|
+
(`hoverSteadily`, `pullSteadily`), with or without the camera key. Why:
|
|
1634
|
+
the keyless hover and pull are impulses scaled by the frame's dt, pushed
|
|
1635
|
+
once a frame, while gravity pulls once per fixed step, so each frame the
|
|
1636
|
+
player gains g x (dt - steps x 1/60), which is g x (the change in
|
|
1637
|
+
physics' accumulator carry). Its vertical speed follows the carry and its
|
|
1638
|
+
drawn height bobs with it. Uncapped, a slow phone's frames longer than
|
|
1639
|
+
33 ms are all clamped to 0.033 s, two steps less 0.3 ms, so the carry
|
|
1640
|
+
barely moves and the bob stays small; under the cap the same frames are
|
|
1641
|
+
handed what they took (25 to 50 ms), the carry jumps anywhere in
|
|
1642
|
+
[0, 1/60) every frame, and the bob grows. That was the TECNO KJ5's
|
|
1643
|
+
tripled walking bob (3.2-3.4 cm against 1.05-1.16) that had the cap
|
|
1644
|
+
reverted: measured before the hover became a force under the camera key,
|
|
1645
|
+
so the town's Player was hovering by impulses then. Never the 3/60 clamp
|
|
1646
|
+
itself: shrinking it would only cut more frames short.
|
|
1647
|
+
`scripts/test-frame-cap-bob.mjs` drives the real Player and physics on
|
|
1648
|
+
made-up frame timestamps through the real `nextFrame`; drawn height
|
|
1649
|
+
peak to peak walking, in mm, without the camera key:
|
|
1650
|
+
|
|
1651
|
+
| frames | uncapped | capped, impulse hover (reverted) | capped (now) |
|
|
1652
|
+
| --- | --- | --- | --- |
|
|
1653
|
+
| 60 Hz steady | 9.50 | 9.50 | 0.00 |
|
|
1654
|
+
| 120 Hz, capped at 60 | 4.85 | 0.00 | 0.00 |
|
|
1655
|
+
| slow phone, 25-55 ms + hitches (3 seeds) | 12.8-13.0 | 21.9-23.6 | 0.00 |
|
|
1656
|
+
| slow phone, whole 90 Hz refreshes | 14.70 | 26.47 | 0.00 |
|
|
1657
|
+
| slow phone, whole 60 Hz refreshes | 10.86 | 28.85 | 0.00 |
|
|
1658
|
+
|
|
1659
|
+
With the camera key every cell is 0.00, capped or not; the walk's
|
|
1660
|
+
horizontal speed is even in every cell (the walk push stays a per-frame
|
|
1661
|
+
impulse: on flat ground nothing pushes against it per step, so at speed
|
|
1662
|
+
it pushes nothing). The terms: with the key absent, `scene.maxFps` is 0
|
|
1663
|
+
and the Player makes the calls it made before (test-steady-hover.mjs).
|
|
1664
|
+
With it, the player stands and walks at the camera key's height, 0.7412 m
|
|
1665
|
+
for the kit's player, whatever the frames, where the keyless player's
|
|
1666
|
+
height depends on the frame rate (the damper answers the speed gravity
|
|
1667
|
+
gave it since the last frame's push): 0.739 m at a steady 60 fps, 0.731
|
|
1668
|
+
at 120, about 0.756 at 30. So a capped scene's player stands up to 1.5 cm
|
|
1669
|
+
lower on a slow phone than the same scene uncapped, and 2 mm higher at
|
|
1670
|
+
60 fps; a player with another gravity scale is off by 0.69 cm per unit of
|
|
1671
|
+
scale, as under the camera key. A jump goes as high as under the camera
|
|
1672
|
+
key, to within 3 mm (2.347 to 2.355 m).
|
|
1673
|
+
|
|
1674
|
+
The same dt variance moved the keyless follow camera (`updateCamera`). It
|
|
1675
|
+
eases once a frame, from the Player's update, by 1 - e^(-12 dt) toward
|
|
1676
|
+
where the player was drawn the frame before; behind a walk at v it trails
|
|
1677
|
+
by about v/12 + v dt/2, and the player is then drawn v dt further on, so
|
|
1678
|
+
under the cap the player slid about on screen (camera-to-player distance
|
|
1679
|
+
peak to peak walking 39-52 mm against 12-19 uncapped on the slow-phone
|
|
1680
|
+
traces). Under the cap, without a camera key, the Player asks for its
|
|
1681
|
+
camera as the rigid one does (`scene.followCamera`, Player.jsx
|
|
1682
|
+
`placeCapped`; `placeFollowCamera` in systems/physics3d.js now takes a
|
|
1683
|
+
request from a scene with `maxFps` too): it is placed at the end of the
|
|
1684
|
+
frame on the position the frame is drawn with, the same target and rate,
|
|
1685
|
+
each coordinate eased as if the target moved steadily since the last
|
|
1686
|
+
frame (`settle`, the exact solution of x' = 12 (target - x)), so a steady
|
|
1687
|
+
walk is trailed by v/12 whatever the frames: that distance moves 0.00 mm
|
|
1688
|
+
on every trace (4.3, 2.1 and 12-19 mm uncapped), and the camera's height
|
|
1689
|
+
0.00. Last frame's target is `actor.runtime.camTarget`; a teleport snaps
|
|
1690
|
+
as it does uncapped. The orbit camera is under the camera key, placed at
|
|
1691
|
+
the frame's end and eased exactly (or toward what the player asked, which
|
|
1692
|
+
does not move with the walk) already, and is not changed.
|
|
1693
|
+
|
|
1694
|
+
60 is the tested cap: `RUN_SHARE`'s margins are worked out for it against
|
|
1695
|
+
the common refresh rates. Other caps are allowed but thinner (a display
|
|
1696
|
+
whose period sits near a multiple of 0.78/maxFps alternates cadences on
|
|
1697
|
+
jittery timestamps), and a cap runs at a whole number of refreshes, not
|
|
1698
|
+
at its own value: on a 60 Hz display a cap from 30 to about 46.8 runs at
|
|
1699
|
+
30 fps and one from about 46.8 up runs at 60. Because the capped keyless
|
|
1700
|
+
camera is placed at the frame's end (as the rigid one is), a deck
|
|
1701
|
+
behaviour that moves the camera during the update is overwritten there
|
|
1702
|
+
under the cap. Releasing: the cap is read by physics-2d's
|
|
1703
|
+
`SceneRuntime` (`maxFps`, latched at load) and acted on by physics-3d;
|
|
1704
|
+
physics-3d pins the physics-2d it imports (`castle.json` `imports`), so
|
|
1705
|
+
physics-2d must be republished and physics-3d's import of it moved before
|
|
1706
|
+
the cap does anything in a deck. Until then `runtime.maxFps` is undefined,
|
|
1707
|
+
every check above reads it as no cap, and the key is dormant.
|
|
1708
|
+
Under the orbit camera key the drag stick is the orbit input's
|
|
1709
|
+
(engine3d/orbitinput.js), which writes the same `runtime.moveInput`; the
|
|
1710
|
+
move handler latches it under a cap as it does its own, so a stick drag
|
|
1711
|
+
begun and ended between two capped frames is lent to the next frame that
|
|
1712
|
+
runs too. Its camera drags are summed until the frame takes them, and lose
|
|
1713
|
+
nothing.
|
|
340
1714
|
- `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
|
|
341
1715
|
kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
|
|
342
1716
|
stage to place), orbit camera (drag orbits, wheel zooms), click to select /
|
|
@@ -380,6 +1754,10 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
|
|
|
380
1754
|
|
|
381
1755
|
## Making a model
|
|
382
1756
|
|
|
1757
|
+
A deck may set top-level `"gait": "model"` in its own `castle.json` for
|
|
1758
|
+
scale-aware walk cadence (docs/pxmodel-format.md, Animation). Absent keeps
|
|
1759
|
+
the fixed gait unchanged; this is a deck option, not a scene/model field.
|
|
1760
|
+
|
|
383
1761
|
Read all of `docs/pxmodel-format.md` before writing a model. Then:
|
|
384
1762
|
|
|
385
1763
|
1. Decide what makes this one distinctive: its silhouette and two or three
|
|
@@ -450,3 +1828,16 @@ formats, imports, reloading, editors -- are the Castle CLI's, not this deck's.
|
|
|
450
1828
|
The serve writes them fresh at every start to `.castle/docs/platform.md`, loaded here:
|
|
451
1829
|
|
|
452
1830
|
@.castle/docs/platform.md
|
|
1831
|
+
|
|
1832
|
+
Client rig budgeting: `entry.node.userData.animationEvery` is an optional
|
|
1833
|
+
positive finite cadence in seconds for composed model animation (biped walk
|
|
1834
|
+
and authored motion together). The animator accumulates dt until that cadence
|
|
1835
|
+
and flushes pending time when the field is removed or its cadence changes. It changes no physics, actor transforms, or events. The hub
|
|
1836
|
+
town sets it only for distant NPC/display actors on its opt-in Low budget.
|
|
1837
|
+
|
|
1838
|
+
A client controller may set `actor.runtime.renderSleep = true` only after
|
|
1839
|
+
detaching its existing actor node from the render scene. Render sync then
|
|
1840
|
+
keeps the node allocated but skips transform/model/animation work; an absent
|
|
1841
|
+
node is still created, and a reattached node always synchronizes. The
|
|
1842
|
+
controller must check live actor data and clear the flag before reattaching
|
|
1843
|
+
or restoring High. This does not pause physics, events, or network state.
|