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,136 @@
|
|
|
1
|
+
# Scene key: engine.maxFps
|
|
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": { "maxFps": 60 }` at the scene file's top level (the same
|
|
7
|
+
`engine` object) asks the play loop (`engine3d/Scene3DPlayer.jsx`) not to
|
|
8
|
+
run its frame more often than that on a display that refreshes faster.
|
|
9
|
+
Without it the loop runs a whole frame (behaviours, physics, drawing) on
|
|
10
|
+
every animation frame the browser gives it, 120 a second on a 120 Hz
|
|
11
|
+
display; a scene that costs most of a frame there runs a core flat out and
|
|
12
|
+
drops every other frame. The terms:
|
|
13
|
+
> With the key absent, the loop runs exactly as before: every animation
|
|
14
|
+
> frame, handed the time since the last one, at most 0.033 s. With the key
|
|
15
|
+
> present, an animation frame runs the whole frame only when at least 78%
|
|
16
|
+
> of 1/maxFps seconds has passed since the last frame that ran, and is
|
|
17
|
+
> handed all of that time, at most 0.05 s, so nothing skipped is lost:
|
|
18
|
+
> a key pressed and let go, or a drag begun and ended, while frames were
|
|
19
|
+
> skipped is seen by the next frame that runs, as one frame would have
|
|
20
|
+
> seen it without the key. An animation frame that does not run does
|
|
21
|
+
> nothing at all. The first frame always runs.
|
|
22
|
+
|
|
23
|
+
0.05 s is three of physics' 1/60 s steps: physics takes at most four a
|
|
24
|
+
frame and drops what is left after four, so a longer frame (with what it
|
|
25
|
+
carries over) could leave physics behind the behaviours' clock; at most
|
|
26
|
+
0.05 s a frame, the two keep the same time to within the one step physics
|
|
27
|
+
carries. That is why a cap is at least 30: a cap's frames are 1/maxFps
|
|
28
|
+
apart, under 0.05 s from 30 up, so the cut falls only on a late frame, as
|
|
29
|
+
0.033 s does without the key. How input is lent (`engine3d/framecap.js`,
|
|
30
|
+
`updateLending`): the key handlers write down, under a cap only, every key
|
|
31
|
+
that went down and the stick's last direction while a drag held it; the
|
|
32
|
+
next frame that runs has each such key that is no longer held in
|
|
33
|
+
`runtime.keys` for its update, and that stick direction in
|
|
34
|
+
`runtime.moveInput` when no drag holds it now, and both are taken back
|
|
35
|
+
after the update. A key held across is seen as held, as always. A tap's
|
|
36
|
+
jump (`consumeJump`), the hub's grab key and its buttons keep their own
|
|
37
|
+
latches or act at once, and lose nothing.
|
|
38
|
+
|
|
39
|
+
It goes by the time between frames, never by counting them; no frame is
|
|
40
|
+
made up after a late one. A browser only hands out frames on the display's
|
|
41
|
+
refresh, so the rule picks a whole number of refreshes per frame, and the
|
|
42
|
+
78% is chosen so that each display gets one steady cadence at 60: every
|
|
43
|
+
refresh at 60 Hz (even with timestamps up to 1.8 ms early or late) and at
|
|
44
|
+
75 Hz; every second at 90, 120 and 144 Hz (45, 60 and 72 fps); every
|
|
45
|
+
third at 165 and 180 Hz (55, 60); every fourth at 240 Hz (60). A cap is a
|
|
46
|
+
finite number from 30 to 240; anything else is no cap. It is read when
|
|
47
|
+
the scene loads (`runtime.maxFps`) and looked at every animation frame,
|
|
48
|
+
so going to a scene without it takes the cap off from the next frame on.
|
|
49
|
+
The scene and model editors run their own loops and are never capped.
|
|
50
|
+
Opt in when a scene costs enough that a fast display keeps the loop busy
|
|
51
|
+
all the time; a cheap scene loses smoothness on such a display and
|
|
52
|
+
gains nothing.
|
|
53
|
+
|
|
54
|
+
The cap also changes how the `Player` hovers, as the camera key does:
|
|
55
|
+
under it the hover spring and the fall-faster pull are forces
|
|
56
|
+
(`hoverSteadily`, `pullSteadily`), with or without the camera key. Why:
|
|
57
|
+
the keyless hover and pull are impulses scaled by the frame's dt, pushed
|
|
58
|
+
once a frame, while gravity pulls once per fixed step, so each frame the
|
|
59
|
+
player gains g x (dt - steps x 1/60), which is g x (the change in
|
|
60
|
+
physics' accumulator carry). Its vertical speed follows the carry and its
|
|
61
|
+
drawn height bobs with it. Uncapped, a slow phone's frames longer than
|
|
62
|
+
33 ms are all clamped to 0.033 s, two steps less 0.3 ms, so the carry
|
|
63
|
+
barely moves and the bob stays small; under the cap the same frames are
|
|
64
|
+
handed what they took (25 to 50 ms), the carry jumps anywhere in
|
|
65
|
+
[0, 1/60) every frame, and the bob grows. That was the TECNO KJ5's
|
|
66
|
+
tripled walking bob (3.2-3.4 cm against 1.05-1.16) that had the cap
|
|
67
|
+
reverted: measured before the hover became a force under the camera key,
|
|
68
|
+
so the town's Player was hovering by impulses then. Never the 3/60 clamp
|
|
69
|
+
itself: shrinking it would only cut more frames short.
|
|
70
|
+
`scripts/test-frame-cap-bob.mjs` drives the real Player and physics on
|
|
71
|
+
made-up frame timestamps through the real `nextFrame`; drawn height
|
|
72
|
+
peak to peak walking, in mm, without the camera key:
|
|
73
|
+
|
|
74
|
+
| frames | uncapped | capped, impulse hover (reverted) | capped (now) |
|
|
75
|
+
| --- | --- | --- | --- |
|
|
76
|
+
| 60 Hz steady | 9.50 | 9.50 | 0.00 |
|
|
77
|
+
| 120 Hz, capped at 60 | 4.85 | 0.00 | 0.00 |
|
|
78
|
+
| slow phone, 25-55 ms + hitches (3 seeds) | 12.8-13.0 | 21.9-23.6 | 0.00 |
|
|
79
|
+
| slow phone, whole 90 Hz refreshes | 14.70 | 26.47 | 0.00 |
|
|
80
|
+
| slow phone, whole 60 Hz refreshes | 10.86 | 28.85 | 0.00 |
|
|
81
|
+
|
|
82
|
+
With the camera key every cell is 0.00, capped or not; the walk's
|
|
83
|
+
horizontal speed is even in every cell (the walk push stays a per-frame
|
|
84
|
+
impulse: on flat ground nothing pushes against it per step, so at speed
|
|
85
|
+
it pushes nothing). The terms: with the key absent, `scene.maxFps` is 0
|
|
86
|
+
and the Player makes the calls it made before (test-steady-hover.mjs).
|
|
87
|
+
With it, the player stands and walks at the camera key's height, 0.7412 m
|
|
88
|
+
for the kit's player, whatever the frames, where the keyless player's
|
|
89
|
+
height depends on the frame rate (the damper answers the speed gravity
|
|
90
|
+
gave it since the last frame's push): 0.739 m at a steady 60 fps, 0.731
|
|
91
|
+
at 120, about 0.756 at 30. So a capped scene's player stands up to 1.5 cm
|
|
92
|
+
lower on a slow phone than the same scene uncapped, and 2 mm higher at
|
|
93
|
+
60 fps; a player with another gravity scale is off by 0.69 cm per unit of
|
|
94
|
+
scale, as under the camera key. A jump goes as high as under the camera
|
|
95
|
+
key, to within 3 mm (2.347 to 2.355 m).
|
|
96
|
+
|
|
97
|
+
The same dt variance moved the keyless follow camera (`updateCamera`). It
|
|
98
|
+
eases once a frame, from the Player's update, by 1 - e^(-12 dt) toward
|
|
99
|
+
where the player was drawn the frame before; behind a walk at v it trails
|
|
100
|
+
by about v/12 + v dt/2, and the player is then drawn v dt further on, so
|
|
101
|
+
under the cap the player slid about on screen (camera-to-player distance
|
|
102
|
+
peak to peak walking 39-52 mm against 12-19 uncapped on the slow-phone
|
|
103
|
+
traces). Under the cap, without a camera key, the Player asks for its
|
|
104
|
+
camera as the rigid one does (`scene.followCamera`, Player.jsx
|
|
105
|
+
`placeCapped`; `placeFollowCamera` in systems/physics3d.js now takes a
|
|
106
|
+
request from a scene with `maxFps` too): it is placed at the end of the
|
|
107
|
+
frame on the position the frame is drawn with, the same target and rate,
|
|
108
|
+
each coordinate eased as if the target moved steadily since the last
|
|
109
|
+
frame (`settle`, the exact solution of x' = 12 (target - x)), so a steady
|
|
110
|
+
walk is trailed by v/12 whatever the frames: that distance moves 0.00 mm
|
|
111
|
+
on every trace (4.3, 2.1 and 12-19 mm uncapped), and the camera's height
|
|
112
|
+
0.00. Last frame's target is `actor.runtime.camTarget`; a teleport snaps
|
|
113
|
+
as it does uncapped. The orbit camera is under the camera key, placed at
|
|
114
|
+
the frame's end and eased exactly (or toward what the player asked, which
|
|
115
|
+
does not move with the walk) already, and is not changed.
|
|
116
|
+
|
|
117
|
+
60 is the tested cap: `RUN_SHARE`'s margins are worked out for it against
|
|
118
|
+
the common refresh rates. Other caps are allowed but thinner (a display
|
|
119
|
+
whose period sits near a multiple of 0.78/maxFps alternates cadences on
|
|
120
|
+
jittery timestamps), and a cap runs at a whole number of refreshes, not
|
|
121
|
+
at its own value: on a 60 Hz display a cap from 30 to about 46.8 runs at
|
|
122
|
+
30 fps and one from about 46.8 up runs at 60. Because the capped keyless
|
|
123
|
+
camera is placed at the frame's end (as the rigid one is), a deck
|
|
124
|
+
behaviour that moves the camera during the update is overwritten there
|
|
125
|
+
under the cap. Releasing: the cap is read by physics-2d's
|
|
126
|
+
`SceneRuntime` (`maxFps`, latched at load) and acted on by physics-3d;
|
|
127
|
+
physics-3d pins the physics-2d it imports (`castle.json` `imports`), so
|
|
128
|
+
physics-2d must be republished and physics-3d's import of it moved before
|
|
129
|
+
the cap does anything in a deck. Until then `runtime.maxFps` is undefined,
|
|
130
|
+
every check above reads it as no cap, and the key is dormant.
|
|
131
|
+
Under the orbit camera key the drag stick is the orbit input's
|
|
132
|
+
(engine3d/orbitinput.js), which writes the same `runtime.moveInput`; the
|
|
133
|
+
move handler latches it under a cap as it does its own, so a stick drag
|
|
134
|
+
begun and ended between two capped frames is lent to the next frame that
|
|
135
|
+
runs too. Its camera drags are summed until the frame takes them, and lose
|
|
136
|
+
nothing.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Scene key: engine.load
|
|
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": { "load": { "first": { "radius": 30 }, "sliceMs": 8 } }`
|
|
7
|
+
builds the square's model visuals before the first frame and the remaining
|
|
8
|
+
models in slices after it. This is dormant unless the scene explicitly sets
|
|
9
|
+
the key; the editor (`world.staticActorsOff`) keeps synchronous visuals.
|
|
10
|
+
`engine3d/squarefirst.js` validates the complete key: `first` is
|
|
11
|
+
either an object containing only a finite `radius > 0` in metres, or an
|
|
12
|
+
array of nonempty actor-id strings (an empty array is allowed). `sliceMs`
|
|
13
|
+
is optional, defaults to 8, and must be a finite number from 1 through 50.
|
|
14
|
+
Optional `horizon` is a finite number of metres >= 0, default 45. It limits
|
|
15
|
+
background builds to pending keys with at least one waiting actor within
|
|
16
|
+
that x/z distance of the current first Player actor's Transform, including
|
|
17
|
+
the boundary; without that Transform it uses the camera's world position.
|
|
18
|
+
Unlike first-sync selection, this horizon follows movement. `horizon: 0`
|
|
19
|
+
disables the distance limit and lets the background drain build every key.
|
|
20
|
+
Eligibility is cached until the player (or fallback camera) moves more than
|
|
21
|
+
1 m in x/z from the last sample, or pending membership/placement changes.
|
|
22
|
+
Sub-metre boundary crossings may therefore wait for the next sample. Sync
|
|
23
|
+
invalidates moving waiters too, including dynamic and tier-detached actors.
|
|
24
|
+
Optional `inert` is an array of nonempty component-name strings (empty is
|
|
25
|
+
allowed), e.g. `["Lookable", "RouteAnchor", "WalkSurface"]`: the deck
|
|
26
|
+
promises those components never consume their actor's visual, even when
|
|
27
|
+
registered on the client.
|
|
28
|
+
Unknown fields, missing `first`, or any invalid value disable the whole
|
|
29
|
+
key; absent/invalid keys retain the synchronous node trees and build calls.
|
|
30
|
+
|
|
31
|
+
Radius uses x/z distance, including the boundary. Its centre is the first
|
|
32
|
+
actor with a `Player` component's Transform at the scene's first sync, or
|
|
33
|
+
the origin if none exists. The centre and selected keys do not move as the
|
|
34
|
+
player moves. With `"first": ["ground", "fountain"]`, those actors select
|
|
35
|
+
their model keys instead. Every copy of a selected key is first, regardless
|
|
36
|
+
of its own distance. Models shared with any unsafe-to-wait actor are first
|
|
37
|
+
too, even when that actor occurs later in the actor list.
|
|
38
|
+
|
|
39
|
+
The wait predicate allows unregistered components (pure scene data: the
|
|
40
|
+
shared SceneRuntime creates no instance or callbacks for them) and declared
|
|
41
|
+
`inert` components. Registered client behaviours otherwise block, even
|
|
42
|
+
disabled or constructor-only custom classes. The kit's Transform, Shape,
|
|
43
|
+
Model, Solid and Body classes are data-only exceptions by exact class
|
|
44
|
+
registration in `engine3d/dataBehaviors.js`. Their canonical behaviour
|
|
45
|
+
modules and generated play mirrors register their own classes in the same
|
|
46
|
+
WeakSet; the predicate imports neither inspectors nor editor modules.
|
|
47
|
+
Replacements and subclasses block unless declared inert, including
|
|
48
|
+
constructors that assign their own update/collision functions. Body may be
|
|
49
|
+
fixed, kinematic or dynamic: `systems/physics3d.js` builds colliders from
|
|
50
|
+
Shape, places bodies from Transform and writes motion back to Transform;
|
|
51
|
+
neither it nor `engine3d/frozenphysics.js` reads model rigs or parts.
|
|
52
|
+
Player always blocks, including when unregistered or declared inert, as do
|
|
53
|
+
requested model clips, follow-camera/own-model actors and registered
|
|
54
|
+
own-model attachments. The model and its references must have no motion, clips, gait
|
|
55
|
+
or biped part ids (`legL`, `legR`, `armL`, `armR`, `torso`), nor parts marked
|
|
56
|
+
`keep`, `tint`, or named `slot-*`. `instanceModels` stays synchronous. Scene
|
|
57
|
+
code opting in must not inspect or alter these deferred actors' visual
|
|
58
|
+
subtrees/parts until they are ready. Colliders, bodies, actor transforms
|
|
59
|
+
and behaviours still initialize and run on their original schedule.
|
|
60
|
+
When `runtime.callsBeforeBehavior === true` explicitly advertises support,
|
|
61
|
+
the runtime's optional `beforeBehavior(actor, name)` fence promotes actors
|
|
62
|
+
that stop being safe to wait immediately before
|
|
63
|
+
instance creation or dispatch. This covers a new registered class, a
|
|
64
|
+
component added during another behaviour's update, enabled transitions,
|
|
65
|
+
direct `behavior()` access, taps and collision callbacks. The previous
|
|
66
|
+
fence is chained and restored when the load is cleared.
|
|
67
|
+
|
|
68
|
+
Older published physics-2d runtimes do not advertise that capability; no
|
|
69
|
+
fence is installed on them. Deferred loading still works: physics-3d checks
|
|
70
|
+
cheap consumer fingerprints before each player update (ordinary and capped).
|
|
71
|
+
Waiters compare component count, membership and each captured registered
|
|
72
|
+
class identity, detecting registration swaps even at unchanged Map size.
|
|
73
|
+
Unchanged waiters allocate no new key list and use one Map lookup per component.
|
|
74
|
+
A remove+add preserving the count promotes conservatively. This path never
|
|
75
|
+
constructs model/node signatures: signatures are still rechecked at fill
|
|
76
|
+
and normal sync. Collision dispatch checks only each pair actor's own wait,
|
|
77
|
+
again before its callback, without visiting unrelated pending keys.
|
|
78
|
+
Taps dispatch inside runtime.update and receive that pre-update check too.
|
|
79
|
+
Thus behaviour registrations and component additions made between frames
|
|
80
|
+
promote before their first callback. The remaining legacy gap is a consumer
|
|
81
|
+
added to a waiting actor and first run within the same runtime.update pass,
|
|
82
|
+
before the next physics-3d check (or a direct nested dispatch inside that
|
|
83
|
+
runtime pass). Such code must call ensureActorModel before using the visual;
|
|
84
|
+
the per-consumer fence closes this gap on runtimes advertising support.
|
|
85
|
+
|
|
86
|
+
Readers that retain, clone or measure another actor's model must call
|
|
87
|
+
`ensureActorModel(world, actorId)` first, then look up its node again. This
|
|
88
|
+
synchronous promotion is exported by `engine3d/modelready.js` and re-exported
|
|
89
|
+
by `world3d.js`; it fills the whole shared key through the normal fill path,
|
|
90
|
+
without draining unrelated keys. It is a no-op for complete/missing actors
|
|
91
|
+
and without the load key. Hub decor, avatar sharing/proxies and idle rig
|
|
92
|
+
readers use it. Companion and wear build independent visuals attached beside
|
|
93
|
+
actor rigs, so do not consume their model; weakest-look sorting skips unbuilt
|
|
94
|
+
models, which have no bake task yet, and reorders when a fill adds tasks.
|
|
95
|
+
|
|
96
|
+
A waiting actor keeps its placed node and an empty rig at the same yOffset
|
|
97
|
+
and scale. The rig and `node.userData.modelParts` Map retain their identities;
|
|
98
|
+
filling adds the model children and Map entries in place. A model reduced
|
|
99
|
+
to nothing by `dropEmptyParts` removes its placeholder rig. `skipEmptyNodes`
|
|
100
|
+
cannot detach a waiting rig as empty. External tier/decor detachment and
|
|
101
|
+
renderSleep remain owned by their controllers: filling does not reattach
|
|
102
|
+
or wake them. Frozen subtrees are thawed and their new matrices updated.
|
|
103
|
+
Every waiting copy's signature is checked again immediately before fill,
|
|
104
|
+
including after another copy's listener ran. A stale signature discards the
|
|
105
|
+
waiting node and rebuilds synchronously through ordinary placement using
|
|
106
|
+
current data. Its fresh root is attached for tier adoption even if the old
|
|
107
|
+
one was detached with renderSleep; the engine leaves the sleep flag owned
|
|
108
|
+
by the controller. This avoids a missing replacement that no controller owns.
|
|
109
|
+
After each waiting actor is filled and its matrices updated, the engine
|
|
110
|
+
dispatches `{ type: 'modelfilled', actorId, node }` on `world.scene` (a
|
|
111
|
+
three.js EventDispatcher). This includes models reduced to empty; it never
|
|
112
|
+
fires for synchronous builds or cancelled waits. Consumers can use
|
|
113
|
+
`world.scene.addEventListener('modelfilled', listener)` to invalidate bounds
|
|
114
|
+
cached under the unchanged node identity, and must remove their listener
|
|
115
|
+
when leaving that world. Hub-game subscribes only while `world.modelLoad`
|
|
116
|
+
exists, drops that node's distance bound and requests a fresh tier pass.
|
|
117
|
+
|
|
118
|
+
The first render arms the queue without building. After subsequent rendered
|
|
119
|
+
frames, eligible keys inside the horizon are prioritized by camera distance
|
|
120
|
+
(the nearest of each key's waiting copies), through the ordinary shared
|
|
121
|
+
`takeModel` path, with ordinary drop-empty and deferred-look handling. All
|
|
122
|
+
waiting copies of that key are filled together, even copies outside the
|
|
123
|
+
horizon. Farther keys remain pending until movement brings a copy in range.
|
|
124
|
+
|
|
125
|
+
The drain measures intervals between actual draws, before deferred look
|
|
126
|
+
baking. If the latest interval exceeds max(2 x the median of the previous
|
|
127
|
+
nine intervals, 50 ms), that frame builds nothing. With fewer samples the
|
|
128
|
+
median uses those available, and the 50 ms floor applies with none. At most
|
|
129
|
+
three consecutive eligible frames are skipped; the fourth builds at least
|
|
130
|
+
one key. On frames that build, another key starts only while elapsed build
|
|
131
|
+
time is below `sliceMs`. A single model build/copy batch is indivisible and
|
|
132
|
+
can overrun the budget; no further key starts after that overrun. Explicit
|
|
133
|
+
`ensureActorModel`, unsafe-consumer promotion and signature rebuilds remain
|
|
134
|
+
synchronous, bypassing horizon and pacing. Waiters acquire
|
|
135
|
+
no shared-build users until filled; removal, rebuild, scene load/swap,
|
|
136
|
+
resident-scene parking and disposal cancel their waits.
|
|
137
|
+
|
|
138
|
+
`world.loadQueue` is a read-only summary `{ pending, near, built, firstKeys,
|
|
139
|
+
deferredKeys }`, counting distinct model keys: pending now, pending inside
|
|
140
|
+
the current horizon, ready so far, ready in the first sync, and ever queued
|
|
141
|
+
respectively. With horizon 0, `near === pending`. Cancellation can
|
|
142
|
+
therefore leave `built < firstKeys + deferredKeys`. The player's `onStage`
|
|
143
|
+
receives `load:first-built` at the end of the first sync and
|
|
144
|
+
`load:rest-built` when the queue empties, with that summary as its second
|
|
145
|
+
argument. Rest-built means construction finished after a draw; the next
|
|
146
|
+
frame shows those last models, and deferred look baking may still remain.
|
|
147
|
+
Horizon-excluded keys are still pending, so `near === 0` alone never emits
|
|
148
|
+
rest-built. Bounds consumers must invalidate cached bounds when a rig fills;
|
|
149
|
+
the hub's distance-tier cache does this via the `modelfilled` listener above.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Scene key: engine.look
|
|
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": { "look": { "bake": "deferred" } }` at the scene file's top
|
|
7
|
+
level (the same `engine` object) asks the engine to draw the scene's models
|
|
8
|
+
before their look is baked. Building a model bakes two things into it
|
|
9
|
+
(`engine3d/look.js`): its soft shading, by casting rays from every vertex
|
|
10
|
+
through a grid of the model's surfaces, and the attributes its outline is
|
|
11
|
+
pushed out by. That is most of what a model costs to build, and all of it
|
|
12
|
+
happens before the first frame: on a slow phone, several seconds of a
|
|
13
|
+
town's load. With the key a model is drawn at once without them, and they
|
|
14
|
+
are baked a little after each frame, nearest the camera first, about 6 ms a
|
|
15
|
+
frame. What a player sees: the scene appears sooner, flat-shaded where
|
|
16
|
+
parts meet and with no outlines, and over the first seconds the shading
|
|
17
|
+
and the outlines come in, model by model. The terms:
|
|
18
|
+
> With the key absent, a model is built exactly as before: the same code,
|
|
19
|
+
> baked before `syncActors` returns. With the key present, a model is built
|
|
20
|
+
> in the same shape, with the same meshes, materials and shader programs
|
|
21
|
+
> (nothing is recompiled when the baking lands), its occlusion all 1
|
|
22
|
+
> (nothing occludes it) and its outline hulls there and not drawn (their
|
|
23
|
+
> material's `visible` is off); once its baking has run, every attribute of
|
|
24
|
+
> every geometry holds what baking at once would have put there, and the
|
|
25
|
+
> hulls are drawn.
|
|
26
|
+
|
|
27
|
+
Any other value of `bake`, or none, is the key absent. It is read when the
|
|
28
|
+
scene loads (`runtime.bakesLookLater`), so it follows a scene switch, and
|
|
29
|
+
it applies to models `syncActors` builds while that scene plays, in the
|
|
30
|
+
play panel, a published deck and the scene editor alike; the model editor
|
|
31
|
+
and thumbnails build their own and always bake at once. A model already
|
|
32
|
+
baked (built for a scene without the key, or one whose baking has run) is
|
|
33
|
+
never unbaked. The other way round, a model built under the key and still
|
|
34
|
+
waiting when a scene without it places the same model in the same world is
|
|
35
|
+
the same shared build: it is drawn unbaked there too until its baking has
|
|
36
|
+
run, which goes on whichever scene plays. Whether a pass bakes later is
|
|
37
|
+
written on the world when `syncActors` starts (`world.bakesLookLater`), so
|
|
38
|
+
a `syncActors` for another runtime entered from inside a pass leaves its
|
|
39
|
+
own answer there for the rest of the outer one: models the outer pass
|
|
40
|
+
builds after it are baked as the inner runtime's scene asked. They end
|
|
41
|
+
the same either way.
|
|
42
|
+
|
|
43
|
+
It goes with `"dropEmptyParts": true`: that key takes the empty groups out
|
|
44
|
+
of a shared build after its look was applied and its baking queued, and the
|
|
45
|
+
baking was written down as geometries and matrices, so with both keys a
|
|
46
|
+
scene ends as it does with `dropEmptyParts` alone.
|
|
47
|
+
|
|
48
|
+
How it goes (`engine3d/lookbake.js` has the queue, the end of `look.js`
|
|
49
|
+
what is queued): one task per model built, cut into steps (the grid, each
|
|
50
|
+
surface marked into it, the rays of 128 vertices, a stretch of 384
|
|
51
|
+
vertices or triangle corners of a geometry's outline attributes, part by
|
|
52
|
+
part for merged parts). After each frame is drawn
|
|
53
|
+
(`renderWorld`), steps are started until 6 ms have gone; a step is never
|
|
54
|
+
interrupted, so a long one overruns and nothing starts after it that frame.
|
|
55
|
+
The frame the queue is first seen bakes nothing, so the first frame is on
|
|
56
|
+
screen first. Tasks are put nearest first whenever the queue has grown, by
|
|
57
|
+
the distance from the camera to the nearest actor placing the model as
|
|
58
|
+
things stood then; they are not re-sorted as the player walks. A task
|
|
59
|
+
bakes from what was written down when the model was built (each surface's
|
|
60
|
+
geometry and where it stood), so a model moved or animated since bakes the
|
|
61
|
+
same. Models sharing a parsed model file share one bake, as before, and a
|
|
62
|
+
geometry is baked once however many copies draw it.
|
|
63
|
+
|
|
64
|
+
`scene.three.lookBake` is null in a world that never built a model under
|
|
65
|
+
the key; otherwise it is the queue: `shown` (true once a frame has been
|
|
66
|
+
drawn with nothing left to bake, false again from the moment a model is
|
|
67
|
+
queued), `pending` (models still to bake), `ms` (time spent baking),
|
|
68
|
+
`baked` and `dropped` (tasks that ran to the end and left the whole of the
|
|
69
|
+
baking in every geometry not disposed, and tasks that did not: the model
|
|
70
|
+
went first, or a geometry was left that could not be written to), and
|
|
71
|
+
`budgetMs`, which a deck may set. **A harness, a screenshot or
|
|
72
|
+
a cover waits for `lookBake === null || lookBake.shown`, not for `pending`
|
|
73
|
+
to reach 0**: the baking is done after the frame is drawn, so the frame
|
|
74
|
+
that brings `pending` to 0 was drawn without the last of it, and it is the
|
|
75
|
+
next one that is the complete picture. A model released, rebuilt (its
|
|
76
|
+
file, its art or the look switch changed) or disposed with its world before
|
|
77
|
+
its task ran is dropped: the task listens for its geometries' `dispose` and
|
|
78
|
+
never writes to one that has been disposed.
|
|
79
|
+
|
|
80
|
+
A geometry replaced while it waits: a copy made with `geometry.clone()`
|
|
81
|
+
waits with the geometry it was copied from, and is given the same occlusion
|
|
82
|
+
and outline attributes when the task runs (in arrays of its own, as a copy
|
|
83
|
+
of a baked geometry has), so a mesh and its outline hull given the copy,
|
|
84
|
+
the first geometry disposed, end as they would in a scene without the key.
|
|
85
|
+
That holds whenever the copy is made (before the task begins or part way
|
|
86
|
+
through it) and whatever it is made from (the geometry, a copy, or either
|
|
87
|
+
one disposed and never written): a task counted in `baked` left every
|
|
88
|
+
geometry of its model that is not disposed, copies included, fully baked.
|
|
89
|
+
The engine does this itself for a part that glows. While it waits a
|
|
90
|
+
geometry has a `clone` of its own for this; it goes when the task ends, and
|
|
91
|
+
a `clone` kept hold of and called afterwards is the ordinary one.
|
|
92
|
+
Anything else put in a waiting geometry's place (a geometry built
|
|
93
|
+
separately, `copy()` into another one, or a copy whose vertices were then
|
|
94
|
+
replaced by a different number) is not written to: it keeps the occlusion
|
|
95
|
+
it came with, and an outline hull drawn from it has no outline attributes.
|
|
96
|
+
A task that ends with such a copy not disposed counts in `dropped`.
|
|
97
|
+
When the waiting geometry and every copy of it are gone before the task
|
|
98
|
+
runs, the hull's material is left not `visible`, so that hull has no
|
|
99
|
+
outline rather than a wrong one; a deck that swaps in its own geometry
|
|
100
|
+
under the key bakes it itself (`addOutlineAttributes`, engine3d/look.js)
|
|
101
|
+
and shows the hull. And a waiting geometry disposed while a mesh still
|
|
102
|
+
draws it is never baked, where without the key it would already have been.
|
|
103
|
+
|
|
104
|
+
`scripts/test-look-bake.mjs` holds all of it, and holds what a build
|
|
105
|
+
without the key gives to a number (`BAKED_AT_ONCE`, a digest from
|
|
106
|
+
`scripts/look-baseline.mjs` of every kit model built at once): change it
|
|
107
|
+
only in a commit that means to change what the look bakes into a model.
|
|
108
|
+
|
|
109
|
+
Do not set it if deck code reads `lookOcclusion`, `lookOutlineNormal` or
|
|
110
|
+
`lookOutlineReach`, or sets `visible` on an outline hull's material, in the
|
|
111
|
+
first seconds of a scene; and a screenshot or cover taken before
|
|
112
|
+
`lookBake.shown` is true shows the unbaked picture. Opt in when a
|
|
113
|
+
scene is many models and the load on a slow phone matters more than the
|
|
114
|
+
first seconds' polish; a small scene gains nothing.
|