castle-web-cli 0.4.230 → 0.4.232

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.
Files changed (92) hide show
  1. package/dist/castle-host/host.js +81 -0
  2. package/dist/devSaveStorage.d.ts +36 -0
  3. package/dist/devSaveStorage.js +469 -0
  4. package/dist/devSessionChild.js +22 -12
  5. package/dist/devSessionServer.js +8 -2
  6. package/dist/devSessionStorage.d.ts +9 -0
  7. package/dist/devSessionStorage.js +66 -1
  8. package/dist/init.js +1 -1
  9. package/dist/serve.js +5 -1
  10. package/dist/serverBundle.js +5 -3
  11. package/kits/base/castle.json +1 -1
  12. package/kits/base/sdk/README.md +148 -1
  13. package/kits/base/sdk/castle.d.ts +4 -0
  14. package/kits/base/sdk/castle.js +2 -0
  15. package/kits/base/sdk/commands.d.ts +15 -0
  16. package/kits/base/sdk/multiplayer.js +52 -4
  17. package/kits/base/sdk/save.d.ts +197 -0
  18. package/kits/base/sdk/save.js +525 -0
  19. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  20. package/kits/base/sdk/saveCoordinator.js +252 -0
  21. package/kits/base/sdk/server/storage.d.ts +3 -2
  22. package/kits/base/sdk/server/storage.js +25 -5
  23. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  24. package/kits/base/sdk/server/wrapper.js +2 -0
  25. package/kits/base/sdk/store.d.ts +3 -2
  26. package/kits/base/sdk/store.js +5 -0
  27. package/kits/hub-game/CLAUDE.md +29 -4
  28. package/kits/hub-game/code/client/avatar.js +39 -0
  29. package/kits/hub-game/code/client/chat.js +12 -0
  30. package/kits/hub-game/code/client/chrome.js +237 -13
  31. package/kits/hub-game/code/client/grab.js +166 -7
  32. package/kits/hub-game/code/client/hats.js +26 -0
  33. package/kits/hub-game/code/client/hookLayer.js +36 -3
  34. package/kits/hub-game/code/client/hudClear.js +126 -0
  35. package/kits/hub-game/code/client/state.js +35 -1
  36. package/kits/hub-game/code/client/talk.js +10 -36
  37. package/kits/hub-game/code/client/tiers.js +505 -0
  38. package/kits/hub-game/code/client/together.js +144 -4
  39. package/kits/hub-game/code/client/wear.js +96 -14
  40. package/kits/hub-game/code/server/actors.js +5 -0
  41. package/kits/hub-game/code/server/grab.js +299 -13
  42. package/kits/hub-game/code/server/hub.js +162 -7
  43. package/kits/hub-game/code/server/manifest.js +80 -8
  44. package/kits/hub-game/code/server/npcs.js +21 -33
  45. package/kits/hub-game/code/server/party.js +75 -6
  46. package/kits/hub-game/code/server/say.js +8 -2
  47. package/kits/hub-game/code/server/wear.js +116 -11
  48. package/kits/hub-game/code/systems/hub.js +386 -21
  49. package/kits/hub-game/docs/contract.md +285 -19
  50. package/kits/hub-game/package.json +1 -1
  51. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  52. package/kits/hub-game/scripts/test-grab-client.mjs +511 -0
  53. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  54. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  55. package/kits/hub-game/scripts/test-hub-trip.mjs +721 -0
  56. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  57. package/kits/hub-game/scripts/test-manifest.mjs +122 -1
  58. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  59. package/kits/hub-game/scripts/test-party.mjs +108 -4
  60. package/kits/hub-game/scripts/test-say.mjs +59 -2
  61. package/kits/hub-game/scripts/test-tiers.mjs +854 -0
  62. package/kits/hub-game/scripts/test-together.mjs +33 -1
  63. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  64. package/kits/physics-2d/CLAUDE.md +2 -0
  65. package/kits/physics-2d/castle.json +2 -2
  66. package/kits/physics-2d/engine/scene.js +127 -0
  67. package/kits/physics-2d/package.json +1 -1
  68. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +298 -0
  69. package/kits/physics-3d/CLAUDE.md +531 -0
  70. package/kits/physics-3d/behaviors/Player.jsx +437 -3
  71. package/kits/physics-3d/castle.json +3 -3
  72. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  73. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -1
  74. package/kits/physics-3d/engine3d/actornode.js +253 -0
  75. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  76. package/kits/physics-3d/engine3d/optimize.js +49 -0
  77. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  78. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  79. package/kits/physics-3d/engine3d/world3d.js +525 -11
  80. package/kits/physics-3d/package.json +1 -1
  81. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  82. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  83. package/kits/physics-3d/scripts/test-camera-follow.mjs +543 -0
  84. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  85. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  86. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  87. package/kits/physics-3d/scripts/test-static-actors.mjs +667 -0
  88. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  89. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  90. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  91. package/kits/physics-3d/systems/physics3d.js +273 -9
  92. package/package.json +1 -1
