castle-web-cli 0.4.233 → 0.4.235
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/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 +17 -2
- package/dist/castle-host/host.js +793 -36
- package/dist/castleJson.d.ts +20 -1
- package/dist/castleJson.js +44 -2
- package/dist/check.js +9 -2
- 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 +3 -1
- 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/index.js +8 -2
- package/dist/init.js +1 -1
- package/dist/save-deck.d.ts +20 -1
- package/dist/save-deck.js +141 -5
- package/dist/serve.js +29 -11
- package/dist/shell/assets/{index-BjOxR-lW.js → index-DulbYIJm.js} +97 -97
- package/dist/shell/index.html +1 -1
- package/dist/vitePlugins.d.ts +2 -1
- package/dist/vitePlugins.js +13 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +266 -3
- package/kits/base/sdk/castle.d.ts +7 -3
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +162 -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 +33 -6
- package/kits/base/sdk/hub.js +68 -5
- package/kits/base/sdk/hubRejoin.d.ts +4 -0
- package/kits/base/sdk/hubRejoin.js +15 -0
- package/kits/base/sdk/multiplayer.d.ts +7 -1
- package/kits/base/sdk/multiplayer.js +147 -40
- 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 +79 -6
- package/kits/base/sdk/server/hub.d.ts +31 -1
- package/kits/base/sdk/server/hub.js +50 -3
- package/kits/base/sdk/server/platformHandle.d.ts +13 -1
- package/kits/base/sdk/server/storage.d.ts +4 -0
- package/kits/base/sdk/server/storage.js +19 -3
- package/kits/base/sdk/server/wrapper.d.ts +7 -1
- package/kits/base/sdk/server/wrapper.js +10 -1
- package/kits/base/sdk/social.d.ts +9 -0
- package/kits/base/sdk/social.js +5 -0
- package/kits/hub-game/CLAUDE.md +123 -3
- package/kits/hub-game/README.md +63 -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/arrivalCamera.js +50 -0
- package/kits/hub-game/code/client/askSlot.js +117 -0
- package/kits/hub-game/code/client/avatar.js +4 -2
- package/kits/hub-game/code/client/avatarShare.js +2 -0
- package/kits/hub-game/code/client/backVisibility.js +13 -0
- package/kits/hub-game/code/client/ballot.js +15 -10
- package/kits/hub-game/code/client/build.js +16 -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 +1148 -258
- package/kits/hub-game/code/client/crowdNames.js +241 -0
- package/kits/hub-game/code/client/decor.js +10 -4
- 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/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 +31 -11
- package/kits/hub-game/code/client/hookLayer.js +87 -8
- 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 +14 -2
- 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/labelsNear.js +31 -2
- 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/menuRows.js +43 -0
- package/kits/hub-game/code/client/modelReady.js +7 -0
- 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/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 +64 -10
- 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/state.js +53 -0
- package/kits/hub-game/code/client/talk.js +209 -45
- package/kits/hub-game/code/client/tiers.js +68 -66
- package/kits/hub-game/code/client/together.js +7 -2
- 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/worldLabels.js +241 -0
- package/kits/hub-game/code/client/yours.js +10 -9
- package/kits/hub-game/code/npcDisplayText.js +55 -0
- package/kits/hub-game/code/server/act.js +124 -0
- package/kits/hub-game/code/server/actions.js +6 -1
- package/kits/hub-game/code/server/actors.js +2 -1
- 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/companion.js +28 -3
- package/kits/hub-game/code/server/doorAnalytics.js +52 -0
- package/kits/hub-game/code/server/earned.js +22 -5
- package/kits/hub-game/code/server/frameBatch.js +183 -0
- package/kits/hub-game/code/server/friendsAmong.js +49 -9
- package/kits/hub-game/code/server/history.js +2 -0
- package/kits/hub-game/code/server/hub.js +1306 -95
- package/kits/hub-game/code/server/idle.js +30 -1
- package/kits/hub-game/code/server/index.js +26 -4
- package/kits/hub-game/code/server/invites.js +19 -0
- package/kits/hub-game/code/server/labels.js +9 -1
- package/kits/hub-game/code/server/loadAbandon.js +106 -0
- package/kits/hub-game/code/server/manifest.js +211 -3
- package/kits/hub-game/code/server/menu.js +31 -3
- package/kits/hub-game/code/server/npcs.js +226 -64
- 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/players.js +9 -1
- 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/standing.js +4 -5
- package/kits/hub-game/code/server/storageLimit.js +187 -0
- package/kits/hub-game/code/server/vis.js +67 -5
- package/kits/hub-game/code/shared/act.js +35 -0
- package/kits/hub-game/code/shared/danceIdle.js +28 -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 +35 -1
- package/kits/hub-game/code/systems/hub.js +970 -169
- package/kits/hub-game/docs/analytics.md +279 -0
- package/kits/hub-game/docs/contract.md +1259 -42
- package/kits/hub-game/docs/home-pieces.md +9 -2
- package/kits/hub-game/docs/observed-progress.md +252 -0
- package/kits/hub-game/main.jsx +2 -0
- package/kits/hub-game/package-lock.json +10 -3
- package/kits/hub-game/package.json +6 -3
- 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 +39 -5
- package/kits/hub-game/scripts/companion-follower-wire.json +1 -1
- package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +11 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless.json +5 -5
- package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +3 -0
- package/kits/hub-game/scripts/fixtures/fake-dom.mjs +19 -3
- package/kits/hub-game/scripts/fixtures/interest-legacy.json +3 -3
- package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -1
- package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -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 +367 -2
- package/kits/hub-game/scripts/test-actors.mjs +20 -7
- 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-slot.mjs +85 -0
- package/kits/hub-game/scripts/test-avatar-wire.mjs +49 -10
- package/kits/hub-game/scripts/test-avatar.mjs +44 -0
- package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
- package/kits/hub-game/scripts/test-ballot.mjs +11 -4
- package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
- package/kits/hub-game/scripts/test-build.mjs +20 -2
- package/kits/hub-game/scripts/test-chat.mjs +206 -5
- package/kits/hub-game/scripts/test-companion-chat.mjs +20 -2
- 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 +45 -4
- package/kits/hub-game/scripts/test-decor.mjs +7 -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.mjs +33 -3
- 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-grab-orbit.mjs +47 -4
- package/kits/hub-game/scripts/test-high-only.mjs +170 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +321 -2
- package/kits/hub-game/scripts/test-hub-trip.mjs +879 -11
- package/kits/hub-game/scripts/test-hud-clear.mjs +162 -59
- 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 +66 -0
- package/kits/hub-game/scripts/test-interest-cells.mjs +20 -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-labels.mjs +71 -3
- 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 +265 -0
- package/kits/hub-game/scripts/test-menu-client.mjs +105 -0
- package/kits/hub-game/scripts/test-menu.mjs +23 -0
- package/kits/hub-game/scripts/test-npcs.mjs +917 -10
- package/kits/hub-game/scripts/test-observed.mjs +745 -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 +234 -7
- 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 +699 -5
- 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 +145 -0
- package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
- package/kits/hub-game/scripts/test-soundscape.mjs +22 -17
- package/kits/hub-game/scripts/test-standing.mjs +35 -2
- package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
- package/kits/hub-game/scripts/test-stuck.mjs +5 -4
- package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
- package/kits/hub-game/scripts/test-tiers-render.mjs +86 -13
- package/kits/hub-game/scripts/test-tiers.mjs +7 -8
- package/kits/hub-game/scripts/test-vis.mjs +433 -6
- 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 +50 -6
- package/kits/hub-game/scripts/test-yours.mjs +39 -8
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
- package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
- package/kits/multiplayer-3d/code/systems/multiplayer.js +369 -30
- package/kits/multiplayer-3d/package-lock.json +8 -1
- package/kits/multiplayer-3d/package.json +2 -1
- package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
- package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
- package/kits/physics-2d/CLAUDE.md +10 -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 +87 -5
- 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-3d/CLAUDE.md +25 -1651
- 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 +35 -18
- 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 +1 -1
- package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -333
- package/kits/physics-3d/engine3d/actornode.js +1 -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/framecap.js +4 -1
- 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 +8 -0
- package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
- package/kits/physics-3d/engine3d/look.js +7 -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 +3 -3
- package/kits/physics-3d/engine3d/nearshadows.js +77 -10
- package/kits/physics-3d/engine3d/orbitinput.js +59 -25
- 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 +3 -3
- 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 +23 -15
- package/kits/physics-3d/engine3d/sky.js +1 -1
- 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/world3d.js +468 -18
- package/kits/physics-3d/eslint.config.js +2 -1
- package/kits/physics-3d/main.jsx +6 -3
- 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/test-camera-follow.mjs +5 -1
- package/kits/physics-3d/scripts/test-camera-orbit.mjs +52 -4
- package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
- package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
- package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +6 -3
- package/kits/physics-3d/scripts/test-frame-cap.mjs +1 -1
- 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-look-bake.mjs +1 -1
- package/kits/physics-3d/scripts/test-near-shadows.mjs +2 -2
- package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +88 -7
- package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +40 -3
- package/kits/physics-3d/scripts/test-orbit-shot.mjs +75 -1
- package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
- package/kits/physics-3d/scripts/test-sky.mjs +1 -1
- package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +3 -1
- package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
- package/kits/physics-3d/scripts/test-static-scenery.mjs +5 -2
- package/kits/physics-3d/scripts/test-steady-hover.mjs +5 -2
- package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
- package/kits/physics-3d/systems/physics3d.js +37 -4
- 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/session.js +6 -4
- package/kits/real-time/package-lock.json +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Scene key: engine.sky
|
|
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": { "sky": { ... } }` at the scene file's top level (the same
|
|
7
|
+
`engine` object) asks the engine to draw a sky behind everything: the sky of
|
|
8
|
+
the zone the player stands in, turning into the next zone's when they walk
|
|
9
|
+
into it. Without it the engine clears to black, and a camera that looks
|
|
10
|
+
above the horizon looks into black.
|
|
11
|
+
|
|
12
|
+
```jsonc
|
|
13
|
+
"sky": {
|
|
14
|
+
"fade": 1.5, // optional: seconds one zone's sky takes to turn into another's (above 0, at most 10)
|
|
15
|
+
"edge": 0.75, // optional: metres past a zone's box a player is still in it (0 to 10)
|
|
16
|
+
"below": 8, // optional: degrees under the horizon an image's last row is (0 to 45)
|
|
17
|
+
"zones": [ // 1 to 16; exactly one has no box
|
|
18
|
+
{ "id": "square", "color": "#bfe3f2", "art": "drawings/sky-square.webp" },
|
|
19
|
+
{ "id": "hollow", "color": "#3d3a5c", "art": "drawings/sky-hollow.webp", "box": [-95, -17, -17, 17] }
|
|
20
|
+
]
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
The terms:
|
|
25
|
+
> With the key absent, a scene is drawn exactly as before: the same scene
|
|
26
|
+
> graph, the same render calls, the same clear to black; nothing of the
|
|
27
|
+
> sky's is made. With the key present, every pixel no opaque thing covers is
|
|
28
|
+
> the sky of one zone, or of two while one turns into the other, and
|
|
29
|
+
> everything else is drawn as it would be without the key: the sky is not
|
|
30
|
+
> lit, casts and takes no shadow, is not an actor, and is in the scene graph
|
|
31
|
+
> only while a frame of its scene is being drawn.
|
|
32
|
+
|
|
33
|
+
A zone is `id`, `color` (`#rrggbb`), optionally `art` and optionally `box`
|
|
34
|
+
(`[x0, z0, x1, z1]`, metres). The zone with no box is the sky of a point in
|
|
35
|
+
no box; a point in two boxes is in the one listed first.
|
|
36
|
+
|
|
37
|
+
**The shape is exact** (`physics-2d` `engine/skyKey.js` reads it at each
|
|
38
|
+
scene load). A key it does not name, a number out of range, a colour that is
|
|
39
|
+
not six hex digits, two zones with one id, no zone without a box or more
|
|
40
|
+
than one: the scene has no sky, the key reads as absent, and the console
|
|
41
|
+
gets one warning that says what was wrong. So a scene written for a later
|
|
42
|
+
engine that knows more keys has no sky on this one, rather than half of one.
|
|
43
|
+
|
|
44
|
+
**A zone's picture** is a deck image (png, jpg, webp: `art` is its path in
|
|
45
|
+
the deck). It enters through the bundler like every deck image and is a
|
|
46
|
+
`data:` URI in a published deck; nothing is fetched. Across, it is the
|
|
47
|
+
bearing: north (-z) at the left edge, east (+x) a quarter of the way along,
|
|
48
|
+
its right edge meeting its left. Down, it is the height: straight overhead
|
|
49
|
+
in the first row, `below` degrees under the horizon in the last, and the
|
|
50
|
+
last row again below that. So the first row is one point of the sky and
|
|
51
|
+
should be one colour. It is drawn with linear filtering and no smaller
|
|
52
|
+
copies, as the whole sky whichever way the camera looks. A texture is made
|
|
53
|
+
when its zone is first drawn, and at most two are held (the zone drawn and
|
|
54
|
+
the one it is turning into). Where a zone has no `art`, or its image has not
|
|
55
|
+
arrived, failed, or is not an image (a `.sprite`), the sky is the zone's
|
|
56
|
+
`color`.
|
|
57
|
+
|
|
58
|
+
**Which zone** is decided each frame from the local Player's Transform (the
|
|
59
|
+
first actor with a `Player` component), never the camera: a player is in a
|
|
60
|
+
box from its edge and stays in it until `edge` metres outside, so standing
|
|
61
|
+
on a line does not flicker. With no Player, the zone with no box.
|
|
62
|
+
|
|
63
|
+
**The fade** takes `fade` seconds by the clock (a frame longer than a
|
|
64
|
+
quarter of a second counts as a quarter). A player who turns back mid-fade
|
|
65
|
+
sees it run backwards from where it is; one who walks on into a third zone
|
|
66
|
+
sees the fade under way finish, then the next. Nothing fades on a scene's
|
|
67
|
+
first frame, or when the player is somewhere else at once (more than 8 m
|
|
68
|
+
from where the frame before had them: a door, a put): the sky is simply
|
|
69
|
+
that zone's.
|
|
70
|
+
|
|
71
|
+
**`scene.skyZone`** says it, to read: `{ id, blend, from, to }`. `id` is
|
|
72
|
+
the zone the player is in; the sky drawn is `from`'s turning into `to`'s,
|
|
73
|
+
`blend` of the way there, 0 to 1 (at rest `from` and `to` are both `id` and
|
|
74
|
+
`blend` is 0). It is the same object from one scene load to the next, kept
|
|
75
|
+
current as frames are drawn (it is one frame behind inside an `update`),
|
|
76
|
+
and it cannot be written. Before a frame is drawn, and after the scene's
|
|
77
|
+
world is disposed, it names the zone with no box. For a scene without the
|
|
78
|
+
key it is `null`, and nothing works it out. A system that fades something
|
|
79
|
+
else with the sky (a zone's sound) reads `from`, `to` and `blend`.
|
|
80
|
+
|
|
81
|
+
What it costs: one draw call in the colour pass (none in the shadow pass),
|
|
82
|
+
under 500 triangles, one texture read for each pixel of sky (two during a
|
|
83
|
+
fade), and no overdraw: it is drawn after every opaque thing, on the far
|
|
84
|
+
plane, so only the pixels they left are shaded. A zone test and a few
|
|
85
|
+
uniforms each frame.
|
|
86
|
+
|
|
87
|
+
How it stays out of the scene's way, and how long it lasts
|
|
88
|
+
(`engine3d/skylife.js` has the rule and all of the code that attaches,
|
|
89
|
+
detaches or disposes anything):
|
|
90
|
+
> The dome and its resources are attached, detached and disposed only by
|
|
91
|
+
> the outermost render of their world, or with no render of that world in
|
|
92
|
+
> progress. Nothing a callback does (re-enter, throw, load, dispose) can
|
|
93
|
+
> leave a dome in the scene graph, a disposed resource in a render list,
|
|
94
|
+
> or a sky record alive past its key.
|
|
95
|
+
|
|
96
|
+
Every frame of a world with the key goes one way (`skyFrame`): counted in,
|
|
97
|
+
prepared, drawn, counted out, and, if it was the outermost, settled. The
|
|
98
|
+
settling alone enforces this, from what is true at that moment:
|
|
99
|
+
> After the outermost frame of a world returns or throws, EITHER
|
|
100
|
+
> `world.sky` is null, OR it is a record whose key is the key the frame's
|
|
101
|
+
> runtime has NOW for THIS world, with its dome out of the scene graph,
|
|
102
|
+
> and neither that frame nor any frame drawn from inside it threw.
|
|
103
|
+
|
|
104
|
+
The key a runtime has for a world is its `sky`, unless the world is
|
|
105
|
+
disposed or the runtime draws in another world (its `three` is set and is
|
|
106
|
+
not this one): then it has none, and no sky is drawn for it there. A frame
|
|
107
|
+
from inside another, or from inside a disposal, never makes, steps,
|
|
108
|
+
attaches, detaches or disposes; a dome in the scene graph that is not of
|
|
109
|
+
its runtime's key is hidden for that draw. Errors are data: a step or a
|
|
110
|
+
disposal that throws does not stop the frame, which is drawn with no sky;
|
|
111
|
+
every release that is due still runs; the first error is thrown at the
|
|
112
|
+
frame's one exit, the frame's own over a kept one.
|
|
113
|
+
|
|
114
|
+
Its mesh, material and textures are the mode's own, kept on `world.sky`,
|
|
115
|
+
one record for one load of one scene. The mesh is in the scene graph only
|
|
116
|
+
while a frame of that scene is being drawn, put there and taken out by
|
|
117
|
+
writing `parent` and `children` directly, so no three.js event is
|
|
118
|
+
dispatched and no listener of a deck's runs. So `skipUnchangedActors`,
|
|
119
|
+
`dropEmptyParts`, the look bake, a deck's own walk of `scene.three.scene`,
|
|
120
|
+
picking, and hub-game's Low tier never meet it; the orbit camera's reach is
|
|
121
|
+
physics, where it has no collider.
|
|
122
|
+
|
|
123
|
+
What ends a record: the scene loaded again or another loaded
|
|
124
|
+
(`SceneRuntime.load`, through the physics system's `reset`; a load ends
|
|
125
|
+
only the record of the key it replaces), a frame of another scene or of
|
|
126
|
+
one without the key, an editor's frame (the editors give `renderWorld` no
|
|
127
|
+
runtime, and draw no sky), `disposeWorld`, the runtime pointed at another
|
|
128
|
+
world, and any frame that throws, or has a frame inside it throw, whether
|
|
129
|
+
or not what called that catches the error. It is disposed at once when no
|
|
130
|
+
frame of the world is being drawn, and otherwise by the outermost frame as
|
|
131
|
+
it settles. Every resource is disposed once, each in a guard of its own; a
|
|
132
|
+
disposal counts as a frame in progress, so a frame drawn from inside a
|
|
133
|
+
`dispose` listener is a frame from inside: it has no sky and makes
|
|
134
|
+
nothing. The next frame of a keyed scene starts from nothing, with no
|
|
135
|
+
fade. Two worlds keep their own.
|
|
136
|
+
`leaveSky` returns `null` only on success. World disposal and physics reset
|
|
137
|
+
propagate its first error with `failed !== null`, so a listener's `throw 0`
|
|
138
|
+
is preserved too. A failed reset stops the load before the new scene is
|
|
139
|
+
installed, after the sky's resources have been released.
|
|
140
|
+
|
|
141
|
+
When `staticActors` is on too, every record release and each nonempty
|
|
142
|
+
shed-texture disposal runs through the world's `outsideCall` hook. The
|
|
143
|
+
entire disposal block is counted, so every texture, geometry and material
|
|
144
|
+
listener sees no recorded adoption and no frozen node, and a listener's
|
|
145
|
+
nested sync cannot adopt between resources or listeners. The callback is
|
|
146
|
+
made once per world, lazily when a record is actually made, and reused on
|
|
147
|
+
later records; unchanged frames do not test or call it. With no hook the
|
|
148
|
+
same block runs directly. This bracket changes neither the sky's ordering
|
|
149
|
+
nor its depth count or handling of errors: each listener still runs in its
|
|
150
|
+
own guard, the first error stays data, and it is thrown at the frame's one
|
|
151
|
+
exit after settling. The next actor pass is ordinary; later passes may
|
|
152
|
+
settle, unless the world was disposed.
|
|
153
|
+
|
|
154
|
+
`runtime.sprites` and its entries are engine-made art data, the same records
|
|
155
|
+
the engine's other drawing reads. The sky reads the slot and `kind`,
|
|
156
|
+
`ready`, `failed` and `image` only with `Object.getOwnPropertyDescriptor`,
|
|
157
|
+
and uses only a data property's `value`:
|
|
158
|
+
> the sky reads art records only through own data properties, so a getter never runs
|
|
159
|
+
|
|
160
|
+
An accessor slot or field, or an entry that is not a plain object (an
|
|
161
|
+
ordinary object or one with a null prototype), is not usable: the zone
|
|
162
|
+
shows its flat colour, with one warning naming the zone and art path per
|
|
163
|
+
world, including across sky record recreation. These reads run without
|
|
164
|
+
`outsideCall`, so unchanged sky frames preserve static adoption. A Proxy
|
|
165
|
+
replacing `runtime.sprites` itself is outside the contract: the deck
|
|
166
|
+
replaced an engine object. The descriptor and prototype checks, and the
|
|
167
|
+
small `{ art, image }` snapshot for a usable entry, run only with the sky
|
|
168
|
+
key on, once for each of the at most two textures drawn; there is no new
|
|
169
|
+
per-frame work with the sky key absent, whether or not static actors are on.
|
|
170
|
+
|
|
171
|
+
**This relies on three.js's EventDispatcher internals, on purpose.** For a
|
|
172
|
+
texture, a geometry and a material, three.js's `dispose()` is
|
|
173
|
+
`dispatchEvent({ type: 'dispose' })` and nothing else, and `dispatchEvent`
|
|
174
|
+
stops at the first listener that throws. The renderer's own cleanup of the
|
|
175
|
+
GPU's copy is one of those listeners, added when the thing is first drawn
|
|
176
|
+
and so after any a deck added before that: one deck listener that throws
|
|
177
|
+
would leave the texture, the buffers or the program allocated for good,
|
|
178
|
+
whatever is caught round `dispose()`. So for the sky's own resources
|
|
179
|
+
`skylife.js` does not call `dispose()`: it reads the resource's
|
|
180
|
+
`_listeners.dispose` (EventDispatcher's own array), copies it, and calls
|
|
181
|
+
each listener in a try of its own with the event three.js would send. If
|
|
182
|
+
that array is not there in that shape it calls `dispose()` instead, in a
|
|
183
|
+
guard. `test-sky.mjs` fails if three.js keeps listeners elsewhere or its
|
|
184
|
+
`dispose()` comes to do more than dispatch: when it does after a three.js
|
|
185
|
+
upgrade, read `disposed` in `skylife.js` again before changing the test.
|
|
186
|
+
|
|
187
|
+
While a record's resources are disposed, `world.sky` is a marker that is
|
|
188
|
+
not a record and owns nothing (`{ releasing: true }`), so that any frame a
|
|
189
|
+
`dispose` listener draws, an editor's or a keyless scene's included, is a
|
|
190
|
+
frame from inside: it makes nothing, and if it throws, the frame round the
|
|
191
|
+
disposal keeps no record. The marker is gone when the disposal ends.
|
|
192
|
+
|
|
193
|
+
With the key absent, what runs that did not before: `load` reads
|
|
194
|
+
`data.engine.sky` once and stores null, and the physics system's `reset`
|
|
195
|
+
reads `world.sky` (null) once; each `renderWorld` reads that null and
|
|
196
|
+
`world.sky` and calls the frame it always was; `disposeWorld` reads
|
|
197
|
+
`world.sky` once. No call-out hook is acquired or allocated for a world
|
|
198
|
+
that never has a sky record.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Scene keys: engine.frozenStatics, staticActors
|
|
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": { "frozenStatics": true }` extends the static path below. It
|
|
7
|
+
requires both `skipUnchangedActors: true` and `staticActors: true`; otherwise
|
|
8
|
+
the runtime warns and ignores it. Absent or false retains the existing path.
|
|
9
|
+
Mark actors with `"static": true` as below. Component field writes, additions
|
|
10
|
+
and deletions, `scene.touch`, spawn/despawn, runtime quaternion/render-sleep
|
|
11
|
+
changes, and node transforms, matrices, visibility and parenting queue a sync.
|
|
12
|
+
A synced static leaves the walk again. Shared model/art edits and the global
|
|
13
|
+
look switch invalidate the affected cached scene state too.
|
|
14
|
+
|
|
15
|
+
Static subtrees freeze their three.js local/world matrix updates only when
|
|
16
|
+
every ancestor is static. Moving parents, animated models, custom matrix
|
|
17
|
+
controllers, nested actor roots, editor/instanced worlds and ground-height
|
|
18
|
+
callbacks retain checked passes where needed. Externally supplied component
|
|
19
|
+
objects, shared nested defaults/spawn data, and exposed raw Rapier handles
|
|
20
|
+
retain per-frame checks because their original references can bypass hooks.
|
|
21
|
+
Use `scene.serialize()`/`scene.clone()` to copy runtime scene data; components
|
|
22
|
+
are observed through Proxies under this key.
|
|
23
|
+
|
|
24
|
+
Fixed static bodies reconcile/push only when dirty. Rapier's active-body
|
|
25
|
+
iterator supplies awake dynamics; a final interpolation sample settles a
|
|
26
|
+
body entering sleep. QA can set `scene.three.auditFrozenStatics = true`
|
|
27
|
+
(off by default) to run the full unchanged checks and assert equal node
|
|
28
|
+
matrices/signatures and body poses/signatures. `test-frozen-statics.mjs`
|
|
29
|
+
compares the paths over 100 frames and counts visits to unchanged statics.
|
|
30
|
+
- `"engine": { "staticActors": true }` at the scene file's top level (the same
|
|
31
|
+
`engine` object), in a scene that also sets `skipUnchangedActors`, asks the
|
|
32
|
+
engine to leave alone the actors the scene file marks as scenery:
|
|
33
|
+
`"static": true` on the actor, beside its `id` and `components`. With
|
|
34
|
+
`skipUnchangedActors` the engine still asks, of every actor on every frame,
|
|
35
|
+
whether anything it is drawn or simulated from has changed; for a town that
|
|
36
|
+
is mostly buildings, that asking is a quarter of a slow phone's frame. A
|
|
37
|
+
marked actor is not asked. The terms:
|
|
38
|
+
> With the key absent, or without `skipUnchangedActors`, a scene runs the
|
|
39
|
+
> engine exactly as before, whatever its actors are marked. With both, a
|
|
40
|
+
> marked actor that is still is drawn and simulated exactly as it was on the
|
|
41
|
+
> last frame the engine looked at it, until the engine is told it is being
|
|
42
|
+
> changed: `scene.touch(actorOrId)`. From the frame of the touch on, the
|
|
43
|
+
> actor is an ordinary one, followed as every actor is under
|
|
44
|
+
> `skipUnchangedActors`, until the next scene load. **A change to a marked
|
|
45
|
+
> actor made without `scene.touch` is not followed**: a component's field
|
|
46
|
+
> written, a component added, removed or switched off (`$enabled`), its
|
|
47
|
+
> node or any object under it moved, hidden or given children. Nothing in a
|
|
48
|
+
> published deck notices such a write.
|
|
49
|
+
|
|
50
|
+
This is the one `engine` key under which "nothing has to be marked dirty"
|
|
51
|
+
stops being true, and only for the actors a scene marks. Mark what nothing
|
|
52
|
+
ever writes; touch before writing anything else.
|
|
53
|
+
|
|
54
|
+
Only actors are marked. What the engine draws that is not an actor -- the
|
|
55
|
+
sun and its shadow camera, the camera, a sky the engine itself draws from
|
|
56
|
+
an `engine` key -- has no `static` to carry and is not
|
|
57
|
+
part of the still set: it is drawn and moved as it always is, every frame,
|
|
58
|
+
whatever the scene marks. A sky that IS an actor (one `Model` on a
|
|
59
|
+
`Transform`, as the hub town's is) is marked like any other scenery.
|
|
60
|
+
|
|
61
|
+
Which marked actors are still. A marked actor is still when it was in the
|
|
62
|
+
scene file at load (a spawned actor never is), has no `Body`, none of its
|
|
63
|
+
components' classes has an `update`, `onEnable` or `onDisable`, its model
|
|
64
|
+
does not walk or move inside itself (the engine finds that out when it has
|
|
65
|
+
built the node, and touches the actor itself), and nothing has touched it
|
|
66
|
+
since the load. Any other marked actor is an ordinary actor; the mark costs
|
|
67
|
+
nothing. `scene.stillActors` is the Set (null in a scene without the key).
|
|
68
|
+
|
|
69
|
+
What tells the engine, so a deck does not have to:
|
|
70
|
+
- `scene.despawnActor`, `scene.load` / `loadFromFile` / `setContent`,
|
|
71
|
+
`scene.setBehaviors` (the still set is reckoned again; what was touched
|
|
72
|
+
stays touched);
|
|
73
|
+
- `scene.physics3d.setVelocity`, `applyImpulse` and `addForce` touch the
|
|
74
|
+
actor they are handed. `bodyOf` does not: asking for a body is not a
|
|
75
|
+
change, and a marked actor's body made dynamic or kinematic through it
|
|
76
|
+
needs a `scene.touch`;
|
|
77
|
+
- the multiplayer-3d kit touches an actor before it writes a network pose
|
|
78
|
+
on it, and hub-game before it hides, shows or tints an actor or swings a
|
|
79
|
+
door (`hub.hide`, `hub.show`, `hub.tint`; `hub.move` arrives as a network
|
|
80
|
+
pose), so a place's server may do those to a marked actor;
|
|
81
|
+
- what marked actors share is watched for all of them at once, and followed
|
|
82
|
+
with no touch: a model file edited (or a file or art it reads), art that
|
|
83
|
+
finishes loading, the look switched, the scene itself
|
|
84
|
+
(`scene.three.scene`) moved, turned or scaled.
|
|
85
|
+
|
|
86
|
+
A behaviour, a collision callback or any other deck code that writes
|
|
87
|
+
another, marked actor calls `scene.touch(id)` first; it is a Set delete,
|
|
88
|
+
safe to call every frame and on any actor, and does nothing in a scene
|
|
89
|
+
without the key. `scene.touch` exists on every scene, so code that may run
|
|
90
|
+
under an older kit calls `scene.touch?.(id)`.
|
|
91
|
+
|
|
92
|
+
What "left alone" means, frame by frame. A still actor is not visited by
|
|
93
|
+
`scene.update` (it has nothing to update), by the pass that builds and
|
|
94
|
+
places nodes, or by the physics pass (its body is fixed and where it was
|
|
95
|
+
put); and its node's `updateMatrixWorld` returns at once, so its matrices
|
|
96
|
+
are not recomputed or even compared. three.js still walks its objects to
|
|
97
|
+
cull and draw them, and rapier still collides with its body. So:
|
|
98
|
+
- `scene.getActors()`, `getActor`, `actorWith` and the node map
|
|
99
|
+
(`scene.three.nodes`) are unchanged: a still actor is in all of them, with
|
|
100
|
+
its node, and the node's `position` is its Transform's;
|
|
101
|
+
- a still actor's node may be taken out of the scene and put back under the
|
|
102
|
+
same parent by deck code (hub-game's low picture does, by distance): it
|
|
103
|
+
comes back drawn where it was, with no touch. Putting it under another
|
|
104
|
+
parent is a change to it;
|
|
105
|
+
- a frame on which the still set changes (a touch, a despawn), and the one
|
|
106
|
+
after, visit every actor once, as a frame under `skipUnchangedActors`
|
|
107
|
+
alone does, before the rest are left alone again; so does a frame on
|
|
108
|
+
which a node is built, rebuilt or released. Touching a different actor
|
|
109
|
+
every frame gives the key's saving away: such actors should not be
|
|
110
|
+
marked.
|
|
111
|
+
|
|
112
|
+
Where the key does nothing: without `skipUnchangedActors`; in the scene
|
|
113
|
+
editor, which changes actors as it pleases; and in a world with
|
|
114
|
+
`instanceModels` on. In a scene with a
|
|
115
|
+
`scene.three.scene.userData.groundHeight` callback no node is frozen (every
|
|
116
|
+
pass there runs the old way, as under `skipUnchangedActors`), though still
|
|
117
|
+
actors are still left out of `update` and the physics pass.
|
|
118
|
+
|
|
119
|
+
How it stays right (`engine3d/world3d.js` has the rule and the code):
|
|
120
|
+
> A pass is ordinary (every actor, as the skipping pass runs it) unless the
|
|
121
|
+
> still set and the things its actors share read as they did when the last
|
|
122
|
+
> ordinary pass that ended alone adopted them; then a still actor is left
|
|
123
|
+
> exactly as that pass left it.
|
|
124
|
+
>
|
|
125
|
+
> The still set is adopted only after an ordinary pass has completed
|
|
126
|
+
> without throwing. While any ordinary pass, or anything a pass calls back
|
|
127
|
+
> into, is running, nothing is frozen and no still state is trusted. Any
|
|
128
|
+
> interruption leaves the next pass ordinary.
|
|
129
|
+
|
|
130
|
+
The second paragraph is one mechanism, used the same way in the three
|
|
131
|
+
places that leave still actors out (the runtime's `update`, the pass that
|
|
132
|
+
places nodes, the physics pass): each has a keeper
|
|
133
|
+
(physics-2d `engine/stillClock.js` `StillKeeper`) that counts every entry
|
|
134
|
+
into its pass, settled or ordinary, by any runtime, nested or not. A pass
|
|
135
|
+
may be settled only on an adoption made, or last confirmed, at the count
|
|
136
|
+
as it stood just before the pass entered, for the very version of the still
|
|
137
|
+
set the runtime has now; otherwise the adoption is dropped there, before
|
|
138
|
+
the pass does anything. A new adoption is recorded only at the very end of
|
|
139
|
+
the whole operation (for `update`: after the behaviours and every system;
|
|
140
|
+
for the physics pass: after the step, the write-back and the collision
|
|
141
|
+
callbacks), and only if the pass returned, nobody else entered, and the
|
|
142
|
+
still set is unmoved. Nothing is ever put back. So code that walks, draws,
|
|
143
|
+
syncs or updates the scene from inside a pass, settled or not, sees what
|
|
144
|
+
it sees without the key; a behaviour, a system, a node being built or
|
|
145
|
+
released, rapier's step or a collision callback that throws leaves nothing
|
|
146
|
+
adopted; and a pass entered from inside another, by the same runtime or a
|
|
147
|
+
different one, whether it returns or throws and is caught, leaves the pass
|
|
148
|
+
around it unable to adopt, and the next pass ordinary. The keeper of a
|
|
149
|
+
world, and of a physics system, sees every pass of every kind from the
|
|
150
|
+
moment it exists, not only those of scenes that ask: a scene without
|
|
151
|
+
`skipUnchangedActors` played on the same world or the same physics system
|
|
152
|
+
(a pack mounted in a town, a callback that syncs another scene) drops what
|
|
153
|
+
was adopted when it enters and adopts nothing.
|
|
154
|
+
|
|
155
|
+
World disposal, standalone ground replacement, physics-debug updates,
|
|
156
|
+
resizing and the editor's orbit-lens return are counted for their whole
|
|
157
|
+
duration by `outsideCall`: `keeper.begin(NOT_STILL)`, adoption dropped and
|
|
158
|
+
nodes thawed, then `keeper.end(pass, false)` in a `finally`. While this pass
|
|
159
|
+
is running, no listener's nested sync can adopt or freeze, including between
|
|
160
|
+
two listeners or two disposable targets. Near shadows use the same bracket
|
|
161
|
+
across both map and blur-map disposal, only when a non-null map is released
|
|
162
|
+
(a fit size change, mode leave, or world disposal). Their callback is made
|
|
163
|
+
once per world and reused across frames and mode recreation. Unchanged
|
|
164
|
+
near-shadow frames keep their adoption and frozen nodes. The sky uses the
|
|
165
|
+
same bracket for each record release (prepare, settle, load or world
|
|
166
|
+
disposal), across every texture, geometry and material listener, and for
|
|
167
|
+
the textures shed after a step. Its callback is acquired only when a sky
|
|
168
|
+
record is made, stored on the world and reused by later records. Unchanged
|
|
169
|
+
sky frames keep their adoption and frozen nodes. On return or throw
|
|
170
|
+
the bracket exits with nothing adopted; the next actor pass is ordinary and
|
|
171
|
+
later passes may settle. A disposed world never adopts again.
|
|
172
|
+
World disposal returns the orbit lens, releases the sky, drops near shadows
|
|
173
|
+
and disposes nodes in that order, each cleanup in the previous one's
|
|
174
|
+
`finally`. All four run even if the lens or an earlier listener throws;
|
|
175
|
+
the first thrown value wins, including a falsy value such as `0`.
|
|
176
|
+
Sky preparation reads engine art through own data-property descriptors,
|
|
177
|
+
never through an accessor, so these reads need no call-out bracket and do
|
|
178
|
+
not drop static adoption on unchanged frames.
|
|
179
|
+
|
|
180
|
+
Before a world has a keeper, `outsideCall` uses `world.unkept` exactly as a
|
|
181
|
+
plain `syncActors` pass does: increment before the operation and decrement
|
|
182
|
+
in a `finally`. A keeper made by a listener sees this count, so none of its
|
|
183
|
+
nested passes can settle or adopt while the operation runs. On exit, if a
|
|
184
|
+
keeper was made, its adoption is dropped and nodes thawed again, leaving
|
|
185
|
+
the next pass ordinary even when the operation throws.
|
|
186
|
+
|
|
187
|
+
Key-absent inventory of the added statements at these call-outs: with no
|
|
188
|
+
`stillKeeper`, `disposeWorld` and `resizeWorld` each add a keeper test, an
|
|
189
|
+
`unkept` increment, a `try/finally`, a decrement and an exit keeper test;
|
|
190
|
+
`updatePhysicsDebug` does the same when buffers exist, `syncGround` when
|
|
191
|
+
the ground changes, and the editor's orbit-lens return when a lens exists.
|
|
192
|
+
Near shadows add no keeper test or new callback allocation on an unchanged frame:
|
|
193
|
+
they reuse the world's lazy callback. A release adds the same `unkept`
|
|
194
|
+
bracket for the entire operation, only when a map or blur map exists. The
|
|
195
|
+
sky allocates its callback only for an actual sky record: a world that never
|
|
196
|
+
has one makes none. Unchanged sky frames do not test or call the hook; a
|
|
197
|
+
record release or a nonempty shed-texture disposal adds the same bracket.
|
|
198
|
+
Rare operations pass a closure to `outsideCall`; with no keeper it runs
|
|
199
|
+
inside this count. Only a keeper made during the call adds `dropStill` on exit.
|
|
200
|
+
None makes a keeper with the key absent.
|
|
201
|
+
|
|
202
|
+
The runtime keeps the still set and a number that moves whenever the set
|
|
203
|
+
changes (`scene.stillActors`, `scene.stillVersion`; one sequence of
|
|
204
|
+
numbers for every scene, so no two states share one); the world and the
|
|
205
|
+
physics system each keep the number they adopted, and a pass decides from
|
|
206
|
+
its own runtime, at its start, whether it may leave anything out. A node is
|
|
207
|
+
frozen by two numbers on it, matched against one on the world that only
|
|
208
|
+
ever moves on, so every frozen node of a world thaws at once with nothing
|
|
209
|
+
to visit. Between passes a frozen node guards itself, on every walk of the
|
|
210
|
+
scene, whoever walks it: it is frozen only while no scene's still set has
|
|
211
|
+
changed since it froze (so `scene.touch` thaws at once: an actor touched
|
|
212
|
+
and then posed by its node is followed by the very next draw), and only
|
|
213
|
+
while it is under the parent it froze under and that parent's world matrix
|
|
214
|
+
is the one three.js has just computed for it (so the scene moved, by its
|
|
215
|
+
position, its matrix written by hand, or a parent of its own, is followed
|
|
216
|
+
by the next walk).
|
|
217
|
+
|
|
218
|
+
For QA, never in play: `scene.three.auditStatic = n` checks `n` still
|
|
219
|
+
actors a frame, in turn, the way an ordinary frame would have (and every
|
|
220
|
+
still body), writes what it finds changed to
|
|
221
|
+
`scene.three.staticAuditFailures` as `{ id, what }`, warns once an actor,
|
|
222
|
+
and touches it. Set it to `Infinity` to check every still actor every
|
|
223
|
+
frame: a deck that marks actors should be played that way once with
|
|
224
|
+
nothing reported.
|
|
225
|
+
Opt in when a scene is hundreds of actors that are never written; a scene
|
|
226
|
+
whose scenery is a dozen actors gains nothing.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Scene key: engine.view
|
|
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": { "view": { "far": 80, "fogFrom": 60, "fogColor": "#bfe3f2" } }`
|
|
7
|
+
limits the world camera's view distance independently of the camera keys.
|
|
8
|
+
`far` is metres, a number in 20..1000; absent or invalid means the whole
|
|
9
|
+
view key is ignored. Each keyed frame sets the camera's far plane and
|
|
10
|
+
updates its projection only if it changed, and sets linear `THREE.Fog`
|
|
11
|
+
ending at `far`. `fogFrom` is optional (default `0.75 * far`); finite
|
|
12
|
+
numbers clamp to 0..just below far, other values use the default.
|
|
13
|
+
`fogColor` must be `#rrggbb`. Otherwise fog follows the visible kit sky:
|
|
14
|
+
the texture row nearest the horizon, averaged across bearings, or the
|
|
15
|
+
zone's flat colour if its texture cannot be read, blended as the sky fades
|
|
16
|
+
between zones. Without a kit sky it uses a colour Three scene background,
|
|
17
|
+
then a `#rrggbb` scene-data `background`, or neutral `#808080`. Horizon
|
|
18
|
+
sampling happens once per art entry and only under this key. The kit sky
|
|
19
|
+
ignores fog and its vertex shader places it
|
|
20
|
+
on the far plane, so reducing the view distance never cuts it off.
|
|
21
|
+
|
|
22
|
+
Lifecycle is the orbit lens's: remember the original far and exact fog
|
|
23
|
+
object on the first keyed frame; give both back on physics reset/load,
|
|
24
|
+
an editor frame (no runtime), and world disposal. Keyed after keyed takes
|
|
25
|
+
them anew. A world that never meets a valid key has no record, allocates
|
|
26
|
+
nothing, and writes no camera or fog properties (engine3d/viewrange.js;
|
|
27
|
+
scripts/test-view-range.mjs, run by check).
|
|
28
|
+
|
|
29
|
+
Materials: kit physical/standard materials and basic outline hulls keep
|
|
30
|
+
Three's fog chunks. The rim/AO, glow, vertex-finish and near-shadow fade
|
|
31
|
+
hooks preserve them; nearshadows itself only changes the shadow pass.
|
|
32
|
+
The sole custom ShaderMaterial is the sky, intentionally `fog: false`.
|
|
33
|
+
No world surface needs a shader change. Deck-supplied shaders must handle
|
|
34
|
+
fog themselves. Turning fog on selects fog-enabled shader programs once;
|
|
35
|
+
expect a one-off compile stall of tens to hundreds of milliseconds on a
|
|
36
|
+
phone with several variants (an estimate, not a device measurement).
|
|
37
|
+
Changing fog distances or colours does not recompile those programs.
|
|
@@ -672,7 +672,7 @@ time.
|
|
|
672
672
|
- `keep: true` on a part keeps it out of merging, with its own mesh and
|
|
673
673
|
material, for a deck that reaches for it by id. Parts with a `tint` are
|
|
674
674
|
kept too.
|
|
675
|
-
- In a scene that set `"engine": { "dropEmptyParts": true }` (
|
|
675
|
+
- In a scene that set `"engine": { "dropEmptyParts": true }` (docs/engine-skip-work.md) a
|
|
676
676
|
placed model has no group for a part that draws nothing. `keep: true` is
|
|
677
677
|
also what keeps such a part's group there, for a deck that reaches for an
|
|
678
678
|
empty part as a locator; `slot-...` parts and parts that move always stay.
|
|
@@ -15,13 +15,16 @@ import { Scene3DPlayer } from './Scene3DPlayer';
|
|
|
15
15
|
|
|
16
16
|
const DEFAULT_SCENE = 'scenes/main.scene';
|
|
17
17
|
|
|
18
|
-
export function PlayOnly3D({ initialScene } = {}) {
|
|
18
|
+
export function PlayOnly3D({ initialScene, onStage } = {}) {
|
|
19
19
|
const files = initialFiles3D;
|
|
20
20
|
const scenePath =
|
|
21
21
|
initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
|
|
22
22
|
const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
|
|
23
23
|
if (!sceneData) return null;
|
|
24
|
+
onStage?.('assets:start');
|
|
24
25
|
const { sprites } = collectAssets(files);
|
|
26
|
+
onStage?.('assets:collected');
|
|
27
|
+
onStage?.assets(sprites);
|
|
25
28
|
return (
|
|
26
29
|
<Scene3DPlayer
|
|
27
30
|
key={scenePath}
|
|
@@ -31,6 +34,7 @@ export function PlayOnly3D({ initialScene } = {}) {
|
|
|
31
34
|
behaviorClasses={behaviorClasses}
|
|
32
35
|
scenePath={scenePath}
|
|
33
36
|
onFirstFrame={Lifecycle.ready}
|
|
37
|
+
onStage={onStage}
|
|
34
38
|
/>
|
|
35
39
|
);
|
|
36
40
|
}
|