@crowdedkingdoms/crowdyjs 18.11.0-dev.1 → 18.13.0-dev.1

package/MIGRATION.md

@@ -120,6 +120,57 @@ super-admin's session). There is no SDK replacement.
 `dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
 `npm run codegen`).
 
+## 18.13.0: the economy
+
+Additive. **Needs a compute toolchain whose starter pack has the `player` and `market`
+starters** (ckx-sdk 0.12.1; dev's toolchain v1.15.0). The economy lives in hub state and is
+not a ledger (the operator's decision HS-52): no double-entry book, no real money, transfers as
+steps each hub answers once.
+
+- **The caller's own `player` hub**, keyed by their player id (the kit needs it: `playerId` in
+  `client.kit()`'s options, or the identity it can ask): `kit.player` (`watch`, `me`, `rules`,
+  `profileOf`, `onEvent`) and its views `kit.inventory` (`items`, `count`, `discard`,
+  `takeMail`), `kit.wallet` (`balances`, `balance`), `kit.progression` (`progress`, `profile`,
+  `onLevel`), `kit.achievements` (`list`, `onUnlock`), `kit.quests` (`list`, `accept`, `claim`,
+  `step` for the counters the game lets a client report), `kit.crafting` (`recipes`, `craft`),
+  `kit.loot` (`tables`, `open`) and `kit.production` (`view`, `collect`). The inventory, wallet
+  and progress are read by calls only the player may make, and read again when the hub's
+  `changed` message names them; the profile is public.
+- **Markets** by name: `kit.shops.at(key)` (`vendors`, `buy`, `sell`), `kit.market.at(key)`
+  (`book`, `order`, `cancel`, `orders` mirrored) and `kit.trades.at(key)` (`open`, `offer`,
+  `accept`, `decline`, `mine` mirrored). An order or an offer holds what it puts up in the
+  player's own hub; a fill or an accepted trade moves it hub to hub.
+- **`unavailable`** (`KIT_CODES.UNAVAILABLE`): a hub refuses a change it could not finish
+  because another hub did not answer. The kit sends a call with an action id again, as it does
+  after a platform `Unavailable`; the hub keeps no receipt for it, so the resend finishes what
+  the first began.
+
+## 18.12.0: the genre starters
+
+Additive. **Needs a compute toolchain whose starter pack has the genre starters** (ckx-sdk
+0.11.0); `kit.topology` lists, builds and deploys them like the others. Against an app that does
+not run one, its module's calls are refused with `NotFound` (the app has no such node type).
+
+- **Nine more kit modules**, one per new starter hub: `leaderboards.board(name)` (the top
+  mirrored, `top`, `around`, `me`, `season`; hubs submit the scores they decided, a client never
+  does), `tables.table(key)` (cards: the table mirrored and the caller's hand as private state),
+  `tactics.battle(key)` (grid battles in phases), `encounters.encounter(key)` (waves, towers, a
+  boss with phases), `minigames.duel(key)` (hidden throws revealed together), `instances.run(key)`
+  (a party's private run: seeded floors, permadeath, expiry), `arenas.arena(key)` (classes and
+  abilities in real time), `racing.race(key)` and `racing.ball(key)` (races with laps, splits
+  and a ghost; ball games with possession), `territory.map(key)` and `territory.zone(key)`
+  (control points; a shrinking circle).
+- **The node types they talk to** are the starters' (`leaderboard`, `deck`, `tactics`,
+  `director`, `minigame`, `instance`, `arena`, `race`, `ball`, `territory`, `zone`); an app that
+  deploys one under another name passes it in `client.kit(appId, { nodes: { ... } })`.
+- **Positions a client reports are the hub's to keep**: `arenas`, `racing` and the ball game take
+  `move` / `pos` reports and answer with the position the hub's movement warden kept (a move too
+  fast is cut short, a jump refused). Each refused report is a `violation` event, and an arena
+  removes a player after a run of them (`removed`). Send them a few times a second, without an
+  action id.
+- **Event bodies never use the header's field names** (`v`, `epoch`, `seq`, `kind`): the race's
+  `timing` events carry their `stage`, the warden's `violation` events their `what`.
+
 ## 18.11.0: the Game Kit on ck-exec
 
 Additive, apart from one fix in `client.exec` (below). **Needs what 18.10.0 needs from the Game

package/README.md

@@ -750,6 +750,17 @@ modules are the tree's starter types:
 | `kit.matchmaking.queue(name)` | `matchmaker` | `join` with a rating, alone or as a party matched whole (the leader names the members; each confirms with `leader`); `accept` / `decline`; `place` and `onMatched` with the session key |
 | `kit.sessions.open(key)` | `session` | lobby, `ready`, the host's `startGame`, `act` in turn under a time limit; the hub scores and names the winner; `state` mirrored |
 | `kit.npcs.area(key)` / `areaAt(x, z)` | `npcs` (`npc-mobs`) | an area's mobs, NPCs and pets mirrored; `attack` (the hub decides reach, cooldown, damage), `talk`; pets: `adopt`, `rename`, `summon`, `dismiss`, `release`, `myPets` |
+| `kit.leaderboards.board(name)` | `leaderboard` | the top mirrored; `top`, `around`, `me`, `season`; scores come from the hubs that decided them (`submit` is for developers and hubs), seasons roll on a schedule (18.12.0) |
+| `kit.tables.table(key)` | `deck` | a card table: the table mirrored, the caller's hand as private state; `join`, `start`, `play`, `draw`, `pass` in the hub's turn order |
+| `kit.tactics.battle(key)` | `tactics` | a grid battle in phases: `move`, `attack`, `endTurn` for the player's units; the hub's units act when every player ended the phase |
+| `kit.encounters.encounter(key)` | `director` | waves down a lane on the hub's clock, `build` towers (the lane must stay open), `hit` with a cooldown, a boss with phases |
+| `kit.minigames.duel(key)` | `minigame` | two-player duels of hidden throws, revealed together; `throw`, `rematch` |
+| `kit.instances.run(key)` | `instance` | a private run for one party: `open` (seeded floors), `invite`, `join`, `enter` each room, `descend`; permadeath and expiry; depth to a leaderboard |
+| `kit.arenas.arena(key)` | `arena` | real-time fights: `join` as a class, `move` (the hub's warden keeps what the speed allows), `cast` (cooldown, resource, range; projectiles and areas land on the hub's ticks) |
+| `kit.racing.race(key)` / `ball(key)` | `race`, `ball` (`racing`) | races (gates in order, laps, splits, places, the winner's `ghost`) and ball games (`claim`, `pass`, `shoot`, goals) on reported positions the warden keeps |
+| `kit.territory.map(key)` / `zone(key)` | `territory`, `zone` (`territory`) | control points a faction captures by standing on them (the hub reads where players are), and a circle that shrinks and wears down whoever is outside |
+| `kit.player` and its views: `kit.inventory`, `kit.wallet`, `kit.progression`, `kit.achievements`, `kit.quests`, `kit.crafting`, `kit.loot`, `kit.production` | `player` (keyed by the player's id) | the caller's own hub: stacks and mail, soft currencies, levels and public profiles, achievements, quests with tutorials (`step` for the counters a client may report), crafting, loot with pity, idle production; private parts read again when the hub says they changed (18.13.0) |
+| `kit.shops.at(key)`, `kit.market.at(key)`, `kit.trades.at(key)` | `market` | vendors with stock and restocks (`buy`, `sell`), order books (`order`, `cancel`, `book`), trades between two players (`open`, `offer`, `accept`, `decline`); what a player puts up is held in their own hub, and a call that could not reach it is refused `unavailable` and sent again |
 | `kit.topology` | — | composes a manifest from `exec.starters` (the types picked, what they hang under and call), checks the tree, builds and deploys (developers, `manage_compute`) |
 | `kit.spectate`, `kit.emotes`, `kit.shards` | — | a viewer's heartbeat so the world's messages reach it; emotes as client events every kit client reads; shard keys as the hubs compute them |
 | `kit.social` | — | parties, guilds and chat rooms over teams and channels |
@@ -782,7 +793,11 @@ await kit.sessions.open(key).act({ points: 2 });   // sent with an action id: pl
   shape React's `useSyncExternalStore` takes. `PrivateState` reads what only its player may
   see with a call, again whenever the hub says it changed for them.
 - **Refusals** are `KitError` (a `CrowdyExecError` with status `AppError`) with a `code` to
-  branch on: `not_your_turn`, `cooldown`, `full`, `forbidden`, ... (`KIT_CODES`).
+  branch on: `not_your_turn`, `cooldown`, `full`, `forbidden`, ... (`KIT_CODES`). A call with an
+  action id refused `unavailable` (a hub it needed did not answer) is sent again (18.13.0).
+- **The economy is not a ledger.** Items and soft currency are hub state; a transfer between
+  players is steps each hub answers once. See the Game Kit's economy page before you put
+  anything of real value in it.
 - **Kit types are the hubs' MessagePack maps as they arrive**, field names and all
   (`time_of_day`, `expires_in_ms`), the same in CrowdyCPP and CrowdyPy.
 - **Realtime**: hubs show server-driven actors through the realtime tier; `kitActorCodec`,
@@ -1227,6 +1242,9 @@ is why the mint also returns `discoveryUrl`.
 `CROWDY_HTTP_URL` and `CROWDY_E2E_THROWAWAY_OWNER=1` it registers a throwaway org admin (its own
 org and app) and a player, opens and closes a grid, and checks the tier's ck-exec gateway. It
 leaves the org behind and archives the app, so it runs only when asked to.
+`test/e2e/game-kit.test.mjs` does the same for the Game Kit: the throwaway owner composes the
+starter hubs with `kit.topology`, builds and deploys them, and two players play them (on dev and
+test it also needs `CROWDY_PROVISIONING_TOKEN`, which their staff-only sign-up asks for).
 
 ## Maintainers: schema artifacts and fixtures
 

package/dist/generated/graphql-schema.d.ts

@@ -3760,14 +3760,14 @@ export type ExecStarterFile = {
     /** The path within the crate, as `execBuild` takes it. */
     path: Scalars['String']['output'];
 };
-/** The starter packs: four crates and a manifest that deploys them as one app. */
+/** The starter packs: the starter crates, and a manifest that deploys them as one app. */
 export type ExecStarterPack = {
     __typename?: 'ExecStarterPack';
-    /** The manifest for `execDeploy` with the build’s id: the root `world` hub, and `matchmaker`, `session` and `npcs` under it, each naming its crate. */
+    /** The manifest for `execDeploy` with the build’s id: the root `world` hub and the types under it, each naming its crate. */
     manifestJson: Scalars['String']['output'];
     /** The mod starter: a player’s code on a grid they own, built with `execModBuild` and deployed with `execModDeploy` rather than in the manifest. Null on a toolchain without it. */
     mod: Maybe<ExecStarter>;
-    /** The crates. */
+    /** One entry per node type of the manifest: a crate that serves two types appears twice, so build each crate once. */
     starters: Array<ExecStarter>;
 };
 /** A deployed version of an app’s ck-exec topology. */
@@ -4836,7 +4836,7 @@ export type Mutation = {
     revokeTierAccessProvisioningToken: TierAccessProvisioningToken;
     /** OPERATOR: remove an entry from the list. Accounts it was admitting are refused at their next request, and their sessions and app tokens are ended. Refused on prod. */
     revokeTierAccessRule: TierAccessRule;
-    /** Reverts every voxel edit made by `userId` in `appId` between `from` and `to`, returning one RollbackVoxelEventResult per affected voxel (`applied` tells you whether each was actually changed). DEFAULTS to dryRun=true, which only PREVIEWS the planned reversions without writing; pass dryRun=false to actually apply them (DESTRUCTIVE — mutates world state). A reverted voxel’s edit-log row takes the earlier edit’s type, state and author and the ROLLBACK’s time as its createdAt, so a client reading edits `since` its last sync sees the revert. Requires a valid bearer token AND the `manage_apps` permission on the org that owns `appId` (super admins bypass). */
+    /** Reverts every voxel edit made by `userId` in `appId` between `from` and `to`, returning one RollbackVoxelEventResult per affected voxel (`applied` tells you whether each was actually changed). DEFAULTS to dryRun=true, which only PREVIEWS the planned reversions without writing; pass dryRun=false to actually apply them (DESTRUCTIVE — mutates world state). A reverted voxel’s edit-log row takes the earlier edit’s type, state and author and the ROLLBACK’s time as its createdAt, so a client reading edits `since` its last sync sees the revert. When the app’s wilderness is closed (`wildernessOpen` false), an applied rollback that would write any chunk of closed, unclaimed wilderness is refused (403) before it writes anything; a dry run is not. Requires a valid bearer token AND the `manage_apps` permission on the org that owns `appId` (super admins bypass). */
     rollbackVoxelUpdates: Array<RollbackVoxelEventResult>;
     /** OPERATOR ONLY. Runs the shared-usage billing tick once. It still bills only the last CLOSED clock hour — it will not charge an open hour. Use this to prove a closed-hour debit without waiting for the ~60s cron. Backdating usage rows is a local-test fixture, not something this mutation does on a live tier. */
     runSharedUsageBillingTick: Scalars['Boolean']['output'];
@@ -6799,7 +6799,7 @@ export type Query = {
     execMods: Array<ExecMod>;
     /** Your mods in an app, on every grid. */
     execMyMods: Array<ExecMod>;
-    /** The starter packs, which replace the compute templates: a world tick (the root hub: clock, weather, resource nodes, liveops events), a matchmaker, game sessions (lobby, host, turns, scores) and an NPC and mob engine, as ckx-sdk crates to pass to `execBuild` and a manifest for `execDeploy`. Requires the org 'manage_compute' permission. */
+    /** The starter packs, which replace the compute templates: ckx-sdk hub crates for a root world, matchmaking, game sessions, NPCs and mobs, game genres (leaderboards, cards, tactics, waves, duels, private runs, arenas, races, territory), and the economy (a player's own hub, markets), to pass to `execBuild`, with a manifest for `execDeploy`. `starters` has one entry per node type, so a crate that serves two types appears twice: build it once. Requires the org 'manage_compute' permission. */
     execStarters: ExecStarterPack;
     /** An app's deployed ck-exec versions, newest first, and which is active. Requires the org 'view_compute_diagnostics' permission. */
     execVersions: Array<ExecVersion>;