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/dist/index.js
CHANGED
|
@@ -39,6 +39,8 @@ const FLAGS_WITH_VALUES = new Set([
|
|
|
39
39
|
'--reason',
|
|
40
40
|
'--remote',
|
|
41
41
|
'--base-url',
|
|
42
|
+
'--deck',
|
|
43
|
+
'--room',
|
|
42
44
|
]);
|
|
43
45
|
// `--foo` is always a flag; a single dash only when it is one we know (`-m`).
|
|
44
46
|
// Anything else starting with `-` is a positional -- a path can begin with one,
|
|
@@ -104,16 +106,19 @@ async function askTerminal(question) {
|
|
|
104
106
|
terminal.close();
|
|
105
107
|
}
|
|
106
108
|
}
|
|
107
|
-
// `castle-web reset-leaderboards [dir] [--deck-id ID] [--yes]`.
|
|
109
|
+
// `castle-web reset-leaderboards [dir] [--deck-id ID] [--yes] [--undo]`.
|
|
108
110
|
async function resetLeaderboardsCommand() {
|
|
109
111
|
const deckDir = path.resolve(findPositionalDir());
|
|
110
112
|
await resetLeaderboards({
|
|
111
113
|
deckId: getFlagValue('--deck-id') ?? readCastleJson(deckDir)?.deckId,
|
|
112
114
|
yes: hasFlag('--yes'),
|
|
115
|
+
undo: hasFlag('--undo'),
|
|
113
116
|
}, {
|
|
114
117
|
signedIn: !!config.getToken(),
|
|
115
118
|
deckTitle: async (deckId) => (await api.deckMeta(deckId))?.title ?? null,
|
|
116
|
-
|
|
119
|
+
resetDeckLeaderboards: api.resetCauldronDeckLeaderboards,
|
|
120
|
+
undoDeckLeaderboardsReset: api.undoCauldronDeckLeaderboardsReset,
|
|
121
|
+
clearClassicLeaderboards: api.clearDeckLeaderboards,
|
|
117
122
|
interactive: !!process.stdin.isTTY,
|
|
118
123
|
confirm: askTerminal,
|
|
119
124
|
log: (line) => console.log(line),
|
|
@@ -190,7 +195,8 @@ function usage() {
|
|
|
190
195
|
castle-web get-deck <dir> --side [--deck-id ID] [--json] (fetches the saved copy into <dir>/.castle/agent/saved-source/<stamp>/, touching nothing else)
|
|
191
196
|
castle-web source-status <dir> [--adopt] [--notify] [--json] (whether the deck's saved copy is newer than this folder)
|
|
192
197
|
castle-web list-decks [dir] [--kind mine|saved|kits] (decks this one could import; ids are what add-import takes)
|
|
193
|
-
castle-web
|
|
198
|
+
castle-web logs [dir] [--deck ID] [--room ROOM] [--rooms] [--json] [--staging] (a published deck's multiplayer room: state, end reason, exit code, out-of-memory kill and its last server log lines; no --room means the newest room; --rooms lists recent rooms; creator only)
|
|
199
|
+
castle-web reset-leaderboards [dir] [--deck-id ID] [--yes] [--undo] (clears every leaderboard on the deck, saved data kept; creator only; --undo puts the scores back for a day; --yes skips the prompt)
|
|
194
200
|
castle-web add-import <deckId|url|kit> [dir] [--as ALIAS] (adds another deck, or a kit this CLI ships, as a read-only dependency in imports/)
|
|
195
201
|
castle-web fork-import-file <imports/...> [dir] (this deck's own version of one imported file)
|
|
196
202
|
castle-web revert-import-file <imports/...> [dir]
|
|
@@ -720,6 +726,19 @@ async function main() {
|
|
|
720
726
|
await runMcpPlaytestServer(path.resolve(dir), getFlagValue('--task-id'));
|
|
721
727
|
return;
|
|
722
728
|
}
|
|
729
|
+
case 'logs': {
|
|
730
|
+
// `castle-web logs [dir] [--deck ID] [--room SESSION] [--rooms] [--json] [--staging]`
|
|
731
|
+
const { roomLogsCommand } = await import('./roomLogs.js');
|
|
732
|
+
await roomLogsCommand({
|
|
733
|
+
dir: path.resolve(findPositionalDir()),
|
|
734
|
+
deckId: getFlagValue('--deck') ?? getFlagValue('--deck-id'),
|
|
735
|
+
sessionId: getFlagValue('--room'),
|
|
736
|
+
listRooms: hasFlag('--rooms'),
|
|
737
|
+
json: hasFlag('--json'),
|
|
738
|
+
staging: hasFlag('--staging'),
|
|
739
|
+
});
|
|
740
|
+
break;
|
|
741
|
+
}
|
|
723
742
|
case 'git':
|
|
724
743
|
await gitCommand();
|
|
725
744
|
break;
|
package/dist/init.js
CHANGED
|
@@ -64,7 +64,7 @@ const BARE_SCAFFOLDS = [
|
|
|
64
64
|
// Registry version of castle-web-sdk to inject when scaffolding from a
|
|
65
65
|
// globally-installed castle-web (not from inside the workspace). Bumped
|
|
66
66
|
// alongside cli/sdk version bumps.
|
|
67
|
-
const PUBLISHED_SDK_VERSION = '0.4.
|
|
67
|
+
const PUBLISHED_SDK_VERSION = '0.4.55';
|
|
68
68
|
// Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
|
|
69
69
|
// face can ship without a cli release, and a caret range means an existing
|
|
70
70
|
// deck's next install picks it up. Nothing here has to move when it does.
|
|
@@ -265,6 +265,28 @@ export function getCliVersion() {
|
|
|
265
265
|
const pkg = readJsonFile(path.join(getKitsDir(), '..', 'package.json'));
|
|
266
266
|
return typeof pkg?.version === 'string' ? pkg.version : '0.0.0';
|
|
267
267
|
}
|
|
268
|
+
// The castle-display the kit's own page declares, as a tag for the deck's page,
|
|
269
|
+
// or '' when it declares none. The host reads the tag from the deck's
|
|
270
|
+
// index.html, never the import's, so a kit that plays full-screen has to hand
|
|
271
|
+
// its declaration on or every deck made from it plays as a card.
|
|
272
|
+
function kitDisplayMeta(projectDir, alias) {
|
|
273
|
+
let html;
|
|
274
|
+
try {
|
|
275
|
+
html = fs.readFileSync(path.join(projectDir, IMPORTS_DIR, alias, 'index.html'), 'utf8');
|
|
276
|
+
}
|
|
277
|
+
catch {
|
|
278
|
+
return '';
|
|
279
|
+
}
|
|
280
|
+
for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
|
|
281
|
+
if (!/\bname\s*=\s*["']castle-display["']/i.test(tag))
|
|
282
|
+
continue;
|
|
283
|
+
const content = tag.match(/\bcontent\s*=\s*(["'])(.*?)\1/i)?.[2];
|
|
284
|
+
if (!content || /["<>&]/.test(content))
|
|
285
|
+
return '';
|
|
286
|
+
return `\n <meta name="castle-display" content="${content}" />`;
|
|
287
|
+
}
|
|
288
|
+
return '';
|
|
289
|
+
}
|
|
268
290
|
// The deck's entry point is the KIT's -- the deck has no engine code of its own
|
|
269
291
|
// -- so index.html points into the import. Everything the kit's main.jsx imports
|
|
270
292
|
// is relative to itself, so it needs no rewriting to run from there.
|
|
@@ -272,7 +294,7 @@ function writeDeckIndexHtml(projectDir, alias, title, mainFile) {
|
|
|
272
294
|
fs.writeFileSync(path.join(projectDir, 'index.html'), `<!doctype html>
|
|
273
295
|
<html>
|
|
274
296
|
<head>
|
|
275
|
-
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"
|
|
297
|
+
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />${kitDisplayMeta(projectDir, alias)}
|
|
276
298
|
<meta name="color-scheme" content="dark" />
|
|
277
299
|
<title>${title}</title>
|
|
278
300
|
<!-- Declare the dark scheme before the JS-imported CSS loads, so the frame
|
package/dist/multiplayerDoc.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const MULTIPLAYER_DOC = "# Multiplayer, in practice\n\nRead this before writing or changing a server entry or client netcode by hand.\nWritten fresh by the Castle CLI at every serve start; the full API reference is\nthe SDK's own, at `imports/castle.base/sdk/README.md`.\n\n## Reach for a kit first\n\n`castle.multiplayer-2d` and `castle.multiplayer-3d` (both on `castle.real-time`)\nalready do everything below: a server-authoritative world, one snapshot per\ntick, pose interpolation, roster handling, reconnects, ownership of loose\nobjects. `castle.turn-based` does the same for games played in turns, with\nseats, spectators and idle clearing. A deck on one of those kits normally\nwrites nothing against the raw session API, and the right move is usually to\nadd a rule to the deck's own game hooks rather than a message of your own.\n\nHand-roll only when the game genuinely does not fit them -- and then keep the\nshape below, because it is the shape the platform's limits ask for.\n\n## The outbound budget\n\nA session may send about `40 + 40 x connected players` frames per second, with\nroughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:\n\n| call | frames |\n|---|---|\n| `session.send(playerId, data)` | 1 |\n| `session.broadcast(data)` | 1, whatever the player count |\n| `session.broadcast(data, { except })` | one per recipient -- it is a loop of sends |\n\nFrames over the budget are **dropped silently**. The session keeps running and\na dropped frame is never retried, so the symptom is not an error: it is a\nclient whose world quietly stops matching everyone else's. Only sustained abuse\nat several times the budget ends a session.\n\nThe arithmetic that matters, at `tickRate: 20`:\n\n- 4 players, one `send` per player per tick: 80 frames/s of a 200 budget --\n before a single hit, join, chat or one-off frame.\n- 8 players, same: 160 of 360. A second per-player message per tick makes it\n 320, and at `tickRate: 30` that is 480 -- over, and frames start dropping.\n- Either, with one `broadcast` per tick: 20 frames/s. The budget stops being\n something you have to think about.\n\nPer-player sends also send the same bytes N times toward the byte budget. The\nlocal serve does not drop anything, but it warns when a 1-second window goes\nover -- `[multiplayer] server sent ...` in `.castle/logs.txt` and in the serve's\nown output (`.castle/serve.log` when it was detached).\n\n## The snapshot pattern\n\nAuthoritative state lives on the server. `onTick` builds ONE snapshot of every\nplayer and broadcasts it once.\n\nEvery client reads EVERY entry in that snapshot, **including its own** -- the\ndifference is only what it does with each:\n\n- **Other players' entries** drive what it draws for them (interpolated between\n snapshots), and are how it learns someone left or went silent.\n- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,\n kills, score and the match state from it every tick, exactly as if it were\n someone else's. The one field it does NOT overwrite each tick is its own pose:\n the local player moves on its own input so the game stays responsive, and the\n client only snaps to the server's position when the two have drifted far\n apart. Ignoring the rest of its own entry is how a player ends up alive on\n their own screen and dead on everyone else's.\n\n```js\nconst state = { matchNumber: 1, players: {}, parked: new Map() };\n\nexport default {\n onPlayerJoin(session, player) {\n state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };\n },\n onMessage(session, player, data) {\n if (data.t === 'move') applyMove(state.players[player.playerId], data);\n },\n onTick(session) {\n // One frame per tick, for any number of players.\n session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });\n },\n};\n```\n\n```js\nconnection.onMessage((msg) => {\n if (msg.t !== 'snap') return;\n match.setNumber(msg.n); // a new match number means: reset, the round moved on\n for (const [id, p] of Object.entries(msg.players)) {\n if (id === connection.playerId) {\n // My own entry: the server owns all of it except where I am right now.\n Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });\n if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {\n me.x = p.x; // drifted too far to argue; the server is right\n me.y = p.y;\n }\n continue;\n }\n remote.set(id, { ...p, seenAt: performance.now() });\n }\n});\n```\n\nDo not build a per-player payload (\"everyone except you\") on the server: the\nclient needs its own entry anyway, and one tailored message per player costs N\nframes where the shared snapshot costs 1.\n\n## One-off events must be self-healing\n\nA dropped or missed event frame is gone for good. So an event may carry an\neffect, never the only copy of a result:\n\n- `{ t: 'hit', target, dmg }` -- fine for a flash, a sound, a particle.\n- The hp it produced, whether the player is alive or wrecked, the kill count,\n the match number: all of that belongs in the periodic snapshot, and the\n client reconciles from the snapshot every tick.\n\nWrite the client so that receiving zero events and only snapshots still\nproduces a correct, playable screen. Then a dropped frame costs one missing\nspark instead of a player who is dead everywhere but on their own device.\n\n## Connection loss has to be visible\n\nTwo independent things can go quiet: the socket, and a player.\n\n```js\nconnection.onStateChange((state, meta) => {\n // 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'\n // meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'\n hud.setConnection(state, meta?.type);\n});\n```\n\n- Show `reconnecting` and `closed` in the deck's own UI. A player staring at a\n frozen game with no explanation assumes the game is broken.\n- Expire a remote player whose last snapshot is older than a few seconds\n (`performance.now() - p.seenAt > 3000`) and stop drawing them. This must run\n off the client's own clock, not off an event -- if the server or the socket\n goes silent, no message will ever arrive to tell you, and every remote player\n stays frozen mid-stride forever.\n- The SDK reconnects short drops by itself and `send` is safe to call while the\n socket is down (those messages are dropped), so the client's job is to show\n the state and recover, not to manage the socket.\n\n## Reconnects: park match state, never delete it\n\n`playerId` is stable across a platform reconnect, but the server still sees\n`onPlayerLeave` and then `onPlayerJoin`. A server that deletes the player's row\non leave silently drops a reconnecting player out of the match while their\nclient happily thinks it is still playing.\n\n```js\nonPlayerLeave(session, player) {\n const parked = state.players[player.playerId];\n delete state.players[player.playerId];\n if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId\n},\nonPlayerJoin(session, player) {\n const held = state.parked.get(player.playerId);\n state.parked.delete(player.playerId);\n state.players[player.playerId] =\n held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();\n session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once\n},\n```\n\nPark for about 60 seconds (the platform's own reconnect window), keyed by\n`playerId`, or by `userId` when the match should survive a genuinely new\nconnection from the same account. Sweep expired entries on a tick.\n\nOn the client, after a state change back to `connected`, ask for full state\nonce and rebuild from the answer rather than assuming the world is as you left\nit.\n\n## The server ignores and tells\n\nWhen the server refuses a message because the player is not in the state the\nclient assumed -- not in the match, already dead, not their turn -- do not just\n`return`. The client believes something false and nothing will correct it.\n\n```js\nonMessage(session, player, data) {\n const me = state.players[player.playerId];\n if (!me || !me.alive) {\n session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer\n return;\n }\n ...\n}\n```\n\nOne frame, and the client resyncs instead of arguing with itself. Rate-limit\nthat reply (once per player per second is plenty) so a looping client cannot\nspend the whole budget on corrections.\n\n## Client to server\n\nClient frames are capped at 16 KB and about 30 messages per second; **exceeding\nthe rate closes the socket**, which is much harsher than the server side's\nsilent drop.\n\n- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the\n client interpolates between samples (the real-time kit reports at 20). Never\n send once per animation frame -- 60/s closes the connection.\n- Send intent (\"I am holding left\", \"I fired\"), not results. The server decides\n what happened.\n- Coalesce: one message per send tick carrying the latest pose beats three\n messages describing how it got there.\n\n## Testing it\n\n- Open **four or more** tabs, not two. Every budget and roster bug scales with\n the player count, and two tabs is exactly the case that never reproduces one.\n- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see\n what a silent player looks like to everyone else.\n- Kill and restart the serve (or edit the server entry, which restarts it) to\n see the disconnected state the deck shows.\n- Watch the serve log for the `[multiplayer]` budget warning and for dropped\n oversize frames while you play.\n";
|
|
1
|
+
export declare const MULTIPLAYER_DOC = "# Multiplayer, in practice\n\nRead this before writing or changing a server entry or client netcode by hand.\nWritten fresh by the Castle CLI at every serve start; the full API reference is\nthe SDK's own, at `imports/castle.base/sdk/README.md`.\n\n## Reach for a kit first\n\n`castle.multiplayer-2d` and `castle.multiplayer-3d` (both on `castle.real-time`)\nalready do everything below: a server-authoritative world, one snapshot per\ntick, pose interpolation, roster handling, reconnects, ownership of loose\nobjects. `castle.turn-based` does the same for games played in turns, with\nseats, spectators and idle clearing. A deck on one of those kits normally\nwrites nothing against the raw session API, and the right move is usually to\nadd a rule to the deck's own game hooks rather than a message of your own.\n\nHand-roll only when the game genuinely does not fit them -- and then keep the\nshape below, because it is the shape the platform's limits ask for.\n\n## The outbound budget\n\nA session may send about `40 + 40 x connected players` frames per second, with\nroughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:\n\n| call | frames |\n|---|---|\n| `session.send(playerId, data)` | 1 |\n| `session.broadcast(data)` | 1, whatever the player count |\n| `session.broadcast(data, { except })` | one per recipient -- it is a loop of sends |\n\nFrames over the budget are **dropped silently**. The session keeps running and\na dropped frame is never retried, so the symptom is not an error: it is a\nclient whose world quietly stops matching everyone else's. Only sustained abuse\nat several times the budget ends a session.\n\nThe arithmetic that matters, at `tickRate: 20`:\n\n- 4 players, one `send` per player per tick: 80 frames/s of a 200 budget --\n before a single hit, join, chat or one-off frame.\n- 8 players, same: 160 of 360. A second per-player message per tick makes it\n 320, and at `tickRate: 30` that is 480 -- over, and frames start dropping.\n- Either, with one `broadcast` per tick: 20 frames/s. The budget stops being\n something you have to think about.\n\nPer-player sends also send the same bytes N times toward the byte budget. The\nlocal serve does not drop anything, but it warns when a 1-second window goes\nover -- `[multiplayer] server sent ...` in `.castle/logs.txt` and in the serve's\nown output (`.castle/serve.log` when it was detached).\n\n## The snapshot pattern\n\nAuthoritative state lives on the server. `onTick` builds ONE snapshot of every\nplayer and broadcasts it once.\n\nEvery client reads EVERY entry in that snapshot, **including its own** -- the\ndifference is only what it does with each:\n\n- **Other players' entries** drive what it draws for them (interpolated between\n snapshots), and are how it learns someone left or went silent.\n- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,\n kills, score and the match state from it every tick, exactly as if it were\n someone else's. The one field it does NOT overwrite each tick is its own pose:\n the local player moves on its own input so the game stays responsive, and the\n client only snaps to the server's position when the two have drifted far\n apart. Ignoring the rest of its own entry is how a player ends up alive on\n their own screen and dead on everyone else's.\n\n```js\nconst state = { matchNumber: 1, players: {}, parked: new Map() };\n\nexport default {\n onPlayerJoin(session, player) {\n state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };\n },\n onMessage(session, player, data) {\n if (data.t === 'move') applyMove(state.players[player.playerId], data);\n },\n onTick(session) {\n // One frame per tick, for any number of players.\n session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });\n },\n};\n```\n\n```js\nconnection.onMessage((msg) => {\n if (msg.t !== 'snap') return;\n match.setNumber(msg.n); // a new match number means: reset, the round moved on\n for (const [id, p] of Object.entries(msg.players)) {\n if (id === connection.playerId) {\n // My own entry: the server owns all of it except where I am right now.\n Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });\n if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {\n me.x = p.x; // drifted too far to argue; the server is right\n me.y = p.y;\n }\n continue;\n }\n remote.set(id, { ...p, seenAt: performance.now() });\n }\n});\n```\n\nDo not build a per-player payload (\"everyone except you\") on the server: the\nclient needs its own entry anyway, and one tailored message per player costs N\nframes where the shared snapshot costs 1.\n\n## One-off events must be self-healing\n\nA dropped or missed event frame is gone for good. So an event may carry an\neffect, never the only copy of a result:\n\n- `{ t: 'hit', target, dmg }` -- fine for a flash, a sound, a particle.\n- The hp it produced, whether the player is alive or wrecked, the kill count,\n the match number: all of that belongs in the periodic snapshot, and the\n client reconciles from the snapshot every tick.\n\nWrite the client so that receiving zero events and only snapshots still\nproduces a correct, playable screen. Then a dropped frame costs one missing\nspark instead of a player who is dead everywhere but on their own device.\n\n## Connection loss has to be visible\n\nTwo independent things can go quiet: the socket, and a player.\n\n```js\nconnection.onStateChange((state, meta) => {\n // 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'\n // meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'\n hud.setConnection(state, meta?.type);\n});\n```\n\n- Show `reconnecting` and `closed` in the deck's own UI. A player staring at a\n frozen game with no explanation assumes the game is broken.\n- On `closed` with `replaced`, call `Multiplayer.join` again: the creator\n published a new server. A `public` join from matchmaking lands on the new\n version; a `named` or `party` room, or a friend's public room the player\n followed, keeps the old one until Castle ends it, about ten minutes after the\n save. That ending, like a kick, arrives as `bye` with a `reason` to show\n the player; don't rejoin a `bye` automatically, or a kicked player comes\n straight back.\n- Expire a remote player whose last snapshot is older than a few seconds\n (`performance.now() - p.seenAt > 3000`) and stop drawing them. This must run\n off the client's own clock, not off an event -- if the server or the socket\n goes silent, no message will ever arrive to tell you, and every remote player\n stays frozen mid-stride forever.\n- The SDK reconnects short drops by itself and `send` is safe to call while the\n socket is down (those messages are dropped), so the client's job is to show\n the state and recover, not to manage the socket.\n\n## Reconnects: park match state, never delete it\n\n`playerId` is stable across a platform reconnect, but the server still sees\n`onPlayerLeave` and then `onPlayerJoin`. A server that deletes the player's row\non leave silently drops a reconnecting player out of the match while their\nclient happily thinks it is still playing.\n\n```js\nonPlayerLeave(session, player) {\n const parked = state.players[player.playerId];\n delete state.players[player.playerId];\n if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId\n},\nonPlayerJoin(session, player) {\n const held = state.parked.get(player.playerId);\n state.parked.delete(player.playerId);\n state.players[player.playerId] =\n held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();\n session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once\n},\n```\n\nPark for about 60 seconds (the platform's own reconnect window), keyed by\n`playerId`, or by `userId` when the match should survive a genuinely new\nconnection from the same account. Sweep expired entries on a tick.\n\nOn the client, after a state change back to `connected`, ask for full state\nonce and rebuild from the answer rather than assuming the world is as you left\nit.\n\n## The server ignores and tells\n\nWhen the server refuses a message because the player is not in the state the\nclient assumed -- not in the match, already dead, not their turn -- do not just\n`return`. The client believes something false and nothing will correct it.\n\n```js\nonMessage(session, player, data) {\n const me = state.players[player.playerId];\n if (!me || !me.alive) {\n session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer\n return;\n }\n ...\n}\n```\n\nOne frame, and the client resyncs instead of arguing with itself. Rate-limit\nthat reply (once per player per second is plenty) so a looping client cannot\nspend the whole budget on corrections.\n\n## Client to server\n\nClient frames are capped at 16 KB and about 30 messages per second; **exceeding\nthe rate closes the socket**, which is much harsher than the server side's\nsilent drop.\n\n- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the\n client interpolates between samples (the real-time kit reports at 20). Never\n send once per animation frame -- 60/s closes the connection.\n- Send intent (\"I am holding left\", \"I fired\"), not results. The server decides\n what happened.\n- Coalesce: one message per send tick carrying the latest pose beats three\n messages describing how it got there.\n\n## Testing it\n\n- Open **four or more** tabs, not two. Every budget and roster bug scales with\n the player count, and two tabs is exactly the case that never reproduces one.\n- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see\n what a silent player looks like to everyone else.\n- Kill and restart the serve (or edit the server entry, which restarts it) to\n see the disconnected state the deck shows.\n- Watch the serve log for the `[multiplayer]` budget warning and for dropped\n oversize frames while you play.\n- A published room that crashed or stopped: `castle-web logs` prints its end\n reason, exit code and last server log lines (creator only; `--rooms` lists rooms).\n";
|
package/dist/multiplayerDoc.js
CHANGED
|
@@ -141,6 +141,13 @@ connection.onStateChange((state, meta) => {
|
|
|
141
141
|
|
|
142
142
|
- Show \`reconnecting\` and \`closed\` in the deck's own UI. A player staring at a
|
|
143
143
|
frozen game with no explanation assumes the game is broken.
|
|
144
|
+
- On \`closed\` with \`replaced\`, call \`Multiplayer.join\` again: the creator
|
|
145
|
+
published a new server. A \`public\` join from matchmaking lands on the new
|
|
146
|
+
version; a \`named\` or \`party\` room, or a friend's public room the player
|
|
147
|
+
followed, keeps the old one until Castle ends it, about ten minutes after the
|
|
148
|
+
save. That ending, like a kick, arrives as \`bye\` with a \`reason\` to show
|
|
149
|
+
the player; don't rejoin a \`bye\` automatically, or a kicked player comes
|
|
150
|
+
straight back.
|
|
144
151
|
- Expire a remote player whose last snapshot is older than a few seconds
|
|
145
152
|
(\`performance.now() - p.seenAt > 3000\`) and stop drawing them. This must run
|
|
146
153
|
off the client's own clock, not off an event -- if the server or the socket
|
|
@@ -225,4 +232,6 @@ silent drop.
|
|
|
225
232
|
see the disconnected state the deck shows.
|
|
226
233
|
- Watch the serve log for the \`[multiplayer]\` budget warning and for dropped
|
|
227
234
|
oversize frames while you play.
|
|
235
|
+
- A published room that crashed or stopped: \`castle-web logs\` prints its end
|
|
236
|
+
reason, exit code and last server log lines (creator only; \`--rooms\` lists rooms).
|
|
228
237
|
`;
|
package/dist/platformDoc.js
CHANGED
|
@@ -54,7 +54,7 @@ const MODE_BULLET = "- Unprompted, an editor is an offer, never a build: when th
|
|
|
54
54
|
export function everyDeckBullets(deckDir) {
|
|
55
55
|
return [
|
|
56
56
|
"- **Castle's Parameters panel is where a creator tunes the deck.** It is one of Castle's own panels, beside Play and Files: it shows the `PARAMS` values of every file that has one as live fields the creator drags while the deck runs, which is how they change the way it plays without putting a cursor in code.",
|
|
57
|
-
`- **Supported media formats are exactly**: ${mediaList(deckDir)}. Nothing else — a published deck inlines every asset as a \`data:\` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (\`.mov\` is the classic case) can be dead once published. Convert, don't improvise.`,
|
|
57
|
+
`- **Supported media formats are exactly**: ${mediaList(deckDir)}. Nothing else — a published deck inlines every asset as a \`data:\` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (\`.mov\` is the classic case) can be dead once published. Convert, don't improvise. Audio and video (\`.mp4\`, \`.webm\`) of 64 KB or more are the assets not inlined: a published deck serves them from Castle's CDN by URL, so play them with \`new Audio(url)\`, \`video.src = url\` or \`fetch\` + \`decodeAudioData\`, never by reading the string (an \`?inline\` import keeps the \`data:\` URI).`,
|
|
58
58
|
"- To add an npm package, put it in `package.json` `dependencies` and run `castle-web install .` (the install `init` ran; it uses whichever package manager made the lockfile).",
|
|
59
59
|
"- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.",
|
|
60
60
|
'- If the browser console shows `[vite] failed to connect to websocket` (or a "Direct websocket connection fallback" line), ignore it. Vite HMR is deliberately off on this serve, so the line is expected and harmless: it is never why a scene is blank, a game is not running, or multiplayer is not connecting. Do not investigate or "fix" it.',
|
|
@@ -80,6 +80,7 @@ export const HOST_LIMIT_BULLETS = [
|
|
|
80
80
|
"- **Where a deck runs decides what it can do.** The Play panel runs it from this serve; players run the published deck in the Castle app (iOS, Android) or castle.xyz's web player. When something works in one and fails in another, check it against the limits below before another fix: if one covers it, name that limit instead of retrying, and ask where they run it if you do not know. If none does, it is an ordinary deck bug (a runtime `fetch` of a loose file, a control that only answers a mouse) and gets fixed.",
|
|
81
81
|
"- **Microphone and camera are blocked in the Play panel and on castle.xyz**: neither frame is granted them, so `getUserMedia` rejects with `NotAllowedError` whatever the person allows, and no deck change helps. The Android app's published deck can use them; the iOS app is untested.",
|
|
82
82
|
"- **A published deck loads almost nothing from the network.** Its CSP allows images, audio and video only from the deck itself, `data:` or `blob:`, `fetch` only to esm.sh, cdnjs.cloudflare.com and Castle's multiplayer hosts, and no iframes. The Play panel enforces the same CSP, so a URL it blocks fails in Play too, and `.castle/logs.txt` names each URL and directive the page blocked with a `[csp] blocked` line. Bundle the file, or let the player pick one with `<input type=\"file\">`.",
|
|
83
|
+
"- **On castle.xyz a published deck's frame has no origin of its own, and on a device its console reaches no devtools.** Browser storage throws a `SecurityError` there, and so do history calls that pass a URL. Don't build on browser storage; the SDK's replacements, how `setup()` keeps history calls working, and the on-screen console for debugging on a device are in the SDK reference, `imports/castle.base/sdk/README.md`.",
|
|
83
84
|
"- **An older Castle app build rejects SDK commands newer than the build**, with a `CastleError` whose `code` is `UNKNOWN_COMMAND`; only an app update fixes that, so the deck should catch it and keep working. Which commands need which app build, and every other limit of a Castle service, is in the SDK reference, `imports/castle.base/sdk/README.md`.",
|
|
84
85
|
];
|
|
85
86
|
// The frustration survey found the router inventing Upload buttons and offering
|
|
@@ -311,7 +312,8 @@ const COMMON_SECTIONS = `## Imports are read-only
|
|
|
311
312
|
- **Limits worth designing around.** Client→server messages are capped at 16 KB and about 30 per second; server→client messages are capped at 64 KB. These limits apply to both JSON and binary frames and are measured on the frame, so a binary frame's one-byte protocol tag leaves you one byte under the cap for payload. A session may also SEND only about \`40 + 40 × connected players\` frames per second (about two seconds of burst, and about 1 MiB/s of bytes): \`session.send\` costs one frame per call, \`session.broadcast(data)\` costs ONE frame however many players are in the session, and \`session.broadcast(data, { except })\` is a loop of sends, so it costs one frame per recipient. Frames over the budget are dropped silently and never retried — the session keeps running, so the symptom is a client whose world quietly stops matching everyone else's; only sustained abuse at several times the budget ends a session. So send one \`broadcast\` per tick carrying every player's state, rather than a tailored \`send\` per player: every client reads every entry of that snapshot INCLUDING its own — it takes hp, kills and match state from its own entry and only keeps its own position locally predicted.
|
|
312
313
|
- **Binary messages are opt-in per payload.** Pass any typed array, \`DataView\`, or \`ArrayBuffer\` to client \`send\`, server \`send\`, or server \`broadcast\` to send its raw bytes. \`onMessage\` always receives those bytes as a \`Uint8Array\`, while every other payload continues to use JSON. Reconstruct another view type such as \`Float32Array\` on receipt; multi-byte values use the sender platform's byte order.
|
|
313
314
|
- **Test multiplayer locally with no setup.** \`castle-web serve\` runs your server file alongside the deck. Open the shell URL it prints in two tabs, then open the Play panel in each; those play surfaces share a session. If you open the content origin from \`.castle/serve.json\` directly, use \`/index.html?edit=0\`. Its bare origin loads the edit surface, where \`Multiplayer.join\` is not answered. Editing the server entry, anything beside it, or a deck-owned hook under \`server/\` or \`code/server/\` restarts it and clients reconnect, so you exercise your reconnect path constantly. Server \`console.log\` goes to the serve's logs, not the browser console.
|
|
314
|
-
- **
|
|
315
|
+
- **A published deck's server rooms have logs too.** \`castle-web logs\` (in the deck folder, signed in as its creator) shows the newest room's state, end reason, exit code, an out-of-memory kill, and its last server log lines; \`--rooms\` lists recent rooms and \`--room <id>\` picks one. Hosts keep the lines for about 30 minutes after a room ends.
|
|
316
|
+
- **Publishing moves players onto the new version; you don't build versioned rooms or a rejoin prompt.** \`save-deck\` bundles and publishes the server entry, and every new session runs it. A session already running keeps the code it started with: its server gets \`onReplaced\`, and each client's connection closes with \`replaced\` metadata. A deck that joins again when the connection closes (the multiplayer kits do) gets the new version at once for a \`public\` join from matchmaking, since new players are not placed in a running public session on the old code; a \`named\` or \`party\` join, or a public one that follows a friend into their room, goes back to that room, which keeps the old code until it ends. About ten minutes after the save Castle ends any ordinary session still on the old code (hub places, persistent worlds and destinations keep their own release handling), closing its connections with \`bye\` and a reason that says the game was updated; its \`onShutdown\` still runs, so a save there lands, and the next join gets the new version.
|
|
315
317
|
`;
|
|
316
318
|
export function platformGuide(deckDir) {
|
|
317
319
|
return `${COMMON_SECTIONS.trimEnd()}
|
package/dist/playPagePolicy.d.ts
CHANGED
package/dist/playPagePolicy.js
CHANGED
|
@@ -7,14 +7,23 @@ const CDN_HOSTS = 'https://esm.sh https://cdnjs.cloudflare.com';
|
|
|
7
7
|
const PLAY_HOSTS = 'wss://*.play.castle.xyz';
|
|
8
8
|
// Content packs a hub door mounts (kits/hub-game/docs/content-pack.md); connect-src only.
|
|
9
9
|
const CONTENT_PACK_HOSTS = 'https://hosted.castle.games';
|
|
10
|
+
// Uploaded textures, models and songs a deck loads from Castle's own CDN instead of
|
|
11
|
+
// inlining them as base64. Castle-controlled hosts that answer
|
|
12
|
+
// `Access-Control-Allow-Origin: *`, so a fetch from the opaque srcdoc origin can read
|
|
13
|
+
// them. img-src, media-src and connect-src only: an asset is data, never script.
|
|
14
|
+
export const CASTLE_ASSET_HOSTS = 'https://castle.imgix.net https://image.castle.xyz https://audio.castle.xyz';
|
|
15
|
+
// A published deck's audio and video, which save-deck stores there instead of
|
|
16
|
+
// inlining it (bundle.ts ExternalMedia). Path-scoped and media-src only: a fetch
|
|
17
|
+
// for decodeAudioData is already covered by CONTENT_PACK_HOSTS in connect-src.
|
|
18
|
+
const MEDIA_ASSET_SRC = 'https://hosted.castle.games/cauldron-assets/';
|
|
10
19
|
const DECK_CSP = [
|
|
11
20
|
"default-src 'self' data: blob:",
|
|
12
21
|
`script-src 'self' 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' data: blob: ${CDN_HOSTS}`,
|
|
13
22
|
"style-src 'self' 'unsafe-inline' data: blob: https://fonts.googleapis.com",
|
|
14
23
|
"font-src 'self' data: blob: https://fonts.gstatic.com",
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
`connect-src 'self' data: blob: ${CDN_HOSTS} ${PLAY_HOSTS} ${CONTENT_PACK_HOSTS}`,
|
|
24
|
+
`img-src 'self' data: blob: ${CASTLE_ASSET_HOSTS}`,
|
|
25
|
+
`media-src 'self' data: blob: ${CASTLE_ASSET_HOSTS} ${MEDIA_ASSET_SRC}`,
|
|
26
|
+
`connect-src 'self' data: blob: ${CDN_HOSTS} ${PLAY_HOSTS} ${CONTENT_PACK_HOSTS} ${CASTLE_ASSET_HOSTS}`,
|
|
18
27
|
"frame-src 'none'",
|
|
19
28
|
"child-src 'self' blob:",
|
|
20
29
|
"worker-src 'self' blob:",
|
|
@@ -1,11 +1,18 @@
|
|
|
1
1
|
export interface ResetLeaderboardsOptions {
|
|
2
2
|
deckId?: string;
|
|
3
3
|
yes: boolean;
|
|
4
|
+
undo?: boolean;
|
|
4
5
|
}
|
|
6
|
+
export declare const NOT_WEB_DECK = "DECK_DATA_RESET_NOT_WEB_DECK";
|
|
7
|
+
export declare function needsClassicClear(err: unknown): boolean;
|
|
5
8
|
export interface ResetLeaderboardsDeps {
|
|
6
9
|
signedIn: boolean;
|
|
7
10
|
deckTitle(deckId: string): Promise<string | null>;
|
|
8
|
-
|
|
11
|
+
resetDeckLeaderboards(deckId: string): Promise<{
|
|
12
|
+
undoUntil: string | null;
|
|
13
|
+
}>;
|
|
14
|
+
undoDeckLeaderboardsReset(deckId: string): Promise<void>;
|
|
15
|
+
clearClassicLeaderboards(deckId: string): Promise<void>;
|
|
9
16
|
interactive: boolean;
|
|
10
17
|
confirm(question: string): Promise<boolean>;
|
|
11
18
|
log(line: string): void;
|
|
@@ -1,11 +1,25 @@
|
|
|
1
1
|
// `castle-web reset-leaderboards` -- clears every leaderboard on a deck, for its
|
|
2
|
-
// creator.
|
|
3
|
-
//
|
|
4
|
-
// undo
|
|
5
|
-
//
|
|
2
|
+
// creator. For a Cauldron deck it sends Ghost's resetCauldronDeckLeaderboards, which
|
|
3
|
+
// starts the Store boards and the classic leaderboards over from empty and can be
|
|
4
|
+
// undone for a day with `--undo`; the players' saved data is untouched. A classic
|
|
5
|
+
// deck (Ghost refuses it with DECK_DATA_RESET_NOT_WEB_DECK) falls back to
|
|
6
|
+
// clearDeckLeaderboards, the classic editor's "Reset all leaderboards", which has no
|
|
7
|
+
// undo.
|
|
6
8
|
//
|
|
7
|
-
// This command is for a signed-in creator at a terminal.
|
|
8
|
-
//
|
|
9
|
+
// This command is for a signed-in creator at a terminal. Neither mutation is in the
|
|
10
|
+
// cloud sandbox's GraphQL allowlist, so the deck agent cannot send them.
|
|
11
|
+
// Ghost's refusal of a classic deck, from the Cauldron reset.
|
|
12
|
+
export const NOT_WEB_DECK = 'DECK_DATA_RESET_NOT_WEB_DECK';
|
|
13
|
+
// Whether the Cauldron reset cannot run here and the classic clear should: a classic
|
|
14
|
+
// deck, or a Ghost from before resetCauldronDeckLeaderboards existed (so this CLI can
|
|
15
|
+
// publish ahead of the server). The classic clear has no undo and leaves Store boards.
|
|
16
|
+
export function needsClassicClear(err) {
|
|
17
|
+
const failure = err;
|
|
18
|
+
if (failure?.extensions?.code === NOT_WEB_DECK)
|
|
19
|
+
return true;
|
|
20
|
+
// Ghost's GraphQL Yoga reports an unknown field with this message and no code.
|
|
21
|
+
return String(failure?.message).includes('Cannot query field "resetCauldronDeckLeaderboards"');
|
|
22
|
+
}
|
|
9
23
|
export async function resetLeaderboards(options, deps) {
|
|
10
24
|
const deckId = options.deckId;
|
|
11
25
|
if (!deckId) {
|
|
@@ -18,18 +32,39 @@ export async function resetLeaderboards(options, deps) {
|
|
|
18
32
|
// still decides whether the deck exists and is this user's.
|
|
19
33
|
const title = await deps.deckTitle(deckId);
|
|
20
34
|
const named = title ? `"${title}" (${deckId})` : `deck ${deckId}`;
|
|
35
|
+
if (options.undo) {
|
|
36
|
+
await deps.undoDeckLeaderboardsReset(deckId);
|
|
37
|
+
deps.log(`Put back the leaderboards of ${named} as they were before the last reset.`);
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
21
40
|
if (!options.yes) {
|
|
22
41
|
if (!deps.interactive) {
|
|
23
42
|
throw new Error(`Not resetting the leaderboards of ${named}: there is no terminal to confirm on. Pass --yes to reset anyway.`);
|
|
24
43
|
}
|
|
25
|
-
const question = `Reset every leaderboard on ${named}? All of its scores are cleared
|
|
44
|
+
const question = `Reset every leaderboard on ${named}? All of its scores are cleared; players' saved data is kept. [y/N] `;
|
|
26
45
|
if (!(await deps.confirm(question))) {
|
|
27
46
|
deps.log('Nothing was reset.');
|
|
28
47
|
return;
|
|
29
48
|
}
|
|
30
49
|
}
|
|
31
|
-
|
|
50
|
+
let undoUntil;
|
|
51
|
+
try {
|
|
52
|
+
({ undoUntil } = await deps.resetDeckLeaderboards(deckId));
|
|
53
|
+
}
|
|
54
|
+
catch (err) {
|
|
55
|
+
if (!needsClassicClear(err)) {
|
|
56
|
+
throw err;
|
|
57
|
+
}
|
|
58
|
+
await deps.clearClassicLeaderboards(deckId);
|
|
59
|
+
deps.log(`Reset the classic leaderboards on ${named} for good: there is no undo here.`);
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
32
62
|
deps.log(`Reset every leaderboard on ${named}. They start empty from the next score.`);
|
|
63
|
+
if (undoUntil) {
|
|
64
|
+
// Names the deck: --undo skips the prompt, and run from another deck's directory
|
|
65
|
+
// the bare command would undo that deck instead.
|
|
66
|
+
deps.log(`Changed your mind? \`castle-web reset-leaderboards --deck-id ${deckId} --undo\` puts the scores back until ${undoUntil}.`);
|
|
67
|
+
}
|
|
33
68
|
}
|
|
34
69
|
// The answer to the confirmation question: only a y or yes resets.
|
|
35
70
|
export function isYes(answer) {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
export interface CauldronRoom {
|
|
2
|
+
sessionId: string;
|
|
3
|
+
deckId: string;
|
|
4
|
+
env: string;
|
|
5
|
+
startedAt: string;
|
|
6
|
+
endedAt: string | null;
|
|
7
|
+
numPlayers: number;
|
|
8
|
+
}
|
|
9
|
+
export interface CauldronRoomLogLine {
|
|
10
|
+
at: string | null;
|
|
11
|
+
stream: string;
|
|
12
|
+
text: string;
|
|
13
|
+
}
|
|
14
|
+
export interface CauldronRoomLogs extends CauldronRoom {
|
|
15
|
+
state: string;
|
|
16
|
+
logsAvailable: boolean;
|
|
17
|
+
logsUnavailableReason: string | null;
|
|
18
|
+
endReason: string | null;
|
|
19
|
+
exitCode: number | null;
|
|
20
|
+
oomKilled: boolean | null;
|
|
21
|
+
droppedLines: number;
|
|
22
|
+
lines: CauldronRoomLogLine[];
|
|
23
|
+
}
|
|
24
|
+
export interface RoomLogsOptions {
|
|
25
|
+
dir: string;
|
|
26
|
+
deckId?: string;
|
|
27
|
+
sessionId?: string;
|
|
28
|
+
listRooms: boolean;
|
|
29
|
+
json: boolean;
|
|
30
|
+
staging: boolean;
|
|
31
|
+
}
|
|
32
|
+
export declare class RoomLogsError extends Error {
|
|
33
|
+
}
|
|
34
|
+
export declare function recentRooms(deckId: string, env: string, limit?: number): Promise<CauldronRoom[]>;
|
|
35
|
+
export declare function roomLogs(deckId: string, sessionId: string, env: string): Promise<CauldronRoomLogs>;
|
|
36
|
+
export declare function visible(text: string): string;
|
|
37
|
+
export declare function formatRooms(deckId: string, env: string, rooms: CauldronRoom[]): string;
|
|
38
|
+
export declare function formatRoomLogs(logs: CauldronRoomLogs): string;
|
|
39
|
+
export declare function roomLogsCommand(options: RoomLogsOptions): Promise<void>;
|
package/dist/roomLogs.js
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
// `castle-web logs` -- a published deck's multiplayer rooms, read by the deck's creator.
|
|
2
|
+
// A room is one multiplayer server session of the deck (one runtime container). Ghost's
|
|
3
|
+
// cauldronRoomLogs answers with the room's end reason, exit code and out-of-memory flag,
|
|
4
|
+
// plus its last log lines when the host that ran it still holds them (the host keeps
|
|
5
|
+
// them in memory, for 30 minutes after a room ends); cauldronRecentRooms lists rooms
|
|
6
|
+
// newest first.
|
|
7
|
+
//
|
|
8
|
+
// Only the deck's creator may read them -- not collaborators, not admins -- because a
|
|
9
|
+
// room's output can carry players' messages. Ghost's sandbox scope does not carry
|
|
10
|
+
// either query, so this works from a creator's own terminal, not a cloud sandbox.
|
|
11
|
+
import { graphql } from './api.js';
|
|
12
|
+
import { readCastleJson } from './castleJson.js';
|
|
13
|
+
import * as config from './config.js';
|
|
14
|
+
const RECENT_ROOMS_LIMIT = 20;
|
|
15
|
+
const ROOM_FIELDS = 'sessionId deckId env startedAt endedAt numPlayers';
|
|
16
|
+
const UNAVAILABLE_REASONS = {
|
|
17
|
+
host_missing: 'the server host that ran this room is gone (hosts are replaced over time), so its logs went with it',
|
|
18
|
+
host_stale: 'the server host that ran this room has stopped reporting in, so its logs cannot be read',
|
|
19
|
+
no_capability: 'the server host that ran this room predates room logs',
|
|
20
|
+
host_timeout: 'the server host did not answer in time; try again',
|
|
21
|
+
host_error: 'the server host could not hand over its logs; try again',
|
|
22
|
+
not_found: 'the server host has no logs for this room -- it may have ended more than 30 minutes ago, or the host predates room logs',
|
|
23
|
+
};
|
|
24
|
+
// Plain words for Ghost's error codes. Anything else is shown with its code.
|
|
25
|
+
const ERROR_CODES = {
|
|
26
|
+
LOGIN_REQUIRED: 'Not logged in. Run `castle-web login`.',
|
|
27
|
+
DECK_INVALID_PERMISSIONS: "Only the deck's creator can read its room logs.",
|
|
28
|
+
DECK_NOT_FOUND: 'No such deck.',
|
|
29
|
+
CAULDRON_ROOM_NOT_FOUND: 'This deck has no room with that id.',
|
|
30
|
+
CAULDRON_ENV_FORBIDDEN: 'Staging rooms are not open to this account.',
|
|
31
|
+
};
|
|
32
|
+
export class RoomLogsError extends Error {
|
|
33
|
+
}
|
|
34
|
+
async function query(document, variables, field) {
|
|
35
|
+
const response = await graphql(document, variables);
|
|
36
|
+
const error = response.errors?.[0];
|
|
37
|
+
if (error)
|
|
38
|
+
throw new RoomLogsError(describeError(error));
|
|
39
|
+
const value = response.data?.[field];
|
|
40
|
+
if (value === undefined || value === null) {
|
|
41
|
+
throw new RoomLogsError(`The server returned no ${field}.`);
|
|
42
|
+
}
|
|
43
|
+
return value;
|
|
44
|
+
}
|
|
45
|
+
function describeError(error) {
|
|
46
|
+
const message = error.message ?? 'GraphQL error';
|
|
47
|
+
// The schema is older than the CLI: the field fails validation before any resolver runs.
|
|
48
|
+
if (/Cannot query field "cauldron(RecentRooms|RoomLogs)"/.test(message)) {
|
|
49
|
+
return "Room logs aren't available on this server yet.";
|
|
50
|
+
}
|
|
51
|
+
const code = typeof error.extensions?.code === 'string' ? error.extensions.code : undefined;
|
|
52
|
+
if (code && ERROR_CODES[code])
|
|
53
|
+
return ERROR_CODES[code];
|
|
54
|
+
return visible(code ? `${message} [${code}]` : message);
|
|
55
|
+
}
|
|
56
|
+
export function recentRooms(deckId, env, limit = RECENT_ROOMS_LIMIT) {
|
|
57
|
+
return query(`query($deckId: ID!, $env: String, $limit: Int) {
|
|
58
|
+
cauldronRecentRooms(deckId: $deckId, env: $env, limit: $limit) {
|
|
59
|
+
${ROOM_FIELDS}
|
|
60
|
+
}
|
|
61
|
+
}`, { deckId, env, limit }, 'cauldronRecentRooms');
|
|
62
|
+
}
|
|
63
|
+
export function roomLogs(deckId, sessionId, env) {
|
|
64
|
+
return query(`query($deckId: ID!, $sessionId: ID!, $env: String) {
|
|
65
|
+
cauldronRoomLogs(deckId: $deckId, sessionId: $sessionId, env: $env) {
|
|
66
|
+
${ROOM_FIELDS}
|
|
67
|
+
state logsAvailable logsUnavailableReason endReason exitCode oomKilled droppedLines
|
|
68
|
+
lines { at stream text }
|
|
69
|
+
}
|
|
70
|
+
}`, { deckId, sessionId, env }, 'cauldronRoomLogs');
|
|
71
|
+
}
|
|
72
|
+
// Everything a room prints, and every string its host reports, is the author's or a
|
|
73
|
+
// player's text: a raw ESC, CR or BEL in it would drive the reader's terminal (move the
|
|
74
|
+
// cursor, rewrite earlier lines, set the clipboard through OSC 52). Human output shows
|
|
75
|
+
// C0 and C1 control characters and DEL as visible escapes instead; tab stays. --json is
|
|
76
|
+
// already escaped by JSON.stringify.
|
|
77
|
+
export function visible(text) {
|
|
78
|
+
// eslint-disable-next-line no-control-regex
|
|
79
|
+
return text.replace(/[\u0000-\u0008\u000a-\u001f\u007f-\u009f]/g, (c) => {
|
|
80
|
+
if (c === '\n')
|
|
81
|
+
return '\\n';
|
|
82
|
+
if (c === '\r')
|
|
83
|
+
return '\\r';
|
|
84
|
+
return `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`;
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
// 2026-10-21T18:38:54.798Z -> 2026-10-21 18:38:54Z
|
|
88
|
+
function shortTime(iso) {
|
|
89
|
+
if (!iso)
|
|
90
|
+
return '';
|
|
91
|
+
return iso.replace('T', ' ').replace(/\.\d+Z$/, 'Z');
|
|
92
|
+
}
|
|
93
|
+
export function formatRooms(deckId, env, rooms) {
|
|
94
|
+
if (!rooms.length)
|
|
95
|
+
return `No rooms yet for deck ${deckId} (${env}).`;
|
|
96
|
+
const rows = rooms.map((room) => [
|
|
97
|
+
room.sessionId,
|
|
98
|
+
shortTime(room.startedAt),
|
|
99
|
+
room.endedAt ? shortTime(room.endedAt) : 'running',
|
|
100
|
+
String(room.numPlayers),
|
|
101
|
+
].map((cell) => visible(String(cell))));
|
|
102
|
+
const header = ['ROOM', 'STARTED', 'ENDED', 'PLAYERS'];
|
|
103
|
+
const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
|
|
104
|
+
const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join(' ').trimEnd();
|
|
105
|
+
return [`Recent rooms of deck ${deckId} (${env}), newest first:`, line(header), ...rows.map(line)].join('\n');
|
|
106
|
+
}
|
|
107
|
+
export function formatRoomLogs(logs) {
|
|
108
|
+
const out = [
|
|
109
|
+
`Room ${logs.sessionId} of deck ${logs.deckId} (${logs.env})`,
|
|
110
|
+
` state: ${logs.state}`,
|
|
111
|
+
` started: ${shortTime(logs.startedAt)}`,
|
|
112
|
+
` ended: ${logs.endedAt ? shortTime(logs.endedAt) : 'running'}`,
|
|
113
|
+
` players: ${logs.numPlayers}`,
|
|
114
|
+
];
|
|
115
|
+
if (logs.endReason)
|
|
116
|
+
out.push(` end reason: ${logs.endReason}`);
|
|
117
|
+
if (logs.exitCode !== null && logs.exitCode !== undefined)
|
|
118
|
+
out.push(` exit code: ${logs.exitCode}`);
|
|
119
|
+
if (logs.oomKilled)
|
|
120
|
+
out.push(' killed: out of memory');
|
|
121
|
+
if (!logs.logsAvailable) {
|
|
122
|
+
const reason = logs.logsUnavailableReason ?? '';
|
|
123
|
+
out.push('', `No log lines: ${UNAVAILABLE_REASONS[reason] ?? `unavailable (${reason || 'no reason given'})`}.`);
|
|
124
|
+
return out.map(visible).join('\n');
|
|
125
|
+
}
|
|
126
|
+
if (logs.droppedLines > 0) {
|
|
127
|
+
out.push(` dropped lines: ${logs.droppedLines} (older lines the host no longer holds)`);
|
|
128
|
+
}
|
|
129
|
+
out.push('');
|
|
130
|
+
if (!logs.lines.length) {
|
|
131
|
+
out.push('(the room printed nothing)');
|
|
132
|
+
}
|
|
133
|
+
else {
|
|
134
|
+
out.push(`Last ${logs.lines.length} line${logs.lines.length === 1 ? '' : 's'}, oldest first:`);
|
|
135
|
+
for (const line of logs.lines) {
|
|
136
|
+
const at = line.at ? `${shortTime(line.at)} ` : '';
|
|
137
|
+
out.push(`${at}${line.stream === 'stderr' ? '[stderr] ' : ''}${line.text}`);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
return out.map(visible).join('\n');
|
|
141
|
+
}
|
|
142
|
+
export async function roomLogsCommand(options) {
|
|
143
|
+
const deckId = options.deckId ?? readCastleJson(options.dir)?.deckId;
|
|
144
|
+
if (!deckId) {
|
|
145
|
+
throw new RoomLogsError('No deckId. Either pass --deck <id> or run from a deck folder whose castle.json has one (it gets one on the first save-deck).');
|
|
146
|
+
}
|
|
147
|
+
if (!config.getToken())
|
|
148
|
+
throw new RoomLogsError(ERROR_CODES.LOGIN_REQUIRED);
|
|
149
|
+
const env = options.staging ? 'staging' : 'prod';
|
|
150
|
+
if (options.listRooms) {
|
|
151
|
+
const rooms = await recentRooms(deckId, env);
|
|
152
|
+
console.log(options.json ? JSON.stringify(rooms, null, 2) : formatRooms(deckId, env, rooms));
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
let sessionId = options.sessionId;
|
|
156
|
+
if (!sessionId) {
|
|
157
|
+
const [latest] = await recentRooms(deckId, env, 1);
|
|
158
|
+
if (!latest) {
|
|
159
|
+
console.log(options.json ? 'null' : formatRooms(deckId, env, []));
|
|
160
|
+
return;
|
|
161
|
+
}
|
|
162
|
+
sessionId = latest.sessionId;
|
|
163
|
+
}
|
|
164
|
+
const logs = await roomLogs(deckId, sessionId, env);
|
|
165
|
+
console.log(options.json ? JSON.stringify(logs, null, 2) : formatRoomLogs(logs));
|
|
166
|
+
}
|
package/dist/save-deck.d.ts
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
import * as api from './api.js';
|
|
2
|
-
import { type BundleChunk } from './bundle.js';
|
|
2
|
+
import { type BundleChunk, type ExternalMediaAsset } from './bundle.js';
|
|
3
3
|
import { type ExperimentConfig } from './castleJson.js';
|
|
4
4
|
import { type SavePrecondition } from './webSourceSync.js';
|
|
5
5
|
export { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
|
|
6
6
|
export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
|
|
7
7
|
export declare const SAVE_STAGE_TELEMETRY_PREFIX = "CASTLE_SAVE_TELEMETRY ";
|
|
8
8
|
export declare const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = "CASTLE_SAVE_COVER_SELECTION ";
|
|
9
|
-
export
|
|
9
|
+
export declare const SAVE_ASSET_INLINE_TELEMETRY_PREFIX = "CASTLE_SAVE_ASSET_INLINE ";
|
|
10
|
+
export type SaveStage = 'bundle' | 'cover' | 'chunk_upload' | 'asset_upload' | 'scene_upload_config' | 'scene_upload' | 'content_publish' | 'server_publish' | 'source_archive' | 'source_upload_config' | 'source_upload' | 'source_commit';
|
|
10
11
|
export declare function runTar(args: string[], opts?: {
|
|
11
12
|
capture?: boolean;
|
|
12
13
|
}): Promise<string>;
|
|
@@ -50,6 +51,35 @@ export declare function uploadBundleChunks(deckId: string, chunks: BundleChunk[]
|
|
|
50
51
|
skipped: number;
|
|
51
52
|
bytesUploaded: number;
|
|
52
53
|
}>;
|
|
54
|
+
export declare const MAX_MEDIA_ASSET_BYTES: number;
|
|
55
|
+
export interface MediaUploadResult {
|
|
56
|
+
uploaded: number;
|
|
57
|
+
skipped: number;
|
|
58
|
+
bytesUploaded: number;
|
|
59
|
+
/** The URLs this upload stored (not the ones already there), to check are served. */
|
|
60
|
+
storedUrls: string[];
|
|
61
|
+
/** Assets Ghost refused, with its code: the page must be built with these inline. */
|
|
62
|
+
refused: {
|
|
63
|
+
asset: ExternalMediaAsset;
|
|
64
|
+
code: string;
|
|
65
|
+
}[];
|
|
66
|
+
}
|
|
67
|
+
export declare const ASSET_SERVED_RETRY_MS: number[];
|
|
68
|
+
/** True once every URL is served through the CDN, trying again after each wait. Exported for the tests. */
|
|
69
|
+
export declare function assetsServed(urls: string[], retryMs?: number[]): Promise<boolean>;
|
|
70
|
+
/**
|
|
71
|
+
* Puts every media asset the page names at its URL, as uploadBundleChunks does
|
|
72
|
+
* chunks: one already there (HEAD 200) is skipped, any other uploaded and
|
|
73
|
+
* stored, and the first that cannot be stored fails the save before the page
|
|
74
|
+
* is published -- except one Ghost refuses (ASSET_REFUSED), which is reported
|
|
75
|
+
* in `refused` for the caller to inline. Null when this Ghost has no asset
|
|
76
|
+
* store: the caller builds the page with its media inline instead.
|
|
77
|
+
* Exported for the tests.
|
|
78
|
+
*/
|
|
79
|
+
export declare function uploadMediaAssets(deckId: string, assets: ExternalMediaAsset[], { busyRetryMs }?: {
|
|
80
|
+
busyRetryMs?: number[];
|
|
81
|
+
}): Promise<MediaUploadResult | null>;
|
|
82
|
+
export type AssetInlineReason = 'no_store' | 'cdn_not_serving' | 'refused';
|
|
53
83
|
export type SaveVisibility = 'unlisted' | 'private';
|
|
54
84
|
export interface SaveDeckOptions {
|
|
55
85
|
title?: string;
|