castle-web-cli 0.4.232 → 0.4.234
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/api.d.ts +11 -0
- package/dist/api.js +43 -0
- package/dist/bundle.d.ts +64 -0
- package/dist/bundle.js +558 -2
- package/dist/castle-host/host.d.ts +18 -2
- package/dist/castle-host/host.js +844 -39
- package/dist/castleJson.d.ts +23 -2
- package/dist/castleJson.js +46 -2
- package/dist/check.d.ts +3 -1
- package/dist/check.js +20 -3
- package/dist/chunkLoader.d.ts +3 -0
- package/dist/chunkLoader.js +111 -0
- package/dist/devParty.d.ts +26 -0
- package/dist/devParty.js +231 -0
- package/dist/devSaveStorage.js +4 -0
- package/dist/devSessionStorage.js +50 -2
- package/dist/devSocial.d.ts +24 -0
- package/dist/devSocial.js +70 -0
- package/dist/ide.d.ts +2 -0
- package/dist/ide.js +119 -15
- 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 +11 -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 +25 -1
- package/dist/save-deck.js +178 -9
- package/dist/serve.js +32 -11
- package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
- 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/dist/vitePlugins.d.ts +2 -1
- package/dist/vitePlugins.js +13 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/README.md +339 -5
- package/kits/base/sdk/avatar.d.ts +6 -2
- package/kits/base/sdk/avatar.js +12 -4
- package/kits/base/sdk/castle.d.ts +7 -3
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +176 -1
- package/kits/base/sdk/commands.js +3 -0
- package/kits/base/sdk/display.d.ts +3 -0
- package/kits/base/sdk/display.js +9 -3
- package/kits/base/sdk/hub.d.ts +37 -6
- package/kits/base/sdk/hub.js +63 -4
- package/kits/base/sdk/multiplayer.d.ts +7 -1
- package/kits/base/sdk/multiplayer.js +148 -32
- package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
- package/kits/base/sdk/party.d.ts +23 -0
- package/kits/base/sdk/party.js +91 -0
- package/kits/base/sdk/reconnectBudget.d.ts +23 -0
- package/kits/base/sdk/reconnectBudget.js +96 -0
- package/kits/base/sdk/save.d.ts +38 -1
- package/kits/base/sdk/save.js +81 -7
- package/kits/base/sdk/server/hub.d.ts +117 -0
- package/kits/base/sdk/server/hub.js +119 -2
- package/kits/base/sdk/server/platformHandle.d.ts +43 -1
- package/kits/base/sdk/server/storage.d.ts +17 -0
- package/kits/base/sdk/server/storage.js +65 -3
- package/kits/base/sdk/server/wrapper.d.ts +43 -6
- package/kits/base/sdk/server/wrapper.js +93 -9
- package/kits/base/sdk/social.d.ts +9 -0
- package/kits/base/sdk/social.js +5 -0
- package/kits/hub-game/CLAUDE.md +451 -13
- package/kits/hub-game/README.md +63 -0
- 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/castle.json +5 -5
- package/kits/hub-game/code/client/act.js +312 -0
- package/kits/hub-game/code/client/actionLayout.js +147 -0
- package/kits/hub-game/code/client/actionOverflow.js +556 -0
- package/kits/hub-game/code/client/actorBudget.js +47 -0
- package/kits/hub-game/code/client/arrivalCamera.js +50 -0
- package/kits/hub-game/code/client/askSlot.js +117 -0
- package/kits/hub-game/code/client/attention.js +11 -2
- package/kits/hub-game/code/client/avatar.js +311 -35
- 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 +253 -0
- package/kits/hub-game/code/client/backVisibility.js +13 -0
- package/kits/hub-game/code/client/ballot.js +472 -0
- package/kits/hub-game/code/client/build.js +38 -0
- package/kits/hub-game/code/client/chat.js +41 -5
- package/kits/hub-game/code/client/chatModeration.js +5 -0
- package/kits/hub-game/code/client/chrome.js +2144 -160
- 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/crowdNames.js +241 -0
- package/kits/hub-game/code/client/decor.js +515 -0
- package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
- package/kits/hub-game/code/client/doorErrors.js +39 -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/fall.js +18 -0
- package/kits/hub-game/code/client/farAvatars.js +233 -0
- package/kits/hub-game/code/client/firstJoin.js +9 -2
- package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
- package/kits/hub-game/code/client/frameBatch.js +5 -0
- package/kits/hub-game/code/client/grab.js +368 -29
- package/kits/hub-game/code/client/hookLayer.js +385 -20
- package/kits/hub-game/code/client/hudCopy.js +51 -0
- package/kits/hub-game/code/client/hudRate.js +20 -0
- package/kits/hub-game/code/client/idle.js +177 -24
- package/kits/hub-game/code/client/interestCap.js +81 -0
- package/kits/hub-game/code/client/invites.js +231 -0
- package/kits/hub-game/code/client/joinError.js +9 -0
- package/kits/hub-game/code/client/keys.js +36 -0
- package/kits/hub-game/code/client/labelsNear.js +234 -0
- package/kits/hub-game/code/client/landscapeLayout.js +17 -0
- package/kits/hub-game/code/client/layoutCache.js +264 -0
- package/kits/hub-game/code/client/loadTelemetry.js +20 -0
- package/kits/hub-game/code/client/loadingCover.js +148 -0
- package/kits/hub-game/code/client/loadingEntry.js +8 -0
- package/kits/hub-game/code/client/menuIcons.js +34 -0
- package/kits/hub-game/code/client/menuRows.js +43 -0
- package/kits/hub-game/code/client/modelReady.js +7 -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/padCueArrival.js +23 -0
- package/kits/hub-game/code/client/padCues.js +112 -0
- package/kits/hub-game/code/client/padOccupancy.js +88 -0
- package/kits/hub-game/code/client/padReadability.js +26 -0
- package/kits/hub-game/code/client/padRings.js +69 -0
- package/kits/hub-game/code/client/pushVisit.js +14 -0
- package/kits/hub-game/code/client/quality.js +205 -0
- package/kits/hub-game/code/client/qualityEntry.js +55 -0
- package/kits/hub-game/code/client/rehello.js +167 -0
- package/kits/hub-game/code/client/safeLayout.js +338 -0
- package/kits/hub-game/code/client/safeStyle.js +42 -0
- package/kits/hub-game/code/client/say.js +12 -3
- package/kits/hub-game/code/client/shot.js +146 -0
- package/kits/hub-game/code/client/shotFit.js +56 -0
- package/kits/hub-game/code/client/signIn.js +28 -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 +162 -1
- package/kits/hub-game/code/client/stuck.js +259 -0
- package/kits/hub-game/code/client/talk.js +714 -59
- package/kits/hub-game/code/client/tiers.js +543 -52
- package/kits/hub-game/code/client/toastBand.js +37 -0
- package/kits/hub-game/code/client/together.js +39 -2
- package/kits/hub-game/code/client/visibility.js +43 -0
- package/kits/hub-game/code/client/weakestLookBake.js +92 -0
- package/kits/hub-game/code/client/weakestTier.js +295 -0
- package/kits/hub-game/code/client/wear.js +461 -170
- package/kits/hub-game/code/client/worldLabels.js +241 -0
- package/kits/hub-game/code/client/yours.js +200 -0
- package/kits/hub-game/code/companionSpec.js +45 -0
- package/kits/hub-game/code/npcDisplayText.js +55 -0
- package/kits/hub-game/code/privateText.js +7 -0
- package/kits/hub-game/code/server/act.js +124 -0
- package/kits/hub-game/code/server/actions.js +138 -0
- package/kits/hub-game/code/server/actors.js +11 -2
- package/kits/hub-game/code/server/analytics.js +83 -0
- package/kits/hub-game/code/server/anonymousEntry.js +49 -0
- package/kits/hub-game/code/server/arrivalPose.js +36 -0
- 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 +107 -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/doorAnalytics.js +52 -0
- package/kits/hub-game/code/server/earned.js +478 -0
- package/kits/hub-game/code/server/frameBatch.js +183 -0
- package/kits/hub-game/code/server/friendBests.js +166 -0
- package/kits/hub-game/code/server/friendsAmong.js +272 -0
- package/kits/hub-game/code/server/history.js +7 -0
- package/kits/hub-game/code/server/hub.js +2510 -95
- package/kits/hub-game/code/server/idle.js +60 -12
- package/kits/hub-game/code/server/index.js +28 -6
- package/kits/hub-game/code/server/invites.js +19 -0
- package/kits/hub-game/code/server/labels.js +36 -2
- package/kits/hub-game/code/server/loadAbandon.js +106 -0
- package/kits/hub-game/code/server/manifest.js +586 -7
- package/kits/hub-game/code/server/menu.js +161 -0
- package/kits/hub-game/code/server/npcs.js +1025 -113
- package/kits/hub-game/code/server/observe.js +408 -0
- package/kits/hub-game/code/server/padOccupancy.js +85 -0
- package/kits/hub-game/code/server/party.js +2 -2
- package/kits/hub-game/code/server/players.js +30 -0
- package/kits/hub-game/code/server/resumePose.js +152 -0
- package/kits/hub-game/code/server/say.js +1 -1
- package/kits/hub-game/code/server/shot.js +110 -0
- package/kits/hub-game/code/server/standing.js +123 -0
- package/kits/hub-game/code/server/storageLimit.js +187 -0
- package/kits/hub-game/code/server/vis.js +175 -0
- package/kits/hub-game/code/server/wear.js +12 -0
- package/kits/hub-game/code/server/yours.js +59 -0
- package/kits/hub-game/code/shared/act.js +35 -0
- package/kits/hub-game/code/shared/cues.js +9 -0
- package/kits/hub-game/code/shared/danceIdle.js +28 -0
- package/kits/hub-game/code/shared/decor.js +41 -0
- package/kits/hub-game/code/shared/loadStages.js +12 -0
- package/kits/hub-game/code/shared/quality.js +74 -0
- package/kits/hub-game/code/shared/say.js +2 -0
- package/kits/hub-game/code/shared/shot.js +53 -0
- package/kits/hub-game/code/shared/spin.js +57 -0
- package/kits/hub-game/code/systems/hub.js +1753 -202
- package/kits/hub-game/docs/analytics.md +279 -0
- package/kits/hub-game/docs/content-pack.md +1 -1
- package/kits/hub-game/docs/contract.md +3475 -77
- package/kits/hub-game/docs/home-pieces.md +71 -0
- package/kits/hub-game/docs/observed-progress.md +252 -0
- package/kits/hub-game/main.jsx +2 -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 +10 -1
- package/kits/hub-game/package.json +6 -2
- package/kits/hub-game/play/player.js +142 -0
- package/kits/hub-game/play/registry.js +47 -0
- package/kits/hub-game/play.jsx +37 -0
- package/kits/hub-game/scripts/check.mjs +117 -16
- package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
- package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
- package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -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/pose-storage-fixture.mjs +46 -0
- package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
- package/kits/hub-game/scripts/test-act-client.mjs +186 -0
- package/kits/hub-game/scripts/test-act.mjs +171 -0
- package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
- package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
- package/kits/hub-game/scripts/test-actions-client.mjs +853 -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 +38 -23
- package/kits/hub-game/scripts/test-analytics.mjs +76 -0
- package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
- package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
- package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
- package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
- package/kits/hub-game/scripts/test-ask-slot.mjs +85 -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 +792 -0
- package/kits/hub-game/scripts/test-avatar.mjs +584 -7
- package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
- package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
- package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
- package/kits/hub-game/scripts/test-build.mjs +49 -0
- package/kits/hub-game/scripts/test-cells.mjs +71 -0
- package/kits/hub-game/scripts/test-chat.mjs +863 -0
- package/kits/hub-game/scripts/test-classic.mjs +2 -0
- package/kits/hub-game/scripts/test-companion-chat.mjs +216 -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-control-layout-dom.mjs +120 -0
- package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
- package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
- package/kits/hub-game/scripts/test-decor.mjs +464 -0
- package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
- package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
- package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
- package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
- package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
- package/kits/hub-game/scripts/test-earned.mjs +1224 -0
- package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
- package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
- package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
- package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
- package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
- package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
- package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
- package/kits/hub-game/scripts/test-grab.mjs +7 -0
- package/kits/hub-game/scripts/test-hats.mjs +422 -168
- package/kits/hub-game/scripts/test-high-only.mjs +170 -0
- package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
- package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
- package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
- package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
- package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
- package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
- package/kits/hub-game/scripts/test-idle.mjs +427 -1
- package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
- package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
- package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
- package/kits/hub-game/scripts/test-interest.mjs +15 -0
- package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
- package/kits/hub-game/scripts/test-invites.mjs +109 -0
- package/kits/hub-game/scripts/test-keys.mjs +46 -1
- package/kits/hub-game/scripts/test-labels.mjs +664 -0
- package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
- package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
- package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
- package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
- package/kits/hub-game/scripts/test-manifest.mjs +472 -0
- package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
- package/kits/hub-game/scripts/test-menu.mjs +319 -0
- package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
- package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
- package/kits/hub-game/scripts/test-observed.mjs +745 -0
- package/kits/hub-game/scripts/test-pack.mjs +7 -0
- package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
- package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
- package/kits/hub-game/scripts/test-picker.mjs +541 -0
- package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
- package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
- package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
- package/kits/hub-game/scripts/test-quality.mjs +385 -0
- package/kits/hub-game/scripts/test-rehello.mjs +1733 -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-resume-action-order.mjs +598 -0
- package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
- package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
- package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
- package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
- package/kits/hub-game/scripts/test-say.mjs +1 -1
- package/kits/hub-game/scripts/test-shot.mjs +901 -0
- package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
- package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
- package/kits/hub-game/scripts/test-spin.mjs +314 -0
- package/kits/hub-game/scripts/test-standing.mjs +449 -0
- package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
- package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
- package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
- package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
- package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
- package/kits/hub-game/scripts/test-tiers.mjs +476 -2
- package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
- package/kits/hub-game/scripts/test-try-on.mjs +22 -22
- package/kits/hub-game/scripts/test-vis.mjs +770 -0
- package/kits/hub-game/scripts/test-visibility.mjs +134 -0
- package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
- package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
- package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
- package/kits/hub-game/scripts/test-yours.mjs +403 -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/joinFailure.js +27 -0
- package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
- package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
- 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 +443 -34
- package/kits/multiplayer-3d/package-lock.json +8 -1
- package/kits/multiplayer-3d/package.json +3 -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-join-watchdog.mjs +436 -0
- package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
- package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
- package/kits/physics-2d/CLAUDE.md +19 -1
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/frozenActors.js +233 -0
- package/kits/physics-2d/engine/scene.js +337 -3
- 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/eslint.config.js +1 -1
- package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
- package/kits/physics-2d/play/behaviors/Camera.js +40 -0
- package/kits/physics-2d/play/behaviors/Collider.js +122 -0
- package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
- package/kits/physics-2d/play/behaviors/Goal.js +46 -0
- package/kits/physics-2d/play/behaviors/Joints.js +126 -0
- package/kits/physics-2d/play/behaviors/Layout.js +71 -0
- package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
- package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
- package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
- package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
- package/kits/physics-2d/play/behaviors/Style.js +209 -0
- package/kits/physics-2d/play/behaviors/Text.js +85 -0
- package/kits/physics-2d/play/behaviors/Video.js +93 -0
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
- package/kits/physics-3d/CLAUDE.md +42 -529
- package/kits/physics-3d/behaviors/Body.jsx +3 -0
- package/kits/physics-3d/behaviors/Model.jsx +3 -0
- package/kits/physics-3d/behaviors/Player.jsx +661 -87
- package/kits/physics-3d/behaviors/Shape.jsx +3 -0
- package/kits/physics-3d/behaviors/Solid.jsx +3 -0
- package/kits/physics-3d/behaviors/Transform.jsx +3 -0
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/docs/engine-camera.md +542 -0
- package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
- package/kits/physics-3d/docs/engine-load.md +149 -0
- package/kits/physics-3d/docs/engine-look.md +114 -0
- package/kits/physics-3d/docs/engine-shadows.md +372 -0
- package/kits/physics-3d/docs/engine-skip-work.md +187 -0
- package/kits/physics-3d/docs/engine-sky.md +198 -0
- package/kits/physics-3d/docs/engine-static-actors.md +226 -0
- package/kits/physics-3d/docs/engine-view.md +37 -0
- package/kits/physics-3d/docs/pxmodel-format.md +9 -1
- package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
- package/kits/physics-3d/engine3d/actornode.js +87 -0
- package/kits/physics-3d/engine3d/animationBudget.js +23 -0
- package/kits/physics-3d/engine3d/branches.js +3 -13
- package/kits/physics-3d/engine3d/cage.js +2 -7
- package/kits/physics-3d/engine3d/cageops.js +2 -17
- package/kits/physics-3d/engine3d/dataBehaviors.js +12 -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 +99 -0
- package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
- package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
- package/kits/physics-3d/engine3d/gait.js +126 -0
- package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
- package/kits/physics-3d/engine3d/kithooks.js +47 -0
- package/kits/physics-3d/engine3d/look.js +514 -48
- package/kits/physics-3d/engine3d/lookbake.js +208 -0
- package/kits/physics-3d/engine3d/materialpresets.js +2 -0
- package/kits/physics-3d/engine3d/modelFiles.js +3 -17
- package/kits/physics-3d/engine3d/modelMath.js +49 -0
- package/kits/physics-3d/engine3d/modelready.js +16 -0
- package/kits/physics-3d/engine3d/motion.js +39 -10
- package/kits/physics-3d/engine3d/nearshadows.js +106 -21
- package/kits/physics-3d/engine3d/optimize.js +9 -5
- package/kits/physics-3d/engine3d/orbitinput.js +522 -10
- package/kits/physics-3d/engine3d/orbitlens.js +48 -0
- package/kits/physics-3d/engine3d/ownmodel.js +213 -0
- package/kits/physics-3d/engine3d/partgeometry.js +1 -16
- package/kits/physics-3d/engine3d/paths.js +1 -9
- package/kits/physics-3d/engine3d/playTimings.js +50 -0
- package/kits/physics-3d/engine3d/playerRun.js +372 -0
- package/kits/physics-3d/engine3d/pxmodel.js +42 -11
- package/kits/physics-3d/engine3d/rapier.js +27 -0
- package/kits/physics-3d/engine3d/scatter.js +1 -11
- package/kits/physics-3d/engine3d/shadowfade.js +890 -0
- package/kits/physics-3d/engine3d/sky.js +547 -0
- package/kits/physics-3d/engine3d/skylife.js +306 -0
- package/kits/physics-3d/engine3d/squarefirst.js +177 -0
- package/kits/physics-3d/engine3d/stillshadows.js +399 -0
- package/kits/physics-3d/engine3d/sweep.js +1 -25
- 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 +1253 -76
- package/kits/physics-3d/eslint.config.js +2 -1
- package/kits/physics-3d/main.jsx +10 -2
- package/kits/physics-3d/package-lock.json +7 -0
- package/kits/physics-3d/package.json +5 -1
- package/kits/physics-3d/play/behaviors/Body.js +31 -0
- package/kits/physics-3d/play/behaviors/Door.js +37 -0
- package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
- package/kits/physics-3d/play/behaviors/Model.js +23 -0
- package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
- package/kits/physics-3d/play/behaviors/Player.js +1204 -0
- package/kits/physics-3d/play/behaviors/Shape.js +47 -0
- package/kits/physics-3d/play/behaviors/Solid.js +16 -0
- package/kits/physics-3d/play/behaviors/Transform.js +29 -0
- package/kits/physics-3d/pnpm-lock.yaml +8 -0
- package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
- package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
- package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
- package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
- package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
- package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
- package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
- package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
- package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
- package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
- package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
- package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
- package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -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 +5 -2
- package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
- package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
- package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
- package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
- package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -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-square-first.mjs +921 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
- package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
- package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
- package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
- package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
- package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
- package/kits/physics-3d/systems/physics3d.js +419 -9
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/connection.js +33 -10
- package/kits/real-time/code/client/gameHooks.js +2 -0
- package/kits/real-time/code/client/joinOverlay.js +9 -4
- package/kits/real-time/code/server/gameHooks.js +7 -0
- package/kits/real-time/code/server/session.js +102 -22
- package/kits/real-time/package-lock.json +1 -1
- package/package.json +2 -2
- package/dist/shell/assets/index-Cf61cNfT.css +0 -1
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
# Scene key: engine.shadows
|
|
2
|
+
|
|
3
|
+
The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
|
|
4
|
+
the `engine` object at a scene file's top level, beside `ground`.
|
|
5
|
+
|
|
6
|
+
- `"engine": { "shadows": { "distance": 40, "cacheStill": true } }`
|
|
7
|
+
additionally reuses the depths of still casters. Omit `cacheStill` (or set
|
|
8
|
+
it to `false`) for the existing behaviour, with no cache allocations,
|
|
9
|
+
traversal, shader, or draws. `cacheStill` alone does nothing without a
|
|
10
|
+
valid near-shadow `distance`.
|
|
11
|
+
|
|
12
|
+
This uses the engine's still tracking, rather than an actor's `static`
|
|
13
|
+
mark alone: an adopted, frozen node from `staticActors` with
|
|
14
|
+
`skipUnchangedActors` (or the `frozenStatics` path). Touch an actor before
|
|
15
|
+
changing it, as required by those modes. Touched/thawed actors, newly
|
|
16
|
+
spawned actors, and animated models cast live shadows every frame.
|
|
17
|
+
Skinned, morphed, instanced, custom-depth, alpha-tested, displaced,
|
|
18
|
+
clipped, and wireframe casters also stay live, even under a frozen node.
|
|
19
|
+
|
|
20
|
+
A change of the existing texel-snapped box, depth range/lens, light
|
|
21
|
+
projection, runtime's still version/frozen epoch, or selected still
|
|
22
|
+
casters invalidates the cache. Its complete key must then match for
|
|
23
|
+
**three consecutive engine frames** (`STABLE_FRAMES = 3`) before a build.
|
|
24
|
+
On a miss or while waiting, the frame uses the ordinary shadow pass:
|
|
25
|
+
**no copy, no extra depth pass, and no still-map rebuild**. Continuous
|
|
26
|
+
camera movement therefore adds only key computation. Repeated renders
|
|
27
|
+
within one engine frame do not count as additional stable frames.
|
|
28
|
+
Selection includes visibility, layers, `castShadow`, the view-slice
|
|
29
|
+
frustum, matrices, geometry uploads/groups/draw range, and material depth
|
|
30
|
+
settings. A small camera move can reuse the map while those inputs remain
|
|
31
|
+
equal. Selection changes also invalidate inside one grid cell: caching
|
|
32
|
+
the whole box instead would change shadows outside the current view slice.
|
|
33
|
+
The picture and snapping are the same as ordinary near shadows.
|
|
34
|
+
|
|
35
|
+
On a cache hit or qualified build frame, the live shadow target is cleared
|
|
36
|
+
normally, then a fullscreen triangle copies the cached packed colour
|
|
37
|
+
**and hardware depth** into it.
|
|
38
|
+
Movers draw on top with the ordinary depth test and no further clear, so
|
|
39
|
+
movers occlude scenery correctly and leave no old shadows behind. On a
|
|
40
|
+
rebuild, a shadow-only pass draws still casters into the cache first. The
|
|
41
|
+
sun's own shadow/camera/map/target remain untouched; private shadows and
|
|
42
|
+
temporary caster filtering exist only inside the engine's render call.
|
|
43
|
+
Filtering ends before another light's shadows or any colour draw. The
|
|
44
|
+
existing orbit shadow-fade hook restores original materials before both
|
|
45
|
+
depth passes; its receiver shaders and fade stay unchanged.
|
|
46
|
+
|
|
47
|
+
Camera/scene identity and camera layers are part of the key. A render
|
|
48
|
+
using another actual camera or scene bypasses the cache entirely and
|
|
49
|
+
uses the ordinary shadow pass, without changing the primary view's key
|
|
50
|
+
or stability count. This includes a nested render from a mesh's
|
|
51
|
+
`onBeforeRender`. Selection and rebuilding use the actual render camera
|
|
52
|
+
and scene passed to the shadow hook. The private copy triangle enables
|
|
53
|
+
all layers so its geometry uploads even when the camera, sun, and casters
|
|
54
|
+
use layer 1 (or any layer other than 0). It is attached for the primary
|
|
55
|
+
camera's object walk before a build can qualify, submits no colour draw,
|
|
56
|
+
and detaches at the primary shadow pass. Unrelated renders leave it for
|
|
57
|
+
the primary camera's walk.
|
|
58
|
+
|
|
59
|
+
Cost: one extra map at the near map's resolution (RGBA8 plus a depth
|
|
60
|
+
texture, about 8 bytes per texel), one fullscreen draw per cache hit/build,
|
|
61
|
+
and a visible-scene walk plus still-caster comparisons. Key buffers and
|
|
62
|
+
selection arrays are reused; steady key computation allocates no arrays,
|
|
63
|
+
sets or per-caster descriptors. A new caster is inspected once; later flag
|
|
64
|
+
locks are checked before copying or drawing. A qualified build draws each
|
|
65
|
+
still caster once into the cache and each mover once into the live map,
|
|
66
|
+
rather than drawing either twice. This reduces draw submission when the
|
|
67
|
+
view and still scenery stay stable; it does not reduce scene updates or
|
|
68
|
+
the fade's own walk/material swaps. Frequent box/selection changes keep ordinary shadow
|
|
69
|
+
submission until the full key settles again.
|
|
70
|
+
|
|
71
|
+
The implementation is pinned to three.js r180's shadow-pass ordering. A
|
|
72
|
+
different revision, reversed/logarithmic depth, or a shadow pass that
|
|
73
|
+
cannot accept a temporary hook uses ordinary near shadows. A scene with
|
|
74
|
+
its own `onBeforeRender` also draws uncached. Custom shadow callbacks or
|
|
75
|
+
non-writable caster flags make the frame uncached, preserving their
|
|
76
|
+
behaviour. Custom depth materials with compile hooks or nonstandard depth
|
|
77
|
+
tests, writes, or blending also draw the frame uncached: reordering them
|
|
78
|
+
around still casters could change the picture. The ordinary near-mode
|
|
79
|
+
plain-frame guards below still apply. Removing either key, a fallback out
|
|
80
|
+
of near mode, a render throw,
|
|
81
|
+
re-entry, or world disposal frees the extra target, copy geometry and
|
|
82
|
+
material along with the near map. Disposal listeners see resources already
|
|
83
|
+
detached, original caster flags, and the sun's original shadow.
|
|
84
|
+
|
|
85
|
+
- `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
|
|
86
|
+
(the same `engine` object) asks the engine to draw the sun's shadows where
|
|
87
|
+
they can be seen, near the camera, rather than in the sun's fixed box.
|
|
88
|
+
Without it the sun's shadow camera is a fixed 150 x 120 m box round the
|
|
89
|
+
origin, so every caster under the box is drawn a second time each frame
|
|
90
|
+
wherever the player stands, and a scene larger than the box has no shadows
|
|
91
|
+
outside it. The terms:
|
|
92
|
+
> With the key absent, a scene is drawn exactly as before: the same shadow
|
|
93
|
+
> camera, map, `castShadow` flags and render calls. On a frame the mode
|
|
94
|
+
> draws, everything the camera sees within `distance` metres (measured along
|
|
95
|
+
> the way it looks) is shadowed as it would be under a box that covered it,
|
|
96
|
+
> with texels exactly the size the sun's own are and the same softness and
|
|
97
|
+
> bias. Shadows are complete out to `distance` for casters inside the depth
|
|
98
|
+
> range below; a point farther off may or may not be shadowed, and nothing
|
|
99
|
+
> cuts shadows off there.
|
|
100
|
+
|
|
101
|
+
Past `distance` on a frame the mode draws, a point may or may not be
|
|
102
|
+
shadowed (a caster kept for a nearer point shadows farther ones too), and
|
|
103
|
+
past the edge of the mode's box nothing is: three.js leaves a point
|
|
104
|
+
outside the shadow map lit, and the sun's own shadow is not drawn on such
|
|
105
|
+
a frame. Under a fixed camera looking down that edge is off screen.
|
|
106
|
+
|
|
107
|
+
Under the orbit camera key as well (docs/engine-camera.md), which tilts the camera to the
|
|
108
|
+
horizontal where that edge would be a hard line across the ground, a frame
|
|
109
|
+
the mode draws fades the sun's shadow out toward it
|
|
110
|
+
(`engine3d/shadowfade.js`): whole up to 0.75 of the mode's reach (the
|
|
111
|
+
distance it could fit, along the way the camera looks), gone at the reach,
|
|
112
|
+
smoothstep between, to full sun, which is what lies beyond. How:
|
|
113
|
+
> The fade writes no material, not even for a moment, and the scene's,
|
|
114
|
+
> the faded meshes' and the faded materials' own callbacks never meet a
|
|
115
|
+
> variant. What gets one: a material whose class is exactly one of
|
|
116
|
+
> three's own lit ones (standard, physical, lambert, phong, toon; a
|
|
117
|
+
> subclass is not faded), alone on its mesh (a mesh with an array of
|
|
118
|
+
> materials is not faded), whose hooks, listeners and mesh are plain
|
|
119
|
+
> data (read from property descriptors: one behind a deck's accessor is
|
|
120
|
+
> not faded, and the fade never calls a getter), and whose `onBeforeCompile`,
|
|
121
|
+
> `customProgramCacheKey` and `onBeforeRender` are three's own or the
|
|
122
|
+
> kit's (`engine3d/kithooks.js`: look.js, optimize.js,
|
|
123
|
+
> materialpresets.js), on a mesh that receives shadows and has no
|
|
124
|
+
> `onBeforeRender` or `onAfterRender` of its own; and a frame is faded
|
|
125
|
+
> only when the scene has no `onBeforeRender` of its own. Anything else
|
|
126
|
+
> is drawn as it is, unfaded. A variant is a separate material object to
|
|
127
|
+
> the renderer whose every property, read or written, is the original's:
|
|
128
|
+
> its prototype, shared per material class, has a forwarding accessor for
|
|
129
|
+
> each property and accessor of the class, over a proxy that answers
|
|
130
|
+
> anything else from the original; so deck code inside the frame that
|
|
131
|
+
> reaches a variant (an LOD's `update`, a callback installed mid-frame and
|
|
132
|
+
> handed the material three listed) and three's own side flip and version
|
|
133
|
+
> bumps write the original as they would without the key. Its events and
|
|
134
|
+
> `dispose` are the original's too; only the renderer's own dispose
|
|
135
|
+
> listener for the variant's program (known by its function, learned
|
|
136
|
+
> once per renderer by compiling a private material and finishing its
|
|
137
|
+
> program's first-use initialization before disposing it) is held by the
|
|
138
|
+
> variant (and added to
|
|
139
|
+
> the original, where the renderer drawing it would have it), and the
|
|
140
|
+
> variant's program is let go of when the variant is disposed or dropped
|
|
141
|
+
> or the original is disposed (seen by a dispose listener gone from the
|
|
142
|
+
> original, or by the renderer's own entry for the original replaced,
|
|
143
|
+
> when the world's renderer also draws it elsewhere). Its own: an id, that listener, and the
|
|
144
|
+
> shader hooks held as they were when it was made (the held
|
|
145
|
+
> `onBeforeCompile` then the fade; the held key plus
|
|
146
|
+
> `|near-shadow-fade`). Before each faded frame it is drawn in it is
|
|
147
|
+
> dropped if the original has other hooks or is no longer one to fade. A
|
|
148
|
+
> hook the original is given inside a frame is never run for the
|
|
149
|
+
> variant: it compiles with the held hook under a key of its own and is
|
|
150
|
+
> dropped next frame. A property defined on a variant reaches the
|
|
151
|
+
> original after the frame; deck code that compares a variant by
|
|
152
|
+
> identity with its original, asks it `key in` or deletes through it sees
|
|
153
|
+
> another object. The fade's
|
|
154
|
+
> uniform is on the variants only. The variants go on the meshes right
|
|
155
|
+
> before the mode's one render call, and come off in a hook on the world
|
|
156
|
+
> renderer's `shadowMap.render`, which three calls on every render after
|
|
157
|
+
> listing the draws and before drawing any, whatever the shadow
|
|
158
|
+
> settings; the hook comes off when the sun gets its own shadow back,
|
|
159
|
+
> whatever the render did (one a deck replaced meanwhile stays replaced,
|
|
160
|
+
> and ours, if it still calls it, only calls the pass it had). So the
|
|
161
|
+
> frame's own draws use the variants and every render after its list of
|
|
162
|
+
> draws sees the originals. Accepted, inside the keyed world's own frame
|
|
163
|
+
> only: a deck's own sort comparator (`renderer.setOpaqueSort` /
|
|
164
|
+
> `setTransparentSort`) is handed render items holding the variants. A
|
|
165
|
+
> variant not drawn for 60 faded frames is disposed; all are disposed on
|
|
166
|
+
> a scene load, an editor frame, any frame of a scene without both keys
|
|
167
|
+
> and `disposeWorld`. The fade is for the first casting directional
|
|
168
|
+
> light, and a frame is faded only when that is the sun. Not covered: a
|
|
169
|
+
> hook or callback that changes in place an object the original holds by
|
|
170
|
+
> reference (its colour, a texture, its defines) changes it for every
|
|
171
|
+
> world, as it would without the key. A material that is itself a Proxy
|
|
172
|
+
> can observe the fade's reads through its traps. Deck getters with side
|
|
173
|
+
> effects on properties three reads during a render (`isMesh`, `visible`,
|
|
174
|
+
> `children`, `matrixWorld`, `layers`, ...) may run extra times in a
|
|
175
|
+
> faded frame. A mesh whose `material` is not its own writable,
|
|
176
|
+
> configurable data property (read-only, an accessor, or inherited from
|
|
177
|
+
> its prototype) is drawn unfaded, and so is a frame whose
|
|
178
|
+
> renderer's `shadowMap.render` cannot take the hook (it goes on before
|
|
179
|
+
> any variant does). A deck that makes `shadowMap.render` read-only
|
|
180
|
+
> during a keyed frame has it put back (redefined) if it is still
|
|
181
|
+
> configurable; one it also makes non-configurable keeps the fade's
|
|
182
|
+
> hook, inert from then on: it only calls the pass it had. A deck
|
|
183
|
+
> setter on a mesh's `material` that throws when the material is put
|
|
184
|
+
> back holds that mesh, as below. Giving the meshes their materials back is total:
|
|
185
|
+
> each mesh on its own. A deck that redefines or locks its own mesh's
|
|
186
|
+
> `material` during a keyed render gets the best the fade can do without
|
|
187
|
+
> calling its getter: a data property made read-only but configurable
|
|
188
|
+
> is redefined with the deck's attributes and the original's value; an
|
|
189
|
+
> accessor with a setter has the original set through it once; anything
|
|
190
|
+
> else (read-only and not configurable, an accessor without a setter)
|
|
191
|
+
> keeps its variant, which reads and writes the original, and is tried
|
|
192
|
+
> again at every frame boundary while the fade lasts. Once the fade is
|
|
193
|
+
> dropped such a variant is inert: it keys and compiles exactly as its
|
|
194
|
+
> original, so later keyless frames draw the original's program. Its
|
|
195
|
+
> programs are not freed by a later `dispose()` of the original (that
|
|
196
|
+
> would take a listener on the shared material): on such a mesh only,
|
|
197
|
+
> each dispose and recompile leaves one program behind.
|
|
198
|
+
> Two more limits, inside the keyed world's own frame: a variant's
|
|
199
|
+
> properties live on its prototype (the forwarders), so deck code run
|
|
200
|
+
> during that frame (an LOD's `update`, a draw callback) that copies a
|
|
201
|
+
> mesh's material with a spread, `Object.keys` or own-property checks
|
|
202
|
+
> sees none of them, and whatever it writes from that copy differs from
|
|
203
|
+
> without the key (on a material shared with a keyless world, that world
|
|
204
|
+
> draws the write too). And a deck that defines a read-only, non-configurable
|
|
205
|
+
> property on one of three's own material prototypes, then shadows it on
|
|
206
|
+
> a material, makes a read of that property through a variant throw a
|
|
207
|
+
> `TypeError` (the forwarder is a Proxy, which must report the
|
|
208
|
+
> prototype's value). Neither happens in a world without the keys.
|
|
209
|
+
|
|
210
|
+
Without both keys nothing of this runs: the same materials, programs,
|
|
211
|
+
program keys, shader sources and draws as before
|
|
212
|
+
(scripts/test-orbit-shadow-fade.mjs, on three.js's own WebGLRenderer over
|
|
213
|
+
a context that draws nothing, also with a keyed and a keyless world
|
|
214
|
+
sharing materials). Under both keys the first faded frame compiles one
|
|
215
|
+
program per distinct lit program in view (a hitch, once), and each faded
|
|
216
|
+
frame walks the scene's visible objects and swaps each receiving lit
|
|
217
|
+
mesh's material twice, and three reads each variant's properties through
|
|
218
|
+
the forwarders. In node over a context that draws nothing, 500 receiving
|
|
219
|
+
meshes on 40 materials take about 2.7 ms a frame with the fade against
|
|
220
|
+
about 1.8 ms with near shadows alone (the JavaScript side only).
|
|
221
|
+
|
|
222
|
+
The depth range is the sun's own `near` and `far` along the light, measured
|
|
223
|
+
from the engine's shadow camera, which stands as far from the middle of the
|
|
224
|
+
view's sphere (taken along the light to the height of the sun's target) as
|
|
225
|
+
the sun does from its target. For the engine's sun (19.9 m from its target,
|
|
226
|
+
near 0.5, far 50) that is casters up to 19.4 m toward the sun and 30.1 m
|
|
227
|
+
away from it, from the ground under the middle of the view. It is what the
|
|
228
|
+
sun's own camera draws for a view round its target: there too a caster 25 m
|
|
229
|
+
up the light from a point on the ground is not drawn.
|
|
230
|
+
|
|
231
|
+
How it stays out of the scene's way (`engine3d/nearshadows.js` has the rule
|
|
232
|
+
and the code):
|
|
233
|
+
> The scene's sun, its shadow object, its shadow camera, its map and its
|
|
234
|
+
> target are never written by this mode. What the mode needs is its own
|
|
235
|
+
> objects, attached only for the duration of one renderer.render call
|
|
236
|
+
> inside try/finally. Outside that call the world is as main leaves it, so
|
|
237
|
+
> there is nothing to restore on a scene change, a throw, a dispose or a
|
|
238
|
+
> keyless frame.
|
|
239
|
+
|
|
240
|
+
Who the key is for:
|
|
241
|
+
> The key is for a scene whose deck leaves the renderer's shadow settings
|
|
242
|
+
> and the drawing of the world to the engine. A deck must not set the key if
|
|
243
|
+
> any of its code, in any scene played in the same world, changes
|
|
244
|
+
> renderer.shadowMap.type, .enabled, .autoUpdate or .needsUpdate after the
|
|
245
|
+
> world is made; calls renderer.render or the composer itself, inside or
|
|
246
|
+
> between the engine's frames; calls renderWorld from inside a frame; or
|
|
247
|
+
> gives the world's renderer to another world. In a deck that does, shadows
|
|
248
|
+
> may be drawn wrongly with the key, and three.js's shadow bookkeeping for
|
|
249
|
+
> the sun's own map (its filter, its size) may differ from a world that
|
|
250
|
+
> never had the key until the world is disposed. A deck that never sets the
|
|
251
|
+
> key is unaffected whatever it does.
|
|
252
|
+
|
|
253
|
+
(three.js keeps the shadow pass's state, the type it last drew with and the
|
|
254
|
+
frustum it culls by, inside the renderer, where the engine can neither read
|
|
255
|
+
it nor put it back. Nothing in the kits does any of the above after
|
|
256
|
+
`makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
|
|
257
|
+
(With the orbit key as well, the far-edge fade below puts a hook on the
|
|
258
|
+
world renderer's `shadowMap.render` for the one render call, and takes
|
|
259
|
+
it off after. The opt-in still cache above also hooks that call.)
|
|
260
|
+
|
|
261
|
+
Within that, the mode draws a frame only when all of these hold; otherwise
|
|
262
|
+
the frame is drawn exactly as without the key. They are cheap protection,
|
|
263
|
+
looked at every frame, not promises about a deck outside the condition
|
|
264
|
+
above. After any `renderWorld` call returns, either the mode drew that
|
|
265
|
+
frame or nothing of the mode's is allocated: every way out of the mode (a
|
|
266
|
+
frame drawn plain for any term, a re-entry, a throw, a dispose) frees its
|
|
267
|
+
map at that moment:
|
|
268
|
+
1. the scene now playing asked, with a finite distance above 0
|
|
269
|
+
(`runtime.nearShadowDistance`, read when the scene loads), the frame is
|
|
270
|
+
the player's (the scene and model editors give `renderWorld` no runtime),
|
|
271
|
+
and the world is not being disposed;
|
|
272
|
+
2. `renderWorld` was not entered from inside another `renderWorld` of this
|
|
273
|
+
world that had anything of the mode's to do, keyed or not, and no frame
|
|
274
|
+
of this world has been entered that way before. The call inside is drawn
|
|
275
|
+
plain; the sun has its own shadow back before that call draws, and still
|
|
276
|
+
has it when the call returns, whatever the call did, disposing the world
|
|
277
|
+
included; the mode is off for this world from then until the world is
|
|
278
|
+
disposed (`world.nearShadows.off`); and the frame that was re-entered,
|
|
279
|
+
whose map is freed under it, may have wrong or missing shadows, that
|
|
280
|
+
once;
|
|
281
|
+
3. read at the start of the frame, `renderer.shadowMap.type` is
|
|
282
|
+
`PCFSoftShadowMap` and `.enabled` and `.autoUpdate` are on, which is how
|
|
283
|
+
the engine makes the renderer; and the frame before was also a frame
|
|
284
|
+
with the key that found the same and was drawn to the end
|
|
285
|
+
(`world.nearShadows.lastType`). So the first frame with the key, after a
|
|
286
|
+
load or after any frame without it, is drawn plain, and three.js
|
|
287
|
+
allocates and configures the sun's own map as it would have; and so is
|
|
288
|
+
the frame after one that threw, and after one the mode drew that ended
|
|
289
|
+
with no map on the engine's shadow (three.js drew nothing: a lost
|
|
290
|
+
context). The engine's shadow never has a blur map;
|
|
291
|
+
4. the sun (`world.sun`, the light whose bias the engine fits) is still a
|
|
292
|
+
child of the scene, is the first directional light there that casts, has
|
|
293
|
+
`castShadow` on, is visible and on the camera's layers, and its own
|
|
294
|
+
shadow is a directional light's, has `autoUpdate` on and has its map.
|
|
295
|
+
Looked at every frame: a sun removed or replaced means plain frames, in
|
|
296
|
+
which a replacement draws its own box as without the key;
|
|
297
|
+
5. the camera is a perspective camera, and the sun's own box and map size
|
|
298
|
+
give a texel size: its shadow camera has zoom 1 and no view offset.
|
|
299
|
+
|
|
300
|
+
All of the mode's work in a `renderWorld` call (deciding the terms, fitting
|
|
301
|
+
the bias, allocating, swapping, rendering, leaving, disposing) happens
|
|
302
|
+
inside one outermost try/finally, counted on the world
|
|
303
|
+
(`world.nearShadows.depth`). A call that arrives while the count is up
|
|
304
|
+
draws plain, puts the mode off and makes nothing. The finally establishes
|
|
305
|
+
the postcondition itself: unless the mode drew this frame to the end, on a
|
|
306
|
+
world not disposed, with the mode not off and a map on its shadow, nothing
|
|
307
|
+
of the mode's is allocated and the sun has its own shadow. Its order is
|
|
308
|
+
what makes that hold through a `dispose` listener that throws: first the
|
|
309
|
+
sun gets its own shadow back (an assignment, which calls no one), then what
|
|
310
|
+
is freed is detached and only then disposed, and looked at again after the
|
|
311
|
+
callbacks; the count comes down in a finally of its own that nothing skips.
|
|
312
|
+
A world with no mode state playing a scene without the key does not enter
|
|
313
|
+
any of it: `renderWorld` runs its two statements (fit the bias, render)
|
|
314
|
+
with no counter and no try, as it always did.
|
|
315
|
+
|
|
316
|
+
On such a frame `renderWorld` fits the bias of the sun's own shadow as
|
|
317
|
+
always, puts the engine's shadow on the sun (`sun.shadow`), renders, and
|
|
318
|
+
puts the sun's own back in a `finally`; that assignment is the only write,
|
|
319
|
+
and it is undone only by the frame that made it (a frame that finds the
|
|
320
|
+
world disposed, its state replaced or itself re-entered touches nothing).
|
|
321
|
+
three.js keeps nothing per shadow object (the shadow pass and the light
|
|
322
|
+
uniforms read `light.shadow` afresh every render), so the next plain render
|
|
323
|
+
reads the sun's own as if nothing had happened. The engine's shadow
|
|
324
|
+
(`world.nearShadows.shadow`, a DirectionalLightShadow with its own camera,
|
|
325
|
+
map, matrix and frustum), each frame:
|
|
326
|
+
- looks along the sun's direction, from as far as the sun is from its
|
|
327
|
+
target, with the sun's own near and far, round the smallest sphere that
|
|
328
|
+
holds the camera's view out to `distance`: one size whichever way the
|
|
329
|
+
camera turns (it changes only with the canvas's shape or the camera's
|
|
330
|
+
lens). It sits a whole number of texels along each of its axes, so a
|
|
331
|
+
shadow's edge does not crawl as the camera moves. The light does not move;
|
|
332
|
+
- has texels exactly the size of the sun's own (the sun's box over its map
|
|
333
|
+
size, read each frame), so its box is `map size x texel` and it copies the
|
|
334
|
+
bias `fitShadowBias` fitted to the sun's own, with its intensity and
|
|
335
|
+
radius: 40 m on a portrait phone is a 710 x 888 map. Its map is never
|
|
336
|
+
larger than the sun's own in area (2048 x 2048) nor than the renderer's
|
|
337
|
+
largest texture on a side; a `distance` that would need more is drawn as
|
|
338
|
+
the largest that fits (about 100 m in portrait, 38 m at 32:9) rather than
|
|
339
|
+
with larger texels;
|
|
340
|
+
- hands three.js a frustum to cull casters with (`getFrustum`) that is its
|
|
341
|
+
box narrowed to the view's outline, out to `distance`, as the sun sees it,
|
|
342
|
+
pushed out by everything three.js's shader moves a shadow lookup by across
|
|
343
|
+
the light: the normal bias drawn with that frame (the lookup is made at
|
|
344
|
+
`position + normal * normalBias`) and four texels for the soft filter's
|
|
345
|
+
taps. The box is wider by the same. Every caster whose shadow
|
|
346
|
+
can land on something the view sees within `distance` is drawn into the
|
|
347
|
+
map; one whose shadow cannot is not. Without `cacheStill`, no
|
|
348
|
+
`castShadow` flag is changed and nothing is cached: every caster that
|
|
349
|
+
is drawn is drawn every frame, so a moving thing's shadow moves with it
|
|
350
|
+
as before.
|
|
351
|
+
|
|
352
|
+
A frame without the key drops what the mode holds, all but `off`;
|
|
353
|
+
`disposeWorld` drops it all. The engine's map (and a blur map, were there
|
|
354
|
+
one) is taken off its shadow before it is disposed, once.
|
|
355
|
+
|
|
356
|
+
What a deck that works on the sun sees under the key: the sun's own
|
|
357
|
+
`shadow.camera` box, `mapSize` and any `getFrustum` of its own are left as
|
|
358
|
+
they are and not used for drawing on the frames the mode draws (a sun whose
|
|
359
|
+
`shadow.autoUpdate` the deck turned off gets plain frames, term 4),
|
|
360
|
+
except that the box over the map size gives the texel size and `near`/`far`,
|
|
361
|
+
`bias`, `normalBias`, `intensity` and `radius` are copied each frame;
|
|
362
|
+
three.js does not draw the sun's own shadow on those frames, so its map and
|
|
363
|
+
its shadow camera's matrices stay as the last plain frame left them; a sun
|
|
364
|
+
moved or re-aimed is followed (its direction is read each frame). Without
|
|
365
|
+
the key such a deck works exactly as before. What differs on screen with
|
|
366
|
+
the key: shadows no longer end at the fixed box's edge, so a scene larger
|
|
367
|
+
than that box gains shadows where it had none; beyond `distance` from the
|
|
368
|
+
camera they thin out and, past the engine's box (which reaches somewhat
|
|
369
|
+
farther than `distance`), end, with a hard edge if the camera can see that
|
|
370
|
+
far (pick a distance past the ground the camera can see). Opt in when a
|
|
371
|
+
scene is wide enough that most of its casters are out of sight; a scene
|
|
372
|
+
that fits the view gains nothing.
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# Scene keys: engine.skipEmptyGaitHints, skipUnchangedActors, dropEmptyParts, skipEmptyNodes
|
|
2
|
+
|
|
3
|
+
The physics-3d kit's CLAUDE.md Quick reference points here. The keys sit in
|
|
4
|
+
the `engine` object at a scene file's top level, beside `ground`.
|
|
5
|
+
|
|
6
|
+
- `"engine": { "skipEmptyGaitHints": true }` skips clock reads and hint
|
|
7
|
+
consumption when an actor node has none of `walkSpeedHint`, `walkTimeHint`,
|
|
8
|
+
or `walkHintAt`. It applies only in play, with model gait; the editor and
|
|
9
|
+
scenes without the key retain the original path. Hint-bearing nodes keep
|
|
10
|
+
their original freshness checks and one-frame consumption. Under this key,
|
|
11
|
+
node `userData` must be ordinary stored data, without accessors or Proxies.
|
|
12
|
+
- `"engine": { "skipUnchangedActors": true }` at the scene file's top level,
|
|
13
|
+
beside `ground`, asks the engine not to redo, every frame, work whose answer
|
|
14
|
+
cannot have changed. The terms:
|
|
15
|
+
> With the key absent, a scene runs the engine exactly as before. With the key
|
|
16
|
+
> present, each frame equals what the engine would have produced without it
|
|
17
|
+
> PROVIDED the scene's components are plain stored data (no accessors, Proxies,
|
|
18
|
+
> toJSON, custom iterators) and three.js objects under actors are changed only
|
|
19
|
+
> through position/rotation/quaternion/scale/visible/parenting. A scene that does
|
|
20
|
+
> not meet that is unsupported under the key and must not set it.
|
|
21
|
+
|
|
22
|
+
It is read when the scene loads, so it follows a scene switch, and a mounted
|
|
23
|
+
pack's scene decides for itself. What is skipped for an actor nothing has
|
|
24
|
+
touched: building the signatures that decide whether its mesh and its
|
|
25
|
+
physics body need rebuilding, recomputing its node's matrices, and sorting
|
|
26
|
+
the actor list. Behaviors run exactly as without the key. Each skipped piece
|
|
27
|
+
is skipped only after reading its inputs and finding them as they were, so
|
|
28
|
+
nothing has to be marked dirty: an actor still follows a change on the very
|
|
29
|
+
next frame -- a component's stored field written in place, a component
|
|
30
|
+
added, removed or replaced, a spawn or despawn, physics, the editor, the
|
|
31
|
+
network, its node posed from `scene.three`. Opt in when a scene is several
|
|
32
|
+
hundred actors that mostly stand still and frame time on a slow phone is
|
|
33
|
+
script, not drawing; a small scene gains nothing.
|
|
34
|
+
How it stays right when deck code runs in the middle of the engine's own
|
|
35
|
+
work (`engine3d/world3d.js` has the rule and the code):
|
|
36
|
+
> Fast-path state (snapshots, pass marks, cached signatures) is trusted only
|
|
37
|
+
> across a span in which no code outside the engine has run. A pass in which
|
|
38
|
+
> the engine calls out (any callback), is re-entered, or sees the scene
|
|
39
|
+
> change, finishes exactly as main would and leaves no fast-path state
|
|
40
|
+
> behind.
|
|
41
|
+
|
|
42
|
+
The engine moves a counter before it does anything, inside a pass over the
|
|
43
|
+
actors, that can run code that is not its own; it does not work out
|
|
44
|
+
afterwards whether something ran. The places, all of them:
|
|
45
|
+
`scene.three.scene.userData.groundHeight`, called while a walking model is
|
|
46
|
+
animated; and three.js listeners (`added`, `removed`, `childadded`,
|
|
47
|
+
`childremoved`, `dispose`) on the scene, a node, a geometry or a material,
|
|
48
|
+
told when a node is built, rebuilt or released, when the scene changes, when
|
|
49
|
+
the ground is dressed anew, and when an instanced mesh is replaced; and
|
|
50
|
+
`syncActors` called again from inside any of those. From that point the
|
|
51
|
+
pass does each actor the old way and writes nothing down, and when it ends,
|
|
52
|
+
or if it throws, everything written down before is dropped. So:
|
|
53
|
+
- a frame in which any actor's mesh is built, rebuilt or released costs what
|
|
54
|
+
it costs without the key, and the frame after it reads every actor once
|
|
55
|
+
more before skipping resumes;
|
|
56
|
+
- a scene with a `groundHeight` callback, or with `instanceModels` on, runs
|
|
57
|
+
every pass the old way and keeps only the matrix saving;
|
|
58
|
+
- the physics pass calls nothing outside the engine until its collision
|
|
59
|
+
callbacks, which come last;
|
|
60
|
+
- a component nested more than 32 levels deep is compared the old way every
|
|
61
|
+
frame.
|
|
62
|
+
|
|
63
|
+
What is written down lives in the world's own maps (`world.snapshots`,
|
|
64
|
+
`world.modelSigs`) and in the physics system's (`remembered`), never on a
|
|
65
|
+
node entry or a body entry, and is dropped by replacing or clearing those.
|
|
66
|
+
The one thing on a node, an ActorNode's `computedFrom`, is numbers only and
|
|
67
|
+
refers to no object.
|
|
68
|
+
A world being disposed never skips: `disposeWorld` drops what was written
|
|
69
|
+
down before it releases the nodes and again after their `dispose` listeners
|
|
70
|
+
have run, so a listener that syncs the world again leaves nothing.
|
|
71
|
+
- Within the terms, these are followed: any stored field of a Shape, Model,
|
|
72
|
+
Body or Transform changed, added, removed or reordered, at any depth; art
|
|
73
|
+
loading or being replaced; a model file, or a model it references, edited;
|
|
74
|
+
a node's, or any object under it's, position, rotation (angles or order),
|
|
75
|
+
quaternion, scale or visibility set; children added, removed, reordered,
|
|
76
|
+
or moved to another parent and back; a body's type changed through
|
|
77
|
+
`scene.physics3d.bodyOf`.
|
|
78
|
+
- Outside the terms the result is not promised. The engine does notice some
|
|
79
|
+
of it and then does the old work for that actor, as protection, not as a
|
|
80
|
+
guarantee to build on: a component with an accessor, a `toJSON` or a class
|
|
81
|
+
of its own found when it is first read; an object under a node with
|
|
82
|
+
`matrixAutoUpdate` off or an `updateMatrixWorld` of its own (a camera, a
|
|
83
|
+
skinned mesh); a world matrix written by hand; a transform changed, used
|
|
84
|
+
and put back between frames.
|
|
85
|
+
- It does not notice, among others: a `Proxy` in place of a component, of
|
|
86
|
+
`actor.components` or of the `sprites` / `files` tables; a getter on
|
|
87
|
+
`Transform`, on `Shape.solid`, or on `actor.components` itself; a stored
|
|
88
|
+
field redefined as a getter after the engine has read it; an object's
|
|
89
|
+
local `matrix` written by hand while its `matrixAutoUpdate` is on (set
|
|
90
|
+
`position` / `quaternion` / `scale` instead); three.js private fields
|
|
91
|
+
written directly (`rotation._order`, `quaternion._x`).
|
|
92
|
+
- `"engine": { "dropEmptyParts": true }` at the scene file's top level (the
|
|
93
|
+
same `engine` object) asks the engine to place models without the groups
|
|
94
|
+
that draw nothing. A placed model is a game build: its meshes are merged
|
|
95
|
+
into a few draw calls, but every part keeps its own three.js group, most of
|
|
96
|
+
them then empty, and three.js and the engine visit every object under the
|
|
97
|
+
scene on every frame. A town of a few hundred models is two thirds such
|
|
98
|
+
groups. The terms:
|
|
99
|
+
> With the key absent, a model is built and placed exactly as before: the
|
|
100
|
+
> same objects, the same shared build, the same node. With the key present,
|
|
101
|
+
> every object that is drawn (a mesh, its outline, anything that is not a
|
|
102
|
+
> plain group) is the same object with the same geometry, material and
|
|
103
|
+
> world matrix as without it, on every frame, and walks, `motion`, clips and
|
|
104
|
+
> glow play the same. What a deck must not rely on under the key is finding
|
|
105
|
+
> the group of a part that draws nothing unless that part is one that
|
|
106
|
+
> stays.
|
|
107
|
+
|
|
108
|
+
What goes: a group with nothing drawn on it or anywhere under it -- no
|
|
109
|
+
mesh, line, points, sprite, light or camera. That includes the group of a
|
|
110
|
+
part that IS drawn when its mesh was merged into a batch on the model's
|
|
111
|
+
root or on a moving part: the picture keeps the part, `modelParts` does
|
|
112
|
+
not. What always stays, with every group above it:
|
|
113
|
+
- a part marked `keep: true` (docs/pxmodel-format.md: "for a deck that
|
|
114
|
+
reaches for it by id"), with its own mesh as before;
|
|
115
|
+
- a part named `slot-...`. The format's docs let a deck "parent your own
|
|
116
|
+
parts to it", and nothing says that happens only in the model file, so a
|
|
117
|
+
slot is never dropped: a deck may hang a mesh on one at runtime and it is
|
|
118
|
+
drawn where it would be without the key;
|
|
119
|
+
- a part the walk moves (`legL`, `legR`, `armL`, `armR`, `torso`) or the
|
|
120
|
+
model's `motion`, gait or `clips` move, drawn or not, and every copy of
|
|
121
|
+
one;
|
|
122
|
+
- anything a kept part or slot holds that is not another part.
|
|
123
|
+
|
|
124
|
+
An actor whose model draws nothing at all (an invisible collider placing an
|
|
125
|
+
empty model) gets no rig group under its node: the node is there, with
|
|
126
|
+
`userData.modelParts` an empty Map and no children.
|
|
127
|
+
So under the key:
|
|
128
|
+
- `scene.three.nodes.get(id).node.userData.modelParts` holds only the parts
|
|
129
|
+
that stayed. `modelParts.get('door')` for a part that draws nothing and
|
|
130
|
+
is none of the above is `undefined`, where without the key it is an empty
|
|
131
|
+
group. To reach for an empty part as a locator (a muzzle, a hand), mark
|
|
132
|
+
it `keep: true` or name it `slot-...`; it then stands exactly where it
|
|
133
|
+
did.
|
|
134
|
+
- code that walks a node's tree counts fewer objects, and a node's first
|
|
135
|
+
child is its rig only when its model draws something.
|
|
136
|
+
- nothing else changes: which actors have nodes, `userData.actorId`, the
|
|
137
|
+
rig's `yOffset` and `scale`, physics, picking, shadows (casters are
|
|
138
|
+
culled by their own meshes' bounds), `instanceModels`.
|
|
139
|
+
|
|
140
|
+
It is read when the scene loads, as `skipUnchangedActors` is, and each
|
|
141
|
+
scene decides for itself: a node and a shared model build made for a scene
|
|
142
|
+
that asked are never used for one that did not, or the other way round (a
|
|
143
|
+
resident scene parked while another plays, a pack mounted in a town, a door
|
|
144
|
+
trip, a scene file reloaded with the key changed -- every node is then
|
|
145
|
+
built again). The scene editor and the play panel draw a scene through the
|
|
146
|
+
same engine, so both follow the scene's key; the editor selects actors, not
|
|
147
|
+
parts, and is not affected. The model editor and `npm run render` build a
|
|
148
|
+
model for themselves, with every part's group, whatever any scene says.
|
|
149
|
+
Opt in with `skipUnchangedActors` when a scene is hundreds of placed
|
|
150
|
+
models; a scene of a few gains nothing.
|
|
151
|
+
- `"engine": { "skipEmptyNodes": true }` at the scene file's top level
|
|
152
|
+
keeps an actor with no children on its three.js node outside the play scene.
|
|
153
|
+
Empty markers, anchors and triggers then cost no scene object. A missing or
|
|
154
|
+
invalid Model with no Shape is empty; a Model that builds a rig is not,
|
|
155
|
+
even if its rig draws nothing. With `dropEmptyParts`, a model reduced to no
|
|
156
|
+
rig is empty too. The key is read on load, and only exactly `true` opts in.
|
|
157
|
+
Without it, nodes, signatures and shared model caches are exactly as before.
|
|
158
|
+
A player whose scenes never ask creates no mode record, system or listeners.
|
|
159
|
+
The player arms the mode only
|
|
160
|
+
after a keyed scene has finished loading; syncs never arm it. The scene
|
|
161
|
+
editor always keeps its nodes.
|
|
162
|
+
|
|
163
|
+
`scene.three.nodes` keeps every entry and its usual Group/ActorNode, with
|
|
164
|
+
position, rotation and world matrix placed by the engine even while detached.
|
|
165
|
+
Move an empty actor through its Transform (or physics), not by writing the
|
|
166
|
+
detached node's position, quaternion, rotation or scale directly: those
|
|
167
|
+
writes are outside this key's contract and do not update its world matrix
|
|
168
|
+
until the node has a child and is attached again.
|
|
169
|
+
No transform properties or methods are wrapped. Adding a
|
|
170
|
+
child queues attachment at the next actor sync; removing its last child
|
|
171
|
+
queues detachment there too, after three.js event dispatch completes.
|
|
172
|
+
Build and child events queue classification for the next outermost sync;
|
|
173
|
+
listeners only mark dirty, and syncs inside event dispatch defer the queue.
|
|
174
|
+
Dispatch depth unwinds even if a listener throws. A load, reset or disposal
|
|
175
|
+
invalidating a pass aborts it before any further placement or attachment.
|
|
176
|
+
Settled frames scan no nodes.
|
|
177
|
+
Only detached empty nodes whose pose changes receive a matrix update; a
|
|
178
|
+
settled static empty actor needs none. Load/reset gives nodes back before
|
|
179
|
+
the next scene runs, leaving keyless sync on its original path.
|
|
180
|
+
Gaining or losing a Model/Shape follows the usual look rebuild, including
|
|
181
|
+
spawn, reload, resident scenes and `staticActors` (call `scene.touch` before
|
|
182
|
+
changing a static actor, as usual). A node deliberately hidden or reparented
|
|
183
|
+
by a consumer stays under that consumer's control. Low-tier bounds and
|
|
184
|
+
hiding, avatar parts and attachments keep using the same entries. Traversing
|
|
185
|
+
the play scene excludes empty actors; traverse `scene.three.nodes` to find
|
|
186
|
+
all actors. If the scene itself has a transform or a parent, nodes stay
|
|
187
|
+
attached so world-space reads retain that transform.
|