castle-web-cli 0.4.229 → 0.4.230
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 +779 -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/devSessionChild.js +3 -1
- package/dist/devSessionServer.d.ts +14 -1
- package/dist/devSessionServer.js +229 -44
- 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 +125 -8
- 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 +94 -13
- 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 +258 -52
- 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 +5 -0
- package/kits/base/sdk/castle.js +3 -0
- package/kits/base/sdk/commands.d.ts +208 -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 +106 -4
- 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 +55 -2
- package/kits/base/sdk/server/wrapper.d.ts +32 -2
- package/kits/base/sdk/server/wrapper.js +90 -11
- 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 +146 -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 +1001 -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 +241 -0
- package/kits/hub-game/code/client/hookLayer.js +230 -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 +131 -0
- package/kits/hub-game/code/client/talk.js +259 -0
- package/kits/hub-game/code/client/together.js +365 -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 +247 -0
- package/kits/hub-game/code/server/history.js +96 -0
- package/kits/hub-game/code/server/hub.js +1904 -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 +527 -0
- package/kits/hub-game/code/server/npcs.js +745 -0
- package/kits/hub-game/code/server/party.js +381 -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 +2230 -0
- package/kits/hub-game/docs/content-pack.md +151 -0
- package/kits/hub-game/docs/contract.md +1139 -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.mjs +331 -0
- package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
- package/kits/hub-game/scripts/test-hub-trip.mjs +1310 -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 +224 -0
- package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
- package/kits/hub-game/scripts/test-npcs.mjs +714 -0
- package/kits/hub-game/scripts/test-pack.mjs +424 -0
- package/kits/hub-game/scripts/test-party.mjs +286 -0
- package/kits/hub-game/scripts/test-say.mjs +149 -0
- package/kits/hub-game/scripts/test-together.mjs +183 -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/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 +25 -5
- package/kits/physics-3d/CLAUDE.md +6 -1
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +32 -4
- package/kits/physics-3d/engine3d/artobjects.js +2 -2
- package/kits/physics-3d/engine3d/materials.js +29 -1
- package/kits/physics-3d/engine3d/world3d.js +65 -1
- package/kits/physics-3d/systems/physics3d.js +5 -2
- 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
|
@@ -0,0 +1,1139 @@
|
|
|
1
|
+
# The hub-game contract
|
|
2
|
+
|
|
3
|
+
**Version 1.14** (2026-10-04; v1 plus the optional additions under "Changes in
|
|
4
|
+
v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
|
|
5
|
+
`cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
|
|
6
|
+
contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
|
|
7
|
+
`hub-m0-town-deck-with-two-doors-scene-swap-and-p`).
|
|
8
|
+
|
|
9
|
+
A **hub game** is a deck built on `castle.hub-game` that declares a `hub` block in
|
|
10
|
+
its `castle.json` and ships nothing to the client but data (Tier 0): scenes,
|
|
11
|
+
models, blueprints, engine behaviors by name. Its server half is ordinary deck
|
|
12
|
+
code (`code/server/game.js`). Every hub-kit deck is a **place**; the town is the
|
|
13
|
+
place with the most doors.
|
|
14
|
+
|
|
15
|
+
The contract is everything a published hub game depends on. It changes only by a
|
|
16
|
+
version bump: a new optional field is a minor change inside the same version; a
|
|
17
|
+
removed or re-meant field is version 2, and the kit keeps reading version 1 decks
|
|
18
|
+
for as long as a published one exists (HUB.md Risks: "a contract is forever").
|
|
19
|
+
|
|
20
|
+
## What a hub game may not do
|
|
21
|
+
|
|
22
|
+
Checked by the kit's check (`scripts/check.mjs`, run by `castle-web check` and `save-deck`) where it can be, by
|
|
23
|
+
curation where it cannot:
|
|
24
|
+
|
|
25
|
+
- ship client code: no `code/client/`, no `code/systems/`, no `behaviors/`, no
|
|
26
|
+
`*.js`/`*.jsx` outside `code/server/`, and an `index.html` that loads the kit's
|
|
27
|
+
entry and nothing else (Tier 0);
|
|
28
|
+
- ship its own player character: no `blueprints/other-player.scene`, and the
|
|
29
|
+
scene's `Player` actor is drawn as the platform avatar whatever its `Model`
|
|
30
|
+
says;
|
|
31
|
+
- call `Portal.open`, draw its own cosmetics or shop, or draw over the hub chrome
|
|
32
|
+
(it has no client code to do any of it with);
|
|
33
|
+
- choose where a player comes out, keep a player past `maxDurationSec`, or have a
|
|
34
|
+
lobby or a leave button of its own.
|
|
35
|
+
|
|
36
|
+
## 1. The manifest: `castle.json` → `hub`
|
|
37
|
+
|
|
38
|
+
```jsonc
|
|
39
|
+
"hub": {
|
|
40
|
+
"contract": 1, // required; the version this deck was written against
|
|
41
|
+
"title": "Foot Race", // ≤ 40 chars; the door cover, the result ribbon
|
|
42
|
+
"scene": "scenes/main.scene", // optional; the place's scene (default: editor.defaultPlayFile, then scenes/main.scene)
|
|
43
|
+
"minPlayers": 1, // 1..24; a pad does not fire below it
|
|
44
|
+
"maxPlayers": 8, // 1..24 and ≤ server.maxPlayers; one instance never holds more
|
|
45
|
+
"lateJoin": true, // a pad may send a player into a running instance with room
|
|
46
|
+
"maxDurationSec": 300, // 30..1800; the kit sends a player back when their visit reaches it
|
|
47
|
+
"controller": "walk", // a controller preset (§6)
|
|
48
|
+
"arrival": { // §5
|
|
49
|
+
"actor": "arrival", // id of the scene actor players arrive at (default: the Player actor's spawn)
|
|
50
|
+
"spread": 1.5, // metres between players arriving together (0..5, default 1.5)
|
|
51
|
+
"face": "actor" // "actor" (its Transform.rotationY) | "center" (toward x=0,z=0) | a number of degrees
|
|
52
|
+
},
|
|
53
|
+
"result": { // §7; omit for a place that reports no results (a town)
|
|
54
|
+
"outcomes": ["win", "lose", "draw"],
|
|
55
|
+
"score": { "unit": "ms", "better": "lower", "min": 0, "max": 600000 },
|
|
56
|
+
"stats": { "laps": "number", "kart": "string" }
|
|
57
|
+
},
|
|
58
|
+
"sign": { "model": "models/sign.pxmodel", "board": "score" }, // optional
|
|
59
|
+
"npcs": { "route": "town", "slot": "square", "turnsPerMinute": 6 }, // optional; §13
|
|
60
|
+
"fallY": -10, // optional (v1.1); below this a player has fallen (§5)
|
|
61
|
+
"grab": true, // optional (v1.3); players pick up loose objects and throw them (§6)
|
|
62
|
+
"idle": { "emotes": true, "seats": true, "sounds": ["sounds/jukebox.mp3"] }, // optional (v1.6); emotes, seats, the place's sounds (§6)
|
|
63
|
+
"nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
|
|
64
|
+
"places": { } // optional; more places in the same deck (§3)
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| field | type | rule |
|
|
69
|
+
| --- | --- | --- |
|
|
70
|
+
| `contract` | integer | `1`. A deck naming a version the kit does not know is refused (check fails; the server logs and runs nothing). |
|
|
71
|
+
| `title` | string | 1-40 chars. |
|
|
72
|
+
| `scene` | string | a `scenes/*.scene` path the deck has. |
|
|
73
|
+
| `minPlayers`, `maxPlayers` | integer | `1 ≤ min ≤ max ≤ 24`; `max ≤ server.maxPlayers`. |
|
|
74
|
+
| `lateJoin` | boolean | default `false`. |
|
|
75
|
+
| `maxDurationSec` | integer | 30-1800. Default 600 for a place that declares `result`; a place that does not (a town) has no limit unless it sets one. |
|
|
76
|
+
| `controller` | string | a preset name the kit has (§6). |
|
|
77
|
+
| `arrival` | object | §5. |
|
|
78
|
+
| `result` | object | §7. |
|
|
79
|
+
| `sign` | object | `model`: a `.pxmodel` the deck has; `board`: `"score"` or a declared numeric stat. |
|
|
80
|
+
| `places` | object | §3. |
|
|
81
|
+
| `npcs` | object | §13. |
|
|
82
|
+
| `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: none, or -20 in a scene with no ground. |
|
|
83
|
+
| `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. `false` or absent: no grabbing (§6). |
|
|
84
|
+
| `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds }`: `emotes` and `seats` true or false (default false), `sounds` up to 16 different `.mp3`/`.wav`/`.m4a` paths (lower-case extensions, as the engine bundles them) of this deck that `hub.sound` may play (each at most 256 KB, 1 MB in all, checked at publish). `false`, absent or all off: none of it (§6). |
|
|
85
|
+
| `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
|
|
86
|
+
|
|
87
|
+
Unknown keys are a check failure, not ignored: a typo in a contract field must
|
|
88
|
+
not publish as "no such rule".
|
|
89
|
+
|
|
90
|
+
## 2. Where a session learns its place
|
|
91
|
+
|
|
92
|
+
**A session's server never learns its place from a client.** (M0 gap 6: the M0
|
|
93
|
+
town let the first client name the scene, so any client could start a session
|
|
94
|
+
of any of the deck's scenes.) The kit resolves the place once, from the session,
|
|
95
|
+
before the world is built, in this order:
|
|
96
|
+
|
|
97
|
+
1. **`session.place`**, stamped by the host. It is the seam for ghost's door
|
|
98
|
+
placement: the door row (`cauldron_hub_doors`) names the destination place,
|
|
99
|
+
ghost puts it in the session spec, and the host hands it to the runtime
|
|
100
|
+
(`PlatformSessionConfig.place`). No production host stamps it yet; that is the
|
|
101
|
+
doors card's.
|
|
102
|
+
2. **The dev serve's named key**, and only there: a session id `dev:hub.<place>.<instance>`
|
|
103
|
+
(the key a place mints in `hub.go`, §4) names `<place>`. This is honoured only
|
|
104
|
+
for a `dev:` session id, i.e. on `castle-web serve`, where every client is the
|
|
105
|
+
author's own. A production named key is chosen by a client and never read.
|
|
106
|
+
3. Otherwise the deck's main place.
|
|
107
|
+
|
|
108
|
+
A place id the deck does not declare falls back to the main place and is logged.
|
|
109
|
+
`sceneFromClient` (the M0 seam in `castle.real-time`) is not used by hub decks.
|
|
110
|
+
|
|
111
|
+
## 3. Places
|
|
112
|
+
|
|
113
|
+
A deck is one place unless it declares more:
|
|
114
|
+
|
|
115
|
+
```jsonc
|
|
116
|
+
"places": {
|
|
117
|
+
"race": { "title": "Foot Race", "scene": "scenes/race.scene", "minPlayers": 1, "maxPlayers": 6, … },
|
|
118
|
+
"arena": { "title": "King of the Hill", "scene": "scenes/arena.scene", … }
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Each entry is a full place block (every field of §1 but `contract` and
|
|
123
|
+
`places`); the top-level fields are the main place. A place's server hooks are
|
|
124
|
+
`code/server/places/<id>.js` when it exists, else `code/server/game.js`. Place ids
|
|
125
|
+
match `[a-z][a-z0-9-]{0,23}`; `main` is reserved for the top level.
|
|
126
|
+
|
|
127
|
+
Several places in one deck is how a game's lobby has doors to its own arenas. A
|
|
128
|
+
door to another deck mounts that deck's **content pack** (`docs/content-pack.md`):
|
|
129
|
+
its client half as data, published paired with its server bundle.
|
|
130
|
+
|
|
131
|
+
## 4. Server hooks
|
|
132
|
+
|
|
133
|
+
`castle.json` → `server.main` is `imports/castle.hub-game/code/server/index.js`.
|
|
134
|
+
The deck writes `code/server/game.js` (or `places/<id>.js`) with a default export
|
|
135
|
+
of any of these. Every hook gets `hub`, the place's context, first:
|
|
136
|
+
|
|
137
|
+
| hook | when |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| `ready(hub)` | the world is built, before the first tick |
|
|
140
|
+
| `arrive(hub, group)` | players with bodies who arrived together this tick: `[{ playerId, username, userId, from, fromDeckId, near, carry }]` (`userId` v1.2: a signed-in player's user id, null for an anonymous one). `from` is the door they came in by; `near` the user id of the friend they jumped to (Join), or null; `carry.result` what they bring back from a game (§7). The kit has already placed them at the arrival (§5), and a player who jumped to a friend in this session beside that friend, facing them; a hook may place them elsewhere |
|
|
141
|
+
| `step(hub, dt)` | after each physics step; `dt` seconds |
|
|
142
|
+
| `fall(hub, playerId)` | v1.1: a player fell below the place's `fallY` (§5); place them somewhere, or the kit puts them back at the arrival |
|
|
143
|
+
| `carry(hub, playerId, carry)` | where the host has hub ops: what an already-arrived player brings back, when ghost's read came after the arrival window (§7) |
|
|
144
|
+
| `leave(hub, playerId, { userId, username })` | a player left (Back, the host's Back, a closed tab). Runs while the player is still known (v1.2): `hub.result` takes their result for the visit here, and `userId` names their storage (§14) |
|
|
145
|
+
| `shutdown(hub)` | v1.2: the session is stopping. Anyone still here has had `leave` first; return a promise to finish writing (awaited up to 1.5 s, inside the host's own grace) |
|
|
146
|
+
| `grab(hub, playerId, actorId, op)` | v1.3, a place with `grab`: a player grabbed (`op` `"grab"`) or threw (`"throw"`) a loose object (§6). Return `false` to a grab to refuse it (the player lets go at once); a throw is only told. A hook that throws refuses the grab |
|
|
147
|
+
| `emote(hub, playerId, id)` | v1.6, a place with `idle.emotes`: a player asked to play emote `id` (§6). Return `false` to refuse it (nobody sees it); a hook that throws refuses it |
|
|
148
|
+
| `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). Return `false` to refuse; a hook that throws refuses |
|
|
149
|
+
| `message(hub, player, data)` | a client message that is not the kit's own. Tier 0 games have no client code, so this is for bots and tests |
|
|
150
|
+
| `where(hub, at)` | v1.9, a town: what the place calls the spot `at` (`{ x, y, z }`), for the People list (§5): a string of at most 40 characters ("in the square", "on Race Row"), or null. Asked only for a spot that is not on a door's pad or beside a door, which the kit words itself |
|
|
151
|
+
| `npcLine(hub, npc, playerId, { why, text })` | an authored line for an NPC to say to a player when its mind is not answering (§13); return a string, or null for the kit's |
|
|
152
|
+
| `npcContext(hub, npc, playerId)` | v1.8: what an NPC's mind should know right now while `playerId` talks to it (§13 notes): a string of at most 700 characters, or null for none. Read when the conversation opens and every second while it lasts |
|
|
153
|
+
| `npcHeard(hub, npc, playerId, { text })` | v1.8: a turn to an NPC's mind was admitted; `text` is the player's own words (§13), for place state a conversation may change |
|
|
154
|
+
|
|
155
|
+
`hub` carries the session, so a tick can send (M0 gap 5):
|
|
156
|
+
|
|
157
|
+
| member | what |
|
|
158
|
+
| --- | --- |
|
|
159
|
+
| `hub.session`, `hub.sim` | the Castle session and the multiplayer-3d simulation |
|
|
160
|
+
| `hub.place` | `{ id, title, scene, manifest }` |
|
|
161
|
+
| `hub.now` | simulation milliseconds |
|
|
162
|
+
| `hub.players()` | `[{ playerId, username, userId, at, arrivedAt }]` for players with bodies (`userId` v1.2, null for an anonymous player) |
|
|
163
|
+
| `hub.actorsWith(component)` | scene actors carrying a component: `[{ id, props, t, shape, body }]`: `props` the component's, `t` the Transform, `shape` the Shape's `{ kind, width, height, depth, radius }` or null, `body` the Body type or null (v1.1: a marker need not repeat its actor's size) |
|
|
164
|
+
| `hub.placeAt(playerId, at, facingDeg?)` | move a player's body; reaches the client as a clamp |
|
|
165
|
+
| `hub.hold(playerId, at?, facingDeg?)` / `hub.release(playerId)` | hold a player still (§8) |
|
|
166
|
+
| `hub.setHud(spec, playerId?)` | the declared HUD, for everyone or one player (§9) |
|
|
167
|
+
| `hub.hide(actorId)` / `hub.show(actorId)` | server-declared actor visibility (§10) |
|
|
168
|
+
| `hub.move(actorId, { x, y, z, rotationY }, { overMs }?)` | move a kinematic scene actor, at once or in a straight line over `overMs`; any subset of the fields (§10, v1.1) |
|
|
169
|
+
| `hub.tint(actorId, color)` | paint a Shape actor `#rrggbb` for everyone; `null` puts back its authored colour (§10, v1.1) |
|
|
170
|
+
| `hub.pose(actorId)` | where an actor's body is now: `{ x, y, z, rotationY, velocity, owner }` (`owner` the player whose client simulates a loose object, or null), or null (§10, v1.3) |
|
|
171
|
+
| `hub.reset(actorId, { x, y, z, rotationY }?)` | put a loose (dynamic) object back where it was authored, or at a point, at rest, taking it from the client simulating it (§10, v1.3) |
|
|
172
|
+
| `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2) |
|
|
173
|
+
| `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back |
|
|
174
|
+
| `hub.drop(playerId?)` / `hub.holding(playerId)` | v1.3: whoever holds an object lets go (default: everyone; a goal, a whistle), returning how many were told; the actor id a player holds, or null (§6) |
|
|
175
|
+
| `hub.emote(playerId, id)` | v1.6, a place with `idle.emotes`: play a kit emote (`"wave"`, `"dance"`, `"cheer"`, `"bow"`, `"spin"`) on a player's avatar for everyone, without the hook or the rate a player's own request has; true when it took (§6) |
|
|
176
|
+
| `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
|
|
177
|
+
| `hub.sound(actorId, file, { loop, volume, radius }?)` | v1.6, a place with `idle.sounds`: play one of them at a scene actor for everyone, `volume` 0-1 (default 1), silent `radius` metres away (1-60, default 20); a loop plays until `hub.sound(actorId, null)`; true when it took (§6) |
|
|
178
|
+
| `hub.mark(playerId, { text, color })` | a coloured tag over a player's avatar for everyone: a team, who is it; `null` clears it (§11, v1.1) |
|
|
179
|
+
| `hub.wear(playerId, { kind, color, rarity })` | put a wearable on a player's avatar, kept on their account in every hub place where the host runs the hub: `kind` `"halo"`, `"aura"` or `"orbit"`, `color` `#rrggbb`, `rarity` 0-9; `null` takes it off; true when taken (§11, v1.4) |
|
|
180
|
+
| `hub.label(actorId, text, { style, ttlMs, to }?)` | words over a scene actor for everyone, or with `to: [playerIds]` for those players only (theirs replace everyone's until cleared the same way): `style` `"tag"` (a pad's count), `"speech"` (an NPC's line) or `"sign"` (a street's or a building's name, drawn at any distance in a town), ≤ 64 chars; `null` clears it (§10). An NPC body's own `say` (§13) runs to 240 chars and its bubble is kept on screen |
|
|
181
|
+
| `hub.npc(actorId)`, `hub.npcs()` | the place's NPC bodies (§13) |
|
|
182
|
+
| `hub.results(playerId)` | ghost's record of a player's hub results: `{ recent, records, readAt }` -- their newest results across places and their record per place -- or null (dev serve, anonymous). Read at arrival and once a minute for everyone here (§7, v1.5) |
|
|
183
|
+
| `hub.result(playerId, result)` | the player's result for this visit (§7) |
|
|
184
|
+
| `hub.end(playerIds?)` | the game is over for these players (default: everyone): they go back through the door |
|
|
185
|
+
| `hub.doors()` | this place's doors: `[{ id, to, actor, t, props, title, minPlayers, maxPlayers, lateJoin, classic }]`, the destination's numbers from its manifest; `classic` (v1.7) is true for a cabinet, a door to a classic deck, once ghost's board says so |
|
|
186
|
+
| `hub.go(door, playerIds, { instance }?)` | send players through a door of this place (a town's pad firing) into a new instance, or into `instance`, one an earlier `go` returned (a late join); returns the instance |
|
|
187
|
+
| `hub.pad(door, playerIds)` | who stands on a pad door's pad; call it as often as they change (each step is fine). Where the host has hub ops the kit tells ghost, which then holds the pad's group; nothing in dev |
|
|
188
|
+
| `hub.coming(door)` | v1.10: how many members of a party were asked to this door and have not answered yet (§5 parties), so a place may hold its pad's countdown for them; 0 where there are none |
|
|
189
|
+
| `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board |
|
|
190
|
+
| `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
|
|
191
|
+
|
|
192
|
+
`hub.go` is how any place launches: in dev it mints `hub.<place>.<random>` and
|
|
193
|
+
tells each client to join that named session. Where the host has hub ops
|
|
194
|
+
(`session.hub`, a session ghost pinned to a hub place) it fires the door's pad
|
|
195
|
+
(`hubPadUpdate`, with the group `hub.pad` gathered): ghost fixes the group and
|
|
196
|
+
the instance, a late join included by the door's own `lateJoin`, and each member
|
|
197
|
+
is told to go through (`hub-go` with `pad` and no `key`). `instance` is ignored
|
|
198
|
+
there; the return value is the pad's id. Doors in dev are `HubDoor` scene actors
|
|
199
|
+
(`{ id, to, … }`, `to` a place id, or `deck:<name>` for a deck the town's
|
|
200
|
+
`castle.json` `devDecks` names, with the door's own `title`, `minPlayers`,
|
|
201
|
+
`maxPlayers` and `lateJoin`; other props are the place's own, such as where
|
|
202
|
+
returning players come out); the door table replaces them without a deck
|
|
203
|
+
change. A door faces its local +z, so it may stand in any wall: the trip
|
|
204
|
+
swings its leaf about its left edge (as you face it) and films through it along
|
|
205
|
+
its own rotationY. On the dev serve a `deck:<name>` door reads those four from the
|
|
206
|
+
destination's own `castle.json` (the serve hands the server each `devDecks`
|
|
207
|
+
deck's castle.json as `import.meta.env.CASTLE_DEV_DECKS`), and the check
|
|
208
|
+
refuses a door whose props disagree with it, so the published town cannot
|
|
209
|
+
drift from what dev played (v1.1). A place keeps its own record of the instances it launched until ghost
|
|
210
|
+
presence can say who is inside.
|
|
211
|
+
|
|
212
|
+
**Cabinets (v1.7).** A door may lead to a classic Castle deck (a Scene Creator
|
|
213
|
+
deck, which is not a hub game and is not changed): an arcade cabinet. The host
|
|
214
|
+
plays the deck itself, over the place, under the hub's cover and with the hub's
|
|
215
|
+
Back; nothing is reported and nothing is granted. Web hosts only.
|
|
216
|
+
|
|
217
|
+
- A cabinet is a `HubDoor` actor whose board from ghost carries `classic`
|
|
218
|
+
(`hub.board(door.id).classic`: `{ deckId, title, label, daily, better, cover,
|
|
219
|
+
top: [{ username, score, photo, frame }] }`, `score` already words, the
|
|
220
|
+
pictures data URIs or null). `hub.doors()` says `classic: true` for it, false
|
|
221
|
+
until the board is read, and the door takes its title from the board like
|
|
222
|
+
any door to another deck; a classic deck its creator never titled reads as
|
|
223
|
+
Castle's placeholder (`deck-` and four characters), which is no title, so
|
|
224
|
+
the door keeps its own (`HubDoor.title`), on its card too. A place marks the actor `"kind": "cabinet"` in its
|
|
225
|
+
`HubDoor` (with any `to` of the `deck:<name>` form, such as `deck:classic`):
|
|
226
|
+
such a door does not swing (the trip's camera goes up to it instead), is not
|
|
227
|
+
in the Doors list (§5), and has no pad with ghost, so `hub.pad` on it tells
|
|
228
|
+
ghost nothing.
|
|
229
|
+
- `hub.go(doorId, [playerId])` on a classic door fires no pad (ghost would
|
|
230
|
+
refuse: it is not a pad door) and places no session. Each player named is
|
|
231
|
+
told to go, each alone (`hub-go` with `classic: true`, §12); where the host
|
|
232
|
+
runs the hub only signed-in players go. It returns the door id, or null when
|
|
233
|
+
nobody went. A door that stayed shut for a player is not tried again until
|
|
234
|
+
they step off its pad, as for any door (`hub.pad` still says who stands
|
|
235
|
+
there).
|
|
236
|
+
- The trip (the client, §5): the door-open beat and the cover, then the player
|
|
237
|
+
leaves the place's session and waits under the cover until Back.
|
|
238
|
+
- The card. The kit's server sends a cabinet's card -- title, label, cover,
|
|
239
|
+
and up to five rows of photo, frame, username and score -- to each player
|
|
240
|
+
who comes within 14 m of it, once per version of the card, and the hub
|
|
241
|
+
chrome draws the card of the cabinet a player stands nearest (within 5 m)
|
|
242
|
+
over it, small: a chip with the best score and that player's photo in a
|
|
243
|
+
circle, the frame over it, a little larger. A tap on the chip opens the
|
|
244
|
+
whole board (cover, title, label, every row) and a tap on the board, or
|
|
245
|
+
walking away, closes it; a cabinet with no score draws no chip. A place
|
|
246
|
+
draws none of it and ships no client code for it. The size rules are in §12.
|
|
247
|
+
- On the dev serve there is no ghost, so no board: a cabinet is inert, and a
|
|
248
|
+
place says so on its label. `{ k: 'hub-dev-classic' }` (§12), honoured only
|
|
249
|
+
by a dev session, gives every cabinet door a stand-in board so the card and
|
|
250
|
+
the trip can be exercised; its trip is told `dev` and asks no host.
|
|
251
|
+
|
|
252
|
+
**Layer doors (v1.11).** A door may lead to a place ghost puts on public
|
|
253
|
+
layers, as it does a town, rather than in an instance per pad: a village, a
|
|
254
|
+
district, another town (the door row's placement is `layer`). A place marks
|
|
255
|
+
the actor `"kind": "layer"` in its `HubDoor`. Ghost holds no pad for such a
|
|
256
|
+
door, so `hub.pad` on it tells ghost nothing, and `hub.go(doorId, playerIds)`
|
|
257
|
+
fires none: each signed-in player named is told to go (`hub-go` with no `key`
|
|
258
|
+
and no `pad`), their client asks the host (`Hub.go`), and ghost steers them to
|
|
259
|
+
a layer of the destination with their party and friends. It returns the door
|
|
260
|
+
id, or null when nobody went. Only a public layer of a deck's main place has
|
|
261
|
+
that place's minds (§13), so a place whose NPCs have minds is reached by a
|
|
262
|
+
layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
263
|
+
|
|
264
|
+
## 5. Arrival and exit
|
|
265
|
+
|
|
266
|
+
- Players sent together by one `hub.go` arrive together: the kit holds a group's
|
|
267
|
+
first arrival still, up to 1.5 s, for the rest, places them in a row at
|
|
268
|
+
`arrival.actor` spaced by `arrival.spread`, and calls `arrive` once with all
|
|
269
|
+
of them. Their way back says the same group size (the hello's `party`, kept
|
|
270
|
+
on the return ticket), so they come back out together; one who stayed
|
|
271
|
+
behind costs the rest at most that 1.5 s.
|
|
272
|
+
- **Arrival facing is contract data**, not scene metadata (M0 gap 9): the body
|
|
273
|
+
faces `arrival.face`, and the client's camera starts behind it.
|
|
274
|
+
- A late joiner arrives the same way, alone.
|
|
275
|
+
- **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
|
|
276
|
+
button lists the place's doors; Go puts the player on that door's pad (the
|
|
277
|
+
`HubPad` actor naming it, v1.10: within 0.9 m of its middle, so the pad
|
|
278
|
+
counts them), facing the door, or 7 m in front of a door with no pad, in the
|
|
279
|
+
door's own frame (at most once a second; never a held player). It is a walk, not a trip: the player stays in this session. A game
|
|
280
|
+
has no list.
|
|
281
|
+
- **Where a player came from** is ghost's arrival where the host has hub ops
|
|
282
|
+
(the door row the player was placed by, `fromDeckId` and `doorId`); the
|
|
283
|
+
client's hello names it only in dev.
|
|
284
|
+
- **A production trip** (a `hub-go` with `pad` and no `key`) is the host's: the
|
|
285
|
+
client asks `Hub.go(door)`, loads the content pack the handoff names under the
|
|
286
|
+
cover (`bundleHash`, `contentUrl`; content-pack.md) and joins with
|
|
287
|
+
`Multiplayer.join({ mode: "hub", handoff })`. A refusal, a handoff without a
|
|
288
|
+
pack, or a pack that fails keeps the door shut and gives the acquisition back
|
|
289
|
+
(`Hub.cancel`). The way back is `Hub.back()`; the host's own Back control is
|
|
290
|
+
answered the same way (`Hub.onBack`), and while the host's trail holds a hub
|
|
291
|
+
trip the kit does not draw its own Back, since the host draws one. Nothing of
|
|
292
|
+
the destination is mounted until the host commits the join
|
|
293
|
+
(`multiplayer.joinState()`); a join it does not commit leaves the player's
|
|
294
|
+
place as it was: a door's trip rejoins the session it left when that is not
|
|
295
|
+
itself a spent hub join, else leaves by that place's way back, and a way back
|
|
296
|
+
is tried once more. A join the host committed whose session then closes
|
|
297
|
+
before placing the player (a full layer refusing the socket after its
|
|
298
|
+
hello; `joinState()` `'lost'`) is not waited out: at the root of the host's
|
|
299
|
+
trail the runtime's first join is made again into the place already loading,
|
|
300
|
+
anywhere deeper the player leaves by that place's way back, twice at most.
|
|
301
|
+
Acquisitions and `Hub.cancel` run one at a time.
|
|
302
|
+
- **A cabinet's trip (v1.7).** A `hub-go` with `classic` is a hub trip with no
|
|
303
|
+
destination session and no content. The client asks `Hub.go(door)`, which a
|
|
304
|
+
host that can play classic decks answers `{ status: 'ok', kind: 'classic' }`
|
|
305
|
+
once it has committed the trip itself (there is no session to join). The
|
|
306
|
+
trip plays the door-open beat (the camera goes up to the cabinet) and
|
|
307
|
+
covers; on that answer the client leaves the place's session -- the place is
|
|
308
|
+
left, not held -- and waits under its cover, away: no scene swap, no content
|
|
309
|
+
pack, the place's scene as it was. It pushes the same way back a door's trip
|
|
310
|
+
pushes, so Back (the host's control, `Hub.onBack`) is the ordinary
|
|
311
|
+
`Hub.back()` return: a hub join on the handoff into the place, arriving at
|
|
312
|
+
the cabinet's door. While away nothing else runs: no friends asked, no
|
|
313
|
+
trips, no talk, no idle play. Anything but that answer keeps the door shut
|
|
314
|
+
as for any door: a refusal or `unavailable`, a host with no doors, and a
|
|
315
|
+
host from before cabinets, whose ordinary handoff is given back
|
|
316
|
+
(`Hub.cancel`). The cover waits up to 40 s for the host (its own limit on
|
|
317
|
+
`Hub.go` is 30 s); should the host answer after that, the client follows it
|
|
318
|
+
and goes away then. A way back that cannot be made (refused, or not
|
|
319
|
+
committed after one more try) leaves the player away, to press Back again,
|
|
320
|
+
since the host is still showing the deck.
|
|
321
|
+
- **Finding a friend (v1.9).** In a town (a place that declares no `result`)
|
|
322
|
+
the chrome's People button lists everyone here, the player's friends first.
|
|
323
|
+
A friend is someone the host's `Hub.friends` names (so only a production hub
|
|
324
|
+
place has any; on a page served from localhost `?hubFriends=all` makes
|
|
325
|
+
everyone one). Every row has where that player is under their name; a
|
|
326
|
+
friend's has Join, anyone else's Find, and anyone standing on a door's pad
|
|
327
|
+
or beside a door has Go there (a jump to that door's pad, as Doors > Go). Where is the place server's word (`hub-where`, §12): "on the
|
|
328
|
+
<door> pad" for a `HubPad` actor's circle, "near <door>" within 7 m of a
|
|
329
|
+
door, else the place's `where` hook (§4), else "in town". Join
|
|
330
|
+
(`hub-goto`) puts the player beside that friend, facing them, as a jump to a
|
|
331
|
+
door does: a town only, at most once a second, never a held player, never
|
|
332
|
+
across a block; a sitter stands first. The server does not know who is whose
|
|
333
|
+
friend, so it moves a player beside any player of the session they may see;
|
|
334
|
+
only the chrome's list limits Join to friends. Find moves nobody: it puts
|
|
335
|
+
the pointer on that player (Stop takes it off), so anyone can be walked to
|
|
336
|
+
by name. A friend, or a found player, more than 12 m off (past where names
|
|
337
|
+
are drawn) gets a small pointer: a chip over them with
|
|
338
|
+
their name and distance, or at the screen's edge with an arrow when they are
|
|
339
|
+
out of view, three at most. A friend the host names who is not in this
|
|
340
|
+
session is listed too: "in another part of town" (another layer; Join is the
|
|
341
|
+
jump below), or, on a host that says which door's game they are in
|
|
342
|
+
(`door` on a `Hub.friends` row), "inside <door>" (Join is a jump to that
|
|
343
|
+
door). A game lists only who may be reported, as before.
|
|
344
|
+
- **Starting next to a friend (v1.12).** A player who walks into a town (no
|
|
345
|
+
door, no jump) and finds a party member or a friend in the same layer is put
|
|
346
|
+
beside them, once: the client asks the place (`hub-goto`) for a party member
|
|
347
|
+
first, else the first friend here in the host's order, as soon as the host
|
|
348
|
+
has named its friends, within 12 s of arriving and only while the player is
|
|
349
|
+
still within 4 m of where they came in; the toast says whom ("You're next to
|
|
350
|
+
amy"). Which layer a player lands in is ghost's pick (the party's layer,
|
|
351
|
+
then a friend's, then the fullest with room), so a friend in a full layer is
|
|
352
|
+
not started beside; they are in the People list with Join. A friend inside a
|
|
353
|
+
game behind one of the town's doors (a host that names the door) is told of
|
|
354
|
+
in a toast, with Join in the People list. Nothing happens for a player with
|
|
355
|
+
no friend here, or on a host without `Hub.friends`.
|
|
356
|
+
- **Parties (v1.10).** In a town, players may go about as a party of up to
|
|
357
|
+
eight. Invite is on a player's row in the People list and on a small button
|
|
358
|
+
once the player has stood within 2.2 m of someone for 1.5 s (offered for 8 s, never over an open card or list); the invited player is asked ("ada
|
|
359
|
+
invited you to their party": Join party / No thanks; one invitation waits on
|
|
360
|
+
a player at a time, for 60 s) and on yes joins the inviter's party, leaving
|
|
361
|
+
any other. Party members are first in the People list, with Join (beside
|
|
362
|
+
them) and a pointer like a friend's, and the list has Leave party. In a
|
|
363
|
+
party, Doors > Go reads "Go together": the member who picks a door is put on
|
|
364
|
+
its pad and every other member here is asked ("ada: let's play Foot Race":
|
|
365
|
+
Go / Not now, for 45 s); each who says Go is put on the pad too, on a spot
|
|
366
|
+
of their own. Nothing else about a door changes: the pad counts who stands
|
|
367
|
+
on it and fires as it always did, and `hub.coming(door)` tells the place how
|
|
368
|
+
many answers are outstanding so it can hold the countdown (a party's
|
|
369
|
+
proposals count there for at most 20 s in any minute, and an answer names
|
|
370
|
+
the invitation or proposal it answers, so it cannot land on a later one). A party is the
|
|
371
|
+
place's own (ghost's parties and the host's `partyId` are not involved) and
|
|
372
|
+
lasts while its layer does: a signed-in member away through a door is kept
|
|
373
|
+
for 30 minutes and is in the party again on return, a guest only while
|
|
374
|
+
here, and a party down to one member ends. No invitation crosses a block,
|
|
375
|
+
and a member a block hides from another is not named to them. A player's
|
|
376
|
+
party messages are limited to a burst of six, then one a second. A game has
|
|
377
|
+
no parties.
|
|
378
|
+
- **Joining a friend in another layer** (where the host has `Hub.friends`, i.e.
|
|
379
|
+
a production hub place): a town asks the host every 20 s which of the
|
|
380
|
+
player's mutual friends are in it or in another layer of it; the ones
|
|
381
|
+
elsewhere are in the People list with Join. Join is `Hub.jump(userId)`: a production trip
|
|
382
|
+
as above to the same place in the friend's session, with no door, no return
|
|
383
|
+
ticket and no step on the host's trail, so the way back is unchanged. The
|
|
384
|
+
content is the place's held release when the handoff names it, else the pack
|
|
385
|
+
the handoff names. The player arrives at `arrival` like any arrival with no
|
|
386
|
+
door (`from` is null), not next to the friend. A jump the host refuses stays
|
|
387
|
+
put; one it does not commit rejoins the session it left when that can be
|
|
388
|
+
joined again, else leaves by the place's way back. A host that answers
|
|
389
|
+
`unavailable` or does not know the command is not asked again.
|
|
390
|
+
- **Falling (v1.1).** A scene can have no ground at all (`"ground": { "none":
|
|
391
|
+
true }` at the scene file's top level, which the engine and the server both
|
|
392
|
+
read): a pit, lava, islands in the sky. A place whose players can fall
|
|
393
|
+
declares `fallY` (or gets -20 in a scene with no ground): a player whose body
|
|
394
|
+
drops below it is handed to the game's `fall(hub, playerId)` hook, and if
|
|
395
|
+
they are still down there afterwards the kit puts them back at the arrival.
|
|
396
|
+
A held player is not caught (the game holds whom it has already dealt
|
|
397
|
+
with). The hub client stops its own player's fall a metre under `fallY`
|
|
398
|
+
(the snapshot's `hubPlace.fallY`), since the server reads no pose below the
|
|
399
|
+
world's floor (-30 m) and a report that skipped past it would never be
|
|
400
|
+
caught. `fallY` must sit below everywhere a player stands, or the arrival
|
|
401
|
+
itself counts as fallen.
|
|
402
|
+
- **Exit** is always through the door the player came in by: the hub-drawn Back
|
|
403
|
+
control, `hub.end`, `maxDurationSec`, a crash or a republish. The game cannot
|
|
404
|
+
name the destination; the client's return ticket does (ghost's, once it
|
|
405
|
+
exists). Returning players come out at that door, facing the square.
|
|
406
|
+
|
|
407
|
+
## 6. Controller presets
|
|
408
|
+
|
|
409
|
+
| preset | what | status |
|
|
410
|
+
| --- | --- | --- |
|
|
411
|
+
| `walk` | physics-3d's `Player`: tank-style walk/turn, drag-stick on touch, jump, follow camera; client-predicted, server-clamped | v1 |
|
|
412
|
+
| `vehicle`, `fixed-camera` | reserved names | refused until built |
|
|
413
|
+
|
|
414
|
+
A game chooses a preset; it does not extend one (HUB.md open question 6 stays
|
|
415
|
+
open for v2). The scene's `Player` actor is the spawn and the preset's tuning
|
|
416
|
+
(`camDistance`, `camHeight`, speed props the behavior already has).
|
|
417
|
+
|
|
418
|
+
**Tuning one player (v1.2).** `hub.tune(playerId, { speed, jump })` changes
|
|
419
|
+
one player's own controller: their walk speed and jump, as multipliers of the
|
|
420
|
+
preset's (the scene Player's `speed` and `jumpSpeed`), for the +1 games where
|
|
421
|
+
a stat makes you faster. `speed` is clamped to 0.25-3 and `jump` to 0.5-2.5;
|
|
422
|
+
either may be left out (1); `null` (or both 1) puts the preset back. Only that
|
|
423
|
+
player's client is told (`hub-tune`), and the server's movement clamp for that
|
|
424
|
+
player follows the larger multiplier, so a tuned player is not pulled back
|
|
425
|
+
while everyone else keeps the place's limit. It needs multiplayer-3d from
|
|
426
|
+
2026-10-03 or later, whose clamp reads a player's own limit; on an older one a
|
|
427
|
+
player tuned past twice the preset is pulled back. A tune lasts the visit and
|
|
428
|
+
goes with the player.
|
|
429
|
+
|
|
430
|
+
**Grabbing and throwing (v1.3).** A place with `grab` in its manifest lets
|
|
431
|
+
players pick up its loose objects -- scene actors whose `Body` is `"dynamic"`
|
|
432
|
+
-- and throw them. The hub draws a Grab button (bottom right; E or F on a
|
|
433
|
+
keyboard) whenever such an object is within about 1.6 m in front of the
|
|
434
|
+
player, and it holds it: `holdDistance` in front of the player (never so close
|
|
435
|
+
it touches them) and `holdHeight` above their feet, following them as they
|
|
436
|
+
walk and turn. The button becomes Throw, which lets go along the way the
|
|
437
|
+
player faces at `throwSpeed`, a quarter of that upward. One object at a time;
|
|
438
|
+
never a player (other players are not scene objects).
|
|
439
|
+
|
|
440
|
+
What can be grabbed is what multiplayer-3d already hands this client to
|
|
441
|
+
simulate: a loose object nearest this player within its reach. A held object
|
|
442
|
+
stays in reach, so the client stays its owner, and its poses are reported and
|
|
443
|
+
checked by the server exactly as any owned object's are: an owner's report
|
|
444
|
+
may move an object at most 40 m/s (multiplayer-3d `MAX_OBJECT_SPEED`), and a
|
|
445
|
+
report past that hands the object back to the server. `throwSpeed`'s top,
|
|
446
|
+
14 m/s, sits well inside that, so no throw is cut short by it. Once a thrown
|
|
447
|
+
object leaves the thrower's reach the server simulates it; the kit lets it fly
|
|
448
|
+
for up to 3 s, or until it slows to 4 m/s, before the server's cap on how fast
|
|
449
|
+
a player's shove may send an object applies again. The flight is the server's
|
|
450
|
+
to bound: a thrown object in the server's hands never goes faster than the
|
|
451
|
+
place's `throwSpeed` (and a tenth more), whatever the thrower reported,
|
|
452
|
+
checked after every physics step (multiplayer-3d's per-object `speedCap`; with
|
|
453
|
+
an older multiplayer-3d a throw is held to a shove's 4 m/s once the server has
|
|
454
|
+
it).
|
|
455
|
+
|
|
456
|
+
The place hears every grab and throw (the `grab` hook, §4) and may refuse a
|
|
457
|
+
grab: the player lets go at once. The server also refuses one by itself when
|
|
458
|
+
the object is not a loose object of the place, is hidden, is not that
|
|
459
|
+
player's to simulate, or is more than 4 m from them, or when the player is
|
|
460
|
+
held (§8) or has not arrived; a player's grab and throw messages are limited to
|
|
461
|
+
4 a second. A hold also ends when the place hides the object, when the
|
|
462
|
+
multiplayer kit hands it to someone else, when the player is held, on a trip
|
|
463
|
+
and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
|
|
464
|
+
whistle): the object falls where it is. A place without `grab` draws no button
|
|
465
|
+
and is sent exactly what it was.
|
|
466
|
+
|
|
467
|
+
A refusal and `hub.drop` bind the hub client, which is the only client a hub
|
|
468
|
+
place has; they do not take the object from its owner on the server. A
|
|
469
|
+
modified client can carry a loose object it owns whatever the place says,
|
|
470
|
+
exactly as it can push one in any multiplayer-3d deck today, so an object the
|
|
471
|
+
place must keep out of players' hands is made kinematic (moved by `hub.move`),
|
|
472
|
+
not merely refused.
|
|
473
|
+
|
|
474
|
+
**Idle play (v1.6).** A place with `idle` in its manifest gives players
|
|
475
|
+
something to do while they wait or hang out, still without client code: the
|
|
476
|
+
hub draws an emote picker, Sit and Stand, and the place's sounds. A place
|
|
477
|
+
without it draws nothing new and is sent exactly what it was.
|
|
478
|
+
|
|
479
|
+
- **Emotes** (`idle.emotes`). An emote button (☺, bottom right, above Grab)
|
|
480
|
+
opens the kit's emotes: `wave` 👋 (a side-to-side sway, 2 s), `dance` 💃
|
|
481
|
+
(bounce, sway and twist, 2.4 s), `cheer` 🎉 (three hops, 1.6 s), `bow` 🙇 (a
|
|
482
|
+
bow forward, 1.6 s) and `spin` 🌀 (a full turn, 1.2 s). Everyone sees it on
|
|
483
|
+
that player's avatar, with the emoji rising over their head. It is drawn
|
|
484
|
+
only: the avatar's model moves inside its drawn node, never its body, its
|
|
485
|
+
network pose or what anyone simulates. The server takes one emote per
|
|
486
|
+
player every 2 s, refuses an id the kit does not have and a player who has
|
|
487
|
+
not arrived, and asks the place's `emote` hook, which may refuse it.
|
|
488
|
+
`hub.emote(playerId, id)` plays one on a player from the place itself (an
|
|
489
|
+
NPC's greeting, a goal) and is neither rate-limited nor offered to the hook.
|
|
490
|
+
- **Seats** (`idle.seats`). A scene actor carrying `HubSeat` (`{ face,
|
|
491
|
+
height }`, both optional) is a seat. A seat stays where it was authored: one
|
|
492
|
+
with a `"dynamic"` or `"kinematic"` `Body` is refused by the check and
|
|
493
|
+
ignored by the hub. A player standing within about 1.5 m of
|
|
494
|
+
a free one is offered Sit (bottom centre). The server checks the seat is one,
|
|
495
|
+
shown and free (one player per seat), the player is here, not held by the
|
|
496
|
+
place and within 2.5 m, and asks the place's `sit` hook; then it holds them
|
|
497
|
+
on the seat (§8): over its centre, `height` metres above its Transform
|
|
498
|
+
(default: the top of its Shape plus a standing body's 0.85 m, so a sitter on
|
|
499
|
+
a solid seat rests on it), facing `face` degrees (default the seat's own
|
|
500
|
+
`rotationY`). Everyone draws a sitter lowered 0.45 m and tipped back a
|
|
501
|
+
little. Stand, any walk, turn or jump input (a tap on touch included), or a
|
|
502
|
+
jump to a door gets them up where they are. A seat is a hold: a held player cannot sit, and the
|
|
503
|
+
place's own `hub.hold` or `hub.release` of a sitter, a game's end, leaving,
|
|
504
|
+
or the place hiding the seat stands them. `hub.seat(playerId)` says where a
|
|
505
|
+
player sits. Sit and Stand are limited to 3 a second per player.
|
|
506
|
+
- **Sounds** (`idle.sounds`). `hub.sound(actorId, file, { loop, volume,
|
|
507
|
+
radius })` plays one of the files the place lists at a scene actor (or a
|
|
508
|
+
spawned copy) for everyone, its volume falling off in a straight line to
|
|
509
|
+
nothing `radius` metres away from the listening player. At most 4 loops at
|
|
510
|
+
once in a place (`hub.sound(actorId, null)` stops one; another sound at the
|
|
511
|
+
same actor, a one-shot included, replaces it) and 4 one-shots a second (a burst of 8). A player who
|
|
512
|
+
joins hears a loop from where everyone else is in it. Browsers start audio
|
|
513
|
+
only after a gesture: a loop waits for the player's first tap or key, and a
|
|
514
|
+
one-shot that cannot play then is dropped. The files are the deck's own:
|
|
515
|
+
bundled into its page where the deck runs as itself (a town), and carried in
|
|
516
|
+
its content pack's `audio` (`docs/content-pack.md`), so a game reached
|
|
517
|
+
through a door sounds too, on a town whose engine is this kit or later. A
|
|
518
|
+
town on an older engine ignores `audio` and the game is silent there. A
|
|
519
|
+
place plays only its own content's files, never a same-named file of the
|
|
520
|
+
town's.
|
|
521
|
+
|
|
522
|
+
**Quick reactions and phrases (v1.11).** In every hub place the chrome has a
|
|
523
|
+
speech button (💬, bottom right, above the emote button) that opens a row of
|
|
524
|
+
emoji (👍 😂 ❤️ 😮 👋 🎉) over the place's canned phrases: in a town "Over
|
|
525
|
+
here!", "Let's play…", "Wait for me", "Yes!", "Not now"; in a game "Over
|
|
526
|
+
here!", "Wait for me", "Yes!", "Not now", "Good game!", "Again?", "Back to
|
|
527
|
+
town?". A pick is `{ k: 'hub-say', r }` (a reaction, by index) or `{ k:
|
|
528
|
+
'hub-say', p }` (a phrase, by id); the server carries no text, refuses
|
|
529
|
+
anything else, limits a player to a burst of three and then one every 1.5 s,
|
|
530
|
+
and tells everyone here a block does not hide the speaker from (`hub-said`).
|
|
531
|
+
"Let's play…" names the door the speaker stands within 12 m of ("Let's play
|
|
532
|
+
Tile Fall"), else "Let's play something". Each client words what was said
|
|
533
|
+
itself: a bubble over the speaker for 4 s (the emoji, or the line), and for a
|
|
534
|
+
phrase a line in a small feed above the dock for 9 s, three at most. "Over
|
|
535
|
+
here!" from a party member or a friend puts the pointer (§5) on them for
|
|
536
|
+
10 s, and a "Let's play" that names a door is offered to everyone who heard it
|
|
537
|
+
as a question for 20 s ("bo: let's play Tile Fall": Go / Not now), Go being a
|
|
538
|
+
jump to that door's pad. This is for everyone, guests included; nothing a player types is
|
|
539
|
+
carried. No place opts in or out, and no hook hears it.
|
|
540
|
+
|
|
541
|
+
**Free-text chat (v1.12).** Two players may type to each other only when
|
|
542
|
+
they follow each other on Castle and both are over 13; a guest, or a player
|
|
543
|
+
whose age Castle does not know, has no chat. That rule is ghost's and ghost
|
|
544
|
+
enforces it; neither the kit nor a place's server is trusted with it or
|
|
545
|
+
carries a word of it. Where the host has the commands (`Hub.chat`, `Hub.say`,
|
|
546
|
+
`Hub.reportChat`; a web host from 2026-10-03), the kit asks the host every
|
|
547
|
+
2.5 s (every 15 s while nobody here can be chatted with) what this player may
|
|
548
|
+
read and whom their words would reach, and the speech card gains a line and a
|
|
549
|
+
field: "Chat reaches bo, amy" over a Message field, or "Follow each other to
|
|
550
|
+
chat" and no field, which is all a player is ever told about why (never
|
|
551
|
+
another player's age). A sent line goes through the host to ghost, which
|
|
552
|
+
filters it as classic party chat is filtered and hands it only to the players
|
|
553
|
+
here who pass the rule with the sender, so in a group each player reads only
|
|
554
|
+
the lines of the players they follow who follow them back. A line is drawn
|
|
555
|
+
like a phrase: over its speaker for 6 s and in the feed; a tap on another
|
|
556
|
+
player's line in the feed offers Report (`Hub.reportChat`). What was said
|
|
557
|
+
before a player arrived is not shown to them. On a host or SDK without the
|
|
558
|
+
commands nothing is drawn and nothing is asked. A deck changes nothing.
|
|
559
|
+
|
|
560
|
+
**Player contact is not in v1.** Other players are kinematic capsules on every
|
|
561
|
+
client, so nobody can be shoved (M0 gap 4). That is an engine rule, not a
|
|
562
|
+
contract field; a game that needs it waits for it.
|
|
563
|
+
|
|
564
|
+
## 7. Results
|
|
565
|
+
|
|
566
|
+
```js
|
|
567
|
+
hub.result(playerId, { outcome: 'win', score: 16900, stats: { laps: 3 } });
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
- Server only, at most once per player per visit; a second call is refused and
|
|
571
|
+
logged.
|
|
572
|
+
- **The outcome may be left out (v1.1)** where the score says it all: a solo
|
|
573
|
+
time trial's time, a co-op run's time. Such a result carries a `score` (a
|
|
574
|
+
result with neither is refused); the town words it as the title and the
|
|
575
|
+
score (`"Summit Sprint: 42.1 s"`), ghost records it without touching the
|
|
576
|
+
win streak, and the board ranks it like any other.
|
|
577
|
+
- Validated against `result`: `outcome`, when given, must be one of `outcomes`; `score` a
|
|
578
|
+
finite number inside `[min, max]` when `score` is declared, absent otherwise;
|
|
579
|
+
`stats` only declared keys, numbers finite, strings ≤ 40 chars. No free text:
|
|
580
|
+
the town writes every word the player sees (`"Foot Race: win · 16.9 s"`), from
|
|
581
|
+
`title`, `outcome` and `score.unit`.
|
|
582
|
+
- `score.unit`: `"ms"`, `"s"` or `"points"`; `better`: `"higher"` or `"lower"`.
|
|
583
|
+
- Where it goes: to the host's `hubResult` op where the host has hub ops
|
|
584
|
+
(`session.hub.reportResult`: validated again against the shape published with
|
|
585
|
+
the server bundle, one per player per visit, rate-limited, recorded by ghost
|
|
586
|
+
for a signed-in player behind a curated door), and to the player's own client
|
|
587
|
+
for display.
|
|
588
|
+
- What a town sees: where the host has hub ops, the kit reads ghost's record of
|
|
589
|
+
each arriving player (`hubResultsRead`) and hands the newest result from the
|
|
590
|
+
deck they came from to `arrive` as `carry.result` (`verified: true`), and sends
|
|
591
|
+
it to that player's client for the ribbon. The client's own carried copy is
|
|
592
|
+
read only in dev, as unverified display; nothing of value may be granted from
|
|
593
|
+
it.
|
|
594
|
+
- A player who leaves without one has no result for that visit.
|
|
595
|
+
- **Reading a player's results (v1.5).** `hub.results(playerId)` hands deck
|
|
596
|
+
code what ghost holds of a signed-in player: `recent`, their newest results
|
|
597
|
+
in any hub place (`{ deckId, place, title, outcome, score, unit, better,
|
|
598
|
+
stats, at }`), and `records`, one per place they have played (`{ deckId,
|
|
599
|
+
place, title, plays, outcomes: { win, lose, draw }, bestScore, unit, better,
|
|
600
|
+
winStreak, lastOutcome, lastScore, lastAt }`), each list at most 20, with
|
|
601
|
+
`readAt`. The kit reads it with the arrival read and again once a minute for
|
|
602
|
+
everyone here (one read for up to 24 players), so a place never calls the
|
|
603
|
+
host's results read itself. A copy: changing it changes nothing. Null on the
|
|
604
|
+
dev serve, for an anonymous player, and until the first read lands.
|
|
605
|
+
|
|
606
|
+
## 8. Holding a player still
|
|
607
|
+
|
|
608
|
+
`hub.hold(playerId, at?, facingDeg?)` pins a body at `at` (default: where it
|
|
609
|
+
is) until `hub.release`. The kit re-clamps every tick the client drifts, and the
|
|
610
|
+
held list rides in the delta so the hub client stops reading input instead of
|
|
611
|
+
fighting the clamp (M0 gap 3: a clamp was sent only when the pose changed). A
|
|
612
|
+
race's countdown line: `hold` on arrival, `release` at "go". A seat (v1.6, §6)
|
|
613
|
+
is a hold too: the place's `hold` replaces it and its `release` ends it, which
|
|
614
|
+
stands the sitter.
|
|
615
|
+
|
|
616
|
+
## 9. The HUD vocabulary
|
|
617
|
+
|
|
618
|
+
The only way a Tier 0 game puts words on screen (M0 gap 1). Drawn by the hub
|
|
619
|
+
chrome, never the game:
|
|
620
|
+
|
|
621
|
+
```js
|
|
622
|
+
hub.setHud({ title: 'Foot Race', big: '3', text: 'get ready', timer: { since: hub.now } });
|
|
623
|
+
hub.setHud(null); // nothing
|
|
624
|
+
hub.setHud({ text: 'you are it!' }, playerId); // one player's override; null clears it
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
| field | rule |
|
|
628
|
+
| --- | --- |
|
|
629
|
+
| `title` | ≤ 40 chars, small caps across the top |
|
|
630
|
+
| `big` | ≤ 12 chars, the large line (a countdown digit, "FINISH") |
|
|
631
|
+
| `text` | ≤ 120 chars, one line under it |
|
|
632
|
+
| `timer` | `{ since: simMs }` counts up, `{ until: simMs }` counts down; shown in `big` when `big` is absent |
|
|
633
|
+
|
|
634
|
+
Longer strings are cut, other keys dropped. A per-player spec replaces the
|
|
635
|
+
shared one for that player.
|
|
636
|
+
|
|
637
|
+
## 10. Actor visibility
|
|
638
|
+
|
|
639
|
+
`hub.hide(actorId)` removes a scene actor for everyone: its server body is
|
|
640
|
+
disabled now, and every client (including later joiners) removes it.
|
|
641
|
+
`hub.show(actorId)` puts it back as authored. Only actors of the place's scene
|
|
642
|
+
(M0 gap 2: the race's start gate). On the client a hidden actor is moved far
|
|
643
|
+
below the ground with its collider rather than despawned, so it is meant for
|
|
644
|
+
actors that do not move by physics.
|
|
645
|
+
|
|
646
|
+
`hub.label` puts words over a scene actor, drawn by the hub chrome like the
|
|
647
|
+
HUD: a pad's "3 of 6", an NPC's line, the hill's king.
|
|
648
|
+
|
|
649
|
+
**Goals (v1.13).** `hub.label(actorId, text, { style: "goal", to: [playerIds] })`
|
|
650
|
+
is where the place is sending those players: an errand's person, the counter
|
|
651
|
+
to fetch from. The hub chrome draws it as a pointer rather than a label: over
|
|
652
|
+
the actor while it is on screen, else at the screen's edge with an arrow along
|
|
653
|
+
the way to it, with the distance in metres beyond 6 m (the follow camera looks
|
|
654
|
+
down, so a far sign is rarely in view). A goal is one player's own: with no
|
|
655
|
+
`to` it is a `"sign"`. The two nearest are drawn; `null` clears one like any
|
|
656
|
+
label. A town on an engine from before v1.13 draws it as a tag.
|
|
657
|
+
|
|
658
|
+
**Labels in a town.** In a place with no `result` (a town, not a game) the
|
|
659
|
+
client draws a label only when its actor is near the player: the nearest
|
|
660
|
+
plain or `"tag"` label within 4 m and the nearest `"speech"` line within 9 m,
|
|
661
|
+
fading in and out, one of each at a time. A `"sign"` label (a street's or a
|
|
662
|
+
building's name, for finding the way, or a word the player must read from
|
|
663
|
+
where they stand, like the kit's own "Door shut" over a door) is drawn at any
|
|
664
|
+
distance. Other players' names show within
|
|
665
|
+
12 m, smaller than in a game. A town labels everything it has -- every
|
|
666
|
+
statue, board, pad and NPC -- and all of it at once was a wall of text from
|
|
667
|
+
the arrival spot; the words are there when the player walks over. A game
|
|
668
|
+
place draws every label it sets, as before.
|
|
669
|
+
|
|
670
|
+
**Moving an actor (v1.1).** `hub.move(actorId, to, { overMs })` moves a scene
|
|
671
|
+
actor whose `Body` is `"kinematic"`: a moving platform, a sweeper, a gate that
|
|
672
|
+
slides open. `to` is any of `x`, `y`, `z` (metres) and `rotationY` (degrees);
|
|
673
|
+
the fields it leaves out stay where they are. With `overMs` (up to 60000) the
|
|
674
|
+
kit moves it in a straight line, a step each tick, from wherever it is now; a
|
|
675
|
+
later move replaces one under way. The kit drives the server body through its
|
|
676
|
+
kinematic target, so it pushes what it meets the way a door does, and every
|
|
677
|
+
client draws it from the pose the multiplayer kit already sends for kinematic
|
|
678
|
+
bodies. A game that wants a loop or a curve calls `move` again when the last
|
|
679
|
+
one ends (or every step, with no `overMs`). Refused, and logged once: an actor
|
|
680
|
+
that is not a kinematic actor of the place's scene, a number that is not
|
|
681
|
+
finite, a point outside the world box (|x|, |z| ≤ 200, -30 ≤ y ≤ 80), more
|
|
682
|
+
than 64 actors moving at once, and a `rotationY` beyond ±36000 degrees. A
|
|
683
|
+
finished move keeps its turn within one turn, so a sweeper that spins by
|
|
684
|
+
asking for `rotationY + 360` each time never grows. A hidden actor can be
|
|
685
|
+
moved; it stays hidden (the hub client applies visibility after the
|
|
686
|
+
multiplayer kit has written that frame's poses).
|
|
687
|
+
|
|
688
|
+
**Reading and putting back a loose object (v1.3).** A scene actor with a
|
|
689
|
+
dynamic `Body` is a loose object: multiplayer-3d hands it to the client
|
|
690
|
+
nearest it, which simulates it and reports where it is. `hub.pose(actorId)`
|
|
691
|
+
says where any body is as the server has it -- `{ x, y, z, rotationY,
|
|
692
|
+
velocity: { x, y, z }, owner }`, `rotationY` its heading (where its front
|
|
693
|
+
points, on the ground; an upright body's Transform.rotationY), `owner` that
|
|
694
|
+
client's player or null -- and null for an actor without one. `hub.reset(actorId, at)` puts a loose object
|
|
695
|
+
back where the scene authored it (or at `at`, any of `x`, `y`, `z`,
|
|
696
|
+
`rotationY`), at rest. If a client is simulating it, the server takes it back
|
|
697
|
+
first with the multiplayer kit's own handover, so that client stops moving its
|
|
698
|
+
copy and a late report from it is dropped; everyone then sees it where it was
|
|
699
|
+
put, and for half a second nobody may be handed it, so no client starts
|
|
700
|
+
simulating it from where it was. A ball back on the spot after a goal; props that fell off the pitch.
|
|
701
|
+
Refused, and logged once: an actor that is not dynamic (move a kinematic one
|
|
702
|
+
with `hub.move`), a point outside the world box, and more than 20 resets a
|
|
703
|
+
second (bursts of 40). An actor with the engine's `Ball` component is never
|
|
704
|
+
slowed to a shove's speed by the server; give it to an object meant to be
|
|
705
|
+
kicked hard, not to one only walked into.
|
|
706
|
+
|
|
707
|
+
**Spawning a copy (v1.2).** `hub.spawn(fromActorId, at)` copies one of the
|
|
708
|
+
place's scene actors (the template) for everyone, later joiners included, at
|
|
709
|
+
`at` (any of `x`, `y`, `z`, `rotationY`; the rest are the template's), and
|
|
710
|
+
returns the copy's id (`<fromActorId>~<n>`, never reused), or null.
|
|
711
|
+
`hub.despawn(id)` removes a copy. A copy is an actor like any other: move it
|
|
712
|
+
(when its template is kinematic), tint, hide and label it. It is the
|
|
713
|
+
template's components as authored, so a template can be a hidden prototype:
|
|
714
|
+
author one lantern, hide it at `ready`, and place copies where they are
|
|
715
|
+
needed. A copy's marker components come with it, but `actorsWith` lists only
|
|
716
|
+
the scene's own actors. A template has a `Shape` (a `Model` may ride on it);
|
|
717
|
+
not a template: a copy, an actor with a dynamic `Body` or a `Pickup`, a
|
|
718
|
+
`Player`, a `HubDoor`, `HubPad` or `HubNpc`. A copy a behavior removes on one
|
|
719
|
+
client is reported gone like any scene actor and is never re-made there; one
|
|
720
|
+
the place despawns is forgotten by every client, pose history included. Bounded: 96 copies
|
|
721
|
+
alive at once and 10 spawns a second with bursts of 40; past either, `spawn`
|
|
722
|
+
returns null and logs once, and a game tries again later. A copy a client
|
|
723
|
+
reports gone (the multiplayer kit's pickup rule) is gone for the game too.
|
|
724
|
+
|
|
725
|
+
**Recolouring an actor (v1.1).** `hub.tint(actorId, '#rrggbb')` paints a scene
|
|
726
|
+
actor drawn by a `Shape` for everyone, later joiners included; a Shape that
|
|
727
|
+
glows (`emissive`) glows in the new colour. `hub.tint(actorId, null)` puts its
|
|
728
|
+
authored colour back. A held plate turning green, a tile about to fall glowing
|
|
729
|
+
orange. Each client rebuilds a painted mesh, so the place has a budget: 20
|
|
730
|
+
changes a second with bursts of 40 (a change past it waits a tick or so, the
|
|
731
|
+
newest colour winning; repeating the colour an actor already has costs
|
|
732
|
+
nothing), and at most 128 actors painted at once. An actor drawn by a `Model`
|
|
733
|
+
cannot be painted (every client would rebuild the model), nor one with a
|
|
734
|
+
dynamic `Body` (a client rebuilds a body whose Shape changes, stopping it
|
|
735
|
+
dead). A textured face takes the colour as its tint.
|
|
736
|
+
|
|
737
|
+
## 11. The platform avatar seam
|
|
738
|
+
|
|
739
|
+
A hub game never draws a player. The kit draws everyone, the local player
|
|
740
|
+
included, as their **avatar**: an id from the kit's set
|
|
741
|
+
(`imports/castle.hub-game/blueprints/avatar-<id>.scene`, v1: `0`-`3`). The
|
|
742
|
+
client says which in its hello; the server broadcasts every player's choice; a
|
|
743
|
+
change says hello again and respawns that player's body (M0 gap 8). Games never
|
|
744
|
+
see any of it.
|
|
745
|
+
|
|
746
|
+
Where the choice comes from is one function, `Avatar.current()` in the kit's
|
|
747
|
+
client:
|
|
748
|
+
|
|
749
|
+
- **The platform avatar**, one per account, the same in every place (HUB.md
|
|
750
|
+
decision 4). Ghost keeps it (`cauldron_hub_avatars`); the host serves it to
|
|
751
|
+
the kit through the SDK's `Avatar.get()` / `Avatar.set()`, which the hub
|
|
752
|
+
chrome's picker calls. Only a curated hub place (an enabled door leads into
|
|
753
|
+
or out of it) may change it; the host names the place, and anywhere else a
|
|
754
|
+
pick stays the runtime's own. A player who never chose wears a default fixed
|
|
755
|
+
by their user id. Anonymous accounts may choose: a template index carries no
|
|
756
|
+
text to moderate and nothing of value, and an anonymous account keeps its
|
|
757
|
+
user id when it signs up.
|
|
758
|
+
- **A stand-in pick** kept in `scene.persistent`, where there is no platform
|
|
759
|
+
avatar: a signed-out visitor, a host or SDK from before avatars, a deck that
|
|
760
|
+
is not a curated place (the dev serve). It lasts for the runtime, across
|
|
761
|
+
doors.
|
|
762
|
+
|
|
763
|
+
The hello never waits for the avatar: it goes out with what the kit has, and
|
|
764
|
+
says hello again when that changes. Picks are written one at a time; one ghost
|
|
765
|
+
refuses is undone.
|
|
766
|
+
|
|
767
|
+
Ghost also returns every listed player's platform avatar in the host's
|
|
768
|
+
`hubResultsRead` (`players[userId].avatar`), so a place's server can draw
|
|
769
|
+
players as ghost says rather than as their clients claim. Where the host has
|
|
770
|
+
hub ops (`session.hub`) the kit reads it for each player who says hello, and it
|
|
771
|
+
replaces the hello's choice unless a later hello changes it. Elsewhere (the dev
|
|
772
|
+
serve) the server takes each client's hello, which can only change how that
|
|
773
|
+
player looks.
|
|
774
|
+
|
|
775
|
+
**Avatar sets.** The kit has more than one drawing of the four avatars:
|
|
776
|
+
`toon` (the default, `blueprints/avatar-<id>.scene`) and `blocky`, `bean` and
|
|
777
|
+
`pixel` (`blueprints/<style>/avatar-<id>.scene`, models in `models/<style>/`,
|
|
778
|
+
art in `drawings/<style>/`). Which set is drawn is the **viewer's** own:
|
|
779
|
+
`Avatar.style()` in the kit's client reads the platform experiment
|
|
780
|
+
`hub_avatar_style` through the SDK (`experiment`, where the SDK has it; the kit
|
|
781
|
+
calls `experimentsReady` once before the first read and draws toon until the
|
|
782
|
+
host answers), and a viewer in a set sees every player in it, themselves
|
|
783
|
+
included, by the same avatar id. Anything else, an SDK without experiments or
|
|
784
|
+
a set the engine's files do not have, is toon, so nothing changes until an
|
|
785
|
+
experiment assigns a set. On a page served from `localhost` or `127.0.0.1`,
|
|
786
|
+
`?hubStyle=<style>` overrides it. Nothing about the set is on the wire and the
|
|
787
|
+
avatar id means what it did, so this is not a contract change: a game never
|
|
788
|
+
sees it, and the town's engine lays every set over a game's content pack as it
|
|
789
|
+
does toon's. Each model is at most 1,500 triangles and 8 draw calls, with no
|
|
790
|
+
outline pass, and its height is in `avatar.js` for what is worn over it. A
|
|
791
|
+
model in a set names its art through the import
|
|
792
|
+
(`imports/castle.hub-game/drawings/<style>/...`), because the engine looks an
|
|
793
|
+
art ref up as written in the deck's files.
|
|
794
|
+
|
|
795
|
+
**Marking a player (v1.1).** A game cannot touch an avatar, but it can mark
|
|
796
|
+
the player wearing it: `hub.mark(playerId, { text: 'RED', color: '#d1453b' })`
|
|
797
|
+
puts a tag in that colour over the player's avatar, above their name, for
|
|
798
|
+
everyone in the place (the player included, over their own body). `text` is
|
|
799
|
+
up to 16 characters, cut beyond; none draws a dot. `color` is `#rrggbb`, and
|
|
800
|
+
the hub chrome picks black or white words to read on it. One mark per player:
|
|
801
|
+
a second call replaces it, `hub.mark(playerId, null)` clears it, and a player
|
|
802
|
+
who leaves takes theirs with them. Refused, and logged once: a player who is
|
|
803
|
+
not here, or a colour that is not `#rrggbb`. A team colour for Zone Wars, a
|
|
804
|
+
red IT for Tag.
|
|
805
|
+
|
|
806
|
+
**Wearing a game's result (v1.4).** A mark lasts the visit; a **wearable**
|
|
807
|
+
goes with the player. `hub.wear(playerId, { kind: 'aura', color: '#9b5cff',
|
|
808
|
+
rarity: 6 })` puts one on the player's avatar: the kit draws it over the avatar
|
|
809
|
+
for everyone here (the player included, over their own body), and where the
|
|
810
|
+
host runs the hub it goes to ghost, which keeps one per account and hands it
|
|
811
|
+
back to every hub place on the arrival read (`players[userId].wearable` of
|
|
812
|
+
`hubResultsRead`), so the player wears it in the town and in every other game.
|
|
813
|
+
The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
|
|
814
|
+
|
|
815
|
+
- `kind` is a lowercase id (`/^[a-z][a-z0-9-]{0,23}$/`). The kit draws
|
|
816
|
+
`"halo"` (a thin glowing disc over the head), `"aura"` (a glowing disc at the
|
|
817
|
+
feet) and `"orbit"` (small sparks circling the head, one more for every three
|
|
818
|
+
rarity); a kind it does not know is kept but not drawn, so a later kit may
|
|
819
|
+
draw more. `color` is `#rrggbb`; `rarity` an integer 0-9, which grows the
|
|
820
|
+
pieces and their glow a little.
|
|
821
|
+
- Ghost takes a wearable only from a curated hub place (an enabled door leads
|
|
822
|
+
into or out of it, the avatar's rule), only for a signed-in player, and at
|
|
823
|
+
most 30 changes a minute per player; the host checks the shape first.
|
|
824
|
+
Refusals are logged once and change nothing in this place: a guest's
|
|
825
|
+
wearable, and any on the dev serve, lasts the session.
|
|
826
|
+
- A wearable the game puts on wins over an arrival read that began before it,
|
|
827
|
+
as a new avatar choice does. A player who leaves takes theirs with them
|
|
828
|
+
(from this place; ghost keeps it).
|
|
829
|
+
- Refused, and logged once: a player who is not here, or a wearable that is
|
|
830
|
+
not exactly `{ kind, color, rarity }` in range. Nothing reaches ghost.
|
|
831
|
+
|
|
832
|
+
A prize from a roll, a crown for the day's champion: the reason a game is
|
|
833
|
+
worth playing elsewhere.
|
|
834
|
+
|
|
835
|
+
## 12. Wire (kit-internal, listed so a host or bot can speak it)
|
|
836
|
+
|
|
837
|
+
Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per session join
|
|
838
|
+
(and again with `again: true` when only the avatar changed, v1.7);
|
|
839
|
+
`{ k: 'hub-dev-classic', on? }` (v1.7; the dev serve's stand-in for classic boards, §4, ignored by any session that is not a dev one);
|
|
840
|
+
`{ k: 'hub-door-jump', door }` (a town's Doors list, §5);
|
|
841
|
+
`{ k: 'hub-say', r }` or `{ k: 'hub-say', p }` (v1.11, §6);
|
|
842
|
+
`{ k: 'hub-party', op, player?, door? }` (v1.10, §5: `op` `"invite"` with `player`, `"accept"` and `"decline"` with `from` (the inviter), `"leave"`, `"go"` with `door`, `"go-yes"` and `"go-no"` with `id` (the proposal's));
|
|
843
|
+
`{ k: 'hub-where', ids }` (v1.9: where up to 12 players of this session are, at most once per 700 ms) and `{ k: 'hub-goto', player }` (v1.9: Join, §5);
|
|
844
|
+
`{ k: 'hub-grab', actor, op }` (v1.3, `op` `"grab"` or `"throw"`, §6);
|
|
845
|
+
`{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
|
|
846
|
+
`{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text }` (authored mode
|
|
847
|
+
only), `{ k: 'hub-npc-end', npc }` (§13).
|
|
848
|
+
Server → client, in deltas and the WORLD snapshot: `hubPlace` (the place's
|
|
849
|
+
public manifest, with the `fallY` the session catches at, and `grab` (v1.3) only where the place sets it), `hubAv`, `hud`, `hidden`, `held`, `labels`, `tints` (v1.1,
|
|
850
|
+
actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDoors` (a town's `[{ id, title }]`, each with `featured: true`, `solo: true` or `need: n` where they apply (v1.14),
|
|
851
|
+
§5), `spawned` (v1.2, copy id → `{ from, x, y, z, rotationY }`) with
|
|
852
|
+
`spawnTemplates` (each template in use → its authored components), `hubWear`
|
|
853
|
+
(v1.4, player id → `{ kind, color, rarity }`; only once someone in the place
|
|
854
|
+
has worn one, and like `hubAv` without the players in a hidden pair), and in a
|
|
855
|
+
place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
|
|
856
|
+
`{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
|
|
857
|
+
`hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing).
|
|
858
|
+
Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
|
|
859
|
+
a one-shot); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
|
|
860
|
+
client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
|
|
861
|
+
`{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
|
|
862
|
+
`{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
|
|
863
|
+
`{ k: 'hub-party', members, away, invite, proposal }` (v1.10, on change: the other members here as player ids or null for no party, how many are away, `{ from, username }` or null, `{ id, door, by, username, asked }` or null, told only to the proposer and the members asked),
|
|
864
|
+
`{ k: 'hub-where', at }` (v1.9: player id → `{ x, z, where, door, on? }`, the ground spot to 0.1 m, the place's words or null, the door those words name or null, `on` true on its pad), `{ k: 'hub-hud', hud }` (that player's
|
|
865
|
+
override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
|
|
866
|
+
`{ k: 'hub-result', result }`, `{ k: 'hub-end', why }`,
|
|
867
|
+
`{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
|
|
868
|
+
`{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }`,
|
|
869
|
+
`{ k: 'hub-npc-line', npc, text, why }` (`why` v1.8, as `npcLine`'s), `{ k: 'hub-npc-notes', npc, prefix }` (v1.8, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
|
|
870
|
+
hidden pair that this player may see, laid over the shared `hubAv`), `{ k: 'hub-wear', hubWear }`
|
|
871
|
+
(v1.4, their wearables, laid over the shared `hubWear` the same way).
|
|
872
|
+
Version-tagged by `hubPlace.contract`.
|
|
873
|
+
|
|
874
|
+
Blocks: two players a block hides from each other (either one blocked the
|
|
875
|
+
other; the host answers `session.hub.hiddenPair`, and the block lists never
|
|
876
|
+
reach the kit) are taken out of each other's interest sets whatever the
|
|
877
|
+
session's size, so neither is sent the other's pose rows or `in`; the shared
|
|
878
|
+
`hubAv` leaves out every player in such a pair, whose avatars go by `hub-av`
|
|
879
|
+
to each player who may see them. Words can name a player too: the shared `hud`
|
|
880
|
+
and `labels` carry no such player's username (it reads "someone") and no NPC
|
|
881
|
+
line about them, and each player gets the words they may read by `hub-hud` and
|
|
882
|
+
`hub-labels`, so nobody is sent a hidden partner's name, a late joiner's
|
|
883
|
+
WORLD included. An NPC conversation never admits a listener hidden from the
|
|
884
|
+
speaker, and its reply is checked again before it is shown. The host's roster, which
|
|
885
|
+
carries names, is already filtered per recipient. A session with no hidden pair
|
|
886
|
+
is sent exactly what it was.
|
|
887
|
+
|
|
888
|
+
Cabinet cards (v1.7). A card's pictures are data URIs, because a published
|
|
889
|
+
deck's page loads images from nowhere else, so a card is tens of kilobytes
|
|
890
|
+
(ghost keeps a board's `classic` to about 44 KB). The host refuses a frame to
|
|
891
|
+
a client over 64 KB and drops frames for the whole session past its send
|
|
892
|
+
budget (1 MB/s), so a card is never in the WORLD snapshot, a delta or a
|
|
893
|
+
broadcast. It is one `hub-cabinet` message to one player, one card a message,
|
|
894
|
+
sent when that player is within 14 m of the cabinet and does not have this
|
|
895
|
+
version of it; a card that changes goes again only to players in range then,
|
|
896
|
+
and to the others when they next come near. All cards together cost at most
|
|
897
|
+
300 KB a second of the session's budget (180 KB in a burst), so a crowd
|
|
898
|
+
arriving at once is served over the following ticks. A card's frame is at most
|
|
899
|
+
60 KB: over that the kit drops pictures -- frames, then photos, from the
|
|
900
|
+
bottom row up, then the cover -- as ghost does, and a picture that is not an
|
|
901
|
+
image data URI of at most 48 KB is left out; a row without a photo is drawn
|
|
902
|
+
with a placeholder. A client that joins afresh holds no cards and is sent them
|
|
903
|
+
again (its hello has no `again`). A row naming a player a block hides from the
|
|
904
|
+
viewer reads "someone" with no pictures (Blocks, above). The kit reads
|
|
905
|
+
cabinets' boards apart from the other doors', at most six to a read, since a
|
|
906
|
+
read answers in one frame of the host's channel. A place with no cabinet is
|
|
907
|
+
sent, and reads, exactly what it did.
|
|
908
|
+
|
|
909
|
+
Interest: in a session with more than `nearestPlayers` other players, each
|
|
910
|
+
client's `STATE` carries the rows of only the `nearestPlayers` players nearest
|
|
911
|
+
it (a player it already has counts as 20% nearer, so the set does not flicker),
|
|
912
|
+
plus `in` (players it starts being sent, each with its whole current row) and
|
|
913
|
+
`out` (players it stops being sent; the client shrinks their avatar away). The
|
|
914
|
+
WORLD snapshot carries the same set. While the session filters, a client is
|
|
915
|
+
sent other players' rows about 10 times a second (each its newest), its own
|
|
916
|
+
only as a correction, and every row's id as a short number: `idm` (`[[n,
|
|
917
|
+
playerId], ...]`) names each number the first time that client gets it, and
|
|
918
|
+
`pi` (ms) says how far apart the rows are, which the client draws others
|
|
919
|
+
behind by. Everything else -- objects, `hubAv` (but for Blocks, above),
|
|
920
|
+
`hud`, `held`, labels, pads and `hub.go` -- is still everyone's: only
|
|
921
|
+
drawing is filtered, and the server's simulation has every player. A
|
|
922
|
+
session no bigger than the set is sent one broadcast, as before.
|
|
923
|
+
|
|
924
|
+
## 13. NPCs
|
|
925
|
+
|
|
926
|
+
HUB.md decision 7: an NPC's **body** is an actor in the place's session and its
|
|
927
|
+
**mind** is a character in ghost. A body is a scene actor with a kinematic
|
|
928
|
+
`Body` and a `HubNpc` component:
|
|
929
|
+
|
|
930
|
+
```jsonc
|
|
931
|
+
"HubNpc": {
|
|
932
|
+
"name": "Rowan, the greeter", // shown on the Talk button, the panel and before every line
|
|
933
|
+
"character": "greeter", // optional: the castle.json characterBundle character that is its mind
|
|
934
|
+
"follow": "greeterFollow", // optional: the gameplay object whose holder the body follows
|
|
935
|
+
"talkRange": 3.5 // optional, metres (≤ 8)
|
|
936
|
+
// any other keys are the place's own (the town's `role`)
|
|
937
|
+
}
|
|
938
|
+
```
|
|
939
|
+
|
|
940
|
+
**What the kit does with a body.** Near one, a player gets a Talk button (hub
|
|
941
|
+
chrome). Opening a conversation is the place server's decision: one player per
|
|
942
|
+
body at a time; another player gets the place's `busy` line. While a
|
|
943
|
+
conversation is open the body faces its speaker and holds still, through the
|
|
944
|
+
gaps between turns, until the player taps Done, walks more than 8 m away, leaves,
|
|
945
|
+
or says nothing for 90 s. Otherwise it walks where the place sends it, follows,
|
|
946
|
+
or faces what it was told to, in that order. Walking is a straight line at
|
|
947
|
+
2.6 m/s with no navigation: put NPCs where a straight walk crosses nothing solid.
|
|
948
|
+
|
|
949
|
+
```js
|
|
950
|
+
const npc = hub.npc('greeter'); // or hub.npcs()
|
|
951
|
+
npc.say('Welcome!'); // speech over it for everyone; { to: [playerIds] } for some
|
|
952
|
+
npc.face(playerId); // or { x, z }, or null; while idle
|
|
953
|
+
npc.walkTo({ x, z }, { stopAt: 0.4, then: () => … });
|
|
954
|
+
npc.home(then?); // back where the scene put it, facing as it did
|
|
955
|
+
npc.follow(playerId); // or null
|
|
956
|
+
npc.stop(); // no walk, no follow
|
|
957
|
+
npc.end(); // end its conversation
|
|
958
|
+
npc.at; npc.talkingTo; npc.following; npc.walking; npc.busy; npc.props;
|
|
959
|
+
```
|
|
960
|
+
|
|
961
|
+
**Minds.** A place's minds live in a persistent world that carries the deck's
|
|
962
|
+
shared characters (`docs/internal/shared-character-world-v1.md` in
|
|
963
|
+
castle-experimental-web): `npcs.route` names one of `server.destinations`
|
|
964
|
+
with `characters: "shared"` (so `selection: "exact"`, `persistence: "world"`),
|
|
965
|
+
and the deck has a `characterBundle` whose `conversation` is
|
|
966
|
+
`{ "version": 1, "authority": "server", "maxListeners": 0 }` (ghost admits a
|
|
967
|
+
turn's audience only when the place's server, not a client, is the authority on
|
|
968
|
+
it).
|
|
969
|
+
|
|
970
|
+
Minds are on every layer of the main place. A place's characters have one
|
|
971
|
+
memory per place: ghost keeps a single place-mind record for the deck (keyed by
|
|
972
|
+
its published character bundle, so a character change starts a new one), and
|
|
973
|
+
every public layer of the main place addresses those characters by id, so what
|
|
974
|
+
Rowan learns in one layer is known in the others and a player who changes layer
|
|
975
|
+
keeps their history with him. On an SDK with place characters
|
|
976
|
+
(`Multiplayer.placeCharacters`), the main place's client joins a layer like any
|
|
977
|
+
other place, and the place's server reads the characters from
|
|
978
|
+
`session.characters`; whether a layer gets them is ghost's and the host's call
|
|
979
|
+
(the pilot is admin-gated, and an older host gives the layer authored lines).
|
|
980
|
+
The `npcs.route` destination is the fallback for older SDKs: there the main
|
|
981
|
+
place's client joins that route (`slot`, default `"main"`, is the world every
|
|
982
|
+
player of the place shares) and the server reads `session.world.characters`.
|
|
983
|
+
Only the main place either way, since every other place is reached through a
|
|
984
|
+
door that names its own session.
|
|
985
|
+
|
|
986
|
+
| `npcs` field | rule |
|
|
987
|
+
| --- | --- |
|
|
988
|
+
| `route` | optional; a `server.destinations` route with `characters: "shared"`, joined only on SDKs without place characters. Without a route the minds are the place's alone: every layer addresses ghost's one place mind |
|
|
989
|
+
| `slot` | 1-64 of `[A-Za-z0-9_.-]`; default `"main"`; the fallback route's world. A world keeps the character definitions it was created with: after changing the bundle's characters, name a new slot (ghost refuses turns in the old world with `CAULDRON_SHARED_CHARACTER_CONFLICT`) |
|
|
990
|
+
| `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer |
|
|
991
|
+
| `disclosure` | `"participants"` (default) or `"world"`: who a turn's words may reach (below) |
|
|
992
|
+
| `followSec` | 10-600, default 120: how long a body follows before it goes home |
|
|
993
|
+
|
|
994
|
+
Where a session has the place's characters, a player's words are a character turn. The kit admits it only
|
|
995
|
+
for the player the body is talking to, near it, with an audience of players
|
|
996
|
+
near it, within the character's `turnsPerMinute`; anything else is refused
|
|
997
|
+
before a model is called, and over budget the place's `budget` line answers
|
|
998
|
+
instead, so a crowd degrades to authored lines rather than a queue. The reply
|
|
999
|
+
is ghost's text, shown in the speaker's panel and over the body for the turn's
|
|
1000
|
+
audience only: the speaker and the players within 6 m when they spoke (at most
|
|
1001
|
+
seven), as `participants` disclosure; `"world"` also lets the exchange enter
|
|
1002
|
+
the place's public knowledge, which every layer sees. A body follows a player
|
|
1003
|
+
only when its character chose its follow action (an action whose object effect
|
|
1004
|
+
hands the `follow` object to `"player"`); clients cannot start or aim it. The
|
|
1005
|
+
follow object is one per place, so only the body in the holder's layer follows.
|
|
1006
|
+
No other character command reaches a hub place's characters in v1.
|
|
1007
|
+
|
|
1008
|
+
**Notes (v1.8).** A mind knows what its memory and the place's news tell it,
|
|
1009
|
+
not what the place knows this second (a quest-giver's ledger, the pad beside a
|
|
1010
|
+
barker). A place gives it that with `npcContext(hub, npc, playerId)`: the
|
|
1011
|
+
kit reads it for the speaker when a conversation opens and every second while
|
|
1012
|
+
it lasts, and sends the speaker's client `{ k: 'hub-npc-notes', npc, prefix }`
|
|
1013
|
+
when it changed, `prefix` being the notes framed by the kit
|
|
1014
|
+
(`[Notes from the place, ...]` ... `[The speaker says]`). The host forwards a
|
|
1015
|
+
player's words to ghost unaltered (the platform does not let the place's
|
|
1016
|
+
server rewrite a turn), so the client sends `prefix` ahead of the player's
|
|
1017
|
+
words, and the kit admits a turn only when its input starts with notes it
|
|
1018
|
+
issued that player for that body (the newest, or one of the last six within a
|
|
1019
|
+
minute), and the words after them frame no notes of their own; anything else
|
|
1020
|
+
is refused with `HUB_NPC_NOTES` and the client sends once more with the
|
|
1021
|
+
newest. A client can therefore leave its own words, but never the place's
|
|
1022
|
+
notes, out of true. The notes are part of the turn's input: ghost keeps them
|
|
1023
|
+
with the player's words as that player's conversation, so they should be facts
|
|
1024
|
+
about this player and this place, never another player's private state. The
|
|
1025
|
+
player's panel shows only their words. After a turn is admitted the kit calls
|
|
1026
|
+
`npcHeard(hub, npc, playerId, { text })` with the words alone. Without
|
|
1027
|
+
`npcContext` a turn is the words alone, as before.
|
|
1028
|
+
|
|
1029
|
+
Several bodies may share one character (one mind for every barker): a turn
|
|
1030
|
+
goes to the body its speaker is talking to.
|
|
1031
|
+
|
|
1032
|
+
**Authored lines.** Where a body has no mind -- no `npcs`, no `character`, or a
|
|
1033
|
+
session the host brokers no characters into (the dev serve; a host without
|
|
1034
|
+
place characters; on an older SDK, an account the route is not open to; the
|
|
1035
|
+
shared-character pilot is admin-gated) -- conversations still
|
|
1036
|
+
open and the place answers every turn from `npcLine(hub, npc, playerId, { why,
|
|
1037
|
+
text })`, with no model call. `why` is `"hello"` (a conversation opened),
|
|
1038
|
+
`"authored"` (the player said `text`), `"busy"`, `"budget"` or
|
|
1039
|
+
`"unavailable"`. Authored lines are the place's own words and go over the body
|
|
1040
|
+
for everyone. Where a body has a mind, `busy`, `budget` and `unavailable` lines
|
|
1041
|
+
answer in its place: the speaker's panel marks them as scripted (v1.8), and a
|
|
1042
|
+
place should have them acknowledge the player ("give me a moment") rather than
|
|
1043
|
+
answer a question they did not ask.
|
|
1044
|
+
|
|
1045
|
+
What a place's NPCs know of results. A place mind hears **verified** results
|
|
1046
|
+
as world news: ghost writes it from the recorded result row (a win, a new
|
|
1047
|
+
personal best: "Rowan won Foot Race in 1:02.4"), with usernames only and never
|
|
1048
|
+
stats or free text, so what a mind repeats is ghost's record, not a player's
|
|
1049
|
+
claim. Ghost publishes such news only for a player who is over 13, has
|
|
1050
|
+
share-what-I-play on, is not anonymous, and is not suspended, shadowbanned,
|
|
1051
|
+
multiplayer-banned or hub-banned. The news, and anything a mind says from it,
|
|
1052
|
+
never reaches anyone who blocks or is blocked by that player, never goes into a
|
|
1053
|
+
world-disclosed turn or to a listener ghost cannot identify, and never appears
|
|
1054
|
+
in public inspect, relays or a mind's autonomous decisions. Place code and authored lines are never handed a result as fact except
|
|
1055
|
+
what ghost verified: `hub.results` (§7) and a `carry.result` with
|
|
1056
|
+
`verified: true`. A carried result the client brought back on the dev serve
|
|
1057
|
+
(`verified: false`) is the client's word and is for display only.
|
|
1058
|
+
|
|
1059
|
+
## 14. Per-player progress (v1.2)
|
|
1060
|
+
|
|
1061
|
+
A place that keeps a player's progress between visits keeps it in **deck
|
|
1062
|
+
scope keyed by the player's user id**: `hub.session.storage.deck` under
|
|
1063
|
+
`'<name>:<userId>'`, with the `userId` the kit hands it (`arrive`,
|
|
1064
|
+
`hub.players()`, `leave`). Never in user scope (`storage.user(userId)`): a
|
|
1065
|
+
player's own client can write that (`Store.me`), so progress kept there can be
|
|
1066
|
+
forged; only the deck's server writes deck scope. An anonymous player
|
|
1067
|
+
(`userId` null) has none, and the place says their progress is not kept.
|
|
1068
|
+
On the dev serve a guest's `userId` is its `dev-guest-<n>` subject.
|
|
1069
|
+
What the kit and Castle promise, and what they do not:
|
|
1070
|
+
|
|
1071
|
+
- **Load before you write.** A read that fails is not an empty save: a place
|
|
1072
|
+
that writes a fresh one after a failed read wipes the player's progress. Keep
|
|
1073
|
+
the player unsaved for the visit instead (Thornwall Escape and Lantern Lot do).
|
|
1074
|
+
- **Save as things change, not only at the end.** `leave` runs for every player
|
|
1075
|
+
who goes, while they are still known (their result is taken there too), and
|
|
1076
|
+
`shutdown` gives a stopping session a few seconds to finish its writes; but a
|
|
1077
|
+
host that fails sends neither. Write every few seconds, one write per account
|
|
1078
|
+
at a time, each carrying the whole save.
|
|
1079
|
+
- **Two visits can hold the same account** (two tabs, a late door), and deck
|
|
1080
|
+
storage has no compare-and-set: the last write wins. A place that must not
|
|
1081
|
+
lose progress to an older visit writes a counter it only ever raises and
|
|
1082
|
+
refuses to load over a newer one it has seen; a revision check in Castle's
|
|
1083
|
+
storage is filed as a platform gap.
|
|
1084
|
+
- **The dev serve:** guests (`dev-guest-<n>`) have storage only once the deck
|
|
1085
|
+
has been saved, and every serve reuses those subjects, so dev guests share
|
|
1086
|
+
their saves across runs; test persistence as the author, or clear the keys.
|
|
1087
|
+
|
|
1088
|
+
## Changes from M0
|
|
1089
|
+
|
|
1090
|
+
| M0 gap | v1 |
|
|
1091
|
+
| --- | --- |
|
|
1092
|
+
| 1 no declared UI | §9 |
|
|
1093
|
+
| 2 server can't change an actor | §10 |
|
|
1094
|
+
| 3 can't hold a player | §8 |
|
|
1095
|
+
| 4 no shove | not in v1; engine rule, §6 |
|
|
1096
|
+
| 5 hooks lack the session | §4, `hub.session` |
|
|
1097
|
+
| 6 session doesn't know its place | §2 |
|
|
1098
|
+
| 7 results faked | §7, server-authored and validated; host forwarding is the hub.result card |
|
|
1099
|
+
| 8 avatar plumbing | §11, owned by the kit |
|
|
1100
|
+
| 9 arrival facing | §5, `arrival.face` |
|
|
1101
|
+
|
|
1102
|
+
## Changes in v1
|
|
1103
|
+
|
|
1104
|
+
Minor additions, each optional; a deck written before them reads the same.
|
|
1105
|
+
|
|
1106
|
+
| date | change |
|
|
1107
|
+
| --- | --- |
|
|
1108
|
+
| 2026-10-04 (v1.14) | §5 a town's Doors rows carry `featured` (listed first, starred), `solo` (a door that takes one player: a party is told so and is not asked to come) and `need` (its minimum when over one); a member who picks the door their party is already going to has answered yes; a friend or party member who comes in after the first moments is announced ("amy is here") and pointed to. §6 the chat field is always shown where the host has chat, disabled with the reason when it cannot be used ("Follow each other to chat. Nobody here follows you back yet.", "Chat isn't available on this account"). A deck changes nothing |
|
|
1109
|
+
| 2026-10-04 (v1.13) | §10 goals: `hub.label`'s `style: "goal"`, a per-player pointer to a scene actor drawn at the screen's edge while it is out of view. Pebble Cove's playtesters could not find the villager an errand named: a sign is drawn only where it projects on screen, and the camera looks down. A place that sets no goal is drawn exactly as before |
|
|
1110
|
+
| 2026-10-03 (v1.12) | §6 free-text chat between players who follow each other and are both over 13, enforced by ghost through the host (`Hub.chat`, `Hub.say`, `Hub.reportChat`); the kit draws what it is handed and says only "Follow each other to chat" otherwise. Nothing on the place's wire, and nothing at all on a host without the commands |
|
|
1111
|
+
| 2026-10-03 (v1.11) | §4 layer doors: `HubDoor` gains the optional `kind: "layer"` for a door whose row places on layers; `hub.go` on it tells each signed-in player to go with no pad, and `hub.pad` tells ghost nothing. The first place with its own minds behind a door (Pebble Cove) needed it: only a public layer gets a place's minds, and a town could only fire pads. A place with no such door behaves exactly as before |
|
|
1112
|
+
| 2026-10-03 (v1.11) | §6 quick reactions and phrases: the speech button, `hub-say` and `hub-said` (§12), in every hub place; the avatar picker is one Character button that opens the characters; a town's Doors list leaves an event gate out while its event is closed and names it "Event · <title>" while open. A deck changes nothing |
|
|
1113
|
+
| 2026-10-03 (v1.10) | §5 parties in a town: invite and accept, Join to a member, Doors > Go proposes the door to the party and puts each member who says yes on its pad; `hub-party` both ways (§12), `hub.coming` (§4). A jump to a door lands on its pad where it has one (it was 7 m in front). A game has none of it; a town that reads no `hub.coming` fires its pads as before |
|
|
1114
|
+
| 2026-10-03 (v1.9) | §5 finding a friend: the People list in a town names everyone with where they are, friends first with Join, the rest with Find (a pointer); `hub-where`, `hub-goto` (§12), the `where` hook (§4), pointers to friends out of sight; the Friends button is gone (its friends are in the People list). A game lists what it did, and a deck changes nothing; a town on a host without `Hub.friends` lists names only |
|
|
1115
|
+
| 2026-10-03 (v1.8) | §13 notes: the `npcContext` and `npcHeard` hooks, `hub-npc-notes` and the notes prefix a mind's turn carries (`HUB_NPC_NOTES` for any other); bodies sharing a character; `hub-npc-line` carries `why`, and the panel marks a mind's scripted answers. A place with neither hook sends turns and is sent what it was, but for the panel's mark |
|
|
1116
|
+
| 2026-10-03 | §10 labels in a town (a place with no `result`): only the nearest plate within 4 m and the nearest NPC line within 9 m are drawn, and other players' names within 12 m, smaller; `hub.label`'s `style: "sign"` is drawn at any distance (an older client draws it as a tag). The contract's calls are unchanged; a game place draws exactly what it did |
|
|
1117
|
+
| 2026-10-03 | §4 a cabinet's card is a chip by default (the best score and whose it is), drawn within 5 m instead of 9; the whole board opens on a tap and closes on a tap or on walking away. What the server sends is unchanged |
|
|
1118
|
+
| 2026-10-03 (v1.7) | §4 cabinets: a door to a classic Castle deck. `hub.doors()` entries gain `classic`; `hub.go` on such a door tells each player's client to go alone (`hub-go` with `classic`) instead of firing a pad; `HubDoor` gains the optional `kind: "cabinet"` (no swing, not in the Doors list, no pad with ghost). §5 the cabinet's trip: `Hub.go` answered `kind: 'classic'`, then away under the cover, out of the session, until the ordinary `Hub.back`. §12 `hub-cabinet` (a card, per player, in range, once per version, budgeted), `hub-dev-classic`, and `again` on a repeated hello. A place with no cabinet draws nothing new and is sent and reads exactly what it did; a host that does not answer `kind: 'classic'` keeps the door shut |
|
|
1119
|
+
| 2026-10-03 (v1.6) | §6 a place's sounds play in a game reached through a door: the content pack carries the files its places' `idle.sounds` list (`audio`, `docs/content-pack.md`), and the town's engine plays them from there. A deck changes nothing; a town on an older engine ignores `audio`, and the game is silent there as before |
|
|
1120
|
+
| 2026-10-03 (v1.6) | §6 idle play: the `idle` manifest field; emotes (`hub-emote`, the `emote` hook, `hub.emote`), seats (`HubSeat` actors, `hub-sit` / `hub-stand`, the `sit` hook, `hub.seat`; a seat is a §8 hold) and the place's sounds (`hub.sound`, its own deck's files); `hubEmotes`, `hubSeated`, `hubSounds` and `hub-sound` (§12). The M2 town's benches could only be stood by and its jukebox played lamp colours. A place without `idle` draws nothing new and is sent exactly what it was |
|
|
1121
|
+
| 2026-10-03 (v1.5) | §7 `hub.results(playerId)`: ghost's recent results and records of a player, read at arrival and once a minute. The town's innkeeper read them through the host's results read beside the kit's own |
|
|
1122
|
+
| 2026-10-03 (v1.4) | §11 `hub.wear`: a wearable `{ kind, color, rarity }` on the player's avatar, kept by ghost per account (from a curated place) and drawn in every hub place; `hubWear` and `hub-wear` (§12). M3's Wishwell rolled an aura it could only draw in its own scene. A place where nobody wears anything is sent exactly what it was; `hubAv` is unchanged |
|
|
1123
|
+
| 2026-10-03 | Blocks hide players both ways (§12 `hub-av`); the hub chrome's People list reports a player (`Hub.report`) where the host runs the hub; a player barred from the hub (`CAULDRON_HUB_BANNED`) is told "You can't enter the town right now." and not retried. A deck changes nothing, and a session with no blocks is sent what it was |
|
|
1124
|
+
| 2026-10-03 | §12 a filtering session sends other players' rows at ~10 Hz with short ids (`idm`, `pi`). A session within `nearestPlayers` is sent what it was |
|
|
1125
|
+
| 2026-10-03 | §5 jumping to a door: a town's Doors button beside Friends, `hubDoors` and `hub-door-jump` (§12). A game draws nothing new, and a deck changes nothing |
|
|
1126
|
+
| 2026-10-03 | §4 a door may face any way: the trip's swing and camera follow its rotationY. A door facing +z (every M1 door) swings and films exactly as before |
|
|
1127
|
+
| 2026-10-02 | `nearestPlayers` and the `in`/`out` interest fields (§12). A session of 31 players or fewer is sent exactly what it was |
|
|
1128
|
+
| 2026-10-02 | §5 joining a friend: the Friends button and `Hub.jump`, drawn only where the host answers `Hub.friends`. A game (a place with `result`) never shows it, and nothing changes for a deck |
|
|
1129
|
+
| 2026-10-02 | §13 NPCs: `HubNpc` bodies, `hub.npc`, `npcLine`, the `npcs` manifest field; `hub.label` gains `to`. A place that uses none of them is drawn and behaves exactly as before |
|
|
1130
|
+
| 2026-10-03 (v1.3) | §10 `hub.pose` and `hub.reset`: read a body and put a loose object back, taking it from the client simulating it with a handover. M3's Bumper Ball kept a pool of eight hidden balls because nothing could put one back on the spot, and read positions out of `hub.sim` |
|
|
1131
|
+
| 2026-10-03 (v1.3) | §6 grabbing and throwing: the `grab` manifest field, the `grab` hook, `hub.drop` and `hub.holding` (§4), the hub chrome's Grab / Throw button, `hub-grab`, `hub-grab-deny` and `hub-drop` (§12). M3's Bumper Ball wanted Fling Things and could only shove props by walking into them. A place without `grab` draws nothing new and is sent exactly what it was |
|
|
1132
|
+
| 2026-10-03 (v1.2) | §4 `hub.board` carries `featured` (today's rotation features the door) and, on an event gate, `event` (`day`, `open`, `opensAt`, `closesAt`, `last`), where ghost has them. The M2 town could not mark featured doors or run its 8pm event gate; a place that reads neither is unchanged |
|
|
1133
|
+
| 2026-10-03 (v1.2) | §4 `userId` on `arrive`, `hub.players()` and `leave`; `leave` runs while the player is known, so it may report their result; a `shutdown` hook; §14 per-player progress. M3's Lantern Lot and Thornwall Escape read user ids out of the session, lost a Back-leaving player's result, and could lose a last save at shutdown |
|
|
1134
|
+
| 2026-10-03 (v1.2) | §6 `hub.tune`, told to its player as `hub-tune` (§12); multiplayer-3d's clamp reads a player's own `maxSpeed`. M3's Thornwall Escape could not make the stat it grows make anyone faster, so the stat only opened gates |
|
|
1135
|
+
| 2026-10-03 (v1.2) | §10 `hub.spawn` and `hub.despawn`, carried as `spawned` (§12). M3's Lantern Lot authored every lantern of every kind on every slot, plus a carried copy per lot per kind, and hid them (230 actors, a 108 KB pack); with templates it has 90. A hidden kinematic actor is now hidden on every client (it was drawn at its network pose) |
|
|
1136
|
+
| 2026-10-02 (v1.1) | §7 a result's `outcome` is optional when it carries a score; §5 `fallY`, the `fall` hook and scenes with no ground (`"ground": { "none": true }`, physics-3d and multiplayer-3d); §4 a dev `deck:<name>` door reads the destination's castle.json, and the check refuses drift. M1's Summit Sprint and Vault Crew called finishing a win; Tile Fall faked its lava with pillars over a coloured ground |
|
|
1137
|
+
| 2026-10-02 (v1.1) | §11 `hub.mark`, carried as `marks` (§12). M1's Zone Wars could not show anyone's team and Tag could not show who was it |
|
|
1138
|
+
| 2026-10-02 (v1.1) | §13 minds on every layer: on an SDK with `Multiplayer.placeCharacters` the main place joins a layer and its NPCs read `session.characters`, one memory per place; `npcs.route` is the fallback for older SDKs. A deck without `npcs` is unchanged |
|
|
1139
|
+
| 2026-10-02 (v1.1) | §10 `hub.move` and `hub.tint`; §4 `hub.actorsWith` adds `shape` and `body`. The snapshot carries `tints` (§12). M1's Vault Crew and Tile Fall said a plate's or tile's state with labels and could not have a moving platform; Zone Wars and Summit Sprint repeated each zone's and pillar's size in its marker |
|