castle-web-cli 0.4.233 → 0.4.234
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/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 +260 -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 +50 -4
- package/kits/base/sdk/multiplayer.d.ts +7 -1
- package/kits/base/sdk/multiplayer.js +140 -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 +1257 -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 +819 -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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The hub-game contract
|
|
2
2
|
|
|
3
|
-
**Version 1.
|
|
3
|
+
**Version 1.145** (2026-10-17; v1 plus the optional additions under "Changes in
|
|
4
4
|
v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
|
|
5
5
|
`cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
|
|
6
6
|
contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
|
|
@@ -37,6 +37,8 @@ curation where it cannot:
|
|
|
37
37
|
|
|
38
38
|
```jsonc
|
|
39
39
|
"hub": {
|
|
40
|
+
"tiers": true, // optional; required when quality is present
|
|
41
|
+
"quality": { "low": { "decor": "skip", "players": 8, "labels": 8, "spawned": 8, "farMindsHz": 4, "physicsHz": 15 } }, // optional v1.137; physicsHz reserved, no effect yet
|
|
40
42
|
"contract": 1, // required; the version this deck was written against
|
|
41
43
|
"title": "Foot Race", // ≤ 40 chars; the door cover, the result ribbon
|
|
42
44
|
"scene": "scenes/main.scene", // optional; the place's scene (default: editor.defaultPlayFile, then scenes/main.scene)
|
|
@@ -55,12 +57,19 @@ curation where it cannot:
|
|
|
55
57
|
"score": { "unit": "ms", "better": "lower", "min": 0, "max": 600000 },
|
|
56
58
|
"stats": { "laps": "number", "kart": "string" }
|
|
57
59
|
},
|
|
60
|
+
"analytics": true, // optional v1.93 server analytics
|
|
61
|
+
"bringFriend": true, // optional v1.113 root invite actions and exact-run routing
|
|
62
|
+
"fpsTelemetry": { "buildSha": "<40 lowercase hex>", "scene": "scenes/main.scene" }, // optional FPS summaries
|
|
63
|
+
"analyticsV111": true, // optional v1.111 Ghost invite/admission events; requires analytics
|
|
64
|
+
"loadTelemetry": true, // optional v1.138 town load-abandoned events; requires analytics and analyticsV111
|
|
58
65
|
"sign": { "model": "models/sign.pxmodel", "board": "score" }, // optional
|
|
59
66
|
"npcs": { "route": "town", "slot": "square", "turnsPerMinute": 6 }, // optional; §13
|
|
60
67
|
"fallY": -10, // optional (v1.1); below this a player has fallen (§5)
|
|
68
|
+
"defaultEnvironment": false, // optional (v1.135, root only); disable the fallback picture and fall fade (§5)
|
|
61
69
|
"house": { "devOwner": "first" }, // optional (v1.67); first arrival owns a dev house (§4)
|
|
62
70
|
"actions": true, // optional (v1.74); private action chips (§9)
|
|
63
71
|
"resume": { "keep": true }, // optional (v1.89), retain a short-drop visit; true keeps v1.72 leave/re-arrive (§12)
|
|
72
|
+
"resumeVisibility": true, // optional (v1.116), retain and synchronously rebuild private actor masks (§12)
|
|
64
73
|
"menu": true, // optional (v1.79); private place menu (§9)
|
|
65
74
|
"ask": true, // optional (v1.75); private text prompt (§9)
|
|
66
75
|
"decor": { "grid": { "origin": "floor", "w": 8, "d": 7, "cell": 1 }, "layers": ["rug", "floor"] }, // optional (v1.67); §10
|
|
@@ -78,6 +87,7 @@ curation where it cannot:
|
|
|
78
87
|
"stuck": true, // optional (v1.33); a town offers a player who walks and gets nowhere the way back to its arrival (§5)
|
|
79
88
|
"labels": "near", // optional (v1.43); a town's labels near the player only, never overlapping, three at most (§10)
|
|
80
89
|
"soundscape": true, // optional (v1.42, v1.49); babble, footsteps, opt-in zone beds/music, surface maps and UI cues, client only (§6)
|
|
90
|
+
"weeklyCup": true, // optional (v1.112); weekly boards, clock and server-only player results (§4)
|
|
81
91
|
"unlocks": [ // optional (v1.53, v1.70/v1.73); at most 8 wearable + 6 furniture/deed + 16 pet items (§11)
|
|
82
92
|
{ "id": "cove-3-wins", "class": "badge", "shape": "badge-round", "name": "Cove Ace", "deed": "win 3 races in Cove", "color": "#3aa0d8" },
|
|
83
93
|
{ "id": "farm-planter", "class": "furniture", "piece": "planter", "name": "Crate Planter", "deed": "buy at the Willowbank stand for 300 coins", "color": "#8a5a2b" },
|
|
@@ -102,6 +112,10 @@ reading the saved deck, treats the same list as no unlocks at all.
|
|
|
102
112
|
|
|
103
113
|
| field | type | rule |
|
|
104
114
|
| --- | --- | --- |
|
|
115
|
+
| `frameBatch` | true | v1.106, top-level: paced player envelopes from the first packet, one normal frame per player per tick, FIFO replay paced against an aggregate byte bucket. Visit controls take priority over replay. Requires updated real-time and multiplayer-3d decoder imports; ACK timing never bypasses pacing. Absent key preserves existing bytes and order. |
|
|
116
|
+
| `fpsTelemetry` | absent | Optional main-place FPS summaries; requires `analytics: true`, a full lowercase `buildSha` and the main `scene`. Client message `hub-fps` carries only validated numeric measurements and that fixed scene; Ghost stamps pinned build attribution on kind 26. See [analytics](analytics.md). |
|
|
117
|
+
| `loadTelemetry` | true | v1.138, main place only; requires `analytics: true` and `analyticsV111: true`. The server reports kind 27 `load_abandoned` for a transport connection that leaves or waits 30 s without arriving (checked on every transport tick, before the simulation exists too); the snapshot's `hubPlace.loadTelemetry` tells the browser to send `{ k: 'hub-load', stage: 4 }` once when its body is placed before `hub-arrived`. Not in houses. See [analytics](analytics.md#load-abandoned-v1138). |
|
|
118
|
+
| `analyticsV111` | true | v1.111, main place only and requires `analytics: true`: Ghost-owned invite lifecycle, arrival-source and public-join-failure events. Server-config/pin only; no host-spec or client-wire field. Absent preserves all v1.93 behavior and emits none of kinds 21–25. See [analytics](analytics.md). |
|
|
105
119
|
| `contract` | integer | `1`. A deck naming a version the kit does not know is refused (check fails; the server logs and runs nothing). |
|
|
106
120
|
| `title` | string | 1-40 chars. |
|
|
107
121
|
| `scene` | string | a `scenes/*.scene` path the deck has. |
|
|
@@ -114,7 +128,7 @@ reading the saved deck, treats the same list as no unlocks at all.
|
|
|
114
128
|
| `sign` | object | `model`: a `.pxmodel` the deck has; `board`: `"score"` or a declared numeric stat. |
|
|
115
129
|
| `places` | object | §3. |
|
|
116
130
|
| `npcs` | object | §13. |
|
|
117
|
-
| `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default:
|
|
131
|
+
| `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: -20. |
|
|
118
132
|
| `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. v1.22 adds two, each optional: `reach`, 1.6-3 m, how far (flat, from the object's near side) an object is offered, and `steady`, true or false, an offer that holds through a moment at its edge (§6). Left out (or `steady: false`), neither is sent to the client nor changes anything: the place is offered, sent and drawn exactly what it was. v1.25 adds `keepHeld`, true or false: a held object stays its holder's, whoever stands nearer (§6); left out or `false`, a place is sent, simulated and drawn exactly as it was. `false` or absent: no grabbing (§6). |
|
|
119
133
|
| `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds }`: `emotes` and `seats` true or false (default false), `sounds` up to 16 different `.mp3`/`.wav`/`.m4a` paths (lower-case extensions, as the engine bundles them) of this deck that `hub.sound` may play (each at most 256 KB, 1 MB in all, checked at publish). `false`, absent or all off: none of it (§6). |
|
|
120
134
|
| `hud` | object | v1.26. `{ clear }`, `clear` true or false (default false; `false` and `{}` are the same as leaving `hud` out). `true`: the place's HUD is laid out to stay short and what the hub draws over the world is kept out from under it (§9, "A clear HUD"). Client only: the server reads it, tells the client, and does nothing else by it. A place without it is sent and drawn exactly what it was. |
|
|
@@ -122,15 +136,24 @@ reading the saved deck, treats the same list as no unlocks at all.
|
|
|
122
136
|
| `companion` | boolean or object | v1.71, a place's (`hub.companion` or `hub.places.<id>.companion`): `true` enables the private companion (§9); `{ "chat": { "character": "companion", "name": "Chirp" } }` also enables owner-only NPC chat (§13). Chat needs `npcs` configured; unknown keys at either nesting level are errors. `character` names an id in the deck's `characterBundle` (non-blank, up to 100 characters / 128 UTF-8 bytes, no NUL); `name` is non-blank, 1..24 code points with no control characters. Leave the key out to disable it. Absent: no API, private state, drawer, message or `hubGlow`; existing wire bytes stay identical. |
|
|
123
137
|
| `visibility` | boolean | v1.91, per place: `true` enables the client visibility signal and server `visibility` hook (§12). Any other value is an error. Absent: no listener, signal, hook dispatch, state or wire field. |
|
|
124
138
|
| `resume` | true or object | v1.72, a place's (`hub.resume` or `hub.places.<id>.resume`), valid only on a place with `result`: `true` says the place's game handles a player's return within a round, so a player the platform let go and who comes back under the same player id is arrived again once (§12, `hub-hello`). The visit goes on: one result per visit (a second `hub.result` is refused, a result reported in `leave` included), one deadline from the first arrival, the end sent again to an ended visit, and the first door kept. v1.89 also accepts exactly `{ keep: true }`: retain the player entry for a same-id reconnect within 60 seconds of observed absence, with no `leave` or `arrive`; see §12. Other values, extra object keys, or the key on a place without `result` are manifest errors. Absent: a game takes no same-id re-hello and no late greet (unchanged), with no extra state, message, field or listener; existing wire bytes stay identical. |
|
|
139
|
+
| `resumeVisibility` | true | v1.116, per place, server-only, and valid only with `resume: { keep: true }` and an exported `resume` hook: preserve an authenticated player's per-viewer `hub.hide/show` overrides during that retained visit's strictly less than 60-second absence. On return the stale replay and action dispatch are held, the authored `resume` hook runs before the next authored `step`, and the resulting whole override is sent (§10/§12). Blocked preparation or a synchronous hook throw ends and forgets only the affected retained visit before authored stepping; the place never waits. The hook must synchronously rebuild current masks before returning or first awaiting. The trusted account must still match; changed identity receives only a clear. Explicit travel, expiry, shutdown and ordinary forget delete the cache. Disconnected targets remain ignored. Any value but `true`, or use with another retention mode, is a manifest error. Absent: resume ordering, cleanup and wire behavior stay unchanged. No new public manifest or wire field. |
|
|
140
|
+
| `resumeArrivalPose` | true | v1.117, optional per place: preserve only the last server pose/facing for a same-player-id, same signed-in account reconnect strictly within 60 wall-clock seconds. Ordinary immediate `leave` and fresh `arrive` still run; the pose replaces normal placement after `arrive`. Result places also require `resume: true`. Cannot combine with `resume: { keep: true }`, `resumePose`, or `houseResume`. Server-only; absent leaves state, lifecycle and wire bytes unchanged. See §12. |
|
|
141
|
+
| `resumePose` | true | v1.98, per non-result place only: retain a same-id visit and its last pose/facing for strictly less than five wall-clock minutes, restoring before hello replay or the deck step. No leave/arrive on retention; explicit kit travel, expiry and shutdown still leave, and new IDs may restore a server-stored pose for the same account/place within ten minutes of departure; kit travel clears it. Absent: no retention state or behavior change. Server-only; no new wire fields. See §12. |
|
|
142
|
+
| `talkLog` | true | v1.101, per place: NPC talk input and replies append to the platform’s private indefinite archive. Authored answers/openings wait for durable acknowledgment; model input/reply commit with their jobs. No player read API or TTL. Requires a host/runtime that offers transcript support; unavailable writes stop the answer. Absent key performs no archive requests and preserves existing protocol. |
|
|
143
|
+
| `under13Choices` | true | (v1.142) Published mind `childAsks` take precedence in every place (§13); otherwise v1.101, per place: NPC conversations for a player whose trusted server identity has `under13 === true` offer three canned lines and hide the text field. Both authored and model admission paths reject other words. Missing age stamp defaults false. Absent key preserves existing UI and protocol bytes; no client age inference. |
|
|
144
|
+
| `freshFriends` | true | v1.99, per place: positive and negative friend permissions expire after 31 seconds. Expired entries revalidate before returning a friend; refusal, malformed reply or a 900 ms timeout returns no friends. The shared read latch preserves the 31-second minimum read gap. Server-only `hub.freshFriends === true` is exposed only in opted-in places; absent keys retain existing cache, API and wire behavior. |
|
|
125
145
|
| `menu` | boolean | v1.79, a place's (`hub.menu` or `hub.places.<id>.menu`): only `true` enables a private place menu (§9). Any other value is a manifest error. Absent: no API, menu hook lookup, private state, chrome, message, snapshot or delta key; existing wire bytes stay identical. |
|
|
126
146
|
| `ask` | boolean | v1.75, a place's (`hub.ask` or `hub.places.<id>.ask`): only `true` enables a private text prompt (§9). Any other value is a manifest error. Absent: no API, answer hook lookup, private state, chrome, message, snapshot or delta key; existing behavior and wire bytes stay identical. |
|
|
127
147
|
| `ballot` | boolean or object | v1.68, a place's (the main block or a place under `places`). `true` (the card with no lines: faces and options only), or `{ lines }`: at most 32 lines, each `{ id, text, about }` -- `id` `[a-z0-9-]`, 1-24 characters, never twice; `text` 1-40 characters on one line (trimmed); `about` `"face"` (said about a player whose face is tapped first: "I saw them by the boat") or `"self"` (said by the speaker alone: "Not me!"). Any other key, here or in a line, is a manifest error. These lines are the only words a player can send through the card (§6, "The choice card"). `false` or absent: no card, no message, no snapshot field, no chrome; the place is sent and drawn exactly what it was. The client is told the lines in `hubPlace.ballot`. |
|
|
128
148
|
| `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
|
|
149
|
+
| `quality` | `{ low: { decor, players, labels, spawned, farMindsHz, physicsHz? } }` | v1.137, root only, requires `tiers: true`; client-only Low build/draw budgets. Unknown keys refused. See "v1.137 hub.quality" below. `physicsHz` is reserved, no effect yet. Absent quality preserves previous behavior and bytes. |
|
|
129
150
|
| `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes (v1.69: and its kit sky is not drawn on Low). v1.30: an actor in a scene file may carry `"tier": "keep"` -- a field of the actor beside `id` and `components`, not a component -- and is then drawn on every tier at any distance, whatever its components; a place's ground (paving, grass, merged dressing: plain `Transform`/`Shape`/`Model`) needs it, or Low draws the place standing on nothing. The mark is read from the scene file, so it says nothing of an actor spawned while playing (those were never hidden); v1.63: `"tier": "near"` instead treats a non-NPC actor as scenery on Low, whatever its components: its node is taken out beyond 30 m of its bounds (the same sized test as static scenery) and put back within that distance. High never hides it; NPCs retain their own 20 m rule, and `keep` wins (the field carries one mark). v1.69: `"tier": "low"` draws an authored actor only on Low, at any distance, without the decoration/scenery/NPC distance rules; High removes its node from the scene graph, and switching back to Low restores its original parent. On High the node is drawn in the one frame that built it (a scene load, or the actor's rebuild): the tier rules run before the engine builds nodes. The place's per-viewer hiding and visibility cells still apply on Low. Low also draws no `engine.sky` dome at all (no drawing, zone stepping or texture uploads), in whatever scene plays, the frame of a scene load included; High draws the zone skies as authored. Both change on the frame after Graphics or the auto judge changes tier. A scene may therefore provide the kit sky for High and a cheap sky actor marked `"tier": "low"` for Low. No physics-3d change: while Low, hub-game puts an own `sky` of null on the scene runtime, over the getter the engine reads each frame, and deletes it on leaving Low; a device that is never Low has no such property. A scene with no low mark draws on High exactly as before, and a scene without the sky key draws on Low exactly as before. Labels, colliders and server state are untouched. Any other value, or none, is an actor as before. The scene editor has no control for it (it is written in the file) and keeps it through a save, and a duplicated actor carries it. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. v1.64: a scene file may carry a top-level `cells` key beside `engine` and `actors` -- `{ version: 1, eyeMax, hysteresis, cells: [{ id, outline: [[x, z], ...], sees: [ids], why? }] }`, outlines partitioning the ground (x east, z south), `sees` the cells visible from somewhere in that one -- and an actor a `cell` field beside `id` (`"n-plaza"`, or a list for one spanning several). On Low only, an eye outside every outline or at a non-finite place has no cell, whatever the hysteresis; otherwise the camera's cell is the one its x, z is in, kept while the eye is inside it or within `hysteresis` m of it. An authored, tagged actor none of whose cells that cell sees is not drawn, `"tier": "keep"` and `"tier": "near"` included: keep exempts distance, not what is in the way (a list is drawn when any of its cells is seen). Only an inert actor is ever out for its cell: every component it has now is one of `Transform`, `Shape`, `Model`, `Solid`, `Lookable`, `RouteAnchor`, `WalkSurface` (`CELL_INERT`; a Lookable's words are read from the scene data either way) and none is in the backstop `CELL_PROTECTED` (`HubDoor`, `HubPad`, `HubNpc`, `Body`, `Player`, `Ball`, `HubSpin`, `TownHats`, `TownStamp`, `TownHatMat`, `TownWardrobeMat`, `TownWardrobeItem`, `TownWardrobe`). Anything that reacts to a player or the server or that something moves (a seat, a sign, a court piece, a statue, any other `Hub*`/`Town*` or unknown component), or an actor with no components, is never out for its cell, whatever its `cell` or `tier` says, and the other Low rules apply to it as before. This is decided from the actor's current components on every look, never remembered: an actor replaced under the same id, or given a component while playing, is decided again on the next look. An eye above `eyeMax` or with no cell, or a game through a door: the cells hide nothing. A malformed table (another version, a cell without a string id, an outline of three or more finite pairs or a `sees` of known ids that includes its own, a duplicate id, a non-finite `eyeMax`/`hysteresis`) is no table; a `cell` that is empty, not strings, or names an unknown id is no cell. `?hubcells=1` shows an overlay (the cell, what is out and why, the last change). Nothing on the wire; a scene without the key is drawn exactly as before. `false` or absent: none of it. |
|
|
130
151
|
| `yourGames` | boolean | v1.54, the deck's (not a place's). `true`: signed-in players in towns get private hearted/recent door rows, account hearts and an arrival offer (§5). `false` or absent: no command, message, UI or storage read; the deck draws exactly what it did. |
|
|
152
|
+
| `safeInsets` | boolean | v1.123, deck-only and client-only. `true`: §9 safe edges, reserved host corners and complete measured chrome. Absent/false preserves the previous rendering; no server or `hubPlace` field. |
|
|
153
|
+
| `playCards` | boolean | v1.122, the deck's. `true`: §6 play cards go to mutual friends and party members anywhere in the layer; strangers must be within 12 m in x/z when the phrase arrives. At most one stranger card is retained at a time, and each stranger can offer one per 60 s across all doors. Absent/false preserves the v1.11 cards and cooldown per player and door. Bubbles, feed and block filtering are unchanged. |
|
|
131
154
|
| `cues` | boolean | v1.23, the deck's (not a place's). `true`, in a town (a place with no `result`): (a) while someone in the roster with a known user id is not named by the host as a friend, the host is asked for the player's friends again a few times in the ~16 s after they were first seen (at about 1, 3, 9 and 15 s -- v1.32; 1, 5, 10, 16 in v1.31; 2, 6, 11 and 17 s before, when the host learned who is in a town only on its heartbeat; those here when the player came in count from then), because the host names a friend only once it knows both are in the town (within a few seconds in the same layer, on its heartbeat across layers) -- never while an ask is out, at most two such asks in any 8 s and 2 s apart however many come in (one in 4 s before v1.32), stopping when the host names them or they leave, the ordinary 20 s ask after that, and a friend already here when the player came in is announced as one who arrives later is ("amy is here · People to join", pointed to), once per friend per session and not where "You're next to amy" said it; (b) the chat field's placeholder says who reads a line ("To your follows…"; the whole sentence is its accessible label) or, disabled, "Friends only" with one sentence as its note and label whatever the reason, so neither tells which it is (v1.29: "Typed chat is for friends who follow each other. Emotes work with everyone."; before v1.29 "No follows here" / "Chat not available" and the longer notes), and the host is asked for chat peers within about a second of someone coming in; (c) "Let's play…" names the door of the speaker's open party proposal before the door they stand by; (d) a party that gains a member says so ("You joined amy's party", "bo joined your party"); (e) v1.29: a player back from a game through one of the town's doors is asked, for 20 s and after any invitation or party proposal, "Play <door> again?" -- Play again is the Doors list's Go for that door (onto its pad; in a party, and for a door that is not `solo`, "Play <door> again together?" / Go together, which proposes it to the party), Not now puts it away. Who is a friend is only what `Hub.friends` already says, and a party is the place's own; chat's rules are ghost's, unchanged. `false` or absent: none of it -- the deck is sent and draws exactly what it did. |
|
|
132
155
|
| `stuck` | boolean | v1.33, the deck's (not a place's). `true`, in a town (a place with no `result`): a player who has given 3 s of walk input within the last 8 s (v1.39: counted across the breaks; 3 s without a break before) while their body got less than 1 m from anywhere it was in that stretch (v1.39; within 0.3 m of where it began before) is offered a chip, "Stuck? Tap to go to the square", and the Doors list gains a "Stuck?" row over its doors; a tap on either has the place put that player back at its arrival, or (v1.39) at the spot its `unstick` hook picks for them (§5 "Stuck?": once in 5 s, never a held player). Nobody is moved without their tap. The chip names the arrival by the place's own `where` word for that spot without its first word ("in the square" → "the square"), and reads "Stuck? Tap to go back to the start" where the place has none. Never in a game (a place with a `result`), whatever the deck says. `false` or absent: none of it -- no chip, no row, no message, and the deck is sent and draws exactly what it did. |
|
|
133
|
-
| `labels` | `"near"` | v1.43, the deck's (not a place's) and the client's alone, like `tiers`: the server reads nothing of it and `hubPlace` does not carry it. In a town (a place with no `result`) the labels `hub.label` puts over scene actors are kept near the player and apart (§10 "Labels kept near"). Any other value is refused;
|
|
156
|
+
| `labels` | `"near"` | v1.43, the deck's (not a place's) and the client's alone, like `tiers`: the server reads nothing of it and `hubPlace` does not carry it. In a town (a place with no `result`) the labels `hub.label` puts over scene actors are kept near the player and apart (§10 "Labels kept near"). Any other value is refused; without it, the default world label focus applies |
|
|
134
157
|
| `soundscape` | boolean or object | v1.42, the deck's (not a place's): synthesis belongs to the client; only the optional v1.50 `cues` part is read by the server and sends named cue messages. `true`, or `{ babble, steps }`, each true or false and on when left out (`{}` is `true`; `false` is the same as leaving the key out). In every place of the deck: NPC lines are voiced as babble, footsteps sound under the player and those near them, and the chrome has a sound control (mute, volume) that also scales the place's own `hub.sound` files (§6, "The soundscape"). v1.49 adds optional `zones` (a scene component name), `ambience: { beds, default, spots, music }`, object `steps: { default, zones, paths }` and boolean `ui` (§6). These fields alone opt into ambience, music, mapped surfaces and UI cues; `true` enables only babble and street steps, including the lighter v1.50 footfall body. v1.50 adds explicit boolean `cues` for named place cues and client-observed actions; it is independent of `ui` and never implied by `true`. Unknown keys, bed or surface names and wrong types are check failures. Without the key nothing of it exists: no audio context, no listener, no storage read, no control, and the place's sounds play exactly as they did. |
|
|
135
158
|
|
|
136
159
|
Unknown keys are a check failure, not ignored: a typo in a contract field must
|
|
@@ -186,8 +209,8 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
186
209
|
| hook | when |
|
|
187
210
|
| --- | --- |
|
|
188
211
|
| `ready(hub)` | the world is built, before the first tick |
|
|
189
|
-
| `arrive(hub, group)` | players with bodies who arrived together this tick: `[{ playerId, username, userId, from, fromDeckId, near, carry }]` (`userId` v1.2: a signed-in player's user id, null for an anonymous one). `from` is the door they came in by; `near` the user id of the friend they jumped to (Join), or null; `carry.result` what they bring back from a game (§7). The kit has already placed them at the arrival (§5), and a player who jumped to a friend in this session beside that friend, facing them; a hook may place them elsewhere (v1.40: wherever the hook leaves them is where they are kept
|
|
190
|
-
| `resume(hub, { playerId })` | v1.89, optional: an already-arrived player sent a fresh or resume hello under their retained id.
|
|
212
|
+
| `arrive(hub, group)` | players with bodies who arrived together this tick: `[{ playerId, username, userId, from, fromDeckId, near, carry }]` (`userId` v1.2: a signed-in player's user id, null for an anonymous one). `from` is the door they came in by; `near` the user id of the friend they jumped to (Join), or null; `carry.result` what they bring back from a game (§7). The kit has already placed them at the arrival (§5), and a player who jumped to a friend in this session beside that friend, facing them; a hook may place them elsewhere (v1.40: wherever the hook leaves them is where they are kept, as after a jump, until their client reports from there (at most 4 s): the body is put back each tick a late move report pulls it off the spot) |
|
|
213
|
+
| `resume(hub, { playerId })` | v1.89, optional: an already-arrived player sent a fresh or resume hello under their retained id. Normally called after that step's private-channel replay sends, once per id per step. v1.116 `resumeVisibility: true` calls it before the next authored `step` and retained visibility replay, requiring synchronous preparation. First arrivals, genuine re-arrivals and avatar-change (`again: true`) hellos do not call it. Restore deck-owned HUD or pointer state here; this is neither `arrive` nor `leave`. Hook presence opts in, including in towns without a `resume` manifest key. See §12. |
|
|
191
214
|
| `step(hub, dt)` | after each physics step; `dt` seconds |
|
|
192
215
|
| `fall(hub, playerId)` | v1.1: a player fell below the place's `fallY` (§5); place them somewhere, or the kit puts them back at the arrival |
|
|
193
216
|
| `carry(hub, playerId, carry)` | where the host has hub ops: what an already-arrived player brings back, when ghost's read came after the arrival window (§7) |
|
|
@@ -209,7 +232,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
209
232
|
| `npcContext(hub, npc, playerId)` | v1.8: what an NPC's mind should know right now while `playerId` talks to it (§13 notes): a string of at most 700 characters, or null for none. Read when the conversation opens and every second while it lasts |
|
|
210
233
|
| `npcAsks(hub, npc, playerId)` | v1.80: questions the place keeps on offer while this player talks to the NPC's mind (§13): `{ persistentAsks: string[] }` or null. Re-read with each notes check; up to two strings, trimmed and cut to 40 characters, deduplicated after cutting. Private to that player in `hub-npc-notes`; lead the three-chip refill row and may return after being sent while still offered. Null clears them. Synchronous; async results are ignored and rejected promises caught; errors log once with fixed words. Absent: no new message key or refill behavior |
|
|
211
234
|
| `npcHeard(hub, npc, playerId, { text, conversation })` | v1.8: a turn to an NPC's mind was admitted; `text` is the player's own words (§13), for place state a conversation may change. v1.47: `conversation` is captured at admission and matches `npcOpening`'s; after the send settles, the hook runs only if that conversation still belongs to the same account and body |
|
|
212
|
-
| `npcOpening(hub, npc, playerId, { met, greeting, conversation })` | v1.37: what an NPC says first when `playerId` opens its chat, and what they might ask it (§13): `{ text, asks, more }`, a string (the words alone), or null. `text` is cut at 240 characters; `asks` is up to three questions of at most 40 characters each (longer ones are cut, repeats and extras dropped). v1.46: `more` is up to nine later questions with the same cut, deduped against `asks`; sent only when non-empty. Shown in that player's panel at once, to them alone, with no model called. A tap on a question sends it as the player's own words by the ordinary path (range, budget and age rules unchanged); after a reply the chips return (§13). `met`: this player has said something to this NPC since the place's server started (by account; a place that remembers longer keeps its own record); kept only where the hook exists. With a mind and `npcContext`, the opening is added to that conversation's notes so the mind knows what it said. An NPC with no mind and an opening says no `npcLine` hello as well. v1.46: no hook or no usable text gives a mind the kit's default opening; a body without a mind keeps its hello line. A hook's text and questions are its own, with no defaults added. v1.47: `conversation` is an integer increasing with every open of this NPC, so a place can match later words to its opening. `greeting` is this speaker's cached next greeting or null; when present it replaces the opening text, keeping the place's asks and more (§13). Async results are unsupported and ignored; rejected promises are caught and logged once with fixed text |
|
|
235
|
+
| `npcOpening(hub, npc, playerId, { met, greeting, conversation })` | v1.37: what an NPC says first when `playerId` opens its chat, and what they might ask it (§13): `{ text, asks, more }`, a string (the words alone), or null. `text` is cut at 240 characters; `asks` is up to three questions of at most 40 characters each (longer ones are cut, repeats and extras dropped). v1.46: `more` is up to nine later questions with the same cut, deduped against `asks`; sent only when non-empty. Shown in that player's panel at once, to them alone, with no model called. A tap on a question sends it as the player's own words by the ordinary path (range, budget and age rules unchanged); after a reply the chips return (§13). `met`: this player has said something to this NPC since the place's server started (by account; a place that remembers longer keeps its own record); kept only where the hook exists. With a mind and `npcContext`, the opening is added to that conversation's notes so the mind knows what it said. An NPC with no mind and an opening says no `npcLine` hello as well. v1.46: no hook or no usable text gives a mind the kit's default opening; a body without a mind keeps its hello line. A hook's text and questions are its own, with no defaults added. v1.47: `conversation` is an integer increasing with every open of this NPC, so a place can match later words to its opening. `greeting` is this speaker's cached next greeting or null; when present it replaces the opening text, keeping the place's asks and more (§13). Async results are unsupported and ignored; rejected promises are caught and logged once with fixed text. v1.148: `authored: true` (with non-empty `asks`) says the place answers those asks itself through `npcLine` `why: 'authored'`, so a speaker under 13 may tap them (§13) |
|
|
213
236
|
| `npcTools(hub, npc, playerId)` | v1.66: what an NPC's mind may look up while it answers this player (§13 tools): up to 8 `{ name, description, input_schema }`, read when a turn is admitted and sent with it. `name` matches `^[A-Za-z][A-Za-z0-9_]{0,31}$` and is not `perform_action` or `capture_claim`; `description` is 1-300 characters; `input_schema` a JSON-schema object of at most 1 KiB; the list at most 6 KiB. A bad entry is dropped, never the turn; a hook that throws or returns no entries leaves the turn as it was. Without it a turn is sent exactly as before |
|
|
214
237
|
| `npcTool(hub, npc, playerId, name, input)` | v1.66: the mind's one lookup for a turn this place admitted (§13 tools): `name` is one the turn declared, `input` the mind's object. Return a string or a JSON value (or a promise of one), at most 1 KiB once serialized; it goes to the mind alone. Answered within 1.5 s or the mind answers without it. Must never carry player-typed text. Called at most once per turn, and only for that turn's speaker |
|
|
215
238
|
|
|
@@ -226,9 +249,12 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
226
249
|
| `hub.session`, `hub.sim` | the Castle session and the multiplayer-3d simulation |
|
|
227
250
|
| `hub.place` | `{ id, title, scene, manifest }` |
|
|
228
251
|
| `hub.now` | simulation milliseconds |
|
|
229
|
-
| `hub.players()` | `[{ playerId, username, userId, at, arrivedAt }]` for players with bodies (`userId` v1.2, null for an anonymous player) |
|
|
252
|
+
| `hub.players()` | `[{ playerId, username, userId, at, arrivedAt }]` for players with bodies (`userId` v1.2, null for an anonymous player). `at` is the client's last accepted report: an input, never evidence of where a player walked (v1.141, `hub.observed`) |
|
|
230
253
|
| `hub.actorsWith(component)` | scene actors carrying a component: `[{ id, props, t, shape, body }]`: `props` the component's, `t` the Transform, `shape` the Shape's `{ kind, width, height, depth, radius }` or null, `body` the Body type or null (v1.1: a marker need not repeat its actor's size) |
|
|
231
254
|
| `hub.placeAt(playerId, at, facingDeg?)` | move a player's body; reaches the client as a clamp |
|
|
255
|
+
| `hub.observed(playerId)` | v1.141: the kit's observed position, `{ at, step, ok, travel, since, speed }` (copies), or null for a player with no body here. Once a tick, after physics and before any authored `step`, each body's move is checked against a walker's allowance (the scene Player's `speed` × the player's `hub.tune` speed × 1.25) and spent from one signed walking credit: funded, unfunded or rejected; `travel` counts only funded walking since the last reset (a placement, a new body). A door scores from this, never from `player.at` or `hub.players()[i].at`. Lazy: nothing is kept until a place first calls this or `hub.station`. See [observed progress](observed-progress.md) |
|
|
256
|
+
| `hub.station(id, { at: { x, y, z }, radius, height? } \| null)` | v1.141: declare (or with `null` remove) a vertical cylinder a door scores, `height` 2 by default; id 1-64 letters, digits, `_ . : -`; at most 64; radius and height above 0 and at most 200 m. The same shape again changes nothing; a new shape zeroes every player's dwell there. True when taken; a bad call warns once and returns false |
|
|
257
|
+
| `hub.dwell(playerId, id)` | v1.141: `{ inside, entered, ms }` at a station, or null. `entered` only after the player walked out beyond `radius + 0.25` m and back within `radius` by funded steps (the player's signed walking credit not below zero); `ms` the sim time they have stayed entered on funded, present ticks. A reset, an unfunded step or a rejection clears it, and a placement elsewhere clears it at once, inside the same tick (the next pass resets at the placement's destination) |
|
|
232
258
|
| `hub.hold(playerId, at?, facingDeg?)` / `hub.release(playerId)` | hold a player still (§8) |
|
|
233
259
|
| `hub.setHud(spec, playerId?)` | the declared HUD, for everyone or one player (§9) |
|
|
234
260
|
| `hub.hide(actorId, options?)` / `hub.show(actorId, options?)` | server-declared actor visibility (§10); v1.62 `{ to: [playerIds], clear?: boolean }` overrides visibility for those connected viewers only. `clear: true` restores their shared view. True when taken; invalid actor/options or more than 256 overrides per player warn once and return false, changing nothing. Without options, the shared operation is unchanged |
|
|
@@ -243,20 +269,24 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
243
269
|
| `hub.emote(playerId, id)` | v1.6, a place with `idle.emotes`: play a kit emote (`"wave"`, `"dance"`, `"cheer"`, `"bow"`, `"spin"`) on a player's avatar for everyone, without the hook or the rate a player's own request has; true when it took (§6) |
|
|
244
270
|
| `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
|
|
245
271
|
| `hub.sound(actorId, file, { loop, volume, radius }?)` | v1.6, a place with `idle.sounds`: play one of them at a scene actor for everyone, `volume` 0-1 (default 1), silent `radius` metres away (1-60, default 20); a loop plays until `hub.sound(actorId, null)`; true when it took (§6) |
|
|
272
|
+
| `hub.danceIdle(actorId, { bpm, floors })` | v1.109, a place with `idle.emotes`: after starting a sound loop at `actorId`, give its tempo (30–300 BPM) and 1–16 axis-aligned floor bounds `{ x, z, halfX, halfZ }` (positive half sizes at most 100 m; coordinates within ±1,000,000 m). Returns true when valid. `hub.danceIdle(actorId, null)` clears it. Replacing/stopping the loop invalidates the previous clock. No emote, scoring hook or cooldown is triggered. |
|
|
246
273
|
| `hub.cue({ player } or { actor, radius? }, name)` | v1.50, a deck with `soundscape.cues: true`: a named synthesised cue for one connected player or near a scene actor, radius 1–60 m (default 12); true when sent, otherwise false and warn once. Six cues/s with burst six per player, or shared per place for actor broadcasts; closed `CUE_NAMES`, no files (§6). v1.60 `busker-jig`/`busker-waltz` loop at an actor within radius under a 25 s re-send lease, one loop per client, or play one full-gain pass to a player. |
|
|
247
274
|
| `hub.shot(playerId, shot \| null)` | v1.61: send one connected player an orbit-camera moment shot `{ look: { x, y, z }, distance, pitch, yaw }`. Look coordinates, distance and angles must be finite, distance > 0 (metres); angles are degrees, pitch capped at ±89. Invalid shots warn once and act as `null` (clear). True when sent, otherwise false and warn once. Four changed shots/s per player, burst four; equal poses suppressed for 1 s, repeated clears suppressed, clears bypass the budget. The place scene needs the orbit key (`cameraControl: "orbit"`); without it the client does nothing and stores nothing for later. The orbit camera blends to the pose and holds until changed or cleared; the shot pose is not collided. The client clears on travel, leave, scene load/place change and disconnect, preserving any shot subsequently assigned by deck client code. A held pose is privately renewed every 2 s of simulation time and immediately on a fresh join, without spending the rate budget or equal-send refusal. Each accepted pose message refreshes a 5 s client lease; equal renewals keep the same shot object and do not restart the blend. Renewals restore a shot lost to a disconnect, but never re-create one the client dropped for a scene load, travel, round end or a deck's own `orbitShot`; only a fresh `hub.shot` call does that. Successful travel and round end stop server renewals while preserving the rate budget. A shot not renewed for 5 s is cleared on the first watcher run, including after a background-tab pause, so it cannot outlive its server or connection. A clear stops renewals. No manifest opt-in or storage/frame work when unused. |
|
|
248
275
|
| `hub.ballot(playerIds \| null, spec \| null)` | v1.68, a deck that declares `ballot` in some place (absent otherwise), in a place with it: show, change or take down the choice card (§6). `null` for everyone here (later joiners too); a list for those connected players (unknown or disconnected ids are ignored), whose card then replaces the shared one for them, as `setHud` does. `spec` null clears: for a list, those players fall back to the shared card; for everyone, every card goes, players' own included. `spec` is `{ title, text, until, mode, faces, options, lines, feed, picked }`, all optional: `title` ≤ 40 and `text` ≤ 120 characters on one line; `until` a simulation time (`hub.now`) the card counts down to; `mode` `"talk"` (default), `"vote"` or `"reveal"`; `faces` up to 24 `{ playerId, note?, off?, votes?, mark? }` (different players; `note` ≤ 24 characters, `off: true` greyed and not tappable, `votes` 0-99 shown as a tally, `mark` `'#rrggbb'`); `options` up to 6 `{ id, text }` (`id` as a line's, `text` ≤ 32: "Skip"); `lines` the manifest line ids offered now (default all); `feed` up to 6 `{ from, to, line }` the card's recent said lines (`to` a player for a `face` line, null or absent for a `self` one); `picked` `{ face }` or `{ option }` (one of the card's), what this viewer has locked in. True when taken; an invalid spec, a bad list or a place of the deck without `ballot` warns once and returns false, changing nothing. Other keys are refused. |
|
|
249
276
|
| `hub.mark(playerId, { text, color })` | a coloured tag over a player's avatar for everyone: a team, who is it; `null` clears it (§11, v1.1) |
|
|
250
277
|
| `hub.wear(playerId, { kind, color, rarity })` | put a wearable on a player's avatar, kept on their account in every hub place where the host runs the hub: `kind` `"halo"`, `"aura"`, `"orbit"` or, v1.24, a hat `"hat-<id>"`, `color` `#rrggbb`, `rarity` 0-9; `null` takes it off; true when taken (§11, v1.4) |
|
|
251
|
-
| `hub.friendsAmong(playerId, userIds)` | v1.36: `Promise<string[]>`, the subset of candidate decimal user-id strings that are this connected
|
|
278
|
+
| `hub.friendsAmong(playerId, userIds)` | v1.36: `Promise<string[]>`, the subset of candidate decimal user-id strings that are this connected player's friends (a guest's too: a guest is over 13 like any other player). Deduped, capped at 100; ghost applies mutual follows, age, blocks and the hub gate. Every refusal (including an unknown op), absent hub ops or failure resolves `[]`. Empty answers cached per player for 40 s, non-empty answers for 10 min; requests within that window intersect the cached answer with their candidates, and never send another op inside 31 s. Optional per-place `freshFriends: true` (v1.99) instead bounds both TTLs to 31 s and exposes the server-only freshness flag. On by use, no manifest key |
|
|
252
279
|
| `hub.friendBests(key, { better: 'higher' or 'lower' })` | v1.57: a helper with `report(playerId, best): Promise<void>` and `friendFor(playerId): Promise<{ userId, username, best } or null>`. Signed-in players only, finite numbers. `report` keeps each user's best in a top-100 deck-storage index `fb:<key>` of `{ userId, username, best, at }` (20-character username, `at` wall-clock milliseconds), through one serialized writer per key per layer. Cross-layer lost updates are acceptable. Index reads cache for 60 s; `friendFor` caches empty membership for 40 s and non-empty membership for 10 min per player per visit, and selects the best friend from the index. Leaving clears the visit cache. Both methods swallow failures. Keys are 1–60 letters, digits, `_`, `.`, `:`, `-`; use one direction per key. No manifest key, reads or writes until used |
|
|
253
280
|
| `hub.leaving(playerId, text)` | v1.52: the line this player reads when leaving this place; a string, trimmed and cut at 120 characters, `null` or empty clears it. The latest call wins; true when taken, otherwise false and warn once. Sent to this player alone, only on change; never in a snapshot (§5) |
|
|
254
281
|
| `hub.tryOn(playerId, { kind, color, rarity } \| null)` | v1.28: show a wearable on a player in this place only, instead of the one they own, until `null`, their leaving or the place's end. Never saved: nothing goes to ghost, the wearable on the account is neither read nor changed, and no other place hears of it. The same shape and refusals as `hub.wear`; true when taken (§11) |
|
|
255
282
|
| `hub.wearing(playerId)` | v1.41: the wearable a player here owns, `{ kind, color, rarity }` (a copy), as this place last knew it (a `hub.wear`, or ghost's on the arrival read), or null: none, or a player not here. A try-on shown over it does not change it. For a place to say what someone is wearing (§11) |
|
|
256
|
-
| `hub.unlock(playerId, itemId)` | v1.53: give a player one of this deck's declared earned items (`hub.unlocks`), for the deed it states. A promise of `{ isNew, earned, saved }` (`earned` what the player now shows, an EarnedItem, or null -- never a home item (v1.70); `saved` false when it is kept in this session only -- a guest, the dev serve -- so `isNew` is true on every visit there and a game need not announce it), or of null when refused: never rejects, and each refusal is logged once and changes nothing. Ghost keeps it for a signed-in player in a curated place; a guest's, and any on the dev serve, lasts the session (§11) |
|
|
283
|
+
| `hub.unlock(playerId, itemId)` | v1.53: give a player one of this deck's declared earned items (`hub.unlocks`), for the deed it states. A promise of `{ isNew, earned, saved }` (`earned` what the player now shows, an EarnedItem, or null -- never a home item (v1.70); `saved` false when it is kept in this session only -- a guest, the dev serve -- so `isNew` is true on every visit there and a game need not announce it), or of null when refused: never rejects, and each refusal is logged once and changes nothing. Ghost keeps it for a signed-in player in a curated place; a guest's, and any on the dev serve, lasts the session. A delayed host receipt updates local shown state only while the same session and account still own that player id (§11, v1.112). |
|
|
257
284
|
| `hub.wearEarned(playerId, { deckId, id } \| null)` | v1.53: the town's choice of which owned earned item a player shows; `null` shows none. Ghost takes it only from the town. Home items resolve null and log `CAULDRON_HUB_EARNED_NOT_WEARABLE` locally when known, without calling the host. A promise of `{ earned, saved }` (`saved` as for `hub.unlock`), or of null when refused (logged once) (§11) |
|
|
258
285
|
| `hub.unlocksOf(userIds)` | v1.53: always a promise: of the earned items players here own, `{ players: { [userId]: { owned: EarnedItem[] } } }` (ghost answers only for connected players); v1.70 includes home items with `class` and `piece`, which the wardrobe filters out. Or of null where the host has no such read or refuses it (logged once) (§11) |
|
|
259
286
|
| `hub.earned(playerId)` | v1.53: the EarnedItem `{ deckId, id, class, shape, name, deed, color }` a player here shows, as this place last knew it (a `hub.unlock` or `hub.wearEarned` answer, or ghost's on the arrival read), a copy, or null. `hub.wearing` is unchanged by it (§11) |
|
|
287
|
+
| `hub.cup(playerId, doorId)` | v1.112, only with top-level `hub.weeklyCup: true`: server-only private result bits for this connected signed-in roster player and door, `{ [occurrenceDay]: { participated, champion } }`, with at most the current and previous weekly occurrence, or `null` while unavailable or a refresh is pending. A copy; never enters a snapshot, delta or client message, and one player's map is never returned for another player id. Refreshed in bounded batches once a minute and fenced to the current session/player/account identity. `champion` can be true only for the previous closed occurrence's rank-one participant, using the earliest valid result to break a score tie. This rolling projection is for presentation, not reward authority. |
|
|
288
|
+
| `hub.cupNow(doorId)` | v1.112, only with top-level `hub.weeklyCup: true`: the event worker's authoritative epoch milliseconds, advanced by elapsed local wall time from the latest successful paired board read. Server-only. Returns `null` during a refresh and after a malformed or failed paired read, a session replacement, or more than two missed one-minute refresh intervals. Authored Cup schedules fail closed on `null`; they do not fall back to local wall time. |
|
|
289
|
+
| `hub.cupDeckId` | v1.112, only with top-level `hub.weeklyCup: true`: the trusted saved id of the awarding deck, or `null` when unavailable. Server-only and constant for the context. Match it together with an item id in `hub.unlocksOf` ownership readback; an id from another deck is not this deck's claim. |
|
|
260
290
|
| `hub.label(actorId, text, { style, ttlMs, to }?)` | words over a scene actor for everyone, or with `to: [playerIds]` for those players only (theirs replace everyone's until cleared the same way): `style` `"tag"` (a pad's count), `"speech"` (an NPC's line) or `"sign"` (a street's or a building's name, drawn at any distance in a town), ≤ 64 chars; `null` clears it (§10). An NPC body's own `say` (§13) runs to 240 chars and its bubble is kept on screen |
|
|
261
291
|
| `hub.npc(actorId)`, `hub.npcs()` | the place's NPC bodies (§13) |
|
|
262
292
|
| `hub.results(playerId)` | ghost's record of a player's hub results: `{ recent, records, readAt }` -- their newest results across places and their record per place -- or null (dev serve, anonymous). Read at arrival and once a minute for everyone here (§7, v1.5) |
|
|
@@ -266,7 +296,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
266
296
|
| `hub.go(door, playerIds, { instance }?)` | send players through a door of this place (a town's pad firing) into a new instance, or into `instance`, one an earlier `go` returned (a late join); returns the instance |
|
|
267
297
|
| `hub.pad(door, playerIds)` | who stands on a pad door's pad; call it as often as they change (each step is fine). Where the host has hub ops the kit tells ghost, which then holds the pad's group; nothing in dev |
|
|
268
298
|
| `hub.coming(door)` | v1.10: how many members of a party were asked to this door and have not answered yet (§5 parties), so a place may hold its pad's countdown for them; 0 where there are none |
|
|
269
|
-
| `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board |
|
|
299
|
+
| `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board. v1.112 weekly boards add `event.validResultCount` and `event.last.validResultCount`: distinct participants with any valid durable result in that occurrence, including an outcome without a numeric score, so replays never inflate either count. Numeric matching scores remain required for ranking. Daily-only boards omit both fields. |
|
|
270
300
|
| `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
|
|
271
301
|
|
|
272
302
|
`hub.go` is how any place launches: in dev it mints `hub.<place>.<random>` and
|
|
@@ -353,7 +383,7 @@ that write completed cannot replace its cache. Reports read-modify-write from
|
|
|
353
383
|
the freshest cache or a storage read begun after the last write. Cross-layer
|
|
354
384
|
lost updates remain acceptable.
|
|
355
385
|
|
|
356
|
-
When a place first calls `friendsAmong` for a connected
|
|
386
|
+
When a place first calls `friendsAmong` for a connected player, only
|
|
357
387
|
that player receives `{ k: 'hub-friends-wanted' }`, latched for the visit and
|
|
358
388
|
resent on a fresh hello. It is never in a snapshot. The client in a game asks
|
|
359
389
|
`castleSdk.Hub.friends()` on receipt (the next idle tick), again 20 s later,
|
|
@@ -367,11 +397,30 @@ The seven games wait for a successfully loaded signed-in record before asking;
|
|
|
367
397
|
guests, players still loading and unsaved players send no friends request or
|
|
368
398
|
flag. Under-13 players and every refusal show no comparison.
|
|
369
399
|
|
|
400
|
+
**Fresh friend permission (v1.99).** A place with `freshFriends: true` expires
|
|
401
|
+
both positive and negative permissions after 31 wall-clock seconds. An expired
|
|
402
|
+
lookup awaits a fresh platform read before answering; an error, malformed reply
|
|
403
|
+
or a 900 ms timeout yields no friends. Concurrent deck asks and cell primes share
|
|
404
|
+
one pending read and the existing 31 s minimum read gap. Late timed-out replies
|
|
405
|
+
cannot restore permission. Reads request strict raw validation from the SDK
|
|
406
|
+
adapter; an older adapter without its validation marker yields no permission. Cell primes check every 5 s, so unchanged rosters
|
|
407
|
+
refresh within about 35 s; a removed follow may remain visible during that window.
|
|
408
|
+
Ghost remains authoritative for mutual follows, blocks and over-13 eligibility.
|
|
409
|
+
Only opted-in server contexts expose `hub.freshFriends === true`; it adds no
|
|
410
|
+
client or snapshot fields. An absent key retains all existing TTLs and behavior.
|
|
411
|
+
NPC tools may use the flag to offer town locations; callers without the flag
|
|
412
|
+
retain presence-only answers. Town enables this key separately, not implicitly.
|
|
413
|
+
|
|
370
414
|
On the local dev serve only, `CASTLE_DEV_HUB_FRIENDS=all` in the serve process
|
|
371
415
|
environment treats every valid candidate as a friend. Without it, absent hub
|
|
372
416
|
ops resolve `[]`. The fixture requires a dev session and no platform hub ops;
|
|
373
417
|
it cannot override ghost in production. It writes no friend list.
|
|
374
418
|
|
|
419
|
+
**Doors list labels.** A `HubDoor` may set `listTitle` to a non-blank string
|
|
420
|
+
(up to 60 characters) for its Doors list row. This changes the list only;
|
|
421
|
+
travel, board titles and the destination manifest keep their original names.
|
|
422
|
+
Town uses this to distinguish the four entrances to your owner-keyed house.
|
|
423
|
+
|
|
375
424
|
**Owner instances (v1.67).** `hub.owner` reads the non-empty string
|
|
376
425
|
`session.hub.owner` supplied by the platform, never a client's message. It is
|
|
377
426
|
the owner account's user id on an owner door instance, and null on other
|
|
@@ -417,7 +466,7 @@ there is no atomic toggle). Hearts live on the account, never in browser storage
|
|
|
417
466
|
the dev serve keeps them per account in memory for its lifetime.
|
|
418
467
|
|
|
419
468
|
An outside arrival with rows is offered `♥ <title>`, its personal line, Go and
|
|
420
|
-
Not now once for
|
|
469
|
+
Not now once for 12 s from its first display. It waits up to 60 s for
|
|
421
470
|
signed-in identity and arrival data. Returning from a game offers the door just played
|
|
422
471
|
instead, with a heart toggle where supported. If it is outside the five private
|
|
423
472
|
rows, its carried last result supplies the line until a read can name it.
|
|
@@ -426,6 +475,31 @@ Go together for a party and a non-solo door, Go for solo. No chip over an
|
|
|
426
475
|
invitation or party proposal, in a game, during a trip or while other chrome is
|
|
427
476
|
suppressed. The chip fits within 94vw and its personal line ellipsizes.
|
|
428
477
|
|
|
478
|
+
- **The ask slot expires (v1.125).** Every §5 card in the shared ask slot -- a
|
|
479
|
+
party invitation or proposal, a play/follow card, Play again and Your games --
|
|
480
|
+
retires 12 s after its first actual display. It retires sooner when the local
|
|
481
|
+
player moves 3 m or more in x/z from that display position, or enters any
|
|
482
|
+
`HubPad`; a card first displayed while already on a pad stays until the player
|
|
483
|
+
leaves and enters a pad again. A frame on a hidden or suspended page is not a
|
|
484
|
+
display. Either action, and a Your games card's heart, still works before the
|
|
485
|
+
boundary and not after; a tap on a redrawn presentation of the same card
|
|
486
|
+
does nothing and leaves the lease running. Passive retirement sends no
|
|
487
|
+
decline or other message. Local play/follow and
|
|
488
|
+
Play again producer deadlines apply only until first display; after display
|
|
489
|
+
the lease supplies the full 12 s action window. The first lease survives
|
|
490
|
+
temporary higher-priority chrome, card redraws and a same-identity reconnect
|
|
491
|
+
replay, so an expired observable offer cannot reappear during the 30 s
|
|
492
|
+
reconnect window. A received invitation clear followed by another invitation,
|
|
493
|
+
or an invitation for a new player identity, starts a new occurrence. Because
|
|
494
|
+
invitation packets carry no occurrence id, indistinguishable same-sender
|
|
495
|
+
packets with no received clear count as the same offer. Server-authoritative
|
|
496
|
+
withdrawal or replacement of a party invitation or proposal can dismiss it
|
|
497
|
+
before 12 s. This applies to every town,
|
|
498
|
+
rather than an opt-in, because it bounds the kit-owned shared chrome lifecycle.
|
|
499
|
+
It adds no manifest capability or wire fields; server-authoritative offer state
|
|
500
|
+
remains unchanged. The
|
|
501
|
+
leaving line/toast is separate and unchanged.
|
|
502
|
+
|
|
429
503
|
- Players sent together by one `hub.go` arrive together: the kit holds a group's
|
|
430
504
|
first arrival still, up to 1.5 s, for the rest, places them in a row at
|
|
431
505
|
`arrival.actor` spaced by `arrival.spread`, and calls `arrive` once with all
|
|
@@ -556,7 +630,16 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
|
|
|
556
630
|
pack, or a pack that fails keeps the door shut and gives the acquisition back
|
|
557
631
|
(`Hub.cancel`). The way back is `Hub.back()`; the host's own Back control is
|
|
558
632
|
answered the same way (`Hub.onBack`), and while the host's trail holds a hub
|
|
559
|
-
trip the kit does not draw its own Back, since the host draws one.
|
|
633
|
+
trip the kit does not draw its own Back, since the host draws one. v1.118:
|
|
634
|
+
on Android mobile hosts in landscape, the kit draws Back during a settled
|
|
635
|
+
visit (including a House without a local ticket) unless
|
|
636
|
+
`window.CastleEmbed.hubBackInLandscape === true`. Old Android hosts have
|
|
637
|
+
only Exit deck there; updated hosts advertise this optional capability at
|
|
638
|
+
document start and after loading, and supply their own Back. Old kits ignore
|
|
639
|
+
the capability and retain their existing host Back behavior. iOS, portrait,
|
|
640
|
+
browser hosts, travel covers and root visits retain their previous behavior.
|
|
641
|
+
The kit control uses the existing `Hub.back()` return, with the same modal
|
|
642
|
+
dismissal and duplicate-trip guards as host Back. Nothing of
|
|
560
643
|
the destination is mounted until the host commits the join
|
|
561
644
|
(`multiplayer.joinState()`); a join it does not commit leaves the player's
|
|
562
645
|
place as it was: a door's trip rejoins the session it left when that is not
|
|
@@ -626,7 +709,14 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
|
|
|
626
709
|
session is listed too: "in another part of town" (another layer; Join is the
|
|
627
710
|
jump below), or, on a host that says which door's game they are in
|
|
628
711
|
(`door` on a `Hub.friends` row), "inside <door>" (Join is a jump to that
|
|
629
|
-
door). A
|
|
712
|
+
door). A friend the host names as at home in their own House behind that
|
|
713
|
+
door (`home: true` and `ownerUserId` on the row) is "inside <name>'s House",
|
|
714
|
+
and Join asks the place (`hub-house-visit`), which sends the player through
|
|
715
|
+
that door with the owner (`hub-go` carrying `owner`, so the visit here ends
|
|
716
|
+
as any door's trip does) and the client acquires their House
|
|
717
|
+
(`Hub.go(door, { ownerUserId })`); a host that predates the owner acquires
|
|
718
|
+
the player's own House instead. A game lists only who may be reported, as
|
|
719
|
+
before.
|
|
630
720
|
- **Starting next to a friend (v1.12).** A player who walks into a town (no
|
|
631
721
|
door, no jump) and finds a party member or a friend in the same layer is put
|
|
632
722
|
beside them, once: the client asks the place (`hub-goto`) for a party member
|
|
@@ -675,16 +765,32 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
|
|
|
675
765
|
`unavailable` or does not know the command is not asked again.
|
|
676
766
|
- **Falling (v1.1).** A scene can have no ground at all (`"ground": { "none":
|
|
677
767
|
true }` at the scene file's top level, which the engine and the server both
|
|
678
|
-
read): a pit, lava, islands in the sky. A place whose players can fall
|
|
679
|
-
|
|
768
|
+
read): a pit, lava, islands in the sky. A place whose players can fall may
|
|
769
|
+
declare `fallY`; otherwise it gets -20, which also catches a player past the
|
|
770
|
+
edge of the finite implicit ground. A player whose body
|
|
680
771
|
drops below it is handed to the game's `fall(hub, playerId)` hook, and if
|
|
681
772
|
they are still down there afterwards the kit puts them back at the arrival.
|
|
682
773
|
A held player is not caught (the game holds whom it has already dealt
|
|
683
774
|
with). The hub client stops its own player's fall a metre under `fallY`
|
|
684
775
|
(the snapshot's `hubPlace.fallY`), since the server reads no pose below the
|
|
685
776
|
world's floor (-30 m) and a report that skipped past it would never be
|
|
686
|
-
caught.
|
|
687
|
-
|
|
777
|
+
caught. After the player crosses `fallY`, the world fades through that last
|
|
778
|
+
metre to its sky/fog colour, then fades back after the authoritative
|
|
779
|
+
placement. `fallY` must sit below
|
|
780
|
+
everywhere a player stands, or the arrival itself counts as fallen.
|
|
781
|
+
|
|
782
|
+
A scene with no authored environment -- no top-level `background`,
|
|
783
|
+
`engine.sky` or `engine.view` key -- gets a pale clear colour and cheap
|
|
784
|
+
linear ground fog from the hub client. It adds no mesh or render pass and
|
|
785
|
+
runs on Low/Weakest too. Outside the fall transition, presence of any
|
|
786
|
+
authored environment key keeps the prior picture byte-for-byte (including a
|
|
787
|
+
graphics tier that suppresses its parsed sky at runtime); scene travel and
|
|
788
|
+
disposal restore the renderer, fog and fade styles exactly. Root
|
|
789
|
+
`hub.defaultEnvironment` (v1.135) is an optional boolean, on when absent or true.
|
|
790
|
+
`false` disables the fallback clear, fallback fog and canvas fall fade
|
|
791
|
+
together for every scene the root deck visits, including mounted content;
|
|
792
|
+
it does not change authored environments or the server's fall catch and
|
|
793
|
+
`fall` hook.
|
|
688
794
|
- **Exit** is always through the door the player came in by: the hub-drawn Back
|
|
689
795
|
control, `hub.end`, `maxDurationSec`, a crash or a republish. The game cannot
|
|
690
796
|
name the destination; the client's return ticket does (ghost's, once it
|
|
@@ -1259,7 +1365,8 @@ named cue messages, in a deck with `soundscape.cues: true`.
|
|
|
1259
1365
|
cues alone adds no chip callback or legacy timer cue, and `soundscape:
|
|
1260
1366
|
true` enables neither. Without `cues` no action observer is made.
|
|
1261
1367
|
|
|
1262
|
-
- **The control.** A speaker button in the
|
|
1368
|
+
- **The control.** A speaker button in the right column, below the reserved native camera
|
|
1369
|
+
corner, opens Mute and a
|
|
1263
1370
|
volume slider, kept on the device (`localStorage`
|
|
1264
1371
|
`castle.hub.soundscape.v1`). It sets the level of everything above and of
|
|
1265
1372
|
the place's own sounds (`hub.sound`, v1.6), which without the key play at
|
|
@@ -1296,7 +1403,15 @@ here!" from a party member or a friend puts the pointer (§5) on them for
|
|
|
1296
1403
|
10 s, and a "Let's play" that names a door is offered to everyone who heard it
|
|
1297
1404
|
as a question for 20 s ("bo: let's play Tile Fall": Go / Not now), Go being a
|
|
1298
1405
|
jump to that door's pad. This is for everyone, guests included; nothing a player types is
|
|
1299
|
-
carried. No
|
|
1406
|
+
carried. No hook hears it. Optional `hub.playCards: true` (v1.122) changes only
|
|
1407
|
+
which phrases offer a Go card: mutual friends (as named by `Hub.friends`) and
|
|
1408
|
+
party members anywhere in this layer; strangers only within 12 m in x/z
|
|
1409
|
+
when received, with missing positions refused. Only one stranger card may
|
|
1410
|
+
be retained at a time, without replacing or extending it; after dismissal or
|
|
1411
|
+
expiry each stranger waits 60 s from their last offered card, across doors.
|
|
1412
|
+
Friends and party members keep the existing per-player, per-door cooldown.
|
|
1413
|
+
Bubbles and feed remain for every unblocked listener. Absent or false keeps
|
|
1414
|
+
the v1.11 behavior and wire bytes.
|
|
1300
1415
|
|
|
1301
1416
|
**Free-text chat (v1.12).** Two players may type to each other only when
|
|
1302
1417
|
they follow each other on Castle and both are over 13; a guest, or a player
|
|
@@ -1316,6 +1431,8 @@ like a phrase: over its speaker for 6 s and in the feed; a tap on another
|
|
|
1316
1431
|
player's line in the feed offers Report (`Hub.reportChat`). What was said
|
|
1317
1432
|
before a player arrived is not shown to them. On a host or SDK without the
|
|
1318
1433
|
commands nothing is drawn and nothing is asked. A deck changes nothing.
|
|
1434
|
+
A guest (their own account is anonymous) is over 13 like any other player:
|
|
1435
|
+
the host's answer decides their field, and they read the same words.
|
|
1319
1436
|
|
|
1320
1437
|
**The choice card (v1.68).** A place whose manifest declares `ballot` (§1)
|
|
1321
1438
|
may put a card of players' faces in front of its players -- a meeting, a vote,
|
|
@@ -1504,6 +1621,79 @@ hub.setHud({ text: 'you are it!' }, playerId); // one player's override; null c
|
|
|
1504
1621
|
Longer strings are cut, other keys dropped. A per-player spec replaces the
|
|
1505
1622
|
shared one for that player.
|
|
1506
1623
|
|
|
1624
|
+
**Safe edges and reserved space (v1.123).** Optional deck key
|
|
1625
|
+
`hub.safeInsets: true` applies to the hub chrome in every place the client draws.
|
|
1626
|
+
The server validates the boolean but does not retain it or send it in `hubPlace`.
|
|
1627
|
+
Absent or false keeps the previous rendering, creates no layout probe or report,
|
|
1628
|
+
and adds no client state key.
|
|
1629
|
+
|
|
1630
|
+
Safe placement persists through CSS custom properties; animation frames do not
|
|
1631
|
+
restore, measure or reapply it. Insets are read on initialization and viewport
|
|
1632
|
+
resize/orientation/visual-viewport events. DOM changes coalesce into keep-out
|
|
1633
|
+
passes at most twice per second. Loading-cover changes settle before paint;
|
|
1634
|
+
explicit debug reports still measure synchronously.
|
|
1635
|
+
|
|
1636
|
+
1. Edge-anchored chrome keeps `max(its existing margin, env(safe-area-inset-*))`
|
|
1637
|
+
on that edge. This includes People/Doors, Character, the action column and
|
|
1638
|
+
its open cards, pointers, bubbles, toasts, the result ribbon and HUD. Zero
|
|
1639
|
+
insets preserve the existing edge offsets.
|
|
1640
|
+
2. The host owns a 64 × 56 CSS px box at each top corner, measured from the
|
|
1641
|
+
top and left/right inset edges. The HUD title row fits between both boxes.
|
|
1642
|
+
Other chrome intersecting a box moves straight down to 6 px beneath it,
|
|
1643
|
+
using the same clearance geometry as the clear HUD below. Transient text
|
|
1644
|
+
also yields to the visible HUD and controls. The web player reserves the
|
|
1645
|
+
same boxes for its own controls.
|
|
1646
|
+
3. Measured chrome crossing a view edge is pulled inside its safe edge and
|
|
1647
|
+
margin. Oversize text wraps; an oversize card keeps its bottom in view and
|
|
1648
|
+
scrolls rather than losing its content. This key enables the existing
|
|
1649
|
+
action overflow path even without a scene's `hubActionOverflow` key,
|
|
1650
|
+
keeping all offers through More/Actions and clear of Shift lock. Round buttons,
|
|
1651
|
+
Character, Shift lock and Decorate use one measured bottom-up stack; a short
|
|
1652
|
+
view wraps whole controls into the next column. External cards and controls
|
|
1653
|
+
share one current registry with the action solver and its observers, so an
|
|
1654
|
+
opened, replaced or closed dialog recalculates unchanged offers and releases
|
|
1655
|
+
detached observer targets. A viewport with no room to satisfy
|
|
1656
|
+
both clearance and visibility is a layout failure, not a reason to hide
|
|
1657
|
+
an offer or silently accept clipped chrome.
|
|
1658
|
+
|
|
1659
|
+
The page-readable debug report `window.castleHub.layout()` exists only for the
|
|
1660
|
+
opted-in client and is removed when that chrome is disposed. It returns a fresh
|
|
1661
|
+
snapshot in CSS px, without wire bytes or text:
|
|
1662
|
+
|
|
1663
|
+
```js
|
|
1664
|
+
{
|
|
1665
|
+
view: { w, h, insets: { top, right, bottom, left } },
|
|
1666
|
+
reserved: [
|
|
1667
|
+
{ id: 'host-back', x, y, w: 64, h: 56 },
|
|
1668
|
+
{ id: 'host-camera', x, y, w: 64, h: 56 },
|
|
1669
|
+
],
|
|
1670
|
+
boxes: [{ id, kind, x, y, w, h }],
|
|
1671
|
+
}
|
|
1672
|
+
```
|
|
1673
|
+
|
|
1674
|
+
`boxes` contains visible measured surfaces, with stable kit ids and kinds
|
|
1675
|
+
(`control`, `card`, `hud`, `label`, `pointer`, `toast`, `ribbon`, `text`). A
|
|
1676
|
+
navigation group reports its visible pills separately; a card reports its
|
|
1677
|
+
outer surface, not every contained row. Hidden ancestors, covers and transparent
|
|
1678
|
+
hit areas are excluded. A layout check compares those boxes with the safe view
|
|
1679
|
+
and reserved boxes and files remaining overlaps or clipping as failures.
|
|
1680
|
+
|
|
1681
|
+
**Next-action prompt (v1.131).** The top HUD keeps a small `title` and big
|
|
1682
|
+
`big` timer or score, each on a compact dark backing that stays legible against
|
|
1683
|
+
pale skies. The first sentence of `text` appears in a dark one-line
|
|
1684
|
+
pill at bottom centre, above the player-count caption and within safe insets.
|
|
1685
|
+
While an NPC conversation offers suggestion or choice buttons, those buttons
|
|
1686
|
+
are the next action: the bottom prompt hides until they close. Toasts yield
|
|
1687
|
+
when they cannot fit clear of those buttons.
|
|
1688
|
+
The wire/API stays unchanged; the client omits later sentences without adding
|
|
1689
|
+
an ellipsis. Door authors write only the next action, about 48 characters;
|
|
1690
|
+
story belongs in NPC talk or a later prompt. Dev serving warns on wrapping,
|
|
1691
|
+
and the layout check reports it as a failure. Existing overlong first sentences
|
|
1692
|
+
remain fully readable by wrapping in the bottom pill until their authors
|
|
1693
|
+
shorten them; the kit never silently clips a sentence. Empty prompts have no pill.
|
|
1694
|
+
Labels reserve the top band and bottom pill separately. Check at 844×390,
|
|
1695
|
+
desktop and portrait.
|
|
1696
|
+
|
|
1507
1697
|
**A clear HUD (v1.26).** The HUD hangs from the top middle of the screen, and
|
|
1508
1698
|
on a phone that is where much of what the hub draws over the world lands too:
|
|
1509
1699
|
with a title, a 56 px big line and a text line the box is over 100 px tall, the
|
|
@@ -1532,8 +1722,7 @@ speech bubble near the top is drawn across it. A place whose manifest sets
|
|
|
1532
1722
|
the HUD is left over its top. Two things moved under it may overlap each
|
|
1533
1723
|
other. While no HUD is drawn nothing moves.
|
|
1534
1724
|
- **A short view.** On a view 480 px tall or less that is wider than it is
|
|
1535
|
-
tall (a phone on its side) the
|
|
1536
|
-
ellipsis) and the box to 40% of the view's height. A portrait view is never
|
|
1725
|
+
tall (a phone on its side) the box keeps to 40% of the view's height. A portrait view is never
|
|
1537
1726
|
short, however small (the web player's card on a 360 px phone is about
|
|
1538
1727
|
475 px tall).
|
|
1539
1728
|
|
|
@@ -1754,6 +1943,41 @@ hat ids from `code/client/hats.js` `HATS`; unknown icons are refused. `on`
|
|
|
1754
1943
|
and `readOnly`, when present, are booleans. A missing color uses the chrome's
|
|
1755
1944
|
text color. Invalid calls throw TypeError before changing state.
|
|
1756
1945
|
|
|
1946
|
+
**Text rows (v1.136).** Optional `presentation: 'rows'` uses the same private
|
|
1947
|
+
menu, versioned picks and close path for full-width text rows. A row item may
|
|
1948
|
+
add `columns: [left, middle, right]`: exactly three texts, each 1..24 code
|
|
1949
|
+
points with the same text hygiene. Its required `label` remains 1..16 code
|
|
1950
|
+
points. The middle column wraps; no icon or swatch is drawn. Optional item
|
|
1951
|
+
`readOnly: true` displays a row without accepting picks for it. These two
|
|
1952
|
+
item keys are valid only with row presentation.
|
|
1953
|
+
|
|
1954
|
+
Row menus may add `footer: [{ id, label }]`, up to four actions pinned below
|
|
1955
|
+
the scrolling rows. Footer ids share the menu's uniqueness and reserved-id
|
|
1956
|
+
rules, and count toward its 48-item total; labels use the existing 1..16 rule.
|
|
1957
|
+
Footer objects accept only `id` and `label`. Spec `readOnly` disables all row
|
|
1958
|
+
and footer picks while still allowing close. The menu hook receives footer
|
|
1959
|
+
ids through the existing versioned pick envelope.
|
|
1960
|
+
|
|
1961
|
+
Without `face`, row presentation can use the viewport height minus 24px and
|
|
1962
|
+
hides the HUD score and instruction while open, restoring them on close. It
|
|
1963
|
+
also hides the on-screen controls the sheet would cover: the Doors and People
|
|
1964
|
+
buttons (and their open lists), the friend and goal direction chips, the
|
|
1965
|
+
character button and sheet, the chat and emoji buttons and their cards, the
|
|
1966
|
+
sound button and card, the grab, sit, talk and near buttons, the stuck chip,
|
|
1967
|
+
the pad context chip, action chips, the action and interaction rails and every
|
|
1968
|
+
control surface registered with the kit (such as the engine's Shift lock).
|
|
1969
|
+
They are masked, not rewritten: a `data-hub-menu-covered` marker and one
|
|
1970
|
+
`visibility: hidden !important` rule in the sheet's own style, so each
|
|
1971
|
+
control's own visibility is never changed and is what it shows once the
|
|
1972
|
+
sheet closes, is replaced (by any menu, including a row menu with `face` or
|
|
1973
|
+
a tile menu), is cleared on a rehello or place change, or is disposed. A
|
|
1974
|
+
control made while the sheet is open is masked at the end of that frame. The kit's
|
|
1975
|
+
Back button, toasts and the chat feed stay. A row menu with `face` and the
|
|
1976
|
+
tile layout leave these controls as they are.
|
|
1977
|
+
With `face`, the existing 40% height limit remains. Footer actions stay outside
|
|
1978
|
+
the row scroll area. Omitting `presentation` retains the existing tile layout
|
|
1979
|
+
and wire shape; `footer`, item `columns` and item `readOnly` are then refused.
|
|
1980
|
+
|
|
1757
1981
|
`face`, when present, is a finite number in degrees, normalised into
|
|
1758
1982
|
[-180, 180). It uses `hub.placeAt`'s facing convention: the avatar looks
|
|
1759
1983
|
along `(sin f, cos f)` in x/z (f in radians); 0° faces +z, 90° faces +x.
|
|
@@ -1827,7 +2051,7 @@ existing override is allowed at the cap. A call that would exceed it for any
|
|
|
1827
2051
|
recipient is refused for all recipients. Private calls return true when taken;
|
|
1828
2052
|
invalid actor/options or the cap warn once per refusal kind and return false
|
|
1829
2053
|
without changing anything. Leaving drops that player's overrides, including
|
|
1830
|
-
ones set before their first hello.
|
|
2054
|
+
ones set before their first hello, except for the bounded retained visit below.
|
|
1831
2055
|
|
|
1832
2056
|
Only the client's view changes: server logic that reads `h.hidden` (pads,
|
|
1833
2057
|
labels, doors and idle) continues to use the shared state. Server bodies and
|
|
@@ -1842,6 +2066,81 @@ and messages; no new snapshot key is added.
|
|
|
1842
2066
|
`hub.label` puts words over a scene actor, drawn by the hub chrome like the
|
|
1843
2067
|
HUD: a pad's "3 of 6", an NPC's line, the hill's king.
|
|
1844
2068
|
|
|
2069
|
+
**Default world label focus.** In door places (including social places without results), and in standalone places without an explicit `hub.labels` town policy, ordinary actor tags, signs and NPC lines use at most three nearby slots (12 m to enter, 14 m to leave, with distance thinning and hysteresis) in towns and games. Goals remain the nearest two drawable pointers. Final pointer chips avoid the HUD, visible chrome surfaces and both reserved host corners; they take precedence over actor tags, marks, speech and emotes. Projected text stays inside the actual world canvas, including letterboxed scenes. Overlapping or clipped labels collapse at their world anchor. This is a client drawing default with no new manifest or wire field. An explicit `labels: "near"` retains the v1.43 selection policy below. Its selected text still receives final clearance from HUD/control surfaces, including engine score/presence captions, and the projected local avatar; pointer chips move around these obstacles without changing their direction. A kit cannot infer a called colour or round objective from ordinary tag text: a game still supplies its active goals or clears irrelevant labels.
|
|
2070
|
+
|
|
2071
|
+
**Optional pad readability.** A scene with `engine.hubPadOccupancy: true`
|
|
2072
|
+
keeps world labels clear of the viewer's projected avatar and visible controls.
|
|
2073
|
+
One nearby `HubPad` receives a private supporting line: `you + N more` while
|
|
2074
|
+
the viewer is a reported member, otherwise `N here`. Membership comes from
|
|
2075
|
+
the deck's existing `hub.pad` reports, intersected with the roster already
|
|
2076
|
+
disclosed to that viewer, connected bodies and current privacy filtering.
|
|
2077
|
+
Unknown or stale reports/rosters, or multiple pads sharing one door id, show
|
|
2078
|
+
`occupancy unavailable` instead of a number. A launch requirement is never an
|
|
2079
|
+
occupancy count. The deck must keep its own population-dependent label text
|
|
2080
|
+
viewer-safe when enabling this marker; the Town supplies its matching dormant
|
|
2081
|
+
branch. Goals and NPC speech retain precedence. A long duplicate station or
|
|
2082
|
+
record line yields to occupancy; an unfit world label is omitted. Existing
|
|
2083
|
+
private labels carry the text, with no new protocol field or social request.
|
|
2084
|
+
Without the scene marker, the existing label and wire paths are unchanged.
|
|
2085
|
+
|
|
2086
|
+
Three independent, client-only scene markers extend pad readability. Each is
|
|
2087
|
+
absent by default; absent markers add no DOM, meshes, listeners, server state,
|
|
2088
|
+
wire messages or saved data. They do not change the contract version.
|
|
2089
|
+
|
|
2090
|
+
A cue is any viewer-visible actor with `HubPad` (its `radius`, and the title of
|
|
2091
|
+
the `HubDoor` whose `id` matches its `door`), or with optional component
|
|
2092
|
+
`HubPadCue: { radius, title? }`. The latter takes precedence over `HubPad`:
|
|
2093
|
+
`radius` must be finite and 0.3–6 metres; an invalid radius excludes the actor.
|
|
2094
|
+
A title must trim to 1–24 Unicode characters, without control characters;
|
|
2095
|
+
invalid titles are ignored. An explicit cue never inherits door wording.
|
|
2096
|
+
The footprint is a circle at its Transform x/z. The local body selects a
|
|
2097
|
+
containing cue, otherwise one within 1.5 m of its edge. Stable actor ids break
|
|
2098
|
+
ties; a still-valid incumbent stays selected (near cues release beyond 2 m).
|
|
2099
|
+
Standing takes precedence over a retained near cue. Selection runs only after
|
|
2100
|
+
movement over 5 cm or a cue/visibility change, without frame allocations.
|
|
2101
|
+
|
|
2102
|
+
- `engine.hubPadContext: true`: one noninteractive chrome caption shows the
|
|
2103
|
+
active title at 16 px, wrapping to at most two lines with ellipsis and the
|
|
2104
|
+
full accessible title. A nearby door pad adds “Step on to join” at 13 px;
|
|
2105
|
+
explicit cues and standing players get no secondary line. It yields to
|
|
2106
|
+
final chrome surfaces, the avatar, joystick and host corners, and is omitted
|
|
2107
|
+
without room. Panels, sheets, chat and travel hide it. It dispatches nothing
|
|
2108
|
+
and leaves Talk, invites and actions alone.
|
|
2109
|
+
- `engine.hubPadRing: true`: one reused client mesh draws a continuous opaque,
|
|
2110
|
+
unlit annulus, inner radius `radius + 0.05`, width 0.12 m, at Transform y
|
|
2111
|
+
plus half the cylinder Shape height (otherwise no height offset), lifted
|
|
2112
|
+
0.03 m. It uses the Shape colour, or `#d9a441`, without animation or extra
|
|
2113
|
+
passes. There is no actor, collider or trigger change.
|
|
2114
|
+
- `engine.hubSpawnRing: true`: one static merged mesh draws eight mint
|
|
2115
|
+
(`#7fc9b8`) segments, inner radius 1.2 m and width 0.12 m, at arrival y +
|
|
2116
|
+
0.03 m. Arrival comes from the existing pack place manifest or bundled
|
|
2117
|
+
`castle.json` and authored scene/blueprint transforms, with the same arrival
|
|
2118
|
+
actor → Player spawn → default fallback as §5. It has no label or action.
|
|
2119
|
+
When centres are within active radius + 1.2 m, the active ring yields to
|
|
2120
|
+
this locator. Both rings remain drawable on Low and dispose on scene unload.
|
|
2121
|
+
|
|
2122
|
+
**Optional crowd names.** A scene with `engine.hubCrowdNames: true` keeps
|
|
2123
|
+
existing eligible multiplayer name sprites clear of the viewer's projected
|
|
2124
|
+
body, final world labels and visible controls. Horizontal proximity and
|
|
2125
|
+
overlapping projected rectangles form crowds; each draws at most two names.
|
|
2126
|
+
One anonymous summary may describe suppressed eligible candidates, only when
|
|
2127
|
+
it fits. Names retain their avatar anchor and scale to at least 15 CSS pixels
|
|
2128
|
+
of text before placement. At 509 × 218 and smaller, individual names are
|
|
2129
|
+
suppressed; use People when a summary cannot fit either.
|
|
2130
|
+
|
|
2131
|
+
Ranking uses the already available allowed friend priority, a retained slot
|
|
2132
|
+
for 500 ms, quarter-metre distance buckets, then the stable session player id.
|
|
2133
|
+
Display names and roster order never identify slots. Eligibility loss and
|
|
2134
|
+
departures remove names and their count contribution immediately; re-admission
|
|
2135
|
+
clears visit-local ranking. Proximity enters at 1 m and leaves at 1.25 m;
|
|
2136
|
+
restoration requires 8 pixels of clearance for 250 ms. These hysteresis values
|
|
2137
|
+
are **unmeasured starting values**, not device performance results. Pair work
|
|
2138
|
+
is bounded to 24 candidates; other eligible candidates may contribute to the
|
|
2139
|
+
one summary. Camera-front and viewport checks suppress clipped tags; wall
|
|
2140
|
+
occlusion remains unknown. There are no raycasts, additional social requests,
|
|
2141
|
+
actors or protocol fields. Without the marker, name behavior is unchanged;
|
|
2142
|
+
turning it off removes crowd state/summary and restores baseline sprite scales.
|
|
2143
|
+
|
|
1845
2144
|
**Goals (v1.13).** `hub.label(actorId, text, { style: "goal", to: [playerIds] })`
|
|
1846
2145
|
is where the place is sending those players: an errand's person, the counter
|
|
1847
2146
|
to fetch from. The hub chrome draws it as a pointer rather than a label: over
|
|
@@ -1850,6 +2149,16 @@ the way to it, with the distance in metres beyond 6 m (the follow camera looks
|
|
|
1850
2149
|
down, so a far sign is rarely in view). A goal is one player's own: with no
|
|
1851
2150
|
`to` it is a `"sign"`. The two nearest are drawn; `null` clears one like any
|
|
1852
2151
|
label. A town on an engine from before v1.13 draws it as a tag.
|
|
2152
|
+
Private goal positions (v1.128): `hub.goalPositions === true` advertises support for
|
|
2153
|
+
`{ at: { x, y, z } }` on a goal label. The actor remains its label key, but the
|
|
2154
|
+
arrow projects the supplied position instead of the actor's Transform. Only
|
|
2155
|
+
private goals carry `at`; shared signs, tags and speech ignore it. Coordinates
|
|
2156
|
+
must be finite and inside the world box (x/z ±200, y −30..80). They are sent
|
|
2157
|
+
only in the recipients' label overrides, with no spawned actor or shared pose.
|
|
2158
|
+
Clear or refresh the label when its target leaves or becomes hidden from its
|
|
2159
|
+
viewer; `about: playerId` also applies the kit's block filter to that label.
|
|
2160
|
+
Older kits have no capability and callers must fall back to location text.
|
|
2161
|
+
|
|
1853
2162
|
v1.39: the distance shown is the player's straight line to the actor unless
|
|
1854
2163
|
the goal says which to show -- `{ distanceM: n }` is the number of metres
|
|
1855
2164
|
shown in its place (finite and 0 or more, kept to the whole metre; the walk
|
|
@@ -1868,7 +2177,7 @@ chosen, so a hidden hint never displaces an edge-drawn goal. Only exactly
|
|
|
1868
2177
|
it. With the key absent, goals are stored, sent and drawn byte-identically.
|
|
1869
2178
|
This applies only to hub places; no editor, classic or other Cauldron deck changes.
|
|
1870
2179
|
|
|
1871
|
-
**Labels in
|
|
2180
|
+
**Labels in an explicitly near town.** At the root of a deck with `labels: "near"`, in a place with no `result`, the
|
|
1872
2181
|
client draws a label only when its actor is near the player: the nearest
|
|
1873
2182
|
plain or `"tag"` label within 4 m and the nearest `"speech"` line within 9 m,
|
|
1874
2183
|
fading in and out, one of each at a time. A `"sign"` label (a street's or a
|
|
@@ -1878,10 +2187,10 @@ distance. Other players' names show within
|
|
|
1878
2187
|
12 m, smaller than in a game. A town labels everything it has -- every
|
|
1879
2188
|
statue, board, pad and NPC -- and all of it at once was a wall of text from
|
|
1880
2189
|
the arrival spot; the words are there when the player walks over. A game
|
|
1881
|
-
place
|
|
2190
|
+
place uses the default world label focus above.
|
|
1882
2191
|
|
|
1883
2192
|
**Labels kept near (v1.43).** A deck whose `hub` block says `"labels":
|
|
1884
|
-
"near"` has its
|
|
2193
|
+
"near"` has its root town draw less still, for a world too wide for names seen
|
|
1885
2194
|
from anywhere. The world labels are the ones `hub.label` puts over scene
|
|
1886
2195
|
actors as a plate (plain or `"tag"`), an NPC's line (`"speech"`) or a
|
|
1887
2196
|
`"sign"`:
|
|
@@ -2574,6 +2883,66 @@ it in the decor tray, Rooms tab or pet book according to its class.
|
|
|
2574
2883
|
|
|
2575
2884
|
## 12. Wire (kit-internal, listed so a host or bot can speak it)
|
|
2576
2885
|
|
|
2886
|
+
### Weakest-phone picture (v1.97, opt-in)
|
|
2887
|
+
|
|
2888
|
+
A deck with both `hub.tiers: true` and `hub.weakestTier: true` offers a
|
|
2889
|
+
Weakest choice beside Auto, Low and High. Auto chooses this profile on a
|
|
2890
|
+
WebGL renderer matching PowerVR GE8xxx (including PowerVR Rogue GE8320).
|
|
2891
|
+
Low on that hardware uses the same profile; High always draws the full picture.
|
|
2892
|
+
With the same opt-in, Mali-G52 MC1/MC2 renderers use a middle profile on Low:
|
|
2893
|
+
ordinary Low plus half of each renderer/composer pixel ratio and district sleep.
|
|
2894
|
+
Middle keeps the authored models and normal look baking and does not enable
|
|
2895
|
+
far-avatar merging. A manual Weakest choice takes precedence; High disables it.
|
|
2896
|
+
Other GPUs retain their existing Auto/Low policy, and may choose Weakest by
|
|
2897
|
+
hand. No frame-rate probe selects this profile. A saved Weakest choice is ignored
|
|
2898
|
+
in decks without the opt-in. The client flag is omitted from server manifests
|
|
2899
|
+
and network state.
|
|
2900
|
+
|
|
2901
|
+
The town scene additionally declares `weakestDistricts`:
|
|
2902
|
+
|
|
2903
|
+
```json
|
|
2904
|
+
{"version":1,"districts":[{"id":"square","outline":[[-14,-14],[14,-14],[14,14],[-14,14]]}],
|
|
2905
|
+
"actors":[{"id":"wall","districts":["square"],"origin":[0,0],"bounds":[-2,-2,2,2]}]}
|
|
2906
|
+
```
|
|
2907
|
+
|
|
2908
|
+
Outlines use x/z metres. Each row's `origin` is the authored Transform `[x,z]`,
|
|
2909
|
+
used to track displacement across mode switches. Each actor's bounds include its physical footprint,
|
|
2910
|
+
including parts of referenced models; membership lists every district that
|
|
2911
|
+
footprint intersects. This is a physical activation table, separate from the
|
|
2912
|
+
occlusion visibility cells. `WEAKEST_TIER=1` in the world assembler emits it and
|
|
2913
|
+
the deck flag; unset emits neither. A malformed table or a player outside its
|
|
2914
|
+
outlines falls back to ordinary Low. Untagged actors, the local player, route
|
|
2915
|
+
anchors and dynamic bodies stay live. Weakest protects only this player's current
|
|
2916
|
+
`labelsMe` guidance targets (quest/stamp pointers and guide-route pads), including
|
|
2917
|
+
far NPCs. Shared `labels` targets sleep with their far district on Weakest; the
|
|
2918
|
+
same-district and four-metre apron rules still wake nearby pads. Middle protects
|
|
2919
|
+
both shared `labels` and this player's `labelsMe` targets. Protected targets stay
|
|
2920
|
+
awake and newly received targets wake immediately. Authored hidden templates below y=-50
|
|
2921
|
+
sleep until shown. Four metres around the player's position wake actors before
|
|
2922
|
+
crossing a district boundary. Moving actors' bounds follow their current
|
|
2923
|
+
Transform. The table is checked each 100 ms and immediately on district changes.
|
|
2924
|
+
|
|
2925
|
+
Sleeping preserves components, behavior state, serialization and actor ID lookup,
|
|
2926
|
+
while behavior, render and collider passes omit the actor. The client restores
|
|
2927
|
+
all actors and its original model files on High, scene loads, door trips or
|
|
2928
|
+
runtime disposal. The server and other players retain the full town. Weakest's per-runtime
|
|
2929
|
+
model file views invalidate built nodes while preserving authored look data.
|
|
2930
|
+
The look-bake queue suppresses outlines and AO without mutating
|
|
2931
|
+
the editor's files; the remaining look work is deferred. Weakest caps its
|
|
2932
|
+
renderer and composer buffers at a pixel ratio of at most 0.5; both
|
|
2933
|
+
previous ratios return on exit unless another owner has changed them. The district
|
|
2934
|
+
controller is created only when the middle or weakest profile is selected with
|
|
2935
|
+
a valid district table. The weakest runtime
|
|
2936
|
+
also uses the engine's empty-part pruning, preserving animated and attachment
|
|
2937
|
+
parts; the full model build returns on exit. Remote bodies use the
|
|
2938
|
+
existing far-avatar merge, with at most twelve nearest full rigs; unsupported
|
|
2939
|
+
custom rigs retain the existing conservative merge fallback. The official sixteen
|
|
2940
|
+
bodies support merging. Names and worn objects retain their usual rules.
|
|
2941
|
+
|
|
2942
|
+
With either deck key absent, no activation table is read or sleeping/model
|
|
2943
|
+
profile allocated, and the existing Graphics row and rendering policy remain.
|
|
2944
|
+
The scene editor's authored picture is unchanged.
|
|
2945
|
+
|
|
2577
2946
|
### Page visibility (v1.91, opt-in)
|
|
2578
2947
|
|
|
2579
2948
|
A place declaring `visibility: true` is sent `hubPlace.visibility: true`. Its
|
|
@@ -2650,6 +3019,7 @@ not arrived again, and is re-sent all of the above);
|
|
|
2650
3019
|
`{ k: 'hub-ballot', v, face?, line?, option? }` (v1.68, §6: `v` the version string of the card tapped, echoed as received, and ids only; only a place with `ballot` knows it, and in any other place it goes on to the place's `message` hook as before);
|
|
2651
3020
|
`{ k: 'hub-party', op, player?, door? }` (v1.10, §5: `op` `"invite"` with `player`, `"accept"` and `"decline"` with `from` (the inviter), `"leave"`, `"go"` with `door`, `"go-yes"` and `"go-no"` with `id` (the proposal's));
|
|
2652
3021
|
`{ k: 'hub-where', ids }` (v1.9: where up to 12 players of this session are, at most once per 700 ms) and `{ k: 'hub-goto', player }` (v1.9: Join, §5);
|
|
3022
|
+
`{ k: 'hub-house-visit', door, owner }` (2026-10-16, §5: Join on a friend at home; with a platform hub, a well-formed `owner` and a signed-in sender the place sends `hub-go` with no `key` and that `owner`, ending the visit as any door's trip does; otherwise it is `hub-door-jump`);
|
|
2653
3023
|
`{ k: 'hub-grab', actor, op }` (v1.3, `op` `"grab"` or `"throw"`, §6; v1.25, `"hold"` once a second while holding, only in a place with `grab.keepHeld`, dropped unheard by any other);
|
|
2654
3024
|
`{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
|
|
2655
3025
|
`{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text, rid? }` (authored mode
|
|
@@ -2689,6 +3059,19 @@ with a non-null companion, and nothing else: no look, words or target. Only
|
|
|
2689
3059
|
an opted-in place carries it, in snapshots once anyone in this session has
|
|
2690
3060
|
had a companion (including `[]` after the last clears or leaves), and in
|
|
2691
3061
|
deltas only when that whole array changes, latched as `hubWear` is.
|
|
3062
|
+
v1.109 adds the optional latched snapshot field `hubDanceIdle`:
|
|
3063
|
+
`{ actor, file, bpm, beatAt, floors: [{ x, z, halfX, halfZ }] }`, or `null`
|
|
3064
|
+
to clear. `beatAt` is the playing loop's server simulation time (milliseconds)
|
|
3065
|
+
of beat zero, matching `hubSounds[actor].since`. The server sends one changed
|
|
3066
|
+
clock per song change, plus a full snapshot on join/reconnect; no per-beat
|
|
3067
|
+
messages or player dance state. The client uses its existing simulation clock
|
|
3068
|
+
to draw a looping hop/sway on each visible player's model inside those floor
|
|
3069
|
+
bounds. A manual emote takes precedence for its full duration, then the idle
|
|
3070
|
+
returns at the current song phase. Seats and holds take precedence too. Outside
|
|
3071
|
+
the bounds, with a missing/replaced/stopped song, or on session switch, normal
|
|
3072
|
+
posing returns. The idle changes no Transform, physics body, manual cooldown,
|
|
3073
|
+
call or answer. Places that never call the API send no new field.
|
|
3074
|
+
|
|
2692
3075
|
Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
|
|
2693
3076
|
a one-shot); `{ k: 'hub-went', players, door }` (v1.15, a town: to each player staying, who of the players they may see went through `door`); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
|
|
2694
3077
|
client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
|
|
@@ -2727,7 +3110,9 @@ on change and replayed on a fresh `hub-hello` without `again` when a line is lat
|
|
|
2727
3110
|
never in a snapshot), `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }` (v1.72: with `again: true` when a resume place says it again, I3),
|
|
2728
3111
|
`{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
|
|
2729
3112
|
`{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }` (since v1.17 `disclosure` is always `"participants"` and `hearRange` always 0: a client from before it named the players in that range as a turn's listeners),
|
|
2730
|
-
|
|
3113
|
+
(v1.142) A child mind open may also carry `choices: [{ id, label }]` from that character's published `childAsks` (§13), without prompts; this takes precedence over legacy `choices: string[]` from `under13Choices`. (v1.148) Or `choices: string[]` with `authoredChoices: true`: the place's authored asks for that speaker, answered by the place (§13); these lead bundle chips.
|
|
3114
|
+
|
|
3115
|
+
`{ k: 'hub-npc', npc, open, ... }` gains `opening: { text, asks, more? }` where the place's `npcOpening` gave one (v1.37), or a mind gets the kit's default (v1.46; `more` only when non-empty), and `ageOff: true` (2026-10-17) only in the open of a mind sent to a speaker whose trusted server identity has `under13 === true`, in every place whatever `under13Choices` says (absent otherwise, and never in anyone else's message), `{ k: 'hub-npc-line', npc, text, why, op?, rid? }` (`why` v1.8, as `npcLine`'s; v1.46 `op` is the refused mind turn's operation id, absent for other lines; `rid` echoes an authored send's request id, a string of at most 64 characters, only when given), `{ k: 'hub-npc-notes', npc, prefix, persistentAsks? }` (v1.8, §13; v1.80 `persistentAsks` only where the place defines `npcAsks`, up to two private chips, an empty array clears), `{ k: 'hub-npc-opening', npc, text }` (v1.47, a late inspect's greeting for an open panel whose player has not yet sent words, §13), `{ k: 'hub-npc-hooks', hooks: [{ npc, character }] }` (v1.76, due greeting body/character ids for that signed-in player alone, no text, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
|
|
2731
3116
|
hidden pair that this player may see, laid over the shared `hubAv`; v1.51: stand-ins as `hubAv`'s are, with `hubAv2` beside it in the same message when one of them wears `4` or more, laid over the shared `hubAv2`; the message is whole, so one without `hubAv2` says none of them does), `{ k: 'hub-wear', hubWear }`
|
|
2732
3117
|
(v1.4, their wearables, laid over the shared `hubWear` the same way),
|
|
2733
3118
|
`{ k: 'hub-earned', hubEarned }` (v1.53, the earned items of players in a
|
|
@@ -2823,6 +3208,139 @@ This mode uses the existing `hubPlace.resume: true` and `hub-hello` fields;
|
|
|
2823
3208
|
there are no new wire keys. Retention state is allocated only for this object
|
|
2824
3209
|
form. No other deck's behavior, state or wire bytes change.
|
|
2825
3210
|
|
|
3211
|
+
#### Retained private visibility (v1.116)
|
|
3212
|
+
|
|
3213
|
+
`hub.resumeVisibility: true` may accompany this mode when the game's private
|
|
3214
|
+
actor masks are part of the retained round. The kit then keeps the viewer's
|
|
3215
|
+
current per-actor hide/show map only while this same visit is absent. This
|
|
3216
|
+
option requires an exported `resume` hook. For a retained visit with a trusted
|
|
3217
|
+
authenticated identity, on a fresh, resume, or kit-generated silent hello,
|
|
3218
|
+
the kit holds the stale map and action dispatch, invokes that
|
|
3219
|
+
hook before the next authored `step`, then sends the complete current map.
|
|
3220
|
+
The synchronous hook can cancel or revalidate deck-owned queued action intents
|
|
3221
|
+
before that step matures them; the kit does not cancel those intents itself.
|
|
3222
|
+
Intent preparation performed only after an `await` is outside this ordering
|
|
3223
|
+
guarantee; returned promises are not awaited or cancelled. The hook must synchronously issue every `hub.hide/show` needed for the current board before it returns or first
|
|
3224
|
+
awaits. Both directions are restored: a shared-hidden actor privately shown to
|
|
3225
|
+
the viewer, and a shared-visible actor privately hidden from them. Calls made
|
|
3226
|
+
while the viewer is disconnected remain ignored.
|
|
3227
|
+
|
|
3228
|
+
An opted-in retained visit without a trusted string identity (anonymous or
|
|
3229
|
+
unknown) cannot be fenced to the same account. The kit ends and forgets that
|
|
3230
|
+
visit through normal `leave` cleanup before cached actions or authored stepping
|
|
3231
|
+
can inherit it; the returning player enters fresh instead. Normalized anonymous
|
|
3232
|
+
null, decimal, and hex ids all follow this rule. Default-off places keep their
|
|
3233
|
+
existing behavior.
|
|
3234
|
+
|
|
3235
|
+
For an eligible same-identity retained visit whose progress marker was already
|
|
3236
|
+
committed and has no existing progress or account reset lock, the synchronous
|
|
3237
|
+
resume prefix runs against that committed state before the kit issues the
|
|
3238
|
+
hello's automatic marker refresh. A later reset marker still applies the ordinary
|
|
3239
|
+
generation cleanup; the new read blocks progress mutations while pending. This
|
|
3240
|
+
ordering does not bypass a read already in flight, an unknown marker, or a reset
|
|
3241
|
+
or read failure.
|
|
3242
|
+
|
|
3243
|
+
The place's authored `step` always continues. If a progress read still blocks
|
|
3244
|
+
this opted-in preparation, the kit immediately ends and forgets only that
|
|
3245
|
+
retained visit through the normal `leave` cleanup before stepping. This covers
|
|
3246
|
+
reset hooks that throw, reject, or never settle: the place does not wait for
|
|
3247
|
+
them. A synchronous resume-hook throw fails closed the same way. A retained
|
|
3248
|
+
hello queued inside a resume hook cannot drain again in the same step; its visit
|
|
3249
|
+
also ends through this cleanup rather than delaying authored stepping. The affected
|
|
3250
|
+
player's next hello uses fresh entry, and late progress completion cannot resume
|
|
3251
|
+
the forgotten entry. Action presses for a pending viewer are rejected, not
|
|
3252
|
+
queued. The old map is not replayed while preparation is pending.
|
|
3253
|
+
|
|
3254
|
+
The retained map is bound to the authenticated roster identity captured for
|
|
3255
|
+
the visit, not only to `playerId`. A missing or changed identity deletes it and
|
|
3256
|
+
sends at most an empty clear; switching back cannot recover it. Expiry,
|
|
3257
|
+
explicit kit travel, shutdown, and every other final `forget` delete it too.
|
|
3258
|
+
Anonymous viewers therefore use the existing departure cleanup.
|
|
3259
|
+
|
|
3260
|
+
This does not make the shared WORLD snapshot and the later private message one
|
|
3261
|
+
atomic client update. Live reconnects can receive WORLD before hello and the
|
|
3262
|
+
prepared `hub-vis`. On an ordinary resumed page the client retains its prior
|
|
3263
|
+
private map while applying WORLD; an actor newly made private while it was away
|
|
3264
|
+
can still appear until the prepared replay. A client whose local state was
|
|
3265
|
+
cleared has only WORLD's shared view during that interval. The contract
|
|
3266
|
+
guarantees only server send ordering: synchronous resume mask writes precede
|
|
3267
|
+
the complete `hub-vis` replay. It does not promise when the browser draws WORLD
|
|
3268
|
+
or that replay. Masks written only after an `await`, or a hook that fails before
|
|
3269
|
+
rebuilding them, are outside even that current-map guarantee. A place that
|
|
3270
|
+
needs a pre-hello atomic mask still needs a separate snapshot or client gate
|
|
3271
|
+
contract. The option is server-only and adds no key to `hubPlace`; absent
|
|
3272
|
+
preserves the existing resume ordering, cleanup and bytes.
|
|
3273
|
+
|
|
3274
|
+
### Town pose retention (v1.98)
|
|
3275
|
+
|
|
3276
|
+
A non-result place may set `hub.resumePose: true` (also valid on a named
|
|
3277
|
+
place). Only `true` or absence is valid; result places must use their existing
|
|
3278
|
+
`resume` modes instead. Towns without this key keep their existing behavior
|
|
3279
|
+
and wire bytes. This server-only option adds no client manifest or wire fields.
|
|
3280
|
+
|
|
3281
|
+
The kit keeps an arrived visit for strictly less than **five wall-clock
|
|
3282
|
+
minutes** after the first observed absence, or after the last tick with the
|
|
3283
|
+
old body when a replacement appears between ticks. A return under the same
|
|
3284
|
+
player id restores the last server pose and facing before hello replay and
|
|
3285
|
+
before the deck's next step, with a short settling period for stale movement
|
|
3286
|
+
reports. The visit remains arrived: its previous door provenance cannot trigger
|
|
3287
|
+
another arrival or door-exit placement. Existing private-channel replay and the
|
|
3288
|
+
optional `resume` hook restore its UI without a `leave` or `arrive`.
|
|
3289
|
+
|
|
3290
|
+
At or after five minutes the old visit leaves once; a return then arrives afresh.
|
|
3291
|
+
A new player ID still arrives separately and runs the deck's arrival hook. With server deck storage available, its first hello waits for a server-owned pose record keyed by user ID, place, and house owner (if any). A record from an ended visit is consumed only for strictly less than **ten wall-clock minutes** after departure. The full position (including depth) and facing replace normal arrival placement after the hook and before the next deck step, with the usual settling period. The arrival hook rebuilds private UI, including a house's fixed shot. Anonymous players and unpublished sessions without deck storage keep the normal new-ID arrival path. Explicit kit travel clears the stored pose before that socket leaves; a later genuine door return arrives normally.
|
|
3292
|
+
Explicit kit travel bypasses retention, and shutdown drains each retained visit
|
|
3293
|
+
once. As with result-place retention, unexplained departures, including Back or
|
|
3294
|
+
closed tabs, may delay `leave` until expiry because the transport supplies no
|
|
3295
|
+
close reason. Absent bodies are not in `hub.players()` and cannot interact.
|
|
3296
|
+
(v1.145) While such a visit is retained for a signed-in player, the kit also
|
|
3297
|
+
keeps their private visibility (`hide`/`show` with `to`) and companion, as it
|
|
3298
|
+
keeps their HUD and labels: calls naming them meanwhile are taken (and return
|
|
3299
|
+
true) but nothing is sent, and the same account's return replays the whole
|
|
3300
|
+
visibility map and the latest companion. A return under another account, or
|
|
3301
|
+
none, gets only clears; guests are not retained, as before. Expiry, explicit
|
|
3302
|
+
travel and shutdown forget both with the visit.
|
|
3303
|
+
Retention cannot keep a host session process alive. Ended-visit pose records survive private-session shutdown via server-owned deck storage; other visit state does not. Read/write failure falls back to a normal arrival. The existing same-ID five-minute path is unchanged. Existing result-place `resume: { keep: true }` retains its strict
|
|
3304
|
+
60-second window, and `resume: true` retains immediate leave/re-arrive behavior.
|
|
3305
|
+
|
|
3306
|
+
### Pose-only reconnect (v1.117)
|
|
3307
|
+
|
|
3308
|
+
`hub.resumeArrivalPose: true` keeps a session-local copy of an arrived player's
|
|
3309
|
+
last server position and facing. It does not retain the arrived visit: ordinary
|
|
3310
|
+
transport departure calls the authored `leave` even when a replacement socket
|
|
3311
|
+
rejoins the same id between ticks. Ordinary reconciliation remains a fallback.
|
|
3312
|
+
During that callback, `hub.players()` excludes bodies absent from the trusted
|
|
3313
|
+
roster even before physical reconciliation removes them. Departure clears private channels,
|
|
3314
|
+
and removes the player from live membership. On a same-id reconnect, normal
|
|
3315
|
+
hello and `arrive` run again. After that hook, the matching signed-in account's
|
|
3316
|
+
pose replaces normal placement and settles stale movement reports. No storage
|
|
3317
|
+
read, promise, client acknowledgement or other player's preparation delays the
|
|
3318
|
+
place. Awards, held work, fishing casts and authored grace remain the deck's
|
|
3319
|
+
responsibility through its existing hooks.
|
|
3320
|
+
|
|
3321
|
+
The copy expires at 60 wall-clock seconds after ordinary departure. A matching
|
|
3322
|
+
hello inside that window claims it once together with the visit bookkeeping.
|
|
3323
|
+
Normal arrival preparation cannot expire an accepted claim; arrival checks the
|
|
3324
|
+
current authenticated owner again before restoring it. Repeated hellos keep only
|
|
3325
|
+
the same owner’s pending claim. Forgetting that pending entry discards its claim.
|
|
3326
|
+
It is consumed once and bounded to 128 entries per process. Anonymous or changed
|
|
3327
|
+
identities, new player ids, expiry, ended visits, explicit kit travel and
|
|
3328
|
+
shutdown receive no restored pose. An explicit friend target also takes normal
|
|
3329
|
+
placement. Session shutdown loses these copies; this option never extends host
|
|
3330
|
+
session lifetime or persists across processes.
|
|
3331
|
+
|
|
3332
|
+
On result places, `resume: true` is required separately and continues to keep
|
|
3333
|
+
one result, the original deadline, end state and provenance. A matching pose
|
|
3334
|
+
qualifies a plain first-page hello as that same resumed visit too; reloading
|
|
3335
|
+
cannot accept a pose while starting another result or deadline. A private
|
|
3336
|
+
`hub.leaving` line does not retire a pose. Retained-visit
|
|
3337
|
+
modes (`resume: { keep: true }`, `resumePose`, `houseResume`) are incompatible
|
|
3338
|
+
and rejected. `resumeVisibility` remains exclusive to its existing keep mode;
|
|
3339
|
+
pose-only reconnect instead uses ordinary leave cleanup and fresh arrival masks,
|
|
3340
|
+
with no old private mask replay. This server-only key accepts only `true` or
|
|
3341
|
+
absence, adds no public manifest or wire field, and allocates no pose cache when
|
|
3342
|
+
absent. Existing modes and absent-key wire bytes are unchanged.
|
|
3343
|
+
|
|
2826
3344
|
### A deck's retained-hello signal (v1.89)
|
|
2827
3345
|
|
|
2828
3346
|
A deck may export `resume(hub, { playerId })` alongside its other hooks. Hook
|
|
@@ -2833,17 +3351,24 @@ id and clients sending `resume: true` both qualify. First arrivals and genuine
|
|
|
2833
3351
|
re-arrivals do not. The keep mode's server-generated silent-return hello also
|
|
2834
3352
|
qualifies, so a short drop can restore a deck's current tutorial HUD or pointer.
|
|
2835
3353
|
|
|
2836
|
-
The hook runs at the end of the next server step, after the private
|
|
2837
|
-
labels, tune and avatar replay sends. This orders server sends; it does not
|
|
2838
|
-
wait for client acknowledgement.
|
|
2839
|
-
|
|
2840
|
-
|
|
2841
|
-
|
|
2842
|
-
|
|
2843
|
-
|
|
2844
|
-
|
|
2845
|
-
|
|
2846
|
-
|
|
3354
|
+
The hook normally runs at the end of the next server step, after the private
|
|
3355
|
+
HUD, labels, tune and avatar replay sends. This orders server sends; it does not
|
|
3356
|
+
wait for client acknowledgement. With v1.116 `resumeVisibility: true`, its
|
|
3357
|
+
synchronous prefix instead runs before the next authored `step` and retained
|
|
3358
|
+
visibility replay; §12's retained-private-visibility rules define that narrower
|
|
3359
|
+
guarantee. It does not await async continuation or cancel deck-owned promises.
|
|
3360
|
+
Repeated qualifying hellos for one id in a step coalesce into one callback. A
|
|
3361
|
+
keep-mode silent-return signal and its late client resume hello share one
|
|
3362
|
+
callback. The player must still be arrived with a connected body when
|
|
3363
|
+
dispatched; a blocking progress read normally keeps it queued. With
|
|
3364
|
+
`resumeVisibility: true`, blocked preparation instead ends that retained visit
|
|
3365
|
+
before authored stepping as described above. Leaving and kit-issued travel
|
|
3366
|
+
cancel pending work. A trip reported shut allows later
|
|
3367
|
+
resumes again. An avatar-change hello alone does not queue it. A hook may update
|
|
3368
|
+
the private HUD and labels, which their normal sends deliver on the following
|
|
3369
|
+
step. Returns are ignored; throws and rejected promises are contained. Async
|
|
3370
|
+
work is not awaited or cancelled, so a deck should restore its current state
|
|
3371
|
+
synchronously.
|
|
2847
3372
|
|
|
2848
3373
|
A deck without this hook allocates no pending-signal state and receives no
|
|
2849
3374
|
callback. No new packets, wire keys or manifest fields are added.
|
|
@@ -3077,6 +3602,53 @@ instead, so a crowd degrades to authored lines rather than a queue. The reply
|
|
|
3077
3602
|
is ghost's text, shown in the speaker's panel and over the body for the
|
|
3078
3603
|
speaker alone.
|
|
3079
3604
|
|
|
3605
|
+
**Tap-only child mind chat (v1.142).** A speaker whose trusted
|
|
3606
|
+
`session.players[]` identity has `under13 === true`, talking to a mind whose
|
|
3607
|
+
published `characterBundle.characters[]` entry has `childAsks`, receives those
|
|
3608
|
+
choices in every place, independently of `under13Choices`. `childAsks` is an
|
|
3609
|
+
optional array of 3-4 `{ id, label, prompt }` entries: ids are unique non-empty
|
|
3610
|
+
strings, labels are non-empty and at most 40 characters, prompts non-empty
|
|
3611
|
+
and at most 300. The kit validates these limits; ghost validates the published
|
|
3612
|
+
bundle and remains the authority for child eligibility and checked replies.
|
|
3613
|
+
The server keeps the bundle outside the public manifest and sends only
|
|
3614
|
+
`choices: [{ id, label }]`, never the prompts.
|
|
3615
|
+
|
|
3616
|
+
For this child conversation, the kit skips cached greetings, place notes,
|
|
3617
|
+
persistent asks and place tools; v1.148 asks `npcOpening` only to learn
|
|
3618
|
+
whether the place has authored taps, and otherwise ignores its words. Its fixed greeting is
|
|
3619
|
+
"Tap a question to talk with <short name>." The client independently uses
|
|
3620
|
+
that kit greeting and ignores deck opening text, late `hub-npc-opening`,
|
|
3621
|
+
`hub-npc-line` and notes messages. No scripted line is sent to that child.
|
|
3622
|
+
The panel shows all 3-4 chips with the reply area and no text box or "or try:"
|
|
3623
|
+
caption; typing being off does not remove these object chips. A successful
|
|
3624
|
+
inspect still gates sends. A tap displays the label and sends exactly
|
|
3625
|
+
`choice:<id>`, with no notes prefix. Admission checks the raw token against
|
|
3626
|
+
that character's `childAsks`, including on replay, and rejects anything else
|
|
3627
|
+
with `HUB_NPC_CHOICE_REQUIRED`. Model suggestions are ignored; the authored
|
|
3628
|
+
chips return after a reply and may be asked again. A child open with chips
|
|
3629
|
+
never shows the 13+ hint.
|
|
3630
|
+
|
|
3631
|
+
Even with `talkLog: true`, the kit skips hub text archive calls for these
|
|
3632
|
+
openings, scripted lines and turns, and sends no `hubTextArchive` metadata.
|
|
3633
|
+
Dialogue is kept by ghost in the speaker's own shared-character history.
|
|
3634
|
+
Adults and unknown ages retain their existing flow. Authored NPCs and minds
|
|
3635
|
+
without `childAsks` retain the legacy `under13Choices` / three canned strings
|
|
3636
|
+
behavior; a mind without chips still uses the 13+ hint when appropriate.
|
|
3637
|
+
These additions remain within `hub.contract: 1`.
|
|
3638
|
+
|
|
3639
|
+
**Authored taps (v1.148).** Where `npcOpening` returns `authored: true` with
|
|
3640
|
+
asks, a speaker whose trusted identity has `under13 === true`, talking to a
|
|
3641
|
+
mind (in a place without `under13Choices`), receives those asks as
|
|
3642
|
+
`choices: string[]` with `authoredChoices: true`, ahead of any bundle chips.
|
|
3643
|
+
The panel shows them as tap-only chips, with no text box and no 13+ hint.
|
|
3644
|
+
A tap displays its words and sends `hub-npc-say`: the kit admits exactly one
|
|
3645
|
+
of that open's asks from that speaker and answers it through `npcLine` with
|
|
3646
|
+
`why: 'authored'`, as for a body with no mind. No model or ghost turn is
|
|
3647
|
+
involved, and the kit refuses that speaker's mind turns on this open with
|
|
3648
|
+
`HUB_NPC_CHOICE_REQUIRED`. After the place answers, the chips clear; the next
|
|
3649
|
+
open brings the place's next asks. Over 13s and unknown ages are unchanged.
|
|
3650
|
+
This is how a first-visit welcome's own choices reach a child.
|
|
3651
|
+
|
|
3080
3652
|
**Opening a chat (v1.37, v1.46).** The place's `npcOpening` gives the first
|
|
3081
3653
|
words and up to three questions, with up to nine more to offer later. A hook
|
|
3082
3654
|
that gives text keeps exactly its own words and questions; text with no asks
|
|
@@ -3169,8 +3741,20 @@ added.
|
|
|
3169
3741
|
For a mind, the client reads `inspect` when the Chat prompt first shows
|
|
3170
3742
|
(v1.47), before the panel opens. Pending reads are shared; a success is
|
|
3171
3743
|
remembered on that net. While it is pending, or if ghost refuses it, only the
|
|
3172
|
-
opening is shown: no text box or chips.
|
|
3173
|
-
|
|
3744
|
+
opening is shown: no text box or chips. The tap-only bundle flow above
|
|
3745
|
+
(v1.142) supplies its fixed greeting and authored chips after a successful inspect. A
|
|
3746
|
+
speaker the server marks `ageOff` (§12: trusted `under13 === true`; the
|
|
3747
|
+
client infers no age) refused it also reads one muted plain line under the
|
|
3748
|
+
opening, "Talking with <first name> is for players 13 and up" (the
|
|
3749
|
+
placeholder's name), except where the place gives them `under13Choices`
|
|
3750
|
+
lines (a refusal there shows the opening alone, no chips). A guest is over 13
|
|
3751
|
+
like any other player and has no line of their own. It never shows while the
|
|
3752
|
+
first read is pending, for anyone else or for a body without a mind, and goes
|
|
3753
|
+
once an inspect succeeds. A refusal is logged once per code
|
|
3754
|
+
and retried on a later open, five seconds after a first failed character read
|
|
3755
|
+
and doubling to five minutes, until one succeeds; a success is remembered for
|
|
3756
|
+
later opens, and another session on the same net reads afresh. A turn's status
|
|
3757
|
+
poll gives up after two failed reads. Ghost still decides
|
|
3174
3758
|
who may speak; the kit changes no gate. A player who may type sees "Ask <first
|
|
3175
3759
|
name> anything…" at the bottom, with chips below it under "or try:". The field
|
|
3176
3760
|
gets focus on a desktop with a fine pointer and no touch, never on a touch
|
|
@@ -3309,7 +3893,8 @@ Hello, busy, budget and unavailable lines remain ambient and must carry no
|
|
|
3309
3893
|
player input. A one-slot body retains the existing authored line bytes, so its
|
|
3310
3894
|
place hooks must keep all those public words free of player input.
|
|
3311
3895
|
Where a body has a mind, `busy`, `budget` and `unavailable` lines
|
|
3312
|
-
answer in its place
|
|
3896
|
+
answer in its place (when ghost refused that turn's characters outright, the
|
|
3897
|
+
kit's own unavailable line promises no retry): the speaker's panel marks them as scripted (v1.8), and a
|
|
3313
3898
|
place should have them acknowledge the player ("give me a moment") rather than
|
|
3314
3899
|
answer a question they did not ask.
|
|
3315
3900
|
|
|
@@ -3329,6 +3914,48 @@ what ghost verified: `hub.results` (§7) and a `carry.result` with
|
|
|
3329
3914
|
|
|
3330
3915
|
## 14. Per-player progress (v1.2)
|
|
3331
3916
|
|
|
3917
|
+
Since v1.92, on every hello, including a retained-id replay, the kit opens
|
|
3918
|
+
that signed-in player's platform playthrough
|
|
3919
|
+
and reads its optional `resetGeneration`. The place can also call
|
|
3920
|
+
`await hub.refreshProgress(playerId)` when its server has reason to check
|
|
3921
|
+
again. `hub.progressGeneration(playerId)` returns the last observed marker,
|
|
3922
|
+
including 0 after a successful never-reset playthrough read, or null before a
|
|
3923
|
+
successful read exists. A failed or absent read does not establish generation 0.
|
|
3924
|
+
An unsaved local dev deck has no platform storage, so
|
|
3925
|
+
its hello does not open a playthrough. `hub.progressPending(userId)` tells a
|
|
3926
|
+
place whether that account's marker read or reset hook is still gating private
|
|
3927
|
+
progress; with no argument it reports whether any connected player is gated.
|
|
3928
|
+
A higher marker clears the kit's per-player progress
|
|
3929
|
+
view and calls the optional `progressReset(hub, playerId, resetGeneration,
|
|
3930
|
+
{ arrived })` server hook for each connected id of that account. The hook may
|
|
3931
|
+
return a promise; the kit waits for it before another private HUD frame and
|
|
3932
|
+
before a new arrival. `arrived` says whether that id has already reached the
|
|
3933
|
+
place's `arrive` hook. The place must drop its own cached rows and pending
|
|
3934
|
+
writes, then read storage again. A confirmed reset's failed hook, or a failed
|
|
3935
|
+
read after a marker has been observed, keeps that player's private progress
|
|
3936
|
+
gate closed. A later hello or explicit refresh retries the read and any failed
|
|
3937
|
+
hook at the same marker; failed reads also retry, five seconds after the first
|
|
3938
|
+
failure and doubling to five minutes per player, until one succeeds. An initial
|
|
3939
|
+
marker read that fails or does not settle releases its arrival and private
|
|
3940
|
+
progress gate after five seconds, allowing the place to run on a platform where
|
|
3941
|
+
marker reads are unavailable. It keeps retrying without
|
|
3942
|
+
blocking that fallback arrival again. A later successful read applies any newer
|
|
3943
|
+
reset under the normal protective gate, with `arrived: true` if the fallback
|
|
3944
|
+
already called `arrive`. An absent marker calls no hook and preserves
|
|
3945
|
+
the original deck-facing wire bytes. A deck without the hook still clears the
|
|
3946
|
+
kit's own progress view on a newer marker. This marker is
|
|
3947
|
+
distinct from the playthrough handle's `generation`, which fences its own
|
|
3948
|
+
operations. Generic deck Store writes already dispatched are not atomically
|
|
3949
|
+
fenced by the marker; a place must account for this when its reset must be
|
|
3950
|
+
durable against an older live server or tab.
|
|
3951
|
+
|
|
3952
|
+
QA this marker on a new unlisted copy owned by a non-admin QA account: use a
|
|
3953
|
+
test-only server seam to return a newer `resetGeneration`, clear that account's
|
|
3954
|
+
test rows, and refresh both connected tabs; verify cache rereads, queued-write
|
|
3955
|
+
cancellation, and 30-second/180-second reconnects. This seam is the QA reset
|
|
3956
|
+
path: the live reset mutation is self-only and admin-only, so never use
|
|
3957
|
+
`@jesse`'s progress or grant a QA account admin access to exercise it.
|
|
3958
|
+
|
|
3332
3959
|
A place that keeps a player's progress between visits keeps it in **deck
|
|
3333
3960
|
scope keyed by the player's user id**: `hub.session.storage.deck` under
|
|
3334
3961
|
`'<name>:<userId>'`, with the `userId` the kit hands it (`arrive`,
|
|
@@ -3472,12 +4099,219 @@ still get full rows. A failing player hook retains the existing hidden-pair
|
|
|
3472
4099
|
fallback. This feature **narrows only**: NPC chat, blocks, hidden pairs and
|
|
3473
4100
|
per-viewer overrides never gain a new recipient through interest filtering.
|
|
3474
4101
|
|
|
4102
|
+
The optional deck-level `hub.pongTimeoutMs` (v1.96) is an integer from 0 through
|
|
4103
|
+
2147483647. Absent or 0 preserves the previous joins and server manifest exactly.
|
|
4104
|
+
A positive value is passed to SDK `Multiplayer.join` on the initial public join,
|
|
4105
|
+
legacy destination fallback, and hub session switches (including returns). It is
|
|
4106
|
+
client-only: not part of a place, snapshot or server state. Legacy destination
|
|
4107
|
+
joins themselves do not support this option. The town value is `45000`: ordinary
|
|
4108
|
+
30-second suspension fits within it; an overdue callback after a longer suspension
|
|
4109
|
+
sends a fresh ping and grants the full deadline. Silent receive loss reconnects
|
|
4110
|
+
after a ping plus that deadline (normally up to 70 seconds while active). No
|
|
4111
|
+
editor or non-hub join is changed. Requires the base SDK with pong-timeout support.
|
|
4112
|
+
|
|
3475
4113
|
## Changes in v1
|
|
3476
4114
|
|
|
3477
|
-
|
|
4115
|
+
### v1.112: weekly Cups
|
|
4116
|
+
|
|
4117
|
+
Top-level `hub.weeklyCup: true` opts a deck into weekly event projections. Its
|
|
4118
|
+
ordinary `hub.board(door)` adds distinct-participant counts to the current and
|
|
4119
|
+
previous occurrence. The kit also exposes server-only `hub.cup(playerId,
|
|
4120
|
+
doorId)`, refreshed once a minute only for connected signed-in accounts, and
|
|
4121
|
+
`hub.cupNow(doorId)`, the authoritative event clock paired with that board
|
|
4122
|
+
read. `hub.cupDeckId` is the trusted saved deck namespace for confirming a Cup
|
|
4123
|
+
claim.
|
|
4124
|
+
The private result carries at most the current and previous `YYYY-MM-DD`
|
|
4125
|
+
occurrences and only the two booleans `participated` and `champion`.
|
|
4126
|
+
`participated` means the account posted any valid durable result, including an
|
|
4127
|
+
unranked outcome without a numeric score. `champion` means rank one in a closed
|
|
4128
|
+
previous occurrence, with the earliest valid result winning a tied numeric
|
|
4129
|
+
score. `closesAt` is the authoritative half-open boundary.
|
|
4130
|
+
|
|
4131
|
+
Private maps cover the connected trusted roster, are isolated per player, and
|
|
4132
|
+
are unavailable while a read is pending, after a failed read, or when the
|
|
4133
|
+
player/session/account identity no longer matches the request. They never enter
|
|
4134
|
+
shared wire or deck persistence. They are a rolling presentation projection,
|
|
4135
|
+
not durable reward authority.
|
|
4136
|
+
|
|
4137
|
+
The host supplies a strict finite integer epoch time with the same successful
|
|
4138
|
+
board response. The kit removes this raw metadata from `hub.board`, caches it
|
|
4139
|
+
for the current session, and `hub.cupNow` advances it by elapsed wall time. It
|
|
4140
|
+
returns `null` during refresh, after a malformed or failed paired read or
|
|
4141
|
+
session replacement, and after two missed one-minute refresh intervals. A Cup
|
|
4142
|
+
uses that clock for its exact Saturday 00:00 UTC through Monday 00:00 UTC
|
|
4143
|
+
half-open window and does not fall back to the server's local clock.
|
|
4144
|
+
|
|
4145
|
+
Season 1 starts with the first live Cup and remains open-ended. At occurrence
|
|
4146
|
+
close Ghost may keep subject-stamped hidden placeholders for the reserved
|
|
4147
|
+
`cup-s1` participant badge and `cup-s1-champ` champion badge. On any later
|
|
4148
|
+
signed-in Town visit, the existing `hub.unlock(playerId, reservedId)` operation
|
|
4149
|
+
atomically discovers and converts that player's pending placeholder; a player
|
|
4150
|
+
without that entitlement is refused. Town checks both reserved ids on arrival
|
|
4151
|
+
and at a bounded one-minute retry cadence, then stops each check after a saved
|
|
4152
|
+
receipt and exact `{ deckId, id }` ownership readback from `hub.unlocksOf`.
|
|
4153
|
+
Pending entitlement does not expire at a weekend boundary. Account replacement
|
|
4154
|
+
or scene-lifetime replacement fences delayed receipts. No reward is inferred
|
|
4155
|
+
from `hub.cup`, a board, a rank, or a clock, and no local storage, carry state or
|
|
4156
|
+
coins record pending entitlement. An unavailable `cupDeckId` waits rather than
|
|
4157
|
+
treating an item with the same id from another deck as confirmation. There is
|
|
4158
|
+
no separate claim acknowledgement or pending-entitlement read API.
|
|
4159
|
+
|
|
4160
|
+
`weeklyCup: false` is equivalent to omission. Without the opt-in the manifest,
|
|
4161
|
+
host reads, server API and every wire byte retain their prior shape.
|
|
4162
|
+
|
|
4163
|
+
### v1.107: anonymous entry and sign-up continuity
|
|
4164
|
+
|
|
4165
|
+
Optional place `anonymousEntry: true` offers a `signin` action chip beside an
|
|
4166
|
+
authored HUD line containing “Sign in to”. It asks `Hub.signIn({ reason })`;
|
|
4167
|
+
`signedIn` causes a fresh hello, `dismissed` keeps the visit, and missing SDK
|
|
4168
|
+
support or `UNKNOWN_COMMAND` leaves the authored text. Existing action ids must
|
|
4169
|
+
leave `signin` available in an opted-in place. This behavior needs no deck client
|
|
4170
|
+
code and applies to towns and houses alike.
|
|
4171
|
+
|
|
4172
|
+
The trusted roster identifies guests. Their name tags and People rows read
|
|
4173
|
+
“Guest · name”. The kit exposes `identityUserId` on player, arrival and leave
|
|
4174
|
+
records for reconnect positioning, while guest `userId` remains null for
|
|
4175
|
+
account-only operations. A same-identity sign-up in the same live layer carries
|
|
4176
|
+
position and avatar once, after placement and the account read have both
|
|
4177
|
+
settled (including an empty or failed read). Explicit later avatar choices win.
|
|
4178
|
+
The arrival's trusted `signedUpFrom` names the guest
|
|
4179
|
+
player id so the town can find that connection's existing `n:<username>`
|
|
4180
|
+
first-visit record and copy only its step into `u:<userId>`. Signing into a
|
|
4181
|
+
different account never merges identities. Guest
|
|
4182
|
+
practice wallets, fish logs, jobs and plots are not transferred. The layer-local
|
|
4183
|
+
carry expires after ten minutes and keeps at most 500 guests.
|
|
4184
|
+
|
|
4185
|
+
Absent `anonymousEntry`, the manifest, wire, guest keys and presentation retain
|
|
4186
|
+
their existing behavior. Hosts own authentication and rejoining as the new
|
|
4187
|
+
account; decks never supply credentials or assert the new identity.
|
|
4188
|
+
|
|
4189
|
+
### v1.124: one invite link, up to five friends
|
|
4190
|
+
|
|
4191
|
+
Both ordinary Invite and share intent open straight to `Hub.invite()`'s five-use
|
|
4192
|
+
link; there is no one-friend/crew choice. The panel reads “Invite up to five
|
|
4193
|
+
friends. This link lasts 24 hours.” Native Share is available where supported;
|
|
4194
|
+
Copy link is always explicit. Explore share and House share use this same flow.
|
|
4195
|
+
Cancelling native Share never copies; clipboard success is still required before
|
|
4196
|
+
the copied toast. `Hub.invite({ crew: false })` retains the one-use SDK option.
|
|
4197
|
+
|
|
4198
|
+
Ghost creates new mutual follow pairs only between an eligible over-13 arrival
|
|
4199
|
+
and the inviter. Arrivals do not follow one another. Existing link caps, expiry,
|
|
4200
|
+
pair receipts and per-pair Undo remain unchanged; under-13 arrivals get no
|
|
4201
|
+
follows. Invite admission, placement and access gates keep their existing rules.
|
|
4202
|
+
The SDK default and the kit both send the five-use request explicitly, so
|
|
4203
|
+
earlier base SDK pins and invite-capable hosts can mint the new default. Absent invite capability stays dormant.
|
|
4204
|
+
|
|
4205
|
+
### v1.95 invites (optional)
|
|
4206
|
+
|
|
4207
|
+
A place may declare `invite: true` (absent by default). Only then does its server
|
|
4208
|
+
context expose `hub.invite(playerId)`, which privately sends `{ k: 'hub-invite' }`
|
|
4209
|
+
to an arrived player, at most once per second. The client opens the authored
|
|
4210
|
+
five-use link sheet (v1.124) through the trusted host's `Hub.invite` command.
|
|
4211
|
+
The town offers it from a pair pad with one player; the house offers it to its owner.
|
|
4212
|
+
These offers also need the existing `actions: true` capability.
|
|
4213
|
+
|
|
4214
|
+
On an admitted opt-in connection the kit calls `Hub.inviteArrival()` before the first hello. The host retains
|
|
4215
|
+
the resolved token; Ghost verifies membership and arrival, then makes real mutual
|
|
4216
|
+
follows between each eligible over-13 arrival and the inviter (v1.124).
|
|
4217
|
+
New arrivals never form pairs with prior arrivals; existing pair receipts remain
|
|
4218
|
+
readable and undoable. Under-13 arrivals join no follow set. The kit shows a now-friends
|
|
4219
|
+
line with Undo per pair; `Hub.undoInvite(userId)` removes both directions and replay
|
|
4220
|
+
cannot restore that pair. Follow push is suppressed while the in-app record remains.
|
|
4221
|
+
The returned target uses `destination.hub { version: 1, townDeckId, target: { kind: 'player', id } }`.
|
|
4222
|
+
The first hello carries the accepted target in the existing `near` field, placing
|
|
4223
|
+
the invitee beside the inviter and facing them. In v1.105, opt-in hellos also carry `invited: true`
|
|
4224
|
+
as an authored welcome-flow hint; it grants no placement or follow authority.
|
|
4225
|
+
The client draws a `Your friend` pointer only to the inviter's body in its visible,
|
|
4226
|
+
block-filtered roster, including a brief confirmation when already beside them.
|
|
4227
|
+
Reconnects preserve the invite welcome hint without replaying the initial placement.
|
|
4228
|
+
Town invite arrivals defer the ordinary welcome walk, including for new players;
|
|
4229
|
+
the saved onboarding record remains available on a later ordinary visit.
|
|
4230
|
+
All keys are absent by default. A non-opt-in place adds no API, state, listener or wire field.
|
|
4231
|
+
|
|
4232
|
+
Older hosts answering `UNKNOWN_COMMAND`, and a `CASTLE_HOST_UNAVAILABLE` failure
|
|
4233
|
+
where no SDK host channel exists, finish the arrival check as no invite: no
|
|
4234
|
+
retry or friend-update panel. Transient host failures retain the bounded backoff.
|
|
4235
|
+
Exhausting it offers **Try again** only after a `route` or `ok` response proved
|
|
4236
|
+
the arrival carried an invite; a plain arrival never shows that recovery panel.
|
|
4237
|
+
Route evidence survives the trip to the destination connection and clears on reset.
|
|
4238
|
+
|
|
4239
|
+
v1.103 adds an optional presentation intent to that same capability. An opted-in
|
|
4240
|
+
place may call `hub.invite(playerId, { share: true })`; the server privately sends
|
|
4241
|
+
`{ k: 'hub-invite', share: true }` to that arrived player under the existing
|
|
4242
|
+
one-request-per-second limit. The options object accepts only the optional boolean
|
|
4243
|
+
`share`; other shapes are refused. The client mints the default five-use link (v1.124)
|
|
4244
|
+
with `Hub.invite()` and offers “Join me in <deck title>.” plus that
|
|
4245
|
+
link. Where `navigator.share` exists, the minted link gets a fresh **Share** gesture;
|
|
4246
|
+
cancelling it copies nothing. **Copy link** is always offered explicitly and
|
|
4247
|
+
reports “Link copied” only after the clipboard write succeeds. Only the authored root deck title and returned URL enter the shared text; no
|
|
4248
|
+
roster or account names are inserted.
|
|
4249
|
+
|
|
4250
|
+
This is presentation only: link age, resolution, arrival verification, mutual
|
|
4251
|
+
follows, Undo and the under-13 boundary stay exactly as above. Calling
|
|
4252
|
+
`hub.invite(playerId)` (or passing no true `share`) still sends exactly
|
|
4253
|
+
`{ k: 'hub-invite' }` and opens the same direct five-use sheet in v1.124. A place without
|
|
4254
|
+
`invite: true` still has no invite API, client state, listener or wire field.
|
|
4255
|
+
|
|
4256
|
+
v1.113 adds optional root `hub.bringFriend: true`, requiring `hub.invite: true`.
|
|
4257
|
+
The town then offers **Invite a friend** anywhere to an arrived player, with the
|
|
4258
|
+
existing actions capability. An authenticated invite arrival may route to the
|
|
4259
|
+
inviter's exact live nonscheduled curated pad run when its door has `late_join`
|
|
4260
|
+
enabled and the destination bundle and immutable run pin opted into invites through their own
|
|
4261
|
+
`hub.bringFriend: true` marker.
|
|
4262
|
+
The host returns `{ status: 'route', doorId }` for a house or active run before
|
|
4263
|
+
completion; the existing near target places the friend beside and facing the
|
|
4264
|
+
inviter in that destination. Full, ended or unavailable runs refuse safely;
|
|
4265
|
+
no new run is allocated and ordinary late-join windows are unchanged. The root's
|
|
4266
|
+
immutable pin must also carry the bringFriend opt-in. No new client wire field
|
|
4267
|
+
is introduced. Absent bringFriend, invite-only towns retain their v1.95 solo-pair
|
|
4268
|
+
pad action and town/house routing, with the same bytes and behavior.
|
|
4269
|
+
In opted-in places with an authored floor (`ground.none: true`), near-placement
|
|
4270
|
+
clearance uses the trusted scene player's standing bounds, so the floor under a
|
|
4271
|
+
shorter body does not reject every nearby spot. Ground-backed town and game
|
|
4272
|
+
placement keeps its existing clearance; walls, unsupported spots, blocks and pads
|
|
4273
|
+
still exclude an arrival.
|
|
4274
|
+
|
|
4275
|
+
Minor additions are optional unless their entry says they apply to every deck;
|
|
4276
|
+
a deck written before them remains valid.
|
|
3478
4277
|
|
|
3479
4278
|
| date | change |
|
|
3480
4279
|
| --- | --- |
|
|
4280
|
+
| 2026-10-17 (v1.147) | §5 a joining player's body without a readable saved pose starts on the scene's spawn itself (its x and z, at the v1.48 standing height), not on the multiplayer spawn ring 1.1 m around it. The client starts its own body at the spawn; on the live Town the first WORLD snapped it to its ring slot, and the kit's arrival row back at the spawn then reached it as a correction under the client's 4 m snap distance, eased a quarter of the way a frame: a 1.1 m glide just after the cover lifted (3 of 5 captures, web and TECNO). Players waiting together share the spot until the arrival row spreads them; the row, the v1.40 settle and every later placement are unchanged. Saved and resumed poses are unchanged. A default in every hub place; no key, nothing new sent. |
|
|
4281
|
+
| 2026-10-17 (v1.148) | §12 and §13 authored taps: `npcOpening` may return `authored: true`, meaning the place answers its asks through `npcLine` `why: 'authored'`. A mind's open for a speaker with trusted `under13 === true` then carries those asks as `choices: string[]` with `authoredChoices: true`, ahead of bundle `childAsks`; a tap goes by `hub-npc-say` to the place's authored line, never a mind turn or ghost, and the kit refuses that speaker's mind turns on that open. Chips clear after the place answers. Over 13s and opens without `authored` are unchanged. Within `hub.contract: 1`. |
|
|
4282
|
+
| 2026-10-17 (v1.145) | §12 `resumePose`: a retained signed-in visit keeps its private visibility and companion through the drop (gap-time calls taken, not sent) and replays both to the same account on return; another account gets clears, guests and expiry unchanged. Fixes Town masks and Chirp lost after a same-id token reconnect. Server-only; no manifest or wire change. |
|
|
4283
|
+
| 2026-10-17 (v1.146) | Invite a friend rail: when the host's `Hub.canInvite` answer names the account its links belong to (`userId`, newer hosts: a web guest's included), the rail is offered only while that account is this socket's own player; a host that names none is checked against `User.getCurrent` as before, which has no guest account. No manifest or wire change. |
|
|
4284
|
+
| 2026-10-17 (v1.144) | Server: every session callback receives one session whose `storage`, `hub`, `characters` and `world` requests (async methods and the save verbs) queue at most 6 in flight, under the host broker's per-session cap of 8. A request the broker still refuses with `CAULDRON_STORAGE_RATE_LIMITED` (never forwarded) is sent again after 100 ms to 2 s, five times at most, before the refusal reaches the caller; a `set` or `remove` the SDK may split into several requests (over 32 keys or 256 KiB) is never sent again. `hub.track` (its own broker pool) and `world.catchUp` (it awaits the author's `apply`) are not queued. Handles keep their identity per session; no API, manifest or wire change. |
|
|
4285
|
+
| 2026-10-17 (v1.143) | Client-only `hub.highOnly: true` requires tiers; actors marked `tier: "high"` are omitted on Low (including Middle/Weakest), restored in cooperative 8 ms slices on High, and hidden again on Low. Independent of quality caps; editor and door content unchanged. |
|
|
4286
|
+
| 2026-10-17 | Guests (their own account is anonymous) are over 13 like any other player: the Invite a friend rail follows the host's `Hub.canInvite` answer alone, and the "Sign in (13+)" words on the chat field and a mind's talk panel are gone (the host decides chat and typing for them as for anyone). In-session friend relations (`friendsAmong`, cell interest priority) include guests; results, history and other account-kept state stay signed-in only. No manifest or wire change. |
|
|
4287
|
+
| 2026-10-17 (v1.142) | §12 and §13 tap-only child mind chat: published `childAsks` (3-4 id/label/prompt entries, label ≤40, prompt ≤300) offer object chips in every place, with a fixed kit greeting, checked replies and no text field. Sends and admission use bare `choice:<id>` tokens; no deck openings, scripted lines, notes, tools, model suggestions, hub text archive calls or archive metadata for these conversations. Adult and legacy `under13Choices` flows stay unchanged. Additive within contract 1. |
|
|
4288
|
+
| 2026-10-17 (v1.141) | §4 observed progress: `hub.observed`, `hub.station` and `hub.dwell` (docs/observed-progress.md). Once a tick, before any authored `step`, the kit checks each body's move for reachability at a walker's allowance (the scene Player's speed × `hub.tune` speed × 1.25) or rejects it, then spends it from one signed walking credit (filled by the allowance, capped at 0.4 s of it plus 0.3 m, allowed to go negative): a step leaving the credit at or above zero is funded and earns travel and entry, one below is unfunded and earns nothing until walking or standing pays the deficit back; every placement more than 5 cm from the observed spot and every new body is a reset. A station is entered only by walking out past its exit band and back in on admitted steps. `player.at` and `hub.players().at` remain inputs, not evidence. Lazy: a place that never calls them keeps no state; no manifest or wire change. |
|
|
4289
|
+
| 2026-10-17 | §12 and §13 a mind's `hub-npc` open carries `ageOff: true` only to a speaker whose trusted identity has `under13 === true` (any place); when their inspect is refused the panel shows "Talking with <first name> is for players 13 and up" under the opening, not in an `under13Choices` place, and gone once an inspect succeeds. Other players' bytes are unchanged. No manifest change. |
|
|
4290
|
+
| 2026-10-16 | §5 People list: Join on a friend the host names as at home in their House (`Hub.friends` `home`, `ownerUserId`) goes through the place (`hub-house-visit`, answered by `hub-go` with `owner`, §12) and acquires that door with the owner (`Hub.go(door, { ownerUserId })`), visiting their House; the row reads "inside <name>'s House". Rows without them keep the door jump. No manifest change; the wire additions are additive and travel with the deck's own client and server. |
|
|
4291
|
+
| 2026-10-16 | Invite refusals stop joining and show "This invite is unavailable." after the loading cover lifts. Other public-join failures retry with backoff. No manifest or wire change. |
|
|
4292
|
+
| 2026-10-15 (v1.137) | Optional root `hub.quality`, requiring tiers: pre-build tier pick, skipped Low decor, 8 ms cooperative restoration slices, bystander/label/decor-spawn caps and far NPC prompt cadence. Quality telemetry is deferred; `__hub.tier.quality` exposes it locally. `physicsHz` validates 10–60 and is reserved, no effect yet. |
|
|
4293
|
+
| 2026-10-14 (v1.135) | §1/§5 optional root-only `hub.defaultEnvironment: false` disables the client's fallback clear, fallback fog and canvas fall fade together across the root and mounted content. Authored environment rendering and the server's fall catch and `fall` hook are unchanged; absent or true preserves the default environment. No wire field or contract-major change. |
|
|
4294
|
+
| 2026-10-14 (v1.131) | §9 moves the first sentence of HUD `text` into a one-line bottom-centre next-action pill with a scrim. Top HUD retains title and timer/score; no wire fields change. Authors shorten prompts to about 48 characters; dev warnings and layout QA flag wrapping. |
|
|
4295
|
+
| 2026-10-14 (v1.128) | §10 private goal labels accept bounded `at: { x, y, z }` when the kit advertises `hub.goalPositions`. Coordinates travel only in each recipient's label override, without a spawned actor or shared pose. `about: playerId` excludes blocked pairs in both directions. Callers clear or refresh departed or hidden targets; older kits fall back to location text. Manifest/wire major remains 1. |
|
|
4296
|
+
| 2026-10-14 (v1.125) | §5 every card in the shared ask slot retires client-side 12 s after first display, at 3 m of x/z movement, or on entry to any pad. The lease survives redraw, priority suppression and same-identity reconnect replay; local producer deadlines become pending-only after display, taps revalidate it and passive expiry sends nothing. Received invitation clears and new identities create later occurrences; indistinguishable same-sender packets are one observable offer, and server withdrawal may dismiss party offers sooner. Universal kit chrome behavior, with no manifest key or wire change; leaving toast unchanged. |
|
|
4297
|
+
| 2026-10-14 (v1.124) | Invite and share intent open directly to one five-use, 24-hour link through the SDK default, with native Share where supported and explicit Copy link. New follow pairs join each eligible over-13 arrival only to the inviter; legacy receipts and per-pair Undo remain. Under-13 arrivals get no follows; absent invite capability stays dormant. |
|
|
4298
|
+
| 2026-10-13 (v1.118) | §5 Android mobile landscape visits with a host trail draw the kit Back unless the host advertises window.CastleEmbed.hubBackInLandscape as true. Includes House visits without a local ticket; uses existing modal dismissal and Hub.back return guards. Updated hosts advertise at document start and post-load, retaining sole Back ownership; old kits ignore the capability. iOS, portrait, browser, root and transition behavior stays unchanged. |
|
|
4299
|
+
| 2026-10-13 (v1.117) | §1/§12 optional server-only `resumeArrivalPose: true`: session-local, one-use same-id/same-signed-in-account pose/facing restoration strictly within 60 seconds, after ordinary `leave` and `arrive`. No retained membership, private masks, rewards, casts or grace. Result places require existing `resume: true`; retained-visit modes conflict. Travel, ended visits, expiry, identity change and shutdown clear or refuse restoration. Absent allocates no cache and preserves lifecycle and wire bytes. |
|
|
4300
|
+
| 2026-10-13 (v1.116) | §1/§10/§12 optional server-only `resumeVisibility: true`, valid only with `resume: { keep: true }` and an exported `resume` hook: retain same-authenticated-viewer private actor masks for the bounded visit, hold stale replay and action dispatch, synchronously prepare through the existing hook before the next authored step, then send the complete override. Blocked preparation or a synchronous hook throw ends and forgets only that retained visit through normal leave cleanup; the place never waits. Deck-owned intents remain the hook's responsibility. Async resume promises are not awaited or cancelled; identity change, expiry, travel, shutdown and forget delete the cache. WORLD and private replay are not atomic, and async-late or throwing preparation has no current-view guarantee. Absent preserves existing resume ordering, cleanup and wire behavior. |
|
|
4301
|
+
| 2026-10-11 (v1.113) | Optional root `hub.bringFriend: true`, requiring invites: town-wide Invite a friend action and trusted exact live late-join run routing through the existing route response and near placement. Absent preserves invite-only v1.95 behavior; no run creation or ordinary late-join window change. |
|
|
4302
|
+
| 2026-10-11 (v1.112) | §1/§4 optional top-level `hub.weeklyCup: true`: weekly public boards add current/previous distinct valid-result participant counts (including unranked outcomes); bounded minute refreshes add isolated current/previous result bits for the connected trusted roster through server-only `hub.cup`, and the paired authoritative event clock through `hub.cupNow`. Pending, failed, stale and identity-replaced reads fail closed. Season 1 rewards use durable subject-stamped hidden placeholders claimed through existing `hub.unlock`, saved receipt and exact namespaced ownership readback; rolling boards and bits are never reward authority. Daily boards, client wire and decks without the opt-in retain their prior shape. |
|
|
4303
|
+
| 2026-10-11 (v1.111) | Optional main-place `hub.analyticsV111: true`, valid only with `hub.analytics: true`, enables Ghost-owned numeric invite, platform-admission-source and public-join-failure events (kinds 21–25). The saved server config and immutable pin retain the opt-in; no host or client wire changes. Authored `hub.track` cannot emit the new kinds. |
|
|
4304
|
+
| 2026-10-09 (v1.106) | Optional top-level `hub.frameBatch: true` batches ordered world/private packets for capable clients, paces replay at 768 KiB/s plus a reserved 64 KiB/s control lane, and prioritizes visit controls. Combined transport bursts are below 128 KiB; storage/hub requests retain 192 KiB/s headroom against the current 1 MiB/s host budget. Older imports fall back to ordinary packets; absent key preserves existing wire bytes and ordering. |
|
|
4305
|
+
| 2026-10-09 (v1.105) | Optional `invited: true` hello hint, sent and read only for `invite: true` places and carried to the arrival hook's member. It lets an authored welcome flow defer onboarding for an accepted invite; it grants no placement or follow authority. Absent capability preserves existing wire fields and behavior. The existing `near` field carries initial invite placement; reconnects retain the welcome hint without replaying placement. |
|
|
4306
|
+
| 2026-10-09 (v1.103) | Optional `hub.invite(playerId, { share: true })` privately marks the existing invite command as share intent. The client mints the default one-person link and offers text derived from the root deck title through native Share or an explicit clipboard fallback; cancellation never copies. Invite age, arrival, follow and Undo behavior are unchanged; absent intent and absent `invite` preserve ordinary bytes and dormant behavior. |
|
|
4307
|
+
| 2026-10-08 (v1.101) | Optional server-only `under13Choices: true`: trusted hub age boundary, three fixed NPC lines through the existing answer path, server validation on authored/model turns, private UI selection message. Defaults absent. Optional `talkLog: true` appends NPC input, model replies, scripted replies and conversation openings to the platform’s private indefinite archive. No archive read API or TTL; defaults absent. |
|
|
4308
|
+
| 2026-10-08 (v1.99) | §1/§4 optional per-place `freshFriends: true`: 31 s positive/negative permissions, shared read latch/rate gap, expired lookups revalidate, refused/malformed/900 ms timeout fails closed; server-only opt-in flag permits NPC location answers. No new wire fields; absent keys unchanged. |
|
|
4309
|
+
| 2026-10-08 (v1.98) | §1/§12 optional non-result-place `resumePose: true` retains same-id pose/facing and the arrived visit strictly within five minutes, restoring before hello replay or deck step; explicit travel, expiry, shutdown and new-id handling remain distinct. Server-only, no new wire fields; absent keys and existing result resume semantics unchanged. |
|
|
4310
|
+
| 2026-10-08 (v1.95) | Optional `invite: true` place capability, private invite request, trusted-host link creation/arrival and per-pair Undo. Absent preserves the previous protocol. |
|
|
4311
|
+
| 2026-10-08 (v1.97) | Optional client-only `hub.weakestTier` selects the weakest profile through Low on PowerVR GE8xxx, with a manual Weakest choice. Scene-authored physical districts sleep off-district actors, cap full remote rigs at twelve, and skip outline/AO baking. Absent keys preserve existing behavior. |
|
|
4312
|
+
| 2026-10-08 (v1.96) | Optional client-only `hub.pongTimeoutMs` opts hub joins into the SDK pong deadline; absent/0 preserves previous behavior. |
|
|
4313
|
+
| 2026-10-08 (v1.93) | Optional main-place `hub.analytics: true` adds server-only `hub.track(playerId, eventName, { subject?, value?, result?, flags? })`; numeric-only authenticated telemetry, creator exclusion, town attribution and old-host no-op. No client wire fields or default state. See [analytics](analytics.md). |
|
|
4314
|
+
| 2026-10-08 (v1.92) | §14 optional platform `resetGeneration` read on hello and through `hub.refreshProgress`. A newer marker clears kit progress views and awaits an optional place cache drop and reread before its private HUD. No marker preserves existing payloads. |
|
|
3481
4315
|
| 2026-10-08 (v1.91) | §1/§12 opt-in per-place `visibility: true`, coalesced `hub-visibility` client signal and `visibility(hub, { playerId, visible, at })` server hook. Hidden delivery is immediate; absent key preserves listeners, state and wire bytes. |
|
|
3482
4316
|
| 2026-10-08 (v1.90) | §13 optional `hub.preferNpc(playerId, npcId \| null)` privately prefers an in-range physical NPC for the talk button, with nearest fallback, explicit clear, departure cleanup and retained-hello replay. Optional NPC `holdMovement(boolean)` cancels and prevents walks/follows, including asynchronous token reads, until cleared. No opt-in means no new bytes or behavior. |
|
|
3483
4317
|
| 2026-10-07 (v1.89) | §1/§12 optional `resume: { keep: true }` retains a result-place visit through a same-id reconnect strictly within 60 wall-clock seconds: restore pose, arrival time, hold, tune, provenance and result eligibility without leave/arrive; expiry and shutdown leave once, and a return after expiry is fresh. Existing `resume: true` and absent keys keep their old behavior and bytes; the object form uses existing wire fields only. Optional `resume(hub, { playerId })` (§2/§12) signals retained-id hellos after private replay sends, allowing a deck to reinstall its current HUD and pointer without an arrival; hook presence is the opt-in, including for towns. |
|
|
@@ -3586,3 +4420,384 @@ Minor additions, each optional; a deck written before them reads the same.
|
|
|
3586
4420
|
| 2026-10-02 (v1.1) | §13 minds on every layer: on an SDK with `Multiplayer.placeCharacters` the main place joins a layer and its NPCs read `session.characters`, one memory per place; `npcs.route` is the fallback for older SDKs. A deck without `npcs` is unchanged |
|
|
3587
4421
|
| 2026-10-02 (v1.1) | §10 `hub.move` and `hub.tint`; §4 `hub.actorsWith` adds `shape` and `body`. The snapshot carries `tints` (§12). M1's Vault Crew and Tile Fall said a plate's or tile's state with labels and could not have a moving platform; Zone Wars and Summit Sprint repeated each zone's and pillar's size in its marker |
|
|
3588
4422
|
| 2026-10-06 (v1.70) | §1 and §11 home unlocks: up to 6 furniture or deed items in addition to 8 wearable earned items, `piece` instead of `shape`, shared unique ids; `docs/home-pieces.md` is the catalogue, an unlisted piece warns and stays owned. `hub.unlock` keeps home ownership and announces "Sent to your house" on first unlock, session-only for guests/dev serve; `hub.unlocksOf` includes home items, the wardrobe filters them out, and `hub.wearEarned` refuses them with `_NOT_WEARABLE`. Home items never enter the shown slot or earned wire; decks and players without home items send and receive the same bytes. SDK types distinguish `piece` and `shape`. |
|
|
4423
|
+
|
|
4424
|
+
### v1.109: beat-synchronised floor dance idle
|
|
4425
|
+
|
|
4426
|
+
The optional `hub.danceIdle` verb and `hubDanceIdle` snapshot clock draw local
|
|
4427
|
+
looping dance poses without server emotes or beat traffic. Manual emotes retain
|
|
4428
|
+
their existing call-answer and cooldown behavior. See §4's verb table and the
|
|
4429
|
+
wire shape above.
|
|
4430
|
+
|
|
4431
|
+
### v1.115: owner-house reconnect retention
|
|
4432
|
+
|
|
4433
|
+
Optional place key `hub.houseResume: true` (also in a `hub.places` block), only
|
|
4434
|
+
for a place without a result. Ghost grants it to the host only on a trusted
|
|
4435
|
+
owner-house instance. Key absent keeps existing manifest and wire bytes.
|
|
4436
|
+
|
|
4437
|
+
Ghost stamps the grace value `reconnectWindowMs: 180000` into the owner-house
|
|
4438
|
+
session spec. A capable host retains each disconnected participant and token
|
|
4439
|
+
through that deadline and keeps an empty opted-in house alive for that window. A guest reconnect is
|
|
4440
|
+
admitted only into that same live instance while its owner has a live connection;
|
|
4441
|
+
otherwise the existing spent-handoff recovery returns through the Town ticket.
|
|
4442
|
+
The owner can resume without another owner connection. Ghost also pins the same180-second grace on trusted Town sessions. Towns
|
|
4443
|
+
retain the same visit and pose, without a fresh arrival hook; door game specs
|
|
4444
|
+
keep their existing values. Missing spec grace preserves legacy transport
|
|
4445
|
+
behavior. Live joins may replace the oldest disconnected held identity when
|
|
4446
|
+
a stamped instance reaches its cap; the evicted token is revoked and its
|
|
4447
|
+
next admission is fresh. Live and held occupancy are counted separately.
|
|
4448
|
+
Explicit travel remains a new visit. The kit uses that same spec deadline: a returning
|
|
4449
|
+
guest is placed at the house arrival with the same participant and user identity,
|
|
4450
|
+
while the owner's pose is restored. No arrival hook is repeated and no guest
|
|
4451
|
+
ownership, deed or owner tools are granted. Stored cold guest poses are not
|
|
4452
|
+
restored over the arrival. New host support is required; source landing alone
|
|
4453
|
+
does not activate this key.
|
|
4454
|
+
|
|
4455
|
+
|
|
4456
|
+
### Optional chat report and block scene marker
|
|
4457
|
+
|
|
4458
|
+
A scene actor named `hub-chat-moderation` with `HubChatModeration: { v: 1 }`
|
|
4459
|
+
adds **Report & block** beside Report on a received chat line. There is no
|
|
4460
|
+
manifest key. Without the exact marker, existing report-only controls remain.
|
|
4461
|
+
The stored message identifies the sender; the deck never chooses a block target
|
|
4462
|
+
on the host request. A confirmed block clears that sender's visible chat, and
|
|
4463
|
+
Ghost filters later sends and reads in both directions (read standing may be
|
|
4464
|
+
cached for four seconds). A host without block confirmation reports no success
|
|
4465
|
+
for the block. This changes no anonymous House guestbook stamps.
|
|
4466
|
+
|
|
4467
|
+
### v1.119 — bounded orbit shot fit
|
|
4468
|
+
|
|
4469
|
+
`hub.shot` optionally accepts `fit: { min: {x,y,z}, max: {x,y,z}, minDistance }`.
|
|
4470
|
+
The bounds are a world-space box. Coordinates must be finite, within ±10000 m,
|
|
4471
|
+
ordered on each axis, and span at most 1000 m per axis; minDistance is finite,
|
|
4472
|
+
positive and at most 1000 m. Invalid fit metadata invalidates the shot, like an
|
|
4473
|
+
invalid pose. Omit fit to retain the authored distance exactly.
|
|
4474
|
+
|
|
4475
|
+
The client chooses the closest distance at least minDistance that fits the box
|
|
4476
|
+
inside the central 90% of its perspective canvas, using the actual aspect and
|
|
4477
|
+
lens, while preserving look, yaw and pitch. The authored distance is a fallback
|
|
4478
|
+
until the lens is available, or when the box cannot fit within its near/far
|
|
4479
|
+
depth range. An impossible fit is ignored rather than moving the subject beyond
|
|
4480
|
+
the far plane. The existing active-shot watcher adapts the distance
|
|
4481
|
+
to resizing without replacing the held object. Lease equality uses the original
|
|
4482
|
+
wire pose and bounds; resize never changes lease identity, arrival facing, or
|
|
4483
|
+
cleanup ownership. Expiry, reconnect, travel and explicit clears keep v1.61 rules.
|
|
4484
|
+
Old clients ignore fit and draw the authored distance.
|
|
4485
|
+
|
|
4486
|
+
|
|
4487
|
+
### Optional invite entry in Character
|
|
4488
|
+
|
|
4489
|
+
A scene with `engine.hubInviteRail: true` adds **Invite a friend** to the existing
|
|
4490
|
+
Character menu in an invite-enabled town or House when the host's
|
|
4491
|
+
`Hub.canInvite` says yes for the trusted roster account: the account it names
|
|
4492
|
+
(v1.146), or else `User.getCurrent()`, must be that player's own. A guest counts
|
|
4493
|
+
like any over-13 player. Unresolved, missing or mismatched identity keeps it hidden. Inside games the entry is hidden. The entry uses the existing
|
|
4494
|
+
five-use share flow (`Hub.invite()`), including text derived from the root deck title, native
|
|
4495
|
+
Share gesture and explicit Copy link fallback. A server refusal shows “Sharing
|
|
4496
|
+
is unavailable here.” and does not retry minting. Existing arrival, follow, Undo
|
|
4497
|
+
and reconnect behavior is unchanged.
|
|
4498
|
+
|
|
4499
|
+
This marker adds no manifest key or kit contract version. It follows the existing
|
|
4500
|
+
House/win-chip capability checks; viewer eligibility remains enforced by the
|
|
4501
|
+
trusted host and server when minting. It does not claim to read the viewer's
|
|
4502
|
+
feature gate before rendering. Without the marker the Character menu has no
|
|
4503
|
+
Invite row and makes no additional host requests.
|
|
4504
|
+
|
|
4505
|
+
The Character sheet and the invite dialog fit the viewport with or without the
|
|
4506
|
+
marker: the sheet sits fixed over the right-side lane, capped to the height
|
|
4507
|
+
over its button. A landscape view where the whole sheet would not fit there
|
|
4508
|
+
(any view under 300 px tall, or one where it would have to scroll, such as
|
|
4509
|
+
844x390) gets one strip of whole tiles with its own Close instead. Open, the sheet covers
|
|
4510
|
+
the rail and House decoration controls wait. The invite dialog wraps its words
|
|
4511
|
+
and its link and scrolls inside itself, wherever it is opened from.
|
|
4512
|
+
|
|
4513
|
+
|
|
4514
|
+
### v1.120 — opt-in play entry in publish checks
|
|
4515
|
+
|
|
4516
|
+
A deck may set `hub.playOnlyEntry: true` in `castle.json` and load
|
|
4517
|
+
`/imports/castle.hub-game/play.jsx` as its single module script in `index.html`.
|
|
4518
|
+
The equivalent `./imports/` and `imports/` relative paths are also accepted.
|
|
4519
|
+
This existing entry leaves the editor code out of saved play bundles; a local
|
|
4520
|
+
development editor still loads the kit editor. It requires the explicit manifest
|
|
4521
|
+
flag at runtime and at publish time. The flag is a deck-level boolean, not a
|
|
4522
|
+
place setting.
|
|
4523
|
+
|
|
4524
|
+
The default entry remains `main.jsx`, which is accepted with or without the flag.
|
|
4525
|
+
With the flag absent or false, publish checks and the default entry behave as
|
|
4526
|
+
before. Opting in permits only the kit's `play.jsx` alternative: all other Tier 0
|
|
4527
|
+
restrictions still apply, including no extra scripts, inline code, event handlers,
|
|
4528
|
+
iframes or module preloads. This addition does not switch existing decks to the
|
|
4529
|
+
play entry or change their saved bundles.
|
|
4530
|
+
|
|
4531
|
+
### v1.121 — bounded look baking on Weakest
|
|
4532
|
+
|
|
4533
|
+
`hub.weakestLookBake: true` is an optional client-only boolean. It is off
|
|
4534
|
+
by default and takes effect only alongside `hub.weakestTier: true` while
|
|
4535
|
+
the Weakest profile is active in a valid authored district. Absent or false
|
|
4536
|
+
retains the existing Weakest picture and identical server manifest/wire state;
|
|
4537
|
+
ordinary Low and High retain synchronous model baking.
|
|
4538
|
+
|
|
4539
|
+
The opted-in picture builds the correct authored body and colour immediately,
|
|
4540
|
+
then finishes its authored AO/outline through the existing bake queue. Local
|
|
4541
|
+
character tasks, including shared accessories, come first; other tasks follow
|
|
4542
|
+
distance from the player. A task already under way finishes first. Work gets
|
|
4543
|
+
a bounded 24 ms per frame after the first draw, rising to 32 ms after 15 s of
|
|
4544
|
+
placement; an atomic engine step can exceed that budget. No task is discarded
|
|
4545
|
+
to meet a deadline. Tier/scene changes restore the previous queue policy.
|
|
4546
|
+
|
|
4547
|
+
Native acceptance requires every visible character complete within 30 s of
|
|
4548
|
+
placement, the whole scene within 60 s, and at least 25% startup gain against
|
|
4549
|
+
synchronous baking. The existing Weakest path is measured separately.
|
|
4550
|
+
Until those phone gates pass, this option remains dormant.
|
|
4551
|
+
|
|
4552
|
+
|
|
4553
|
+
### v1.122 — bounded play cards
|
|
4554
|
+
|
|
4555
|
+
Optional deck key `hub.playCards: true` applies the §6 friend/party/nearby
|
|
4556
|
+
stranger policy to Go cards from canned play phrases. It adds no wire fields
|
|
4557
|
+
and changes no server delivery, bubbles or feed. Decks without the key keep
|
|
4558
|
+
the existing card behavior.
|
|
4559
|
+
|
|
4560
|
+
|
|
4561
|
+
### v1.126 — cover until the first rendered frame
|
|
4562
|
+
|
|
4563
|
+
Optional deck key `hub.loadingCover: true` draws the deck title and a white
|
|
4564
|
+
spinner on solid black as the hub entry starts. The cover remains above the
|
|
4565
|
+
world until the connected player is placed and the first completed render
|
|
4566
|
+
through the world's output pass; no
|
|
4567
|
+
HUD, chips, pointer or game offer is visible beneath it. The same cover returns
|
|
4568
|
+
when the page backgrounds or its connection drops, and clears after a completed
|
|
4569
|
+
render with the current connection connected and the player placed. Failed
|
|
4570
|
+
renders keep loading chrome suppressed and expose the engine’s existing
|
|
4571
|
+
error/retry controls; restarting restores the cover. WebGL context
|
|
4572
|
+
loss or a no-op draw cannot clear it. Intentional session exits and terminal
|
|
4573
|
+
join failures leave existing recovery controls accessible. Both the ordinary and play-only entries support it;
|
|
4574
|
+
the development editor does not draw it.
|
|
4575
|
+
|
|
4576
|
+
This is a deck-level, client-only boolean, with no new wire fields. Absent or
|
|
4577
|
+
false preserves existing drawing and connection behavior. Older kits retain
|
|
4578
|
+
their existing loading behavior.
|
|
4579
|
+
|
|
4580
|
+
### v1.123 — safe edges and host-reserved corners
|
|
4581
|
+
|
|
4582
|
+
Optional client-only `hub.safeInsets: true` applies the three §9 layout rules
|
|
4583
|
+
through a shared measured pass: safe edges, both host corners, and complete
|
|
4584
|
+
chrome with wrapping or scrolling where necessary. Its debug layout snapshot
|
|
4585
|
+
is page-readable and adds no server state or wire field. Absent/false retains
|
|
4586
|
+
the previous client behavior. The host still owns and positions its controls.
|
|
4587
|
+
|
|
4588
|
+
### v1.127 — opt-in Act and proximity prompts
|
|
4589
|
+
|
|
4590
|
+
The deck-only boolean `hub.act: true` enables shared Act and Jump controls in
|
|
4591
|
+
all its places, using the common v1.123 safe layout registry even without a
|
|
4592
|
+
separate safeInsets flag. Act/Jump share one rail row; debug snapshots report
|
|
4593
|
+
their leaf button boxes, not their wrapper. Absent or false preserves existing controls, state and wire
|
|
4594
|
+
bytes. Named places cannot set it independently. Seats and grabbing are enabled
|
|
4595
|
+
in opted-in places even without the older idle/grab keys; existing emotes,
|
|
4596
|
+
sounds and grab settings are retained.
|
|
4597
|
+
|
|
4598
|
+
Within reach, a prompt floats by each usable actor. The nearest is lit, others
|
|
4599
|
+
are dim, and all can be pressed. Act uses the nearest; E or Space does the same
|
|
4600
|
+
on desktop. Key hints show only after keyboard game/navigation input; pointer
|
|
4601
|
+
input clears them, and touch pills show the verb alone. A fine pointer or text
|
|
4602
|
+
entry does not enable key hints. With no prompt, Space jumps. Jump sits left of Act on phones and
|
|
4603
|
+
remains available on desktop. Controls respect safe insets, both native 64×56
|
|
4604
|
+
reserved corners, other chrome and the viewport. Opening a panel, travel,
|
|
4605
|
+
place change, losing focus or disconnect cancels a pending press.
|
|
4606
|
+
|
|
4607
|
+
An actor may declare `HubAct: { verb, reach, hold, id }`: verb is 1–16 Unicode
|
|
4608
|
+
characters, nonblank, without control/direction characters; reach is 0.8–4
|
|
4609
|
+
metres; hold is boolean; id is a unique identifier of 1–64 ASCII letters,
|
|
4610
|
+
numbers, underscores or hyphens, starting with a letter or number. Duplicate
|
|
4611
|
+
interaction ids fail publishing. A spawned copy uses its runtime actor id as
|
|
4612
|
+
its interaction id, letting the message hook identify the chosen instance; the
|
|
4613
|
+
template keeps its authored id. Defaults: HubSeat is Sit at 1.6 m from its
|
|
4614
|
+
footprint (Stand while seated); HubNpc is Talk to its name at its talk range;
|
|
4615
|
+
loose dynamic grabbables are Grab at 1.2 m (Throw while held). HubPad has no
|
|
4616
|
+
interaction default and keeps its stand-on behavior. Explicit HubAct replaces
|
|
4617
|
+
the default. Anything spending tokens or progress must declare `hold: true`;
|
|
4618
|
+
walking across it never dispatches its Act.
|
|
4619
|
+
|
|
4620
|
+
Server → player: `{ k: 'hub-prompts', items: [{ id, verb, hold }] }`, only when
|
|
4621
|
+
the reachable set changes, plus one replay on a fresh hello. Ranking is local,
|
|
4622
|
+
so moving between two items already in reach sends no new prompt bytes.
|
|
4623
|
+
Player → server: `{ k: 'hub-act', id, n }`, once per press. `n` is a positive
|
|
4624
|
+
safe-integer press sequence, increasing for that client; page instances seed
|
|
4625
|
+
it from wall-clock time. Held presses first send
|
|
4626
|
+
`{ k: 'hub-act-hold', id, n, down: true }`; early release/cancel sends the same
|
|
4627
|
+
with `down: false`. The client holds for 500 ms. The server accepts the final
|
|
4628
|
+
after 500 ms minus a 150 ms latency allowance (350 ms of simulation time),
|
|
4629
|
+
within 2 seconds, with a matching unconsumed start and the same `n` press
|
|
4630
|
+
version. Reach is checked at both start and final. Prompt
|
|
4631
|
+
changes, leaving reach, disconnect and fresh hello invalidate the hold.
|
|
4632
|
+
Repeated starts cannot extend or reuse a sequence. Requests are limited to six
|
|
4633
|
+
per second, burst eight, malformed requests included.
|
|
4634
|
+
|
|
4635
|
+
Every press must still name a delivered current prompt, from an arrived player
|
|
4636
|
+
who is connected, in reach, outside travel/progress restore, and not held by
|
|
4637
|
+
the game. Shared and per-viewer hidden actors are refused. The server consumes
|
|
4638
|
+
before dispatching: defaults use existing sit, grab and NPC paths; a custom
|
|
4639
|
+
interaction calls the existing `message(hub, player, { k: 'hub-act', id, n })`
|
|
4640
|
+
hook. No player-authored text is carried. Legacy physical Sit, Grab and NPC
|
|
4641
|
+
Open requests cannot bypass Act in an opted-in deck; Stand, held-object lease
|
|
4642
|
+
renewals and virtual companion conversations retain their existing paths.
|
|
4643
|
+
|
|
4644
|
+
Tests: `scripts/test-act.mjs`, `scripts/test-act-client.mjs`.
|
|
4645
|
+
|
|
4646
|
+
### v1.133 door analytics
|
|
4647
|
+
|
|
4648
|
+
The kit emits numeric door round, progress and client-error categories through the
|
|
4649
|
+
existing server analytics channel. Ghost attributes them to the committed player
|
|
4650
|
+
trip; no client-supplied door identity is trusted. See [analytics](analytics.md#door-analytics-v1133)
|
|
4651
|
+
for kinds 28–31, automatic lifecycle boundaries, custom-loop calls and limits.
|
|
4652
|
+
|
|
4653
|
+
### v1.134 first-visit variants
|
|
4654
|
+
|
|
4655
|
+
Root-only `hub.firstVisit: { live: ['home', 'door'] }` opts the town into sticky
|
|
4656
|
+
first-visit assignment. `live` contains one to three unique names from `home`,
|
|
4657
|
+
`door`, `npc`; an absent key leaves the existing flow and arrival emission in
|
|
4658
|
+
place. The validated config is available only on the server as `hub.firstVisit`;
|
|
4659
|
+
it is absent from the public place manifest.
|
|
4660
|
+
|
|
4661
|
+
The town hashes `userId + 'firstVisit-1'` with unsigned FNV-1a and saves the
|
|
4662
|
+
selected name alongside its existing first-visit progress. Existing records
|
|
4663
|
+
without an assignment retain the home flow. A saved assignment and completed
|
|
4664
|
+
intro survive reconnects and changes to `live`. Launch enables home and door;
|
|
4665
|
+
npc stays available for preview QA only until enabled by a later config save.
|
|
4666
|
+
|
|
4667
|
+
Home keeps the house, like, play, stamp, done flow. Door first points to the
|
|
4668
|
+
featured available game door (otherwise the first available game door); returning
|
|
4669
|
+
from that trip resumes at home, including when the result arrives late. NPC
|
|
4670
|
+
summons the greeter, opens one private welcome with the choices “Show me around”
|
|
4671
|
+
and “I'll look myself”, and attaches Chirp from that talk. The first choice
|
|
4672
|
+
starts home; the second completes onboarding without a reward.
|
|
4673
|
+
|
|
4674
|
+
Opted-in server contexts gain `hub.firstVisitArrived(playerId, flags)`: resolve
|
|
4675
|
+
the pending kind-1 arrival once the storage read answers, with flags 1 home,
|
|
4676
|
+
2 door, 3 npc or 0 legacy/unassigned. It emits at most once per arrival;
|
|
4677
|
+
short reconnects retain kind 10. A departure before resolution emits flags 0.
|
|
4678
|
+
Every actual home/like/play/stamp/done kind-9 stage carries the same flags;
|
|
4679
|
+
intro-only moments do not claim that home was reached. No new event kind.
|
|
4680
|
+
|
|
4681
|
+
NPC handles gain `npc.open(playerId)` only with this root opt-in. It uses the
|
|
4682
|
+
existing private conversation path and returns whether it opened a conversation;
|
|
4683
|
+
an absent/unarrived player, an out-of-range player, an occupied slot, or a talk
|
|
4684
|
+
already open returns false. The town opens it only once the greeter is beside
|
|
4685
|
+
the newcomer. Existing chat permission, account, range and capacity checks apply.
|
|
4686
|
+
|
|
4687
|
+
### v1.136 private menu text rows
|
|
4688
|
+
|
|
4689
|
+
Optional row presentation, three text columns, individual read-only rows and a
|
|
4690
|
+
pinned footer extend the existing private place menu. The default tile menu is
|
|
4691
|
+
unchanged. See the place-menu contract above for limits and pick validation.
|
|
4692
|
+
|
|
4693
|
+
Tests: `scripts/test-menu.mjs`, `scripts/test-menu-client.mjs`.
|
|
4694
|
+
|
|
4695
|
+
### v1.137 hub.quality
|
|
4696
|
+
|
|
4697
|
+
**Opt-in.** castle.json "hub": { "quality": { ... } }. Absent: byte-identical to today. Requires
|
|
4698
|
+
"tiers": true (refused with a manifest error otherwise).
|
|
4699
|
+
|
|
4700
|
+
```json
|
|
4701
|
+
"hub": {
|
|
4702
|
+
"tiers": true,
|
|
4703
|
+
"quality": {
|
|
4704
|
+
"low": { "decor": "skip", "players": 8, "labels": 8, "spawned": 8, "farMindsHz": 4, "physicsHz": 15 }
|
|
4705
|
+
}
|
|
4706
|
+
}
|
|
4707
|
+
```
|
|
4708
|
+
|
|
4709
|
+
- quality.low.decor: "skip" | "hide". "hide" is today's Low. "skip": on a client that starts on
|
|
4710
|
+
Low, actors in the decor class are not built at all. Decor class = no collider, no behaviour other
|
|
4711
|
+
than Transform/Shape/Model, no "tier": "keep" mark, not a pad, door, NPC, spawn template or
|
|
4712
|
+
scripted target. The manifest check refuses a scene where a server or deck script names a decor
|
|
4713
|
+
actor by id (it may not exist on a Low client).
|
|
4714
|
+
- quality.low.players (1-30): Low clients draw at most this many bystanders, nearest first, with
|
|
4715
|
+
2 m hysteresis. Always drawn and not counted: the player's own party, anyone on the same pad, and
|
|
4716
|
+
anyone who chatted or emoted at this player in the last 10 s. Not-drawn bystanders keep their
|
|
4717
|
+
state and appear when they come nearer. The server still sends every player (no wire change in
|
|
4718
|
+
v1.137); a server-side cap is a later version.
|
|
4719
|
+
- quality.low.labels (0-30): nearest world labels shown on Low. Never capped: pointers (quest, door,
|
|
4720
|
+
home arrows) and the player's own party. The labels kit's three-nearest-door rule still wins inside
|
|
4721
|
+
its 12/14 m; door labels admitted by that rule are exempt and consume no quality slots.
|
|
4722
|
+
- quality.low.spawned (0-64): caps only hub.spawn templates that declare "decor": true; a Low client
|
|
4723
|
+
builds those nearest first and the rest when they come within range. Templates without it are
|
|
4724
|
+
gameplay (gems, tiles, pickups) and a Low client builds every one. A cap on a deck with no decor
|
|
4725
|
+
templates is a no-op and logs a warning, not an error. The server and other clients are unaffected.
|
|
4726
|
+
- quality.low.farMindsHz (1-60): per-frame NPC talk and prompt work for far NPCs runs at this rate on
|
|
4727
|
+
Low. Far = past lowActorDistance and not within talk range of this player and not in a
|
|
4728
|
+
conversation with this player, so a line caused by the player's own action shows at once.
|
|
4729
|
+
- quality.low.physicsHz (10-60, absent = every frame): **reserved, no effect yet**. The future behavior is: on Low, remote players' bodies and props step
|
|
4730
|
+
at this rate with interpolated rendering. The player's own body and anything the player is touching,
|
|
4731
|
+
holding or riding step every frame. Client-only; the server stays authoritative. Ships after the
|
|
4732
|
+
engine floor, and only if physics is still over 3 ms per frame on the TECNO.
|
|
4733
|
+
- **Tier is picked before the scene build** when quality is present: manual setting, then stored
|
|
4734
|
+
history, then GPU/deviceMemory hint, as today. The first-frame judge still runs and can drop to Low.
|
|
4735
|
+
- Mid-visit changes: Low to High builds skipped decor in budgeted slices (at most 8 ms per frame);
|
|
4736
|
+
High to Low hides (no teardown). A device never rises on its own, as today.
|
|
4737
|
+
- **What never differs by tier** (unchanged from hub.tiers): pads, doors, colliders, positions,
|
|
4738
|
+
physics, server state, what other players see you do. Everything in hub.quality is client-only.
|
|
4739
|
+
- Telemetry: quality telemetry is deferred. The client exposes "skip" | "hide" at
|
|
4740
|
+
`__hub.tier.quality`; the fps report (v1.132) keeps its existing payload.
|
|
4741
|
+
- Gate (seat, added to qa-standards): a Low client in a door round sees every gameplay spawn and
|
|
4742
|
+
every pad, door and collider at the same position as a High client, proved by one Gem Rush round on
|
|
4743
|
+
the TECNO on Low against a Metal High partner.
|
|
4744
|
+
- Validation errors name the field and the allowed range; unknown keys are refused.
|
|
4745
|
+
|
|
4746
|
+
Omitted Low fields default to decor `"skip"`, players 8, labels 8, spawned 8,
|
|
4747
|
+
farMindsHz 4. There is no physicsHz default stored or applied. Fields are integers
|
|
4748
|
+
except decor. A scene actor declares a decorative spawn template with
|
|
4749
|
+
`"decor": true` beside `id`; it must have only Transform/Shape/Model and no
|
|
4750
|
+
collider. Template actors themselves are retained. Gameplay templates are
|
|
4751
|
+
unmarked and always built. Opted-in template snapshots carry `decor: true`
|
|
4752
|
+
only for those declared templates; no player wire cap is added.
|
|
4753
|
+
|
|
4754
|
+
The kit entry adapts `SceneRuntime.load` before the constructor builds actors;
|
|
4755
|
+
it resolves blueprint components without altering the authored files. The
|
|
4756
|
+
ordinary Graphics menu and judge reuse that same tier controller. Skipped decor
|
|
4757
|
+
is restored through the engine's actor/node path. Each cooperative slice stops
|
|
4758
|
+
admitting actors within an 8 ms budget (including synchronous node sync). A
|
|
4759
|
+
single synchronous engine/model build cannot be interrupted and can overrun
|
|
4760
|
+
that budget; a strict wall-clock bound needs an incremental engine build API.
|
|
4761
|
+
|
|
4762
|
+
The publish check refuses literal decor ids in known actor APIs in deck/server
|
|
4763
|
+
scripts (including hub.spawn); mark a plain gameplay template `"tier": "keep"`
|
|
4764
|
+
or declare a decorative template `"decor": true`. The client never bundles
|
|
4765
|
+
server script source to discover targets. Computed ids, aliased
|
|
4766
|
+
APIs and arbitrary helpers cannot be proved by the kit's current source checks;
|
|
4767
|
+
mark such targets `"tier": "keep"` (or choose decor `"hide"`).
|
|
4768
|
+
|
|
4769
|
+
Quality telemetry is deferred: Ghost owns the FPS variants map and overwrites
|
|
4770
|
+
caller flags with owner/guest attribution. No caller field preserves quality
|
|
4771
|
+
without changing the existing measurement meanings. The v1.132 FPS message and
|
|
4772
|
+
kind-26 record remain unchanged. Opted-in clients expose `__hub.tier.quality`
|
|
4773
|
+
(`"skip"` or `"hide"`) for local inspection and a later telemetry version.
|
|
4774
|
+
|
|
4775
|
+
Tests: `scripts/test-quality.mjs`, plus the existing tiers, manifest, avatars,
|
|
4776
|
+
labels, NPCs, actors and FPS telemetry tests.
|
|
4777
|
+
|
|
4778
|
+
### v1.138 load-abandoned telemetry
|
|
4779
|
+
|
|
4780
|
+
`hub.loadTelemetry: true` (main place, beside `analytics` and `analyticsV111`) adds
|
|
4781
|
+
kind 27 `load_abandoned`: a town connection the server saw that never arrived.
|
|
4782
|
+
It is a server-platform path like FPS summaries; authored `hub.track` cannot send it.
|
|
4783
|
+
The only new wire is the opted-in `hubPlace.loadTelemetry` field and one numeric
|
|
4784
|
+
`hub-load` message per transport. Absent preserves existing bytes. See
|
|
4785
|
+
[analytics](analytics.md#load-abandoned-v1138). Tests: `scripts/test-load-abandon.mjs`.
|
|
4786
|
+
|
|
4787
|
+
### v1.143 High-only scenery
|
|
4788
|
+
|
|
4789
|
+
Optional root `hub.highOnly: true` requires `hub.tiers: true`. Mark extra
|
|
4790
|
+
scenery actors `tier: "high"` beside `id`, with only Transform/Shape/Model
|
|
4791
|
+
components. On Low (including Middle and Weakest), the client holds these
|
|
4792
|
+
actors out of the loaded scene before model construction. Switching Graphics
|
|
4793
|
+
to High restores them through the cooperative 8 ms decor queue; switching
|
|
4794
|
+
back to Low hides their nodes with the ordinary decor rule. They are never
|
|
4795
|
+
occluders or protected visibility-cell actors. No gameplay belongs on them.
|
|
4796
|
+
|
|
4797
|
+
This flag works independently of `hub.quality`; it enables none of quality's
|
|
4798
|
+
player, label, spawn or NPC caps. With both keys absent the runtime load
|
|
4799
|
+
method is untouched. With only quality present its existing behavior remains.
|
|
4800
|
+
The editor and mounted door content are unaffected. The key is client-only,
|
|
4801
|
+
validated as a boolean and omitted from the server manifest and wire.
|
|
4802
|
+
|
|
4803
|
+
Tests: `scripts/test-high-only.mjs`.
|