castle-web-cli 0.4.238 → 0.4.240
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.js +5 -1
- package/dist/api.d.ts +20 -0
- package/dist/api.js +57 -0
- package/dist/bundle.d.ts +38 -1
- package/dist/bundle.js +309 -13
- package/dist/castle-host/host.js +218 -11
- package/dist/castleJson.d.ts +10 -0
- package/dist/castleJson.js +46 -2
- package/dist/check.js +5 -2
- package/dist/devSessionServer.js +4 -1
- package/dist/devSessionStorage.d.ts +1 -0
- package/dist/devSessionStorage.js +32 -7
- package/dist/importOrder.d.ts +2 -0
- package/dist/importOrder.js +29 -0
- package/dist/index.js +22 -3
- package/dist/init.js +24 -2
- package/dist/multiplayerDoc.d.ts +1 -1
- package/dist/multiplayerDoc.js +9 -0
- package/dist/platformDoc.js +4 -2
- package/dist/playPagePolicy.d.ts +1 -0
- package/dist/playPagePolicy.js +12 -3
- package/dist/resetLeaderboards.d.ts +8 -1
- package/dist/resetLeaderboards.js +43 -8
- package/dist/roomLogs.d.ts +39 -0
- package/dist/roomLogs.js +166 -0
- package/dist/save-deck.d.ts +32 -2
- package/dist/save-deck.js +240 -39
- package/kits/base/CLAUDE.md +2 -1
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +240 -8
- package/kits/base/sdk/analytics.d.ts +8 -0
- package/kits/base/sdk/analytics.js +92 -0
- package/kits/base/sdk/castle.d.ts +8 -2
- package/kits/base/sdk/castle.js +3 -0
- package/kits/base/sdk/commands.d.ts +79 -0
- package/kits/base/sdk/commands.js +1 -0
- package/kits/base/sdk/debugConsole.d.ts +17 -0
- package/kits/base/sdk/debugConsole.js +154 -0
- package/kits/base/sdk/experiments.js +24 -1
- package/kits/base/sdk/hostRetry.d.ts +7 -0
- package/kits/base/sdk/hostRetry.js +57 -0
- package/kits/base/sdk/hub.d.ts +20 -2
- package/kits/base/sdk/hub.js +99 -13
- package/kits/base/sdk/multiplayer.d.ts +2 -0
- package/kits/base/sdk/multiplayer.js +198 -26
- package/kits/base/sdk/reconnectBudget.d.ts +6 -0
- package/kits/base/sdk/reconnectBudget.js +41 -1
- package/kits/base/sdk/rooms.d.ts +11 -0
- package/kits/base/sdk/rooms.js +22 -0
- package/kits/base/sdk/runtime.js +36 -19
- package/kits/base/sdk/server/hub.d.ts +19 -0
- package/kits/base/sdk/server/hub.js +12 -0
- package/kits/base/sdk/server/platformHandle.d.ts +1 -0
- package/kits/base/sdk/server/wrapper.d.ts +1 -1
- package/kits/base/sdk/server/wrapper.js +26 -1
- package/kits/base/sdk/store.d.ts +8 -2
- package/kits/base/sdk/store.js +5 -1
- package/kits/base/sdk/transport.d.ts +2 -1
- package/kits/base/sdk/transport.js +35 -0
- package/kits/hub-game/CLAUDE.md +66 -19
- package/kits/hub-game/castle.json +4 -4
- package/kits/hub-game/code/client/act.js +9 -6
- package/kits/hub-game/code/client/actCore.js +26 -6
- package/kits/hub-game/code/client/actGateLog.js +36 -0
- package/kits/hub-game/code/client/actionOverflow.js +29 -8
- package/kits/hub-game/code/client/actionRailSurface.js +186 -0
- package/kits/hub-game/code/client/actionRailTree.js +173 -0
- package/kits/hub-game/code/client/askSurface.js +85 -0
- package/kits/hub-game/code/client/askTree.js +51 -0
- package/kits/hub-game/code/client/attention.js +31 -6
- package/kits/hub-game/code/client/ballot.js +42 -5
- package/kits/hub-game/code/client/ballotSurface.js +115 -0
- package/kits/hub-game/code/client/ballotTree.js +180 -0
- package/kits/hub-game/code/client/catchingUp.js +19 -0
- package/kits/hub-game/code/client/celebrate.js +66 -0
- package/kits/hub-game/code/client/chrome.js +474 -53
- package/kits/hub-game/code/client/companion.js +93 -23
- package/kits/hub-game/code/client/companionDress.js +1 -1
- package/kits/hub-game/code/client/cornerSurface.js +106 -0
- package/kits/hub-game/code/client/cornerTree.js +83 -0
- package/kits/hub-game/code/client/decor.js +20 -11
- package/kits/hub-game/code/client/deviceStorage.js +121 -0
- package/kits/hub-game/code/client/disguise.js +23 -0
- package/kits/hub-game/code/client/disguiseDraw.js +87 -0
- package/kits/hub-game/code/client/dockSurface.js +206 -0
- package/kits/hub-game/code/client/dockTree.js +232 -0
- package/kits/hub-game/code/client/earned.js +29 -0
- package/kits/hub-game/code/client/emoteSurface.js +188 -0
- package/kits/hub-game/code/client/emoteTree.js +264 -0
- package/kits/hub-game/code/client/farAvatars.js +4 -3
- package/kits/hub-game/code/client/fpsTelemetry.js +3 -1
- package/kits/hub-game/code/client/grab.js +121 -50
- package/kits/hub-game/code/client/holdShow.js +19 -0
- package/kits/hub-game/code/client/hookLayer.js +96 -12
- package/kits/hub-game/code/client/hubControls.js +7 -1
- package/kits/hub-game/code/client/hudSurface.js +11 -3
- package/kits/hub-game/code/client/hudTree.js +7 -4
- package/kits/hub-game/code/client/idle.js +21 -3
- package/kits/hub-game/code/client/invites.js +24 -3
- package/kits/hub-game/code/client/keys.js +15 -0
- package/kits/hub-game/code/client/labelsNear.js +8 -1
- package/kits/hub-game/code/client/layoutCache.js +57 -8
- package/kits/hub-game/code/client/loadingCover.js +53 -4
- package/kits/hub-game/code/client/menuIcons.js +15 -0
- package/kits/hub-game/code/client/menuRows.js +8 -2
- package/kits/hub-game/code/client/menuSurface.js +102 -0
- package/kits/hub-game/code/client/menuTree.js +135 -0
- package/kits/hub-game/code/client/modelLook.js +41 -0
- package/kits/hub-game/code/client/pickerSurface.js +152 -0
- package/kits/hub-game/code/client/pickerTree.js +163 -0
- package/kits/hub-game/code/client/pushVisit.js +4 -2
- package/kits/hub-game/code/client/quality.js +188 -29
- package/kits/hub-game/code/client/qualityEntry.js +10 -1
- package/kits/hub-game/code/client/quickChatSurface.js +222 -0
- package/kits/hub-game/code/client/quickChatTree.js +201 -0
- package/kits/hub-game/code/client/rehello.js +75 -0
- package/kits/hub-game/code/client/renderVisibility.js +17 -0
- package/kits/hub-game/code/client/replay.js +118 -0
- package/kits/hub-game/code/client/role.js +3 -0
- package/kits/hub-game/code/client/safeLayout.js +441 -56
- package/kits/hub-game/code/client/safeStyle.js +13 -10
- package/kits/hub-game/code/client/say.js +2 -0
- package/kits/hub-game/code/client/soundSurface.js +77 -0
- package/kits/hub-game/code/client/soundTree.js +74 -0
- package/kits/hub-game/code/client/soundscape.js +12 -9
- package/kits/hub-game/code/client/soundscapeCues.js +1 -1
- package/kits/hub-game/code/client/state.js +67 -1
- package/kits/hub-game/code/client/stuckSurface.js +76 -0
- package/kits/hub-game/code/client/stuckTree.js +67 -0
- package/kits/hub-game/code/client/talk.js +42 -12
- package/kits/hub-game/code/client/talkTree.js +4 -2
- package/kits/hub-game/code/client/textAskSurface.js +147 -0
- package/kits/hub-game/code/client/textAskTree.js +67 -0
- package/kits/hub-game/code/client/tiers.js +252 -27
- package/kits/hub-game/code/client/together.js +4 -1
- package/kits/hub-game/code/client/uiDom.js +86 -8
- package/kits/hub-game/code/client/uiTree.js +33 -4
- package/kits/hub-game/code/client/vehicle.js +75 -52
- package/kits/hub-game/code/client/weakestTier.js +75 -31
- package/kits/hub-game/code/client/wear.js +159 -5
- package/kits/hub-game/code/client/worldLabels.js +215 -26
- package/kits/hub-game/code/companionSpec.js +4 -2
- package/kits/hub-game/code/server/act.js +3 -0
- package/kits/hub-game/code/server/actGate.js +83 -0
- package/kits/hub-game/code/server/actions.js +71 -15
- package/kits/hub-game/code/server/actors.js +20 -5
- package/kits/hub-game/code/server/analytics.js +40 -15
- package/kits/hub-game/code/server/ask.js +39 -3
- package/kits/hub-game/code/server/ballot.js +167 -4
- package/kits/hub-game/code/server/celebrate.js +64 -0
- package/kits/hub-game/code/server/companion.js +17 -2
- package/kits/hub-game/code/server/decor.js +11 -2
- package/kits/hub-game/code/server/disguise.js +63 -0
- package/kits/hub-game/code/server/doorAnalytics.js +2 -5
- package/kits/hub-game/code/server/earned.js +6 -2
- package/kits/hub-game/code/server/friendBests.js +13 -4
- package/kits/hub-game/code/server/friendsAmong.js +67 -8
- package/kits/hub-game/code/server/grab.js +12 -2
- package/kits/hub-game/code/server/heldOffers.js +142 -0
- package/kits/hub-game/code/server/holdShow.js +98 -0
- package/kits/hub-game/code/server/hub.js +854 -45
- package/kits/hub-game/code/server/idle.js +110 -9
- package/kits/hub-game/code/server/index.js +9 -0
- package/kits/hub-game/code/server/labels.js +13 -3
- package/kits/hub-game/code/server/loadAbandon.js +2 -5
- package/kits/hub-game/code/server/manifest.js +94 -6
- package/kits/hub-game/code/server/menu.js +26 -3
- package/kits/hub-game/code/server/npcs.js +55 -9
- package/kits/hub-game/code/server/observe.js +67 -6
- package/kits/hub-game/code/server/players.js +8 -1
- package/kits/hub-game/code/server/replay.js +135 -0
- package/kits/hub-game/code/server/storageLimit.js +4 -1
- package/kits/hub-game/code/server/townDay.js +74 -0
- package/kits/hub-game/code/server/trackQueue.js +29 -0
- package/kits/hub-game/code/server/vehicle.js +3 -0
- package/kits/hub-game/code/server/vis.js +26 -4
- package/kits/hub-game/code/server/wallet.js +677 -0
- package/kits/hub-game/code/server/wear.js +13 -3
- package/kits/hub-game/code/server/writerLease.js +191 -0
- package/kits/hub-game/code/shared/act.js +1 -1
- package/kits/hub-game/code/shared/expression.js +6 -0
- package/kits/hub-game/code/shared/replay.js +37 -0
- package/kits/hub-game/code/systems/hub.js +437 -57
- package/kits/hub-game/docs/analytics.md +20 -3
- package/kits/hub-game/docs/contract.md +942 -99
- package/kits/hub-game/docs/home-pieces.md +5 -6
- package/kits/hub-game/docs/observed-progress.md +49 -1
- package/kits/hub-game/docs/vehicle-preset.md +23 -0
- package/kits/hub-game/index.html +1 -0
- package/kits/hub-game/models/hats/baker-cap.pxmodel +3 -3
- package/kits/hub-game/models/hats/bat-clip.pxmodel +3 -3
- package/kits/hub-game/models/hats/beekeeper.pxmodel +3 -3
- package/kits/hub-game/models/hats/cap.pxmodel +3 -3
- package/kits/hub-game/models/hats/captain.pxmodel +3 -3
- package/kits/hub-game/models/hats/chef-toque.pxmodel +3 -3
- package/kits/hub-game/models/hats/crooked-top.pxmodel +3 -3
- package/kits/hub-game/models/hats/delivery-cap.pxmodel +3 -3
- package/kits/hub-game/models/hats/fire-helmet.pxmodel +3 -3
- package/kits/hub-game/models/hats/flower-crown.pxmodel +3 -3
- package/kits/hub-game/models/hats/foam-crown.pxmodel +3 -3
- package/kits/hub-game/models/hats/hard-hat.pxmodel +3 -3
- package/kits/hub-game/models/hats/lantern.pxmodel +3 -3
- package/kits/hub-game/models/hats/laurel.pxmodel +3 -3
- package/kits/hub-game/models/hats/lighthouse.pxmodel +3 -3
- package/kits/hub-game/models/hats/nurse-cap.pxmodel +3 -3
- package/kits/hub-game/models/hats/police-cap.pxmodel +3 -3
- package/kits/hub-game/models/hats/sailor.pxmodel +3 -3
- package/kits/hub-game/models/hats/souwester.pxmodel +3 -3
- package/kits/hub-game/models/hats/straw.pxmodel +3 -3
- package/kits/hub-game/models/hats/sunflower.pxmodel +3 -3
- package/kits/hub-game/models/hats/sweatband.pxmodel +3 -3
- package/kits/hub-game/models/hats/teacher-beret.pxmodel +3 -3
- package/kits/hub-game/models/hats/witch.pxmodel +3 -3
- package/kits/hub-game/models/hold-show/daisy.pxmodel +231 -0
- package/kits/hub-game/models/hold-show/moonflower.pxmodel +171 -0
- package/kits/hub-game/models/hold-show/rose.pxmodel +191 -0
- package/kits/hub-game/models/hold-show/square/daisy.pxmodel +233 -0
- package/kits/hub-game/models/hold-show/square/moonflower.pxmodel +173 -0
- package/kits/hub-game/models/hold-show/square/rose.pxmodel +193 -0
- package/kits/hub-game/models/hold-show/square/sunflower.pxmodel +313 -0
- package/kits/hub-game/models/hold-show/square/tulip.pxmodel +133 -0
- package/kits/hub-game/models/hold-show/sunflower.pxmodel +311 -0
- package/kits/hub-game/models/hold-show/tulip.pxmodel +131 -0
- package/kits/hub-game/package-lock.json +3 -3
- package/kits/hub-game/package.json +4 -3
- package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +1 -0
- package/kits/hub-game/scripts/fixtures/hud-surface.json +12 -12
- package/kits/hub-game/scripts/fixtures/talk-surface.json +8 -8
- package/kits/hub-game/scripts/gen-hats.mjs +1 -1
- package/kits/hub-game/scripts/gen-hold-show.mjs +27 -0
- package/kits/hub-game/scripts/pack.mjs +89 -23
- package/kits/hub-game/scripts/test-act-client.mjs +5 -0
- package/kits/hub-game/scripts/test-act-core.mjs +32 -0
- package/kits/hub-game/scripts/test-act-gate.mjs +186 -0
- package/kits/hub-game/scripts/test-action-rail-crowded-dom.mjs +7 -1
- package/kits/hub-game/scripts/test-action-rail-default-dom.mjs +102 -0
- package/kits/hub-game/scripts/test-action-rail-never-silent-dom.mjs +50 -0
- package/kits/hub-game/scripts/test-action-rail-surface.mjs +368 -0
- package/kits/hub-game/scripts/test-action-rail-town-jobs-dom.mjs +118 -0
- package/kits/hub-game/scripts/test-actions-client.mjs +5 -3
- package/kits/hub-game/scripts/test-actions.mjs +24 -0
- package/kits/hub-game/scripts/test-actors.mjs +19 -0
- package/kits/hub-game/scripts/test-again-corner-dom.mjs +59 -0
- package/kits/hub-game/scripts/test-analytics.mjs +80 -1
- package/kits/hub-game/scripts/test-arrival-pose-server.mjs +25 -8
- package/kits/hub-game/scripts/test-ask-client.mjs +9 -0
- package/kits/hub-game/scripts/test-ask-surface.mjs +188 -0
- package/kits/hub-game/scripts/test-attention.mjs +43 -1
- package/kits/hub-game/scripts/test-ballot-sheet-dom.mjs +71 -0
- package/kits/hub-game/scripts/test-ballot-surface.mjs +276 -0
- package/kits/hub-game/scripts/test-ballot.mjs +420 -3
- package/kits/hub-game/scripts/test-ban-join.mjs +1 -1
- package/kits/hub-game/scripts/test-celebrate-client.mjs +62 -0
- package/kits/hub-game/scripts/test-celebrate.mjs +116 -0
- package/kits/hub-game/scripts/test-chat.mjs +73 -0
- package/kits/hub-game/scripts/test-companion-client.mjs +203 -21
- package/kits/hub-game/scripts/test-companion.mjs +110 -3
- package/kits/hub-game/scripts/test-control-layout-dom.mjs +57 -10
- package/kits/hub-game/scripts/test-corner-surface.mjs +268 -0
- package/kits/hub-game/scripts/test-decor-client.mjs +59 -3
- package/kits/hub-game/scripts/test-decor.mjs +27 -0
- package/kits/hub-game/scripts/test-device-class.mjs +4 -1
- package/kits/hub-game/scripts/test-disguise-client.mjs +281 -0
- package/kits/hub-game/scripts/test-disguise.mjs +176 -0
- package/kits/hub-game/scripts/test-dock-surface.mjs +404 -0
- package/kits/hub-game/scripts/test-door-analytics.mjs +1 -1
- package/kits/hub-game/scripts/test-door-stay-client.mjs +602 -0
- package/kits/hub-game/scripts/test-door-stay.mjs +613 -0
- package/kits/hub-game/scripts/test-earned-client.mjs +119 -0
- package/kits/hub-game/scripts/test-emote-surface.mjs +616 -0
- package/kits/hub-game/scripts/test-fps-telemetry.mjs +39 -4
- package/kits/hub-game/scripts/test-friend-bests.mjs +38 -12
- package/kits/hub-game/scripts/test-ghost-click-dom.mjs +75 -0
- package/kits/hub-game/scripts/test-grab-client.mjs +29 -2
- package/kits/hub-game/scripts/test-grab-orbit.mjs +260 -11
- package/kits/hub-game/scripts/test-grab.mjs +10 -1
- package/kits/hub-game/scripts/test-hats.mjs +28 -0
- package/kits/hub-game/scripts/test-held-offers.mjs +394 -0
- package/kits/hub-game/scripts/test-high-only.mjs +3 -3
- package/kits/hub-game/scripts/test-hold-show-client.mjs +175 -0
- package/kits/hub-game/scripts/test-hold-show.mjs +355 -0
- package/kits/hub-game/scripts/test-hub-controls.mjs +3 -1
- package/kits/hub-game/scripts/test-hub-idle.mjs +348 -0
- package/kits/hub-game/scripts/test-hub-leaving.mjs +21 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +147 -0
- package/kits/hub-game/scripts/test-hub-trip.mjs +260 -5
- package/kits/hub-game/scripts/test-hud-clear.mjs +83 -0
- package/kits/hub-game/scripts/test-hud-rate.mjs +2 -1
- package/kits/hub-game/scripts/test-idle.mjs +160 -0
- package/kits/hub-game/scripts/test-invites-client.mjs +53 -0
- package/kits/hub-game/scripts/test-labels.mjs +11 -0
- package/kits/hub-game/scripts/test-landscape-layout.mjs +20 -0
- package/kits/hub-game/scripts/test-load-abandon.mjs +2 -2
- package/kits/hub-game/scripts/test-loading-cover.mjs +67 -1
- package/kits/hub-game/scripts/test-manifest.mjs +27 -0
- package/kits/hub-game/scripts/test-menu-client.mjs +55 -6
- package/kits/hub-game/scripts/test-menu-surface.mjs +236 -0
- package/kits/hub-game/scripts/test-npcs.mjs +128 -0
- package/kits/hub-game/scripts/test-observed.mjs +171 -3
- package/kits/hub-game/scripts/test-pack.mjs +166 -0
- package/kits/hub-game/scripts/test-picker-surface.mjs +321 -0
- package/kits/hub-game/scripts/test-placeat-server.mjs +395 -0
- package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
- package/kits/hub-game/scripts/test-pointer-clear-dom.mjs +82 -0
- package/kits/hub-game/scripts/test-progress-reset.mjs +184 -6
- package/kits/hub-game/scripts/test-push-visit.mjs +9 -0
- package/kits/hub-game/scripts/test-quality.mjs +312 -9
- package/kits/hub-game/scripts/test-quick-chat-surface.mjs +511 -0
- package/kits/hub-game/scripts/test-rehello.mjs +237 -0
- package/kits/hub-game/scripts/test-rejoin-yaw.mjs +138 -0
- package/kits/hub-game/scripts/test-relations-among.mjs +13 -7
- package/kits/hub-game/scripts/test-relations-refresh.mjs +90 -2
- package/kits/hub-game/scripts/test-replay-client.mjs +110 -0
- package/kits/hub-game/scripts/test-replay.mjs +178 -0
- package/kits/hub-game/scripts/test-resume-held.mjs +13 -0
- package/kits/hub-game/scripts/test-resume-pose-server.mjs +43 -5
- package/kits/hub-game/scripts/test-resync.mjs +13 -0
- package/kits/hub-game/scripts/test-role-client.mjs +10 -3
- package/kits/hub-game/scripts/test-safe-act.mjs +233 -0
- package/kits/hub-game/scripts/test-safe-caption.mjs +364 -0
- package/kits/hub-game/scripts/test-safe-layout.mjs +79 -0
- package/kits/hub-game/scripts/test-safe-prompt.mjs +163 -0
- package/kits/hub-game/scripts/test-sound-surface.mjs +256 -0
- package/kits/hub-game/scripts/test-soundscape.mjs +85 -2
- package/kits/hub-game/scripts/test-stuck-surface.mjs +174 -0
- package/kits/hub-game/scripts/test-stuck.mjs +31 -0
- package/kits/hub-game/scripts/test-talk-surface.mjs +23 -6
- package/kits/hub-game/scripts/test-talk-walk-dom.mjs +123 -0
- package/kits/hub-game/scripts/test-text-ask-surface.mjs +273 -0
- package/kits/hub-game/scripts/test-tiers.mjs +453 -3
- package/kits/hub-game/scripts/test-toast-no-row-dom.mjs +71 -0
- package/kits/hub-game/scripts/test-together.mjs +11 -0
- package/kits/hub-game/scripts/test-town-day.mjs +90 -0
- package/kits/hub-game/scripts/test-track-queue.mjs +64 -0
- package/kits/hub-game/scripts/test-try-on.mjs +39 -0
- package/kits/hub-game/scripts/test-ui-dom-dom.mjs +49 -2
- package/kits/hub-game/scripts/test-ui-tree.mjs +28 -0
- package/kits/hub-game/scripts/test-vehicle-client.mjs +77 -1
- package/kits/hub-game/scripts/test-vis.mjs +145 -0
- package/kits/hub-game/scripts/test-wallet.mjs +650 -0
- package/kits/hub-game/scripts/test-weakest-tier.mjs +135 -1
- package/kits/hub-game/scripts/test-world-labels.mjs +380 -0
- package/kits/hub-game/scripts/test-writer-lease-server.mjs +234 -0
- package/kits/hub-game/scripts/test-writer-lease.mjs +281 -0
- package/kits/hub-game/scripts/writer-storage-fixture.mjs +37 -0
- package/kits/hub-game/tools/hubScene/export.mjs +6 -5
- package/kits/hub-game/tools/hubScene/hubdata.mjs +10 -0
- package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +48 -2
- package/kits/hub-game/tools/hubScene/validate-manifest.mjs +21 -3
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/resumeGate.js +49 -2
- package/kits/multiplayer-3d/code/server/ownership.js +25 -6
- package/kits/multiplayer-3d/code/server/world.js +19 -4
- package/kits/multiplayer-3d/code/systems/multiplayer.js +67 -11
- package/kits/multiplayer-3d/package-lock.json +1 -1
- package/kits/multiplayer-3d/package.json +2 -1
- package/kits/multiplayer-3d/scripts/test-ground-half.mjs +56 -0
- package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +54 -3
- package/kits/multiplayer-3d/scripts/test-owned-moves.mjs +190 -0
- package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +191 -5
- package/kits/multiplayer-3d/scripts/test-resync-reconnect.mjs +68 -0
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/scene.js +10 -2
- package/kits/physics-3d/CLAUDE.md +14 -0
- package/kits/physics-3d/behaviors/Player.jsx +39 -3
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/docs/engine-model-cache.md +109 -0
- package/kits/physics-3d/docs/engine-player.md +76 -0
- package/kits/physics-3d/docs/engine-skip-work.md +16 -0
- package/kits/physics-3d/docs/pxmodel-format.md +5 -1
- package/kits/physics-3d/engine3d/gait.js +16 -8
- package/kits/physics-3d/engine3d/groundsize.js +23 -0
- package/kits/physics-3d/engine3d/kithooks.js +50 -0
- package/kits/physics-3d/engine3d/look.js +110 -17
- package/kits/physics-3d/engine3d/lookbake.js +19 -1
- package/kits/physics-3d/engine3d/materialpresets.js +3 -2
- package/kits/physics-3d/engine3d/modelcache.js +280 -0
- package/kits/physics-3d/engine3d/modelcachedigest.js +37 -0
- package/kits/physics-3d/engine3d/modelcachegate.js +69 -0
- package/kits/physics-3d/engine3d/modelrefs.js +13 -0
- package/kits/physics-3d/engine3d/optimize.js +20 -9
- package/kits/physics-3d/engine3d/playerRun.js +26 -1
- package/kits/physics-3d/engine3d/pxmodel.js +7 -3
- package/kits/physics-3d/engine3d/templatecache.js +722 -0
- package/kits/physics-3d/engine3d/world3d.js +211 -17
- package/kits/physics-3d/package-lock.json +1 -1
- package/kits/physics-3d/package.json +2 -1
- package/kits/physics-3d/play/behaviors/Player.js +43 -3
- package/kits/physics-3d/scripts/render.mjs +56 -8
- package/kits/physics-3d/scripts/template-cache-fixtures.mjs +37 -0
- package/kits/physics-3d/scripts/template-cache-v1-bytes.json +49 -0
- package/kits/physics-3d/scripts/test-gait.mjs +53 -9
- package/kits/physics-3d/scripts/test-ground-half.mjs +120 -0
- package/kits/physics-3d/scripts/test-model-cache.mjs +600 -0
- package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1 -0
- package/kits/physics-3d/scripts/test-sleeping-models.mjs +384 -0
- package/kits/physics-3d/scripts/test-template-cache-minified.mjs +106 -0
- package/kits/physics-3d/scripts/test-template-cache.mjs +519 -0
- package/kits/physics-3d/scripts/test-wall-slide.mjs +272 -0
- package/kits/physics-3d/systems/physics3d.js +51 -2
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/connection.js +3 -0
- package/package.json +2 -2
- package/vendor/three/examples/jsm/libs/fflate.module.js +2672 -0
package/kits/base/sdk/README.md
CHANGED
|
@@ -23,11 +23,13 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
|
|
|
23
23
|
- [Time](#time)
|
|
24
24
|
- [User](#user)
|
|
25
25
|
- [Experiments](#experiments)
|
|
26
|
+
- [Analytics](#analytics)
|
|
26
27
|
- [Avatar](#avatar)
|
|
27
28
|
- [Pass](#pass)
|
|
28
29
|
- [Snapshot](#snapshot)
|
|
29
30
|
- [Portal](#portal)
|
|
30
31
|
- [Social](#social)
|
|
32
|
+
- [Rooms](#rooms)
|
|
31
33
|
- [Party](#party)
|
|
32
34
|
- [Hub](#hub)
|
|
33
35
|
- [Decks](#decks)
|
|
@@ -36,6 +38,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
|
|
|
36
38
|
- [Agent](#agent)
|
|
37
39
|
- [Lifecycle](#lifecycle)
|
|
38
40
|
- [Display](#display)
|
|
41
|
+
- [DebugConsole](#debugconsole)
|
|
39
42
|
- [Multiplayer](#multiplayer)
|
|
40
43
|
- [Setup](#setup)
|
|
41
44
|
- [Saving files](#writefilepath-contents-promisevoid)
|
|
@@ -73,9 +76,13 @@ of foreground time; time while the page is hidden or frozen does not spend it,
|
|
|
73
76
|
and a stall of the page's JavaScript (a debugger pause, an app pausing its web
|
|
74
77
|
view) spends at most two seconds. After any return the SDK tries the reconnect
|
|
75
78
|
credential at least once before giving up on it. Retries wait for the page to
|
|
76
|
-
become visible and resume. A
|
|
79
|
+
become visible and resume. A drop found as the page comes back from being
|
|
80
|
+
hidden, frozen or suspended is retried at once; one met while the page is
|
|
81
|
+
running waits a short backoff first. A server rejecting the
|
|
77
82
|
credential or confirming the session ended can still trigger a fresh join sooner.
|
|
78
83
|
|
|
84
|
+
`connection.reconnect()` starts recovery for a connected socket and returns `true`; otherwise it returns `false`, including in solo mode.
|
|
85
|
+
|
|
79
86
|
`connection.serverBundleId` and `connection.serverBundleSha256` identify the server publication running the connected session. These read-only diagnostics are `null` before a live connection, while disconnected, in solo mode, or when the host does not provide them. The ID identifies a publication; the SHA-256 identifies its code bytes, so two publications can share a hash. Read the values again after a reconnect or a destination join. They describe the running server, not the client bundle or the deck’s newest save.
|
|
80
87
|
|
|
81
88
|
Experimental: `Multiplayer.join({ mode: "public", pongTimeoutMs: 10_000 })`
|
|
@@ -235,12 +242,27 @@ dev serve.
|
|
|
235
242
|
the third argument of `onPlayerJoin`.
|
|
236
243
|
- `session.hub.push` is optional, present only for a place declaring
|
|
237
244
|
`hub.push: { version: 1 }` on a capable runtime. Its
|
|
238
|
-
`visit(playerId, { userId, timezone })` reports
|
|
239
|
-
authenticated account and an IANA timezone.
|
|
245
|
+
`visit(playerId, { userId, timezone, phase? })` reports visit facts with the captured
|
|
246
|
+
authenticated account and an IANA timezone. Absent `phase` starts a visit as before;
|
|
247
|
+
its only optional value, `"end"` (v1.189), reports the end. The place server
|
|
248
|
+
remembers the account and timezone only after a start returns `true`, then sends
|
|
249
|
+
an end once from `leave` (at forget for a retained resume player, not backgrounding)
|
|
250
|
+
or for every remembered player at layer shutdown, and clears the entry.
|
|
251
|
+
It returns `true` only for `accepted === true`; errors and refusals return `false`.
|
|
252
|
+
Ignore `false` and never retry. An old host-agent or Ghost answers `false` for
|
|
253
|
+
an end, and Ghost derives from the start. Ghost keeps the latest end per user,
|
|
254
|
+
place and join generation, dropping an end older than the start or from an old
|
|
255
|
+
generation. Landing order: Ghost first, then the host-agent, then the deck save.
|
|
240
256
|
Ghost derives the three-day come-back reminder and checks consent, answered
|
|
241
257
|
age, experiments, quiet hours and delivery limits. Reporting a visit does not
|
|
242
258
|
opt the player in or promise a notification. No crop reporting or queue
|
|
243
|
-
reconciliation API is exposed.
|
|
259
|
+
reconciliation API is exposed. On a runtime with preferences it also has
|
|
260
|
+
`preference(playerId, change)`: `{}` reads, `{ enabled: boolean }` sets
|
|
261
|
+
consent and `{ declined: true }` records a declined prompt. It returns
|
|
262
|
+
`{ accepted: true, enabled, globalEnabled, touched, milestone, nextPromptAt }`
|
|
263
|
+
or `null` when refused or unavailable, and never throws. `touched` says the
|
|
264
|
+
player has ever set this place's preference; `nextPromptAt` is non-null once
|
|
265
|
+
they declined or disabled. Consent is checked again by Ghost on delivery.
|
|
244
266
|
- `session.hub.reportResult(playerId, { outcome?, score?, stats? })` records a
|
|
245
267
|
signed-in player's result for this visit, once. The host checks it against the
|
|
246
268
|
published shape and Castle keeps it only for a place behind a curated door;
|
|
@@ -321,6 +343,9 @@ arms the player's page reads and nothing a client can claim.
|
|
|
321
343
|
such experiment.
|
|
322
344
|
- `session.experiments(player)` is all of them, `{ name: variant }`.
|
|
323
345
|
|
|
346
|
+
The first `session.experiment` of each name for a player's join records an
|
|
347
|
+
exposure, as the client's first read does; `session.experiments` records none.
|
|
348
|
+
|
|
324
349
|
Both answer from `onPlayerJoin` until the player leaves, and `null` / `{}`
|
|
325
350
|
after. The variants are never on the player object, so a roster or state built
|
|
326
351
|
from `session.players` does not show one player's arm to another; send a variant
|
|
@@ -539,6 +564,28 @@ the page made before calling it, even ones still being batched; await an
|
|
|
539
564
|
`increment` or a board `submit` first if the answer should include it. A player can only ever see their own usage, not
|
|
540
565
|
another player's.
|
|
541
566
|
|
|
567
|
+
`rate` says how much of the per-second rate limits (the last two rows of
|
|
568
|
+
the table below) is spent right now, so a deck that writes often can back
|
|
569
|
+
off before a call is refused rather than after:
|
|
570
|
+
|
|
571
|
+
```js
|
|
572
|
+
const { rate } = await Store.usage();
|
|
573
|
+
if (rate && rate.caller.opsUsed > rate.caller.opsLimit * 0.8) {
|
|
574
|
+
// Close to this player's calls-per-second limit: batch or slow down.
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
- `rate.caller` is the current player's own limit, and `rate.deck` is the
|
|
579
|
+
one every player of the deck shares.
|
|
580
|
+
- Each has `opsUsed`, `opsLimit`, `bytesUsed` and `bytesLimit`, counted
|
|
581
|
+
over the current one-second window, and the `usage` call itself is
|
|
582
|
+
counted in them.
|
|
583
|
+
- `rate.callerClass` names which limit `caller` is: `"client"` for a
|
|
584
|
+
page.
|
|
585
|
+
|
|
586
|
+
`rate` is missing when the app is older than it, so check for it before
|
|
587
|
+
reading it.
|
|
588
|
+
|
|
542
589
|
An app too old to know `usage` rejects with a `CastleError` whose `code`
|
|
543
590
|
is `UNKNOWN_COMMAND`.
|
|
544
591
|
|
|
@@ -1073,9 +1120,14 @@ in no such experiment: the deck does not declare it, it was removed, or the host
|
|
|
1073
1120
|
is an older one that knows nothing of experiments. Always give `null` a
|
|
1074
1121
|
behavior, normally the one the deck had before the test.
|
|
1075
1122
|
|
|
1123
|
+
The first read of each name that returns a variant also records an exposure,
|
|
1124
|
+
the moment the player was shown that arm, for the deck's analytics. Read it
|
|
1125
|
+
where the variant changes what the player sees, not up front.
|
|
1126
|
+
|
|
1076
1127
|
### `experiments(): Record<string, string>`
|
|
1077
1128
|
|
|
1078
|
-
Every experiment this player is in on this deck, as `{ name: variant }`.
|
|
1129
|
+
Every experiment this player is in on this deck, as `{ name: variant }`. It
|
|
1130
|
+
records no exposure.
|
|
1079
1131
|
|
|
1080
1132
|
### `experimentsReady(): Promise<Record<string, string>>`
|
|
1081
1133
|
|
|
@@ -1093,10 +1145,64 @@ assigned to you exactly as they will be once the deck is saved. Add
|
|
|
1093
1145
|
experiment and one of its variants); it holds for the whole serve, client and
|
|
1094
1146
|
local server alike, until `?experiment.<name>=` clears it or the serve stops.
|
|
1095
1147
|
An open deck page keeps the arm it loaded with until it is reloaded.
|
|
1096
|
-
|
|
1148
|
+
On a published deck the same parameter on the deck's page forces an arm for the
|
|
1149
|
+
deck's owner only, for a day; see [docs/ab-tests.md](../docs/ab-tests.md#try-an-arm-on-the-published-deck).
|
|
1150
|
+
`devExperiments` in `castle.json`, a
|
|
1097
1151
|
`{ "name": "variant" }` map, answers for experiments the deck does not declare
|
|
1098
1152
|
itself (ones Castle runs across decks), on the serve only.
|
|
1099
1153
|
|
|
1154
|
+
## Analytics
|
|
1155
|
+
|
|
1156
|
+
A deck's own named events, recorded in its creator analytics beside Castle's
|
|
1157
|
+
built-in ones (plays, play time, players who come back).
|
|
1158
|
+
|
|
1159
|
+
```js
|
|
1160
|
+
import { Analytics } from "castle-web-sdk";
|
|
1161
|
+
|
|
1162
|
+
Analytics.event("level_complete", { level: 3, seconds: 41 });
|
|
1163
|
+
```
|
|
1164
|
+
|
|
1165
|
+
### `Analytics.event(name, properties?): void`
|
|
1166
|
+
|
|
1167
|
+
Records one event for the player. Synchronous and fire and forget: it returns
|
|
1168
|
+
nothing, and a host that cannot record it (an older one, or no network) drops
|
|
1169
|
+
it without the deck noticing.
|
|
1170
|
+
|
|
1171
|
+
- `name` is trimmed, then 1 to 64 characters of letters, digits, space and
|
|
1172
|
+
`_ . : / -`, starting with a letter or digit.
|
|
1173
|
+
- `properties` is optional: a plain object of at most 5 keys, each 1 to 32
|
|
1174
|
+
characters under the same rule, whose values are finite numbers. Castle stores
|
|
1175
|
+
each as a whole number (rounded).
|
|
1176
|
+
- A bad name or properties throws a `TypeError` at the call, so a mistake shows
|
|
1177
|
+
up while you build the deck.
|
|
1178
|
+
- At most 60 events a minute per page load; the rest are dropped, with one
|
|
1179
|
+
console warning the first time.
|
|
1180
|
+
|
|
1181
|
+
**An event has to be registered before players' events are kept.** Castle keeps
|
|
1182
|
+
a list of event types per creator, up to 100 across all of a creator's decks.
|
|
1183
|
+
When the deck's creator plays the published deck, each `Analytics.event` call
|
|
1184
|
+
registers its name, with its property keys in the order the call gives them;
|
|
1185
|
+
the creator's own plays are not counted. After that, players' events with that
|
|
1186
|
+
name are recorded, carrying the properties the type names. A player's event
|
|
1187
|
+
under a name the creator never registered is dropped, as are property keys the
|
|
1188
|
+
type does not name. So play every path that sends an event once, signed in as
|
|
1189
|
+
the deck's owner, after saving the deck.
|
|
1190
|
+
|
|
1191
|
+
Registration is limited: at most 20 registrations per creator per hour (a new
|
|
1192
|
+
name, or a property key added to an existing name, each counts as one), and at
|
|
1193
|
+
most 100 event types per creator. A call past either limit registers nothing,
|
|
1194
|
+
so the name stays unregistered and players' events under it are dropped until
|
|
1195
|
+
the creator plays it again after the hour has passed. To see what is registered, the `creatorEventTypes` query in Castle's API
|
|
1196
|
+
lists the creator's event types with their property names, in slot order;
|
|
1197
|
+
`createCreatorEventType` registers one directly.
|
|
1198
|
+
|
|
1199
|
+
Only a published deck records events: on `castle-web serve` of a deck that was
|
|
1200
|
+
never saved, `Analytics.event` validates its arguments and sends nothing.
|
|
1201
|
+
|
|
1202
|
+
Each event carries the player's experiment arms, like the built-in events, so
|
|
1203
|
+
`creatorEventStats` with `splitBy: EXPERIMENT` reads custom events per variant;
|
|
1204
|
+
see [Measure a variant with your own events](../docs/ab-tests.md#measure-a-variant-with-your-own-events).
|
|
1205
|
+
|
|
1100
1206
|
## Avatar
|
|
1101
1207
|
|
|
1102
1208
|
The player's platform avatar: one per account, worn in every hub place
|
|
@@ -1247,6 +1353,45 @@ const friends = await Social.friends();
|
|
|
1247
1353
|
const playingHere = await Social.presence();
|
|
1248
1354
|
```
|
|
1249
1355
|
|
|
1356
|
+
## Rooms
|
|
1357
|
+
|
|
1358
|
+
### `Rooms.list(): Promise<RoomsListResult | null>`
|
|
1359
|
+
|
|
1360
|
+
This deck's public multiplayer rooms and how many players are in each, for a
|
|
1361
|
+
lobby, a room picker or a "12 playing now" line. No room has to write its own
|
|
1362
|
+
count to `Store` for a menu to read.
|
|
1363
|
+
|
|
1364
|
+
```js
|
|
1365
|
+
import { Rooms } from "castle-web-sdk";
|
|
1366
|
+
|
|
1367
|
+
const list = await Rooms.list();
|
|
1368
|
+
if (list) {
|
|
1369
|
+
label.textContent = `${list.total} playing now`;
|
|
1370
|
+
for (const room of list.rooms) {
|
|
1371
|
+
// { sessionId, routeId?, slot?, players, maxPlayers }
|
|
1372
|
+
}
|
|
1373
|
+
}
|
|
1374
|
+
```
|
|
1375
|
+
|
|
1376
|
+
- `total` is the players across every listed room; `rooms` is one entry per
|
|
1377
|
+
room, with `routeId` and `slot` as the deck passed them to
|
|
1378
|
+
`Multiplayer.joinDestination` (absent for a room `Multiplayer.join`
|
|
1379
|
+
opened).
|
|
1380
|
+
- It resolves `null` when Castle will not list the deck's rooms for this
|
|
1381
|
+
player. The deck's owner and Castle admins always get a list; whether
|
|
1382
|
+
other players do depends on how far Castle has rolled presence out, so
|
|
1383
|
+
handle `null` for any player. A player under 13, or one Castle keeps out
|
|
1384
|
+
of multiplayer, gets `null` even on their own deck. Treat `null` as "not available", never as "no
|
|
1385
|
+
rooms": a deck nobody is playing answers `{ total: 0, rooms: [] }`.
|
|
1386
|
+
- An app built before the call also resolves `null` rather than throwing
|
|
1387
|
+
`UNKNOWN_COMMAND`. An unsaved deck throws `MISSING_DECK_ID`.
|
|
1388
|
+
- Counts come from a rollup Castle refreshes about every 10 seconds, so a
|
|
1389
|
+
player who joined or left in the last few seconds may not show yet. Poll it
|
|
1390
|
+
no more than every 10 seconds; there is no event.
|
|
1391
|
+
- Only public rooms are listed. Private, party and named rooms are not.
|
|
1392
|
+
- A local `castle-web serve` lists the saved deck's rooms on Castle, not the
|
|
1393
|
+
rooms of the local serve.
|
|
1394
|
+
|
|
1250
1395
|
## Party
|
|
1251
1396
|
|
|
1252
1397
|
`Party` creates and drives Castle parties with the signed-in player's account.
|
|
@@ -1306,6 +1451,14 @@ With `canInvite: true`, newer hosts also name the account the links belong to
|
|
|
1306
1451
|
account is the player's own, and checks `User.getCurrent()` when a host names
|
|
1307
1452
|
none.
|
|
1308
1453
|
|
|
1454
|
+
`Hub.inviteAvailable()` takes no parameters and reads the authenticated viewer's
|
|
1455
|
+
invite gate through the trusted, invite-enabled hub visit. It answers
|
|
1456
|
+
`{ status: 'ok', available: boolean }`, or `{ status: 'unavailable' }` when the
|
|
1457
|
+
viewer is signed out or anonymous, the visit or invite opt-in is absent, the
|
|
1458
|
+
read fails, or the host predates the command. It creates no invite and exposes
|
|
1459
|
+
no gate map. The opt-in Character entry also requires `available: true`;
|
|
1460
|
+
pending, false and unavailable answers keep it hidden.
|
|
1461
|
+
|
|
1309
1462
|
The trusted host resolves the link after sign-in, retains its token, and requests
|
|
1310
1463
|
the inviter's layer when it has room. If resolution refuses the invite, the host
|
|
1311
1464
|
discards it for that visit and joins normally. Transient resolution failures
|
|
@@ -1345,6 +1498,19 @@ the signed-in account id. A new host without native sign-in support returns
|
|
|
1345
1498
|
`unavailable`; an older host that does not know this command rejects with
|
|
1346
1499
|
`UNKNOWN_COMMAND`.
|
|
1347
1500
|
|
|
1501
|
+
`Hub.pushPermission()` (hub contract v1.177) may ask the native host to request
|
|
1502
|
+
OS notification permission. Call it only from a deliberate tap after the player
|
|
1503
|
+
committed to something worth a reminder. It waits for the player's answer and
|
|
1504
|
+
resolves to `{ status: 'granted' | 'denied' | 'unavailable' }`.
|
|
1505
|
+
`Hub.pushDestination()` reads, once, the native push hint that opened the app
|
|
1506
|
+
into this town: `{ notificationId, townDeckId }` or `{ status: 'unavailable' }`.
|
|
1507
|
+
On mobile the SDK acknowledges a delivered hint back to the host as soon as it
|
|
1508
|
+
resolves the call; a deck does nothing extra. Both take no arguments and answer
|
|
1509
|
+
`unavailable` on web, for a signed-out player, outside a joined session, or
|
|
1510
|
+
where the host does not offer hub notifications. A host that predates them
|
|
1511
|
+
(`UNKNOWN_COMMAND`) or no reachable host (`CASTLE_HOST_UNAVAILABLE`) also reads
|
|
1512
|
+
as `unavailable`; any other failure rejects with its `CastleError`.
|
|
1513
|
+
|
|
1348
1514
|
- `Hub.doors()` reads the current place's doors and who is inside them:
|
|
1349
1515
|
`{ status: "ok", doors }` or `{ status: "unavailable", doors: null }`. A row has
|
|
1350
1516
|
`doorId`, `launcherKind` (`door`, `table`, `cabinet`, `gate`), `placementKind`
|
|
@@ -1408,6 +1574,14 @@ the signed-in account id. A new host without native sign-in support returns
|
|
|
1408
1574
|
`Hub.go(doorId)` (with `{ ownerUserId: owner }` when set) behind its door
|
|
1409
1575
|
animation. Hosts that never send it are the norm. Returns an unsubscribe
|
|
1410
1576
|
function.
|
|
1577
|
+
- `Hub.goFailed({ doorId, owner }, why)` tells the host that a Go it sent
|
|
1578
|
+
(`Hub.onGo`) ended without the player going through: `why` is `"refused"`
|
|
1579
|
+
(`Hub.go` gave no handoff), `"content"` (the destination's content would not
|
|
1580
|
+
load) or `"join"` (the join was never committed). Call it at most once per
|
|
1581
|
+
Go, and not for a join the host committed. A host that acquired the door
|
|
1582
|
+
from its own session may acquire it again there and send a fresh Go; do not
|
|
1583
|
+
ask `Hub.go` again yourself. One-way: nothing answers it, and older hosts
|
|
1584
|
+
ignore it.
|
|
1411
1585
|
|
|
1412
1586
|
A player Castle has barred from the hub is refused at every hub door and at the
|
|
1413
1587
|
town itself with `CastleError` code `CAULDRON_HUB_BANNED` (from `Hub.go`,
|
|
@@ -1806,6 +1980,44 @@ deck's preferred display orientation: `landscape`, `portrait`, or `any`.
|
|
|
1806
1980
|
Missing or unrecognized preferences mean `any`; read the value as
|
|
1807
1981
|
`display.orientation ?? "any"`.
|
|
1808
1982
|
|
|
1983
|
+
## DebugConsole
|
|
1984
|
+
|
|
1985
|
+
A published deck's `console` output never reaches devtools: on
|
|
1986
|
+
castle.xyz the deck runs in a sandboxed frame of its own, and in the
|
|
1987
|
+
app it runs in a WebView. `DebugConsole` draws the deck's console as a
|
|
1988
|
+
panel along the bottom of the deck itself, so it can be read on the
|
|
1989
|
+
device the deck is running on.
|
|
1990
|
+
|
|
1991
|
+
- **`DebugConsole.show()`** — opens the panel. It holds the last 300
|
|
1992
|
+
lines of `console.log`, `console.warn` and `console.error`, plus
|
|
1993
|
+
uncaught errors and unhandled promise rejections. After
|
|
1994
|
+
[`setup()`](#setup) that includes everything since the deck started;
|
|
1995
|
+
in a deck that never calls `setup()`, only what comes after the first
|
|
1996
|
+
`show()`. The panel has **Clear** and **Hide** buttons.
|
|
1997
|
+
- **`DebugConsole.hide()`** — closes the panel. Lines keep being
|
|
1998
|
+
recorded.
|
|
1999
|
+
- **`DebugConsole.lines(): DebugConsoleLine[]`** — the recorded lines,
|
|
2000
|
+
oldest first, each `{ level: "log" | "warn" | "error", text, time }`
|
|
2001
|
+
with `time` from `Date.now()`, for a deck that draws its own.
|
|
2002
|
+
|
|
2003
|
+
The panel covers the bottom of the deck and takes touches there, so
|
|
2004
|
+
open it from a gesture or a debug option the deck controls, and remove
|
|
2005
|
+
that before the deck is for players:
|
|
2006
|
+
|
|
2007
|
+
```js
|
|
2008
|
+
import { DebugConsole } from "castle-web-sdk";
|
|
2009
|
+
|
|
2010
|
+
// Three fingers on the card toggles the console.
|
|
2011
|
+
let open = false;
|
|
2012
|
+
window.addEventListener("touchstart", (event) => {
|
|
2013
|
+
if (event.touches.length === 3) {
|
|
2014
|
+
open = !open;
|
|
2015
|
+
if (open) DebugConsole.show();
|
|
2016
|
+
else DebugConsole.hide();
|
|
2017
|
+
}
|
|
2018
|
+
});
|
|
2019
|
+
```
|
|
2020
|
+
|
|
1809
2021
|
## Setup
|
|
1810
2022
|
|
|
1811
2023
|
Startup, editor-mode check, and a file-write call for editor UI.
|
|
@@ -1821,6 +2033,17 @@ While running locally with `castle-web serve`, it also forwards
|
|
|
1821
2033
|
`console` output to the CLI and reloads the page when `castle-web
|
|
1822
2034
|
restart` runs.
|
|
1823
2035
|
|
|
2036
|
+
`setup()` also keeps `history.pushState` and `history.replaceState`
|
|
2037
|
+
from throwing in a deck published on castle.xyz. There the deck's frame
|
|
2038
|
+
has no origin of its own, and a call that passes a URL throws a
|
|
2039
|
+
`SecurityError`; after
|
|
2040
|
+
`setup()` the call adds or replaces the history entry with its state
|
|
2041
|
+
but leaves the address as it was. A router that keeps its route in the
|
|
2042
|
+
address won't see it change; keep the route in the state or in the
|
|
2043
|
+
deck's own variables. `localStorage` throws there too; use
|
|
2044
|
+
[`LocalCache`](#localcache) for things the deck can rebuild and
|
|
2045
|
+
[`Store`](#store) for everything else.
|
|
2046
|
+
|
|
1824
2047
|
```js
|
|
1825
2048
|
import { setup } from "castle-web-sdk";
|
|
1826
2049
|
|
|
@@ -1951,8 +2174,17 @@ load its assets through the bundler instead.
|
|
|
1951
2174
|
A multiplayer socket closed before its first hello reports its WebSocket close
|
|
1952
2175
|
code in `error.extensions.closeCode` when available. Code `4404` means the
|
|
1953
2176
|
play proxy could not route the session (`not_running`); it does not prove the
|
|
1954
|
-
runtime ended. A
|
|
1955
|
-
a
|
|
2177
|
+
runtime ended. A hub join refused this way tries the same handoff again for a
|
|
2178
|
+
few seconds, since a session ghost has just started can briefly be unroutable;
|
|
2179
|
+
the error is reported only when those tries run out. A failed hub join cancels
|
|
2180
|
+
its handoff, so retrying a door after that requires a fresh `Hub.go` acquisition.
|
|
2181
|
+
|
|
2182
|
+
`Hub.go`, `Hub.back`, `Hub.jump`, `Multiplayer.join`'s session request and
|
|
2183
|
+
`Multiplayer.joinDestination` ask the host again when it fails in transit
|
|
2184
|
+
(`CASTLE_HOST_ERROR`, e.g. a 502 from Castle's API): after 1, 2, 4 and 8 s,
|
|
2185
|
+
then the last error is thrown. `Hub.cancel` ends that wait with `cancelled`, as
|
|
2186
|
+
does a newer destination join; a newer `Multiplayer.join` stops an older one's
|
|
2187
|
+
tries. Any other code (`FORBIDDEN`, `LOGIN_REQUIRED`, ...) fails at once.
|
|
1956
2188
|
|
|
1957
2189
|
Every error the SDK throws is a `CastleError`. Check `code` to tell
|
|
1958
2190
|
the kinds apart.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export interface CastleAnalyticsApi {
|
|
2
|
+
/**
|
|
3
|
+
* Records one named event, with up to five numeric properties, for the deck's
|
|
4
|
+
* creator analytics. Synchronous and fire and forget.
|
|
5
|
+
*/
|
|
6
|
+
event(name: string, properties?: Record<string, number>): void;
|
|
7
|
+
}
|
|
8
|
+
export declare const Analytics: CastleAnalyticsApi;
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
// Analytics — a deck's own named events, recorded in its creator analytics.
|
|
2
|
+
//
|
|
3
|
+
// Analytics.event("level_complete", { level: 3, seconds: 41 });
|
|
4
|
+
//
|
|
5
|
+
// Fire and forget: the call validates its arguments synchronously (a bad name
|
|
6
|
+
// or properties shape is a coding error, so it throws a TypeError the author
|
|
7
|
+
// sees in dev) and then tells the host, which records the event for a published
|
|
8
|
+
// deck's real players. Nothing is returned and nothing is awaited: an older host
|
|
9
|
+
// refuses the unknown command and a failed report never reaches the deck.
|
|
10
|
+
//
|
|
11
|
+
// Castle keeps a registry per creator: the deck's creator playing the deck
|
|
12
|
+
// registers each event name with its property keys, and a player's event under
|
|
13
|
+
// a name that is not registered is dropped. Each row carries the player's
|
|
14
|
+
// experiment arms, so creator analytics can split custom events by experiment.
|
|
15
|
+
import { hostRequest } from "./transport";
|
|
16
|
+
export const Analytics = {
|
|
17
|
+
event,
|
|
18
|
+
};
|
|
19
|
+
const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.:/-]*$/;
|
|
20
|
+
const MAX_NAME_LENGTH = 64;
|
|
21
|
+
const MAX_KEY_LENGTH = 32;
|
|
22
|
+
const MAX_PROPERTIES = 5;
|
|
23
|
+
const RATE_LIMIT = 60;
|
|
24
|
+
const RATE_WINDOW_MS = 60_000;
|
|
25
|
+
// When each recent event was sent, oldest first, for the rolling-minute limit.
|
|
26
|
+
const sentAt = [];
|
|
27
|
+
let warnedRateLimit = false;
|
|
28
|
+
function event(name, properties) {
|
|
29
|
+
const trimmed = checkName(name);
|
|
30
|
+
const props = checkProperties(properties);
|
|
31
|
+
if (!admit())
|
|
32
|
+
return;
|
|
33
|
+
try {
|
|
34
|
+
void hostRequest("analytics.event", { name: trimmed, properties: props }).catch(() => { });
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
// No host to tell.
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
function checkName(name) {
|
|
41
|
+
if (typeof name !== "string") {
|
|
42
|
+
throw new TypeError("Analytics.event name must be a string.");
|
|
43
|
+
}
|
|
44
|
+
const trimmed = name.trim();
|
|
45
|
+
if (trimmed.length === 0 || trimmed.length > MAX_NAME_LENGTH || !NAME_PATTERN.test(trimmed)) {
|
|
46
|
+
throw new TypeError(`Analytics.event name must be 1 to ${MAX_NAME_LENGTH} characters of letters, digits, ` +
|
|
47
|
+
"space, _ . : / and -, starting with a letter or digit.");
|
|
48
|
+
}
|
|
49
|
+
return trimmed;
|
|
50
|
+
}
|
|
51
|
+
function checkProperties(properties) {
|
|
52
|
+
if (properties === undefined || properties === null)
|
|
53
|
+
return {};
|
|
54
|
+
if (typeof properties !== "object" || Array.isArray(properties)) {
|
|
55
|
+
throw new TypeError("Analytics.event properties must be a plain object of numbers.");
|
|
56
|
+
}
|
|
57
|
+
const proto = Object.getPrototypeOf(properties);
|
|
58
|
+
if (proto !== Object.prototype && proto !== null) {
|
|
59
|
+
throw new TypeError("Analytics.event properties must be a plain object of numbers.");
|
|
60
|
+
}
|
|
61
|
+
const entries = Object.entries(properties);
|
|
62
|
+
if (entries.length > MAX_PROPERTIES) {
|
|
63
|
+
throw new TypeError(`Analytics.event takes at most ${MAX_PROPERTIES} properties.`);
|
|
64
|
+
}
|
|
65
|
+
for (const [key, value] of entries) {
|
|
66
|
+
if (key.length > MAX_KEY_LENGTH || !NAME_PATTERN.test(key)) {
|
|
67
|
+
throw new TypeError(`Analytics.event property "${key}" must be 1 to ${MAX_KEY_LENGTH} characters, ` +
|
|
68
|
+
"following the same rule as an event name.");
|
|
69
|
+
}
|
|
70
|
+
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
71
|
+
throw new TypeError(`Analytics.event property "${key}" must be a finite number.`);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
return Object.fromEntries(entries);
|
|
75
|
+
}
|
|
76
|
+
// At most RATE_LIMIT events in any rolling RATE_WINDOW_MS per page load; the
|
|
77
|
+
// rest are dropped, with one warning the first time.
|
|
78
|
+
function admit() {
|
|
79
|
+
const now = Date.now();
|
|
80
|
+
while (sentAt.length > 0 && now - sentAt[0] >= RATE_WINDOW_MS)
|
|
81
|
+
sentAt.shift();
|
|
82
|
+
if (sentAt.length >= RATE_LIMIT) {
|
|
83
|
+
if (!warnedRateLimit) {
|
|
84
|
+
warnedRateLimit = true;
|
|
85
|
+
console.warn(`Castle Analytics.event is limited to ${RATE_LIMIT} events a minute; ` +
|
|
86
|
+
"events past that are dropped.");
|
|
87
|
+
}
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
sentAt.push(now);
|
|
91
|
+
return true;
|
|
92
|
+
}
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { isEdit } from "./context";
|
|
2
2
|
export { Agent } from "./agent";
|
|
3
3
|
export type { AgentChatDelta, AgentChatParams, AgentChatResult, AgentMessage, AgentReasoning, AgentTool, AgentToolCall, AgentToolChoice, AgentUsage, CastleAgentApi, } from "./agent";
|
|
4
|
+
export { Analytics } from "./analytics";
|
|
5
|
+
export type { CastleAnalyticsApi } from "./analytics";
|
|
4
6
|
export { Avatar } from "./avatar";
|
|
5
7
|
export type { AvatarResult, CastleAvatarApi } from "./avatar";
|
|
6
8
|
export { Characters } from "./characters";
|
|
@@ -13,7 +15,9 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
|
|
|
13
15
|
export { Haptics } from "./haptics";
|
|
14
16
|
export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
|
|
15
17
|
export { Hub } from "./hub";
|
|
16
|
-
export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoRequest, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
|
|
18
|
+
export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteAvailableResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubGoFailedWhy, HubGoRequest, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
|
|
19
|
+
export { Rooms } from "./rooms";
|
|
20
|
+
export type { CastleRoomsApi, RoomSummary, RoomsListResult } from "./rooms";
|
|
17
21
|
export { Social } from "./social";
|
|
18
22
|
export type { CastleSocialApi, SocialFriend, SocialPresence } from "./social";
|
|
19
23
|
export { Party } from "./party";
|
|
@@ -42,11 +46,13 @@ export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
|
|
|
42
46
|
export type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
|
|
43
47
|
export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
|
|
44
48
|
export type { SaveState } from "./saveQueue";
|
|
49
|
+
export { DebugConsole } from "./debugConsole";
|
|
50
|
+
export type { DebugConsoleApi, DebugConsoleLevel, DebugConsoleLine } from "./debugConsole";
|
|
45
51
|
export { LocalCache } from "./localCache";
|
|
46
52
|
export type { LocalCacheApi } from "./localCache";
|
|
47
53
|
export { SharedStorage, Storage } from "./storage";
|
|
48
54
|
export { Store } from "./store";
|
|
49
|
-
export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreScopeApi, StoreUsage, } from "./store";
|
|
55
|
+
export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreRateBudget, StoreRateUsage, StoreScopeApi, StoreUsage, } from "./store";
|
|
50
56
|
export { Time } from "./time";
|
|
51
57
|
export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
|
|
52
58
|
export type { Json } from "./types";
|
package/kits/base/sdk/castle.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// Castle Web SDK
|
|
2
2
|
export { isEdit } from "./context";
|
|
3
3
|
export { Agent } from "./agent";
|
|
4
|
+
export { Analytics } from "./analytics";
|
|
4
5
|
export { Avatar } from "./avatar";
|
|
5
6
|
export { Characters } from "./characters";
|
|
6
7
|
export { Decks } from "./decks";
|
|
@@ -9,6 +10,7 @@ export { experiment, experiments, experimentsReady } from "./experiments";
|
|
|
9
10
|
export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
|
|
10
11
|
export { Haptics } from "./haptics";
|
|
11
12
|
export { Hub } from "./hub";
|
|
13
|
+
export { Rooms } from "./rooms";
|
|
12
14
|
export { Social } from "./social";
|
|
13
15
|
export { Party } from "./party";
|
|
14
16
|
export { Leaderboard } from "./leaderboard";
|
|
@@ -22,6 +24,7 @@ export { Portal } from "./portal";
|
|
|
22
24
|
export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
|
|
23
25
|
export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
|
|
24
26
|
export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
|
|
27
|
+
export { DebugConsole } from "./debugConsole";
|
|
25
28
|
export { LocalCache } from "./localCache";
|
|
26
29
|
export { SharedStorage, Storage } from "./storage";
|
|
27
30
|
export { Store } from "./store";
|