@@ -0,0 +1,252 @@
1
+ import { asSaveError, encodeSaveInput, matchSaveTarget, SaveError, saveTargetKey, } from "./save";
2
+ // The request is built when a save is first sent, from the revisions known then.
3
+ function buildRequest(intent, access, revisions, writers) {
4
+ const changes = intent.changes.map((change) => {
5
+ const key = saveTargetKey(change.target);
6
+ const expectedRevision = change.expectedRevision === undefined
7
+ ? revisions.get(key)
8
+ : change.expectedRevision;
9
+ if (expectedRevision === undefined) {
10
+ throw new SaveError({
11
+ code: "CAULDRON_STORAGE_INVALID_ARGUMENT",
12
+ message: "Load a target's revision before saving it.",
13
+ operationId: intent.operationId,
14
+ retryable: false,
15
+ committed: false,
16
+ target: change.target,
17
+ });
18
+ }
19
+ const writer = change.writer ?? writers.get(key);
20
+ return {
21
+ ...change,
22
+ expectedRevision,
23
+ ...(writer === undefined ? {} : { writer }),
24
+ };
25
+ });
26
+ return {
27
+ operationId: intent.operationId,
28
+ expectedAccess: access,
29
+ ...(intent.checks ? { checks: intent.checks } : {}),
30
+ changes,
31
+ };
32
+ }
33
+ // A committed error with its receipt is a repeat of a save that committed
34
+ // earlier, whose fresh reply failed for some other reason.
35
+ async function send(api, request) {
36
+ try {
37
+ return await api.transaction(request);
38
+ }
39
+ catch (failure) {
40
+ const error = asSaveError(failure, request.operationId);
41
+ if (error.committed === true && error.receipt)
42
+ return error.receipt;
43
+ throw error;
44
+ }
45
+ }
46
+ // An unknown outcome is not a cancellation: the first request may still
47
+ // arrive. So it is looked up, then sent again exactly as before.
48
+ async function settle(api, request) {
49
+ try {
50
+ return await send(api, request);
51
+ }
52
+ catch (error) {
53
+ if (error.committed !== "unknown")
54
+ throw error;
55
+ }
56
+ let found;
57
+ try {
58
+ found = await api.operation(request.operationId);
59
+ }
60
+ catch (failure) {
61
+ const error = asSaveError(failure, request.operationId);
62
+ throw new SaveError({
63
+ ...error.extensions,
64
+ code: error.code,
65
+ message: error.message,
66
+ operationId: request.operationId,
67
+ retryable: error.retryable,
68
+ committed: "unknown",
69
+ });
70
+ }
71
+ if (found.state === "committed")
72
+ return found.receipt;
73
+ return send(api, request);
74
+ }
75
+ /**
76
+ * Starts from a snapshot of the targets to be saved and the writers of any
77
+ * claimed ones. Keep the coordinator where it outlives a replaceable worker.
78
+ */
79
+ export function createSaveCoordinator(api, snapshot, writers = []) {
80
+ const access = snapshot.access;
81
+ const revisions = new Map(snapshot.targets.map((entry) => [
82
+ saveTargetKey(entry.target),
83
+ entry.revision,
84
+ ]));
85
+ const writerTokens = new Map(writers.map((entry) => [saveTargetKey(entry.target), entry.writer]));
86
+ const submittedIds = new Set();
87
+ const queue = [];
88
+ let flushes = [];
89
+ let blocked;
90
+ let running;
91
+ function apply(receipt, request) {
92
+ const targets = request.changes.map((change) => change.target);
93
+ for (const entry of receipt.revisions) {
94
+ const target = matchSaveTarget(entry.target, targets);
95
+ revisions.set(saveTargetKey(target), entry.revision);
96
+ }
97
+ }
98
+ function block(item, error) {
99
+ blocked = error;
100
+ if (error.committed === false && !error.retryable) {
101
+ item.failed = true;
102
+ item.reject(error);
103
+ }
104
+ for (const flush of flushes)
105
+ flush.reject(error);
106
+ flushes = [];
107
+ }
108
+ function commit(item, receipt) {
109
+ queue.shift();
110
+ item.resolve(receipt);
111
+ flushes = flushes.filter((flush) => {
112
+ if (flush.last !== item)
113
+ return true;
114
+ flush.resolve();
115
+ return false;
116
+ });
117
+ }
118
+ async function drain() {
119
+ while (queue.length > 0 && !blocked) {
120
+ const item = queue[0];
121
+ try {
122
+ item.request ??= buildRequest(item.intent, access, revisions, writerTokens);
123
+ const receipt = await settle(api, item.request);
124
+ apply(receipt, item.request);
125
+ commit(item, receipt);
126
+ }
127
+ catch (failure) {
128
+ block(item, asSaveError(failure, item.intent.operationId));
129
+ }
130
+ }
131
+ }
132
+ // A save submitted while the last drain was finishing finds it still running,
133
+ // so the drain looks again once it is done.
134
+ function start() {
135
+ running ??= drain().finally(() => {
136
+ running = undefined;
137
+ if (queue.length > 0 && !blocked)
138
+ void start();
139
+ });
140
+ return running;
141
+ }
142
+ return {
143
+ get status() {
144
+ if (blocked)
145
+ return "blocked";
146
+ return queue.length > 0 ? "pending" : "saved";
147
+ },
148
+ get error() {
149
+ return blocked;
150
+ },
151
+ get pendingOperationIds() {
152
+ return queue
153
+ .filter((item) => !item.failed)
154
+ .map((item) => item.intent.operationId);
155
+ },
156
+ revision: (target) => revisions.get(saveTargetKey(target)),
157
+ submit(input) {
158
+ if (submittedIds.has(input.operationId)) {
159
+ return Promise.reject(new SaveError({
160
+ code: "CAULDRON_STORAGE_OPERATION_MISMATCH",
161
+ message: "This coordinator already has that operation id.",
162
+ operationId: input.operationId,
163
+ retryable: false,
164
+ committed: false,
165
+ }));
166
+ }
167
+ // Encoding validates and copies the save, so later changes to the
168
+ // caller's objects do not reach it.
169
+ let intent;
170
+ try {
171
+ const encoded = encodeSaveInput("transaction", {
172
+ operationId: input.operationId,
173
+ expectedAccess: access,
174
+ ...(input.checks ? { checks: input.checks } : {}),
175
+ changes: input.changes.map((change) => ({
176
+ ...change,
177
+ expectedRevision: change.expectedRevision ?? null,
178
+ })),
179
+ });
180
+ intent = {
181
+ operationId: encoded.operationId,
182
+ ...(encoded.checks ? { checks: encoded.checks } : {}),
183
+ changes: encoded.changes.map((change, index) => ({
184
+ ...change,
185
+ expectedRevision: input.changes[index].expectedRevision,
186
+ })),
187
+ };
188
+ }
189
+ catch (error) {
190
+ return Promise.reject(asSaveError(error, input.operationId));
191
+ }
192
+ submittedIds.add(input.operationId);
193
+ const promise = new Promise((resolve, reject) => {
194
+ queue.push({ intent, failed: false, resolve, reject });
195
+ });
196
+ // A deck may watch status or flush() instead of every save's promise.
197
+ promise.catch(() => { });
198
+ void start();
199
+ return promise;
200
+ },
201
+ flush() {
202
+ const last = queue.at(-1);
203
+ if (!last)
204
+ return Promise.resolve();
205
+ if (blocked)
206
+ return Promise.reject(blocked);
207
+ return new Promise((resolve, reject) => {
208
+ flushes.push({ last, resolve, reject });
209
+ });
210
+ },
211
+ async retry() {
212
+ await running;
213
+ if (!blocked)
214
+ return;
215
+ if (queue[0]?.failed)
216
+ throw blocked;
217
+ if (blocked.retryAfterMs !== undefined && blocked.retryAfterMs > 0) {
218
+ const delay = blocked.retryAfterMs;
219
+ await new Promise((resolve) => setTimeout(resolve, delay));
220
+ }
221
+ blocked = undefined;
222
+ return start().then(() => {
223
+ if (blocked)
224
+ throw blocked;
225
+ });
226
+ },
227
+ discardUnsent() {
228
+ const error = new SaveError({
229
+ code: "CAULDRON_STORAGE_CANCELLED",
230
+ message: "The save was discarded before it was sent.",
231
+ retryable: false,
232
+ committed: false,
233
+ });
234
+ for (let index = queue.length - 1; index >= 0; index--) {
235
+ const item = queue[index];
236
+ if (item.request || item.failed)
237
+ continue;
238
+ queue.splice(index, 1);
239
+ item.reject(error);
240
+ }
241
+ // A flush still waits for the sent save ahead of what was dropped.
242
+ flushes = flushes.filter((flush) => {
243
+ if (!flush.last || !queue.includes(flush.last))
244
+ flush.last = queue[0];
245
+ if (flush.last)
246
+ return true;
247
+ flush.resolve();
248
+ return false;
249
+ });
250
+ },
251
+ };
252
+ }
@@ -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>;
@@ -257,7 +258,7 @@ export interface ServerCharacterHistoryOptions {
257
258
  limit?: number;
258
259
  cursor?: string | null;
259
260
  }
