castle-web-cli 0.4.232 → 0.4.234
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-failures.d.ts +8 -0
- package/dist/agent-failures.js +19 -2
- package/dist/agent-prompts.d.ts +1 -1
- package/dist/agent-prompts.js +10 -3
- package/dist/agent.d.ts +64 -3
- package/dist/agent.js +170 -81
- package/dist/api.d.ts +11 -0
- package/dist/api.js +43 -0
- package/dist/bundle.d.ts +64 -0
- package/dist/bundle.js +558 -2
- package/dist/castle-host/host.d.ts +18 -2
- package/dist/castle-host/host.js +844 -39
- package/dist/castleJson.d.ts +23 -2
- package/dist/castleJson.js +46 -2
- package/dist/check.d.ts +3 -1
- package/dist/check.js +20 -3
- package/dist/chunkLoader.d.ts +3 -0
- package/dist/chunkLoader.js +111 -0
- package/dist/devParty.d.ts +26 -0
- package/dist/devParty.js +231 -0
- package/dist/devSaveStorage.js +4 -0
- package/dist/devSessionStorage.js +50 -2
- package/dist/devSocial.d.ts +24 -0
- package/dist/devSocial.js +70 -0
- package/dist/ide.d.ts +2 -0
- package/dist/ide.js +119 -15
- package/dist/importPinMismatch.d.ts +22 -0
- package/dist/importPinMismatch.js +77 -0
- package/dist/importRegression.js +3 -15
- package/dist/imports.d.ts +10 -3
- package/dist/imports.js +88 -20
- package/dist/index.js +11 -4
- package/dist/init.js +1 -1
- package/dist/platformDoc.js +22 -0
- package/dist/routerFences.d.ts +5 -0
- package/dist/routerFences.js +12 -2
- package/dist/save-deck.d.ts +25 -1
- package/dist/save-deck.js +178 -9
- package/dist/serve.js +32 -11
- package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
- package/dist/shell/assets/index-MVLfNYd9.css +1 -0
- package/dist/shell/index.html +2 -2
- package/dist/taskSteer.d.ts +13 -0
- package/dist/taskSteer.js +22 -2
- package/dist/vitePlugins.d.ts +2 -1
- package/dist/vitePlugins.js +13 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/README.md +339 -5
- package/kits/base/sdk/avatar.d.ts +6 -2
- package/kits/base/sdk/avatar.js +12 -4
- package/kits/base/sdk/castle.d.ts +7 -3
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +176 -1
- package/kits/base/sdk/commands.js +3 -0
- package/kits/base/sdk/display.d.ts +3 -0
- package/kits/base/sdk/display.js +9 -3
- package/kits/base/sdk/hub.d.ts +37 -6
- package/kits/base/sdk/hub.js +63 -4
- package/kits/base/sdk/multiplayer.d.ts +7 -1
- package/kits/base/sdk/multiplayer.js +148 -32
- package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
- package/kits/base/sdk/party.d.ts +23 -0
- package/kits/base/sdk/party.js +91 -0
- package/kits/base/sdk/reconnectBudget.d.ts +23 -0
- package/kits/base/sdk/reconnectBudget.js +96 -0
- package/kits/base/sdk/save.d.ts +38 -1
- package/kits/base/sdk/save.js +81 -7
- package/kits/base/sdk/server/hub.d.ts +117 -0
- package/kits/base/sdk/server/hub.js +119 -2
- package/kits/base/sdk/server/platformHandle.d.ts +43 -1
- package/kits/base/sdk/server/storage.d.ts +17 -0
- package/kits/base/sdk/server/storage.js +65 -3
- package/kits/base/sdk/server/wrapper.d.ts +43 -6
- package/kits/base/sdk/server/wrapper.js +93 -9
- package/kits/base/sdk/social.d.ts +9 -0
- package/kits/base/sdk/social.js +5 -0
- package/kits/hub-game/CLAUDE.md +451 -13
- package/kits/hub-game/README.md +63 -0
- package/kits/hub-game/blueprints/avatar-10.scene +28 -0
- package/kits/hub-game/blueprints/avatar-11.scene +28 -0
- package/kits/hub-game/blueprints/avatar-12.scene +28 -0
- package/kits/hub-game/blueprints/avatar-13.scene +28 -0
- package/kits/hub-game/blueprints/avatar-14.scene +28 -0
- package/kits/hub-game/blueprints/avatar-15.scene +28 -0
- package/kits/hub-game/blueprints/avatar-4.scene +28 -0
- package/kits/hub-game/blueprints/avatar-5.scene +28 -0
- package/kits/hub-game/blueprints/avatar-6.scene +28 -0
- package/kits/hub-game/blueprints/avatar-7.scene +28 -0
- package/kits/hub-game/blueprints/avatar-8.scene +28 -0
- package/kits/hub-game/blueprints/avatar-9.scene +28 -0
- package/kits/hub-game/castle.json +5 -5
- package/kits/hub-game/code/client/act.js +312 -0
- package/kits/hub-game/code/client/actionLayout.js +147 -0
- package/kits/hub-game/code/client/actionOverflow.js +556 -0
- package/kits/hub-game/code/client/actorBudget.js +47 -0
- package/kits/hub-game/code/client/arrivalCamera.js +50 -0
- package/kits/hub-game/code/client/askSlot.js +117 -0
- package/kits/hub-game/code/client/attention.js +11 -2
- package/kits/hub-game/code/client/avatar.js +311 -35
- package/kits/hub-game/code/client/avatarCap.js +228 -0
- package/kits/hub-game/code/client/avatarColors.js +70 -0
- package/kits/hub-game/code/client/avatarFaces.js +21 -0
- package/kits/hub-game/code/client/avatarShare.js +253 -0
- package/kits/hub-game/code/client/backVisibility.js +13 -0
- package/kits/hub-game/code/client/ballot.js +472 -0
- package/kits/hub-game/code/client/build.js +38 -0
- package/kits/hub-game/code/client/chat.js +41 -5
- package/kits/hub-game/code/client/chatModeration.js +5 -0
- package/kits/hub-game/code/client/chrome.js +2144 -160
- package/kits/hub-game/code/client/companion.js +716 -0
- package/kits/hub-game/code/client/companionDress.js +99 -0
- package/kits/hub-game/code/client/crowdNames.js +241 -0
- package/kits/hub-game/code/client/decor.js +515 -0
- package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
- package/kits/hub-game/code/client/doorErrors.js +39 -0
- package/kits/hub-game/code/client/earned.js +131 -0
- package/kits/hub-game/code/client/emoteBubble.js +75 -0
- package/kits/hub-game/code/client/fall.js +18 -0
- package/kits/hub-game/code/client/farAvatars.js +233 -0
- package/kits/hub-game/code/client/firstJoin.js +9 -2
- package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
- package/kits/hub-game/code/client/frameBatch.js +5 -0
- package/kits/hub-game/code/client/grab.js +368 -29
- package/kits/hub-game/code/client/hookLayer.js +385 -20
- package/kits/hub-game/code/client/hudCopy.js +51 -0
- package/kits/hub-game/code/client/hudRate.js +20 -0
- package/kits/hub-game/code/client/idle.js +177 -24
- package/kits/hub-game/code/client/interestCap.js +81 -0
- package/kits/hub-game/code/client/invites.js +231 -0
- package/kits/hub-game/code/client/joinError.js +9 -0
- package/kits/hub-game/code/client/keys.js +36 -0
- package/kits/hub-game/code/client/labelsNear.js +234 -0
- package/kits/hub-game/code/client/landscapeLayout.js +17 -0
- package/kits/hub-game/code/client/layoutCache.js +264 -0
- package/kits/hub-game/code/client/loadTelemetry.js +20 -0
- package/kits/hub-game/code/client/loadingCover.js +148 -0
- package/kits/hub-game/code/client/loadingEntry.js +8 -0
- package/kits/hub-game/code/client/menuIcons.js +34 -0
- package/kits/hub-game/code/client/menuRows.js +43 -0
- package/kits/hub-game/code/client/modelReady.js +7 -0
- package/kits/hub-game/code/client/pack.js +6 -2
- package/kits/hub-game/code/client/packFormat.js +3 -3
- package/kits/hub-game/code/client/padCueArrival.js +23 -0
- package/kits/hub-game/code/client/padCues.js +112 -0
- package/kits/hub-game/code/client/padOccupancy.js +88 -0
- package/kits/hub-game/code/client/padReadability.js +26 -0
- package/kits/hub-game/code/client/padRings.js +69 -0
- package/kits/hub-game/code/client/pushVisit.js +14 -0
- package/kits/hub-game/code/client/quality.js +205 -0
- package/kits/hub-game/code/client/qualityEntry.js +55 -0
- package/kits/hub-game/code/client/rehello.js +167 -0
- package/kits/hub-game/code/client/safeLayout.js +338 -0
- package/kits/hub-game/code/client/safeStyle.js +42 -0
- package/kits/hub-game/code/client/say.js +12 -3
- package/kits/hub-game/code/client/shot.js +146 -0
- package/kits/hub-game/code/client/shotFit.js +56 -0
- package/kits/hub-game/code/client/signIn.js +28 -0
- package/kits/hub-game/code/client/sound.js +63 -8
- package/kits/hub-game/code/client/soundscape.js +1151 -0
- package/kits/hub-game/code/client/soundscapeActions.js +99 -0
- package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
- package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
- package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
- package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
- package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
- package/kits/hub-game/code/client/soundscapeCues.js +362 -0
- package/kits/hub-game/code/client/soundscapeMap.js +181 -0
- package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
- package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
- package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
- package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
- package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
- package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
- package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
- package/kits/hub-game/code/client/soundscapeUi.js +211 -0
- package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
- package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
- package/kits/hub-game/code/client/spin.js +101 -0
- package/kits/hub-game/code/client/state.js +162 -1
- package/kits/hub-game/code/client/stuck.js +259 -0
- package/kits/hub-game/code/client/talk.js +714 -59
- package/kits/hub-game/code/client/tiers.js +543 -52
- package/kits/hub-game/code/client/toastBand.js +37 -0
- package/kits/hub-game/code/client/together.js +39 -2
- package/kits/hub-game/code/client/visibility.js +43 -0
- package/kits/hub-game/code/client/weakestLookBake.js +92 -0
- package/kits/hub-game/code/client/weakestTier.js +295 -0
- package/kits/hub-game/code/client/wear.js +461 -170
- package/kits/hub-game/code/client/worldLabels.js +241 -0
- package/kits/hub-game/code/client/yours.js +200 -0
- package/kits/hub-game/code/companionSpec.js +45 -0
- package/kits/hub-game/code/npcDisplayText.js +55 -0
- package/kits/hub-game/code/privateText.js +7 -0
- package/kits/hub-game/code/server/act.js +124 -0
- package/kits/hub-game/code/server/actions.js +138 -0
- package/kits/hub-game/code/server/actors.js +11 -2
- package/kits/hub-game/code/server/analytics.js +83 -0
- package/kits/hub-game/code/server/anonymousEntry.js +49 -0
- package/kits/hub-game/code/server/arrivalPose.js +36 -0
- package/kits/hub-game/code/server/ask.js +155 -0
- package/kits/hub-game/code/server/ballot.js +539 -0
- package/kits/hub-game/code/server/cells.js +100 -0
- package/kits/hub-game/code/server/companion.js +107 -0
- package/kits/hub-game/code/server/cues.js +70 -0
- package/kits/hub-game/code/server/decor.js +269 -0
- package/kits/hub-game/code/server/doorAnalytics.js +52 -0
- package/kits/hub-game/code/server/earned.js +478 -0
- package/kits/hub-game/code/server/frameBatch.js +183 -0
- package/kits/hub-game/code/server/friendBests.js +166 -0
- package/kits/hub-game/code/server/friendsAmong.js +272 -0
- package/kits/hub-game/code/server/history.js +7 -0
- package/kits/hub-game/code/server/hub.js +2510 -95
- package/kits/hub-game/code/server/idle.js +60 -12
- package/kits/hub-game/code/server/index.js +28 -6
- package/kits/hub-game/code/server/invites.js +19 -0
- package/kits/hub-game/code/server/labels.js +36 -2
- package/kits/hub-game/code/server/loadAbandon.js +106 -0
- package/kits/hub-game/code/server/manifest.js +586 -7
- package/kits/hub-game/code/server/menu.js +161 -0
- package/kits/hub-game/code/server/npcs.js +1025 -113
- package/kits/hub-game/code/server/observe.js +408 -0
- package/kits/hub-game/code/server/padOccupancy.js +85 -0
- package/kits/hub-game/code/server/party.js +2 -2
- package/kits/hub-game/code/server/players.js +30 -0
- package/kits/hub-game/code/server/resumePose.js +152 -0
- package/kits/hub-game/code/server/say.js +1 -1
- package/kits/hub-game/code/server/shot.js +110 -0
- package/kits/hub-game/code/server/standing.js +123 -0
- package/kits/hub-game/code/server/storageLimit.js +187 -0
- package/kits/hub-game/code/server/vis.js +175 -0
- package/kits/hub-game/code/server/wear.js +12 -0
- package/kits/hub-game/code/server/yours.js +59 -0
- package/kits/hub-game/code/shared/act.js +35 -0
- package/kits/hub-game/code/shared/cues.js +9 -0
- package/kits/hub-game/code/shared/danceIdle.js +28 -0
- package/kits/hub-game/code/shared/decor.js +41 -0
- package/kits/hub-game/code/shared/loadStages.js +12 -0
- package/kits/hub-game/code/shared/quality.js +74 -0
- package/kits/hub-game/code/shared/say.js +2 -0
- package/kits/hub-game/code/shared/shot.js +53 -0
- package/kits/hub-game/code/shared/spin.js +57 -0
- package/kits/hub-game/code/systems/hub.js +1753 -202
- package/kits/hub-game/docs/analytics.md +279 -0
- package/kits/hub-game/docs/content-pack.md +1 -1
- package/kits/hub-game/docs/contract.md +3475 -77
- package/kits/hub-game/docs/home-pieces.md +71 -0
- package/kits/hub-game/docs/observed-progress.md +252 -0
- package/kits/hub-game/main.jsx +2 -0
- package/kits/hub-game/models/avatar-10.pxmodel +28 -0
- package/kits/hub-game/models/avatar-11.pxmodel +28 -0
- package/kits/hub-game/models/avatar-12.pxmodel +27 -0
- package/kits/hub-game/models/avatar-13.pxmodel +24 -0
- package/kits/hub-game/models/avatar-14.pxmodel +29 -0
- package/kits/hub-game/models/avatar-15.pxmodel +24 -0
- package/kits/hub-game/models/avatar-4.pxmodel +29 -0
- package/kits/hub-game/models/avatar-5.pxmodel +27 -0
- package/kits/hub-game/models/avatar-6.pxmodel +26 -0
- package/kits/hub-game/models/avatar-7.pxmodel +25 -0
- package/kits/hub-game/models/avatar-8.pxmodel +24 -0
- package/kits/hub-game/models/avatar-9.pxmodel +30 -0
- package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
- package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
- package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
- package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
- package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
- package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
- package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
- package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
- package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
- package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
- package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
- package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
- package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
- package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
- package/kits/hub-game/models/hats/cap.pxmodel +162 -0
- package/kits/hub-game/models/hats/captain.pxmodel +178 -0
- package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
- package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
- package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
- package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
- package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
- package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
- package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
- package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
- package/kits/hub-game/models/hats/straw.pxmodel +139 -0
- package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
- package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
- package/kits/hub-game/models/hats/witch.pxmodel +147 -0
- package/kits/hub-game/package-lock.json +10 -1
- package/kits/hub-game/package.json +6 -2
- package/kits/hub-game/play/player.js +142 -0
- package/kits/hub-game/play/registry.js +47 -0
- package/kits/hub-game/play.jsx +37 -0
- package/kits/hub-game/scripts/check.mjs +117 -16
- package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
- package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
- package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
- package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
- package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
- package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
- package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
- package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
- package/kits/hub-game/scripts/gen-earned.mjs +285 -0
- package/kits/hub-game/scripts/gen-hats.mjs +827 -0
- package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
- package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
- package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
- package/kits/hub-game/scripts/test-act-client.mjs +186 -0
- package/kits/hub-game/scripts/test-act.mjs +171 -0
- package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
- package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
- package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
- package/kits/hub-game/scripts/test-actions.mjs +298 -0
- package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
- package/kits/hub-game/scripts/test-actors.mjs +38 -23
- package/kits/hub-game/scripts/test-analytics.mjs +76 -0
- package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
- package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
- package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
- package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
- package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
- package/kits/hub-game/scripts/test-ask.mjs +269 -0
- package/kits/hub-game/scripts/test-attention.mjs +10 -1
- package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
- package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
- package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
- package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
- package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
- package/kits/hub-game/scripts/test-avatar.mjs +584 -7
- package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
- package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
- package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
- package/kits/hub-game/scripts/test-build.mjs +49 -0
- package/kits/hub-game/scripts/test-cells.mjs +71 -0
- package/kits/hub-game/scripts/test-chat.mjs +863 -0
- package/kits/hub-game/scripts/test-classic.mjs +2 -0
- package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
- package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
- package/kits/hub-game/scripts/test-companion.mjs +259 -0
- package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
- package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
- package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
- package/kits/hub-game/scripts/test-decor.mjs +464 -0
- package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
- package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
- package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
- package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
- package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
- package/kits/hub-game/scripts/test-earned.mjs +1224 -0
- package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
- package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
- package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
- package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
- package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
- package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
- package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
- package/kits/hub-game/scripts/test-grab.mjs +7 -0
- package/kits/hub-game/scripts/test-hats.mjs +422 -168
- package/kits/hub-game/scripts/test-high-only.mjs +170 -0
- package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
- package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
- package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
- package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
- package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
- package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
- package/kits/hub-game/scripts/test-idle.mjs +427 -1
- package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
- package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
- package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
- package/kits/hub-game/scripts/test-interest.mjs +15 -0
- package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
- package/kits/hub-game/scripts/test-invites.mjs +109 -0
- package/kits/hub-game/scripts/test-keys.mjs +46 -1
- package/kits/hub-game/scripts/test-labels.mjs +664 -0
- package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
- package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
- package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
- package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
- package/kits/hub-game/scripts/test-manifest.mjs +472 -0
- package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
- package/kits/hub-game/scripts/test-menu.mjs +319 -0
- package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
- package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
- package/kits/hub-game/scripts/test-observed.mjs +745 -0
- package/kits/hub-game/scripts/test-pack.mjs +7 -0
- package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
- package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
- package/kits/hub-game/scripts/test-picker.mjs +541 -0
- package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
- package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
- package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
- package/kits/hub-game/scripts/test-quality.mjs +385 -0
- package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
- package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
- package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
- package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
- package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
- package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
- package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
- package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
- package/kits/hub-game/scripts/test-say.mjs +1 -1
- package/kits/hub-game/scripts/test-shot.mjs +901 -0
- package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
- package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
- package/kits/hub-game/scripts/test-spin.mjs +314 -0
- package/kits/hub-game/scripts/test-standing.mjs +449 -0
- package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
- package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
- package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
- package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
- package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
- package/kits/hub-game/scripts/test-tiers.mjs +476 -2
- package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
- package/kits/hub-game/scripts/test-try-on.mjs +22 -22
- package/kits/hub-game/scripts/test-vis.mjs +770 -0
- package/kits/hub-game/scripts/test-visibility.mjs +134 -0
- package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
- package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
- package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
- package/kits/hub-game/scripts/test-yours.mjs +403 -0
- package/kits/multiplayer-3d/CLAUDE.md +50 -0
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/avatars.js +7 -0
- package/kits/multiplayer-3d/code/client/gait.js +65 -0
- package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
- package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
- package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
- package/kits/multiplayer-3d/code/options.js +5 -0
- package/kits/multiplayer-3d/code/server/ownership.js +10 -2
- package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
- package/kits/multiplayer-3d/code/server/world.js +7 -0
- package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
- package/kits/multiplayer-3d/package-lock.json +8 -1
- package/kits/multiplayer-3d/package.json +3 -1
- package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
- package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
- package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
- package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
- package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
- package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
- package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
- package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
- package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
- package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
- package/kits/physics-2d/CLAUDE.md +19 -1
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/frozenActors.js +233 -0
- package/kits/physics-2d/engine/scene.js +337 -3
- package/kits/physics-2d/engine/skyKey.js +129 -0
- package/kits/physics-2d/engine/stillClock.js +106 -0
- package/kits/physics-2d/engine/updateBudget.js +21 -0
- package/kits/physics-2d/eslint.config.js +1 -1
- package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
- package/kits/physics-2d/play/behaviors/Camera.js +40 -0
- package/kits/physics-2d/play/behaviors/Collider.js +122 -0
- package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
- package/kits/physics-2d/play/behaviors/Goal.js +46 -0
- package/kits/physics-2d/play/behaviors/Joints.js +126 -0
- package/kits/physics-2d/play/behaviors/Layout.js +71 -0
- package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
- package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
- package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
- package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
- package/kits/physics-2d/play/behaviors/Style.js +209 -0
- package/kits/physics-2d/play/behaviors/Text.js +85 -0
- package/kits/physics-2d/play/behaviors/Video.js +93 -0
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
- package/kits/physics-3d/CLAUDE.md +42 -529
- package/kits/physics-3d/behaviors/Body.jsx +3 -0
- package/kits/physics-3d/behaviors/Model.jsx +3 -0
- package/kits/physics-3d/behaviors/Player.jsx +661 -87
- package/kits/physics-3d/behaviors/Shape.jsx +3 -0
- package/kits/physics-3d/behaviors/Solid.jsx +3 -0
- package/kits/physics-3d/behaviors/Transform.jsx +3 -0
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/docs/engine-camera.md +542 -0
- package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
- package/kits/physics-3d/docs/engine-load.md +149 -0
- package/kits/physics-3d/docs/engine-look.md +114 -0
- package/kits/physics-3d/docs/engine-shadows.md +372 -0
- package/kits/physics-3d/docs/engine-skip-work.md +187 -0
- package/kits/physics-3d/docs/engine-sky.md +198 -0
- package/kits/physics-3d/docs/engine-static-actors.md +226 -0
- package/kits/physics-3d/docs/engine-view.md +37 -0
- package/kits/physics-3d/docs/pxmodel-format.md +9 -1
- package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
- package/kits/physics-3d/engine3d/actornode.js +87 -0
- package/kits/physics-3d/engine3d/animationBudget.js +23 -0
- package/kits/physics-3d/engine3d/branches.js +3 -13
- package/kits/physics-3d/engine3d/cage.js +2 -7
- package/kits/physics-3d/engine3d/cageops.js +2 -17
- package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
- package/kits/physics-3d/engine3d/editorWorld.js +6 -0
- package/kits/physics-3d/engine3d/emptynodes.js +232 -0
- package/kits/physics-3d/engine3d/framecap.js +99 -0
- package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
- package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
- package/kits/physics-3d/engine3d/gait.js +126 -0
- package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
- package/kits/physics-3d/engine3d/kithooks.js +47 -0
- package/kits/physics-3d/engine3d/look.js +514 -48
- package/kits/physics-3d/engine3d/lookbake.js +208 -0
- package/kits/physics-3d/engine3d/materialpresets.js +2 -0
- package/kits/physics-3d/engine3d/modelFiles.js +3 -17
- package/kits/physics-3d/engine3d/modelMath.js +49 -0
- package/kits/physics-3d/engine3d/modelready.js +16 -0
- package/kits/physics-3d/engine3d/motion.js +39 -10
- package/kits/physics-3d/engine3d/nearshadows.js +106 -21
- package/kits/physics-3d/engine3d/optimize.js +9 -5
- package/kits/physics-3d/engine3d/orbitinput.js +522 -10
- package/kits/physics-3d/engine3d/orbitlens.js +48 -0
- package/kits/physics-3d/engine3d/ownmodel.js +213 -0
- package/kits/physics-3d/engine3d/partgeometry.js +1 -16
- package/kits/physics-3d/engine3d/paths.js +1 -9
- package/kits/physics-3d/engine3d/playTimings.js +50 -0
- package/kits/physics-3d/engine3d/playerRun.js +372 -0
- package/kits/physics-3d/engine3d/pxmodel.js +42 -11
- package/kits/physics-3d/engine3d/rapier.js +27 -0
- package/kits/physics-3d/engine3d/scatter.js +1 -11
- package/kits/physics-3d/engine3d/shadowfade.js +890 -0
- package/kits/physics-3d/engine3d/sky.js +547 -0
- package/kits/physics-3d/engine3d/skylife.js +306 -0
- package/kits/physics-3d/engine3d/squarefirst.js +177 -0
- package/kits/physics-3d/engine3d/stillshadows.js +399 -0
- package/kits/physics-3d/engine3d/sweep.js +1 -25
- package/kits/physics-3d/engine3d/unchanged.js +11 -0
- package/kits/physics-3d/engine3d/viewrange.js +52 -0
- package/kits/physics-3d/engine3d/world3d.js +1253 -76
- package/kits/physics-3d/eslint.config.js +2 -1
- package/kits/physics-3d/main.jsx +10 -2
- package/kits/physics-3d/package-lock.json +7 -0
- package/kits/physics-3d/package.json +5 -1
- package/kits/physics-3d/play/behaviors/Body.js +31 -0
- package/kits/physics-3d/play/behaviors/Door.js +37 -0
- package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
- package/kits/physics-3d/play/behaviors/Model.js +23 -0
- package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
- package/kits/physics-3d/play/behaviors/Player.js +1204 -0
- package/kits/physics-3d/play/behaviors/Shape.js +47 -0
- package/kits/physics-3d/play/behaviors/Solid.js +16 -0
- package/kits/physics-3d/play/behaviors/Transform.js +29 -0
- package/kits/physics-3d/pnpm-lock.yaml +8 -0
- package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
- package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
- package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
- package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
- package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
- package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
- package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
- package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
- package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
- package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
- package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
- package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
- package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
- package/kits/physics-3d/scripts/test-gait.mjs +387 -0
- package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
- package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
- package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
- package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
- package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
- package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
- package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
- package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
- package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
- package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
- package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
- package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
- package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
- package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
- package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
- package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
- package/kits/physics-3d/systems/physics3d.js +419 -9
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/connection.js +33 -10
- package/kits/real-time/code/client/gameHooks.js +2 -0
- package/kits/real-time/code/client/joinOverlay.js +9 -4
- package/kits/real-time/code/server/gameHooks.js +7 -0
- package/kits/real-time/code/server/session.js +102 -22
- package/kits/real-time/package-lock.json +1 -1
- package/package.json +2 -2
- package/dist/shell/assets/index-Cf61cNfT.css +0 -1
|
@@ -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,21 +57,65 @@ 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)
|
|
69
|
+
"house": { "devOwner": "first" }, // optional (v1.67); first arrival owns a dev house (§4)
|
|
70
|
+
"actions": true, // optional (v1.74); private action chips (§9)
|
|
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)
|
|
73
|
+
"menu": true, // optional (v1.79); private place menu (§9)
|
|
74
|
+
"ask": true, // optional (v1.75); private text prompt (§9)
|
|
75
|
+
"decor": { "grid": { "origin": "floor", "w": 8, "d": 7, "cell": 1 }, "layers": ["rug", "floor"] }, // optional (v1.67); §10
|
|
61
76
|
"grab": true, // optional (v1.3); players pick up loose objects and throw them (§6)
|
|
62
77
|
"idle": { "emotes": true, "seats": true, "sounds": ["sounds/jukebox.mp3"] }, // optional (v1.6); emotes, seats, the place's sounds (§6)
|
|
63
78
|
"hud": { "clear": true }, // optional (v1.26); a shorter HUD, and labels kept out from under it (§9)
|
|
79
|
+
"ballot": { "lines": [ // optional (v1.68); the choice card and the deck's fixed lines (§6)
|
|
80
|
+
{ "id": "boat", "text": "I saw them by the boat", "about": "face" },
|
|
81
|
+
{ "id": "not-me", "text": "Not me!", "about": "self" }
|
|
82
|
+
] },
|
|
83
|
+
"interest": "cells", // optional (v1.65); body-cell interest, scene-authored visibility (§12)
|
|
64
84
|
"nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
|
|
65
85
|
"tiers": true, // optional (v1.21); a cheaper picture on a slow device, client only
|
|
66
86
|
"cues": true, // optional (v1.23); a town says more about the friends and party a player came with
|
|
87
|
+
"stuck": true, // optional (v1.33); a town offers a player who walks and gets nowhere the way back to its arrival (§5)
|
|
88
|
+
"labels": "near", // optional (v1.43); a town's labels near the player only, never overlapping, three at most (§10)
|
|
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)
|
|
91
|
+
"unlocks": [ // optional (v1.53, v1.70/v1.73); at most 8 wearable + 6 furniture/deed + 16 pet items (§11)
|
|
92
|
+
{ "id": "cove-3-wins", "class": "badge", "shape": "badge-round", "name": "Cove Ace", "deed": "win 3 races in Cove", "color": "#3aa0d8" },
|
|
93
|
+
{ "id": "farm-planter", "class": "furniture", "piece": "planter", "name": "Crate Planter", "deed": "buy at the Willowbank stand for 300 coins", "color": "#8a5a2b" },
|
|
94
|
+
{ "id": "farm-yard", "class": "deed", "piece": "yard", "name": "Yard Deed", "deed": "buy at the Willowbank stand for 800 coins", "color": "#5aa04a" }
|
|
95
|
+
],
|
|
67
96
|
"places": { } // optional; more places in the same deck (§3)
|
|
68
97
|
}
|
|
69
98
|
```
|
|
70
99
|
|
|
100
|
+
A deck may declare up to 8 wearable earned items (badge, pin, belt, sash,
|
|
101
|
+
held), up to 6 furniture or deed items, and separately up to 16 pet items,
|
|
102
|
+
with ids unique across all three groups. A home entry is exactly
|
|
103
|
+
`{ id, class, piece, name, deed, color }`;
|
|
104
|
+
`piece` matches `[a-z][a-z0-9-]{0,23}`; a pet species matches
|
|
105
|
+
`pet-[a-z][a-z0-9-]{0,19}` and never `pet-walk-*`. A `shape` on a home entry
|
|
106
|
+
or `piece` on a wearable is an error. The check warns about an unlisted piece and keeps it.
|
|
107
|
+
|
|
108
|
+
A malformed `unlocks` (more than 8 wearable, 6 furniture/deed or 16 pet items,
|
|
109
|
+
an entry out of the rules of §11, an id twice) is a manifest error like any other here: the kit refuses to load
|
|
110
|
+
the place, and `castle-web check` / save-deck's check catches it first. Ghost,
|
|
111
|
+
reading the saved deck, treats the same list as no unlocks at all.
|
|
112
|
+
|
|
71
113
|
| field | type | rule |
|
|
72
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). |
|
|
73
119
|
| `contract` | integer | `1`. A deck naming a version the kit does not know is refused (check fails; the server logs and runs nothing). |
|
|
74
120
|
| `title` | string | 1-40 chars. |
|
|
75
121
|
| `scene` | string | a `scenes/*.scene` path the deck has. |
|
|
@@ -82,13 +128,33 @@ curation where it cannot:
|
|
|
82
128
|
| `sign` | object | `model`: a `.pxmodel` the deck has; `board`: `"score"` or a declared numeric stat. |
|
|
83
129
|
| `places` | object | §3. |
|
|
84
130
|
| `npcs` | object | §13. |
|
|
85
|
-
| `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. |
|
|
86
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). |
|
|
87
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). |
|
|
88
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. |
|
|
135
|
+
| `actions` | boolean | v1.74, a place's (`hub.actions` or `hub.places.<id>.actions`): `true` enables private action chips (§9). Any value other than `true` or an absent key is a manifest error. Absent: no API, action hook lookup, private state, chrome, message or snapshot key; existing wire bytes stay identical. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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`. |
|
|
89
148
|
| `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
|
|
90
|
-
| `
|
|
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. |
|
|
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. |
|
|
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. |
|
|
91
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. |
|
|
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. |
|
|
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 |
|
|
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. |
|
|
92
158
|
|
|
93
159
|
Unknown keys are a check failure, not ignored: a typo in a contract field must
|
|
94
160
|
not publish as "no such rule".
|
|
@@ -143,34 +209,55 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
143
209
|
| hook | when |
|
|
144
210
|
| --- | --- |
|
|
145
211
|
| `ready(hub)` | the world is built, before the first tick |
|
|
146
|
-
| `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 |
|
|
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. |
|
|
147
214
|
| `step(hub, dt)` | after each physics step; `dt` seconds |
|
|
148
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 |
|
|
149
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) |
|
|
150
|
-
| `leave(hub, playerId, { userId, username })` | a player left (Back, the host's Back, a closed tab). Runs while the player is still known (v1.2): `hub.result` takes their result for the visit here, and `userId` names their storage (§14) |
|
|
217
|
+
| `leave(hub, playerId, { userId, username })` | a player left (Back, the host's Back, a closed tab). v1.89 `{ resume: { keep: true } }` delays an unexplained absence up to 60 s (§12); a short resume runs neither leave nor arrive. Runs while the player is still known (v1.2): `hub.result` takes their result for the visit here, and `userId` names their storage (§14) |
|
|
151
218
|
| `shutdown(hub)` | v1.2: the session is stopping. Anyone still here has had `leave` first; return a promise to finish writing (awaited up to 1.5 s, inside the host's own grace) |
|
|
152
219
|
| `grab(hub, playerId, actorId, op)` | v1.3, a place with `grab`: a player grabbed (`op` `"grab"`) or threw (`"throw"`) a loose object (§6). Return `false` to a grab to refuse it (the player lets go at once); a throw is only told. A hook that throws refuses the grab |
|
|
153
220
|
| `emote(hub, playerId, id)` | v1.6, a place with `idle.emotes`: a player asked to play emote `id` (§6). Return `false` to refuse it (nobody sees it); a hook that throws refuses it |
|
|
221
|
+
| `npcReact(hub, npc, playerId, { emote })` | v1.47: a nearby free NPC may answer this player's emote (§6, §13). Return `false` to leave it alone, null or undefined for its props and the kit's defaults, or `{ emote, line }` to replace either. `emote` is a kit id or null for no motion; `line` is public speech, cut to 80 characters, or null for none. Errors are logged once and use the defaults. Async results are unsupported and ignored; rejected promises are caught with fixed log text. No model is called |
|
|
154
222
|
| `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). Return `false` to refuse; a hook that throws refuses |
|
|
223
|
+
| `action(hub, playerId, id)` | v1.74, a place with `actions: true`: an arrived, connected player pressed an id in their current offer, carrying a safe-integer `n` equal to that offer's current version (§9). Stale, removed, another player's, malformed or over-budget presses are silently dropped. Six presses/s with a burst of eight per player; dropped or refused presses spend tokens too. The return is ignored; throws and rejections are contained and logged once. Async hooks are neither serialised nor cancelled when the player leaves. |
|
|
224
|
+
| `menu(hub, playerId, id)` | v1.79, only with `menu: true`: an arrived, connected player picked an item in their current, last-sent menu with its safe-integer `n`, or closed the sheet (`id: "close"`). Stale, unknown, malformed and over-budget picks are dropped; readOnly refuses item picks but still delivers close. Six attempts/s, burst eight per player, including dropped presses. Return ignored; throws/rejections contained and logged once. Async hooks are neither serialised nor cancelled on leave. |
|
|
225
|
+
| `answer(hub, playerId, id, text)` | v1.75, only in a place with `ask: true`: that arrived, connected player answered their last-sent and still-current prompt; `text` is the exact string they typed, or `null` for Cancel (§9). The prompt is consumed and its close queued before the hook runs. Refused text on a current id/version consumes the prompt and calls the hook with null; it is never passed on. Two attempts/s, burst four per player; stale, malformed, oversized and dropped messages spend tokens too. Return ignored; throws and rejections contained and logged once without the text or error details. A place must never show what a player typed to another player. |
|
|
226
|
+
| `decor(hub, playerId, op)` | v1.67, a place with `decor`: an offered button or an open catalogue's validated edit (§10 Decorating). The deck checks ownership, stock and collisions and applies the edit; the kit moves or spawns nothing |
|
|
227
|
+
| `ballot(hub, playerId, { face, line, option, mode })` | v1.68, a place with `ballot`: a player tapped the choice card (§6). `face` a player id on their card or null, `line` a manifest line id or null, `option` an option id of the card or null, `mode` the card's mode then. The kit has already checked it against the card that player was last sent and limited it; the hook decides what it means (a line for the card's `feed`, a vote to count). Its return is ignored; a hook that throws is logged |
|
|
155
228
|
| `message(hub, player, data)` | a client message that is not the kit's own. Tier 0 games have no client code, so this is for bots and tests |
|
|
229
|
+
| `unstick(hub, playerId, from)` | v1.39, a town of a deck with `hub.stuck`: where to put a player who is stuck at `from` (`{ x, y, z }`, their body) and asked to be moved (§5 "Stuck?"): `{ x, z, y?, facing?, to? }` -- a spot inside the world box, `facing` in degrees, `to` the place's name for it in at most 40 characters ("the street") -- or null for the arrival. It answers at once (a promise is the arrival). Asked when the player taps, and also when their client is about to offer the tap, to word it: it must change nothing. A place without it lands its players at the arrival |
|
|
156
230
|
| `where(hub, at)` | v1.9, a town: what the place calls the spot `at` (`{ x, y, z }`), for the People list (§5): a string of at most 40 characters ("in the square", "on Race Row"), or null. Asked only for a spot that is not on a door's pad or beside a door, which the kit words itself |
|
|
157
|
-
| `npcLine(hub, npc, playerId, { why, text })` | an authored line for an NPC to say to a player when its mind is not answering (§13); return a string, or null for the kit's |
|
|
231
|
+
| `npcLine(hub, npc, playerId, { why, text, conversation })` | an authored line for an NPC to say to a player when its mind is not answering (§13); return a string, or null for the kit's. v1.47: an authored say receives the conversation number captured at admission, matching `npcOpening`'s `info.conversation` |
|
|
158
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 |
|
|
159
|
-
| `
|
|
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 |
|
|
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 |
|
|
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) |
|
|
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 |
|
|
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 |
|
|
160
238
|
|
|
161
239
|
`hub` carries the session, so a tick can send (M0 gap 5):
|
|
162
240
|
|
|
163
241
|
| member | what |
|
|
164
242
|
| --- | --- |
|
|
243
|
+
| `hub.owner` | v1.67: the platform owner user id string on an owner door instance, null otherwise; dev-only `hub.house.devOwner: "first"` keeps the first arrival as owner for the session (below) |
|
|
244
|
+
| `hub.actions(playerId, items \| null)` | v1.74, present only in a place with `actions: true`: privately offer 0..3 `{ id, label }` chips. Unique ids match `[a-z][a-z0-9_-]{0,23}`; labels are strings of 1..16 characters (code points), no control, direction or zero-width characters, and cannot be only whitespace. Items must be plain objects with own `id` and `label` properties; each is read once, validated and copied; unknown keys are refused. `null` or `[]` clears. Invalid calls throw `TypeError` before changing state. Unknown, disconnected or not-arrived players return false; otherwise true. Calls record the newest list; a changed recorded list advances that player's safe-integer version `n`, including a change to null. The tick coalesces ordinary deliveries to at most four offers a second per player (250 ms apart), newest wins; equal last-sent and current lists send nothing. Leave drops chips; the session's counter is kept. A fresh hello immediately replays the current offer once (or null), with its current `n`. |
|
|
245
|
+
| `hub.companion(playerId, spec \| null)` | v1.71, present only with either companion manifest form: one private follower per arrived player. `spec` is a plain object with only own `look` (required, `"lantern"` or `"bird"`), optional `say` (string, 1..80 code points, at most 240 UTF-16 units, non-blank, no control, bidi, zero-width characters or newlines), optional `dress` (v1.78, bird only; enum slots and defaults in §9), optional `pose` (v1.78, bird only; only `"show"`), and optional `at` (scene actor id string, 1..64 characters; unknown ids are ignored by the client). Fields are read once, validated and copied. Invalid calls throw `TypeError` before changing state; an absent or not-arrived player returns false, otherwise true. `null` clears; equal specs change and send nothing. Ordinary tick sends coalesce to at most four/s per player, newest wins; a spec changed back to the last-sent one keeps that version. Fresh hello replays the current spec; leave forgets it, retaining the place session's version counter. The place authors every line; nothing a player typed may be passed to `say`. The line is never shown to anyone else. |
|
|
246
|
+
| `hub.menu(playerId, spec \| null)` | v1.79, present only with `menu: true`: privately offer the sheet described in §9. Null closes it. Validate and copy before changing state; invalid calls throw TypeError. Unknown, disconnected or not-arrived players return false; otherwise true. Every changed spec advances that player's safe-integer version `n`; equal re-sends send nothing. Tick coalesces to four ordinary offers/s; a fresh hello replays an open menu or a pending close once, and sends nothing for an unused menu or an already delivered close. Leave forgets the menu, retaining the counter to prevent reused versions. |
|
|
247
|
+
| `hub.ask(playerId, spec \| null)` | v1.75, present only with `ask: true`: one private prompt per player, replaced by a new spec. A plain object has exactly own `id`, `title`, `max`; each field is read once, validated and copied. Ids match `[a-z][a-z0-9_-]{0,23}`; titles are 1..32 code points, not whitespace-only, with no control, Bidi_Control or zero-width characters; `max` is a safe integer 1..32 code points. `null` closes. Invalid calls throw `TypeError` before changing state; unknown, disconnected or not-arrived players return false, otherwise true. Every changed recorded prompt, including null, advances safe-integer `n` from one session counter. Tick deliveries coalesce to at most four/s per player, newest wins, equal last-sent/current content and version suppressed. Leave forgets; a fresh hello replays the current prompt or null once with its `n`. Accepted answers consume and queue the close before calling the hook; it shares the tick delivery budget. |
|
|
248
|
+
| `hub.decor` | v1.67, present only in a place declaring `decor`: private `button`, `open`, `close` and `update` (§10 Decorating) |
|
|
165
249
|
| `hub.session`, `hub.sim` | the Castle session and the multiplayer-3d simulation |
|
|
166
250
|
| `hub.place` | `{ id, title, scene, manifest }` |
|
|
167
251
|
| `hub.now` | simulation milliseconds |
|
|
168
|
-
| `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`) |
|
|
169
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) |
|
|
170
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) |
|
|
171
258
|
| `hub.hold(playerId, at?, facingDeg?)` / `hub.release(playerId)` | hold a player still (§8) |
|
|
172
259
|
| `hub.setHud(spec, playerId?)` | the declared HUD, for everyone or one player (§9) |
|
|
173
|
-
| `hub.hide(actorId)` / `hub.show(actorId)` | server-declared actor visibility (§10) |
|
|
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 |
|
|
174
261
|
| `hub.move(actorId, { x, y, z, rotationY }, { overMs }?)` | move a kinematic scene actor, at once or in a straight line over `overMs`; any subset of the fields (§10, v1.1) |
|
|
175
262
|
| `hub.tint(actorId, color)` | paint a Shape actor `#rrggbb` for everyone; `null` puts back its authored colour (§10, v1.1) |
|
|
176
263
|
| `hub.pose(actorId)` | where an actor's body is now: `{ x, y, z, rotationY, velocity, owner }` (`owner` the player whose client simulates a loose object, or null), or null (§10, v1.3) |
|
|
@@ -182,9 +269,24 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
182
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) |
|
|
183
270
|
| `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
|
|
184
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
185
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) |
|
|
186
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) |
|
|
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 |
|
|
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 |
|
|
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) |
|
|
187
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) |
|
|
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) |
|
|
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). |
|
|
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) |
|
|
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) |
|
|
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. |
|
|
188
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 |
|
|
189
291
|
| `hub.npc(actorId)`, `hub.npcs()` | the place's NPC bodies (§13) |
|
|
190
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) |
|
|
@@ -194,7 +296,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
|
|
|
194
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 |
|
|
195
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 |
|
|
196
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 |
|
|
197
|
-
| `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. |
|
|
198
300
|
| `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
|
|
199
301
|
|
|
200
302
|
`hub.go` is how any place launches: in dev it mints `hub.<place>.<random>` and
|
|
@@ -269,8 +371,135 @@ id, or null when nobody went. Only a public layer of a deck's main place has
|
|
|
269
371
|
that place's minds (§13), so a place whose NPCs have minds is reached by a
|
|
270
372
|
layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
271
373
|
|
|
374
|
+
**Friends and bests (v1.36, v1.57).** The kit has no age data. The bounded
|
|
375
|
+
`friendBests` index keeps user id, username and best for every signed-in player
|
|
376
|
+
who reports a best, just like the game's own board/results and its per-player
|
|
377
|
+
record keys. It is shown to no one except through `friendsAmong`: ghost requires
|
|
378
|
+
a mutual follow, no block and both players answered over 13. An under-13 player
|
|
379
|
+
is never shown and never sees anyone. The client flag may make their client ask
|
|
380
|
+
`Hub.friends`; ghost answers with nothing, so no data flows from that ask.
|
|
381
|
+
Each successful write advances a local index generation; a read begun before
|
|
382
|
+
that write completed cannot replace its cache. Reports read-modify-write from
|
|
383
|
+
the freshest cache or a storage read begun after the last write. Cross-layer
|
|
384
|
+
lost updates remain acceptable.
|
|
385
|
+
|
|
386
|
+
When a place first calls `friendsAmong` for a connected player, only
|
|
387
|
+
that player receives `{ k: 'hub-friends-wanted' }`, latched for the visit and
|
|
388
|
+
resent on a fresh hello. It is never in a snapshot. The client in a game asks
|
|
389
|
+
`castleSdk.Hub.friends()` on receipt (the next idle tick), again 20 s later,
|
|
390
|
+
then every 90 s while joined, outside a trip; `UNKNOWN_COMMAND` disables asks as in the town.
|
|
391
|
+
A place that never calls it sends no flag and its game clients make no ask.
|
|
392
|
+
Ghost answers only when that player's own client asked within the last 120 s;
|
|
393
|
+
the handoff writes no marker. In pad/exact sessions, ghost also needs the
|
|
394
|
+
player in its heartbeat roster (up to about 15 s late). Empty arrival lookups
|
|
395
|
+
expire after 40 s so a result-screen or leaving-line lookup can succeed later.
|
|
396
|
+
The seven games wait for a successfully loaded signed-in record before asking;
|
|
397
|
+
guests, players still loading and unsaved players send no friends request or
|
|
398
|
+
flag. Under-13 players and every refusal show no comparison.
|
|
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
|
+
|
|
414
|
+
On the local dev serve only, `CASTLE_DEV_HUB_FRIENDS=all` in the serve process
|
|
415
|
+
environment treats every valid candidate as a friend. Without it, absent hub
|
|
416
|
+
ops resolve `[]`. The fixture requires a dev session and no platform hub ops;
|
|
417
|
+
it cannot override ghost in production. It writes no friend list.
|
|
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
|
+
|
|
424
|
+
**Owner instances (v1.67).** `hub.owner` reads the non-empty string
|
|
425
|
+
`session.hub.owner` supplied by the platform, never a client's message. It is
|
|
426
|
+
the owner account's user id on an owner door instance, and null on other
|
|
427
|
+
instances. The owner need not have arrived when `ready` reads it. A deck's
|
|
428
|
+
optional `hub.house: { devOwner: "first" }` stands in on the dev serve only
|
|
429
|
+
(`dev` / `dev:*`, with no platform hub): immediately before the first `arrive`
|
|
430
|
+
hook, the first player in arrival order becomes the owner by their `userId`
|
|
431
|
+
(dev guest subjects count). That choice remains for the session after the
|
|
432
|
+
owner leaves; an arrival with no user id keeps null. The key has no effect in
|
|
433
|
+
production and is not sent to clients. Leaving it out keeps dev ownership null.
|
|
434
|
+
|
|
272
435
|
## 5. Arrival and exit
|
|
273
436
|
|
|
437
|
+
**Your games (v1.54, `hub.yourGames: true`).** Only in a town (no `result`),
|
|
438
|
+
for signed-in players. The kit uses the results reads it already makes: account
|
|
439
|
+
`hearts` on each read player, `hub.results(playerId).recent` and `records`, and
|
|
440
|
+
this place's doors and boards. Hearted doors come first in heart order, then
|
|
441
|
+
recent games mapped by destination deck to this town's doors, with no
|
|
442
|
+
duplicates and at most five rows. Each line names their best with the board's
|
|
443
|
+
unit from the record for the destination place, or their last result in that
|
|
444
|
+
deck, plus when they played (today, yesterday, 3 days ago), formatted by the
|
|
445
|
+
client using the player's local calendar date. The server sends the result
|
|
446
|
+
wording in `line` and the last play time in `lastAt` (epoch ms, or `null`).
|
|
447
|
+
A door with no record may have an empty line. Hidden doors, cabinets and closed
|
|
448
|
+
event gates are excluded before the five-row cap, using the Doors list's filter.
|
|
449
|
+
`{ k: 'hub-yours', rows: [{ door, title, line, lastAt, hearted }],
|
|
450
|
+
hearts }` is latched to that player alone when it changes; a player with nothing
|
|
451
|
+
gets no initial message. A later empty answer clears rows previously sent.
|
|
452
|
+
Fresh client hellos resend private rows; ordinary history refreshes update them.
|
|
453
|
+
|
|
454
|
+
The Doors list draws Your games above All doors, three rows on a narrow stage
|
|
455
|
+
and five with the chrome's desktop breakpoint (fine pointer and width ≥700px).
|
|
456
|
+
Go uses the existing jump onto that door's pad, including party and solo rules.
|
|
457
|
+
Every row can carry ♡ / ♥; ★ still means featured today. The kit asks
|
|
458
|
+
`Hub.hearts()` once per town visit after signed-in identity is known. Hearts are
|
|
459
|
+
hidden for guests, unavailable hosts and `UNKNOWN_COMMAND`. Taps update
|
|
460
|
+
optimistically and serialize `Hub.setHearts(doorIds)` writes: new hearts go last,
|
|
461
|
+
the oldest drops beyond eight. A failed write rolls that toggle back with a short
|
|
462
|
+
toast, preserving later taps. Each write reads the account's hearts first and applies
|
|
463
|
+
the toggle to them; two tabs or devices of one account that toggle in the same
|
|
464
|
+
read-to-write moment can lose one of the two hearts (accepted: ghost replaces the list,
|
|
465
|
+
there is no atomic toggle). Hearts live on the account, never in browser storage;
|
|
466
|
+
the dev serve keeps them per account in memory for its lifetime.
|
|
467
|
+
|
|
468
|
+
An outside arrival with rows is offered `♥ <title>`, its personal line, Go and
|
|
469
|
+
Not now once for 12 s from its first display. It waits up to 60 s for
|
|
470
|
+
signed-in identity and arrival data. Returning from a game offers the door just played
|
|
471
|
+
instead, with a heart toggle where supported. If it is outside the five private
|
|
472
|
+
rows, its carried last result supplies the line until a read can name it.
|
|
473
|
+
This replaces cues' Play again chip when `yourGames` is enabled. Both use the same ask slot and door jump:
|
|
474
|
+
Go together for a party and a non-solo door, Go for solo. No chip over an
|
|
475
|
+
invitation or party proposal, in a game, during a trip or while other chrome is
|
|
476
|
+
suppressed. The chip fits within 94vw and its personal line ellipsizes.
|
|
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
|
+
|
|
274
503
|
- Players sent together by one `hub.go` arrive together: the kit holds a group's
|
|
275
504
|
first arrival still, up to 1.5 s, for the rest, places them in a row at
|
|
276
505
|
`arrival.actor` spaced by `arrival.spread`, and calls `arrive` once with all
|
|
@@ -280,6 +509,19 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
280
509
|
- **Arrival facing is contract data**, not scene metadata (M0 gap 9): the body
|
|
281
510
|
faces `arrival.face`, and the client's camera starts behind it.
|
|
282
511
|
- A late joiner arrives the same way, alone.
|
|
512
|
+
- **A line on leaving (v1.52).** `hub.leaving(playerId, text)` says what is waiting
|
|
513
|
+
next visit: on Back, a game's end or a door out of the place (not a classic
|
|
514
|
+
cabinet), the latest line is captured under the trip cover's title and,
|
|
515
|
+
if the cover lifts sooner, kept as a toast until 2.8 s after the trip started,
|
|
516
|
+
combined with "Back from <result>" on a return. Retries keep the first trip's
|
|
517
|
+
captured line and deadline; newer toast feedback supersedes it. The leaving
|
|
518
|
+
toast wraps within the screen width and restores the ordinary toast styles
|
|
519
|
+
afterward. Toasts sit under the HUD and top cards on a phone, or above
|
|
520
|
+
the bottom controls on a desktop, with a gap and their box kept in view.
|
|
521
|
+
A fresh hello replays the latched line to that player alone. It never slows the trip,
|
|
522
|
+
clears on leaving, and a place that never calls it sends and draws exactly
|
|
523
|
+
what it did before. Set it during the visit, before `hub.go` or `hub.end`,
|
|
524
|
+
rather than in `leave`, which runs after the player has gone.
|
|
283
525
|
- **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
|
|
284
526
|
button lists the place's doors; Go puts the player on that door's pad (the
|
|
285
527
|
`HubPad` actor naming it, v1.10: inside its radius, so the pad counts them;
|
|
@@ -288,6 +530,96 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
288
530
|
most room), facing the door, or 7 m in front of a door with no pad, in the
|
|
289
531
|
door's own frame (at most once a second; never a held player). It is a walk, not a trip: the player stays in this session. A game
|
|
290
532
|
has no list.
|
|
533
|
+
- **Stuck? (v1.33).** In a deck with `hub.stuck`, a town offers the way back
|
|
534
|
+
to its arrival to a player who walks and gets nowhere. The client watches
|
|
535
|
+
its own player only: walk input -- whatever the Player behavior walks the
|
|
536
|
+
body on, by its own rule under each camera (W/S and up/down; the drag stick
|
|
537
|
+
pushed 0.15 or more of its length with any push up or down, or under the
|
|
538
|
+
orbit camera any push at all; A/D under the orbit camera, where they walk
|
|
539
|
+
sideways; never input that only turns, and never Space). The rule
|
|
540
|
+
(v1.39): look back from now over the shortest stretch that holds 3 s of
|
|
541
|
+
walk input seen, never further than 8 s; the chip shows when there is such
|
|
542
|
+
a stretch and, over it, the box round every position the body was seen at
|
|
543
|
+
is under 1 m from corner to corner on the ground (a jump on the spot is
|
|
544
|
+
not a way out). The input need not be without a break: a player who walks
|
|
545
|
+
in bursts, pushing and letting go, is counted across the breaks, and one
|
|
546
|
+
who walks less than 3 s in 8 is not offered it. "Nowhere" is the net of
|
|
547
|
+
the stretch, not its path: pacing 0.9 m back and forth against a wall is
|
|
548
|
+
stuck; pacing across 3 m, or circling a prop, is not; and a free walker
|
|
549
|
+
covers some 17 m in 3 s of walking (about 6 m at 10 frames a second, the
|
|
550
|
+
body moving 33 ms of walking a frame), so nothing that moves is near it.
|
|
551
|
+
(v1.33's rule was 3 s without a break of 250 ms within 0.3 m of where the
|
|
552
|
+
count began: a player walking in bursts never saw the chip.) The 3 s are
|
|
553
|
+
of frames drawn, each counted for its own length up to 100 ms, so a phone
|
|
554
|
+
at 10 frames a second is offered it as soon as a fast one. A frame over
|
|
555
|
+
250 ms is a hitch and counts for nothing, with nothing forgotten; 1 s
|
|
556
|
+
between two frames, a clock that went backwards, or a hidden page starts
|
|
557
|
+
everything over and takes the chip down. Then a chip shows at the bottom centre, "Stuck? Tap to go to
|
|
558
|
+
the square". It is kept out from under the HUD and a question (an
|
|
559
|
+
invitation, a party's door, "Play <door> again?") as a clear HUD keeps
|
|
560
|
+
labels out from under itself (§9), in any place: moved to just under them
|
|
561
|
+
on a view short enough that they reach it (a phone on its side), and not
|
|
562
|
+
drawn where that would put it over another control, a cabinet's card or
|
|
563
|
+
the ribbon (where a clear HUD has put them, §9), or off the view: the chip
|
|
564
|
+
is placed last in a frame and is the one that yields. A label, speech or a
|
|
565
|
+
pointer is not in its way: those pass under the chip, as under every
|
|
566
|
+
button of the chrome. It only offers: a player leaning on a wall is not
|
|
567
|
+
stuck, and nobody is moved without their tap. Once up it stays
|
|
568
|
+
while the last 8 s still hold 2.5 s of walk input (the stretch looked over
|
|
569
|
+
is then the one holding that much), so a player whose input sits right at
|
|
570
|
+
3 s in 8 does not see it come and go. It goes the moment that
|
|
571
|
+
box is 1 m across, when the place changes, while a list or
|
|
572
|
+
card of the chrome is open or there is no room for it, and 3 s after the player last gave walk input (not at once:
|
|
573
|
+
on a phone the thumb that walks is the thumb that taps); pushing on again
|
|
574
|
+
keeps it, or brings it back. The Doors list has the same thing as its first
|
|
575
|
+
row, "Stuck?" over "Back to the square", whenever the list is shown (a town
|
|
576
|
+
with no door has no list, and only the chip). A tap on either sends
|
|
577
|
+
`hub-unstick` (§12) and the place puts that one player where the fall rule
|
|
578
|
+
would -- `arrival`'s actor, facing as an arrival does -- then says
|
|
579
|
+
`hub-jumped`, as for a jump to a door. The place answers once in 5 s per
|
|
580
|
+
player; it counts as a jump (not within a second of one, and a sitter gets
|
|
581
|
+
up first); never for a held player, one who has not arrived or one whose
|
|
582
|
+
visit has ended; and never in a game (a place with a `result`), where the
|
|
583
|
+
way back to the start is the game's to give or keep -- a free one would be
|
|
584
|
+
a way out of a trap, a tag or a lost position. **The place's own spot
|
|
585
|
+
(v1.39).** The arrival is not always a way out: a player whose straight
|
|
586
|
+
line from it ran into the obstacle walks back into it. A place with the
|
|
587
|
+
`unstick(hub, playerId, from)` hook (§4) is asked, at the tap and after
|
|
588
|
+
every check above, where to put the player whose body is at `from`
|
|
589
|
+
(`{ x, y, z }`), and answers `{ x, z }` -- with `y` (default standing
|
|
590
|
+
height at that spot when proved clear and no higher than 1.2, else 1.2,
|
|
591
|
+
as an arrival's; v1.48), `facing` (degrees, as `hub.hold` takes them; default:
|
|
592
|
+
as the body faces) and `to` (its name for the spot, at most 40 characters,
|
|
593
|
+
"the street") where it has them -- or null for the arrival. The kit puts the
|
|
594
|
+
player there and says `hub-jumped` with that facing, so the camera turns
|
|
595
|
+
to it. An answer that is not a spot (`x`, `z` and any `y` or `facing` not
|
|
596
|
+
finite numbers, or a point outside the world box, |x|, |z| ≤ 200,
|
|
597
|
+
-30 ≤ y ≤ 80) or a hook that throws is the arrival, with a warning in the
|
|
598
|
+
log; the kit does not check that the spot is clear. The hook answers at
|
|
599
|
+
once: a promise (anything with a `then`) is not a spot and is the arrival
|
|
600
|
+
too, whatever it would have resolved to. Nothing a place returns or throws
|
|
601
|
+
there stops a tap from landing somewhere valid and being answered. In such a place the
|
|
602
|
+
snapshot's `hubStuck` carries `hook: true`, the Doors row reads "Get
|
|
603
|
+
unstuck", and the chip's words are the place's: as the chip comes up the
|
|
604
|
+
client asks what a tap would do (`{ k: 'hub-unstick', ask: true }`, §12)
|
|
605
|
+
and the place asks its hook and answers (`hub-unstick-to`) without moving
|
|
606
|
+
anyone -- so the hook is a question, asked more often than players are
|
|
607
|
+
moved, and must change nothing -- at most once a second per player, and
|
|
608
|
+
not for one it would not move. The chip reads "Stuck? Tap to go to the
|
|
609
|
+
street" for a spot with a name, "Stuck? Tap to get unstuck" for one
|
|
610
|
+
without (and until the answer comes), and the arrival's own words where
|
|
611
|
+
the hook answered null. The `hub-jumped` that follows a tap there carries
|
|
612
|
+
`stuck: { spot, to }`, which the client says once the player has landed
|
|
613
|
+
("Back to the street"). A place without the hook is asked nothing, is sent
|
|
614
|
+
nothing more and lands its players at the arrival as before. A place that takes it says
|
|
615
|
+
so in its snapshot (`hubStuck: { to }`), and a client offers nothing where
|
|
616
|
+
it has not: `to` is the place's name for its arrival, the `where` hook's
|
|
617
|
+
words for that spot when they begin "in ", "on " or "at ", without that
|
|
618
|
+
word ("in the square" → "the square"; the kit's own words for a pad or a
|
|
619
|
+
door are not used), else null and the chip reads "Stuck? Tap to go back to
|
|
620
|
+
the start". Without `hub.stuck` none of this exists: `hub-unstick` is a
|
|
621
|
+
message the kit does not know and goes to the place's `message` hook like
|
|
622
|
+
any other.
|
|
291
623
|
- **Where a player came from** is ghost's arrival where the host has hub ops
|
|
292
624
|
(the door row the player was placed by, `fromDeckId` and `doorId`); the
|
|
293
625
|
client's hello names it only in dev.
|
|
@@ -298,7 +630,16 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
298
630
|
pack, or a pack that fails keeps the door shut and gives the acquisition back
|
|
299
631
|
(`Hub.cancel`). The way back is `Hub.back()`; the host's own Back control is
|
|
300
632
|
answered the same way (`Hub.onBack`), and while the host's trail holds a hub
|
|
301
|
-
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
|
|
302
643
|
the destination is mounted until the host commits the join
|
|
303
644
|
(`multiplayer.joinState()`); a join it does not commit leaves the player's
|
|
304
645
|
place as it was: a door's trip rejoins the session it left when that is not
|
|
@@ -368,7 +709,14 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
368
709
|
session is listed too: "in another part of town" (another layer; Join is the
|
|
369
710
|
jump below), or, on a host that says which door's game they are in
|
|
370
711
|
(`door` on a `Hub.friends` row), "inside <door>" (Join is a jump to that
|
|
371
|
-
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.
|
|
372
720
|
- **Starting next to a friend (v1.12).** A player who walks into a town (no
|
|
373
721
|
door, no jump) and finds a party member or a friend in the same layer is put
|
|
374
722
|
beside them, once: the client asks the place (`hub-goto`) for a party member
|
|
@@ -417,16 +765,32 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
417
765
|
`unavailable` or does not know the command is not asked again.
|
|
418
766
|
- **Falling (v1.1).** A scene can have no ground at all (`"ground": { "none":
|
|
419
767
|
true }` at the scene file's top level, which the engine and the server both
|
|
420
|
-
read): a pit, lava, islands in the sky. A place whose players can fall
|
|
421
|
-
|
|
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
|
|
422
771
|
drops below it is handed to the game's `fall(hub, playerId)` hook, and if
|
|
423
772
|
they are still down there afterwards the kit puts them back at the arrival.
|
|
424
773
|
A held player is not caught (the game holds whom it has already dealt
|
|
425
774
|
with). The hub client stops its own player's fall a metre under `fallY`
|
|
426
775
|
(the snapshot's `hubPlace.fallY`), since the server reads no pose below the
|
|
427
776
|
world's floor (-30 m) and a report that skipped past it would never be
|
|
428
|
-
caught.
|
|
429
|
-
|
|
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.
|
|
430
794
|
- **Exit** is always through the door the player came in by: the hub-drawn Back
|
|
431
795
|
control, `hub.end`, `maxDurationSec`, a crash or a republish. The game cannot
|
|
432
796
|
name the destination; the client's return ticket does (ghost's, once it
|
|
@@ -601,28 +965,49 @@ hub draws an emote picker, Sit and Stand, and the place's sounds. A place
|
|
|
601
965
|
without it draws nothing new and is sent exactly what it was.
|
|
602
966
|
|
|
603
967
|
- **Emotes** (`idle.emotes`). An emote button (☺, bottom right, above Grab)
|
|
604
|
-
opens the kit's emotes: `wave` 👋 (a side-to-side sway, 2 s), `dance` 💃
|
|
605
|
-
(bounce, sway and twist, 2
|
|
606
|
-
bow forward,
|
|
607
|
-
that player's avatar, with the emoji rising
|
|
968
|
+
opens the kit's emotes: `wave` 👋 (a side-to-side sway, 2.8 s), `dance` 💃
|
|
969
|
+
(bounce, sway and twist, 3.2 s), `cheer` 🎉 (three hops, 2.4 s), `bow` 🙇 (a
|
|
970
|
+
bow forward, 2.4 s) and `spin` 🌀 (a full turn, 2 s). Everyone sees it on
|
|
971
|
+
that player's avatar, with the emoji rising from the top of their drawn
|
|
972
|
+
model's head; where that is off the view's top or under the top chrome (the
|
|
973
|
+
HUD's box, a question card, Back, the sound button: a portrait phone), it is
|
|
974
|
+
drawn beside the head on its open side, and never under the top chrome
|
|
975
|
+
(2026-10-06; before, 2, 2.4, 1.6, 1.6 and 1.2 s, a smaller emoji and a
|
|
976
|
+
gentler motion, 2.25 m over the body, often under the HUD). It is drawn
|
|
608
977
|
only: the avatar's model moves inside its drawn node, never its body, its
|
|
609
978
|
network pose or what anyone simulates. The server takes one emote per
|
|
610
979
|
player every 2 s, refuses an id the kit does not have and a player who has
|
|
611
980
|
not arrived, and asks the place's `emote` hook, which may refuse it.
|
|
612
981
|
`hub.emote(playerId, id)` plays one on a player from the place itself (an
|
|
613
982
|
NPC's greeting, a goal) and is neither rate-limited nor offered to the hook.
|
|
983
|
+
v1.47: when a player's emote starts, up to three nearest free `HubNpc`
|
|
984
|
+
bodies within 6 flat metres face them and emote back. Wave, dance, cheer
|
|
985
|
+
and bow answer with the same emote; spin answers with cheer. About one in
|
|
986
|
+
three also says a short public line (§13). One player's emotes can start
|
|
987
|
+
reactions once every 4 s, and each NPC reacts once every 8 s; the player's
|
|
988
|
+
emote still plays as before. A conversation, follow, authored walk, place
|
|
989
|
+
move or hold, or a line still being spoken keeps that body busy. The place
|
|
990
|
+
can refuse others with `npcReact`. No model is called. A player without a
|
|
991
|
+
body here or who has not arrived triggers none; an NPC's emote triggers none.
|
|
614
992
|
- **Seats** (`idle.seats`). A scene actor carrying `HubSeat` (`{ face,
|
|
615
|
-
height }`,
|
|
993
|
+
height, pose }`, all optional) is a seat. `pose` is `"sit"` (the default)
|
|
994
|
+
or `"lie"`; any other value or unknown HubSeat key is refused by the check. A seat stays where it was authored: one
|
|
616
995
|
with a `"dynamic"` or `"kinematic"` `Body` is refused by the check and
|
|
617
996
|
ignored by the hub. A player standing within about 1.5 m of
|
|
618
|
-
a free one is offered Sit (bottom centre)
|
|
997
|
+
a free one is offered Sit (bottom centre), or Lie down for `pose: "lie"`. The server checks the seat is one,
|
|
619
998
|
shown and free (one player per seat), the player is here, not held by the
|
|
620
999
|
place and within 2.5 m, and asks the place's `sit` hook; then it holds them
|
|
621
1000
|
on the seat (§8): over its centre, `height` metres above its Transform
|
|
622
1001
|
(default: the top of its Shape plus a standing body's 0.85 m, so a sitter on
|
|
623
1002
|
a solid seat rests on it), facing `face` degrees (default the seat's own
|
|
624
1003
|
`rotationY`). Everyone draws a sitter lowered 0.45 m and tipped back a
|
|
625
|
-
little.
|
|
1004
|
+
little. A lie seat instead rotates the model -90 degrees about local X
|
|
1005
|
+
(face up, head toward the back / local -Z, feet toward its facing / +Z),
|
|
1006
|
+
offsets it +0.7 m along local Z to centre its length, cancels its standing
|
|
1007
|
+
model Y offset and places its origin 0.6 m below the held body centre.
|
|
1008
|
+
On the house bed (top about 0.55 m), the back rests about 0.56 m high.
|
|
1009
|
+
Absent `pose` or `"sit"` preserves the previous pose and wire byte-identically.
|
|
1010
|
+
Stand, any walk, turn or jump input (a tap on touch included), or a
|
|
626
1011
|
jump to a door gets them up where they are. A seat is a hold: a held player cannot sit, and the
|
|
627
1012
|
place's own `hub.hold` or `hub.release` of a sitter, a game's end, leaving,
|
|
628
1013
|
or the place hiding the seat stands them. `hub.seat(playerId)` says where a
|
|
@@ -643,6 +1028,364 @@ without it draws nothing new and is sent exactly what it was.
|
|
|
643
1028
|
place plays only its own content's files, never a same-named file of the
|
|
644
1029
|
town's.
|
|
645
1030
|
|
|
1031
|
+
**The soundscape (v1.42, v1.49, v1.50, v1.56).** A deck with `soundscape` in its manifest (§1) has
|
|
1032
|
+
the kit make sounds of its own, in every one of its places. All of it is
|
|
1033
|
+
synthesised in the client (WebAudio); none of it is a file, none of it is
|
|
1034
|
+
speech, and no word of a line can be made out. Synthesis belongs to the client:
|
|
1035
|
+
the place's server hears none of it; only explicit `hub.cue` calls (v1.50) send
|
|
1036
|
+
named cue messages, in a deck with `soundscape.cues: true`.
|
|
1037
|
+
|
|
1038
|
+
- **Babble** (`babble`, on unless `false`). v1.56 uses all four original
|
|
1039
|
+
round-6 audition options as voice types: glottal pulses through four
|
|
1040
|
+
formants, consonant noise, breath gated on the glottal open phase before
|
|
1041
|
+
the formants, and pitch jitter; no samples, TTS or real words. Text supplies
|
|
1042
|
+
word lengths (one to three made-up syllables per word), punctuation and a
|
|
1043
|
+
deterministic seed; the spoken words are made up, not the displayed text.
|
|
1044
|
+
`HubNpc.voice.type` selects a stable name from the exported `VOICE_TYPES`:
|
|
1045
|
+
|
|
1046
|
+
| type | audition and roles | parameters |
|
|
1047
|
+
| --- | --- | --- |
|
|
1048
|
+
| `townsfolk` | option 1; everyday townsfolk, shop/stall keepers | Rosenberg source, open quotient 0.6, speed quotient 2.5, rate 3.3, source gain 0.86 |
|
|
1049
|
+
| `lively` | option 2; barkers, kids, couriers, excitable roles | same as townsfolk, rate 4.6 |
|
|
1050
|
+
| `gruff` | option 3; older/gruff roles | LF source, Rd 1.2, rate 3.3, formant gains [11, 12, 9, 6] dB, source gain 1.158 |
|
|
1051
|
+
| `gentle` | option 4; caring roles | Rosenberg source as townsfolk, rate 3.3, formant gains [11, 12, 9, 6] dB, jitter 0.7, breath 0.75, jitter low-pass 120 Hz, source gain 1.047 |
|
|
1052
|
+
|
|
1053
|
+
All four start at pitch 240 Hz, mouth 1.08, pace 1.3 and breath low-pass
|
|
1054
|
+
2400 Hz; other parameters keep the audition defaults. Each type keeps its
|
|
1055
|
+
own source gain: the audition matched their voice RMS within 0.1%, preserving
|
|
1056
|
+
the fixed `BABBLE_LEVEL` calibration pending browser re-measurement.
|
|
1057
|
+
A valid explicit type wins. Otherwise the lower-case text
|
|
1058
|
+
`${role} ${character} ${name}` from `HubNpc` is matched as whole words in
|
|
1059
|
+
fixed precedence (gruff, gentle, lively); `role` is the place's own key,
|
|
1060
|
+
`character` its characterBundle id, and `name` its name. Invalid type names
|
|
1061
|
+
use the same default selection. `Innes` does not match `inn`.
|
|
1062
|
+
|
|
1063
|
+
| precedence/type | default keywords |
|
|
1064
|
+
| --- | --- |
|
|
1065
|
+
| 1 / `gruff` | harbourmaster, harbour master, innkeeper, inn, fisher, captain, smith, guard, elder, grandpa, old |
|
|
1066
|
+
| 2 / `gentle` | nursery, clinic, nurse, nana, granny, gardener, healer, vet, teacher, carer |
|
|
1067
|
+
| 3 / `lively` | kid, child, barker, crier, hawker, postie, courier, runner, coach, announcer, busker |
|
|
1068
|
+
| fallback / `townsfolk` | no keyword matched |
|
|
1069
|
+
|
|
1070
|
+
The actor id and `HubNpc.name` hash still seeds each NPC's made-up words
|
|
1071
|
+
and variation: pitch `240 * 2^(u * 0.9 - 0.4)` Hz (about 182–339), mouth
|
|
1072
|
+
from 1.0 to 1.16 rising with pitch, and its type's rate multiplied by
|
|
1073
|
+
0.9–1.1. The type replaces only the old seeded style choice; variation
|
|
1074
|
+
keeps its existing random draws. The same NPC sounds the same to everyone
|
|
1075
|
+
on every visit, in public speech and private panel lines.
|
|
1076
|
+
A body may override it with
|
|
1077
|
+
`"voice": { "type": "gentle", "pitch": 220, "rate": 7, "timbre": "square" }`.
|
|
1078
|
+
Each field is optional: pitch stays Hz clamped to 80–500 (mouth follows
|
|
1079
|
+
the clamped pitch); the legacy rate field stays clamped to 4–10 and maps
|
|
1080
|
+
linearly to the synthesiser's 2.5–6 range:
|
|
1081
|
+
`2.5 + (clamp(rate, 4, 10) - 4) * 3.5 / 6` (7 maps to 4.25).
|
|
1082
|
+
Legacy `sawtooth`, `square` and `triangle` timbre names are accepted and
|
|
1083
|
+
ignored. Invalid/nonfinite overrides use the character's defaults.
|
|
1084
|
+
A line lasts no more than 3 s, including its 50 ms fade/tail, and no more
|
|
1085
|
+
than 30 syllables. Long lines stop at the last complete word that fits.
|
|
1086
|
+
Each line has 22 synthesis nodes plus its distance gain; all three sources
|
|
1087
|
+
stop and every node disconnects on natural end or a quick cut (20 ms fade,
|
|
1088
|
+
sources stopped within 30 ms), without timers. `BABBLE_LEVEL` (about 0.248)
|
|
1089
|
+
matches the old babble's median active RMS (about −25.6 dBFS at volume 0.7),
|
|
1090
|
+
measured offline in Chromium through the whole chain.
|
|
1091
|
+
Moving formants, breath and the limiter await browser re-measurement.
|
|
1092
|
+
The text is drawn all at once, so babble starts as it appears.
|
|
1093
|
+
A line in a player's open talk panel is heard by that player alone, at
|
|
1094
|
+
full voice. Speech drawn over an NPC (`npc.say`, an
|
|
1095
|
+
authored line) is heard by whoever is sent it, louder the nearer they stand
|
|
1096
|
+
and silent 12 m away. A line that is both is voiced once. At most two NPCs
|
|
1097
|
+
are voiced at once, the nearest; a new line from an NPC cuts its old one.
|
|
1098
|
+
Only `HubNpc` bodies babble: never a player's reaction, phrase or chat.
|
|
1099
|
+
- **Steps** (`steps`, on unless `false`). A footfall for each stride the
|
|
1100
|
+
player's body covers on the ground (0.65 m at a walk, longer at a run, so
|
|
1101
|
+
about four a second at any speed, and none standing still), a small sound as
|
|
1102
|
+
they jump and a heavier one as they land. The same, at half the level, with
|
|
1103
|
+
no jump, for the other players and the NPCs within 10 m, quieter the
|
|
1104
|
+
farther off, four at once at most. A body that is put somewhere (a door
|
|
1105
|
+
jump, "Stuck?", a hold) takes no step, and nor does one the place hid.
|
|
1106
|
+
v1.50 high-passes each footfall body at 150–220 Hz, including landings,
|
|
1107
|
+
and lowers the thump by 40%, decaying in 55 ms instead of 90 ms.
|
|
1108
|
+
Boolean `steps: true` keeps street everywhere. v1.49 also
|
|
1109
|
+
accepts `steps: { default, zones, paths }`: `default` is a surface name
|
|
1110
|
+
(street when omitted), `zones` maps zone actor ids to surfaces, and `paths`
|
|
1111
|
+
names a scene component. Surfaces are `street`, `grass`, `wood`, `stone`,
|
|
1112
|
+
`sand` and `cobble`; grass is soft (low-passed at 2.5 kHz), and every
|
|
1113
|
+
surface's step is about as loud as the others (v1.56). A path component carries `points` (a polyline of
|
|
1114
|
+
`[x,z]` pairs or `{x,z}` objects), `half` (half its width in metres) and
|
|
1115
|
+
`surface`. A foot within `half` of any segment uses that surface before
|
|
1116
|
+
the zone or default. The player's zone keeps the same exit margin as
|
|
1117
|
+
ambience; nearby bodies use their own positions and zone history.
|
|
1118
|
+
- **Zones** (`zones`, v1.49, absent by default). The shared component name
|
|
1119
|
+
for ambience and mapped steps. Actors carrying it have numeric finite
|
|
1120
|
+
`x0,z0,x1,z1` bounds. The client reads these actors once for a scene and
|
|
1121
|
+
chooses by the local player's body, never the camera. A body enters from
|
|
1122
|
+
the exact edge and remains in the zone until more than 0.75 m outside;
|
|
1123
|
+
a point in no zone uses the default. An `ambience.beds` or `steps.zones`
|
|
1124
|
+
map requires this component name.
|
|
1125
|
+
- **Ambience** (`ambience`, v1.49, absent means none). An object with optional
|
|
1126
|
+
`beds` (zone actor id → bed), `default` (bed outside mapped zones),
|
|
1127
|
+
`spots` (component name → bed) and `music` (boolean, off by default).
|
|
1128
|
+
No default bed is added when `default` is omitted. The closed bed list is:
|
|
1129
|
+
|
|
1130
|
+
| Bed | Sound |
|
|
1131
|
+
| --- | --- |
|
|
1132
|
+
| `square` | Soft breeze and faint distant town air |
|
|
1133
|
+
| `meadow` | Breeze with birds at random intervals |
|
|
1134
|
+
| `night` | Low wind and an occasional owl |
|
|
1135
|
+
| `harbour` | Harbour A-rolled: balanced alternating swells, foam/backwash, distant sea, gulls and rope creaks |
|
|
1136
|
+
| `crowd` | Stadium crowd A: individual wordless voices, applause and clap-along swells with stadium echoes |
|
|
1137
|
+
| `market` | Stalls A / Haggling B: distant Simlish-like speakers, consonants/vowels, no real words or TTS |
|
|
1138
|
+
|
|
1139
|
+
Zone beds cross-fade over 1.5 s at approximately equal power. At most two
|
|
1140
|
+
zone beds live during a fade; the outgoing bed's sources stop and its
|
|
1141
|
+
nodes disconnect at the end. Noise buffers are shared, each bed's graph
|
|
1142
|
+
stays small, and at most one animal call lives per bed. Spots layer one
|
|
1143
|
+
bed at a lower level: the nearest actor carrying any named component,
|
|
1144
|
+
full within 4 m and falling linearly to silence at 14 m. Spots play no
|
|
1145
|
+
music.
|
|
1146
|
+
|
|
1147
|
+
Stadium, market (including spots) and harbour beds render once per page
|
|
1148
|
+
context offline from the same seeded generators into seamless 40/60/48 s
|
|
1149
|
+
loops, so phones play one buffer instead of the live graph; music stays
|
|
1150
|
+
live. Beds stay silent until ready and fade in, with the original live
|
|
1151
|
+
generator as fallback when offline rendering is unavailable or fails.
|
|
1152
|
+
After activation while sound is allowed, only referenced heavy beds
|
|
1153
|
+
prewarm one at a time with the current zone first, scheduling each
|
|
1154
|
+
complete seeded plan before offline rendering without suspends.
|
|
1155
|
+
Crowd and market use 24 kHz; harbour retains the live context's sample
|
|
1156
|
+
rate to preserve wash RMS, using about 8.5/9.2 MB of mono loop memory at
|
|
1157
|
+
44.1/48 kHz (8.1/8.8 MiB).
|
|
1158
|
+
|
|
1159
|
+
`music: true` selects original built-in music (v1.50 rounds 2–3):
|
|
1160
|
+
|
|
1161
|
+
| Zone | Songs | Music nodes |
|
|
1162
|
+
| --- | --- | --- |
|
|
1163
|
+
| `square` | Stroll (SQUARE_A, 116 BPM, G major) / Bounce (SQUARE_B, 126 BPM, D major) | 37 / 42 |
|
|
1164
|
+
| `meadow` | Garden walk (SUNNY_A, 112 BPM, C major) / Meadow jig (SUNNY_B, 92 dotted beats/min, F major, 6/8) | 37 / 27 |
|
|
1165
|
+
| `night` | Original D3 minor-pentatonic sine notes, 1.8 s apart, with warm pad A / breathing pad B | 11 / 15 for pads, plus two shared sine/envelope nodes |
|
|
1166
|
+
| `harbour` | Drift (HARBOUR_B, 100 BPM, G major pentatonic, 3/4) / Harbour jig (HARBOUR_C, 76 dotted beats/min, C mixolydian, 6/8) | 37 / 37 |
|
|
1167
|
+
| `crowd` | Victory lap (STADIUM_1, 126 BPM, G mixolydian) / Arena bounce (STADIUM_3, 132 BPM, A mixolydian) | 38 / 35 |
|
|
1168
|
+
| `market` | Original seeded triangle melody, at the common music target | 2 |
|
|
1169
|
+
|
|
1170
|
+
Square, meadow, night, harbour and stadium alternate their two songs.
|
|
1171
|
+
The session seed chooses the first; each runs for 3–5 minutes in whole bars, reaches silence exactly
|
|
1172
|
+
on a boundary with a 25 ms exit ramp, waits 4–8 seconds, then changes.
|
|
1173
|
+
Crossing zones uses the same bed fade; a returning bed restarts its
|
|
1174
|
+
seeded song. The notes, track
|
|
1175
|
+
timbres, envelopes and tempos are the chosen audition generators'.
|
|
1176
|
+
Hollow retains its original bassy sine and adds a pad 3 dB below it.
|
|
1177
|
+
New tonal voices use shared band-limited PeriodicWaves or sines. Both
|
|
1178
|
+
A/B pools are built with the bed, so alternation makes no nodes; frames
|
|
1179
|
+
only automate parameters, looking 0.3 s ahead (the old night sine remains
|
|
1180
|
+
at most one bar ahead). Inactive pools are silent, and both stop and
|
|
1181
|
+
disconnect when the bed fades out or the soundscape quiets. Market keeps
|
|
1182
|
+
its original seeded melody, root and triangle, at the common music target.
|
|
1183
|
+
|
|
1184
|
+
Harbour A-rolled uses two alternating wash channels and fixed sea, gull
|
|
1185
|
+
and creak voices. Two shared 3.5 kHz low-passes (Q 0) roll off the wash
|
|
1186
|
+
paths; foam is high-passed at 1.6 kHz. Both channels use identical gains.
|
|
1187
|
+
The random size draw stays 0.6–1 and opens the filter as before, with
|
|
1188
|
+
the same RNG sequence. Only size-dependent body/foam amplitudes use
|
|
1189
|
+
`0.6 + (size - 0.6) * 0.25` (0.6–0.7), retaining envelope timing and shape.
|
|
1190
|
+
Sea, gull and creak bypass the wash roll-off.
|
|
1191
|
+
The whole generator is calibrated to the original −41 dBFS bed target
|
|
1192
|
+
before the ambience bus raises it 8 dB to about −33 dBFS, using
|
|
1193
|
+
the audition's active-RMS rule (2048-sample windows within 20 dB of the
|
|
1194
|
+
loudest). A 300 s pure-JS offline model compares the previous and
|
|
1195
|
+
compressed graphs; the previous unit RMS of 0.08952332884 anchors the
|
|
1196
|
+
absolute level. Whole-bed gain rises from 0.316048 to 0.367716
|
|
1197
|
+
(+1.315 dB) to preserve model RMS, pending a measured correction.
|
|
1198
|
+
`HARBOUR_WAVE_RMS` retains the calibration, checked
|
|
1199
|
+
by `scripts/soundscape-wave-analysis.mjs` through the soundscape tests.
|
|
1200
|
+
|
|
1201
|
+
The stadium source generator retains all 12 voices and eight clappers,
|
|
1202
|
+
87 fixed generator nodes. The live market fallback alternates A/B in
|
|
1203
|
+
seeded 3–5 minute runs, letting reserved
|
|
1204
|
+
lines end before changing the four/five speakers and distance filter.
|
|
1205
|
+
Its consonants, vowel formants, pitches, pacing and envelopes are the
|
|
1206
|
+
audition's, using two reusable 19-node Simlish graphs and three damped
|
|
1207
|
+
room delays. Oscillator/noise phase continues between pooled lines;
|
|
1208
|
+
each line's envelope closes fully. Zone and spot use the same generator;
|
|
1209
|
+
spots retain the 0.45 mix and no music. Once ready, frames allocate no
|
|
1210
|
+
audio nodes.
|
|
1211
|
+
|
|
1212
|
+
| Zone | Bed nodes without / with music |
|
|
1213
|
+
| --- | --- |
|
|
1214
|
+
| `square` | 7 / 87 |
|
|
1215
|
+
| `meadow` | 7 / 72 (plus two during a bird call) |
|
|
1216
|
+
| `night` | 7 / 36 (plus two during an owl call) |
|
|
1217
|
+
| `harbour` | 4 / 79 (live fallback: 24 / 99) |
|
|
1218
|
+
| `crowd` | 4 / 78 (live fallback: 89 / 163) |
|
|
1219
|
+
| `market` | 4 / 7; a market spot adds 4 (live fallback: 54 / 57; spot adds 55) |
|
|
1220
|
+
|
|
1221
|
+
Counts are for ready beds, include mix/air and, with music, its duck gain
|
|
1222
|
+
and both pools;
|
|
1223
|
+
the shared master/buses are separate. All sources, pooled voices and
|
|
1224
|
+
delay loops stop and disconnect on fade-out, hidden tab, trip, mute or
|
|
1225
|
+
disposal. Missed frames drop past calls. No timers or audio files are used.
|
|
1226
|
+
An audibly playing loop from this client's `hub.sound` takes priority:
|
|
1227
|
+
music ducks to zero and ambience to about 35% over 0.6 s, then restores
|
|
1228
|
+
when the loop stops or becomes quiet by distance. Priority uses the loop's
|
|
1229
|
+
place volume times distance falloff, before user volume: it enters at
|
|
1230
|
+
0.06 or above and leaves at 0.03 or below, keeping its state between those
|
|
1231
|
+
levels so walking at the edge does not switch it back and forth. One-shots do not
|
|
1232
|
+
duck. Everything goes through the existing ambience bus and master.
|
|
1233
|
+
At default user volume 0.7, all six zone beds target about −33 dBFS
|
|
1234
|
+
active RMS (up 8 dB, about 8 dB under a footstep). Music rises 9 dB from
|
|
1235
|
+
its old −47 dBFS calibration target, sitting roughly level with the beds,
|
|
1236
|
+
including stadium and the original market melody.
|
|
1237
|
+
`AMBIENCE_LEVELS` in `code/client/soundscapeAmbience.js` holds the gains
|
|
1238
|
+
and intended pre-bus music RMS; `SONG_RMS` normalises the selected
|
|
1239
|
+
generators from retained audition PCM and the pads' harmonic/filter
|
|
1240
|
+
model. The opt-in master compressor protects the sum with babble and
|
|
1241
|
+
footsteps. Night's 4.1 kHz cricket pulses remain removed, with wind/owl.
|
|
1242
|
+
|
|
1243
|
+
For example, the deck's `hub` block may contain:
|
|
1244
|
+
|
|
1245
|
+
```json
|
|
1246
|
+
"soundscape": {
|
|
1247
|
+
"ui": true,
|
|
1248
|
+
"zones": "TownDistrict",
|
|
1249
|
+
"ambience": {
|
|
1250
|
+
"beds": { "district-sunny": "meadow", "district-harbour": "harbour" },
|
|
1251
|
+
"default": "square",
|
|
1252
|
+
"spots": { "TownStamp": "market", "TownHats": "market" },
|
|
1253
|
+
"music": true
|
|
1254
|
+
},
|
|
1255
|
+
"steps": {
|
|
1256
|
+
"default": "street",
|
|
1257
|
+
"zones": { "district-sunny": "grass", "district-harbour": "wood" },
|
|
1258
|
+
"paths": "TownAlley"
|
|
1259
|
+
}
|
|
1260
|
+
}
|
|
1261
|
+
```
|
|
1262
|
+
|
|
1263
|
+
- **UI cues** (`ui`, v1.49, only explicit `true`; absent or `false` means
|
|
1264
|
+
none). Quiet original one-shots through the UI bus: a 120 ms rising noise
|
|
1265
|
+
whoosh when this player's door trip starts, a 320 ms two-note chime on
|
|
1266
|
+
their arrival or return to town, a 180 ms rising tone when their private
|
|
1267
|
+
town HUD timer starts or changes, and a 65 ms tick for a quick reaction,
|
|
1268
|
+
phrase, emote, talk reply chip or Doors list Go. The departure starts
|
|
1269
|
+
before the trip gate and alone may finish into the trip; sound never
|
|
1270
|
+
delays or changes the trip. No other cue starts during it. Hiding the
|
|
1271
|
+
page, muting or setting volume to zero stops even that tail immediately.
|
|
1272
|
+
Arrival alone waits for the first settled live frame, and is dropped if
|
|
1273
|
+
more than 3 s late or interrupted. Before the first gesture it is dropped.
|
|
1274
|
+
Other cues never wait. Two UI voices at most and four starts per rolling
|
|
1275
|
+
second; extras are dropped, and ended graphs are stopped and disconnected.
|
|
1276
|
+
Each cue uses two nodes, or three for the noise whoosh; idle frames
|
|
1277
|
+
allocate no nodes. `soundscape: true` does not enable any UI cue.
|
|
1278
|
+
|
|
1279
|
+
Activity uses only the existing private HUD's finite `timer.since` or
|
|
1280
|
+
`timer.until` (§9), such as the town trial clock. The first frame's timer
|
|
1281
|
+
state is a baseline; shared HUDs and game clocks are ignored, and timers received
|
|
1282
|
+
while quiet are consumed without replay. A hold does not identify an
|
|
1283
|
+
activity, so stall and cabinet holds make no activity cue. Town token
|
|
1284
|
+
balances reach the client only as authored HUD text, so UI does not infer
|
|
1285
|
+
a token cue; a place may explicitly send `hub.cue({ player }, 'token')`.
|
|
1286
|
+
UI cues parse no text and add no message or snapshot field.
|
|
1287
|
+
|
|
1288
|
+
- **Named cues and observed actions** (`cues`, v1.50, v1.60, only explicit `true`).
|
|
1289
|
+
A place calls `hub.cue({ player: playerId }, name)` for that player alone,
|
|
1290
|
+
or `hub.cue({ actor: actorId, radius: 12 }, name)` for everyone near that
|
|
1291
|
+
scene actor (spawned copies included), fading linearly to silence at the
|
|
1292
|
+
radius (1–60 m, default 12). It returns true when sent, or false with a
|
|
1293
|
+
warning logged once for a disabled deck, unknown name, invalid target,
|
|
1294
|
+
disconnected player, invalid radius or spent budget. Private targets each
|
|
1295
|
+
have a six-token bucket replenished at six per second; actor broadcasts
|
|
1296
|
+
share one bucket per place. No sound file or `idle.sounds` declaration is
|
|
1297
|
+
needed. Names are the closed, exported `CUE_NAMES` list:
|
|
1298
|
+
|
|
1299
|
+
`kick`, `goal`, `cast`, `nibble`, `bite`, `catch`, `token`, `hat-bought`,
|
|
1300
|
+
`hat-on`, `lantern`, `stamp`, `trial-start`, `trial-gate`, `trial-finish`,
|
|
1301
|
+
`pad-tick`, `pad-go`, `court-chime`, `court-bell`, `court-splash`,
|
|
1302
|
+
`court-flutter`, `busker-jig`, `busker-waltz`.
|
|
1303
|
+
|
|
1304
|
+
Court voices are chime A (one stone per call, fixed stone 0 at 587.33 Hz),
|
|
1305
|
+
brass bell A (its full 2.6 s ring), fountain splash A and flutter B.
|
|
1306
|
+
There is no pitch-step argument or new API. Their pitches, envelopes,
|
|
1307
|
+
noise seed and offsets are retained in `code/client/soundscapeCourt.js`.
|
|
1308
|
+
They use the same delivery, falloff, caps, gates and cleanup as other cues.
|
|
1309
|
+
|
|
1310
|
+
**Busker tunes (v1.60).** A place sends
|
|
1311
|
+
`hub.cue({ actor: buskerId, radius }, "busker-jig")` (or `"busker-waltz"`)
|
|
1312
|
+
and re-sends it every 10 s or less while the busker should play. Each client
|
|
1313
|
+
that receives it loops that tune positioned at that actor while the local
|
|
1314
|
+
player is within radius of the actor (the same linear `distanceGain` as
|
|
1315
|
+
`soundscapeActions.js`), the actor exists and is not hidden, sound is live,
|
|
1316
|
+
and less than 25 s have passed since the last send for that actor. This is
|
|
1317
|
+
a lease: when the place stops re-sending, the loop fades out; a late joiner
|
|
1318
|
+
starts on the next re-send. Leaving the radius fades it out; coming back
|
|
1319
|
+
while the lease holds resumes it (restarting the phrase is fine). At most
|
|
1320
|
+
ONE busker loop plays per client: the loudest (nearest) one; a second actor
|
|
1321
|
+
or a name change switches with a short fade (about 0.3 s). A `{ player }`
|
|
1322
|
+
target with a busker name plays one pass of the tune to that player at full
|
|
1323
|
+
gain, no loop, also through the busker layer.
|
|
1324
|
+
|
|
1325
|
+
`code/client/soundscapeBusker.js` synthesises two original 8–12 s
|
|
1326
|
+
placeholder melodies: a lively 6/8 pluck jig and a gentle 3/4 waltz with
|
|
1327
|
+
quiet root/fifth bass on beat one. Each phrase player uses four pooled
|
|
1328
|
+
oscillators and gains, one 3 kHz low-pass and one distance gain: ten nodes
|
|
1329
|
+
for its entire life, no allocation per note. The frame clock schedules
|
|
1330
|
+
at most 0.3 s ahead and skips missed notes after a stall; exact beat-length
|
|
1331
|
+
phrases loop seamlessly. The separate layer uses the existing UI bus and
|
|
1332
|
+
master without the short cues' 3 s or two-voice cap; neither layer evicts
|
|
1333
|
+
the other. One private phrase slot is bounded independently. Fade completion,
|
|
1334
|
+
teardown, hide and scene change stop and disconnect every node. All cue
|
|
1335
|
+
opt-in, sound gates and volume rules apply; without `soundscape.cues: true`
|
|
1336
|
+
no busker layer is made or driven. The exported `BUSKER_LEVEL` targets
|
|
1337
|
+
about −40 dBFS active RMS at the actor at volume 0.7 (about 7 dB under the
|
|
1338
|
+
beds), pending calibration in Chromium.
|
|
1339
|
+
|
|
1340
|
+
The chosen original audition voices are in frozen `CUE_VOICES` in
|
|
1341
|
+
`code/client/soundscapeCues.js`: kick A, catch C and the chosen single
|
|
1342
|
+
voices for the other short names. The wire is `{ k: 'hub-cue', cue: name }`,
|
|
1343
|
+
with `actor` and `radius` only for broadcasts. The client queues at most
|
|
1344
|
+
eight events when enabled and live. Missing voices, malformed, distant or
|
|
1345
|
+
quiet events are dropped. Parts keep the audition's pitches, envelopes,
|
|
1346
|
+
noise seed and scheduled times, and are built 75 ms ahead by the frame;
|
|
1347
|
+
ended sources stop and all nodes disconnect. A stalled frame drops missed
|
|
1348
|
+
parts instead of starting them late.
|
|
1349
|
+
|
|
1350
|
+
The same opt-in also voices existing client state changes: wave B,
|
|
1351
|
+
dance C, cheer, bow and spin emotes, sitting, and this player's NPC talk
|
|
1352
|
+
panel opening. The local player's emote and sit play at full cue level;
|
|
1353
|
+
another player's falls off to zero at 12 m. Initial state is a silent
|
|
1354
|
+
baseline, and repeated, expired, distant or blocked state never replays.
|
|
1355
|
+
Client observation adds no messages or snapshot fields and parses no text.
|
|
1356
|
+
There is no structured pad countdown or departure state on this client,
|
|
1357
|
+
so pads use explicit `hub.cue` calls rather than guessed label text.
|
|
1358
|
+
|
|
1359
|
+
Short cues use the existing UI bus and master, sharing `ui`'s cap of two voices
|
|
1360
|
+
and four starts in any rolling second. Local cues take priority over
|
|
1361
|
+
nearby players and actor broadcasts; they may replace a lower-priority
|
|
1362
|
+
voice, and extra starts are dropped. First gesture, settling, trip,
|
|
1363
|
+
hidden tab, mute and volume apply to every cue; only the legacy UI door
|
|
1364
|
+
departure tail may finish into a trip. `ui` and `cues` are separate flags:
|
|
1365
|
+
cues alone adds no chip callback or legacy timer cue, and `soundscape:
|
|
1366
|
+
true` enables neither. Without `cues` no action observer is made.
|
|
1367
|
+
|
|
1368
|
+
- **The control.** A speaker button in the right column, below the reserved native camera
|
|
1369
|
+
corner, opens Mute and a
|
|
1370
|
+
volume slider, kept on the device (`localStorage`
|
|
1371
|
+
`castle.hub.soundscape.v1`). It sets the level of everything above and of
|
|
1372
|
+
the place's own sounds (`hub.sound`, v1.6), which without the key play at
|
|
1373
|
+
the volume the place gave them.
|
|
1374
|
+
|
|
1375
|
+
Nothing sounds before the player's first tap or key, and nothing waits for
|
|
1376
|
+
it: a sound that could not play when it happened is dropped, and a line that
|
|
1377
|
+
came up meanwhile is never said late. In such a deck that holds for the
|
|
1378
|
+
place's own `hub.sound` files too: none is started before the gesture (a
|
|
1379
|
+
one-shot before it is dropped; a loop starts after it, where everyone else is
|
|
1380
|
+
in it), where without the key the engine starts a waiting loop on the first
|
|
1381
|
+
tap as it always has. During a trip through a door only the already-started
|
|
1382
|
+
UI departure tail may finish; everything is silent while the page is hidden,
|
|
1383
|
+
and a line that arrived then is not said on return.
|
|
1384
|
+
Ambience and music follow the same first-gesture, trip, hidden-tab, mute and
|
|
1385
|
+
volume rules. An interruption stops their sources and scheduled notes;
|
|
1386
|
+
returning waits for two consecutive completed live frames before beds start
|
|
1387
|
+
again. No bed or animal voice is built before the gesture or while blocked.
|
|
1388
|
+
|
|
646
1389
|
**Quick reactions and phrases (v1.11).** In every hub place the chrome has a
|
|
647
1390
|
speech button (💬, bottom right, above the emote button) that opens a row of
|
|
648
1391
|
emoji (👍 😂 ❤️ 😮 👋 🎉) over the place's canned phrases: in a town "Over
|
|
@@ -660,7 +1403,15 @@ here!" from a party member or a friend puts the pointer (§5) on them for
|
|
|
660
1403
|
10 s, and a "Let's play" that names a door is offered to everyone who heard it
|
|
661
1404
|
as a question for 20 s ("bo: let's play Tile Fall": Go / Not now), Go being a
|
|
662
1405
|
jump to that door's pad. This is for everyone, guests included; nothing a player types is
|
|
663
|
-
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.
|
|
664
1415
|
|
|
665
1416
|
**Free-text chat (v1.12).** Two players may type to each other only when
|
|
666
1417
|
they follow each other on Castle and both are over 13; a guest, or a player
|
|
@@ -680,6 +1431,118 @@ like a phrase: over its speaker for 6 s and in the feed; a tap on another
|
|
|
680
1431
|
player's line in the feed offers Report (`Hub.reportChat`). What was said
|
|
681
1432
|
before a player arrived is not shown to them. On a host or SDK without the
|
|
682
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.
|
|
1436
|
+
|
|
1437
|
+
**The choice card (v1.68).** A place whose manifest declares `ballot` (§1)
|
|
1438
|
+
may put a card of players' faces in front of its players -- a meeting, a vote,
|
|
1439
|
+
a reveal -- with `hub.ballot` (§4). Two rules hold on every path, client and
|
|
1440
|
+
server (`code/server/ballot.js` states them at its top):
|
|
1441
|
+
|
|
1442
|
+
- **(A) The version rule.** Each player's card has a version `v`, an
|
|
1443
|
+
opaque string: this server's own epoch (its start time and a random part)
|
|
1444
|
+
and a counter, so a version from an earlier server for the same layer (a
|
|
1445
|
+
replacement restarts its counter) never equals one of this server's. The
|
|
1446
|
+
client echoes it as it came and never compares or computes with it beyond
|
|
1447
|
+
equality. A `hub.ballot` call gives a player's card a new version exactly
|
|
1448
|
+
when it changes what that player can tap, compared with
|
|
1449
|
+
the card they have now: the mode, the faces offered and which are `off`,
|
|
1450
|
+
the lines offered, the option ids, or `picked`. A call that changes only
|
|
1451
|
+
the title, text, `until`, notes, votes, marks, option words or the feed
|
|
1452
|
+
keeps the version, so a game that refreshes its feed as lines are said
|
|
1453
|
+
never refuses a tap made meanwhile. Clearing a player's own card is such a
|
|
1454
|
+
call too: back on the shared card, they keep their version if it allows the
|
|
1455
|
+
same taps as the card they had, and get a new one otherwise. A tap carries the `v` of the card it
|
|
1456
|
+
was made on, and is taken only if that `v` is the version last delivered
|
|
1457
|
+
to the player AND the version of their current card, and its ids are on
|
|
1458
|
+
that card and allowed by it. The same version allows the same taps, so a
|
|
1459
|
+
card whose taps changed since, or not yet delivered, has another version,
|
|
1460
|
+
and a lock the hook just set holds at once. The client starts its
|
|
1461
|
+
selection afresh on a new version.
|
|
1462
|
+
- **(B) Keys absent means no ballot code path runs at all**: no allocation,
|
|
1463
|
+
no per-frame call, no disposal work, no listener, client or server. A
|
|
1464
|
+
place without `ballot` only reads the key and finds it missing; a deck
|
|
1465
|
+
that declares it in none of its places has no `hub.ballot`. On the
|
|
1466
|
+
client everything enters through one gate, the `hub-ballot-card` message:
|
|
1467
|
+
while the place is not yet known (the server's first tick sends a card
|
|
1468
|
+
ahead of the WORLD snapshot) one card is held; in a place known to be
|
|
1469
|
+
keyless the card is dropped before anything is made; otherwise it is held
|
|
1470
|
+
with its connection. While a card is held, every WORLD snapshot rechecks
|
|
1471
|
+
it: one naming a place without `ballot` lets it go, pending or not (a
|
|
1472
|
+
recovery that keeps the connection but lands somewhere keyless). Nothing
|
|
1473
|
+
else on the client touches the card until the gate holds one, and the hub
|
|
1474
|
+
system reads the gate again after letting go of another connection's card,
|
|
1475
|
+
before it makes or draws anything.
|
|
1476
|
+
|
|
1477
|
+
The kit draws it as a bottom sheet over
|
|
1478
|
+
the world (the world stays in view above it; up to 60% of the view's height,
|
|
1479
|
+
which an ordinary HUD never reaches, and under a clear HUD's box, scrolling
|
|
1480
|
+
inside itself): the title, a countdown to `until`, the
|
|
1481
|
+
text, the last of the card's `feed` lines, a grid of faces (each player's
|
|
1482
|
+
avatar face and username, "You" for the viewer, the deck's `note` under it,
|
|
1483
|
+
greyed when `off`, a tally when `votes` is set, a dot and border in `mark`),
|
|
1484
|
+
and chips for the offered lines and the options. Phone first: chips at least
|
|
1485
|
+
40 px tall, text at least 15 px (the ✓ on a picked face is a mark, not text), white on dark; a phone on its side puts the
|
|
1486
|
+
faces left and the chips right, each scrolling alone. While a card is up the
|
|
1487
|
+
chrome it would cover waits (the emote, Sit, speech and Character buttons,
|
|
1488
|
+
the Doors and People dock and the said-lines feed); a place without the key
|
|
1489
|
+
is drawn exactly as before.
|
|
1490
|
+
|
|
1491
|
+
- **Talk** (`mode: "talk"`): a tap on a face selects it (a ring), and the
|
|
1492
|
+
`face` lines are offered only then; a tap on one sends `{ face, line }`. A
|
|
1493
|
+
`self` line sends `{ line }` at once; an option sends `{ option }` at once.
|
|
1494
|
+
- **Vote**: a tap on a face or an option selects it, and a Vote button sends
|
|
1495
|
+
`{ face }` or `{ option }`. Once the place sets `picked` for that player the
|
|
1496
|
+
card shows it locked in and takes no more votes -- from the moment
|
|
1497
|
+
`hub.ballot` is called, so a vote replayed before the next tick is refused
|
|
1498
|
+
too.
|
|
1499
|
+
- **Reveal**: read only (the tallies, who it was).
|
|
1500
|
+
|
|
1501
|
+
A tap is `{ k: 'hub-ballot', v, face?, line?, option? }` and nothing else.
|
|
1502
|
+
By rule A the server takes it only on the version delivered and current, and
|
|
1503
|
+
checks its ids against that card (another version, no card, a
|
|
1504
|
+
reveal, an unknown or `off` face, a line not offered now, a `face` line
|
|
1505
|
+
without a face or a `self` line with one, a line in a vote, a vote once
|
|
1506
|
+
`picked`, an option the card has not, any other key: dropped without a word),
|
|
1507
|
+
limits a player to a burst of three and then one every 1.5 s (as quick
|
|
1508
|
+
phrases are), and hands it to the place's `ballot` hook. The kit says nothing
|
|
1509
|
+
for the place: what was said reaches others only through the `feed` the
|
|
1510
|
+
place puts on its next card, and votes are counted by the place.
|
|
1511
|
+
|
|
1512
|
+
**No free text:** a player cannot put a word of their own on the card. A tap
|
|
1513
|
+
carries ids only, and every word the card shows is the deck's (its manifest's
|
|
1514
|
+
lines, its server's title, text, notes and options -- never a player's) or
|
|
1515
|
+
the kit's (usernames, "You", "Vote for amy", "Locked in"). Feed lines are
|
|
1516
|
+
worded on each client from ids: "bo → amy: I saw them by the boat", "bo: Not
|
|
1517
|
+
me!". A deck must never pass anything a player typed into `title`, `text`,
|
|
1518
|
+
`note` or an option.
|
|
1519
|
+
|
|
1520
|
+
Names and faces are the kit's: the card names a face by player id, and the
|
|
1521
|
+
server adds that player's username and avatar from the session. Each
|
|
1522
|
+
player's card is a pure function of the card and of who is connected now,
|
|
1523
|
+
worked out again on every send: a face, or a feed row from or to a player
|
|
1524
|
+
who is not here now, is left off for every viewer, and nothing about a
|
|
1525
|
+
player is remembered once they leave. A block (§12, "Blocks") holds: a player a block hides from
|
|
1526
|
+
the viewer is not on their card (no face, no feed row from or to them), and
|
|
1527
|
+
their name is taken out of every word the card shows them: the title, text,
|
|
1528
|
+
notes and options, and the manifest's lines too (in the chips and the feed:
|
|
1529
|
+
"cy: someone did it" for a line "bo did it"; the server sends the redacted
|
|
1530
|
+
words of those lines in the card's `words`). A lock (`picked`) on a face the
|
|
1531
|
+
viewer is not shown -- one a block hides, or a player gone -- stays a lock
|
|
1532
|
+
and names nobody: `picked: {}`, drawn "Locked in ✓". Blocks are the
|
|
1533
|
+
session's pairs among the players here (`session.hub.hiddenPair` says
|
|
1534
|
+
nothing about a player who has left), so name redaction covers players
|
|
1535
|
+
present now: a departed player's name in the deck's own words (title, text,
|
|
1536
|
+
notes, options, or a manifest line that happens to contain it) is not
|
|
1537
|
+
redacted -- the same limit the HUD and labels have. Their rows and face are
|
|
1538
|
+
gone for every viewer by then. Each player is sent their own
|
|
1539
|
+
whole card privately when it changes (`hub-ballot-card`, §12) and again after
|
|
1540
|
+
a fresh join; a leaving player's own card goes with them, and so does
|
|
1541
|
+
anything kept for a connection that left before saying hello. A deck that
|
|
1542
|
+
declares `ballot` in none of its places has no `hub.ballot` (the member is
|
|
1543
|
+
absent; in a deck that declares it elsewhere, a place without it is refused
|
|
1544
|
+
as above). Ids are looked up as own properties only (`who`, `words`), so an
|
|
1545
|
+
id such as `constructor` names nothing it should not.
|
|
683
1546
|
|
|
684
1547
|
**Player contact is not in v1.** Other players are kinematic capsules on every
|
|
685
1548
|
client, so nobody can be shoved (M0 gap 4). That is an engine rule, not a
|
|
@@ -758,6 +1621,79 @@ hub.setHud({ text: 'you are it!' }, playerId); // one player's override; null c
|
|
|
758
1621
|
Longer strings are cut, other keys dropped. A per-player spec replaces the
|
|
759
1622
|
shared one for that player.
|
|
760
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
|
+
|
|
761
1697
|
**A clear HUD (v1.26).** The HUD hangs from the top middle of the screen, and
|
|
762
1698
|
on a phone that is where much of what the hub draws over the world lands too:
|
|
763
1699
|
with a title, a 56 px big line and a text line the box is over 100 px tall, the
|
|
@@ -786,11 +1722,15 @@ speech bubble near the top is drawn across it. A place whose manifest sets
|
|
|
786
1722
|
the HUD is left over its top. Two things moved under it may overlap each
|
|
787
1723
|
other. While no HUD is drawn nothing moves.
|
|
788
1724
|
- **A short view.** On a view 480 px tall or less that is wider than it is
|
|
789
|
-
tall (a phone on its side) the
|
|
790
|
-
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
|
|
791
1726
|
short, however small (the web player's card on a 360 px phone is about
|
|
792
1727
|
475 px tall).
|
|
793
1728
|
|
|
1729
|
+
A choice card (v1.68, §6) takes at most 60% of the view's height, below where
|
|
1730
|
+
an ordinary HUD ends; under a clear HUD its height is also kept to the room
|
|
1731
|
+
below the HUD's measured box (never under 160 px), so the HUD stays in view
|
|
1732
|
+
over it.
|
|
1733
|
+
|
|
794
1734
|
The option is the place's: a game behind a town's door is drawn by the town's
|
|
795
1735
|
client, which is told by the game's server (`hubPlace.hud`), so the game's own
|
|
796
1736
|
manifest decides either way it is opened, and the town's own HUD is not
|
|
@@ -798,6 +1738,295 @@ changed by a game that asks. A town running a kit older than v1.26 draws the
|
|
|
798
1738
|
game as before. Fixed chrome (the Back button, an invitation card, the
|
|
799
1739
|
buttons) is not moved.
|
|
800
1740
|
|
|
1741
|
+
### Action chips (v1.74)
|
|
1742
|
+
|
|
1743
|
+
A place with `actions: true` may offer each player up to three buttons with
|
|
1744
|
+
`hub.actions(playerId, [{ id: 'start', label: 'Start' }])`. They stack upward
|
|
1745
|
+
at the bottom-right, with targets at least 44 px tall, above Character, Grab,
|
|
1746
|
+
emotes, speech and the decor button. When that column is full, they move left
|
|
1747
|
+
of the measured left edges of the round-control column, with a 12 px gap,
|
|
1748
|
+
above any controls sharing the new span. Sound and its open card,
|
|
1749
|
+
the HUD, the ask card and Back are upper bounds; other controls sharing the
|
|
1750
|
+
chips' column push the stack up wherever they sit in the view. Chips keep
|
|
1751
|
+
12 px view margins and gaps above controls, and trim from the top when the
|
|
1752
|
+
second position is full, retrying both positions after each trim and preserving
|
|
1753
|
+
the first (bottom) chip whenever it fits.
|
|
1754
|
+
They yield to open panels, decorating, the choice card and travel.
|
|
1755
|
+
Pointer presses do not focus chips; clicks blur them, and
|
|
1756
|
+
a chip focused by other means contains its keydown/keyup events. Identical
|
|
1757
|
+
received items and `n` keep the existing buttons.
|
|
1758
|
+
|
|
1759
|
+
A tap sends `{ k: 'hub-action', id, n }`. It reaches `action` only if `n` is a
|
|
1760
|
+
safe integer equal to that player's current offer version **and** `id` is in
|
|
1761
|
+
that current list, and that offer is the one the player was last sent (a list
|
|
1762
|
+
recorded and not yet sent cannot be pressed). An id reused by a changed offer
|
|
1763
|
+
cannot take a stale press.
|
|
1764
|
+
Async hooks are neither serialised nor cancelled when the player leaves.
|
|
1765
|
+
|
|
1766
|
+
`hub.actions` records, rather than sends, the newest list. Each change from
|
|
1767
|
+
the last recorded list takes a new version, including clearing to null, from
|
|
1768
|
+
one counter for the place's session (no offer shares a version with an
|
|
1769
|
+
earlier one, whoever it was for); a list changed back to the one the player
|
|
1770
|
+
was last sent, with nothing sent between, keeps that offer's version, so what
|
|
1771
|
+
the player sees can always be pressed. The tick sends at most four ordinary offers a second per player,
|
|
1772
|
+
250 ms apart, and sends nothing when the last-sent items equal the current
|
|
1773
|
+
items. Intermediate recordings still advance `n` even when the final list
|
|
1774
|
+
returns to the last-sent list; earlier presses remain superseded. A fresh
|
|
1775
|
+
hello immediately replays the current offer once with its current `n`, and
|
|
1776
|
+
is an exception to the ordinary delivery budget. Offers are private, never
|
|
1777
|
+
snapshot state. Before WORLD the client buffers an offer but draws nothing
|
|
1778
|
+
until the place is known to opt in; a keyless WORLD drops it. The client
|
|
1779
|
+
drops its chips when reconnect re-hello marks private state stale; the server
|
|
1780
|
+
restores its current offer.
|
|
1781
|
+
|
|
1782
|
+
An action the player chooses is a button (hub.actions); standing somewhere only moves the player. Stand-on pads stay for go doors and race starts.
|
|
1783
|
+
|
|
1784
|
+
### The companion (v1.71, dress and pose v1.78)
|
|
1785
|
+
|
|
1786
|
+
A place with `companion: true` may give each arrived player a floating
|
|
1787
|
+
companion with `hub.companion(playerId, { look: 'lantern', say: 'Follow me',
|
|
1788
|
+
at: 'gate' })`. The whole spec is private to its owner. **The place authors
|
|
1789
|
+
every line; nothing a player typed may be passed to `say`. The line is never
|
|
1790
|
+
shown to anyone else.** With the object manifest form, the existing NPC talk protocol also opens a private chat (§13).
|
|
1791
|
+
|
|
1792
|
+
The lantern or folded paper bird floats 0.55 m right and 0.35 m behind the
|
|
1793
|
+
player, or 0.9 m toward the target actor, 1.45 m above the feet (the avatar
|
|
1794
|
+
origin is 0.7 m above its feet, as for wearables). It bobs 0.06 m at 0.5 Hz,
|
|
1795
|
+
eases with a 0.25 s time constant and snaps when over 6 m away. The bird
|
|
1796
|
+
faces its travel or pointing direction and flaps at about 2 Hz. After 1.5 s
|
|
1797
|
+
under 0.2 m/s with no point target it rests 0.28 m to the avatar's right,
|
|
1798
|
+
1.25 m over the feet, facing with the player, without bobbing, wings folded
|
|
1799
|
+
down at a fixed angle. Motion or a point target resumes flight. A changed
|
|
1800
|
+
version with `say` shows the owner's existing speech bubble for 3500 ms plus
|
|
1801
|
+
55 ms per code point, capped at 9000 ms; text only, no input or focus.
|
|
1802
|
+
The current line is shown again, once, when the owner's connection comes
|
|
1803
|
+
back or their frames stopped for ten seconds (a hidden page), whatever the
|
|
1804
|
+
version: a reconnect says it again. No wire change.
|
|
1805
|
+
Other players see only a tiny warm glow parented at the avatar's shoulder.
|
|
1806
|
+
The owner's public id draws no second glow. Bodies rebuilt or removed take
|
|
1807
|
+
their glows with them; travel hides both follower and glows.
|
|
1808
|
+
|
|
1809
|
+
v1.78 adds optional own `dress`, a plain object with only optional own
|
|
1810
|
+
`species`, `wear`, and `tint`. Species ids are `songbird` (the default),
|
|
1811
|
+
`owl`, `parrot`, and `hummingbird`; wear ids are `tophat`, `sunhat`, `bow`,
|
|
1812
|
+
`scarf`, `stampcap`, and `flowercrown`; tint ids are `rose`, `mint`,
|
|
1813
|
+
`midnight`, and `gold`. Wear and tint default to absent. Unknown keys or
|
|
1814
|
+
values throw; a lantern rejects any dress, even an empty one. An empty or
|
|
1815
|
+
all-default dress is omitted, preserving exactly the v1.71 spec bytes.
|
|
1816
|
+
|
|
1817
|
+
v1.78 also accepts optional own `pose: 'show'`, only for birds; every other
|
|
1818
|
+
value and any lantern pose throw. Absent pose preserves existing spec bytes.
|
|
1819
|
+
The show-off bird flies close to the camera, in front of the player. Its
|
|
1820
|
+
paper-and-wear projected box is centred at 27% of view width and 40% of view
|
|
1821
|
+
height on portrait phones (35% width and 45% height in landscape), with at
|
|
1822
|
+
least a 4% screen inset.
|
|
1823
|
+
In portrait the whole box stays left of the projected player centre by at
|
|
1824
|
+
least 2% of view width, including while the held pose springs to its target.
|
|
1825
|
+
Its built paper bounding-box height at normal scale seeds the distance; the
|
|
1826
|
+
transformed paper and worn vertices, including the hat anchor and wing flutter,
|
|
1827
|
+
then fit about 33% of the vertical view, reduced as needed for width clearance.
|
|
1828
|
+
At 412×870 with the town's 70-degree lens, the upright pose keeps at least 28%
|
|
1829
|
+
of the view height throughout its turn.
|
|
1830
|
+
The glow is excluded from fitting. Hats use each species' head dimensions and
|
|
1831
|
+
attachment point; a tophat is about one third of its body length tall, with a
|
|
1832
|
+
brim only a little wider than its head. Bow and scarf attach at the neck.
|
|
1833
|
+
These accessory proportions apply to the ordinary follow pose too.
|
|
1834
|
+
Framing uses the scene's active render lens, including the orbit lens and
|
|
1835
|
+
camera zoom, with camera near-plane clearance and room before the player.
|
|
1836
|
+
A normal-scale origin-centred bounding sphere includes the transformed geometry
|
|
1837
|
+
and worn item; the nearest model point stays at least `near + 0.15` away in
|
|
1838
|
+
camera depth. The show flight reaches its current camera target in 0.7 seconds
|
|
1839
|
+
regardless of starting distance, then holds with the short spring and enforces
|
|
1840
|
+
the whole box's screen inset. An extreme zoom with no room prioritises camera
|
|
1841
|
+
clearance. The model's up axis stays upright in the camera's view plane at any
|
|
1842
|
+
orbit elevation. The orientation uses the camera's world right/up/toward-camera
|
|
1843
|
+
basis, a shallow 8-degree turn about camera up, then a 30-degree tilt about
|
|
1844
|
+
camera right. A gentle four-second turn varies that side angle by ±2 degrees,
|
|
1845
|
+
with raised, lightly fluttering wings; the shallower turn keeps the bird large
|
|
1846
|
+
in the portrait slot. From the first approach frame it uses full normal
|
|
1847
|
+
scale, opaque paper and worn materials. The additive glow uses 20% of its normal opacity while showing,
|
|
1848
|
+
restored afterwards. Show suppresses leading, quieting, stamp twirls and
|
|
1849
|
+
temporary hat try-on while keeping the worn item visible. Clearing the pose
|
|
1850
|
+
flies back to normal follow.
|
|
1851
|
+
Dress and pose are owner-only, never in `hubGlow`, snapshots or deltas; the
|
|
1852
|
+
public glow remains presence only. The opted-in server API exposes
|
|
1853
|
+
`hub.companionDress === true` for dress and the separate
|
|
1854
|
+
`hub.companionPose === true` for pose. A kit with dress support may lack pose
|
|
1855
|
+
support; places must gate each field on its own capability. These server-only
|
|
1856
|
+
flags send no wire bytes.
|
|
1857
|
+
|
|
1858
|
+
Every species uses the same wing rig, head anchor, lead, perch, twirl and
|
|
1859
|
+
quiet-follow scaling/opacity. Hummingbird wings flutter faster. Tint paints
|
|
1860
|
+
the main body and wing paper, leaving glow, beak and eyes unchanged. A worn
|
|
1861
|
+
accessory hides during the temporary hat-stall try-on and returns afterwards.
|
|
1862
|
+
Changing dress disposes the old geometry and materials and rebuilds the bird.
|
|
1863
|
+
|
|
1864
|
+
These unlit primitives use no textures, lights or shadows: 30 triangles for
|
|
1865
|
+
the lantern, sixteen for the songbird, 40 for the owl, 31 for the parrot,
|
|
1866
|
+
30 for the hummingbird (including their glows), eight for a public glow. The paper bird is
|
|
1867
|
+
about 0.5 m across, with orange undersides (`#f2a65a`) for its folds and a soft glow behind it. They are nodes,
|
|
1868
|
+
never scene actors, so tier rules neither count nor cull them on Low.
|
|
1869
|
+
Private state arriving before WORLD is held until the place's opt-in is
|
|
1870
|
+
known; a keyless WORLD drops it. Reconnect re-hello drops stale private state
|
|
1871
|
+
and replays the current companion, including its line. Ordinary sends are
|
|
1872
|
+
250 ms apart per player; a fresh hello is an exception. A place without the
|
|
1873
|
+
key creates no companion state or drawer and keeps its existing wire bytes.
|
|
1874
|
+
|
|
1875
|
+
### Private text prompt (v1.75)
|
|
1876
|
+
|
|
1877
|
+
A place with `ask: true` may call
|
|
1878
|
+
`hub.ask(playerId, { id: 'pet-name', title: 'Only you will see this name', max: 16 })`.
|
|
1879
|
+
Only that player sees the card: its title, one single-line input, OK and Cancel.
|
|
1880
|
+
Enter submits; OK stays disabled unless the field passes the same text rules
|
|
1881
|
+
as the server. IME confirmation (including keyCode 229) does not submit. The
|
|
1882
|
+
card stays above the phone keyboard and suspends walking and orbit input
|
|
1883
|
+
while open. Sending closes it
|
|
1884
|
+
immediately, and the same `n` cannot reopen it. Null, a newer version,
|
|
1885
|
+
re-hello, leaving the place and scene teardown remove the card, wipe its field
|
|
1886
|
+
and release the input lock. Movement and look input are suppressed before
|
|
1887
|
+
player behaviors run, and a gesture shield keeps drags off the canvas.
|
|
1888
|
+
A pending prompt waits while a ballot card or NPC conversation is open; an
|
|
1889
|
+
NPC opening or ballot arriving while the prompt is open cancels it once,
|
|
1890
|
+
without taking focus back. A close or newer version replaces a pending
|
|
1891
|
+
prompt. A fresh hello can replay the current prompt.
|
|
1892
|
+
|
|
1893
|
+
An answer is `{ k: 'hub-menu-pick', id, n }` (v1.79, §9: exactly these keys; current and last-sent version, known item id or reserved `close`, six/s burst eight including dropped presses; readOnly allows close only);
|
|
1894
|
+
`{ k: 'hub-answer', id, n, text }`, with exactly those keys.
|
|
1895
|
+
It is accepted only from the arrived, connected player whose last-sent prompt
|
|
1896
|
+
has that id, with a safe-integer `n` equal to both the sent and current
|
|
1897
|
+
versions. A changed, closed or recorded-but-unsent prompt cannot be answered.
|
|
1898
|
+
Cancel is `text: null`. A string is first bounded cheaply to `4 * max` UTF-16
|
|
1899
|
+
units, then checked for 1..max code points, not whitespace-only, and no control,
|
|
1900
|
+
Bidi_Control or zero-width characters. The kit never trims or normalises it.
|
|
1901
|
+
Stale ids/versions and malformed envelopes are silently dropped. Once id
|
|
1902
|
+
and version match the prompt in force, refused text (wrong type, oversized,
|
|
1903
|
+
empty, whitespace-only or refused characters) consumes the prompt as Cancel
|
|
1904
|
+
and calls `answer` with `null`; the refused text never reaches the hook.
|
|
1905
|
+
Accepted answers consume the prompt, advance its version and queue the
|
|
1906
|
+
close before `answer` runs; closes share
|
|
1907
|
+
the tick delivery budget. Equality suppresses delivery only when both
|
|
1908
|
+
content and `n` equal the last sent prompt: reopening the same spec after an
|
|
1909
|
+
answer or cancel sends its new version even if the queued close was coalesced.
|
|
1910
|
+
Throwing getters and Proxies are contained without logging their errors.
|
|
1911
|
+
|
|
1912
|
+
**Privacy:** typed text goes only from the typing client to the place server
|
|
1913
|
+
hook. The kit never sends it to any client, including the sender, puts it in a
|
|
1914
|
+
snapshot, delta, label, log or error, or stores it after the hook returns.
|
|
1915
|
+
A place must never show what a player typed to another player. A place without
|
|
1916
|
+
`ask` has no API, hook lookup, private state, chrome or wire additions.
|
|
1917
|
+
|
|
1918
|
+
**A place menu (v1.79).** Only a place with `menu: true` can call
|
|
1919
|
+
`hub.menu(playerId, spec | null)`. It offers one sheet privately to that player:
|
|
1920
|
+
|
|
1921
|
+
```js
|
|
1922
|
+
hub.menu(playerId, {
|
|
1923
|
+
title: 'Your colours', note: 'Choose a colour', readOnly: false,
|
|
1924
|
+
sections: [{ title: 'Colours', items: [
|
|
1925
|
+
{ id: 'blue', label: 'Blue', color: '#3aa0d8', icon: 'badge-round', on: true },
|
|
1926
|
+
] }],
|
|
1927
|
+
});
|
|
1928
|
+
```
|
|
1929
|
+
|
|
1930
|
+
Spec, sections and items are plain objects with own required properties;
|
|
1931
|
+
optional properties must also be own. Each is read once, validated and copied;
|
|
1932
|
+
unknown keys (including hidden or symbol keys) are refused. Required: spec
|
|
1933
|
+
`title` and `sections`, section `title` and `items`, item `id` and `label`.
|
|
1934
|
+
Optional: spec `note`, `readOnly` and `face` (v1.85), item `color`, `icon`, `on`.
|
|
1935
|
+
Title: 1..32 code points; note, when present: 1..80; 0..8 sections with titles
|
|
1936
|
+
1..24 code points; 0..48 total items (a section may be empty); labels 1..16
|
|
1937
|
+
code points. All text uses actions' hygiene: no control, direction or
|
|
1938
|
+
zero-width characters, never whitespace-only. Item ids match
|
|
1939
|
+
`[a-z][a-z0-9_-]{0,31}`, unique across the menu; `close` is reserved and refused
|
|
1940
|
+
as an item id. Color is `#rrggbb` (hex digits case-insensitive). Icons are
|
|
1941
|
+
exact earned shape ids from `code/client/earned.js` `EARNED_SHAPES`, or bare
|
|
1942
|
+
hat ids from `code/client/hats.js` `HATS`; unknown icons are refused. `on`
|
|
1943
|
+
and `readOnly`, when present, are booleans. A missing color uses the chrome's
|
|
1944
|
+
text color. Invalid calls throw TypeError before changing state.
|
|
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
|
+
|
|
1981
|
+
`face`, when present, is a finite number in degrees, normalised into
|
|
1982
|
+
[-180, 180). It uses `hub.placeAt`'s facing convention: the avatar looks
|
|
1983
|
+
along `(sin f, cos f)` in x/z (f in radians); 0° faces +z, 90° faces +x.
|
|
1984
|
+
While this sheet is shown under orbit camera control, the player's own
|
|
1985
|
+
client holds its local avatar at that facing; normal move reports carry it
|
|
1986
|
+
to other players. Held and seated players keep their hold or seat facing,
|
|
1987
|
+
which takes precedence. Follow-camera places ignore `face`; it never
|
|
1988
|
+
changes the camera's chosen yaw (`camAngle`). A held orbit shot uses the
|
|
1989
|
+
same orbit-control gate. Close, replacement without `face`, leave or a
|
|
1990
|
+
higher-priority UI releases the override immediately. The avatar keeps its
|
|
1991
|
+
last facing until the player moves. Older menu clients retain the spec and
|
|
1992
|
+
read only known display keys, so they ignore `face`.
|
|
1993
|
+
Without `face`, client control and the offer's wire bytes are unchanged.
|
|
1994
|
+
With `face`, the sheet is capped at 40% of the view height (40vh, or 40dvh where supported) to leave room for the avatar close-up, with its tile area scrolling as before; without `face`, the existing 55vh/55dvh cap and styles are unchanged (v1.86).
|
|
1995
|
+
|
|
1996
|
+
Every change, including null or a change back before delivery, increments a
|
|
1997
|
+
safe-integer counter for that player. Equal specs change nothing. Ordinary
|
|
1998
|
+
tick offers coalesce to at most four/s per player, at least 250 ms apart;
|
|
1999
|
+
newest wins. Fresh hello replays an open menu or a still-undelivered null once immediately,
|
|
2000
|
+
with its current version. An unused menu or an already delivered null sends nothing; leave forgets menu and press budget, retaining only
|
|
2001
|
+
the counter so returning players cannot reuse versions. Menus never appear
|
|
2002
|
+
in snapshots or deltas. Before WORLD, offers buffer but draw nothing until
|
|
2003
|
+
an opted-in place is known; a keyless WORLD discards them. Reconnect clears
|
|
2004
|
+
private client state before the hello replay.
|
|
2005
|
+
|
|
2006
|
+
The sheet is phone-first, at most 55% of the viewport height, with an internal
|
|
2007
|
+
scroll and the avatar visible above it. A title row has Close (×), then the
|
|
2008
|
+
optional note and section titles with square tiles of at least 64 px: 3–4
|
|
2009
|
+
columns on portrait phones, more on wide screens. Each tile shows a color
|
|
2010
|
+
swatch or an icon silhouette in that color, with its label underneath;
|
|
2011
|
+
`on` shows a ring and check. Pointer presses do not take canvas focus; tiles
|
|
2012
|
+
show immediate pressed feedback, but only the next spec changes selection.
|
|
2013
|
+
Reduced motion suppresses the pressed scale. ReadOnly tiles cannot be tapped
|
|
2014
|
+
and have no hover/press affordance; a note such as "Only <owner> can change
|
|
2015
|
+
this" is the place's responsibility. Walking and orbit input are held as for
|
|
2016
|
+
ask while open. Close, Escape, browser Back or the host's Back closes locally
|
|
2017
|
+
and sends `{ k: 'hub-menu-pick', id: 'close', n }`. The place decides whether
|
|
2018
|
+
to call null (including any distance-based close); the kit does not consume
|
|
2019
|
+
a menu on a pick or close. A newer spec replaces all old tiles, and null
|
|
2020
|
+
removes the sheet. Ask, conversations, the choice card, decorating and travel
|
|
2021
|
+
have priority over this sheet.
|
|
2022
|
+
|
|
2023
|
+
A tile sends `{ k: 'hub-menu-pick', id, n }`. The server requires the player's
|
|
2024
|
+
CURRENT menu and its last-sent version, drops stale/unknown picks, and refuses
|
|
2025
|
+
all item picks while readOnly; close still reaches `menu(hub, playerId, id)`.
|
|
2026
|
+
Six attempts/s with burst eight per player, including dropped presses.
|
|
2027
|
+
Async hooks are neither serialised nor cancelled on leave. Absent `menu`:
|
|
2028
|
+
no API, hook lookup, state, chrome, messages or wire additions.
|
|
2029
|
+
|
|
801
2030
|
## 10. Actor visibility
|
|
802
2031
|
|
|
803
2032
|
`hub.hide(actorId)` removes a scene actor for everyone: its server body is
|
|
@@ -807,9 +2036,111 @@ disabled now, and every client (including later joiners) removes it.
|
|
|
807
2036
|
below the ground with its collider rather than despawned, so it is meant for
|
|
808
2037
|
actors that do not move by physics.
|
|
809
2038
|
|
|
2039
|
+
**Per-viewer visibility (v1.62).** `hub.hide(actorId, { to: [playerIds] })`
|
|
2040
|
+
and `hub.show(actorId, { to: [playerIds] })` replace the shared visibility for
|
|
2041
|
+
those connected players until cleared. For example, two baked Model actors
|
|
2042
|
+
at one spot can show a lit trophy to its owner and a dark silhouette to
|
|
2043
|
+
others; Models are supported without tinting. Either operation with
|
|
2044
|
+
`{ to: [playerIds], clear: true }` drops the override, restoring the current
|
|
2045
|
+
shared state. Shared hide/show calls leave private overrides in place.
|
|
2046
|
+
Unknown or disconnected player ids are ignored; `to` must be an array of
|
|
2047
|
+
strings and `clear`, when supplied, a boolean. Empty target lists are accepted.
|
|
2048
|
+
Actor validation is the same as shared hide (scene actors and spawned copies).
|
|
2049
|
+
There are at most 256 actor overrides per player; replacing or clearing an
|
|
2050
|
+
existing override is allowed at the cap. A call that would exceed it for any
|
|
2051
|
+
recipient is refused for all recipients. Private calls return true when taken;
|
|
2052
|
+
invalid actor/options or the cap warn once per refusal kind and return false
|
|
2053
|
+
without changing anything. Leaving drops that player's overrides, including
|
|
2054
|
+
ones set before their first hello, except for the bounded retained visit below.
|
|
2055
|
+
|
|
2056
|
+
Only the client's view changes: server logic that reads `h.hidden` (pads,
|
|
2057
|
+
labels, doors and idle) continues to use the shared state. Server bodies and
|
|
2058
|
+
grab ownership are unchanged by private calls; a privately shown actor whose
|
|
2059
|
+
shared body is disabled still has a disabled server body. The client merges
|
|
2060
|
+
visibility as `(shared hidden - private show) + private hide`, used by its
|
|
2061
|
+
existing drawing, pads, idle and soundscape readers. Overrides clear on the
|
|
2062
|
+
same scene/place changes and leave paths that clear shared client visibility.
|
|
2063
|
+
A place that never supplies options sends byte-identical snapshots, deltas
|
|
2064
|
+
and messages; no new snapshot key is added.
|
|
2065
|
+
|
|
810
2066
|
`hub.label` puts words over a scene actor, drawn by the hub chrome like the
|
|
811
2067
|
HUD: a pad's "3 of 6", an NPC's line, the hill's king.
|
|
812
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
|
+
|
|
813
2144
|
**Goals (v1.13).** `hub.label(actorId, text, { style: "goal", to: [playerIds] })`
|
|
814
2145
|
is where the place is sending those players: an errand's person, the counter
|
|
815
2146
|
to fetch from. The hub chrome draws it as a pointer rather than a label: over
|
|
@@ -818,8 +2149,35 @@ the way to it, with the distance in metres beyond 6 m (the follow camera looks
|
|
|
818
2149
|
down, so a far sign is rarely in view). A goal is one player's own: with no
|
|
819
2150
|
`to` it is a `"sign"`. The two nearest are drawn; `null` clears one like any
|
|
820
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
|
+
|
|
2162
|
+
v1.39: the distance shown is the player's straight line to the actor unless
|
|
2163
|
+
the goal says which to show -- `{ distanceM: n }` is the number of metres
|
|
2164
|
+
shown in its place (finite and 0 or more, kept to the whole metre; the walk
|
|
2165
|
+
to the end of a route whose next corner the pointer aims at), shown like the
|
|
2166
|
+
measured one only beyond 6 m, and `{ distance: false }` shows none. Any other
|
|
2167
|
+
value of either is ignored and the measured distance is shown; neither means
|
|
2168
|
+
anything on a label that is not a goal. Set again with a new number (a place
|
|
2169
|
+
may do so about once a second) only the chip's words change; a label's
|
|
2170
|
+
expiry (`ttlMs`, from each time it is set) is as it was.
|
|
821
2171
|
|
|
822
|
-
|
|
2172
|
+
v1.81: `{ edge: false }` makes a goal a hint: the same pointer and distance
|
|
2173
|
+
label over its actor while it projects on screen, nothing when off screen or
|
|
2174
|
+
behind the camera. The two nearest goals that will actually be drawn are
|
|
2175
|
+
chosen, so a hidden hint never displaces an edge-drawn goal. Only exactly
|
|
2176
|
+
`false` on a goal with `to` is stored and sent; any other value or style ignores
|
|
2177
|
+
it. With the key absent, goals are stored, sent and drawn byte-identically.
|
|
2178
|
+
This applies only to hub places; no editor, classic or other Cauldron deck changes.
|
|
2179
|
+
|
|
2180
|
+
**Labels in an explicitly near town.** At the root of a deck with `labels: "near"`, in a place with no `result`, the
|
|
823
2181
|
client draws a label only when its actor is near the player: the nearest
|
|
824
2182
|
plain or `"tag"` label within 4 m and the nearest `"speech"` line within 9 m,
|
|
825
2183
|
fading in and out, one of each at a time. A `"sign"` label (a street's or a
|
|
@@ -829,7 +2187,52 @@ distance. Other players' names show within
|
|
|
829
2187
|
12 m, smaller than in a game. A town labels everything it has -- every
|
|
830
2188
|
statue, board, pad and NPC -- and all of it at once was a wall of text from
|
|
831
2189
|
the arrival spot; the words are there when the player walks over. A game
|
|
832
|
-
place
|
|
2190
|
+
place uses the default world label focus above.
|
|
2191
|
+
|
|
2192
|
+
**Labels kept near (v1.43).** A deck whose `hub` block says `"labels":
|
|
2193
|
+
"near"` has its root town draw less still, for a world too wide for names seen
|
|
2194
|
+
from anywhere. The world labels are the ones `hub.label` puts over scene
|
|
2195
|
+
actors as a plate (plain or `"tag"`), an NPC's line (`"speech"`) or a
|
|
2196
|
+
`"sign"`:
|
|
2197
|
+
|
|
2198
|
+
- a plate and an NPC's line are picked as above (the nearest within 4 m, the
|
|
2199
|
+
nearest within 9 m, one of each);
|
|
2200
|
+
- a `"sign"` is drawn only near the player: it comes on within 12 m of them
|
|
2201
|
+
on the ground and is kept until 14 m, thinning over the last metre, so
|
|
2202
|
+
nothing is drawn at 14 m or past it. The distance is the player's, not the
|
|
2203
|
+
camera's: zooming out brings no sign in;
|
|
2204
|
+
- no two world labels overlap. They are taken in order -- the plate stood
|
|
2205
|
+
by, the NPC's line, then signs by how near (one already drawn counts
|
|
2206
|
+
0.75 m nearer, so two equally near do not swap; of two equally near, one
|
|
2207
|
+
said to this player alone before one said to everyone) -- and one whose
|
|
2208
|
+
box touches a label already taken is not drawn. One taken down this way
|
|
2209
|
+
comes back only when it clears the others by 8 px and no sooner than two
|
|
2210
|
+
seconds later, so no label goes, comes and goes inside two seconds; while
|
|
2211
|
+
it waits it keeps its place among the three, so the next one down the
|
|
2212
|
+
order does not flash up for that moment;
|
|
2213
|
+
- at most three world labels are drawn at once;
|
|
2214
|
+
- a label comes and goes over a quarter second. Every label drawn in a
|
|
2215
|
+
frame, at any opacity, is held to the same rule: the ones going are taken
|
|
2216
|
+
after the ones chosen, in the same order, and one that would touch a label
|
|
2217
|
+
already taken (or be a fourth) goes at once instead of fading;
|
|
2218
|
+
- a label is judged where it is drawn, and drawn where it was judged: one
|
|
2219
|
+
box is worked out for it (its size for the words it has this frame, an
|
|
2220
|
+
NPC's line kept on the screen sideways, and in a place with a clear HUD
|
|
2221
|
+
-- `hud.clear`, §9 -- its move out from under the HUD), the rule is given
|
|
2222
|
+
that box and the chrome draws the label in it. So two signs moved onto one
|
|
2223
|
+
spot are one sign, and an NPC's reply that changes length by the screen's
|
|
2224
|
+
edge is placed by its new words;
|
|
2225
|
+
- what is held down, in reach or half faded belongs to one visit: another
|
|
2226
|
+
scene, the scene loaded again, a reconnect or a trip through a door starts
|
|
2227
|
+
the rule again.
|
|
2228
|
+
|
|
2229
|
+
Not world labels, and drawn, counted and placed exactly as without the key:
|
|
2230
|
+
goal pointers (`style: "goal"`) and friend pointers, players' own speech
|
|
2231
|
+
bubbles, reactions, emotes and marks, name tags, a cabinet's card, the result
|
|
2232
|
+
ribbon and the "Stuck?" chip. Nothing is tested for being behind a building.
|
|
2233
|
+
The key changes nothing a place's server calls or is told: a place that wants
|
|
2234
|
+
a far thing found says so with a goal. A game place draws every label it
|
|
2235
|
+
sets, with the key or without.
|
|
833
2236
|
|
|
834
2237
|
**Moving an actor (v1.1).** `hub.move(actorId, to, { overMs })` moves a scene
|
|
835
2238
|
actor whose `Body` is `"kinematic"`: a moving platform, a sweeper, a gate that
|
|
@@ -886,6 +2289,16 @@ alive at once and 10 spawns a second with bursts of 40; past either, `spawn`
|
|
|
886
2289
|
returns null and logs once, and a game tries again later. A copy a client
|
|
887
2290
|
reports gone (the multiplayer kit's pickup rule) is gone for the game too.
|
|
888
2291
|
|
|
2292
|
+
**Scenery a scene marks static.** A place's scene may mark actors
|
|
2293
|
+
`"static": true` and set `"engine": { "staticActors": true }` (physics-3d
|
|
2294
|
+
`CLAUDE.md`): the engine then leaves a marked actor alone until it is told the
|
|
2295
|
+
actor is being changed. Nothing in this contract changes for such a scene. The
|
|
2296
|
+
client tells the engine before it applies `hub.hide`, `hub.show`, `hub.tint`
|
|
2297
|
+
or `hub.move` to an actor and before it swings a door, so a place may do any
|
|
2298
|
+
of those to a marked actor; the actor is then an ordinary one until the scene
|
|
2299
|
+
is loaded again. A place whose own client code writes a marked actor's
|
|
2300
|
+
components calls `scene.touch(id)` first.
|
|
2301
|
+
|
|
889
2302
|
**Recolouring an actor (v1.1).** `hub.tint(actorId, '#rrggbb')` paints a scene
|
|
890
2303
|
actor drawn by a `Shape` for everyone, later joiners included; a Shape that
|
|
891
2304
|
glows (`emissive`) glows in the new colour. `hub.tint(actorId, null)` puts its
|
|
@@ -898,14 +2311,159 @@ cannot be painted (every client would rebuild the model), nor one with a
|
|
|
898
2311
|
dynamic `Body` (a client rebuilds a body whose Shape changes, stopping it
|
|
899
2312
|
dead). A textured face takes the colour as its tint.
|
|
900
2313
|
|
|
2314
|
+
**Turning displays (v1.55).** A scene actor may carry `"HubSpin": { "rate":
|
|
2315
|
+
45 }` among its components: every client turns it about its vertical axis at
|
|
2316
|
+
`rate` degrees a second (negative turns the other way), from the scene data
|
|
2317
|
+
alone -- a hat on a stand, a trophy, a sign. Nothing goes over the wire:
|
|
2318
|
+
there is no op, no snapshot field and no body; the server never turns it
|
|
2319
|
+
(`actorsWith`'s `t` keeps the authored rotationY), and two
|
|
2320
|
+
players' displays need not face the same way at the same moment. The turn is
|
|
2321
|
+
written to the actor's Transform each frame, rate times the frame's time, so
|
|
2322
|
+
it is as fast on a slow phone as on a fast one, and is drawn with everything
|
|
2323
|
+
under the actor's node (a `Model` riding on its `Shape`). `rate` is a finite
|
|
2324
|
+
number, not 0, from -720 to 720; `HubSpin` has no other key. The check
|
|
2325
|
+
refuses it (as the engine merges the actor with its blueprint) on an actor
|
|
2326
|
+
with a `"dynamic"` or `"kinematic"` `Body` -- its pose is its simulation's or
|
|
2327
|
+
the server's (`hub.move`) -- on a solid one (`Solid`, or `Shape.solid`),
|
|
2328
|
+
whose collider would turn on every client and stand still on the server,
|
|
2329
|
+
and on a `Player`, `HubDoor`, `HubNpc`, `HubSeat` or `Pickup`, whose facing
|
|
2330
|
+
is already owned; a client turns none of those either. Put the turning part on
|
|
2331
|
+
an actor of its own (the hat, not the stand). With the rest of §10: a hidden
|
|
2332
|
+
actor waits unturned and turns on when shown; `hub.tint` paints a turning one;
|
|
2333
|
+
a copy `hub.spawn` makes of a template carrying `HubSpin` turns too, from the
|
|
2334
|
+
`rotationY` it was put at (a hidden prototype costs next to nothing); a scene with
|
|
2335
|
+
`staticActors` is told before each turn (`scene.touch`). `HubSpin` is a `Hub`
|
|
2336
|
+
component, so device tiers (v1.21) draw the actor on every tier. A scene
|
|
2337
|
+
with no `HubSpin` is looked through once when it loads and nothing more:
|
|
2338
|
+
nothing is registered, turned or touched. A shop that turns its hats lets a
|
|
2339
|
+
player try one on with `hub.tryOn` (v1.28), never saved.
|
|
2340
|
+
|
|
2341
|
+
### Decorating (v1.67)
|
|
2342
|
+
|
|
2343
|
+
A place opts in with `hub.decor` (or `hub.places.<id>.decor`):
|
|
2344
|
+
|
|
2345
|
+
```json
|
|
2346
|
+
"decor": {
|
|
2347
|
+
"grid": { "origin": "floor", "w": 8, "d": 7, "cell": 1 },
|
|
2348
|
+
"layers": ["rug", "floor"]
|
|
2349
|
+
}
|
|
2350
|
+
```
|
|
2351
|
+
|
|
2352
|
+
The origin is a scene actor with a finite Transform: its x,z is the grid's
|
|
2353
|
+
minimum corner, y the floor height. Axes stay world x,z; the actor's rotation
|
|
2354
|
+
is not applied. Width and depth are integers 1..16, cell size 0.5..2 metres.
|
|
2355
|
+
There are 1..3 unique layer ids. Catalogue, tab, swatch and layer ids match
|
|
2356
|
+
`[a-z][a-z0-9_-]{0,23}`; actor ids are non-empty strings of at most 128 chars.
|
|
2357
|
+
The publish check refuses an invalid declaration or missing origin actor.
|
|
2358
|
+
|
|
2359
|
+
The server receives `hub.decor` only in a place with that key:
|
|
2360
|
+
|
|
2361
|
+
| call | what it does |
|
|
2362
|
+
| --- | --- |
|
|
2363
|
+
| `hub.decor.has(key)` | Whether a spawned piece still exists; use before including its key in a catalogue or restoring it |
|
|
2364
|
+
| `hub.decor.button(playerId, label \| null)` | Offers this player a chrome button at bottom-right. Label 1..16 characters; null removes it. A tap is `{ op: 'button' }` to the hook, with no catalogue required |
|
|
2365
|
+
| `hub.decor.open(playerId, spec)` | Opens the private catalogue below and a local floor grid/placement preview |
|
|
2366
|
+
| `hub.decor.close(playerId)` | Closes the catalogue and clears its preview, retaining the offered button |
|
|
2367
|
+
| `hub.decor.update(playerId, partialSpec)` | Replaces named spec fields (whole arrays), retaining the rest, and validates the resulting spec. Requires an open catalogue |
|
|
2368
|
+
|
|
2369
|
+
The player-targeted calls need a connected player. Invalid calls throw `TypeError` before
|
|
2370
|
+
changing state. Specifications contain only these fields:
|
|
2371
|
+
|
|
2372
|
+
```js
|
|
2373
|
+
{
|
|
2374
|
+
title: 'Only you can change your house', // optional, at most 40 characters
|
|
2375
|
+
tabs: [{ id: 'furniture', label: 'Furniture' }],
|
|
2376
|
+
items: [{
|
|
2377
|
+
id: 'chair', tab: 'furniture', label: 'Chair', template: 'chair-template',
|
|
2378
|
+
w: 1, d: 1, layer: 'floor', count: 2,
|
|
2379
|
+
// locked: { price: '120 ▲' },
|
|
2380
|
+
}],
|
|
2381
|
+
// swatches: [{ id: 'sage', tab: 'walls', label: 'Sage', color: '#779977' }],
|
|
2382
|
+
placed: [{ key: 'chair-template-1', item: 'chair', x: 2, z: 3, rot: 0, layer: 'floor' }],
|
|
2383
|
+
}
|
|
2384
|
+
```
|
|
2385
|
+
|
|
2386
|
+
Tabs: 1..6 unique ids, labels 1..16 characters. Items: at most 64, unique
|
|
2387
|
+
ids, a declared tab/layer, label 1..16 characters, integer w,d 1..4 cells,
|
|
2388
|
+
count a non-negative safe integer. Count means spare copies; it shows a ×n
|
|
2389
|
+
chip above one, and ×0 for placed-out stock. Locked items show a lock and
|
|
2390
|
+
price (1..12 characters) and cannot be picked. The template must be a
|
|
2391
|
+
spawnable scene actor (`hub.spawn`'s Shape/Transform rules). It supplies both
|
|
2392
|
+
the offscreen thumbnail and local ghost, including Models; a hidden template
|
|
2393
|
+
is allowed. Swatches: at most 24 unique ids, declared tabs, labels 1..16
|
|
2394
|
+
characters, `#rrggbb` colours. Placed: at most 64 unique keys naming live
|
|
2395
|
+
spawned actors, item/layer matching the catalogue, integer x,z inside the
|
|
2396
|
+
grid, rot 0..3; the rotated footprint must fit. All arrays except swatches
|
|
2397
|
+
are required, including empty items/placed arrays. Unknown keys are refused.
|
|
2398
|
+
|
|
2399
|
+
`decor(hub, playerId, op)` receives one of:
|
|
2400
|
+
|
|
2401
|
+
```js
|
|
2402
|
+
{ op: 'button' }
|
|
2403
|
+
{ op: 'place', item, x, z, rot }
|
|
2404
|
+
{ op: 'move', key, x, z, rot }
|
|
2405
|
+
{ op: 'stash', key }
|
|
2406
|
+
{ op: 'swatch', swatch }
|
|
2407
|
+
{ op: 'close' }
|
|
2408
|
+
```
|
|
2409
|
+
|
|
2410
|
+
Only arrived, connected players receive routing. A button must be offered;
|
|
2411
|
+
every other op requires that player's own open catalogue. Items must be
|
|
2412
|
+
pickable with spare stock; keys and swatches must belong to that catalogue.
|
|
2413
|
+
Cells are integers inside the grid, rot 0..3; unknown fields/ops are dropped.
|
|
2414
|
+
The server routes at most six ops/s per player with a burst of eight; a hook
|
|
2415
|
+
refusal spends its token too. Throws/rejections are logged and contained.
|
|
2416
|
+
**The deck decides ownership, collision, stock consumption and saving.** The
|
|
2417
|
+
kit changes no actor for an op, and does not close on a close request: the
|
|
2418
|
+
hook calls `hub.decor.close`, or accepts an edit with `hub.spawn/move/despawn`
|
|
2419
|
+
and `hub.decor.update`. Colour choices use `hub.tint` as before.
|
|
2420
|
+
|
|
2421
|
+
The kit draws “Decorating” plus the optional subtitle, a floor grid, and a
|
|
2422
|
+
bottom tray of horizontally scrollable tabs, thumbnail tiles and swatches.
|
|
2423
|
+
Touch or mouse on a placed actor lifts a translucent copy slightly; tap/drag
|
|
2424
|
+
the floor sets its corner cell, Rotate turns it by 90 degrees, Put away asks
|
|
2425
|
+
to stash it, and ✓ asks to move it. Picking stock starts a new ghost at a
|
|
2426
|
+
free cell nearest the player; ✓ then asks to place it. A new ghost has Cancel.
|
|
2427
|
+
Green/red footprints preview overlap on the same layer and leaving the grid;
|
|
2428
|
+
red cannot be confirmed. The server remains authoritative. Done ✓ asks to
|
|
2429
|
+
close even when nothing is lifted. Walking and orbit input are suspended
|
|
2430
|
+
using the existing input lock while open; Back remains accessible. Preview
|
|
2431
|
+
nodes and private chrome are cleared on close, scene/travel/disconnect and
|
|
2432
|
+
teardown. Thumbnails are cached per scene and rendered at most one new image
|
|
2433
|
+
per frame; closing hides the tray without affecting other players' views.
|
|
2434
|
+
|
|
2435
|
+
Decor places refuse client GONE reports; the server owns actor removal. Leaving
|
|
2436
|
+
for a place without decor disposes its DOM, listeners and thumbnail renderer.
|
|
2437
|
+
|
|
2438
|
+
In a decor place with `idle.seats`, a spawned `HubSeat` copy is offered to guests, fixed or
|
|
2439
|
+
kinematic; a kinematic copy uses the pose `hub.move` last set, and an explicit
|
|
2440
|
+
`HubSeat.face` turns with the copy relative to its template. Copies also inherit
|
|
2441
|
+
`HubSeat.pose`, including Lie down and the lying draw pose. Moving, hiding
|
|
2442
|
+
or despawning its seat stands the sitter. Authored movable seats remain
|
|
2443
|
+
unusable; a decor scene may hold a kinematic seat as a hidden spawn template.
|
|
2444
|
+
Keyless places keep their previous seat behavior.
|
|
2445
|
+
|
|
2446
|
+
Wire (§12): `{ k: 'decor', ...op }` from client, and private
|
|
2447
|
+
`{ k: 'hub-decor', button: label | null, spec: spec | null, grid? }` from
|
|
2448
|
+
server. When open, grid is resolved to `{ x,y,z,w,d,cell }`. Every API call
|
|
2449
|
+
sends that player's whole current state; a fresh hello replays it, an avatar
|
|
2450
|
+
change does not. Leaving forgets it. No state enters a shared snapshot or
|
|
2451
|
+
delta, and a place without `decor` never sends it, draws the tray, creates
|
|
2452
|
+
preview/thumbnail resources, or intercepts the new client message. The
|
|
2453
|
+
manifest/wire major remains `hub.contract: 1`.
|
|
2454
|
+
|
|
2455
|
+
A saved town draws door games with its own client. A town on a kit before
|
|
2456
|
+
v1.67 ignores the private decor message; update and save that town before
|
|
2457
|
+
offering a house with decorating through its doors.
|
|
2458
|
+
|
|
901
2459
|
## 11. The platform avatar seam
|
|
902
2460
|
|
|
903
2461
|
A hub game never draws a player. The kit draws everyone, the local player
|
|
904
2462
|
included, as their **avatar**: an id from the kit's set
|
|
905
|
-
(`imports/castle.hub-game/blueprints/avatar-<id>.scene`, v1: `0`-`3
|
|
906
|
-
client says which in its hello; the server broadcasts
|
|
907
|
-
change says hello again and respawns that player's
|
|
908
|
-
see any of it.
|
|
2463
|
+
(`imports/castle.hub-game/blueprints/avatar-<id>.scene`, v1: `0`-`3`; v1.51:
|
|
2464
|
+
`0`-`15`, below). The client says which in its hello; the server broadcasts
|
|
2465
|
+
every player's choice; a change says hello again and respawns that player's
|
|
2466
|
+
body (M0 gap 8). Games never see any of it.
|
|
909
2467
|
|
|
910
2468
|
Where the choice comes from is one function, `Avatar.current()` in the kit's
|
|
911
2469
|
client:
|
|
@@ -916,13 +2474,16 @@ client:
|
|
|
916
2474
|
chrome's picker calls. Only a curated hub place (an enabled door leads into
|
|
917
2475
|
or out of it) may change it; the host names the place, and anywhere else a
|
|
918
2476
|
pick stays the runtime's own. A player who never chose wears a default fixed
|
|
919
|
-
by their user id.
|
|
920
|
-
|
|
921
|
-
|
|
2477
|
+
by their user id. Ghost uses a user-id cutoff: existing accounts below it
|
|
2478
|
+
keep `userId % 4` (`0`-`3`); new accounts from it on use `userId % 16`
|
|
2479
|
+
(`0`-`15`). Stored choices stay unchanged. Anonymous accounts may choose: a template
|
|
2480
|
+
index carries no text to moderate and nothing of value, and an anonymous
|
|
2481
|
+
account keeps its user id when it signs up.
|
|
922
2482
|
- **A stand-in pick** kept in `scene.persistent`, where there is no platform
|
|
923
2483
|
avatar: a signed-out visitor, a host or SDK from before avatars, a deck that
|
|
924
2484
|
is not a curated place (the dev serve). It lasts for the runtime, across
|
|
925
|
-
doors.
|
|
2485
|
+
doors. With no stored local choice, it is a random one of `0`-`15`,
|
|
2486
|
+
also used until the platform answers. A stored local choice stays unchanged.
|
|
926
2487
|
|
|
927
2488
|
The hello never waits for the avatar: it goes out with what the kit has, and
|
|
928
2489
|
says hello again when that changes. Picks are written one at a time; one ghost
|
|
@@ -936,7 +2497,132 @@ replaces the hello's choice unless a later hello changes it. Elsewhere (the dev
|
|
|
936
2497
|
serve) the server takes each client's hello, which can only change how that
|
|
937
2498
|
player looks.
|
|
938
2499
|
|
|
939
|
-
**Avatar
|
|
2500
|
+
**Avatar colours (v1.87, dormant).** Each toon character offers six colours:
|
|
2501
|
+
`0` is the model as drawn; `1`–`5` recolour its named main/shade parts, leaving
|
|
2502
|
+
faces and other parts unchanged. One colour per account, cleared when the
|
|
2503
|
+
character changes. `Avatar.currentColor(scene)` reads it; `colorsAvailable()`
|
|
2504
|
+
is true on the platform path only after the host's `Avatar.get()` answer
|
|
2505
|
+
carries a `color` field and the deck's `castle.base` SDK carries
|
|
2506
|
+
`Avatar.colors === true` (a base republished from main at or after this change).
|
|
2507
|
+
On the stand-in path, support already confirmed by the platform remains
|
|
2508
|
+
available; otherwise the deck's `castle.json` opts in with `hub.avatarColors: true`.
|
|
2509
|
+
`hub.avatarColors` must be a boolean; absent or `false` preserves the stored
|
|
2510
|
+
manifest, and without host hub ops preserves wire bytes and behavior. Only
|
|
2511
|
+
exactly `true` is stored in the manifest. It applies to all of the deck's
|
|
2512
|
+
places, like `hub.yourGames`.
|
|
2513
|
+
`choose(scene, index)` keeps `Avatar.set(index)`
|
|
2514
|
+
without options; `chooseColor(scene, color)` calls `Avatar.set(current,
|
|
2515
|
+
{ color })` and confirms or undoes it like the character. Stand-in colours
|
|
2516
|
+
live in `scene.persistent.hubAvatarColor` and clear on a character change
|
|
2517
|
+
only while colours are available; otherwise the stored colour is ignored
|
|
2518
|
+
and colour picks do nothing. A stand-in runtime alone does not enable them.
|
|
2519
|
+
The picker offers six click-only dots below the character grid only when
|
|
2520
|
+
colours are available, the viewer uses toon and the character has a palette.
|
|
2521
|
+
|
|
2522
|
+
The hello adds `color` only while colours are available and for a non-zero
|
|
2523
|
+
integer. The server accepts a hello colour where the host has hub ops or with
|
|
2524
|
+
`hub.avatarColors: true`, provisionally like the hello's avatar. It takes ghost's
|
|
2525
|
+
`hubResultsRead` `players[userId].avatarColor` where the host has hub ops,
|
|
2526
|
+
by the same revision rule as its avatar, regardless of the manifest opt-in;
|
|
2527
|
+
elsewhere it takes the opted-in hello. With no ghost colour and no opt-in,
|
|
2528
|
+
there is no hello `color`, no `hubAvC` and no colour row in the picker.
|
|
2529
|
+
Anything other than an integer `0`–`15` becomes `0`; changing character with
|
|
2530
|
+
no new colour clears it. `hubAvC: { playerId: color }` is a latched whole block
|
|
2531
|
+
listing only non-zero colours, hidden by the same blocked-pair rule as
|
|
2532
|
+
`hubAv`/`hubAv2`, with each permitted viewer's own block in `hub-av`.
|
|
2533
|
+
Snapshots omit an empty block; deltas send `{}` once to clear a block already
|
|
2534
|
+
sent. Old clients ignore `hubAvC`; `hubAv` and `hubAv2` are unchanged.
|
|
2535
|
+
Without colours, client/server behavior and wire bytes remain identical.
|
|
2536
|
+
|
|
2537
|
+
Only toon recolours known palettes. Kit-only live `.colors/` model and
|
|
2538
|
+
blueprint files are cached once per character/colour pair; colour zero, other
|
|
2539
|
+
styles and missing files keep the existing paths. Local bodies use the same
|
|
2540
|
+
variants. Items, hats, fits and heights keep the same character index.
|
|
2541
|
+
The avatar cap counts character/colour pairs and first drops colour before
|
|
2542
|
+
falling back to a stand-in character; nearby players and the local player
|
|
2543
|
+
keep their own appearance.
|
|
2544
|
+
|
|
2545
|
+
**Sixteen avatars (v1.51).** The ids are `0`-`15`: the Castle mascot, Petal,
|
|
2546
|
+
Beat and Star (`0`-`3`, as before), then Biscuit (a puppy), Mochi (a cat), Hop
|
|
2547
|
+
(a bunny), Pip (a penguin), Ribbit (a frog), Ember (a dragon), Bolt (a robot),
|
|
2548
|
+
Gloop (an alien), Cap (a mushroom), Toast, Scoop (an ice cream) and Zest (an
|
|
2549
|
+
orange). The picker shows all sixteen by face and name
|
|
2550
|
+
(`code/client/avatarFaces.js`, written with the models by
|
|
2551
|
+
`scripts/gen-avatars.mjs`). An avatar is still one integer in the hello, and
|
|
2552
|
+
where nobody wears one of the twelve nothing new is sent.
|
|
2553
|
+
|
|
2554
|
+
- **New defaults span all sixteen.** A guest with no stored local choice
|
|
2555
|
+
may be given any of `0`-`15`. Ghost gives an account that never picked
|
|
2556
|
+
`userId % 16` from its user-id cutoff on; an existing account below it
|
|
2557
|
+
keeps `userId % 4`, one of the first four. The cutoff is ghost's rule,
|
|
2558
|
+
not the kit's. Stored choices are kept. Compatibility still uses four:
|
|
2559
|
+
`hubAv` carries `avatar % 4`, and an index this kit lacks folds into
|
|
2560
|
+
`0`-`3`. Server messages are unchanged for the same avatar inputs.
|
|
2561
|
+
- **The other sets do not have them.** `4`-`15` are toon's alone. A viewer in
|
|
2562
|
+
`blocky`, `bean` or `pixel` sees a player who wears one as its toon model,
|
|
2563
|
+
beside the set's own drawings of `0`-`3`, at toon's height and hat fit
|
|
2564
|
+
(`Avatar.drawn`, `top`, `hatFit`).
|
|
2565
|
+
- **A viewer may draw fewer different characters at once**
|
|
2566
|
+
(`code/client/avatarCap.js`). By default the limit is all sixteen, so
|
|
2567
|
+
everyone is drawn as what they wear; with `?hubAvDistinct=N`, at most N
|
|
2568
|
+
different characters, the local player's own included: beyond that
|
|
2569
|
+
the farthest players who wear one of `4`-`15` are drawn as their stand-in,
|
|
2570
|
+
`avatar % 4`, hats fitted to it (the stand-ins count toward N, so
|
|
2571
|
+
the total never passes it unless the first four worn here and the local
|
|
2572
|
+
player's alone do), and nearer players win, with hysteresis
|
|
2573
|
+
(a player drawn as their own counts 3 m nearer; a change holds 2 s).
|
|
2574
|
+
Nobody within 8 m is a stand-in, even past N: a player who walks up is
|
|
2575
|
+
drawn as their own at once and stays so out to 11 m. It is
|
|
2576
|
+
this viewer's drawing alone: the wire, what is saved, the picker and what
|
|
2577
|
+
a place hears are unchanged, and the local player always draws their own.
|
|
2578
|
+
Different characters also draw from shared materials
|
|
2579
|
+
(`code/client/avatarShare.js`); nothing on screen changes for it.
|
|
2580
|
+
`?hubAvDistinct=N` sets the limit and `?hubAvShare=0` turns the sharing
|
|
2581
|
+
off, `?hubAvShare=sort` adds a draw order by geometry, for measuring.
|
|
2582
|
+
- **On the wire, `hubAv` still only names `0`-`3`** (§12). A client from
|
|
2583
|
+
before v1.51 has no blueprint for another avatar and would not draw the
|
|
2584
|
+
player at all, so a v1.51 place lists a player who wears `4`-`15` in
|
|
2585
|
+
`hubAv` as a stand-in, `avatar % 4`, and says what they really wear in a
|
|
2586
|
+
second block, `hubAv2`. A v1.51 client draws `hubAv2`'s avatar where it
|
|
2587
|
+
names a player `hubAv` lists, and `hubAv`'s otherwise; a client from before
|
|
2588
|
+
it never reads `hubAv2`. The block is there only while someone in the place
|
|
2589
|
+
wears one of the twelve: a place where nobody does sends the bytes it sent
|
|
2590
|
+
before v1.51 (`scripts/test-avatar-wire.mjs` holds them to a hash of what
|
|
2591
|
+
the kit wrote then).
|
|
2592
|
+
- **A v1.51 client in a place on an older kit** (its server takes `0`-`3`):
|
|
2593
|
+
a hello that says `4`-`15` is taken as `0`, and ghost's read of `4`-`15` is
|
|
2594
|
+
not taken, so the hello's `0` stands. Everyone else there sees that player
|
|
2595
|
+
as the Castle mascot, hats fitted to the mascot. The player's own client
|
|
2596
|
+
draws its own body from its own pick, so they see the character they
|
|
2597
|
+
chose. Nothing throws; it ends when the place is saved again on v1.51.
|
|
2598
|
+
- **A client from before v1.51 in a v1.51 place** (a town saved before it
|
|
2599
|
+
draws every place a player reaches through its doors): a player who wears
|
|
2600
|
+
`4`-`15` is drawn as the stand-in, one of the first four, with their name
|
|
2601
|
+
tag and a hat fitted to the stand-in. Always somebody, never nobody, and
|
|
2602
|
+
the same somebody a v1.51 client would fall back to. Such a client treats
|
|
2603
|
+
its own account's `4`-`15` as no platform avatar: it wears a random
|
|
2604
|
+
stand-in from `0`-`3` and says so in its hello, but where the host runs the
|
|
2605
|
+
hub ghost's `4`-`15` replaces that hello, so others on v1.51 see the
|
|
2606
|
+
character the account chose (and others on an older client its `% 4`)
|
|
2607
|
+
while the player sees their own stand-in. A pick they make there is the
|
|
2608
|
+
runtime's own and wins from then on, for everyone.
|
|
2609
|
+
- **A page left open across the save.** A page that loaded the town before
|
|
2610
|
+
it was saved on v1.51 keeps the client it loaded. In the session it is in,
|
|
2611
|
+
the place is the kit it started on, and a newer client who joins it and
|
|
2612
|
+
wears `4`-`15` is the case above this one's: the mascot to everyone else.
|
|
2613
|
+
Once that page joins a session of a v1.51 place (a door, a reconnect), it
|
|
2614
|
+
is the case just above: stand-ins. In neither is anyone left undrawn.
|
|
2615
|
+
- **A later kit's avatar** (an id of 16 or more, in `hubAv2` from a place on
|
|
2616
|
+
a kit after this one): a v1.51 client draws that player as `id % 4`, which
|
|
2617
|
+
is also what that place's `hubAv` says, and fits hats to that
|
|
2618
|
+
(`Avatar.known`). Its own account's id of 16 or more is no platform avatar
|
|
2619
|
+
here (the stand-in is worn). A later kit that adds avatars keeps `hubAv`
|
|
2620
|
+
within `0`-`3` and may send any id in `hubAv2`.
|
|
2621
|
+
- Each of the twelve is at most 1,500 triangles with its outline pass and 8
|
|
2622
|
+
draw calls, as the first four are (`scripts/test-avatar-models.mjs` counts
|
|
2623
|
+
them with the engine's `modelCost`).
|
|
2624
|
+
|
|
2625
|
+
**Avatar sets.** The kit has more than one drawing of the first four avatars:
|
|
940
2626
|
`toon` (the default, `blueprints/avatar-<id>.scene`) and `blocky`, `bean` and
|
|
941
2627
|
`pixel` (`blueprints/<style>/avatar-<id>.scene`, models in `models/<style>/`,
|
|
942
2628
|
art in `drawings/<style>/`). Which set is drawn is the **viewer's** own:
|
|
@@ -946,7 +2632,8 @@ calls `experimentsReady` once before the first read and draws toon until the
|
|
|
946
2632
|
host answers), and a viewer in a set sees every player in it, themselves
|
|
947
2633
|
included, by the same avatar id. Anything else, an SDK without experiments or
|
|
948
2634
|
a set the engine's files do not have, is toon, so nothing changes until an
|
|
949
|
-
experiment assigns a set
|
|
2635
|
+
experiment assigns a set (and an avatar a set does not draw, `4`-`15`, is
|
|
2636
|
+
toon's, above). On a page served from `localhost` or `127.0.0.1`,
|
|
950
2637
|
`?hubStyle=<style>` overrides it. Nothing about the set is on the wire and the
|
|
951
2638
|
avatar id means what it did, so this is not a contract change: a game never
|
|
952
2639
|
sees it, and the town's engine lays every set over a game's content pack as it
|
|
@@ -977,9 +2664,10 @@ back to every hub place on the arrival read (`players[userId].wearable` of
|
|
|
977
2664
|
The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
|
|
978
2665
|
|
|
979
2666
|
- `kind` is a lowercase id (`/^[a-z][a-z0-9-]{0,23}$/`). The kit draws
|
|
980
|
-
`"halo"` (a
|
|
981
|
-
|
|
982
|
-
|
|
2667
|
+
`"halo"` (a glowing ring with an open middle over the head, as wide as the
|
|
2668
|
+
head; v1.41, before it a thin disc), `"aura"` (a glowing ring at the feet
|
|
2669
|
+
round a faint disc; v1.41, before it a disc) and `"orbit"` (small sparks
|
|
2670
|
+
circling the head, one more for every three rarity); a kind it does not know is kept but not drawn, so a later kit may
|
|
983
2671
|
draw more. `color` is `#rrggbb`; `rarity` an integer 0-9, which grows the
|
|
984
2672
|
pieces and their glow a little.
|
|
985
2673
|
- **Hats (v1.24).** A `kind` of `hat-<id>` is a hat the kit draws on the
|
|
@@ -990,11 +2678,17 @@ The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
|
|
|
990
2678
|
A place's server reads the list from the kit, `HATS` (and `HAT_SETS`, the
|
|
991
2679
|
same ids four to a set) in
|
|
992
2680
|
`@imports/castle.hub-game/code/client/hats.js`, so it offers only hats
|
|
993
|
-
every client draws.
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
2681
|
+
every client draws. Since v1.41 a hat is the kit's model of it
|
|
2682
|
+
(`models/hats/<id>.pxmodel`, drawn with the avatars' outline look) in its
|
|
2683
|
+
own colours; `color` is still sent and checked, and a place sends the hat's
|
|
2684
|
+
main colour. `rarity` is kept and changes nothing: a hat is one size,
|
|
2685
|
+
fitted to each avatar in each set, and does not glow. A hat is drawn for the
|
|
2686
|
+
players a client is sent (`nearestPlayers`, §1) at every device tier, as the
|
|
2687
|
+
other wearables are. Every wearable is drawn under its avatar's own node,
|
|
2688
|
+
so it moves, turns and is hidden with the avatar: under the orbit camera
|
|
2689
|
+
(physics-3d) a player's own wearable is left out of the frames their own
|
|
2690
|
+
body is, when the camera is pressed against it. A town's engine draws the
|
|
2691
|
+
hats of a game behind a door from its own kit (a pack carries none). A `hat-` id not in the list is a
|
|
998
2692
|
kind the kit does not know: kept, not drawn. Still one wearable per account:
|
|
999
2693
|
a hat replaces a halo and a halo a hat.
|
|
1000
2694
|
- Ghost takes a wearable only from a curated hub place (an enabled door leads
|
|
@@ -1051,21 +2745,287 @@ shows a wearable on the player **in this place only, without saving it**:
|
|
|
1051
2745
|
nothing breaks, the try-on is simply not seen there until that deck is
|
|
1052
2746
|
saved again.
|
|
1053
2747
|
|
|
2748
|
+
**The Earned slot (v1.53).** A player has two wearable slots. The **Look**
|
|
2749
|
+
(`hub.wear`, above: hats, halos, auras, anything with a rarity) is the town's
|
|
2750
|
+
and, later, the shop's. The **Earned** slot holds one small thing a game gave
|
|
2751
|
+
for a stated deed, drawn beside whatever the Look puts on the head, so a win
|
|
2752
|
+
never takes a hat off:
|
|
2753
|
+
|
|
2754
|
+
- **Classes.** `badge` or `pin` (on the chest, front, upper left), `belt`
|
|
2755
|
+
(round the waist), `sash` (across the torso, right shoulder to left hip) or
|
|
2756
|
+
`held` (in the right hand, at the side). No hats, halos, auras, orbits,
|
|
2757
|
+
capes or outfits: those are the Look's. An earned item has **no rarity**;
|
|
2758
|
+
its look is fixed per item.
|
|
2759
|
+
- **Declared.** A deck lists wearable items in `hub.unlocks` (§1): at most 8,
|
|
2760
|
+
each `{ id, class, shape, name, deed, color }`, `id` and `shape` matching
|
|
2761
|
+
`[a-z][a-z0-9-]{0,23}`, `name` 1-24 characters, `deed` 1-80 (what the town
|
|
2762
|
+
shows: "win 3 races in Cove"), both trimmed before they are measured, as
|
|
2763
|
+
ghost trims them, `color` `#rrggbb`. Ghost reads it from the
|
|
2764
|
+
saved deck and refuses an id it does not declare. The kit's check refuses a
|
|
2765
|
+
declaration out of these rules and warns of a shape it does not draw for
|
|
2766
|
+
that class.
|
|
2767
|
+
- **Shapes.** `badge-round` (the glow badge: its face glows in its colour),
|
|
2768
|
+
`badge-star`, `badge-shield`, `pin-round`, `belt-plain`, `sash-plain`,
|
|
2769
|
+
`held-lantern`, `held-trophy`, `held-net`, `held-ball`
|
|
2770
|
+
(`code/client/earned.js` `EARNED_SHAPES`, which a place's server may read;
|
|
2771
|
+
`models/earned/<shape>.pxmodel`, `scripts/gen-earned.mjs`). The item's
|
|
2772
|
+
`color` is its main material's; trims keep theirs. A badge's shape may be
|
|
2773
|
+
worn as a pin and a pin's as a badge. A shape the kit does not draw, or one
|
|
2774
|
+
of another class, is kept and not drawn. Each sits at its class's anchor
|
|
2775
|
+
fitted to every avatar (`avatar.js` `earnedFit`, measured against the
|
|
2776
|
+
models), under the avatar's own node like a hat, hidden with the player's
|
|
2777
|
+
own body, and never over the face: a badge, drawn 2.6 times its model
|
|
2778
|
+
(about 38 cm across, to be seen across a street as the halos it replaces
|
|
2779
|
+
were) with a soft glow in its colour behind it, or a pin, drawn 2.1 times,
|
|
2780
|
+
on the chest under the face and any head (Castle's, under its eye, 0.75 as
|
|
2781
|
+
big); a belt round the outside of the waist;
|
|
2782
|
+
a sash round the outside of the torso from the right shoulder to the left
|
|
2783
|
+
hip, 45 degrees where a head stands over the body and 36-40 on a one-piece
|
|
2784
|
+
body, so it passes under the face; a held thing, drawn 1.2 times its
|
|
2785
|
+
model, gripped in the right hand. On the boxy sets (blocky, and pixel but
|
|
2786
|
+
for its round Castle) a belt and sash are square
|
|
2787
|
+
(`models/earned/square/<shape>.pxmodel`), so they lie flat on a box. A town's engine draws them from its own kit, as it does hats (a
|
|
2788
|
+
mounted pack is given the engine's earned models).
|
|
2789
|
+
- **Never random, tradeable or paid.** A game gives an item only by
|
|
2790
|
+
`hub.unlock`, for its stated deed, the same for everyone: no rolls or
|
|
2791
|
+
chance, no selling it for money or bricks, no giving it to another player,
|
|
2792
|
+
no taking it back (owned is only raised).
|
|
2793
|
+
- **Given.** `hub.unlock(playerId, id)`: ghost checks the place is curated,
|
|
2794
|
+
the player signed in, the id declared by this deck, the class an earned
|
|
2795
|
+
one, and a rate limit, then keeps it per account. A first unlock is shown.
|
|
2796
|
+
A refusal resolves null and is logged once (`CAULDRON_HUB_UNLOCK_*`,
|
|
2797
|
+
`CAULDRON_HUB_INVALID_ARGUMENT`); nothing here changes. A guest's unlock,
|
|
2798
|
+
and any where the host has no unlock (the dev serve, a runtime without it:
|
|
2799
|
+
`CAULDRON_HUB_UNAVAILABLE`), is this session's alone, from the deck's own
|
|
2800
|
+
declaration: drawn here, never saved, as a guest's wearable is.
|
|
2801
|
+
- **The town alone chooses.** `hub.wearEarned(playerId, { deckId, id } |
|
|
2802
|
+
null)` changes which owned item a player shows, everywhere; ghost refuses it
|
|
2803
|
+
from any place but the town (`CAULDRON_HUB_EARNED_NOT_A_ROOT`) and for an
|
|
2804
|
+
item the player does not own (`_NOT_OWNED`). `hub.unlocksOf(userIds)` reads
|
|
2805
|
+
what players here own, for a wardrobe.
|
|
2806
|
+
- **Read on arrival.** Ghost's arrival read carries `earned` only for a player
|
|
2807
|
+
who shows one; the place keeps it (`hub.earned`). An unlock or choice made
|
|
2808
|
+
after a read began wins over that read, as `hub.wear` does; a refused one
|
|
2809
|
+
changes nothing and lets the read land.
|
|
2810
|
+
- **Nothing for a place where nobody has one.** `hubEarned` and `hub-earned`
|
|
2811
|
+
(§12) go only once someone here shows an item; `hub.wearing` and `hubWear`
|
|
2812
|
+
are what they were. A client older than v1.53 ignores both and draws the
|
|
2813
|
+
Look alone.
|
|
2814
|
+
|
|
2815
|
+
### Home unlocks (v1.70/v1.73)
|
|
2816
|
+
|
|
2817
|
+
A game may also give a player something for their house. It is never worn or drawn on
|
|
2818
|
+
the avatar, and it is not shown in the wardrobe. The player's house reads it and offers
|
|
2819
|
+
it in the decor tray, Rooms tab or pet book according to its class.
|
|
2820
|
+
|
|
2821
|
+
- **Classes.**
|
|
2822
|
+
- `furniture`: one catalogue piece. The house shows it in the decor tray, unlocked,
|
|
2823
|
+
and the player places, moves and stashes it like any other piece. Owning it once
|
|
2824
|
+
lets the player place one copy.
|
|
2825
|
+
- `deed`: one area of the house (a yard, kitchen, upstairs, pond or attic). The house
|
|
2826
|
+
shows it on its Rooms tab, where the owner builds it.
|
|
2827
|
+
- `pet` (v1.73): one species of pet the player has adopted. The house shows it
|
|
2828
|
+
in its pet book; `piece` is `pet-<species>`. A deck may declare up to 16 pet
|
|
2829
|
+
items, counted apart from the 6 furniture/deed items and the 8 wearables.
|
|
2830
|
+
- **Declared.** Each entry is `{ id, class, piece, name, deed, color }`:
|
|
2831
|
+
- `piece` names what the house shows, from the house's published list (below), and
|
|
2832
|
+
matches `[a-z][a-z0-9-]{0,23}`. For `pet`, it must also match
|
|
2833
|
+
`pet-[a-z][a-z0-9-]{0,19}`. `pet-walk-*` is the house pet's stage, not a
|
|
2834
|
+
species: pet entries cannot use it. Furniture/deed piece rules are unchanged,
|
|
2835
|
+
including existing `pet-walk-1..3`, `pet-collar` and other `pet-*` furniture.
|
|
2836
|
+
- Ghost must accept the `pet` class before a deck declares one. An older ghost
|
|
2837
|
+
refuses that deck's whole unlocks list, including its furniture and wearables.
|
|
2838
|
+
- It has no `shape`. The kit's check refuses a `shape` on a home entry and a `piece`
|
|
2839
|
+
on a wearable one.
|
|
2840
|
+
- `id`, `name`, `deed` and `color` follow the earned rules: `deed` says how the
|
|
2841
|
+
player gets it ("buy at the Willowbank stand for 300 coins", "catch all 12 fish in
|
|
2842
|
+
Amberwake").
|
|
2843
|
+
- The check warns about a `piece` that is not in the list, and keeps the entry. An
|
|
2844
|
+
unknown piece is owned but not offered.
|
|
2845
|
+
- **The list of pieces** is the house deck's, published in this contract:
|
|
2846
|
+
- `kits/hub-game/docs/home-pieces.md`: id, footprint and which game gives it.
|
|
2847
|
+
- The house adds a piece to its catalogue before any game declares it.
|
|
2848
|
+
- A game claims a piece id by naming it on its card and in that file. Two games
|
|
2849
|
+
never give the same piece.
|
|
2850
|
+
- **Never random, tradeable or paid.** The earned rule applies unchanged:
|
|
2851
|
+
- The game gives it only by `hub.unlock`, for its stated deed, the same for everyone.
|
|
2852
|
+
- It may be sold for **the game's own coins**, earned by playing. It is never sold
|
|
2853
|
+
for money or bricks, never in a random box, never given to another player, and
|
|
2854
|
+
never taken back.
|
|
2855
|
+
- A coin price is the game's own: its coin shop, its pad, its save.
|
|
2856
|
+
- **Given.** `hub.unlock(playerId, id)` works the same way and answers
|
|
2857
|
+
`{ isNew, earned, saved }`:
|
|
2858
|
+
- `earned` is what the player now shows, a wearable EarnedItem or null, never
|
|
2859
|
+
the home item given. Home items use `piece` in place of `shape` in owned reads.
|
|
2860
|
+
- A first unlock is announced with "Sent to your house". It is never shown
|
|
2861
|
+
on the avatar. A harbour boat deed, a home item whose `piece` (or id, when it
|
|
2862
|
+
has none) starts with `boat-`, is announced with "Sent to your boat at the
|
|
2863
|
+
Harbour" instead (v1.77).
|
|
2864
|
+
- A guest's unlock, and any unlock on the dev serve, lasts the session.
|
|
2865
|
+
- **Never worn.**
|
|
2866
|
+
- `hub.wearEarned` resolves null and logs once
|
|
2867
|
+
(`CAULDRON_HUB_EARNED_NOT_WEARABLE`), locally without calling the host
|
|
2868
|
+
when the item is known from this deck's declaration, an unlock or an owned read.
|
|
2869
|
+
- The arrival read's `earned` and `hub.earned` never carry one.
|
|
2870
|
+
- The town's wardrobe filters all home classes out of `hub.unlocksOf`.
|
|
2871
|
+
- **Read by the house.** `hub.unlocksOf([owner])` returns home items among `owned`,
|
|
2872
|
+
answered for connected players as before:
|
|
2873
|
+
- The house reads it when the owner arrives, and again when the decor tray opens.
|
|
2874
|
+
- It unlocks a catalogue piece whose id is a `furniture` item's `piece`, and an
|
|
2875
|
+
area whose id is a `deed` item's `piece`. A `pet` item's `piece` names the
|
|
2876
|
+
adopted species in its pet book.
|
|
2877
|
+
- Guests never need the read: what the owner placed is in the house's own save.
|
|
2878
|
+
- **Nothing changes where nobody declares one.** A deck without a pet entry and a
|
|
2879
|
+
player without a pet sends and receives exactly the bytes it did before v1.73,
|
|
2880
|
+
including decks with furniture or deeds. A deck without any home entry, and a
|
|
2881
|
+
player without one, sends and receives the same bytes as before. An older client
|
|
2882
|
+
draws nothing for a home item, which is already correct.
|
|
2883
|
+
|
|
1054
2884
|
## 12. Wire (kit-internal, listed so a host or bot can speak it)
|
|
1055
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
|
+
|
|
2946
|
+
### Page visibility (v1.91, opt-in)
|
|
2947
|
+
|
|
2948
|
+
A place declaring `visibility: true` is sent `hubPlace.visibility: true`. Its
|
|
2949
|
+
client listens for `document.visibilitychange` and sends
|
|
2950
|
+
`{ k: 'hub-visibility', visible: boolean, at: number }`, where `at` is the
|
|
2951
|
+
client's Unix timestamp in milliseconds. Repeated events with the same state
|
|
2952
|
+
are coalesced. A hidden page sends immediately, without waiting for an animation
|
|
2953
|
+
frame. A change while disconnected is sent when the connection can send again;
|
|
2954
|
+
a newly mounted client reports its initial hidden or visible state. Leaving an opted-in place
|
|
2955
|
+
removes its listener. A place without the key installs no listener and keeps
|
|
2956
|
+
its original wire fields and behavior.
|
|
2957
|
+
|
|
2958
|
+
A signal received after hello but before arrival is kept and delivered after
|
|
2959
|
+
the deck's arrival hook. The kit calls the optional server hook
|
|
2960
|
+
`visibility(hub, { playerId, visible, at })` only for an arrived, present sender.
|
|
2961
|
+
The sender identity comes from the session; a payload cannot name another player.
|
|
2962
|
+
Malformed, duplicate-state and older-timestamp messages are ignored. `at` is
|
|
2963
|
+
untrusted metadata, never server simulation time or proof of elapsed time.
|
|
2964
|
+
A place may pause its own guidance clocks while hidden and restore its UI on
|
|
2965
|
+
visible. This does not itself reconnect, arrive, leave or change progression;
|
|
2966
|
+
the existing `resume` hook remains independent.
|
|
2967
|
+
|
|
2968
|
+
|
|
2969
|
+
A first home unlock (v1.70, §11) sends private `{ k: 'hub-home-unlock' }`
|
|
2970
|
+
to its player only, announcing "Sent to your house". It carries no item and
|
|
2971
|
+
never changes WORLD, deltas, `hubEarned` or `hub-earned`. No such message is
|
|
2972
|
+
sent when there is no home unlock. A harbour boat deed's (a `boat-` piece,
|
|
2973
|
+
v1.77) is `{ k: 'hub-home-unlock', to: 'boat' }`, announcing "Sent to your boat
|
|
2974
|
+
at the Harbour"; every other home item's keeps exactly the bytes above. An
|
|
2975
|
+
older client ignores `to` and says "Sent to your house".
|
|
2976
|
+
|
|
2977
|
+
Decorating (v1.67, §10) adds client `{ k: 'decor', ...op }` only in a
|
|
2978
|
+
`decor` place, and server `{ k: 'hub-decor', button, spec, grid? }` to the
|
|
2979
|
+
concerned player only. These private states never enter WORLD or deltas.
|
|
2980
|
+
|
|
2981
|
+
|
|
1056
2982
|
Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per session join
|
|
1057
|
-
(and again with `again: true` when only the avatar changed, v1.7
|
|
2983
|
+
(and again with `again: true` when only the avatar changed, v1.7; and again,
|
|
2984
|
+
fresh, with `resume: true`, `party: 1` and no `carry` or `near`, when the
|
|
2985
|
+
session gives this connection a body again after a drop (a second WORLD on the
|
|
2986
|
+
same connection, or a new player id on it, which also clears what the client
|
|
2987
|
+
held privately from the old session): every place but a game (one with
|
|
2988
|
+
`result`), so a player the place let go during a phone's app switch is arrived
|
|
2989
|
+
again without waiting for the place's own greet 3 s later. Whichever comes
|
|
2990
|
+
first arrives them, once, and marks stale what their client still holds; a
|
|
2991
|
+
hello from a player still arrived does not replay the arrival. v1.88: a fresh
|
|
2992
|
+
hello under a retained player id replays that player's current private HUD,
|
|
2993
|
+
labels, tune and avatar overrides once on the next tick, sending nothing for
|
|
2994
|
+
a channel never set or whose last sent value was empty (a `resume: true` hello,
|
|
2995
|
+
whose client may have missed a clear, is re-sent empty ones too), with no new
|
|
2996
|
+
wire keys.
|
|
2997
|
+
A game takes neither under the same player id; under a new one its client
|
|
2998
|
+
says an ordinary first hello, a party of one. v1.72: a game whose place says `resume: true`
|
|
2999
|
+
takes both under the same player id, as any place does (`hubPlace.resume:
|
|
3000
|
+
true` tells its client): a player its `leave` let go is arrived again, the
|
|
3001
|
+
`arrive` hook running once whichever of the two comes first, and the visit
|
|
3002
|
+
goes on. Its invariants: (I1) exactly one result per visit whatever the
|
|
3003
|
+
order of leave, report and resume (a result the `leave` hook reports is
|
|
3004
|
+
kept, and a second `hub.result` is refused); (I2) the visit's
|
|
3005
|
+
`maxDurationSec` deadline is set once, at its first arrival, so drops never
|
|
3006
|
+
extend it; (I3) restored state with a packet is sent again on resume: an
|
|
3007
|
+
ended visit hears `{ k: 'hub-end', why, again: true }` once arrived (a
|
|
3008
|
+
client already ending keeps its pause), and the HUD, labels, tune, avatars,
|
|
3009
|
+
visibility, party and the place's own shot and card go again; (I4)
|
|
3010
|
+
provenance is written once per visit: `from` and `fromDeckId` stay the
|
|
3011
|
+
visit's first (the platform's door then, else none). One still arrived is
|
|
3012
|
+
not arrived again, and is re-sent all of the above);
|
|
1058
3013
|
`{ k: 'hub-dev-classic', on? }` (v1.7; the dev serve's stand-in for classic boards, §4, ignored by any session that is not a dev one);
|
|
1059
3014
|
`{ k: 'hub-door-jump', door }` (a town's Doors list, §5);
|
|
3015
|
+
`{ k: 'hub-unstick' }` (v1.33, §5 "Stuck?": only a deck with `hub.stuck` knows it, and only its towns answer, once in 5 s; v1.39, with `ask: true` it moves nobody and asks what the tap would do, answered only by a place with the `unstick` hook, once a second);
|
|
1060
3016
|
`{ k: 'hub-say', r }` or `{ k: 'hub-say', p }` (v1.11, §6);
|
|
3017
|
+
`{ k: 'hub-answer', id, n, text }` (v1.75, §9: exactly these keys; text is a string or null for Cancel, checked against the sender's last-sent and current prompt and limited to two/s, burst four, including dropped attempts; refused text on a current id/version becomes a cancel with null; routed only with `ask: true`, never echoed);
|
|
3018
|
+
`{ k: 'hub-action', id, n }` (v1.74, §9: only `k`, a string `id` and a safe-integer `n`; `n` must equal the sender's current offer version and `id` must be in that current list; routed to `action` only in a place with `actions: true`);
|
|
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);
|
|
1061
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));
|
|
1062
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`);
|
|
1063
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);
|
|
1064
3024
|
`{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
|
|
1065
|
-
`{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text }` (authored mode
|
|
3025
|
+
`{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text, rid? }` (authored mode
|
|
1066
3026
|
only), `{ k: 'hub-npc-end', npc }` (§13).
|
|
1067
3027
|
Server → client, in deltas and the WORLD snapshot: `hubPlace` (the place's
|
|
1068
|
-
public manifest, with the `fallY` the session catches at, and `grab` (v1.3) only where the place sets it), `hubAv`, `hud`, `hidden`, `held`, `labels`, `tints` (v1.1,
|
|
3028
|
+
public manifest, with the `fallY` the session catches at, and `grab` (v1.3) only where the place sets it), `hubAv` (player id → avatar; v1.51: always one of `0`-`3`, `avatar % 4` for a player who wears another), `hubAv2` (v1.51, §11: player id → the avatar really worn, for the players who wear `4` or more and by `hubAv`'s rule of who is listed; in the snapshot only while there is such a player, in deltas from the first one on and `{}` once when the last is gone, never sent by a place where nobody has worn one), `hud`, `hidden`, `held`, `labels`, `tints` (v1.1,
|
|
1069
3029
|
actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDoors` (a town's `[{ id, title }]`, each with `featured: true`, `solo: true` or `need: n` where they apply (v1.14),
|
|
1070
3030
|
§5), `spawned` (v1.2, copy id → `{ from, x, y, z, rotationY }`) with
|
|
1071
3031
|
`spawnTemplates` (each template in use → its authored components), `hubWear`
|
|
@@ -1074,6 +3034,9 @@ has worn one, and like `hubAv` without the players in a hidden pair), and in a
|
|
|
1074
3034
|
place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
|
|
1075
3035
|
`{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
|
|
1076
3036
|
`hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing);
|
|
3037
|
+
v1.47 adds `hubNpcEmotes` (NPC actor id → `{ id, at, until }`, simulation ms)
|
|
3038
|
+
only after an NPC has emoted back, then latched when it changes, including
|
|
3039
|
+
`{}` at expiry. A place where no NPC has emoted sends exactly what it did;
|
|
1077
3040
|
and `hubKept` (v1.27, actor id → the player id it is kept for, §6; only once
|
|
1078
3041
|
the place has kept an object with `hub.keepFor`, then whenever it changes,
|
|
1079
3042
|
`{}` once when the last is gone, and in the snapshot only while something is
|
|
@@ -1082,21 +3045,81 @@ wearable the place shows on that player instead of their own, §11; the same
|
|
|
1082
3045
|
rule: only once the place has called `hub.tryOn`, then whenever it changes,
|
|
1083
3046
|
`{}` once when the last is gone, in the snapshot only while one is shown, and
|
|
1084
3047
|
like `hubWear` without the players in a hidden pair). A client lays it over
|
|
1085
|
-
`hubWear`; one that does not know it draws `hubWear` alone.
|
|
3048
|
+
`hubWear`; one that does not know it draws `hubWear` alone. `hubEarned` (v1.53,
|
|
3049
|
+
player id → `{ class, shape, color, name }`, the earned item each shows, §11;
|
|
3050
|
+
latched as `hubWear` is: only once someone in the place shows one, then
|
|
3051
|
+
whenever it changes, `{}` once when the last is gone, in the snapshot only
|
|
3052
|
+
while one is shown, without the players in a hidden pair). In the snapshot
|
|
3053
|
+
only, `hubStuck` (v1.33, `{ to }`: this place answers `hub-unstick`, and `to`
|
|
3054
|
+
is its name for its arrival or null, §5; only a town of a deck with
|
|
3055
|
+
`hub.stuck`; v1.39, with `hook: true` in a place that has the `unstick`
|
|
3056
|
+
hook, and no such key in any other).
|
|
3057
|
+
`hubGlow` (v1.71, §9) is a sorted array of the helloed, arrived player ids
|
|
3058
|
+
with a non-null companion, and nothing else: no look, words or target. Only
|
|
3059
|
+
an opted-in place carries it, in snapshots once anyone in this session has
|
|
3060
|
+
had a companion (including `[]` after the last clears or leaves), and in
|
|
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
|
+
|
|
1086
3075
|
Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
|
|
1087
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
|
|
1088
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),
|
|
1089
3078
|
`{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
|
|
1090
|
-
`{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
|
|
3079
|
+
`{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5; v1.33, after `hub-unstick` too; v1.39, from a place with the `unstick` hook that one carries `stuck: { spot, to }`, whether the player was put at the hook's spot and the name of where they were put, or null),
|
|
3080
|
+
`{ k: 'hub-unstick-to', spot, to }` (v1.39: the answer to `hub-unstick` with `ask: true`, the same two words for what a tap would do now),
|
|
1091
3081
|
`{ k: 'hub-party', members, away, invite, proposal }` (v1.10, on change: the other members here as player ids or null for no party, how many are away, `{ from, username }` or null, `{ id, door, by, username, asked }` or null, told only to the proposer and the members asked),
|
|
1092
3082
|
`{ k: 'hub-where', at }` (v1.9: player id → `{ x, z, where, door, on? }`, the ground spot to 0.1 m, the place's words or null, the door those words name or null, `on` true on its pad), `{ k: 'hub-hud', hud }` (that player's
|
|
1093
3083
|
override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
|
|
1094
|
-
`{ k: 'hub-
|
|
3084
|
+
`{ k: 'hub-companion', c, n }` (v1.71, §9: to its owner alone, the whole private spec or `null`, with version `n` from one counter for the place session; ordinary sends coalesce to four/s per player, equal specs send nothing, fresh hello replays once, leave forgets and absent players are pruned; never in a snapshot or delta);
|
|
3085
|
+
`{ k: 'hub-actions', items, n }` (v1.74, §9: that player's whole private list of `{ id, label }`, or `null` to clear, with its safe-integer version `n`; changed recorded lists advance `n`, ordinary sends coalesce to at most four offers a second per player, and a fresh hello replays the current offer once with its current `n`; offers are forgotten on leave, never in snapshots or deltas; `hubPlace.actions: true` is carried only by an opted-in place);
|
|
3086
|
+
`{ k: 'hub-menu', spec, n }` (v1.79, §9: spec or null to that player alone; never snapshots/deltas, four ordinary offers/s, hello replays once; `hubPlace.menu: true` carried only by an opted-in place);
|
|
3087
|
+
`{ k: 'hub-ask', id, title, max, n }` or `{ k: 'hub-ask', id: null, n }` (v1.75, §9: private prompt or close to that player alone; never in snapshots or deltas; ordinary deliveries coalesce to four/s and fresh hello replays once; `hubPlace.ask: true` is carried only by an opted-in place);
|
|
3088
|
+
`{ k: 'hub-ballot-card', card }` (v1.68, §6: that player's whole choice card,
|
|
3089
|
+
or null when it is taken down; sent on change and again after a fresh
|
|
3090
|
+
`hub-hello` without `again`. `card` is `{ v, mode, title?, text?, until?, faces:
|
|
3091
|
+
[{ id, note?, off?, votes?, mark? }], options: [{ id, text }], lines: [ids],
|
|
3092
|
+
feed: [{ from, to?, line }], picked?, words?, who: { playerId: { name, avatar? } } }`,
|
|
3093
|
+
`v` the card's version, an opaque string echoed as it came (§6 rule A: this
|
|
3094
|
+
server's epoch and a counter; it moves only when the mode, the faces
|
|
3095
|
+
offered or their `off`, the lines offered, the option ids or `picked` change
|
|
3096
|
+
for that player); `who` the username and avatar index of every player the faces and feed name;
|
|
3097
|
+
`picked` `{ face }`, `{ option }` or `{}` (locked on a face not shown);
|
|
3098
|
+
`words` (only for a viewer a block hides someone from) line id → that
|
|
3099
|
+
manifest line with the hidden names taken out, for each line it changes.
|
|
3100
|
+
Never in snapshots or deltas, never sent by a place without `ballot`, which
|
|
3101
|
+
also sends no `hubPlace.ballot`),
|
|
3102
|
+
`{ k: 'hub-vis', hide: [actorIds], show: [actorIds] }` (v1.62, §10: the
|
|
3103
|
+
viewer's whole private visibility override, replacing their previous lists;
|
|
3104
|
+
empty lists restore shared visibility. Sent privately on a changed override
|
|
3105
|
+
set and replayed on a fresh `hub-hello` without `again` while overrides exist.
|
|
3106
|
+
Never in snapshots or deltas, never sent by a place that uses only shared
|
|
3107
|
+
hide/show),
|
|
3108
|
+
`{ k: 'hub-leaving', text }` (v1.52, one player's latest leaving line or null,
|
|
3109
|
+
on change and replayed on a fresh `hub-hello` without `again` when a line is latched;
|
|
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),
|
|
1095
3111
|
`{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
|
|
1096
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),
|
|
1097
|
-
`
|
|
1098
|
-
|
|
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
|
|
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 }`
|
|
1099
3117
|
(v1.4, their wearables, laid over the shared `hubWear` the same way),
|
|
3118
|
+
`{ k: 'hub-earned', hubEarned }` (v1.53, the earned items of players in a
|
|
3119
|
+
hidden pair this player may see, laid over the shared `hubEarned` as
|
|
3120
|
+
`hub-wear` is over `hubWear`; only in a place where someone shows one. There
|
|
3121
|
+
a client that joins afresh -- a `hub-hello` without `again` -- is sent the
|
|
3122
|
+
map as it is, empty or not),
|
|
1100
3123
|
`{ k: 'hub-try', hubTry }` (v1.28, their try-ons, laid over the shared
|
|
1101
3124
|
`hubTry`; only in a place that has called `hub.tryOn` with a hidden pair in
|
|
1102
3125
|
it. Once a place has sent one, a client that joins afresh -- a `hub-hello`
|
|
@@ -1109,8 +3132,8 @@ Blocks: two players a block hides from each other (either one blocked the
|
|
|
1109
3132
|
other; the host answers `session.hub.hiddenPair`, and the block lists never
|
|
1110
3133
|
reach the kit) are taken out of each other's interest sets whatever the
|
|
1111
3134
|
session's size, so neither is sent the other's pose rows or `in`; the shared
|
|
1112
|
-
`hubAv` leaves out every player in such a pair, whose
|
|
1113
|
-
to each player who may see them. Words can name a player too: the shared `hud`
|
|
3135
|
+
`hubAv` (and `hubAv2`, v1.51) leaves out every player in such a pair, whose
|
|
3136
|
+
avatars go by `hub-av` to each player who may see them. Words can name a player too: the shared `hud`
|
|
1114
3137
|
and `labels` carry no such player's username (it reads "someone") and no NPC
|
|
1115
3138
|
line about them, and each player gets the words they may read by `hub-hud` and
|
|
1116
3139
|
`hub-labels`, so nobody is sent a hidden partner's name, a late joiner's
|
|
@@ -1155,6 +3178,201 @@ behind by. Everything else -- objects, `hubAv` (but for Blocks, above),
|
|
|
1155
3178
|
drawing is filtered, and the server's simulation has every player. A
|
|
1156
3179
|
session no bigger than the set is sent one broadcast, as before.
|
|
1157
3180
|
|
|
3181
|
+
### Keeping a visit through a short drop (v1.89)
|
|
3182
|
+
|
|
3183
|
+
A result place may set `hub.resume: { keep: true }` (also valid on a named
|
|
3184
|
+
place). This extends the v1.72 opt-in; `resume: true` keeps its existing
|
|
3185
|
+
immediate leave/re-arrive behavior, and an absent key changes nothing.
|
|
3186
|
+
|
|
3187
|
+
The kit keeps an arrived player's entry for **60 wall-clock seconds** from
|
|
3188
|
+
the first tick observing their absence. A replacement body seen without an
|
|
3189
|
+
absent tick uses the last tick with the old body as its deadline origin.
|
|
3190
|
+
A same-id return strictly inside this window restores the last server pose
|
|
3191
|
+
and facing, `arrivedAt`, hold, tune, first-door provenance, and result state.
|
|
3192
|
+
It runs neither `leave` nor `arrive`; the ordinary private-channel replay
|
|
3193
|
+
restores the HUD, labels and tune. `hub.result`, `hub.tune` and `hub.unlock`
|
|
3194
|
+
remain usable once the body returns, with one result per retained visit.
|
|
3195
|
+
The original duration deadline continues through the drop, and fall handling
|
|
3196
|
+
continues on return. A short settling period rejects stale movement reports.
|
|
3197
|
+
|
|
3198
|
+
At or after 60 s the old visit leaves exactly once. A same-id return after
|
|
3199
|
+
expiry is a fresh arrive, with fresh result eligibility, placement and timing;
|
|
3200
|
+
a new player id is always a separate arrival. Shutdown drains retained players
|
|
3201
|
+
once. A kit-issued travel command bypasses retention once that player disappears.
|
|
3202
|
+
The transport does not expose whether other departures were socket drops,
|
|
3203
|
+
Back or closed tabs, so those departures wait for the same expiry; no claim
|
|
3204
|
+
is made that a host keeps the session process alive throughout the window.
|
|
3205
|
+
Absent bodies are not listed by `hub.players()` and cannot interact as bodies.
|
|
3206
|
+
|
|
3207
|
+
This mode uses the existing `hubPlace.resume: true` and `hub-hello` fields;
|
|
3208
|
+
there are no new wire keys. Retention state is allocated only for this object
|
|
3209
|
+
form. No other deck's behavior, state or wire bytes change.
|
|
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
|
+
|
|
3344
|
+
### A deck's retained-hello signal (v1.89)
|
|
3345
|
+
|
|
3346
|
+
A deck may export `resume(hub, { playerId })` alongside its other hooks. Hook
|
|
3347
|
+
presence is the opt-in; it works in towns as well as result places, without
|
|
3348
|
+
requiring a `resume` manifest key. A non-`again` hello for an already-arrived,
|
|
3349
|
+
retained player queues the signal. Fresh clients reloading under that retained
|
|
3350
|
+
id and clients sending `resume: true` both qualify. First arrivals and genuine
|
|
3351
|
+
re-arrivals do not. The keep mode's server-generated silent-return hello also
|
|
3352
|
+
qualifies, so a short drop can restore a deck's current tutorial HUD or pointer.
|
|
3353
|
+
|
|
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.
|
|
3372
|
+
|
|
3373
|
+
A deck without this hook allocates no pending-signal state and receives no
|
|
3374
|
+
callback. No new packets, wire keys or manifest fields are added.
|
|
3375
|
+
|
|
1158
3376
|
## 13. NPCs
|
|
1159
3377
|
|
|
1160
3378
|
HUB.md decision 7: an NPC's **body** is an actor in the place's session and its
|
|
@@ -1163,22 +3381,104 @@ HUB.md decision 7: an NPC's **body** is an actor in the place's session and its
|
|
|
1163
3381
|
|
|
1164
3382
|
```jsonc
|
|
1165
3383
|
"HubNpc": {
|
|
1166
|
-
"name": "Rowan, the greeter", // shown on the Talk button, the panel and before every line
|
|
3384
|
+
"name": "Rowan, the greeter", // shown on the Chat or Talk button, the panel and before every line
|
|
1167
3385
|
"character": "greeter", // optional: the castle.json characterBundle character that is its mind
|
|
1168
3386
|
"follow": "greeterFollow", // optional: the gameplay object whose holder the body follows
|
|
1169
|
-
"talkRange": 3.5
|
|
3387
|
+
"talkRange": 3.5, // optional, metres (≤ 8)
|
|
3388
|
+
"turnsAtOnce": 3, // optional (v1.83), integer 1-3; overrides hub.npcs.turnsAtOnce
|
|
3389
|
+
"voice": { "type": "townsfolk", "pitch": 220 }, // optional, heard in a deck with `soundscape` (§6): its babble voice (§6, v1.56)
|
|
3390
|
+
"reactions": { // optional (v1.47), per kit emote
|
|
3391
|
+
"wave": { "emote": "bow", "lines": ["Welcome back!"] }
|
|
3392
|
+
}
|
|
1170
3393
|
// any other keys are the place's own (the town's `role`)
|
|
1171
3394
|
}
|
|
1172
3395
|
```
|
|
1173
3396
|
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
3397
|
+
`HubNpc.voice` is client-only and used only when `soundscape.babble` is on.
|
|
3398
|
+
In v1.56, optional `type` selects `townsfolk`, `lively`, `gruff` or `gentle`
|
|
3399
|
+
before the role/character/name keyword default (§6); invalid types fall back.
|
|
3400
|
+
`pitch` remains 80–500 Hz; legacy `rate` 4–10 maps linearly to
|
|
3401
|
+
synthesis rate 2.5–6 (7 → 4.25). Waveform `timbre` names are accepted and
|
|
3402
|
+
ignored. Omitted or invalid fields keep the deterministic character voice;
|
|
3403
|
+
§6 describes the four round-6 types, keyword table, per-NPC variation and limits.
|
|
3404
|
+
|
|
3405
|
+
**Reacting to emotes (v1.47).** A free body answers nearby player emotes as
|
|
3406
|
+
§6 describes, with the same motion and emoji every client draws for a
|
|
3407
|
+
player. `HubNpc.reactions` replaces defaults per emote: `emote` is a kit id
|
|
3408
|
+
or null for none; `lines` is up to six strings, each cut to 80 characters.
|
|
3409
|
+
An empty list means no speech. Missing fields keep their defaults. The kit's
|
|
3410
|
+
public lines are wave: "Hello there!", "Hi!", "Hey, hi!"; dance: "Nice
|
|
3411
|
+
moves!", "Ooh, let me try!"; cheer: "Woo!", "Yay!"; bow: "Likewise!", "Oh,
|
|
3412
|
+
how polite!"; spin: "Whee!", "Dizzy yet?". About one in three reactions
|
|
3413
|
+
chooses a line, deterministically per body and tick. These are authored
|
|
3414
|
+
words, drawn through the public `npcLine` speech path, never a mind's reply.
|
|
3415
|
+
`npcReact` can refuse a busy character the kit cannot tell is busy, or
|
|
3416
|
+
replace its emote or line. The hook's line is spoken whenever supplied;
|
|
3417
|
+
null removes speech. Invalid emote ids keep the default or props choice.
|
|
3418
|
+
`npcReact` and `npcOpening` are synchronous hooks. A promise or thenable
|
|
3419
|
+
is ignored; a rejection is caught and logged once with fixed words, never
|
|
3420
|
+
the error's text. A shorter later line does not shorten another listener's
|
|
3421
|
+
active speech deadline; reactions wait for the longest one.
|
|
3422
|
+
|
|
3423
|
+
### A preferred talk target and movement hold (v1.90)
|
|
3424
|
+
|
|
3425
|
+
`hub.preferNpc(playerId, npcId | null)` sets one player's preferred physical
|
|
3426
|
+
NPC for the Chat button; null clears it. Returns false for a missing player or
|
|
3427
|
+
NPC, otherwise true. While that NPC is within its normal talk range, the button
|
|
3428
|
+
chooses it; outside range or when absent, the nearest NPC wins as before.
|
|
3429
|
+
This is a private hint, not chat admission: all server chat checks still apply.
|
|
3430
|
+
The preference lasts until cleared or the player leaves, and is replayed on a
|
|
3431
|
+
retained hello. The kit sends `hub-npc-preferred` only to that player, only after
|
|
3432
|
+
opt-in; decks that never call it keep their existing wire bytes and behavior.
|
|
3433
|
+
|
|
3434
|
+
`hub.npc(npcId).holdMovement(boolean)` optionally holds a physical NPC at its
|
|
3435
|
+
current position until cleared with false. Engaging the hold cancels its current
|
|
3436
|
+
walk/follow and any already queued physics translation. While held, `walkTo`,
|
|
3437
|
+
`home`, `follow` and asynchronous follow-token reads cannot start movement;
|
|
3438
|
+
the kit also checks the hold before each movement tick. Releasing it allows new
|
|
3439
|
+
walks and token reads to move the body again; cancelled walks are not replayed.
|
|
3440
|
+
The place owns when to engage and clear this server-only flag. It emits no wire
|
|
3441
|
+
message, does nothing on a virtual companion, and is absent by default, preserving
|
|
3442
|
+
existing movement behavior in decks that never call it.
|
|
3443
|
+
|
|
3444
|
+
**What the kit does with a body.** Near one, a player gets a Chat with button
|
|
3445
|
+
when the actor names a character, otherwise Talk to (hub chrome, v1.46).
|
|
3446
|
+
Opening a conversation is the place server's decision. In v1.83 a body has
|
|
3447
|
+
`turnsAtOnce` conversation slots (integer 1-3, default 1): the body's
|
|
3448
|
+
`HubNpc.turnsAtOnce` overrides `hub.npcs.turnsAtOnce`. A new speaker gets the
|
|
3449
|
+
place's `busy` line only when all slots are occupied; an existing speaker can
|
|
3450
|
+
continue, with at most one unanswered turn per speaker. Each speaker has their
|
|
3451
|
+
own opening, notes and pending turn. The `turnsPerMinute` window remains shared
|
|
3452
|
+
by the body, so more slots do not increase its budget. A speaker tapping Done,
|
|
3453
|
+
walking more than 8 m away, leaving, or saying nothing for 90 s closes only
|
|
3454
|
+
their conversation and frees one slot. `open` refuses with `why: "busy"` and a
|
|
3455
|
+
turn from another player when slots are full refuses with `HUB_NPC_BUSY`.
|
|
3456
|
+
|
|
3457
|
+
In v1.84 a connection returning under the same player id with its talk panel
|
|
3458
|
+
still open re-attaches through the existing `hub-npc-open` request. The visible
|
|
3459
|
+
transcript stays; the server opens a new conversation and issues fresh notes,
|
|
3460
|
+
while the mind keeps its per-player memory. A pending question waits for that
|
|
3461
|
+
open. A turn refused with `HUB_NPC_NOT_TALKING` can also re-attach and retry
|
|
3462
|
+
once; no question retries re-attachment twice, and an admitted turn is never
|
|
3463
|
+
replayed merely because the connection returned. A refused re-attach shows
|
|
3464
|
+
the place's supplied busy/unavailable line, otherwise "Lost the thread there.
|
|
3465
|
+
Tap to talk again.", before closing; unsent words return to the input when
|
|
3466
|
+
that body is next opened. Owner companions use the same recovery. A new player
|
|
3467
|
+
id still clears the old panel and drafts. No wire key changes, no traffic
|
|
3468
|
+
changes without reconnect or a stale-panel refusal, and no player's words
|
|
3469
|
+
reach another player or an ambient line.
|
|
3470
|
+
|
|
3471
|
+
With one slot an open conversation holds the body still facing its speaker,
|
|
3472
|
+
through the gaps between turns, exactly as before. With multiple slots opening
|
|
3473
|
+
or continuing a conversation never interrupts or holds a place `walkTo` or a
|
|
3474
|
+
follow; the body faces a speaker only while neither walking nor following.
|
|
3475
|
+
Otherwise it walks where the place sends it, follows, or faces what it was told
|
|
3476
|
+
to, in that order. With both new keys absent, stored manifest, messages, handle
|
|
3477
|
+
behavior and timing are byte-identical to before (apart from the handle-only
|
|
3478
|
+
`talkingWith` and `turnsAtOnce` properties). An explicit 1 adds no stored
|
|
3479
|
+
manifest or wire key.
|
|
3480
|
+
Walking is a straight line at 2.6 m/s with no navigation: put NPCs where a
|
|
3481
|
+
straight walk crosses nothing solid.
|
|
1182
3482
|
|
|
1183
3483
|
```js
|
|
1184
3484
|
const npc = hub.npc('greeter'); // or hub.npcs()
|
|
@@ -1188,10 +3488,78 @@ npc.walkTo({ x, z }, { stopAt: 0.4, then: () => … });
|
|
|
1188
3488
|
npc.home(then?); // back where the scene put it, facing as it did
|
|
1189
3489
|
npc.follow(playerId); // or null
|
|
1190
3490
|
npc.stop(); // no walk, no follow
|
|
1191
|
-
npc.end(); // end its
|
|
1192
|
-
npc.at; npc.talkingTo; npc.following; npc.walking; npc.busy; npc.props;
|
|
3491
|
+
npc.end(); // end all its open conversations
|
|
3492
|
+
npc.at; npc.talkingTo; npc.talkingWith; npc.turnsAtOnce; npc.following; npc.walking; npc.busy; npc.props;
|
|
3493
|
+
```
|
|
3494
|
+
|
|
3495
|
+
`talkingTo` is the earliest still-open speaker, or null; with one conversation
|
|
3496
|
+
its meaning is unchanged. `talkingWith` is the array of player ids in open
|
|
3497
|
+
order, empty when none, on every handle (never a wire field). `busy` with one
|
|
3498
|
+
slot remains talking-or-walking-or-following; with multiple slots it means
|
|
3499
|
+
all conversation slots occupied, or walking, or following. In v1.83 the
|
|
3500
|
+
handle-only `turnsAtOnce` exposes the body's effective capacity: its
|
|
3501
|
+
`HubNpc.turnsAtOnce` override, else `hub.npcs.turnsAtOnce`, else 1. Virtual
|
|
3502
|
+
companions always have 1. The property exists even when both keys are absent;
|
|
3503
|
+
it changes no stored object, wire bytes, or existing handle behavior.
|
|
3504
|
+
|
|
3505
|
+
**Privacy with concurrent speakers (v1.83).** A reply, notes, opening,
|
|
3506
|
+
`persistentAsks`, and anything derived from what a player typed belong only to
|
|
3507
|
+
that speaker. Panel events go only to them; speech with those words uses
|
|
3508
|
+
`say(text, { to: [speaker] })`. A second player's open, close, leave, notes or
|
|
3509
|
+
reply never changes the first player's panel. Ambient authored, busy and budget
|
|
3510
|
+
lines may be spoken over the body for everyone, but must never contain player
|
|
3511
|
+
input or a mind's reply to another player. Place hooks must preserve this rule;
|
|
3512
|
+
the kit targets multi-slot authored answers that receive player input only to
|
|
3513
|
+
that player. Ghost admits up to six simultaneous turns per place-mind character,
|
|
3514
|
+
ordered per speaker; its busy/budget error mapping is unchanged.
|
|
3515
|
+
|
|
3516
|
+
**Companion chat (v1.71).** A place can declare a follower and owner-only
|
|
3517
|
+
chat together:
|
|
3518
|
+
|
|
3519
|
+
```json
|
|
3520
|
+
"companion": { "chat": { "character": "companion", "name": "Chirp" } },
|
|
3521
|
+
"npcs": { "slot": "main" }
|
|
1193
3522
|
```
|
|
1194
3523
|
|
|
3524
|
+
Both manifest forms normalise to `place.companion === true`. The object
|
|
3525
|
+
form also has `place.companionChat = { character, name }`; the public place
|
|
3526
|
+
carries `companion: true` and `companionChat: { name }` only, never the
|
|
3527
|
+
character id. Chat requires the place's `npcs` mind slot and a character id
|
|
3528
|
+
in the deck's bundle. Unknown keys in `companion` or `chat` are errors.
|
|
3529
|
+
|
|
3530
|
+
The kit lazily creates one **virtual NPC record** when an arrived owner
|
|
3531
|
+
opens `companion:<playerId>`. Only that sender's own id is accepted, without
|
|
3532
|
+
a distance check (virtual distance is zero). Malformed ids, someone else's
|
|
3533
|
+
id, not-arrived players, and places without chat get the ordinary unknown
|
|
3534
|
+
NPC response. The record is removed on leave, forget or absent-owner pruning.
|
|
3535
|
+
It is never a scene actor, body, snapshot entry or member of `hub.npcs()`;
|
|
3536
|
+
it never moves, faces, follows, reacts, speaks ambient lines or greets.
|
|
3537
|
+
|
|
3538
|
+
Conversation hooks (`npcOpening`, `npcContext`, `npcAsks`, `npcLine`, `npcHeard`,
|
|
3539
|
+
`npcTools`, `npcTool`) receive the usual `hub.npc(id)` handle with
|
|
3540
|
+
`id: "companion:<playerId>"`, `owner: playerId`,
|
|
3541
|
+
`props: { role: "companion", name, character }`, `at` equal to the owner's
|
|
3542
|
+
current position, and `busy: false`. `say`, `face`, `walkTo`, `home`,
|
|
3543
|
+
`follow` and `stop` are safe no-ops; `end` closes the conversation.
|
|
3544
|
+
|
|
3545
|
+
**Every companion line is owner-only**, including authored openings,
|
|
3546
|
+
scripted answers and busy/budget/unavailable refusals. These use the owner's
|
|
3547
|
+
existing panel messages, never a public or private scene label or bubble.
|
|
3548
|
+
Mind replies are read through the owner's existing status path and shown in
|
|
3549
|
+
that panel alone. Nothing the owner typed and nothing the companion says
|
|
3550
|
+
may be sent to another player, stored in a snapshot/delta, or passed into
|
|
3551
|
+
another player's notes. Place code must preserve this rule in its hooks.
|
|
3552
|
+
The record keeps the usual one unanswered turn, per-record
|
|
3553
|
+
`turnsPerMinute` budget, one tool lookup per reply, speaker-gone end and
|
|
3554
|
+
90 s idle end. Ghost's speaker gate remains unchanged.
|
|
3555
|
+
|
|
3556
|
+
When the local player has a follower, the existing Chat with button offers
|
|
3557
|
+
its manifest name if no physical NPC is in talk range (a body wins). A
|
|
3558
|
+
44 px hit area over the projected follower also opens it, using local
|
|
3559
|
+
chrome pointer handling. The existing panel uses the manifest name and the
|
|
3560
|
+
same questions, typing gate and reply drawing. `companion: true` alone
|
|
3561
|
+
creates no chat state or entry point and keeps its existing wire bytes.
|
|
3562
|
+
|
|
1195
3563
|
**Minds.** A place's minds live in a persistent world that carries the deck's
|
|
1196
3564
|
shared characters (`docs/internal/shared-character-world-v1.md` in
|
|
1197
3565
|
castle-experimental-web): `npcs.route` names one of `server.destinations`
|
|
@@ -1221,7 +3589,8 @@ door that names its own session.
|
|
|
1221
3589
|
| --- | --- |
|
|
1222
3590
|
| `route` | optional; a `server.destinations` route with `characters: "shared"`, joined only on SDKs without place characters. Without a route the minds are the place's alone: every layer addresses ghost's one place mind |
|
|
1223
3591
|
| `slot` | 1-64 of `[A-Za-z0-9_.-]`; default `"main"`; the fallback route's world. A world keeps the character definitions it was created with: after changing the bundle's characters, name a new slot (ghost refuses turns in the old world with `CAULDRON_SHARED_CHARACTER_CONFLICT`) |
|
|
1224
|
-
| `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer |
|
|
3592
|
+
| `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer; shared by all its speakers |
|
|
3593
|
+
| `turnsAtOnce` | v1.83, integer 1-3, default 1: open conversations per body; `HubNpc.turnsAtOnce` overrides it. Only values above 1 enter the stored manifest; absent/1 adds no wire key |
|
|
1225
3594
|
| `disclosure` | `"participants"` or `"world"`: read, and since v1.17 not acted on. A player's conversation with a character is theirs alone (below) |
|
|
1226
3595
|
| `followSec` | 10-600, default 120: how long a body follows before it goes home |
|
|
1227
3596
|
|
|
@@ -1233,6 +3602,186 @@ instead, so a crowd degrades to authored lines rather than a queue. The reply
|
|
|
1233
3602
|
is ghost's text, shown in the speaker's panel and over the body for the
|
|
1234
3603
|
speaker alone.
|
|
1235
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
|
+
|
|
3652
|
+
**Opening a chat (v1.37, v1.46).** The place's `npcOpening` gives the first
|
|
3653
|
+
words and up to three questions, with up to nine more to offer later. A hook
|
|
3654
|
+
that gives text keeps exactly its own words and questions; text with no asks
|
|
3655
|
+
gets no default questions. Without the hook, or when it gives no usable text,
|
|
3656
|
+
a mind opens with "Hi, I'm <first name>! Ask me anything." (the name up to the
|
|
3657
|
+
first comma), and "Who are you?", "What do you do here?", "Tell me a secret!".
|
|
3658
|
+
Its later questions are "What's your favourite thing here?", "What should I
|
|
3659
|
+
try first?", "Do you have any friends here?", "What's the funniest thing
|
|
3660
|
+
you've seen?", "What do you dream about?", "What makes you laugh?". The
|
|
3661
|
+
default opening enters that conversation's notes just like a place opening,
|
|
3662
|
+
only where the place defines `npcContext`. A body without a mind gets no
|
|
3663
|
+
default opening and keeps its `npcLine` hello.
|
|
3664
|
+
|
|
3665
|
+
v1.47: every open gets an integer sequence number increasing per NPC for
|
|
3666
|
+
this server's lifetime. `npcOpening` receives it as `info.conversation`;
|
|
3667
|
+
`npcHeard` and `npcLine` for an authored say receive the number captured
|
|
3668
|
+
when those words were admitted, before any await. A place can match the
|
|
3669
|
+
words to the opening it gave. After an awaited send settles, the kit checks
|
|
3670
|
+
that the same conversation is still open with the same bound account key
|
|
3671
|
+
and exact player body before calling a place hook with the player's words.
|
|
3672
|
+
The kit never hands a place words from a conversation that has ended or
|
|
3673
|
+
changed hands, including a close and reopen by the same player or a player
|
|
3674
|
+
id reused by another account; dropped words never enter a log.
|
|
3675
|
+
|
|
3676
|
+
v1.47: the speaker's own `inspect` may carry each character's
|
|
3677
|
+
`privateState.nextGreeting: { text, at }`. The server keeps the text for
|
|
3678
|
+
that authenticated account, player body and character until the player
|
|
3679
|
+
leaves, removing control characters, trimming it and cutting it to 240
|
|
3680
|
+
characters. Older bundles
|
|
3681
|
+
without it keep the opening above. When present it replaces the opening's
|
|
3682
|
+
text; the place's asks and more stay its own, or the v1.46 defaults apply
|
|
3683
|
+
where no place opening was given. `npcOpening` receives `info.greeting`,
|
|
3684
|
+
the string or null, along with `met`, so it can use the memory in its own
|
|
3685
|
+
opening choices. The greeting enters the conversation's notes under the
|
|
3686
|
+
same rule as any opening. It reaches only that player's open or opening
|
|
3687
|
+
update messages and notes (and the v1.76 private bubble below), never a
|
|
3688
|
+
public bubble, snapshot, log line or another player.
|
|
3689
|
+
Guests have no greeting cache. The account and exact body are checked
|
|
3690
|
+
again before using a cached greeting; replacing either invalidates it.
|
|
3691
|
+
An inspect read that finishes after departure or a change of account or
|
|
3692
|
+
body cannot fill the cache for the new visitor.
|
|
3693
|
+
The conversation's opening and notes carry the same account and body
|
|
3694
|
+
binding. Before admitting a turn or sending either, the server checks it
|
|
3695
|
+
again; a mismatch ends the conversation and clears both, without sending
|
|
3696
|
+
the old words, even when a turn asks for its notes to be sent again.
|
|
3697
|
+
|
|
3698
|
+
If inspect finishes while the panel is already open, before that player has
|
|
3699
|
+
said anything in the conversation, `{ k: 'hub-npc-opening', npc, text }`
|
|
3700
|
+
replaces the NPC's first line for that player alone. Questions stay as they
|
|
3701
|
+
were, and the opening and its private notes are updated together. Once the
|
|
3702
|
+
player has sent words, or the panel has closed, no line is replaced. Older
|
|
3703
|
+
clients ignore the unknown message.
|
|
3704
|
+
|
|
3705
|
+
#### Personalised walk-up bubble (v1.76)
|
|
3706
|
+
|
|
3707
|
+
After a signed-in speaker's successful inspect, the server privately sends
|
|
3708
|
+
`{ k: 'hub-npc-hooks', hooks: [{ npc, character }] }` for each physical NPC
|
|
3709
|
+
body with a mind whose character has a due greeting for that speaker.
|
|
3710
|
+
The message carries ids only, never text. Guests, virtual companions and
|
|
3711
|
+
owner records get no hooks; no message is sent when the list is empty.
|
|
3712
|
+
Older clients ignore it.
|
|
3713
|
+
|
|
3714
|
+
The client keeps these ids on that net until a session switch or reset.
|
|
3715
|
+
When idle within that body's Chat prompt range and with no panel open or
|
|
3716
|
+
opening, it drops the character's hooks and sends one read:
|
|
3717
|
+
`{ type: 'status', operationId: 'greeting:' + character }`. A failed read
|
|
3718
|
+
logs once without error details and never retries. Duplicate hook messages
|
|
3719
|
+
and other bodies sharing that character do not read it again in the session.
|
|
3720
|
+
Opening that character's chat first drops its hooks without reading, even
|
|
3721
|
+
when inspect finishes after the panel opens.
|
|
3722
|
+
|
|
3723
|
+
Ghost returns `{ characterId, greeting: { text, at } | null }` only once
|
|
3724
|
+
per due hook, marking it shown in the same transaction; later reads return
|
|
3725
|
+
null. The kit keeps `status` as the read type for the current host.
|
|
3726
|
+
`greeting:` is reserved: such an operation id is refused for a turn and its
|
|
3727
|
+
status can never look up or deliver a turn.
|
|
3728
|
+
|
|
3729
|
+
Before showing a result, the server rechecks the signed-in account and exact
|
|
3730
|
+
speaker body captured before the read, the returned character id and a
|
|
3731
|
+
non-empty line cleaned and capped as above. It picks the nearest physical
|
|
3732
|
+
body with that mind, excluding owner records and bodies talking with another
|
|
3733
|
+
player, within that body's Chat range plus 2 flat metres (5.5 m by default).
|
|
3734
|
+
The ordinary 7 s speech label is sent with `to: [speaker]` and
|
|
3735
|
+
`about: speaker`. No text enters a public label, snapshot, log or place hook.
|
|
3736
|
+
A null or stale result says nothing. The cached greeting stays: the next
|
|
3737
|
+
chat still opens with it so that player can answer. Places without minds or
|
|
3738
|
+
due greetings keep their existing lines and messages. No place opt-out is
|
|
3739
|
+
added.
|
|
3740
|
+
|
|
3741
|
+
For a mind, the client reads `inspect` when the Chat prompt first shows
|
|
3742
|
+
(v1.47), before the panel opens. Pending reads are shared; a success is
|
|
3743
|
+
remembered on that net. While it is pending, or if ghost refuses it, only the
|
|
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
|
|
3758
|
+
who may speak; the kit changes no gate. A player who may type sees "Ask <first
|
|
3759
|
+
name> anything…" at the bottom, with chips below it under "or try:". The field
|
|
3760
|
+
gets focus on a desktop with a fine pointer and no touch, never on a touch
|
|
3761
|
+
screen. While a mind answers, a three-dot bubble appears on its side of the
|
|
3762
|
+
log (a static "…" with reduced motion); a reply or scripted line removes it.
|
|
3763
|
+
After a reply or scripted line, up to three chips return: a status result's
|
|
3764
|
+
`suggestions` (or `response.suggestions`) array of strings first, otherwise
|
|
3765
|
+
unused questions from `asks` then `more`. v1.80: the latest `persistentAsks`
|
|
3766
|
+
from the place's notes lead either source, deduplicated into the same
|
|
3767
|
+
three-chip row. Changed offers refresh the row with its current suggestions,
|
|
3768
|
+
keeping chips hidden while a turn is pending. Withdrawn offers stay out of
|
|
3769
|
+
both sources until the place offers them again, even if never sent.
|
|
3770
|
+
A question the player already sent
|
|
3771
|
+
is never offered again in that conversation, except while the place keeps
|
|
3772
|
+
it in `persistentAsks`; when none remain there are no
|
|
3773
|
+
chips. The log keeps its height and scrolls a new reply to its first word
|
|
3774
|
+
(v1.35), leaving a player reading earlier words where they are. A body without
|
|
3775
|
+
a mind keeps its authored-message path, text box and questions. An authored
|
|
3776
|
+
send waits for its reply or 1.2 s before the chips return; only a reply marks
|
|
3777
|
+
the question used, so a dropped send can be retried. Each send carries a fresh
|
|
3778
|
+
`rid`, echoed by its reply: only a matching id acknowledges the pending
|
|
3779
|
+
question. A reply without `rid` keeps the older-server behaviour. Sends inside
|
|
3780
|
+
the server's
|
|
3781
|
+
900 ms cooldown are held back even when its reply came at once. A scripted
|
|
3782
|
+
refusal of a mind turn carries its operation id: only a matching line ends
|
|
3783
|
+
that turn's poll; a late or untagged line leaves a newer turn alone.
|
|
3784
|
+
|
|
1236
3785
|
**A player's conversation is theirs alone (v1.17).** What a player types to a
|
|
1237
3786
|
character, and what the character answers, reaches no other player: not as a
|
|
1238
3787
|
bubble, not through the character's memory, not in another layer or a later
|
|
@@ -1270,23 +3819,82 @@ newest. A client can therefore leave its own words, but never the place's
|
|
|
1270
3819
|
notes, out of true. The notes are part of the turn's input: ghost keeps them
|
|
1271
3820
|
with the player's words as that player's conversation, so they should be facts
|
|
1272
3821
|
about this player and this place, never another player's private state. The
|
|
1273
|
-
player's panel shows only their words. After
|
|
1274
|
-
|
|
3822
|
+
player's panel shows only their words. After an admitted turn's send settles,
|
|
3823
|
+
if its conversation and bound speaker are still current,
|
|
3824
|
+
the kit calls `npcHeard(hub, npc, playerId, { text, conversation })` with the
|
|
3825
|
+
words alone and the conversation number captured at admission. Without
|
|
1275
3826
|
`npcContext` a turn is the words alone, as before.
|
|
1276
3827
|
|
|
3828
|
+
**Questions kept on offer (v1.80).** A place may define the synchronous
|
|
3829
|
+
`npcAsks(hub, npc, playerId) -> { persistentAsks: string[] } | null` to keep
|
|
3830
|
+
an action available after a reply, such as "I brought you something!" while
|
|
3831
|
+
the player carries a gift. The kit calls it with the speaker's notes when
|
|
3832
|
+
the conversation opens, every second while it lasts, and when issuing fresh
|
|
3833
|
+
notes for a refused turn. It keeps at most two non-empty strings, each
|
|
3834
|
+
trimmed and cut to 40 characters, deduplicated after cutting; other values
|
|
3835
|
+
are dropped. A throw is caught and logged once with fixed words, never the
|
|
3836
|
+
hook's words or error text. Promises and thenables are ignored; rejected
|
|
3837
|
+
ones are caught and logged once with fixed words.
|
|
3838
|
+
|
|
3839
|
+
Where the hook exists, `hub-npc-notes` carries `persistentAsks`, an array
|
|
3840
|
+
that is empty for null or no usable questions. A changed offer issues notes
|
|
3841
|
+
even when `prefix` has not changed; a non-empty offer can also issue notes
|
|
3842
|
+
with a null prefix where there is no `npcContext`. The kit rechecks the same
|
|
3843
|
+
conversation, account and player body before sending, and sends only to
|
|
3844
|
+
that talking player, never in public labels, snapshots or deltas. Chips do
|
|
3845
|
+
not become mind notes or change the turn's input. Each client refill puts
|
|
3846
|
+
the latest offer before status suggestions or unused opening questions,
|
|
3847
|
+
deduplicated into the existing three-chip row. These questions may return
|
|
3848
|
+
after being sent while the place keeps offering them. Changed offers refresh
|
|
3849
|
+
the row with its current suggestions, unless a turn is pending, when chips
|
|
3850
|
+
stay hidden. A question removed from the offer stays out of suggestions and
|
|
3851
|
+
unused opening questions until the place offers it again, even if never sent.
|
|
3852
|
+
Latest notes with no offer withdraw all previous offers. A new
|
|
3853
|
+
conversation starts with no previous offer or withdrawals. Without `npcAsks`, no message
|
|
3854
|
+
has a `persistentAsks` key and the client uses its existing refill path;
|
|
3855
|
+
notes messages stay byte-identical. Older clients ignore the new key.
|
|
3856
|
+
|
|
1277
3857
|
Several bodies may share one character (one mind for every barker): a turn
|
|
1278
3858
|
goes to the body its speaker is talking to.
|
|
1279
3859
|
|
|
3860
|
+
**Tools (v1.66).** Notes are paid for on every turn; a place that knows a lot
|
|
3861
|
+
(a town's every door) can instead let a mind look things up. `npcTools` declares
|
|
3862
|
+
what it may ask; the kit sends the declarations with a newly admitted turn (a
|
|
3863
|
+
replay keeps the first admission's), and the mind may make **one** lookup per
|
|
3864
|
+
reply: the platform asks the place's server, the kit checks the call is for a
|
|
3865
|
+
turn it admitted, for that turn's speaker and character, of a declared name,
|
|
3866
|
+
and not yet used, then calls `npcTool(hub, npc, playerId, name, input)`. Its
|
|
3867
|
+
answer goes to the mind and nowhere else; after 1.5 s (or on any error) the mind
|
|
3868
|
+
is told the lookup is unavailable and answers without it. A reply then takes
|
|
3869
|
+
two model calls instead of one, from the same per-turn allowance.
|
|
3870
|
+
|
|
3871
|
+
The same rules as notes hold for results: never `npcHeard` or `npcLine` text,
|
|
3872
|
+
never another player's typing or private state (a player's name is the only
|
|
3873
|
+
player-made text a result may carry). A lookup is read-only, except actions a
|
|
3874
|
+
place lists and checks itself (the town's `pointTo`: a pointer only the asker
|
|
3875
|
+
sees). Nothing a lookup returns is shown to any other player. Who may talk to
|
|
3876
|
+
an NPC is unchanged. The kit logs a lookup's name and duration, never its input
|
|
3877
|
+
or answer. Without `npcTools` a turn is sent as before; without `npcTool` the
|
|
3878
|
+
kit does not listen for lookups at all.
|
|
3879
|
+
|
|
1280
3880
|
**Authored lines.** Where a body has no mind -- no `npcs`, no `character`, or a
|
|
1281
3881
|
session the host brokers no characters into (the dev serve; a host without
|
|
1282
3882
|
place characters; on an older SDK, an account the route is not open to; the
|
|
1283
3883
|
shared-character pilot is admin-gated) -- conversations still
|
|
1284
3884
|
open and the place answers every turn from `npcLine(hub, npc, playerId, { why,
|
|
1285
|
-
text })`, with no model call. `why` is `"hello"` (a conversation
|
|
1286
|
-
`"authored"` (the player said `text
|
|
1287
|
-
`"
|
|
1288
|
-
|
|
1289
|
-
|
|
3885
|
+
text, conversation })`, with no model call. `why` is `"hello"` (a conversation
|
|
3886
|
+
opened), `"authored"` (the player said `text`; v1.47 `conversation` matches the
|
|
3887
|
+
opening), `"busy"`, `"budget"` or
|
|
3888
|
+
`"unavailable"`. Ambient authored lines are the place's own words and go over
|
|
3889
|
+
the body for everyone. In v1.83 a multi-slot body's `"authored"` answer to
|
|
3890
|
+
player input is sent over the body only to that speaker, as well as in their
|
|
3891
|
+
own panel; even if authored, a response may derive from that player's words.
|
|
3892
|
+
Hello, busy, budget and unavailable lines remain ambient and must carry no
|
|
3893
|
+
player input. A one-slot body retains the existing authored line bytes, so its
|
|
3894
|
+
place hooks must keep all those public words free of player input.
|
|
3895
|
+
Where a body has a mind, `busy`, `budget` and `unavailable` lines
|
|
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
|
|
1290
3898
|
place should have them acknowledge the player ("give me a moment") rather than
|
|
1291
3899
|
answer a question they did not ask.
|
|
1292
3900
|
|
|
@@ -1306,6 +3914,48 @@ what ghost verified: `hub.results` (§7) and a `carry.result` with
|
|
|
1306
3914
|
|
|
1307
3915
|
## 14. Per-player progress (v1.2)
|
|
1308
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
|
+
|
|
1309
3959
|
A place that keeps a player's progress between visits keeps it in **deck
|
|
1310
3960
|
scope keyed by the player's user id**: `hub.session.storage.deck` under
|
|
1311
3961
|
`'<name>:<userId>'`, with the `userId` the kit hands it (`arrive`,
|
|
@@ -1347,12 +3997,378 @@ What the kit and Castle promise, and what they do not:
|
|
|
1347
3997
|
| 8 avatar plumbing | §11, owned by the kit |
|
|
1348
3998
|
| 9 arrival facing | §5, `arrival.face` |
|
|
1349
3999
|
|
|
4000
|
+
## Cell interest (v1.65)
|
|
4001
|
+
|
|
4002
|
+
`hub.interest: "cells"` opts the deck's places into interest management. Any
|
|
4003
|
+
other value is a manifest error: `hub.interest must be "cells" (or left out).`
|
|
4004
|
+
The public `hubPlace` carries `interest: "cells"` and the place's
|
|
4005
|
+
`nearestPlayers` only while this mode is active. Its default is 48 other
|
|
4006
|
+
players (`NEAREST_PLAYERS_CELLS`); an explicit `hub.nearestPlayers` or place's
|
|
4007
|
+
`nearestPlayers` still wins, with the existing 1..100 bound. Without the key,
|
|
4008
|
+
the default stays 30 and all wire traffic and behavior stay unchanged.
|
|
4009
|
+
|
|
4010
|
+
Each place reads its own scene's top-level table, authored as:
|
|
4011
|
+
|
|
4012
|
+
```json
|
|
4013
|
+
"cells": {
|
|
4014
|
+
"version": 1,
|
|
4015
|
+
"eyeMax": 14,
|
|
4016
|
+
"hysteresis": 2.5,
|
|
4017
|
+
"cells": [
|
|
4018
|
+
{ "id": "square", "outline": [[-20, -20], [20, -20], [20, 20], [-20, 20]],
|
|
4019
|
+
"sees": ["square"], "why": "Open square" }
|
|
4020
|
+
]
|
|
4021
|
+
}
|
|
4022
|
+
```
|
|
4023
|
+
|
|
4024
|
+
Outlines are polygons in world metres, x east and z south, in either winding;
|
|
4025
|
+
they need not be rectangular. Version must be 1, ids must be unique strings,
|
|
4026
|
+
outlines must have at least three finite `[x,z]` pairs, and `sees` must include
|
|
4027
|
+
the cell itself and refer only to known ids. The authored polygons partition
|
|
4028
|
+
the ground. Actor `cell` tags do not decide interest: the server resolves
|
|
4029
|
+
players and moving objects from their current body positions. It keeps their
|
|
4030
|
+
previous cell while they remain within `hysteresis` metres of its polygon
|
|
4031
|
+
(default 2.5). `eyeMax` and `why` describe the authored table; they do not
|
|
4032
|
+
change the server's view radius.
|
|
4033
|
+
|
|
4034
|
+
A viewer sees the union of `sees` from all polygons within **10 metres** of
|
|
4035
|
+
its body (`VIEW_RADIUS_M`), allowing for the orbit camera sitting in a
|
|
4036
|
+
neighbour cell. Per-player lookups are cached each tick. Other players whose
|
|
4037
|
+
body cells are visible become candidates, after the existing block/hidden-pair
|
|
4038
|
+
filter. Players the viewer follows or who follow the viewer (either direction),
|
|
4039
|
+
and mutual friends, rank first from that viewer's own server cache, then nearest
|
|
4040
|
+
distance, retaining the existing `KEEP_NEARER` preference for players already
|
|
4041
|
+
known. The server cuts
|
|
4042
|
+
at the smaller of the client's cap and the place's `nearestPlayers`. Entry
|
|
4043
|
+
uses the existing `in` message and full current player row.
|
|
4044
|
+
|
|
4045
|
+
Under this key, the base SDK's `relationsAmong` reads the same host
|
|
4046
|
+
`hubFriendsAmong` operation: `userIds` supplies mutual friends, and `follows` /
|
|
4047
|
+
`followedBy` supply follows in either direction when ghost provides them
|
|
4048
|
+
(mutual friends only before that). The cache is primed after a signed-in player's
|
|
4049
|
+
hello and body exist, with deck-requested ids first, then other signed-in players
|
|
4050
|
+
in the place, deduped and capped at 100. Deck asks share the same pending read
|
|
4051
|
+
and still return mutual friends only. An ask with uncovered ids waits for a
|
|
4052
|
+
pending read, then can read its own candidates first once 31 seconds have passed
|
|
4053
|
+
since the last read started; before that it answers only covered mutual friends.
|
|
4054
|
+
Every five seconds the tick checks for expiry and new players outside the asked
|
|
4055
|
+
set: expired entries refresh even with an unchanged roster or after a refusal,
|
|
4056
|
+
and entries with mutual friends also become stale after 60 seconds when new
|
|
4057
|
+
players are present. All reads under the key stay at least 31 seconds apart,
|
|
4058
|
+
with one read in flight per player. Only non-empty mutual friends get the
|
|
4059
|
+
10-minute TTL; empty mutual friends, including follows-only answers and
|
|
4060
|
+
refusals, keep the 40-second TTL. Expired entries confer no interest priority
|
|
4061
|
+
until refreshed. These relation lists remain server-side for ordering and
|
|
4062
|
+
never go to any client. Chat rules are unchanged.
|
|
4063
|
+
|
|
4064
|
+
`{ k: "hub-cap", n }` asks for an integer cap, clamped to
|
|
4065
|
+
1..place.nearestPlayers. Malformed requests are ignored; at most four valid
|
|
4066
|
+
requests per second are accepted, and leaving forgets the cap. Before a
|
|
4067
|
+
request, the cap is the place's limit. Clients send on WORLD/place load and
|
|
4068
|
+
tier changes: Low asks for 16, High for the place limit. On High, a p95 frame
|
|
4069
|
+
time above 40 ms over the last 3 seconds drops the cap to 16. After 20
|
|
4070
|
+
continuous seconds with p95 below 28 ms it returns to full. Frame-guard
|
|
4071
|
+
changes are at least 10 seconds apart; transition/hidden frames do not count.
|
|
4072
|
+
A place without active cell interest sends no cap messages.
|
|
4073
|
+
|
|
4074
|
+
The optional real-time `objectInterest(sim)` hook returns a Map from player
|
|
4075
|
+
id to a Set of object ids. Deltas carry changed visible `os` rows and the full
|
|
4076
|
+
current row of every object entering the viewer's set, with those ids in
|
|
4077
|
+
`oin`. Leaving sends no notice; the client retains its last pose. `oin`
|
|
4078
|
+
starts a fresh interpolation, smoothing and steering history so re-entry
|
|
4079
|
+
snaps to the current pose. WORLD continues sending every object. Ownership
|
|
4080
|
+
(`own`), removals (`gone`), acknowledgements (`ack`) and deck fields remain
|
|
4081
|
+
common. The hub includes objects in visible body cells and always includes
|
|
4082
|
+
the viewer's owned or held object.
|
|
4083
|
+
|
|
4084
|
+
Under this key, common `labels`, `tints` and `marks` are latched dictionary
|
|
4085
|
+
patches: `labelsD`, `tintsD`, `marksD`, each `{ actorId: newValue | null }`.
|
|
4086
|
+
Only changed keys are sent, and null deletes a key. WORLD still carries whole
|
|
4087
|
+
maps. Clients merge patches into the same state as whole maps. Diffing uses
|
|
4088
|
+
exactly the existing common, privacy-filtered block; private `hub-labels`,
|
|
4089
|
+
visibility (`hub-vis`), wear and other per-viewer overrides keep their
|
|
4090
|
+
existing routes and precedence. Labels themselves are not scoped to cells.
|
|
4091
|
+
|
|
4092
|
+
Fail-safe rules: a missing or invalid table warns once with
|
|
4093
|
+
`[hub] interest: cells table ...` and restores behavior as if the key were
|
|
4094
|
+
absent, including the old default cap and whole dictionaries. A body in no
|
|
4095
|
+
resolvable cell is included; a viewer outside all cells sees everything
|
|
4096
|
+
allowed by existing privacy rules. A null or throwing object hook, or a
|
|
4097
|
+
viewer absent from its Map, sees every object that tick; re-entering objects
|
|
4098
|
+
still get full rows. A failing player hook retains the existing hidden-pair
|
|
4099
|
+
fallback. This feature **narrows only**: NPC chat, blocks, hidden pairs and
|
|
4100
|
+
per-viewer overrides never gain a new recipient through interest filtering.
|
|
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
|
+
|
|
1350
4113
|
## Changes in v1
|
|
1351
4114
|
|
|
1352
|
-
|
|
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.
|
|
1353
4277
|
|
|
1354
4278
|
| date | change |
|
|
1355
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
4318
|
+
| 2026-10-07 (v1.88) | §12 a fresh hello under a retained player id replays that player's current private HUD, labels, tune and avatar overrides once on the next tick, to that player alone. Nothing is sent where none was ever set or the last value sent was empty, except after a `resume: true` hello: that client kept what it held and may have missed a clear, so every channel ever sent to it goes again once, empty ones too. An `again: true` hello replays nothing. No new wire keys. |
|
|
4319
|
+
| 2026-10-07 (v1.87) | §11 dormant avatar colours: six toon colours per character; hello `color`, ghost `avatarColor` and latched `hubAvC` with blocked-pair privacy and empty clearing. Platform colours require both the host's `color` field and the deck's castle.base SDK marker `Avatar.colors === true` (a base republished from main at or after this change); stand-in colours require confirmed platform support or boolean `hub.avatarColors: true`, and hello colours require the manifest opt-in. Absent/false opt-in preserves stored manifest, behavior and wire bytes without ghost colours. Cached recoloured models preserve faces and fits; the avatar cap drops colour before character and reuses already-drawn plain models. Old clients ignore `hubAvC`. |
|
|
4320
|
+
| 2026-10-07 (v1.86) | §9 a private place menu whose spec carries `face` caps its sheet at 40vh (40dvh where supported), leaving room above for the avatar close-up; its tile area scrolls as before. Replacing the spec updates the cap. Without `face`, the existing 55vh/55dvh cap, element styles and CSS text are unchanged. Client only; no server or wire changes. |
|
|
4321
|
+
| 2026-10-07 (v1.85) | §9 private place menu's optional `face`: finite degrees normalised into [-180, 180), the same `(sin f, cos f)` x/z facing as `hub.placeAt`. The player's own client holds its avatar facing while the sheet is shown under orbit control (including held orbit shots); normal moves report it to other players. Holds and seats take precedence; follow-camera places ignore `face`, and camera yaw is never changed. Close, replacement without `face`, leave and higher-priority UI release it. Older clients ignore the key; absent `face` preserves control and wire bytes. |
|
|
4322
|
+
| 2026-10-07 (v1.84) | §13 a talk panel kept open across a same-player-id reconnect re-attaches with the existing `hub-npc-open`, retaining its visible transcript and using the new conversation's notes before sending a pending question. `HUB_NPC_NOT_TALKING` also permits one re-attach and retry per question, never a loop or a replay of an admitted turn. A refused re-attach shows the place's supplied busy/unavailable line or a fixed interruption line, then closes and keeps unsent words as that body's input draft. Works with one or three slots and owner companions; a new player id still clears the old panel and drafts. No wire keys or privacy changes; without reconnect or a stale-panel refusal traffic is byte-identical. |
|
|
4323
|
+
| 2026-10-07 (v1.83) | §13 optional `hub.npcs.turnsAtOnce` and per-body `HubNpc.turnsAtOnce` (integer 1-3, default 1) give each body conversation slots with speaker-specific openings, notes and pending turns, sharing the existing per-minute budget. Each speaker receives only their own panel, replies, notes and persistent asks; ambient lines never carry player input or another speaker’s reply. `talkingWith` lists open speakers in order; `talkingTo` is the earliest and handle-only `turnsAtOnce` exposes the effective capacity. Multi-slot conversations leave place walks and follows running and face a speaker only while idle. End/leave frees only that speaker’s slot. Absent keys retain the stored manifest, wire, behavior and timing; explicit 1 adds no manifest or wire key. |
|
|
4324
|
+
| 2026-10-07 (v1.82) | §6 seats accept optional `HubSeat.pose: "sit" \| "lie"`: lie offers "Lie down" and every client draws the player on their back, centred along the seat facing, head toward its back. §10 decor copies inherit the pose and turn with their template-facing offset. Holds, seat ids, Stand, input and nap hooks stay unchanged. Absent key = byte-identical sitting pose and wire; explicit `"sit"` also preserves today's behavior. The check refuses other poses and unknown HubSeat keys. |
|
|
4325
|
+
| 2026-10-07 (v1.81) | §10 a goal may carry `edge: false`: a hint hovers over its on-screen destination and disappears off screen or behind the camera. The two nearest drawable goals are chosen, so hidden hints never displace edge-drawn goals. Only exactly false on a goal with `to` is stored and sent; keys absent are byte-identical. Hub places only; no editor, classic or other Cauldron deck changes. |
|
|
4326
|
+
| 2026-10-07 (v1.80) | §13 a place may keep chips on offer after a reply with optional synchronous `npcAsks(hub, npc, playerId) -> { persistentAsks: string[] } \| null`. Re-read with the mind's notes; up to two trimmed, distinct strings cut to 40 characters, invalid entries dropped. Only the talking player's `hub-npc-notes` carries the offer; changes issue notes even when the prefix stays the same, and null clears it. The latest offer leads suggestions or unused opening questions in the existing three-chip row and is exempt from sent questions staying gone while still offered. Throws and rejected async results are caught and logged once without private words; the conversation's bound speaker is rechecked before delivery. Without the hook, no new message key or refill path; notes wire bytes stay identical. Older clients ignore the key. |
|
|
4327
|
+
| 2026-10-07 (v1.79) | §1/§4/§9/§12 private place menu: `menu: true` enables `hub.menu(playerId, spec \| null)` and a versioned item/close hook. A phone bottom sheet has up to eight sections and 48 total items, color/icon tiles, selection and readOnly; walking is held while open. Private offers coalesce to four/s; stale/unknown picks drop, six/s burst eight. Keys absent preserve existing behavior and wire bytes. |
|
|
4328
|
+
| 2026-10-07 (v1.78) | §4/§9 owner-only bird `pose: 'show'` flies to a camera-relative left view at about one-third screen height fitted from paper and worn vertices (excluding glow) under the active orbit lens, with a 4% screen inset; upright camera-basis orientation, shallow side angle and gentle turn, portrait centre at 27% width / 40% height with a player margin, raised wing flutter and reduced glow; proportional species hats and neck accessories in every pose, with opaque paper and full scale from the first approach frame; hides temporary hat try-on and returns to follow when cleared; absent pose preserves wire bytes and lantern rejects pose. Owner-only bird `dress`: fixed species, wear and tint enums; empty/default dress omitted with literal v1.71 wire compatibility; lantern rejects dress. Folded-paper owl, parrot and hummingbird share the songbird rig, glow, motion and quiet opacity; worn accessories hide during hat try-on and dress rebuilds dispose all resources. `hub.companionDress` gates dress and the separate `hub.companionPose` gates pose, preserving fallback for dress-only kits; show reaches its target in 0.7 s and keeps the full geometry at least `near + 0.15` away in camera depth; `hubGlow` stays presence only. |
|
|
4329
|
+
| 2026-10-07 (v1.77) | §11 and §12 a harbour boat deed's first unlock names its destination: a home item whose `piece` (or id, when it has none) starts with `boat-` sends private `{ k: 'hub-home-unlock', to: 'boat' }` and the client says "Sent to your boat at the Harbour". Every other home item sends exactly `{"k":"hub-home-unlock"}` and says "Sent to your house"; a repeat unlock sends nothing, as before. An older client ignores `to` and says "Sent to your house", which is acceptable. Decks without a boat deed, and keys-absent decks, send and receive the same bytes as before. |
|
|
4330
|
+
| 2026-10-07 (v1.76) | §13 personalised walk-up bubble: a signed-in inspect privately offers physical mind body/character ids via `hub-npc-hooks`, never text. Idle approach reads `status` with reserved `greeting:<character>` once per character per session; opening chat first drops the hooks without reading, failures never retry. Ghost consumes the due hook transactionally; the server checks the captured account/body, returned character and cleaned line, then speaks through only the nearest eligible body within Chat range plus 2 m, to the speaker alone for 7 s. Guests, owners, virtual companions, busy bodies and stale/null results say nothing. Greeting cache stays for the next chat opening and notes. No public text, snapshots, logs or place hooks; no editor or classic deck changes. |
|
|
4331
|
+
| 2026-10-07 (v1.75) | §1 place-only `ask: true`; §4 private `hub.ask(playerId, spec \| null)` and `answer(hub, playerId, id, text)`; §9 phone-first single-line prompt, OK/Enter and Cancel, keyboard-aware card and walking/orbit input lock released on every close. §12 private `hub-ask` prompts/closures and `hub-answer` submissions, checked against both current and last-sent versions and ids, limited to two/s, burst four, dropped attempts included. Plain specs have exactly own id/title/max read once, validated and copied; titles and answers reject whitespace-only, control, Bidi_Control and zero-width text. Every changed prompt advances the session counter; tick offers coalesce to four/s, equal sent/current content and version suppressed; fresh hello replays once and leave forgets. A current answer with refused text consumes as Cancel, passing only null. An accepted answer consumes and queues its close before the hook runs; hook errors are contained and logged once without text. Typed text reaches only the place server hook, is never echoed or retained by the kit, and a place must never show it to another player. Absent keys add no API, hook lookup, private state, chrome or wire bytes. |
|
|
4332
|
+
| 2026-10-07 (v1.74) | §1 place-only `actions: true`; §4 private `hub.actions(playerId, items \| null)` and `action(hub, playerId, id)`; §9 up to three phone-first action chips, stacked above existing bottom-right controls. §12 private whole `hub-actions` offers (`items`, safe-integer version `n`) and `hub-action` presses (`id`, `n`), checked against both the sender's current version and current ids and limited to six/s, burst eight, dropped presses included. Invalid API calls throw before state changes; plain items carry own fields read once, with labels of 1..16 characters (code points), no control, direction or zero-width characters and never whitespace-only. Changed recorded lists advance `n`; tick deliveries coalesce to at most four offers a second per player, newest wins, equal last-sent/current lists suppressed. Leave forgets offers; re-hello clears stale client chips and replays the current offer once with its current `n`. Async hooks are neither serialised nor cancelled on leave. Top controls bound the stack from above; pointer presses never focus chips. Absent keys add no API, hook lookup, private state, chrome or wire bytes. Door games use buttons for choices; stand-on pads stay for go doors and race starts. |
|
|
4333
|
+
| 2026-10-07 (v1.73) | §1 and §11 add the `pet` home class: adopted species in the house pet book, with up to 16 per deck counted separately from 6 furniture/deed and 8 wearable items. Pet pieces match `pet-[a-z][a-z0-9-]{0,19}`; `pet-walk-*` stages remain furniture and cannot be pet species. Furniture/deed validation is unchanged. Pets share home ownership, first-unlock "Sent to your house", guest/dev session unlocks and local wear refusal, and never enter the earned slot or wire. Unlisted pet pieces warn against `docs/home-pieces.md`; ghost must accept `pet` before any declaration or it refuses the whole unlocks list. SDK home types include `pet`; absent pets preserve wire/host bytes. |
|
|
4334
|
+
| 2026-10-07 (v1.72) | §1 place-only `resume: true`, valid only on a place with `result` (a manifest error elsewhere, and for any value but `true`); `hubPlace.resume: true` is carried only by an opted-in place. §12 such a game takes the reconnect re-hello under the same player id, both the client's resume hello and the place's late greet: whichever comes first arrives a player its `leave` let go once (one `arrive`), and the other is idempotent; a player still arrived is not arrived again and is re-sent their private HUD, labels, tune, avatars, visibility and party. The visit goes on, under four invariants: (I1) one result per visit whatever the order of leave, report and resume, a result reported inside `leave` included; (I2) the `maxDurationSec` deadline is set once, at the first arrival; (I3) restored state with a packet is sent again on resume, an ended visit's `hub-end` with `again: true` (taken only by a client not already ending); (I4) `from` and `fromDeckId` are written once per visit. Absent: no new code path, state, message, field or listener; games keep taking neither hello under the same id and wire bytes stay identical. |
|
|
4335
|
+
| 2026-10-07 (v1.71) | Allocated before v1.74, landed after it: §1 place-only `companion: true` or `{ chat: { character, name } }`; §13 an owner-only virtual NPC chat record with private authored lines and the existing talk panel; §4 private `hub.companion(playerId, spec \| null)`; §9 a lantern or paper bird follower and the owner's timed speech bubble, all tiers, tiny shoulder glows for others; §12 owner-only `hub-companion` with a session version and four/s coalescing, replayed on fresh hello and forgotten on leave, plus latched public `hubGlow` player ids alone. Plain own fields are read once and invalid specs throw atomically. The place authors every line; nothing a player typed may be passed to `say`; the line is never shown to anyone else. Absent keys add no API, state, drawer or wire bytes. |
|
|
4336
|
+
| 2026-10-07 (v1.68, no bump) | §12 reconnect re-hello (default, all places), the client half, a fix with no contract version: alongside the place's own greet above, a connection the session takes back after a drop says a fresh `hub-hello` itself (`resume: true`, `party: 1`, no `carry` or `near`), seen client-side as a second WORLD snapshot on the same connection or a new player id on it, so it holds while the page's frames were stopped and needs no re-save of the place (the client is the town page's). Whichever of the two hellos comes first arrives the player, once, and marks stale what the client still holds privately (HUD, labels, tune, avatars, visibility, party, ballot card, leaving line); a hello from a player still arrived does not replay the arrival. A new player id on the same connection is a new session: the client drops the old one's private state (HUD, tune, decor, card, labels, holds) before the new one's packets apply, and starts beside nobody. Games (a place with `result`) take neither hello, client or server, under the same player id; a game connection back under a new player id (a fresh session) says an ordinary first hello (a party of one, nothing carried), so the player is arrived. No steady-state message |
|
|
4337
|
+
| 2026-10-07 (v1.68, no bump) | Reconnect re-hello (bug fix, all places), ruled a default fix by #791 per Jesse's standing order that reconnects must work: a connection that comes back without a hello after the place let its player go (the host's reconnect window keeps the client's connection object, so the client never greets again) is greeted for by the place 3 s later, with the avatar it last chose here; only players let go in the last 10 minutes, so a newcomer always sends its own first hello (party, arrival). The player arrives again (arrive hook, HUD, shots, doors). No message, field or hook changes; nothing differs until a reconnect |
|
|
4338
|
+
| 2026-10-06 (v1.68, no bump) | §Idle play, a default fix Jesse approved, no contract version: an emote's emoji is drawn from the top of the emoting avatar's drawn head (beside the head on its open side where above it would leave the view or go under the top chrome; none for a head wholly off the view), 42 px, and each emote plays 0.8 s longer with a stronger pose (wave 2.8, dance 3.2, cheer 2.4, bow 2.4, spin 2 s). No message, field or hook changes; a deck gets the longer emotes when it is saved with this kit |
|
|
4339
|
+
| 2026-10-06 (v1.69) | §1 `tiers`: an actor may carry `"tier": "low"` beside `id` in its scene file: Low draws it at any distance, High removes its node (drawn on High only in the frame that built it), and a live tier change restores/removes it on the next frame. Low draws no `engine.sky`: while Low the scene runtime's `sky` reads null (an own property hub-game sets and deletes; physics-3d is unchanged), so there is no dome draw, zone stepping or texture upload, a scene load's frame included. No sky key and no low mark: unchanged; no `hub.tiers`: none of it. |
|
|
4340
|
+
| 2026-10-06 (v1.68) | §1 `ballot` (a place's: `true`, or `{ lines }` of at most 32 `{ id, text, about }`), §4 `hub.ballot(playerIds \| null, spec \| null)` and the `ballot` hook, §6 "The choice card": a generic tappable card of faces, the deck's fixed lines and options in `talk`, `vote` and `reveal` modes, drawn by the kit as a phone-first bottom sheet under the HUD. Taps are ids only (`hub-ballot`), checked against the card the player was sent and limited to a burst of three then one per 1.5 s; no free text. §12 private `hub-ballot-card` and `hubPlace.ballot`. Rule A: each player's card has an opaque string version `v` (this server's epoch and a counter) that moves only when what can be tapped changes (mode, faces and `off`, lines, option ids, `picked`); a tap carries it and is taken only when it is both the version delivered and the current one, with ids on that card. Rule B: keys absent, no ballot code runs, client or server; on the client one gate (`hub-ballot-card`) holds a card, buffering one ahead of WORLD; every WORLD naming a keyless place lets a held card go. The card is a pure function of who is here now: faces and feed rows of absent players are left off for every viewer, nothing is remembered after a player leaves, and blocks among players here hide faces and feed rows and take the names of present hidden players out of every word the card shows (a departed name in the deck's words is not redacted, as with the HUD), manifest lines included (`words`); a lock on a face not shown is `picked: {}`. State for connections that left is pruned whether or not they said hello. A deck with no `ballot` anywhere has no `hub.ballot`. A place without the key sends, draws and listens exactly as before (no message, field, DOM or listener) |
|
|
4341
|
+
| 2026-10-06 (v1.67) | §1/§4 owner houses: the SDK copies platform `owner` onto frozen `session.hub` only for a non-empty string; `hub.owner` is that user id or null, and deck-only `house: { devOwner: "first" }` keeps the first dev arrival as owner for the session. §10 Decorating: place-only `decor` grid/layers, private `hub.decor.button/open/close/update`, catalogue thumbnails, stock/locks/swatches, touch/mouse grid ghosts and Rotate/Put away/✓. The validated `decor` hook owns every edit; only the opener's catalogue ids reach it, with a per-player budget. §12 client `decor` and private whole `hub-decor` state, replayed on fresh hello and forgotten on departure, never in shared snapshots. Spawned seats work in decor places, including kinematic copies; moving/hiding/stashing stands the sitter. Absent keys retain byte-identical SDK objects, manifests, snapshots, deltas, messages and legacy drawing. |
|
|
4342
|
+
| 2026-10-06 (v1.66) | §4/§13 tools: `npcTools(hub, npc, playerId)` declares up to 8 lookups (name, description, input_schema; capped and filtered, never costing a turn) sent with a newly admitted turn, and `npcTool(hub, npc, playerId, name, input)` answers the mind's one lookup for that turn, checked against the admitted operation, speaker, character and declared names, at most 1 KiB, to the mind alone. Needs a host with place tools (`init.characterTools`) and a ghost and worker that run the round; elsewhere declarations are dropped and a turn is one call as before. No manifest key; decks without the hooks send byte-identical turns |
|
|
4343
|
+
| 2026-10-06 (v1.65) | §12 `hub.interest: "cells"`: scene-authored body-cell visibility with a 10 m view radius and hysteresis, viewer follows in either direction and mutual friends first, then nearest players, default nearestPlayers 48 and client `hub-cap`. Base SDK `relationsAmong` primes relations for players in the place under the key using the host's `hubFriendsAmong` reply fields `follows`/`followedBy` when available (mutual friends only on older ghost); chat rules stay unchanged. Real-time `objectInterest` filters object deltas with full `oin` entry rows; owned/held objects remain included and WORLD keeps all objects. Common labels/tints/marks send dictionary patches; private overrides and hidden pairs keep their existing privacy. Missing/invalid tables restore legacy behavior, and keyless decks retain byte-identical traffic. |
|
|
4344
|
+
| 2026-10-06 (v1.64) | §1 `tiers`: visibility cells. A scene's top-level `cells` key (`version` 1, `eyeMax`, `hysteresis`, cells of `id`, `outline`, `sees`) and an actor's `cell` field (an id or a list) have Low leave out every authored actor whose cells are none of those seen from the camera's cell, overriding `"tier": "keep"`; only an inert actor (every current component in `CELL_INERT`: `Transform`, `Shape`, `Model`, `Solid`, `Lookable`, `RouteAnchor`, `WalkSurface`; none in the backstop `CELL_PROTECTED`, wardrobes included) is ever out for its cell, decided from its components on every look, never cached by id. The rule is off outside every outline (checked before the hysteresis), above `eyeMax`, in a game through a door, and for a malformed table (a row not seeing itself included) or `cell`; the cell is held with hysteresis between outlines. Looked at again the frame the cell changes. `?hubcells=1` overlay; `__hub.tier.cell`, `.cellHidden`, `.cells(on)` for A/B. Client only, Low only, nothing on the wire; a scene without the key is drawn exactly as before |
|
|
4345
|
+
| 2026-10-06 (v1.63) | §1 `tiers`: an actor may carry `"tier": "near"` beside `id` in its scene file. Low treats it as scenery whatever its components, using the sized 30 m distance test; High draws it as authored. NPCs keep their own rule and `keep` wins. Client node only: labels, colliders and server state are unchanged; scenes without the mark behave as before. |
|
|
4346
|
+
| 2026-10-06 (v1.62) | §4/§10 `hub.hide/show(actorId, { to: [playerIds], clear?: boolean })`: per-viewer actor visibility, including baked Models. Connected viewers only, capped at 256 overrides per player, atomic refusals warn once; clearing restores shared state and leaving drops overrides. §12 private `hub-vis` sends whole hide/show lists on change and on fresh join, without altering snapshots/deltas. Clients merge shared hidden and private overrides for existing drawing, pads, idle and soundscape readers. Server bodies and shared `h.hidden` logic (pads, labels, doors, idle) stay unchanged. Shared-only places retain byte-identical wire traffic. |
|
|
4347
|
+
| 2026-10-05 (v1.61) | §4 `hub.shot(playerId, shot \| null)`: private, validated orbit moment shots for data-only places. Four shots/s with burst four, bounded equal-pose repeats and unthrottled clears; no-op without the scene orbit key, no collision, and identity-owned client cleanup on travel, leave, load/place change and disconnect; held poses renew privately every 2 s and on fresh join, preserving equal-shot identity without spending the rate budget. The client expires an unrenewed shot after 5 s, even when its watcher was delayed in a background tab; renewals restore disconnect losses but respect scene-load, travel, round-end and deck-ownership clears until a fresh explicit call. Clearing, travel, round end or forgetting the holder stops renewals, and unused places have no renewal callback. No state or work until called. |
|
|
4348
|
+
| 2026-10-05 (v1.56) | §6 NPC babble retuned to all four original round-6 options as `HubNpc.voice.type`: townsfolk, lively, gruff and gentle. A valid explicit type wins; whole-word role/character/name keywords default in gruff/gentle/lively precedence, otherwise townsfolk. Per-character pitch/mouth/rate variation and word seeds retain the existing actor/name hash and random draws. Rosenberg/LF Fourier source waves and breath gated on the glottal open phase before formants keep each option’s calibrated source gain (voice RMS matched within 0.1% in the audition). Legacy `HubNpc.voice.pitch` stays 80–500 Hz; rate 4–10 maps linearly to synthesis rate 2.5–6; waveform timbre names remain accepted and are ignored. Lines fit complete words within 3 s including the fade and within 30 syllables; 22 synthesis nodes plus distance gain, three-source cuts and complete natural/failure cleanup. The fixed level (about 0.248) matches the previous babble's median active RMS (about −25.6 dBFS at volume 0.7), measured offline in Chromium. Existing voice priority, panel ownership, gates and stall rules remain; keyless and `babble: false` audio traces are unchanged and market round-3 speakers retain their existing voices. Grass steps are low-passed at 2.5 kHz instead of high-passed at 2.2 kHz, and grass (+2.35 dB) and wood (−2.08 dB) are levelled so every surface's step sounds within about 1 dB of the others (K-weighted, measured offline); boolean `steps: true` (street) is unchanged. Referenced crowd/market/harbour beds now prewarm serially after activation while sound is allowed, current zone first, scheduling the same seeded events up front with zero offline suspends. |
|
|
4349
|
+
| 2026-10-05 (v1.54) | §1 `yourGames`, §5 private hearted/recent rows and account hearts (`Hub.hearts`, `Hub.setHearts`), three/five-row Your games section and 15 s arrival/return offers. Opt-in only; keyless decks retain their messages and chrome. |
|
|
4350
|
+
| 2026-10-05 (v1.57) | §4 `hub.friendBests(key, { better })`: signed-in bests in a serialized, top-100 `fb:<key>` deck index, best friend lookup through `friendsAmong`, cached by layer and visit; every failure is silent. No manifest key; unused places send and store nothing new |
|
|
4351
|
+
| 2026-10-05 (v1.60) | §6 and `hub.cue`: closed `busker-jig`/`busker-waltz` placeholder tunes, original pooled synthesis independent of short UI cues and zone music. Actor sends refreshed every 10 s or less lease a distance-scaled loop for 25 s, only while in radius and visible with sound live; one loudest loop per client, 0.3 s switches and fade-out, return within lease resumes. Private targets hear one full-gain pass. Ten fixed nodes per phrase player, frame scheduling within 0.3 s, missed notes dropped, full cleanup and unchanged cues-off/keyless behavior; level targets −40 dBFS active RMS at volume 0.7 pending Chromium calibration. |
|
|
4352
|
+
| 2026-10-05 (v1.36) | §4 `hub.friendsAmong(playerId, userIds)`: at most 100 deduped decimal candidates, the player's friends only, 40 s empty/10 min non-empty cache and silent refusals. One private latched `hub-friends-wanted` message enables immediate and 20 s client asks, then 90 s refresh; unused places are unchanged. Local dev fixture `CASTLE_DEV_HUB_FRIENDS=all` |
|
|
4353
|
+
| 2026-10-05 (v1.55) | §10 "Turning displays": a scene actor's `"HubSpin": { "rate" }` (degrees a second, -720 to 720, not 0, sign the way round) is turned about its vertical axis by every client, rate x frame time, from scene data alone -- no op, no wire or snapshot field, no body. The hub town's hat shop could turn a display only by `hub.move` on a kinematic body broadcast to everyone. The check refuses it on a dynamic or kinematic `Body`, a solid actor, a `Player`, `HubDoor`, `HubNpc`, `HubSeat` or `Pickup` (which turns itself), and any other key; hidden actors wait unturned, spawned copies of a template turn. A scene without it is looked through once per load and runs as it did |
|
|
4354
|
+
| 2026-10-05 (v1.53) | §1 `hub.unlocks`, §4 `hub.unlock`, `hub.wearEarned`, `hub.unlocksOf`, `hub.earned`, §11 "The Earned slot": a second wearable slot for small items a game gives for a stated deed (badge, pin, belt, sash, held), declared in castle.json, no rarity, never random, tradeable or paid, chosen by the town alone; ghost keeps them per account (SDK `session.hub.unlock`, `wearEarned`, `readUnlocks`), and a guest's or the dev serve's last the session. Drawn at a per-class anchor fitted to every avatar, from ten new models (`models/earned/`, `scripts/gen-earned.mjs`) in the item's colour, beside the Look. §12 `hubEarned` and `hub-earned`. **Nothing changes for a place where nobody has an earned item**: no new key in any snapshot, delta or message, byte for byte (`scripts/test-earned.mjs`), and `hub.wearing` is unchanged |
|
|
4355
|
+
| 2026-10-05 (v1.52) | §4 `hub.leaving(playerId, text)`, a private next-visit line trimmed and cut at 120 characters; null or empty clears it. Captured when leaving via Back, a game end or a door, under the cover title then as a toast for the remainder of 2.8 s from the start, combined with the return result. Trips never wait for it; classic cabinets do not use it. No snapshot field or traffic from a place that never calls it; localhost `?hubLeaving=<text>` previews it. |
|
|
4356
|
+
| 2026-10-05 (v1.51) | §11 sixteen avatars. Twelve more toon characters, ids `4`-`15` (Biscuit, Mochi, Hop, Pip, Ribbit, Ember, Bolt, Gloop, Cap, Toast, Scoop, Zest), each with its blueprint, its model (at most 1,500 triangles with the outline and 8 draw calls), its height, its hat fit and its earned-item fit (v1.53's badge, pin, belt, sash and held thing; the other sets use toon's for `4`-`15`); the client's and the place's count are 16. The picker is a grid, four across (eight on a phone on its side), of faces and names in place of four numbered circles, the one worn ringed, in a card that scrolls inside itself rather than leave the screen; shut, it is the same "Character" button in the same place. New defaults span all sixteen: a guest with no stored local choice gets a random one of `0`-`15`; ghost defaults accounts that never picked to `userId % 16` from its user-id cutoff on, while existing accounts below it keep `userId % 4`. Stored choices stay unchanged. Server messages for the same avatar inputs stay byte-for-byte unchanged. The other sets (`blocky`, `bean`, `pixel`) draw `4`-`15` from toon's blueprint at toon's height and hat fit. §12 the wire is safe for a client from before v1.51, which cannot draw `4`-`15`: `hubAv` (and `hub-av`) only ever names `0`-`3`, `avatar % 4` for a player who wears another, and a new block `hubAv2` names what such players really wear, sent only while there is one (and `{}` once in a delta when the last is gone). A v1.51 client draws `hubAv2`'s; an older one ignores it and draws the stand-in, so nobody is ever left undrawn. Across versions: a place on an older kit shows a player wearing `4`-`15` as avatar `0` to everyone but themselves; a v1.51 client draws an id of 16 or more, from a later kit, as `id % 4`. Ghost must take `0`-`15` for a pick to be kept; its account default cutoff is a separate ghost-server change. Client display only: `?hubAvDistinct=N` has a viewer draw at most N different characters at once (by default all sixteen), the farthest past that as their stand-in but never anyone within 8 m, and different characters draw from shared materials (`?hubAvShare=0` off). |
|
|
4357
|
+
| 2026-10-05 (v1.50) | §1 explicit `soundscape.cues`, §6 named original audition voices and client-observed actions, ops table `hub.cue(target, name)`: private player delivery or actor broadcasts with finite distance falloff, strict names and six-token server budgets. The client consumes at most eight queued events, sharing UI's two-voice/four-start cap and all sound gates; nearby actions have lower priority. Wave B, dance C, cheer, bow, spin, sit and private NPC panel opening use existing structured state; pad ticks/go are explicit cue names because no structured pad countdown reaches the client. Parts are built 75 ms ahead and released at their end; no free-text parsing. Every footfall body, including landing, has a 150–220 Hz low cut and a lighter, shorter thump. Square, meadow, night and selected harbour A target about −33 dBFS RMS (up 8 dB); the 4.1 kHz cricket pulses remain removed, wind/owl retained. Round-2 square A/B, Sunny A/B and Hollow pad A/B, plus round-3 stadium Victory lap/Arena bounce and harbour Drift/Harbour jig, alternate every 3–5 minutes at bar boundaries with 4–8 s silence. Chosen notes, timbres, envelopes and tempos are retained in fixed pools, with music raised 9 dB from its old −47 dBFS RMS calibration target and Hollow retaining its old sine plus the pad 3 dB below. Harbour A-rolled keeps its swell/gull/creak with two 3.5 kHz wash low-passes and 1.6 kHz foam high-pass; its first wave is scaled to the second peak and the whole bed recalibrated. Stadium crowd A retains 12 voices/eight clappers in 87 fixed nodes. Market Stalls/Haggling alternate every 3–5 minutes with two pooled Simlish graphs for zones/spots. All beds target about −33 dBFS active RMS; music rises 9 dB from its old −47 calibration target, roughly level with the beds, including stadium and the original market melody. Four closed court names add chime A at stone 0, bell A, splash A and flutter B; no new keys or API arguments. Stadium, market (including spots) and harbour beds render offline once per page context from the same seeded generators into seamless 40/60/48 s loops, so phones play one buffer instead of the live graph; music stays live. Keyless audio traces and boolean opt-in behavior remain unchanged apart from the approved footstep timbre adjustment. |
|
|
4358
|
+
| 2026-10-05 (v1.49) | §1 `soundscape.zones`, `ambience: { beds, default, spots, music }` and object `steps: { default, zones, paths }`; §6 "The soundscape": opt-in synthesised square, meadow, night, harbour, crowd and market beds, 1.5 s zone cross-fades with a two-bed cap, nearby spot murmur and quiet original seeded music. Zones use the local player with a 0.75 m exit margin; path polylines override zone surfaces, including new cobble. Audible `hub.sound` loops duck music and ambience. All beds obey the existing activation and settling gate, hidden tab, trip, mute and volume rules. Existing boolean parts sound as before; keyless frames keep their original trace. Strict manifest validation and fake-context real-frame tests cover geometry, bounds, cleanup and ducking. Explicit `soundscape.ui: true` adds quiet synthesised door departure/settled arrival, private town HUD timer activity and chip tap cues on the UI bus, capped at two voices and four starts per second. Only the departure tail may finish into a trip; hiding or muting stops it immediately. Arrival waits at most 3 s for settling. Token text and ambiguous holds make no cue; no wire data is added. Boolean `true` enables no UI, and tests cover opt-in callbacks, caps, gates and graph cleanup. Approved square, meadow and night beds target about −41 dBFS RMS at volume 0.7; crowd, harbour, market and music retain their previous levels pending a second audition, and the periodic cricket tone is removed. |
|
|
4359
|
+
| 2026-10-05 (v1.48) | §5 a joining player's body without a readable saved pose, the kit's arrival row, door jumps, party pad placements and an unstick answer without `y` start at a proved clear standing height no higher than the given height, or keep that height unchanged (normally 1.2). On production an arriving player fell to 0.74, was lifted to 1.2 at ~1.1 s and settled at ~2.8 s: the server's drop height and later settle placements made the player bob. This private proof reads scene and spawned solids at each body's current position and rotation, or its authored Transform when there is no body, and respects hide/show immediately. Support is the highest upright fixed box or cylinder top within the body's padded footprint and no higher than its given feet, or implicit ground at 0 unless the scene has none; add the player's half height and 0.06 m, only when the candidate is no higher and its full height is clear. Nearby non-fixed solids (kinematic or dynamic) never provide support and keep the given height; spheres, tilted and other uncertain shapes use enclosing spheres. Solids entirely above the given body are irrelevant, so a high ball or ceiling does not refuse placement. Friend placement keeps its original clearance rules. No scene query or physics step; body poses are read without changing velocities, sleep or pending kinematic targets. The first join uses the place and actors read before admission. Saved poses, heights given by the place, holds and placements beside another player are unchanged. A default in every hub place; no key, nothing new sent. |
|
|
4360
|
+
| 2026-10-05 (v1.47) | §6 and §13 up to three nearest free NPC bodies within 6 flat metres face a player and answer their emote, with the same motion and emoji on every client and sometimes short public authored speech. Per-player 4 s and per-NPC 8 s limits keep a crowd still between reactions; conversations, follows, walks, moves, holds and speaking bodies are skipped. `HubNpc.reactions` and `npcReact` replace or refuse kit choices, with no model called. `hubNpcEmotes` is sent only after a body has emoted. The Chat prompt starts the speaker's inspect read on approach; refusals still retry on the next open. A character's private `nextGreeting` replaces that speaker's opening text, keeps the place's questions and enters the same private notes; `npcOpening` receives `greeting`, and departure clears the cache. No greeting in public speech, snapshots or logs. Every NPC open gets an increasing integer `info.conversation`, passed to `npcOpening` and captured at admission for `npcHeard` and an authored say's `npcLine`, so a place can match words to the opening it gave. The kit never hands a place words from a conversation that has ended or changed hands: after an awaited send it rechecks the sequence, account key and exact body, dropping stale words without logging them. Only hub places; no editor, classic or other Cauldron deck changes; places with no NPCs keep their messages and snapshots |
|
|
4361
|
+
| 2026-10-05 (v1.46) | §4 and §13 a mind speaks first when `npcOpening` gives no words: "Hi, I'm <first name>! Ask me anything.", with three questions and six more. A place opening keeps its own words and questions; a body without a mind keeps its hello. `npcOpening.more` adds up to nine later questions (40 characters each, deduped); `more` is sent only when non-empty. A mind's Chat with panel shows the text box above "or try:" chips, focuses it only with a fine pointer and no touch, and draws a three-dot typing bubble (static with reduced motion). Chips refill after replies or scripted lines from status suggestions, else unused opening questions; sent questions never return. The client retries its inspect read on each open until one succeeds, hiding typing and chips while pending or refused and remembering only success per net. Ghost's speaker gate is unchanged. Only hub places; no editor, classic or other Cauldron deck changes |
|
|
4362
|
+
| 2026-10-05 (v1.43) | §1 `labels: "near"`, §10 "Labels kept near": a deck may have its towns keep the world labels (`hub.label`'s plates, NPC lines and `"sign"`s over scene actors) near the player and apart -- a `"sign"` only from 12 m (kept to 14 m, thinning), no two overlapping (the plate stood by, then the NPC's line, then signs by how near; the other is not drawn), three at most, with hysteresis at each edge (a label taken down for another stays down two seconds). The owner, standing in one district of the 4x world with the orbit camera: "from sunny side i can see labels for the harbor, sunny side, hollow end, the stadium all at the same time" -- seven pills, drawn on one another, the nearest sign 34 m off. Goal and friend pointers, players' bubbles, emotes and marks, name tags, a cabinet's card, the ribbon and the "Stuck?" chip are not world labels and are untouched. The deck's and the client's alone, like `tiers`: validated (`"near"` or left out), read by no server, in no manifest. A deck without the key runs the statements it ran: the hub system asks the key before its one new branch, and the chrome's two new methods (`measureLabel`, which makes its node on first use, and `hudClearBox`, which reads) are called by nothing else |
|
|
4363
|
+
| 2026-10-05 (v1.42) | §1 `soundscape`, §6 "The soundscape": a deck may have the kit make sounds of its own, synthesised in the client and never a file or speech. `true`, or `{ babble, steps }`. Babble: an NPC's line (in the talk panel for the player it answers; over the NPC for whoever is sent it, by distance to 12 m) is voiced as syllables paced to its text, in a voice that is that NPC's from its actor id and name, or its optional `HubNpc.voice: { pitch, rate, timbre }`; two voices at once at most. Steps: footfalls by the ground covered, a jump and a landing for the player, and quieter steps for the players and NPCs within 10 m. A speaker button (mute, volume, kept in `localStorage`) sets the level of both and of the place's `hub.sound` files. Silent before the first gesture, during a trip and while the page is hidden. Client only: no message, no snapshot field, and the server's manifest gains the key only where it is on. Without the key no audio context, listener, storage read or control is made, and `hub.sound` plays exactly as it did (`scripts/test-soundscape.mjs`) |
|
|
4364
|
+
| 2026-10-05 (v1.41) | §11 what players wear is drawn under each avatar's own node rather than as actors, so it moves and turns with the avatar in the same frame and, under the orbit camera, is left out with a player's own body when the camera is pressed into it (a hat's brim filled a quarter of the screen). Each hat is the kit's model (`models/hats/<id>.pxmodel`, `scripts/gen-hats.mjs`) with the avatars' look, where it was one to three plain shapes; Star's and Beat's hat fits are measured again (a hat sank into Star's point; Beat's crest came through the crown). A halo is a ring with an open middle sized to the head, and an aura a ring round a faint disc: Jesse took a halo for a flat hat. A mounted pack is given the engine's hat models with its avatars. `hub.wearing(playerId)` reads the wearable a player here owns. Nothing sent or saved changes, and no key: every place draws wearables this way |
|
|
4365
|
+
| 2026-10-05 (v1.40) | §5 an arriving player is kept where the arrival put them (the kit's row, beside a friend, or wherever the place's `arrive` hook placed them) for the first 0.6 s, the settle a door jump has had since v1.10. A player waits for their group at the scene's spawn, where their client agrees they are; once placed, that client's move reports still on their way name the spawn, and the movement clamp let each pull the body a step back toward it. In the production town four players back from Tag were each given a spot of their own and two were dragged 2 to 3 m toward the arrival, onto Summit Sprint's pad, and taken into its game (the same pull took a pair back from Foot Race into King of the Hill). Only a player the arrival moved from where they waited (more than the hold's slack) is kept, and any later placement by the place (`hub.placeAt`, a hold, a jump) is where they are from then on. Not a hold: the player is not in the held list and walks off at will after the moment; a player the place holds keeps the hold's spot. A default, in every hub place; no key, nothing new sent. |
|
|
4366
|
+
| 2026-10-05 (v1.39) | §5 "Stuck?", behind the same `hub.stuck`. (a) The rule: the chip shows when 3 s of walk input have been seen within the last 8 s -- counted across breaks, where v1.33 started over at every break of 250 ms, so a player walking in bursts never saw it -- and over that stretch the box round where the body was is under 1 m corner to corner (v1.33: within 0.3 m of where the count began). The frame rules are unchanged. (b) §4 `unstick(hub, playerId, from)`: a place may pick the spot a stuck player is put at, since from the arrival a straight line could run back into the same obstacle; null, no hook, a throw or an answer that is not a spot in the world box is the arrival as before. In a place with the hook `hubStuck` carries `hook: true`, the client asks what a tap would do (`hub-unstick` with `ask: true`, answered by `hub-unstick-to`) to word the chip, and the `hub-jumped` after a tap carries `stuck` (§12). A deck without `hub.stuck`, and a place without the hook, are sent what they were. Also §10: a goal label may say which distance its pointer shows, `{ distanceM: n }` (that many metres in place of the straight line the client measures, for a pointer aimed at the next corner of a route) or `{ distance: false }` (none); a goal without either, and every other label, is stored, sent and drawn as before |
|
|
4367
|
+
| 2026-10-05 (v1.38) | §9 the hub chrome's pointer chips are drawn under the labels as well as under every panel: an NPC's speech bubble (and any label) is read over a goal's or a friend's chip, which cut through the words of an NPC standing by a goal (Flop Park, on a phone). And a chip at the screen's edge is kept beside the round quick-chat, emote and grab buttons, never under one (half its words were covered at the right edge). A default, in every hub place; no key. |
|
|
4368
|
+
| 2026-10-05 (v1.37) | §4 and §13 `npcOpening(hub, npc, playerId, { met })`: an NPC speaks first. A new player opening an NPC's chat saw an empty panel and did not know what it could be asked: the place may now give the NPC's first words and up to three tappable questions, shown at once with no model call. The open message carries `opening: { text, asks }` only when the hook gives one, and the talk panel makes its row of question chips only then, so a place without the hook is sent and draws what it did. |
|
|
4369
|
+
| 2026-10-05 (v1.35) | §9 the NPC talk panel: a new reply is scrolled so its first word is at the top of what shows (it was scrolled to the end of the log, so a long reply had to be scrolled back up to be read); the player's own line still goes to the end; a player who has scrolled up to read is left where they are. A default, in every hub place; no key. A mind's instructions should still keep a reply to two or three short sentences. |
|
|
4370
|
+
| 2026-10-05 (v1.34) | §9 the hub chrome's pointer chips (the pointers to friends in a town, a place's `goals` arrows) are drawn under every panel, card and button of the chrome -- the NPC talk panel, the say panel, People, Doors, the question card -- as the labels always were. They were drawn over them, so a goal's arrow could sit on the words of an NPC being read. A default, in every hub place; no key. |
|
|
4371
|
+
| 2026-10-04 (v1.33) | §1 `stuck`, §5 "Stuck?": a deck may have its towns offer a player who walks and gets nowhere the way back to the arrival. Walk input for 3 s with the body inside 0.3 m shows a chip ("Stuck? Tap to go to the square"), and the Doors list gains a "Stuck?" row; a tap sends `hub-unstick` (§12) and the place puts that player at its arrival as the fall rule does, once in 5 s, never held, never in a game. A town that takes it says so in its snapshot (`hubStuck`). Nobody is moved without a tap. A deck without `stuck` is sent and draws exactly what it did, and `hub-unstick` there is the place's own message |
|
|
1356
4372
|
| 2026-10-04 (v1.32) | §2 `cues` (a): the extra friends asks come at about 1, 3, 9 and 15 s, bounded as two in any 8 s at least 2 s apart (was one in 4 s): measured on production after v1.31, the ask at 1 s often came back before the host had both connections and the next was 4 s later. The same number of asks over time (15 a minute, 16 in the worst-placed minute), four for someone never named. A deck without `hub.cues` asks exactly as before. |
|
|
1357
4373
|
| 2026-10-04 (v1.31) | §2 `cues` (a): the extra friends asks come at about 1, 5, 10 and 16 s after someone is first seen (were 2, 6, 11, 17), and may follow any ask by 1 s (was 2). The host now names a mutual follow in the same layer within a few seconds of their joining, so the first of these is the one that tells a player their friend is here. Still at most one extra ask in 4 s, 15 a minute, four for someone never named. A deck without `hub.cues` asks exactly as before. |
|
|
1358
4374
|
| 2026-10-04 (v1.30) | §1 `tiers`: `"tier": "keep"` on an actor in a scene file (beside `id`, not a component) has it drawn on every tier. Low does not draw an actor with only `Transform`/`Shape`/`Model`, which is what the hub world's ground is (paving, grass, the running track, merged per-cell dressing), so on Low its stalls and benches stood on black; giving ground a `Solid` or `Lookable` it does not need was the only way round. A marked actor is never taken out by Low: not as decoration, not as scenery past 30 m, not as an NPC body past 20 m. Client only, read from the scene file with the ids the tiers already read there; a scene with no mark, and a deck without `tiers`, are drawn exactly as before |
|
|
@@ -1403,3 +4419,385 @@ Minor additions, each optional; a deck written before them reads the same.
|
|
|
1403
4419
|
| 2026-10-02 (v1.1) | §11 `hub.mark`, carried as `marks` (§12). M1's Zone Wars could not show anyone's team and Tag could not show who was it |
|
|
1404
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 |
|
|
1405
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 |
|
|
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`.
|