castle-web-cli 0.4.229 → 0.4.231
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-prompts.d.ts +2 -0
- package/dist/agent-prompts.js +16 -8
- package/dist/agent.d.ts +2 -0
- package/dist/agent.js +21 -21
- package/dist/api.d.ts +28 -2
- package/dist/api.js +74 -16
- package/dist/castle-host/host.d.ts +91 -0
- package/dist/castle-host/host.js +860 -3
- package/dist/castleJson.d.ts +44 -0
- package/dist/castleJson.js +131 -0
- package/dist/check.js +27 -1
- package/dist/contentPack.d.ts +49 -0
- package/dist/contentPack.js +273 -0
- package/dist/devExperiments.d.ts +21 -0
- package/dist/devExperiments.js +139 -0
- package/dist/devHub.d.ts +55 -0
- package/dist/devHub.js +187 -0
- package/dist/devSaveStorage.d.ts +36 -0
- package/dist/devSaveStorage.js +469 -0
- package/dist/devSessionChild.js +25 -13
- package/dist/devSessionServer.d.ts +14 -1
- package/dist/devSessionServer.js +237 -46
- package/dist/devSessionStorage.d.ts +9 -0
- package/dist/devSessionStorage.js +66 -1
- package/dist/experimentAssignment.d.ts +15 -0
- package/dist/experimentAssignment.js +41 -0
- package/dist/importCheckHook.d.ts +40 -0
- package/dist/importCheckHook.js +171 -0
- package/dist/importRegression.d.ts +15 -0
- package/dist/importRegression.js +100 -0
- package/dist/importTrust.d.ts +2 -0
- package/dist/importTrust.js +27 -0
- package/dist/importUpdateHook.d.ts +18 -0
- package/dist/importUpdateHook.js +31 -8
- package/dist/importUpdateHookRunner.js +19 -7
- package/dist/imports.d.ts +16 -0
- package/dist/imports.js +141 -31
- package/dist/index.js +3 -1
- package/dist/init.d.ts +3 -0
- package/dist/init.js +126 -9
- package/dist/install.js +4 -1
- package/dist/localPaths.js +4 -0
- package/dist/login.js +2 -2
- package/dist/platformDoc.js +3 -8
- package/dist/playPagePolicy.js +3 -1
- package/dist/remix.js +5 -0
- package/dist/routerTaskReport.d.ts +28 -0
- package/dist/routerTaskReport.js +56 -0
- package/dist/save-deck.d.ts +18 -0
- package/dist/save-deck.js +142 -6
- package/dist/serve.d.ts +8 -0
- package/dist/serve.js +99 -14
- package/dist/serverBundle.d.ts +1 -1
- package/dist/serverBundle.js +5 -1
- package/dist/webSourceSync.d.ts +2 -0
- package/dist/webSourceSync.js +2 -0
- package/kits/base/CLAUDE.md +2 -3
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +406 -53
- package/kits/base/sdk/agent.js +4 -4
- package/kits/base/sdk/avatar.d.ts +12 -0
- package/kits/base/sdk/avatar.js +23 -0
- package/kits/base/sdk/castle.d.ts +9 -0
- package/kits/base/sdk/castle.js +5 -0
- package/kits/base/sdk/commands.d.ts +223 -0
- package/kits/base/sdk/commands.js +16 -0
- package/kits/base/sdk/context.d.ts +6 -0
- package/kits/base/sdk/experiments.d.ts +15 -0
- package/kits/base/sdk/experiments.js +83 -0
- package/kits/base/sdk/hub.d.ts +85 -0
- package/kits/base/sdk/hub.js +107 -0
- package/kits/base/sdk/multiplayer.d.ts +45 -1
- package/kits/base/sdk/multiplayer.js +158 -8
- package/kits/base/sdk/save.d.ts +197 -0
- package/kits/base/sdk/save.js +525 -0
- package/kits/base/sdk/saveCoordinator.d.ts +39 -0
- package/kits/base/sdk/saveCoordinator.js +252 -0
- package/kits/base/sdk/server/hub.d.ts +169 -0
- package/kits/base/sdk/server/hub.js +125 -0
- package/kits/base/sdk/server/platformHandle.d.ts +42 -1
- package/kits/base/sdk/server/storage.d.ts +58 -4
- package/kits/base/sdk/server/storage.js +25 -5
- package/kits/base/sdk/server/wrapper.d.ts +36 -2
- package/kits/base/sdk/server/wrapper.js +92 -11
- package/kits/base/sdk/store.d.ts +3 -2
- package/kits/base/sdk/store.js +5 -0
- package/kits/base/sdk/transport.d.ts +2 -1
- package/kits/base/sdk/transport.js +13 -1
- package/kits/hub-game/.prettierrc +5 -0
- package/kits/hub-game/CLAUDE.md +149 -0
- package/kits/hub-game/blueprints/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
- package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
- package/kits/hub-game/castle.json +96 -0
- package/kits/hub-game/code/client/attention.js +133 -0
- package/kits/hub-game/code/client/avatar.js +288 -0
- package/kits/hub-game/code/client/cabinets.js +90 -0
- package/kits/hub-game/code/client/chat.js +135 -0
- package/kits/hub-game/code/client/chrome.js +1035 -0
- package/kits/hub-game/code/client/doorFrame.js +15 -0
- package/kits/hub-game/code/client/firstJoin.js +14 -0
- package/kits/hub-game/code/client/grab.js +376 -0
- package/kits/hub-game/code/client/hookLayer.js +236 -0
- package/kits/hub-game/code/client/idle.js +326 -0
- package/kits/hub-game/code/client/keys.js +48 -0
- package/kits/hub-game/code/client/pack.js +232 -0
- package/kits/hub-game/code/client/packFormat.js +397 -0
- package/kits/hub-game/code/client/say.js +127 -0
- package/kits/hub-game/code/client/sha256.js +80 -0
- package/kits/hub-game/code/client/sound.js +147 -0
- package/kits/hub-game/code/client/state.js +143 -0
- package/kits/hub-game/code/client/talk.js +233 -0
- package/kits/hub-game/code/client/tiers.js +480 -0
- package/kits/hub-game/code/client/together.js +440 -0
- package/kits/hub-game/code/client/wear.js +149 -0
- package/kits/hub-game/code/server/actors.js +627 -0
- package/kits/hub-game/code/server/blocks.js +103 -0
- package/kits/hub-game/code/server/cabinets.js +309 -0
- package/kits/hub-game/code/server/game.js +137 -0
- package/kits/hub-game/code/server/grab.js +248 -0
- package/kits/hub-game/code/server/history.js +96 -0
- package/kits/hub-game/code/server/hub.js +1998 -0
- package/kits/hub-game/code/server/idle.js +412 -0
- package/kits/hub-game/code/server/index.js +64 -0
- package/kits/hub-game/code/server/labels.js +59 -0
- package/kits/hub-game/code/server/manifest.js +554 -0
- package/kits/hub-game/code/server/npcs.js +733 -0
- package/kits/hub-game/code/server/party.js +439 -0
- package/kits/hub-game/code/server/place.js +43 -0
- package/kits/hub-game/code/server/say.js +83 -0
- package/kits/hub-game/code/server/wear.js +142 -0
- package/kits/hub-game/code/systems/hub.js +2347 -0
- package/kits/hub-game/docs/content-pack.md +151 -0
- package/kits/hub-game/docs/contract.md +1209 -0
- package/kits/hub-game/docs/style.md +137 -0
- package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
- package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
- package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
- package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
- package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
- package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
- package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
- package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
- package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
- package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
- package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
- package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
- package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
- package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
- package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
- package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
- package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
- package/kits/hub-game/eslint.config.js +20 -0
- package/kits/hub-game/fonts.generated.js +9 -0
- package/kits/hub-game/index.html +22 -0
- package/kits/hub-game/main.jsx +6 -0
- package/kits/hub-game/models/avatar-0.pxmodel +21 -0
- package/kits/hub-game/models/avatar-1.pxmodel +24 -0
- package/kits/hub-game/models/avatar-2.pxmodel +27 -0
- package/kits/hub-game/models/avatar-3.pxmodel +22 -0
- package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
- package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
- package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
- package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
- package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
- package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
- package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
- package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
- package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
- package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
- package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
- package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
- package/kits/hub-game/package-lock.json +365 -0
- package/kits/hub-game/package.json +32 -0
- package/kits/hub-game/scenes/main.scene +318 -0
- package/kits/hub-game/scripts/check.mjs +339 -0
- package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
- package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
- package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
- package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
- package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
- package/kits/hub-game/scripts/pack.mjs +192 -0
- package/kits/hub-game/scripts/test-actors.mjs +666 -0
- package/kits/hub-game/scripts/test-attention.mjs +103 -0
- package/kits/hub-game/scripts/test-avatar.mjs +472 -0
- package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
- package/kits/hub-game/scripts/test-blocks.mjs +351 -0
- package/kits/hub-game/scripts/test-chat.mjs +98 -0
- package/kits/hub-game/scripts/test-classic.mjs +590 -0
- package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
- package/kits/hub-game/scripts/test-door.mjs +56 -0
- package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
- package/kits/hub-game/scripts/test-grab.mjs +331 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
- package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
- package/kits/hub-game/scripts/test-idle.mjs +518 -0
- package/kits/hub-game/scripts/test-interest.mjs +413 -0
- package/kits/hub-game/scripts/test-keys.mjs +50 -0
- package/kits/hub-game/scripts/test-manifest.mjs +270 -0
- package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
- package/kits/hub-game/scripts/test-npcs.mjs +724 -0
- package/kits/hub-game/scripts/test-pack.mjs +424 -0
- package/kits/hub-game/scripts/test-party.mjs +369 -0
- package/kits/hub-game/scripts/test-say.mjs +149 -0
- package/kits/hub-game/scripts/test-tiers.mjs +666 -0
- package/kits/hub-game/scripts/test-together.mjs +215 -0
- package/kits/hub-game/theme.style +3 -0
- package/kits/multiplayer-3d/castle.json +5 -5
- package/kits/multiplayer-3d/code/client/avatars.js +101 -1
- package/kits/multiplayer-3d/code/server/players.js +4 -1
- package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
- package/kits/multiplayer-3d/code/server/world.js +20 -7
- package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
- package/kits/physics-2d/CLAUDE.md +2 -0
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/art.js +13 -0
- package/kits/physics-2d/engine/assets.js +4 -2
- package/kits/physics-2d/engine/scene.js +117 -5
- package/kits/physics-2d/package.json +1 -1
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
- package/kits/physics-3d/CLAUDE.md +285 -1
- package/kits/physics-3d/behaviors/Player.jsx +74 -1
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
- package/kits/physics-3d/engine3d/actornode.js +253 -0
- package/kits/physics-3d/engine3d/artobjects.js +2 -2
- package/kits/physics-3d/engine3d/materials.js +29 -1
- package/kits/physics-3d/engine3d/nearshadows.js +600 -0
- package/kits/physics-3d/engine3d/unchanged.js +153 -0
- package/kits/physics-3d/engine3d/world3d.js +527 -5
- package/kits/physics-3d/package.json +1 -1
- package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
- package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
- package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
- package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
- package/kits/physics-3d/systems/physics3d.js +187 -5
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/connection.js +77 -7
- package/kits/real-time/code/client/gameHooks.js +63 -3
- package/kits/real-time/code/client/messages.js +7 -0
- package/kits/real-time/code/server/gameHooks.js +24 -0
- package/kits/real-time/code/server/session.js +390 -22
- package/package.json +2 -2
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Json } from "../types";
|
|
2
2
|
import type { CharacterHistory, CharacterOperation } from "../commands";
|
|
3
3
|
import type { PlatformHandle } from "./platformHandle";
|
|
4
|
+
import { type SaveApi, type SaveBucketApi } from "../save";
|
|
4
5
|
export interface ServerStorageListOptions {
|
|
5
6
|
prefix?: string;
|
|
6
7
|
limit?: number;
|
|
@@ -15,7 +16,7 @@ export interface ServerStorageListPage<T extends Json = Json> {
|
|
|
15
16
|
/** Null means there is nothing left. A short page alone does not mean that. */
|
|
16
17
|
cursor: string | null;
|
|
17
18
|
}
|
|
18
|
-
export interface ServerStorageScope {
|
|
19
|
+
export interface ServerStorageScope extends SaveBucketApi {
|
|
19
20
|
get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
|
|
20
21
|
set(values: Record<string, Json>): Promise<void>;
|
|
21
22
|
remove(keys: string[]): Promise<void>;
|
|
@@ -95,6 +96,59 @@ export interface DeliverCharacterKnowledgeInput {
|
|
|
95
96
|
claimIds: string[];
|
|
96
97
|
source: CharacterKnowledgeSource;
|
|
97
98
|
}
|
|
99
|
+
/**
|
|
100
|
+
* A character acting on its own after a command woke it (autonomous character
|
|
101
|
+
* actions, bundles with `characterActions`). `declined` covers choosing
|
|
102
|
+
* nothing, too little confidence for its temperament, and an action no longer
|
|
103
|
+
* eligible when it committed; `failed` is a decision-model error.
|
|
104
|
+
*/
|
|
105
|
+
export type CharacterActionNotice = {
|
|
106
|
+
characterId: string;
|
|
107
|
+
/** `id` is the event occurrence, routine, or promise id. */
|
|
108
|
+
trigger: {
|
|
109
|
+
type: "witnessed" | "routine" | "promise_due";
|
|
110
|
+
id: string;
|
|
111
|
+
};
|
|
112
|
+
outcome: "acted" | "declined" | "failed";
|
|
113
|
+
/** When acted. */
|
|
114
|
+
actionId?: string;
|
|
115
|
+
/** When acted with a parameterized action's variant. */
|
|
116
|
+
variantId?: string;
|
|
117
|
+
/** The action's world event, when it has one. */
|
|
118
|
+
eventOccurrenceId?: string;
|
|
119
|
+
/** The decision model's probability for its choice. */
|
|
120
|
+
probability?: number;
|
|
121
|
+
};
|
|
122
|
+
export type CharacterGameStateResult = {
|
|
123
|
+
revision: number;
|
|
124
|
+
state: {
|
|
125
|
+
[key: string]: string | number | boolean;
|
|
126
|
+
};
|
|
127
|
+
promiseOutcomes: Array<{
|
|
128
|
+
id: string;
|
|
129
|
+
status: "fulfilled" | "broken";
|
|
130
|
+
due: number;
|
|
131
|
+
resolvedAtGameTime: number;
|
|
132
|
+
}>;
|
|
133
|
+
/** At most 8, omitted when no character acted, declined, or failed. */
|
|
134
|
+
characterActions?: CharacterActionNotice[];
|
|
135
|
+
};
|
|
136
|
+
export type CharacterGameStateOperation = Omit<CharacterOperation, "result"> & {
|
|
137
|
+
result: CharacterGameStateResult | null;
|
|
138
|
+
};
|
|
139
|
+
export type CharacterKnowledgeDeliveryResult = {
|
|
140
|
+
deliveryId: string;
|
|
141
|
+
recipientCharacterId: string;
|
|
142
|
+
eventOccurrenceId: string;
|
|
143
|
+
claimIds: string[];
|
|
144
|
+
source: CharacterKnowledgeSource;
|
|
145
|
+
deliveredAt: string;
|
|
146
|
+
/** At most 8, omitted when no character acted, declined, or failed. */
|
|
147
|
+
characterActions?: CharacterActionNotice[];
|
|
148
|
+
};
|
|
149
|
+
export type CharacterKnowledgeDeliveryOperation = Omit<CharacterOperation, "result"> & {
|
|
150
|
+
result: CharacterKnowledgeDeliveryResult | null;
|
|
151
|
+
};
|
|
98
152
|
export interface CompleteCharacterBeatInput {
|
|
99
153
|
operationId: string;
|
|
100
154
|
characterId: string;
|
|
@@ -189,10 +243,10 @@ export interface ServerPlaythroughCharacters {
|
|
|
189
243
|
/** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
|
|
190
244
|
send(input: SendCharacterInput): Promise<CharacterOperation>;
|
|
191
245
|
recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
|
|
192
|
-
setGameState(input: SetCharacterGameStateInput): Promise<
|
|
246
|
+
setGameState(input: SetCharacterGameStateInput): Promise<CharacterGameStateOperation>;
|
|
193
247
|
shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
|
|
194
248
|
inspect(): Promise<Json>;
|
|
195
|
-
deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<
|
|
249
|
+
deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterKnowledgeDeliveryOperation>;
|
|
196
250
|
completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
|
|
197
251
|
evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
|
|
198
252
|
evaluateBeats(input: EvaluateCharacterBeatsInput): Promise<CharacterBeatEvaluationOperation>;
|
|
@@ -204,7 +258,7 @@ export interface ServerCharacterHistoryOptions {
|
|
|
204
258
|
limit?: number;
|
|
205
259
|
cursor?: string | null;
|
|
206
260
|
}
|
|
207
|
-
export interface ServerStorage {
|
|
261
|
+
export interface ServerStorage extends SaveApi {
|
|
208
262
|
/** Shared by everyone playing the deck, and owned by this server. */
|
|
209
263
|
readonly deck: ServerStorageScope;
|
|
210
264
|
/** One player's public data. Readable by anyone; writable by them or by this server. */
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { chunked } from "../chunk";
|
|
2
2
|
import { decodeStorageValue, encodeStorageValue, storageError, } from "../storageJson";
|
|
3
|
+
import { createSaveApi, createSaveBucket, preflightSaveRequest, SaveError, } from "../save";
|
|
3
4
|
// Deck storage for an author's session server.
|
|
4
5
|
//
|
|
5
6
|
// The same store the deck's clients use, reached over the platform channel instead of
|
|
@@ -56,8 +57,26 @@ export function createServerStorage(platformHandle) {
|
|
|
56
57
|
const result = await platformHandle.storage(op, JSON.stringify(args));
|
|
57
58
|
return JSON.parse(result);
|
|
58
59
|
};
|
|
60
|
+
// The host forwards these args to the platform's storage route unchanged,
|
|
61
|
+
// which takes a save's request as `input` and a lookup as `operationId`.
|
|
62
|
+
const saveApi = createSaveApi(async (verb, input) => {
|
|
63
|
+
if (typeof platformHandle.storage !== "function" ||
|
|
64
|
+
platformHandle.storageEnabled === false) {
|
|
65
|
+
throw new SaveError({
|
|
66
|
+
code: "CAULDRON_STORAGE_UNAVAILABLE",
|
|
67
|
+
message: "Storage is not available to this session.",
|
|
68
|
+
operationId: input.operationId,
|
|
69
|
+
retryable: false,
|
|
70
|
+
committed: false,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
const args = verb === "operation" ? input : { input };
|
|
74
|
+
preflightSaveRequest(verb, args, MAX_REQUEST_BYTES);
|
|
75
|
+
return call(verb, args);
|
|
76
|
+
}, true);
|
|
59
77
|
return {
|
|
60
|
-
|
|
78
|
+
...saveApi,
|
|
79
|
+
deck: createScope(call, "DECK", null, saveApi),
|
|
61
80
|
user(userId) {
|
|
62
81
|
// A bad id poisons the scope rather than throwing here, so the failure arrives
|
|
63
82
|
// the same way every other failure does -- as a rejection the author can await.
|
|
@@ -65,12 +84,12 @@ export function createServerStorage(platformHandle) {
|
|
|
65
84
|
// resolved by the platform to the deck's creator, quietly writing the wrong
|
|
66
85
|
// player's bucket, so nothing is sent either.
|
|
67
86
|
if (typeof userId !== "string" || userId.length === 0) {
|
|
68
|
-
return createScope(rejectMissingSubject, "USER", null);
|
|
87
|
+
return createScope(rejectMissingSubject, "USER", null, saveApi);
|
|
69
88
|
}
|
|
70
89
|
if (utf8Length(userId) > MAX_SUBJECT_BYTES) {
|
|
71
|
-
return createScope(rejectOversizeSubject, "USER",
|
|
90
|
+
return createScope(rejectOversizeSubject, "USER", userId, saveApi);
|
|
72
91
|
}
|
|
73
|
-
return createScope(call, "USER", userId);
|
|
92
|
+
return createScope(call, "USER", userId, saveApi);
|
|
74
93
|
},
|
|
75
94
|
board(name) {
|
|
76
95
|
return createBoard(call, name);
|
|
@@ -224,8 +243,9 @@ function createPlaythrough(call, subject, generation) {
|
|
|
224
243
|
},
|
|
225
244
|
});
|
|
226
245
|
}
|
|
227
|
-
function createScope(call, scope, subject) {
|
|
246
|
+
function createScope(call, scope, subject, saveApi) {
|
|
228
247
|
return {
|
|
248
|
+
...createSaveBucket(saveApi, scope === "DECK" ? "deck" : "user", subject ?? undefined),
|
|
229
249
|
async get(keys) {
|
|
230
250
|
// A bare array, not a wrapper: the platform hands back exactly what the
|
|
231
251
|
// storage verb returns, and `get` returns its entries directly.
|
|
@@ -2,8 +2,14 @@ import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./p
|
|
|
2
2
|
import type { Json } from "../types";
|
|
3
3
|
import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
|
|
4
4
|
import { type ServerStorage } from "./storage";
|
|
5
|
+
import { type MultiplayerHubArrival, type MultiplayerServerHub } from "./hub";
|
|
5
6
|
export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
|
|
6
|
-
export
|
|
7
|
+
export { createSaveCoordinator } from "../saveCoordinator";
|
|
8
|
+
export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "../saveCoordinator";
|
|
9
|
+
export { SaveError } from "../save";
|
|
10
|
+
export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "../save";
|
|
11
|
+
export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
|
|
12
|
+
export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
|
|
7
13
|
export interface MultiplayerServerPlayer extends PlayerIdentity {
|
|
8
14
|
playerId: string;
|
|
9
15
|
readonly participantId: string;
|
|
@@ -16,6 +22,12 @@ export interface MultiplayerServerSession {
|
|
|
16
22
|
readonly sessionId: string;
|
|
17
23
|
readonly deckId: string;
|
|
18
24
|
readonly mode: MultiplayerSessionMode;
|
|
25
|
+
/**
|
|
26
|
+
* The place the host started this session for (a hub door's destination, or
|
|
27
|
+
* the hub place ghost pinned the session to), or null when the host stamped
|
|
28
|
+
* none. Never set from a client.
|
|
29
|
+
*/
|
|
30
|
+
readonly place: string | null;
|
|
19
31
|
/**
|
|
20
32
|
* Deck storage that outlives the session. Nothing else here does: a session ends
|
|
21
33
|
* when its last player leaves and its memory goes with it.
|
|
@@ -23,6 +35,27 @@ export interface MultiplayerServerSession {
|
|
|
23
35
|
readonly storage: ServerStorage;
|
|
24
36
|
/** A durable checkpoint for an opted-in persistent destination. */
|
|
25
37
|
readonly world: MultiplayerServerWorld | null;
|
|
38
|
+
/**
|
|
39
|
+
* The shared characters this session can address: `session.world.characters`
|
|
40
|
+
* in a shared-character world (the same object), or a hub place's characters
|
|
41
|
+
* on one of its layers, where `session.world` stays null. Null everywhere else.
|
|
42
|
+
*/
|
|
43
|
+
readonly characters: MultiplayerServerWorldCharacters | null;
|
|
44
|
+
/**
|
|
45
|
+
* The hub place this session runs (castle.json `hub`, as ghost pinned it):
|
|
46
|
+
* results, pads and arrivals. Null for a deck without a hub block and on hosts
|
|
47
|
+
* without hub support.
|
|
48
|
+
*/
|
|
49
|
+
readonly hub: MultiplayerServerHub | null;
|
|
50
|
+
/**
|
|
51
|
+
* The variant a connected player has in the A/B experiment `name`, or null
|
|
52
|
+
* when they are in no such experiment (or have left). Castle's server
|
|
53
|
+
* resolved it and the host delivered it with the join, so it is the same arm
|
|
54
|
+
* the player's page reads and nothing a client sent.
|
|
55
|
+
*/
|
|
56
|
+
experiment(player: MultiplayerServerPlayer | string, name: string): string | null;
|
|
57
|
+
/** Every experiment a connected player is in, `{ name: variant }`. */
|
|
58
|
+
experiments(player: MultiplayerServerPlayer | string): Record<string, string>;
|
|
26
59
|
/** Sends bytes as a binary message and all other payloads as JSON. */
|
|
27
60
|
send(playerId: string, data: unknown): void;
|
|
28
61
|
/** Broadcasts bytes as a binary message and all other payloads as JSON. */
|
|
@@ -243,7 +276,8 @@ export interface MultiplayerWorldCharacterTurn {
|
|
|
243
276
|
type CallbackResult = unknown;
|
|
244
277
|
export interface MultiplayerServerCallbacks {
|
|
245
278
|
onStart?: (session: MultiplayerServerSession) => CallbackResult;
|
|
246
|
-
|
|
279
|
+
/** `arrival` is set when ghost placed the player through a hub door. */
|
|
280
|
+
onPlayerJoin?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, arrival: MultiplayerHubArrival | null) => CallbackResult;
|
|
247
281
|
onPlayerLeave?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer) => CallbackResult;
|
|
248
282
|
/** Receives binary messages as Uint8Array values and JSON messages otherwise. */
|
|
249
283
|
onMessage?: (session: MultiplayerServerSession, player: MultiplayerServerPlayer, data: unknown) => CallbackResult;
|
|
@@ -1,6 +1,9 @@
|
|
|
1
1
|
import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
|
|
2
2
|
import { encodeStorageValue, storageError } from "../storageJson";
|
|
3
3
|
import { createServerStorage } from "./storage";
|
|
4
|
+
import { createServerHub, hubArrival, recordHiddenUserIds, } from "./hub";
|
|
5
|
+
export { createSaveCoordinator } from "../saveCoordinator";
|
|
6
|
+
export { SaveError } from "../save";
|
|
4
7
|
// The publish bundler binds the author's default callbacks export once and
|
|
5
8
|
// exports the returned one-argument function as `__castleBootSession`.
|
|
6
9
|
export function createCastleSessionBoot(callbacks) {
|
|
@@ -10,19 +13,23 @@ export function createCastleSessionBoot(callbacks) {
|
|
|
10
13
|
}
|
|
11
14
|
async function bootSession(platformHandle, callbacks) {
|
|
12
15
|
const players = new Map();
|
|
13
|
-
const
|
|
16
|
+
const arrivals = new Map();
|
|
17
|
+
// playerId -> users a block hides from them; never on the player object.
|
|
18
|
+
const hidden = new Map();
|
|
19
|
+
// playerId -> their A/B arms while connected; never on the player object.
|
|
20
|
+
const variants = new Map();
|
|
21
|
+
const session = createAuthorSession(platformHandle, players, arrivals, hidden, variants);
|
|
14
22
|
let tickTimer = null;
|
|
15
|
-
platformHandle.on("join", async (connId, identity) => {
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
// the runtime-agnostic (connId, trusted identity) pair.
|
|
19
|
-
const player = joinedPlayer(connId, identity);
|
|
20
|
-
players.set(player.playerId, player);
|
|
21
|
-
await callbacks.onPlayerJoin?.(session, player);
|
|
23
|
+
platformHandle.on("join", async (connId, identity, handleArrival, handleVariants) => {
|
|
24
|
+
const { player, arrival } = admitPlayer({ players, arrivals, hidden, variants }, connId, identity, handleArrival, handleVariants);
|
|
25
|
+
await callbacks.onPlayerJoin?.(session, player, arrival);
|
|
22
26
|
});
|
|
23
27
|
platformHandle.on("leave", async (connId) => {
|
|
24
28
|
const player = players.get(connId);
|
|
25
29
|
players.delete(connId);
|
|
30
|
+
arrivals.delete(connId);
|
|
31
|
+
hidden.delete(connId);
|
|
32
|
+
variants.delete(connId);
|
|
26
33
|
if (player) {
|
|
27
34
|
await callbacks.onPlayerLeave?.(session, player);
|
|
28
35
|
}
|
|
@@ -203,7 +210,22 @@ async function bootSession(platformHandle, callbacks) {
|
|
|
203
210
|
}, 1_000 / platformHandle.config.tickRate);
|
|
204
211
|
}
|
|
205
212
|
}
|
|
206
|
-
function createAuthorSession(platformHandle, players) {
|
|
213
|
+
function createAuthorSession(platformHandle, players, arrivals, hidden, variants) {
|
|
214
|
+
// Lenient about what it is handed: an unknown player is in no experiment.
|
|
215
|
+
const variantsOf = (player) => variants.get(typeof player === "string"
|
|
216
|
+
? player
|
|
217
|
+
: (player?.playerId ?? ""));
|
|
218
|
+
// The pinned place counts only where the host services the hub ops.
|
|
219
|
+
const hub = createServerHub(platformHandle, arrivals, (a, b) => {
|
|
220
|
+
if (hidden.size === 0 || a === b)
|
|
221
|
+
return false;
|
|
222
|
+
const userA = players.get(a)?.userId;
|
|
223
|
+
const userB = players.get(b)?.userId;
|
|
224
|
+
if (!userA || !userB)
|
|
225
|
+
return false;
|
|
226
|
+
return Boolean(hidden.get(a)?.has(userB) || hidden.get(b)?.has(userA));
|
|
227
|
+
});
|
|
228
|
+
const world = createServerWorld(platformHandle);
|
|
207
229
|
return {
|
|
208
230
|
get players() {
|
|
209
231
|
return Array.from(players.values());
|
|
@@ -211,8 +233,20 @@ function createAuthorSession(platformHandle, players) {
|
|
|
211
233
|
sessionId: platformHandle.config.sessionId,
|
|
212
234
|
deckId: platformHandle.config.deckId,
|
|
213
235
|
mode: platformHandle.config.mode,
|
|
236
|
+
place: typeof platformHandle.config.place === "string"
|
|
237
|
+
? platformHandle.config.place
|
|
238
|
+
: hub?.place ?? null,
|
|
214
239
|
storage: createServerStorage(platformHandle),
|
|
215
|
-
world
|
|
240
|
+
world,
|
|
241
|
+
characters: world?.characters ?? createPlaceCharacters(platformHandle),
|
|
242
|
+
hub,
|
|
243
|
+
experiment(player, name) {
|
|
244
|
+
const known = variantsOf(player);
|
|
245
|
+
return known && Object.hasOwn(known, name) ? known[name] : null;
|
|
246
|
+
},
|
|
247
|
+
experiments(player) {
|
|
248
|
+
return { ...variantsOf(player) };
|
|
249
|
+
},
|
|
216
250
|
send(playerId, data) {
|
|
217
251
|
if (isBinaryPayload(data)) {
|
|
218
252
|
requireSendBinary(platformHandle);
|
|
@@ -274,6 +308,15 @@ const WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS = 7 * 24 * 60 * 60 * 1_000;
|
|
|
274
308
|
const SAFE_WORLD_NOTIFICATION_KEY = /^[A-Za-z0-9_-]+$/;
|
|
275
309
|
const CANONICAL_WORLD_NOTIFICATION_TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/;
|
|
276
310
|
const URL_IN_WORLD_NOTIFICATION_TEXT = /(?:https?:\/\/|www\.|\b[a-z0-9-]+\.(?:app|com|dev|gg|io|net|org|xyz)\b)/i;
|
|
311
|
+
// A hub place's layer has no world of its own, but the host may still broker
|
|
312
|
+
// the place's shared characters into it (`placeCharacters` in the runtime
|
|
313
|
+
// init). The character API is the world one; only the binding differs, and the
|
|
314
|
+
// host stamps that.
|
|
315
|
+
function createPlaceCharacters(platformHandle) {
|
|
316
|
+
if (platformHandle.config.placeCharacters !== true)
|
|
317
|
+
return null;
|
|
318
|
+
return createServerWorldCharacters(platformHandle);
|
|
319
|
+
}
|
|
277
320
|
function createServerWorld(platformHandle) {
|
|
278
321
|
if (!platformHandle.config.world)
|
|
279
322
|
return null;
|
|
@@ -1257,13 +1300,51 @@ function requireBroadcastBinary(platformHandle) {
|
|
|
1257
1300
|
function unsupportedBinaryRuntime() {
|
|
1258
1301
|
throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
|
|
1259
1302
|
}
|
|
1303
|
+
// The compatibility branch accepts the current Node shim's legacy
|
|
1304
|
+
// single-argument SessionPlayer event while the public handle contract uses the
|
|
1305
|
+
// runtime-agnostic (connId, trusted identity) pair. Either form may carry the hub
|
|
1306
|
+
// arrival after the player and the player's A/B arms after that, and a hub
|
|
1307
|
+
// player's block list on the player itself.
|
|
1308
|
+
function admitPlayer(state, connId, identity, handleArrival, handleVariants) {
|
|
1309
|
+
const player = joinedPlayer(connId, identity);
|
|
1310
|
+
const arrival = hubArrival(typeof connId === "string" ? handleArrival : identity);
|
|
1311
|
+
const known = experimentVariants(typeof connId === "string" ? handleVariants : handleArrival);
|
|
1312
|
+
state.players.set(player.playerId, player);
|
|
1313
|
+
if (known) {
|
|
1314
|
+
state.variants.set(player.playerId, known);
|
|
1315
|
+
}
|
|
1316
|
+
else {
|
|
1317
|
+
state.variants.delete(player.playerId);
|
|
1318
|
+
}
|
|
1319
|
+
recordHiddenUserIds(state.hidden, player.playerId, typeof connId === "string" ? identity : connId);
|
|
1320
|
+
if (arrival) {
|
|
1321
|
+
state.arrivals.set(player.playerId, arrival);
|
|
1322
|
+
}
|
|
1323
|
+
else {
|
|
1324
|
+
state.arrivals.delete(player.playerId);
|
|
1325
|
+
}
|
|
1326
|
+
return { player, arrival };
|
|
1327
|
+
}
|
|
1328
|
+
// Absent on a host that predates experiments, and for a player who is in none.
|
|
1329
|
+
function experimentVariants(value) {
|
|
1330
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
1331
|
+
return null;
|
|
1332
|
+
const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
|
|
1333
|
+
return entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : null;
|
|
1334
|
+
}
|
|
1260
1335
|
function joinedPlayer(connId, identity) {
|
|
1261
1336
|
if (typeof connId === "string") {
|
|
1262
|
-
|
|
1337
|
+
const player = {
|
|
1263
1338
|
...identity,
|
|
1264
1339
|
playerId: connId,
|
|
1265
1340
|
participantId: identity.scopedUserId ?? identity.userId,
|
|
1266
1341
|
};
|
|
1342
|
+
// A hub player's block list stays in the wrapper (`session.hub.hiddenPair`):
|
|
1343
|
+
// decks broadcast player objects.
|
|
1344
|
+
delete player.hiddenUserIds;
|
|
1345
|
+
// A/B arms arrive beside the player; one a host put on it stays off it too.
|
|
1346
|
+
delete player.experimentVariants;
|
|
1347
|
+
return player;
|
|
1267
1348
|
}
|
|
1268
1349
|
const legacy = connId;
|
|
1269
1350
|
return {
|
package/kits/base/sdk/store.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { StoreAllowance } from "./commands";
|
|
2
2
|
import type { Json } from "./types";
|
|
3
|
+
import { type SaveApi, type SaveBucketApi } from "./save";
|
|
3
4
|
export interface StoreListOptions {
|
|
4
5
|
/** Only keys beginning with this. Omit for every key in the scope. */
|
|
5
6
|
prefix?: string;
|
|
@@ -21,7 +22,7 @@ export interface StoreListPage<T extends Json = Json> {
|
|
|
21
22
|
*/
|
|
22
23
|
cursor: string | null;
|
|
23
24
|
}
|
|
24
|
-
export interface StoreScopeApi {
|
|
25
|
+
export interface StoreScopeApi extends SaveBucketApi {
|
|
25
26
|
/** Reads keys. Keys with no value are absent from the result. */
|
|
26
27
|
get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
|
|
27
28
|
/**
|
|
@@ -63,7 +64,7 @@ export interface StoreUsage {
|
|
|
63
64
|
/** `Store.deck`: one allowance shared by every player of the deck. */
|
|
64
65
|
shared: StoreAllowance;
|
|
65
66
|
}
|
|
66
|
-
export interface CastleStoreApi {
|
|
67
|
+
export interface CastleStoreApi extends SaveApi {
|
|
67
68
|
/** Shared by everyone playing the deck. */
|
|
68
69
|
readonly deck: StoreScopeApi;
|
|
69
70
|
/** The current player's data, which other players can read. */
|
package/kits/base/sdk/store.js
CHANGED
|
@@ -2,6 +2,7 @@ import { chunked } from "./chunk";
|
|
|
2
2
|
import { decodeStorageValue, encodeStorageValue, storageError } from "./storageJson";
|
|
3
3
|
import { hostRequest } from "./transport";
|
|
4
4
|
import { onUnloadFlush } from "./unloadFlush";
|
|
5
|
+
import { createSaveApi, createSaveBucket, } from "./save";
|
|
5
6
|
// Per-key deck storage for Cauldron decks.
|
|
6
7
|
//
|
|
7
8
|
// The older Storage/SharedStorage keep one document per bucket and rewrite the
|
|
@@ -212,6 +213,7 @@ function assertKeys(keys, operation) {
|
|
|
212
213
|
}
|
|
213
214
|
function createScope(scope, subject) {
|
|
214
215
|
return {
|
|
216
|
+
...createSaveBucket(saveApi, scope, subject ?? undefined),
|
|
215
217
|
async get(keys) {
|
|
216
218
|
const { entries } = await hostRequest("cauldronStorage.get", {
|
|
217
219
|
scope,
|
|
@@ -309,7 +311,10 @@ async function usage() {
|
|
|
309
311
|
const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
|
|
310
312
|
return { player: allowances.player, shared: allowances.shared };
|
|
311
313
|
}
|
|
314
|
+
// Saves skip the write coalescing above: each is one request, sent at once.
|
|
315
|
+
const saveApi = createSaveApi((verb, input) => hostRequest(`cauldronStorage.${verb}`, input));
|
|
312
316
|
export const Store = {
|
|
317
|
+
...saveApi,
|
|
313
318
|
deck: createScope("deck", null),
|
|
314
319
|
me: createScope("user", null),
|
|
315
320
|
user(userId) {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent, type VoiceEvent } from "./commands";
|
|
1
|
+
import { type CommandName, type CommandParams, type CommandResult, type HubEvent, type LifecycleEvent, type VoiceEvent } from "./commands";
|
|
2
2
|
type PostChannel = "mobile" | "web";
|
|
3
3
|
export interface HostStreamOptions {
|
|
4
4
|
onStream?: (event: unknown) => void;
|
|
@@ -21,5 +21,6 @@ export declare function hostNotify(event: LifecycleEvent): void;
|
|
|
21
21
|
export declare function postUnloadDone(unloadId: string, state?: string): void;
|
|
22
22
|
export declare function setUnloadHandler(handler: (unloadId: string) => void): void;
|
|
23
23
|
export declare function setVoiceEventHandler(handler: ((event: VoiceEvent) => void) | null): void;
|
|
24
|
+
export declare function setHubEventHandler(handler: ((event: HubEvent) => void) | null): void;
|
|
24
25
|
export declare function installHostListener(): void;
|
|
25
26
|
export {};
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
// A streaming command (agent.chat) gets stream envelopes on its requestId before
|
|
12
12
|
// its response. Each one goes to the caller's onStream and restarts the wait,
|
|
13
13
|
// and the caller's AbortSignal sends the host a cancel envelope.
|
|
14
|
-
import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, unloadRequestId, voiceEventFrom, } from "./commands";
|
|
14
|
+
import { CASTLE_SDK_PROTOCOL, COMMAND_TIMEOUTS_MS, STREAM_IDLE_TIMEOUT_MS, isResponseEnvelope, isStreamEnvelope, hubEventFrom, unloadRequestId, voiceEventFrom, } from "./commands";
|
|
15
15
|
import { getCastleEmbed } from "./context";
|
|
16
16
|
import { CastleError } from "./errors";
|
|
17
17
|
import { cancelLocalCommand, releaseLocalCommand, sendLocalCommand } from "./runtime";
|
|
@@ -35,6 +35,7 @@ const pending = new Map();
|
|
|
35
35
|
let listenersInstalled = false;
|
|
36
36
|
let unloadHandler = null;
|
|
37
37
|
let voiceEventHandler = null;
|
|
38
|
+
let hubEventHandler = null;
|
|
38
39
|
export async function hostRequest(command, params, stream = {}) {
|
|
39
40
|
try {
|
|
40
41
|
const env = await sendCommand(resolveChannel(), command, params, stream);
|
|
@@ -103,6 +104,12 @@ export function setVoiceEventHandler(handler) {
|
|
|
103
104
|
if (handler)
|
|
104
105
|
installHostListener();
|
|
105
106
|
}
|
|
107
|
+
// Registered by hub.ts while the deck listens for the host's Back control.
|
|
108
|
+
export function setHubEventHandler(handler) {
|
|
109
|
+
hubEventHandler = handler;
|
|
110
|
+
if (handler)
|
|
111
|
+
installHostListener();
|
|
112
|
+
}
|
|
106
113
|
function resolveChannel() {
|
|
107
114
|
if (typeof window === "undefined")
|
|
108
115
|
return "local";
|
|
@@ -233,6 +240,11 @@ function receive(message) {
|
|
|
233
240
|
voiceEventHandler?.(voiceEvent);
|
|
234
241
|
return;
|
|
235
242
|
}
|
|
243
|
+
const hubEvent = hubEventFrom(message);
|
|
244
|
+
if (hubEvent) {
|
|
245
|
+
hubEventHandler?.(hubEvent);
|
|
246
|
+
return;
|
|
247
|
+
}
|
|
236
248
|
const unloadId = unloadRequestId(message);
|
|
237
249
|
if (unloadId !== null)
|
|
238
250
|
unloadHandler?.(unloadId);
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# hub-game
|
|
2
|
+
|
|
3
|
+
A game behind a door in the Cauldron hub town. A hub game is a
|
|
4
|
+
`castle.multiplayer-3d` deck that meets the **hub contract**
|
|
5
|
+
(`docs/contract.md`, version 1): the kit draws every player as their platform
|
|
6
|
+
avatar, brings them in at the arrival together and sends them back out
|
|
7
|
+
through the door they came in by, and draws the HUD, labels and Back control
|
|
8
|
+
the game declares. The game itself is scene data plus server hooks -- **no
|
|
9
|
+
client code** (Tier 0).
|
|
10
|
+
|
|
11
|
+
Read `docs/contract.md` before changing the `hub` block or the server hooks;
|
|
12
|
+
it is what every published hub game depends on.
|
|
13
|
+
|
|
14
|
+
## Quick reference
|
|
15
|
+
|
|
16
|
+
<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
|
|
17
|
+
|
|
18
|
+
- Scenes, blueprints, models and behaviors are `castle.physics-3d`'s, the
|
|
19
|
+
network is `castle.multiplayer-3d`'s; this kit adds the hub. Everything those
|
|
20
|
+
kits' guides say about scenes and the server holds, except where it says
|
|
21
|
+
otherwise below.
|
|
22
|
+
- **No client code.** A hub game ships nothing under `code/client/`,
|
|
23
|
+
`code/systems/`, `behaviors/`, and no `.js` outside `code/server/`. The
|
|
24
|
+
check refuses it: a hub game's content runs inside the town's iframe.
|
|
25
|
+
- **The game is `code/server/game.js`**, a default export of hooks that each
|
|
26
|
+
get `hub`, the place's context: `ready(hub)`, `arrive(hub, group)`,
|
|
27
|
+
`step(hub, dt)`, `leave(hub, playerId, { userId, username })` (a result may be
|
|
28
|
+
reported there), `shutdown(hub)` (finish writing), `message(hub, player, data)`,
|
|
29
|
+
`fall(hub, playerId)` (below the place's `fallY`; a scene with
|
|
30
|
+
`"ground": { "none": true }` has no ground and catches at -20 by default).
|
|
31
|
+
`server.main` stays `imports/castle.hub-game/code/server/index.js`.
|
|
32
|
+
- **A player's progress between visits** goes in `hub.session.storage.deck`
|
|
33
|
+
under `'<name>:<userId>'`, never user scope, which their own client can
|
|
34
|
+
write (contract §14).
|
|
35
|
+
- What `hub` does: `players()`, `actorsWith(component)` (each with its `t`,
|
|
36
|
+
`props`, `shape` and `body`), `now`, `placeAt`,
|
|
37
|
+
`hold` / `release` (keep a player still), `setHud(spec, playerId?)`,
|
|
38
|
+
`hide` / `show` (an actor, for everyone), `move(actorId, { x, y, z,
|
|
39
|
+
rotationY }, { overMs })` (a `Body` `"kinematic"` actor: platforms, sweepers,
|
|
40
|
+
gates), `tint(actorId, '#rrggbb' | null)` (a Shape actor's colour),
|
|
41
|
+
`mark(playerId, { text, color } | null)` (a coloured tag over a player's
|
|
42
|
+
avatar: a team, who is it), `wear(playerId, { kind, color, rarity } | null)`
|
|
43
|
+
(v1.4: `halo`, `aura` or `orbit` in `#rrggbb`, rarity 0-9, worn on the
|
|
44
|
+
player's avatar in every hub place once ghost keeps it), `spawn(fromActorId, at)` / `despawn(id)` (a
|
|
45
|
+
copy of a scene actor, often a hidden prototype), `pose(actorId)` /
|
|
46
|
+
`reset(actorId, at?)` (read a body; put a loose object back, at rest),
|
|
47
|
+
`tune(playerId, { speed,
|
|
48
|
+
jump } | null)` (one player's own walk, as multipliers of the preset),
|
|
49
|
+
`label(actorId, text)`, `drop(playerId?)` / `holding(playerId)` (grab, below),
|
|
50
|
+
`result(playerId, { outcome, score, stats })`, `results(playerId)` (ghost's
|
|
51
|
+
recent results and records of a player), `end(playerIds?)`,
|
|
52
|
+
`go(door, playerIds)`, `send`, `broadcast`, `session`, `sim`, `place`.
|
|
53
|
+
- **The HUD** is `{ title, big, text, timer: { since | until } }` in simulation
|
|
54
|
+
ms (`hub.now`), drawn by the hub. It is the only way the game puts words on
|
|
55
|
+
screen.
|
|
56
|
+
- **Results** are server-only, once per player per visit, checked against
|
|
57
|
+
`hub.result` in `castle.json`. No free text: the town writes the words. The
|
|
58
|
+
`outcome` may be left out when a `score` says it all (a time trial).
|
|
59
|
+
- **Players arrive at `hub.arrival.actor`**, in a row, facing
|
|
60
|
+
`hub.arrival.face`, already placed when `arrive` runs. Never move the Player
|
|
61
|
+
actor in the scene to change that -- change the arrival.
|
|
62
|
+
- **Exit is always the hub's**: the Back control, `hub.end`, or
|
|
63
|
+
`hub.maxDurationSec`. A game has no lobby and no leave button.
|
|
64
|
+
- Never ship `blueprints/other-player.scene` or restyle the Player: every
|
|
65
|
+
player is drawn as their avatar (`blueprints/avatar-<n>.scene` here).
|
|
66
|
+
- Controller: `"walk"` (the engine's `Player`) is the only preset; `hub.tune`
|
|
67
|
+
scales one player's speed and jump within it. No
|
|
68
|
+
player shove: other players are kinematic.
|
|
69
|
+
- **Grab and throw** (contract v1.3): `"grab": true` in the `hub` block (or
|
|
70
|
+
`{ throwSpeed, holdDistance, holdHeight }`) gives players a Grab / Throw
|
|
71
|
+
button for the place's `Body` `"dynamic"` actors (crates, barrels). The
|
|
72
|
+
optional hook `grab(hub, playerId, actorId, op)` hears each `'grab'` and
|
|
73
|
+
`'throw'` and refuses a grab by returning `false`; `hub.drop(playerId?)`
|
|
74
|
+
makes holders let go (a goal, a whistle), `hub.holding(playerId)` says what
|
|
75
|
+
someone holds. Never a player, one object at a time. `reach` (1.6-3 m) and
|
|
76
|
+
`steady: true` (contract v1.22) offer objects from farther away and keep
|
|
77
|
+
the button up through a moment at the reach, the cone or a shared owner --
|
|
78
|
+
for places played on phones.
|
|
79
|
+
- **Idle play** (contract v1.6): `"idle": true` in the `hub` block (or
|
|
80
|
+
`{ emotes, seats, sounds: ["sounds/x.mp3"] }`) gives players an emote picker
|
|
81
|
+
(wave, dance, cheer, bow, spin, drawn on their avatar) and Sit on scene
|
|
82
|
+
actors carrying `HubSeat` (`{ face, height }`); a seat is a hold, so the
|
|
83
|
+
place's `hub.release` stands a sitter. Hooks `emote(hub, playerId, id)` and
|
|
84
|
+
`sit(hub, playerId, seatId)` may refuse with `false`; `hub.emote(playerId,
|
|
85
|
+
id)`, `hub.seat(playerId)`, and `hub.sound(actorId, file, { loop, volume,
|
|
86
|
+
radius })` / `hub.sound(actorId, null)` for a listed sound file of the deck
|
|
87
|
+
(carried in its content pack's `audio`, so a game behind a door sounds too;
|
|
88
|
+
silent only on a town whose engine predates that).
|
|
89
|
+
- **Cabinets** (contract v1.7): a `HubDoor` with `"kind": "cabinet"` whose
|
|
90
|
+
board from ghost carries `classic` is a door to a classic Castle deck the
|
|
91
|
+
host plays itself. `hub.doors()` says `classic: true` once the board is
|
|
92
|
+
read; `hub.go(doorId, [playerId])` sends that player through alone (away
|
|
93
|
+
under the hub's cover until Back). The kit sends and draws the cabinet's
|
|
94
|
+
card: by the cabinet a small chip (the best score and whose it is), and on a
|
|
95
|
+
tap the board (cover, title, top scores with photos and frames). Inert on the dev
|
|
96
|
+
serve, where there is no board.
|
|
97
|
+
- Run it like any multiplayer deck: `castle-web serve`, two tabs on the play
|
|
98
|
+
URL. Played on its own, Back and the game's end start a fresh instance.
|
|
99
|
+
- `npm run check` bundles the deck and runs this kit's contract check; it must
|
|
100
|
+
pass before `save-deck`, which runs the same check and refuses to publish.
|
|
101
|
+
|
|
102
|
+
## What is where
|
|
103
|
+
|
|
104
|
+
| file | what it is |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| `docs/contract.md` | the contract, versioned |
|
|
107
|
+
| `code/server/index.js` | the session entry: multiplayer-3d's, with the hub layer around the deck's hooks |
|
|
108
|
+
| `code/server/hub.js` | the hub layer: place, avatars, arrival, holds, HUD, visibility, labels, results, exit, doors |
|
|
109
|
+
| `code/server/actors.js` | `hub.move` and `hub.tint`: kinematic actors driven by the server, painted actors under a budget |
|
|
110
|
+
| `code/server/grab.js`, `code/client/grab.js` | grabbing and throwing (v1.3): the server's checks, hook and `hub.drop`; the client's button, hold and throw |
|
|
111
|
+
| `code/server/idle.js`, `code/client/idle.js`, `code/client/sound.js` | idle play (v1.6): emotes, seats and sounds; the server's checks, hooks and `hub.emote` / `hub.seat` / `hub.sound`; the client's picker, Sit / Stand, avatar motion and audio |
|
|
112
|
+
| `code/server/cabinets.js`, `code/client/cabinets.js` | cabinets (v1.7): the server's cards (bounded, sent per player in range inside a send budget) and the dev fixture; the client's kept cards and which one to draw |
|
|
113
|
+
| `code/server/say.js`, `code/client/say.js` | quick reactions and canned phrases (v1.11): ids only, never text; the server's checks and fan-out, the client's words, bubbles and feed |
|
|
114
|
+
| `code/client/chat.js` | free-text chat (v1.12): polls the host for what this player may read and whom they reach, sends through it; who may chat is ghost's rule, never the kit's |
|
|
115
|
+
| `code/server/party.js` | parties in a town (v1.10): invitations, a door proposed to the party, members put on its pad, `hub.coming`; a member away through a door is kept |
|
|
116
|
+
| `code/client/together.js` | finding a friend in a town (v1.9): who here is one, the People list's rows, the pointers; the server's half (`hub-where`, `hub-goto`, the `where` hook) is in `code/server/hub.js` |
|
|
117
|
+
| `code/server/manifest.js` | reads and checks the `hub` block and results (plain JS, shared with the check) |
|
|
118
|
+
| `code/server/place.js` | which place a session runs, from the session alone |
|
|
119
|
+
| `code/server/game.js` | the starter game (Flag Dash), copied into a new deck |
|
|
120
|
+
| `code/client/hookLayer.js` | the client hooks, layered under the deck's by `castle.real-time` |
|
|
121
|
+
| `code/systems/hub.js` | the door trip, Back, joining a friend's layer, the HUD, labels, hidden actors, holds, the ribbon |
|
|
122
|
+
| `code/client/chrome.js`, `state.js`, `avatar.js`, `firstJoin.js` | the DOM chrome, what the place declared, the avatar seam, the main place's first join (§13) |
|
|
123
|
+
| `blueprints/avatar-<n>.scene`, `models/avatar-<n>.pxmodel`, `scripts/gen-avatars.mjs` | the four avatars (the Castle mascot, Petal, Beat, Star) and the script that writes their models; each avatar's height is in `avatar.js`, for what is worn over it |
|
|
124
|
+
| `scripts/gen-avatars-blocky.mjs`, `gen-avatars-bean.mjs`, `gen-avatars-pixel.mjs` | the scripts that write the other three sets' models (and blocky's and pixel's drawings); each set is the Castle mascot and three characters of its own |
|
|
125
|
+
| `blueprints/<style>/avatar-<n>.scene`, `models/<style>/`, `drawings/<style>/` | the other avatar sets (`blocky`, `bean`, `pixel`): the same four avatar ids drawn another way, picked per viewer by `Avatar.style()` (the `hub_avatar_style` experiment, or `?hubStyle=` on localhost); toon unless one is assigned (contract §11) |
|
|
126
|
+
| `scripts/check.mjs` | the publish check (`onCheck`) |
|
|
127
|
+
| `scripts/pack.mjs` | the content pack exporter (`onPack`): the deck's client half as data, for another deck's engine (`docs/content-pack.md`) |
|
|
128
|
+
| `code/client/pack.js`, `packFormat.js`, `sha256.js` | mounting a pack: fetch, verify, validate, build content |
|
|
129
|
+
| `scripts/test-manifest.mjs`, `test-pack.mjs`, `test-actors.mjs`, `test-idle.mjs`, `test-classic.mjs` | tests over the manifest, results, place resolution, the pack, moved and painted actors, idle play, and cabinets |
|
|
130
|
+
|
|
131
|
+
## Rules for editing this kit
|
|
132
|
+
|
|
133
|
+
- A change to anything `docs/contract.md` describes is a contract change: an
|
|
134
|
+
optional new field is fine within v1; anything that changes what a field
|
|
135
|
+
means, or removes one, is v2 and must keep v1 decks working.
|
|
136
|
+
- The place a session runs comes from the session (`place.js`), never from a
|
|
137
|
+
client message.
|
|
138
|
+
- Hub chrome is drawn by this kit, never by game content.
|
|
139
|
+
- Root-anchor anything that reaches the deck (`/castle.json`,
|
|
140
|
+
`/code/server/game.js`), as the multiplayer kits do.
|
|
141
|
+
|
|
142
|
+
## Not offered yet
|
|
143
|
+
|
|
144
|
+
This kit's `castle.json` carries no `description` on purpose: the CLI's kit
|
|
145
|
+
catalog (`cli/src/kitCatalog.ts`) offers the create assistant only kits that
|
|
146
|
+
describe themselves, and hub games are Castle-authored only until the door
|
|
147
|
+
table and curation exist (HUB.md decision 10). `castle-web init --kit
|
|
148
|
+
hub-game` works regardless. Adding the description is the switch that offers
|
|
149
|
+
it.
|