260
- export interface ServerStorage {
261
+ export interface ServerStorage extends SaveApi {
261
262
  /** Shared by everyone playing the deck, and owned by this server. */
262
263
  readonly deck: ServerStorageScope;
263
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
- deck: createScope(call, "DECK", null),
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", null);
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.
@@ -4,6 +4,10 @@ import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommand
4
4
  import { type ServerStorage } from "./storage";
5
5
  import { type MultiplayerHubArrival, type MultiplayerServerHub } from "./hub";
6
6
  export type { MultiplayerSessionMode, PlatformHandle, PlatformSessionConfig, PlatformWorldCheckpoint, PlatformWorldSnapshot, PlatformWorldTimeConfig, PlayerIdentity, } from "./platformHandle";
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";
7
11
  export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
8
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";
9
13
  export interface MultiplayerServerPlayer extends PlayerIdentity {
@@ -2,6 +2,8 @@ import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
2
2
  import { encodeStorageValue, storageError } from "../storageJson";
3
3
  import { createServerStorage } from "./storage";
4
4
  import { createServerHub, hubArrival, recordHiddenUserIds, } from "./hub";
5
+ export { createSaveCoordinator } from "../saveCoordinator";
6
+ export { SaveError } from "../save";
5
7
  // The publish bundler binds the author's default callbacks export once and
6
8
  // exports the returned one-argument function as `__castleBootSession`.
7
9
  export function createCastleSessionBoot(callbacks) {
@@ -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. */
@@ -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) {
@@ -40,13 +40,19 @@ it is what every published hub game depends on.
40
40
  gates), `tint(actorId, '#rrggbb' | null)` (a Shape actor's colour),
41
41
  `mark(playerId, { text, color } | null)` (a coloured tag over a player's
42
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
43
+ (v1.4: `halo`, `aura`, `orbit` or a hat `hat-<id>`, the ids in
44
+ `code/client/hats.js` `HATS`; in `#rrggbb`, rarity 0-9, worn on the
45
+ player's avatar in every hub place once ghost keeps it),
46
+ `tryOn(playerId, { kind, color, rarity } | null)` (v1.28: the same wearable
47
+ shown in this place only and never saved -- a shop's try-on, a costume for
48
+ the visit; the one the player owns is untouched and is drawn again on
49
+ `null`, when they leave or when the place ends), `spawn(fromActorId, at)` / `despawn(id)` (a
45
50
  copy of a scene actor, often a hidden prototype), `pose(actorId)` /
46
51
  `reset(actorId, at?)` (read a body; put a loose object back, at rest),
47
52
  `tune(playerId, { speed,
48
53
  jump } | null)` (one player's own walk, as multipliers of the preset),
49
- `label(actorId, text)`, `drop(playerId?)` / `holding(playerId)` (grab, below),
54
+ `label(actorId, text)`, `drop(playerId?)` / `holding(playerId)` /
55
+ `keepFor(actorId, playerId | null)` (grab, below),
50
56
  `result(playerId, { outcome, score, stats })`, `results(playerId)` (ghost's
51
57
  recent results and records of a player), `end(playerIds?)`,
52
58
  `go(door, playerIds)`, `send`, `broadcast`, `session`, `sim`, `place`.
@@ -72,7 +78,24 @@ it is what every published hub game depends on.
72
78
  optional hook `grab(hub, playerId, actorId, op)` hears each `'grab'` and
73
79
  `'throw'` and refuses a grab by returning `false`; `hub.drop(playerId?)`
74
80
  makes holders let go (a goal, a whistle), `hub.holding(playerId)` says what
75
- someone holds. Never a player, one object at a time.
81
+ someone holds. Never a player, one object at a time. `reach` (1.6-3 m) and
82
+ `steady: true` (contract v1.22) offer objects from farther away and keep
83
+ the button up through a moment at the reach, the cone or a shared owner --
84
+ for places played on phones. `keepHeld: true` (contract v1.25) keeps a
85
+ held object its holder's when another player stands nearer; without it the
86
+ nearer player is handed it and the hold ends.
87
+ `hub.keepFor(actorId, playerId | null)` (contract v1.27) keeps a loose
88
+ object for one player (a pillow of their own): nobody else is offered it or
89
+ may grab it, and the `grab` hook is not asked about their tries. It ends
90
+ with `null`, `hub.hide` and the player's leaving, and outlives `hub.reset`.
91
+ It does not change who simulates the object, so its keeper is offered it
92
+ only while nearest to it: put it beside them (`hub.reset(actorId, at)`).
93
+ - **A clear HUD** (contract v1.26): `"hud": { "clear": true }` in the `hub`
94
+ block, for places played on phones. A big line with a text line under it
95
+ is drawn at 32 px on one line (alone it keeps 56 px), labels, speech, marks
96
+ and goal pointers that would lie over the HUD are moved to just under it,
97
+ and on a phone on its side the text keeps to two lines. Without it the HUD
98
+ and labels are drawn as they always were.
76
99
  - **Idle play** (contract v1.6): `"idle": true` in the `hub` block (or
77
100
  `{ emotes, seats, sounds: ["sounds/x.mp3"] }`) gives players an emote picker
78
101
  (wave, dance, cheer, bow, spin, drawn on their avatar) and Sit on scene
@@ -111,6 +134,8 @@ it is what every published hub game depends on.
111
134
  | `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 |
112
135
  | `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 |
113
136
  | `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` |
137
+ | `code/server/wear.js` | wearables on the server: `hub.wear` (kept here and sent to ghost) and `hub.tryOn` (v1.28: kept here only, never sent to ghost), and what each client is told of both |
138
+ | `code/client/wear.js`, `code/client/hats.js` | what players wear (v1.4) and how each hat is built; the hat ids, a list a place's server may import; each avatar's hat fit is in `avatar.js` |
114
139
  | `code/server/manifest.js` | reads and checks the `hub` block and results (plain JS, shared with the check) |
115
140
  | `code/server/place.js` | which place a session runs, from the session alone |
116
141
  | `code/server/game.js` | the starter game (Flag Dash), copied into a new deck |
@@ -33,6 +33,39 @@ const TOPS = {
33
33
  };
34
34
  const DEFAULT_TOP = 1.65;
35
35
 
36
+ // How a hat sits on each avatar (`wear.js`), `[seat, scale, rise]`: how big the
37
+ // hat is drawn for the size of the head (toon's Star wears a small one on its
38
+ // top point); the height over its feet of the ring of its head that the hat's
39
+ // rim, 0.2 m times the scale, rests on, measured down onto each model, not
40
+ // its top, which is often an ear, a bow or a leaf; and how far the crown of
41
+ // the head stands over the seat, for a hat narrower than the rim.
42
+ const HAT_FITS = {
43
+ toon: [
44
+ [1.27, 1.3, 0.08],
45
+ [1.21, 1.1, 0.07],
46
+ [1.18, 1.1, 0.08],
47
+ [1.43, 0.6, 0.06],
48
+ ],
49
+ blocky: [
50
+ [1.39, 1.1, 0.04],
51
+ [1.48, 1.1, 0],
52
+ [1.47, 1.1, 0],
53
+ [1.48, 1.1, 0],
54
+ ],
55
+ bean: [
56
+ [1.27, 1.3, 0.08],
57
+ [1.16, 1.3, 0.11],
58
+ [1.22, 1, 0.1],
59
+ [1.18, 1.3, 0.06],
60
+ ],
61
+ pixel: [
62
+ [1.33, 1.2, 0.04],
63
+ [1.33, 1.15, 0.07],
64
+ [1.27, 1.15, 0.06],
65
+ [1.33, 1.15, 0.01],
66
+ ],
67
+ };
68
+
36
69
  // Where the kit's blueprints are: inside the import in a deck, at the root
37
70
  // while this kit is served as itself.
38
71
  const ROOTS = ['imports/castle.hub-game/', ''];
@@ -257,6 +290,12 @@ export function top(index, which = style()) {
257
290
  return usable(index) ? TOPS[STYLES.includes(which) ? which : DEFAULT_STYLE][index] : DEFAULT_TOP;
258
291
  }
259
292
 
293
+ // How a hat sits on the avatar in a set (`HAT_FITS`), or null for one this kit
294
+ // does not have. The same array every time: nothing is made per frame.
295
+ export function hatFit(index, which = style()) {
296
+ return usable(index) ? HAT_FITS[STYLES.includes(which) ? which : DEFAULT_STYLE][index] : null;
297
+ }
298
+
260
299
  // The blueprint other players are drawn from, as a path the live files map
261
300
  // has, or null before the files are known. A set these files do not have is
262
301
  // drawn from toon's.
@@ -11,6 +11,9 @@ import * as castleSdk from 'castle-web-sdk';
11
11
  // while nobody can (a friend may arrive).
12
12
  const POLL_MS = 2500;
13
13
  const IDLE_POLL_MS = 15000;
14
+ // Cues (v1.23): someone came into the roster while nobody could be chatted
15
+ // with: the host is asked again this soon, not at the end of the idle wait.
16
+ const SOON_MS = 1000;
14
17
  // A chat line stays over its speaker this long.
15
18
  export const CHAT_BUBBLE_MS = 6000;
16
19
 
@@ -84,6 +87,15 @@ export function makeChat() {
84
87
  });
85
88
  },
86
89
 
90
+ // Cues (v1.23): a player just came in, who may be one this player can
91
+ // chat with. Brings the next ask forward when the idle wait is on; a
92
+ // crowd coming in together is still one ask.
93
+ soon(now) {
94
+ if (!c.peers?.length && askedAt !== -Infinity) {
95
+ askedAt = Math.min(askedAt, now - IDLE_POLL_MS + SOON_MS);
96
+ }
97
+ },
98
+
87
99
  // Sends `text`; `done(status)` hears ghost's answer: "sent", "none"
88
100
  // (nobody here may read it), "limited", "refused" or "unavailable".
89
101
  send(text, done = () => {}) {