@plupin/cli 0.1.0 → 0.2.0

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.
@@ -11,6 +11,7 @@ same three calls work for a Three.js world, a canvas 2D game, Phaser, or plain D
11
11
  | [api.md](api.md) | you need the exact surface: every option, method, event |
12
12
  | [netcode.md](netcode.md) | you must choose between host-relayed world and server-authoritative play |
13
13
  | [leaderboards.md](leaderboards.md) | your game should keep a ranking, and you want the top list plus each player's own place |
14
+ | [randomness.md](randomness.md) | your game rolls for a cosmetic: one platform source, and why a paid outcome never uses yours |
14
15
  | [integration.md](integration.md) | you have a game on your laptop and want it online |
15
16
  | [cli.md](cli.md) | you want `plupin dev` / `plupin deploy` (**planned**) |
16
17
  | [checks.md](checks.md) | `plupin up` refused your build, or you want to know what it measures: MB, page load, time-to-first-input |
@@ -59,6 +60,7 @@ Three concepts, that is the entire SDK: **Room** (the connection), **Peers** (th
59
60
  | Server relay room (`authority: "host"`) | shipped and routed: `plupin.json` `authority: "host"` admits a room with kind `l`, no document needed |
60
61
  | Referee (`room.claim`) | in progress |
61
62
  | Leaderboards (`plupin.json` `leaderboards[]`, `GET /api/games/:gameId/leaderboards/:boardId`) | implemented, not deployed yet: declared in the manifest, written by the room, read with the caller's own rank. A `host`-authority game has no server result, so its boards stay empty |
63
+ | Randomness: `rollPlatformRandom` + gacha pools (`gacha.*`) | shipped in source: one CSPRNG, moderated pools, ledger-mediated draws, SDK roll. Not deployed yet |
62
64
  | `plupin dev`, `plupin deploy`, `plupin mcp` | planned — contracts written, not implemented |
63
65
 
64
66
  Docs marked **planned** describe a contract that exists so the implementation can be checked against
package/dist/docs/api.md CHANGED
@@ -76,7 +76,7 @@ only when you need your own buffer policy (for example, a camera target that mus
76
76
  ## In-app purchases
77
77
 
78
78
  A game asks; the player confirms on the platform's own page; the platform moves the Sigma. A static game with no server just reads what the player holds; a game with a server can take a signed receipt instead. A game never holds spending authority ([ADR-0018](../architecture/adr/0018-game-address-and-identity.md)).
79
- The creator keeps 95% and the platform 5% (`GAME_CREATOR_SHARE_BPS`). The paid-Sigma part of that share becomes Creator Earnings, cashable at Rp80 per Sigma after a 30-day hold ([payouts](../product/payouts.md)). A creator cannot buy from their own game (`SELF_PURCHASE`).
79
+ The creator keeps 85% and the platform 15% (`GAME_CREATOR_SHARE_BPS`). The paid-Sigma part of that share becomes Creator Earnings, cashable at Rp80 per Sigma after a 30-day hold ([payouts](../product/payouts.md)). A creator cannot buy from their own game (`SELF_PURCHASE`).
80
80
 
81
81
  ### 1. Declare what you sell
82
82
 
@@ -205,6 +205,35 @@ plupin dev --receipt-url http://127.0.0.1:9000/receipts
205
205
 
206
206
  Receipts go to that URL, signed with the fixed key `plupin_gsk_dev`, retried every 5 seconds; `verifyReceipt` and the game-server routes work unchanged with that key. `POST /_dev/purchases/expire` stands in for the window running out and refunds whatever is unacknowledged. On the dev origin a game's scripts share the page's test wallet, so test mode proves your flow, not the origin boundary.
207
207
 
208
+ ## Randomness
209
+
210
+ Plupin has **one** source of randomness: the Workers runtime CSPRNG (`crypto.getRandomValues`) behind one weighted-draw implementation (`packages/api/src/domains/random`). The invariant is not a suggestion:
211
+
212
+ > A game never rolls its own RNG for anything a player pays for. A paid random outcome (gacha, mystery item, loot draw) is a platform draw: Sigma leaves the wallet and the item arrives in one transaction, so the game cannot see or influence the roll. A free in-game roll may ask the platform for the number instead of generating its own.
213
+
214
+ Use that call for cosmetics, emote drops, chest contents — anything a player might later trade or care about. Writing your own generator means a player can argue the outcome was yours to choose, and the platform has no record to answer with.
215
+
216
+ ```ts
217
+ import { rollPlatformRandom } from "@plupin/game-sdk"
218
+
219
+ // one weight per outcome, in your own order: a fair die, then a 1-in-6 / 2-in-6 / 3-in-6 table
220
+ const die = await rollPlatformRandom([1, 1, 1, 1, 1, 1])
221
+ const drop = await rollPlatformRandom([1, 2, 3])
222
+
223
+ if (drop.status === "ok") grantCosmetic(drop.index) // 0 | 1 | 2
224
+ else showRetry(drop.code) // "busy" | "network" | "invalid_weights" | "unknown_platform"
225
+ ```
226
+
227
+ | field | type | meaning |
228
+ |---|---|---|
229
+ | `weights` | `number[]` | 2–64 relative weights, each an integer 1–10 000. Only the ratio matters |
230
+ | `options.url` | `string` | API origin; omit when the game is served from `<game>.plupin.com` or `plupin dev` |
231
+ | `options.fetch` | `Function` | injection point for tests |
232
+
233
+ The answer is `{ status: "ok", index, roll, total }`: `index` is into the array you passed, `roll` is the uniform offset in `[0, total)` and `total` is the weight sum. Store them if you want to prove a roll later — a paid draw stores the same two numbers on its row. The call never throws: a spent budget is `status: "failed", code: "busy"`.
234
+
235
+ What the platform does with a paid draw (visible to players through the shop, moderated like any listing): a creator publishes a pool of live listing ids with weights and a Sigma price per draw; the pool is reviewed before it goes live; the pool owner cannot draw from their own pool; an item the player already owns or authored is not in the roll, and when nothing is left the draw is refused rather than charged. Every draw keeps its request key, so a retried request returns the recorded outcome instead of a second roll.
236
+
208
237
  ## `plupin.json`
209
238
 
210
239
  The ranking your `plupin.json` declares, read from the game. Read-only on purpose: a score is produced
@@ -46,3 +46,85 @@ drawCharacter2D(context, {
46
46
  ## Roblox clothing
47
47
 
48
48
  `shirt` and `pants` take a Roblox classic template, a 585×559 PNG, unchanged. `validateClassicTemplate(width, height)` rejects any other size. T-shirts (512×512) and 3D layered clothing are not supported yet.
49
+
50
+ ## Emotes
51
+
52
+ An emote is a name, a face and a clip the rig already has. The faces are the named faces of the Plupin films (`cool`, `dead`, `stars`, ...), so an emote reads the same in a video, in the app and in your game. The same list is the shop's: the first eight are free, the rest are bought with Σ.
53
+
54
+ ```ts
55
+ import { EMOTES, emoteOf, NAMED_FACE_STAMPS } from "@plupin/character"
56
+ import { faceCanvas } from "@plupin/character/canvas"
57
+
58
+ const emote = player.emote("ngakak") // plays its clip; undefined for an unknown name
59
+ if (emote) {
60
+ emote.glyph // "(≧▽≦)", the kaomoji to float over the character
61
+ emote.face // "teriak", a key of NAMED_FACE_STAMPS (8 x 4 pixels)
62
+ const face = faceCanvas(emote.face) // a 64 x 64 canvas, usable as `look.face`
63
+ }
64
+ ```
65
+
66
+ `emoteOf("emote-tewas")` and `emoteOf("tewas")` are the same lookup. Paid emotes are for players who own them: the platform decides that, the SDK only plays what it is asked to.
67
+
68
+ ## Making an emote
69
+
70
+ An emote you sell is a composition, not a video: `{ glyph, face, clip }` plus a name, an id and a
71
+ price. The gallery seeds are the same shape, so a creator emote is not a second format.
72
+
73
+ ```json
74
+ {
75
+ "id": "emote-ngakak",
76
+ "slot": "emote",
77
+ "name": "Ngakak",
78
+ "sigmaPrice": 25,
79
+ "assetConfig": { "glyph": "(≧▽≦)", "face": "teriak", "clip": "jump" }
80
+ }
81
+ ```
82
+
83
+ `slot` is `emote` (played) or `outfit` / `hair` / `accessory` (worn, where `assetConfig` is
84
+ `{ "color": "#8a5ad8" }`). A face is either a named one from `NAMED_FACES` or your own drawn stamp:
85
+ `faceStamp` is four rows of eight palette keys (`FACE_STAMP_PALETTE`, `.` for transparent).
86
+
87
+ ```bash
88
+ plupin emote new my-emote --id emote-ngakak --name Ngakak --glyph "(≧▽≦)" --face teriak --clip jump --price 25
89
+ plupin emote preview my-emote # writes my-emote/.plupin/emote-preview.svg
90
+ plupin emote push my-emote # the listing id, state `pending`
91
+ ```
92
+
93
+ `@plupin/character/listing` is the module behind all three: `checkListingManifest` validates a
94
+ composition against these tables and `renderListingPreview` draws the headshot. The platform calls
95
+ the same two functions, so the SVG in `.plupin/` is byte-for-byte the picture the moderator decides
96
+ on and the shop shows, and `plupin emote push` fails rather than report success if they ever differ.
97
+ An agent can run the same loop through the hosted MCP tools `emote_new`, `emote_preview` and
98
+ `emote_push`.
99
+
100
+ ### Badges
101
+
102
+ A creator's name carries a tick when the platform vouches for it: gold for the official Plupin account,
103
+ blue for a creator whose identity check passed. You do not set it; it follows the account. See
104
+ `docs/ops/official-account.md`.
105
+
106
+ ### Animated emotes
107
+
108
+ An emote can ship its own animation instead of naming one the rig already has. `assetConfig.anim`
109
+ is keyframes for some of the six bones (`head`, `torso`, `armL`, `armR`, `legL`, `legR`):
110
+
111
+ ```json
112
+ { "fps": 20, "loop": false, "bones": ["armR"], "frames": [[0, 0, 0, 0], [0, 0, 2.6, 0.1]] }
113
+ ```
114
+
115
+ A frame is `x, y, z` in radians for each listed bone, in order, then one `lift` in studs (never
116
+ negative: the legs are straight, so a crouch would sink them into the floor). The same limits apply
117
+ for every surface, with the sentence naming the path: at most 30 fps, 240 frames and 8 seconds, a
118
+ rotation within ±3.2 rad, lift within 0 to 3, and 32 KB as JSON. `clip` may be left out; it is then
119
+ `idle`, the fallback an older renderer plays.
120
+
121
+ You rarely write frames by hand. `plupin emote import clip.json my-emote` takes a baked motion clip
122
+ (the 18-joint format the CC0 libraries convert to, such as Quaternius's Universal Animation Library,
123
+ or one you keyed yourself), solves each limb into the rig's rotations, and writes `anim` for you.
124
+ Use motion you have the right to ship: CC0, or your own. Do not upload ripped game or dance-app
125
+ emotes; a moderator rejects them, and a rejected listing does not refund its fee.
126
+
127
+ A paid listing costs a listing fee (10 Σ) when it enters review, counts against 5 listings per 24
128
+ hours and 12 pending-or-live listings, and an identical manifest is refused as `DUPLICATE_CONTENT`.
129
+ A rejection does not refund the fee. The shop shows "sold by @username", and a sale pays the creator
130
+ through the existing 90/10 creator-earnings lane.
@@ -85,7 +85,7 @@ apply.
85
85
  - `1` — the folder is not a valid build, or Playwright's browser is missing. Install it with
86
86
  `bunx playwright install chromium`.
87
87
 
88
- Two files land in `.plupin/` beside the build (`./.plus1/` for `./dist`), never inside it, because
88
+ Two files land in `.plupin/` beside the build (`./.plupin/` for `./dist`), never inside it, because
89
89
  everything inside the folder is the bundle: `checks.json` holds the measured result and `checks.png` is
90
90
  a screenshot of the phone viewport at the end of the run.
91
91
 
package/dist/docs/cli.md CHANGED
@@ -12,9 +12,12 @@ program.
12
12
 
13
13
  ```sh
14
14
  bun add -d @plupin/cli
15
- bunx plupin --help
15
+ bunx @plupin/cli --help
16
16
  ```
17
17
 
18
+ There is no unscoped `plupin` package on npm: `bunx plupin` is a 404, and `npx @plupin/cli` works
19
+ when Bun is on `PATH`.
20
+
18
21
  A game that imports the SDK installs it beside the CLI:
19
22
 
20
23
  ```sh
@@ -60,6 +63,38 @@ The same `idempotencyKey` is one debit; two keys are two debits. `--seed` fills
60
63
  in `plupin.json` with five reproducible rows. `bun packages/cli/scripts/local-money-check.ts` is the
61
64
  runnable acceptance transcript.
62
65
 
66
+ ## `plupin emote new | preview | push`
67
+
68
+ An emote or wearable you sell is one file, `emote.json`, and one folder:
69
+
70
+ ```bash
71
+ plupin emote new my-emote --id emote-ngakak --name Ngakak --face teriak --clip jump --price 25
72
+ plupin emote import walk-cycle.json my-emote # optional: put a baked animation on it
73
+ plupin emote preview my-emote
74
+ plupin emote push my-emote
75
+ ```
76
+
77
+ `emote new [dir] [--id <id>] [--name <n>] [--slot emote|outfit|hair|accessory] [--price <n>]`
78
+ writes `emote.json` and an `assets/` folder. The composition is validated before anything is
79
+ written, with the shared character package the server uses, so an unknown face or clip fails here
80
+ and names the ones that exist. `--glyph`, `--face`, `--clip` fill an emote; `--color` fills a
81
+ wearable; `--price 0` is a giveaway. It refuses to overwrite an existing manifest.
82
+ `emote import <clip.json> [dir] [--fps <n>]` then puts your own animation on the emote (see "Animated
83
+ emotes" in the character guide); it scaffolds the folder first when there is no manifest yet.
84
+
85
+ `emote preview [dir] [--out <file>]` renders the composition and writes the SVG to
86
+ `<dir>/.plupin/emote-preview.svg` (or `--out`). No network, no upload: the bytes on disk are the
87
+ bytes the moderator will decide on, because the platform renders with the same function.
88
+
89
+ `emote push [dir] [--api <url>]` sends `emote.json` to `POST /api/items` with the token
90
+ `plupin login` stored, and prints the listing id, its `pending` state and the fee. Refusals are the
91
+ server's own sentence and exit 3: `DAILY_LISTING_LIMIT` (5 per 24 hours), `ACTIVE_LISTING_CAP`
92
+ (12 pending or live), `DUPLICATE_CONTENT` (the same manifest is already listed), or the manifest
93
+ field and the values it accepts. Publishing a rejected id again does not charge the fee twice; a
94
+ rejection itself does not refund it.
95
+
96
+ Only `push` needs an account. `new` and `preview` write files and nothing else.
97
+
63
98
  ## `plupin up [dir]`
64
99
 
65
100
  The one command: measure the build, create the game if it does not exist, deploy the bundle, wait for
@@ -167,10 +202,12 @@ Writes `~/.config/plupin/credentials.json` with mode `600`. Reads the token from
167
202
  never appears in a command line transcript; `--token <token>` exists for scripts that already keep
168
203
  the secret out of the transcript, and `--token -` reads stdin explicitly.
169
204
 
170
- Today the token is the session token the platform issues at sign-in
171
- (`__Host-plus1.session_token`), because the server has no separate creator-token issuer yet. It is a
172
- full account credential: treat it like a password, and do not commit it. A narrower, revocable
173
- creator token is a separate slice.
205
+ The token is an OAuth 2.1 access token (PKCE, loopback redirect) minted for the `/mcp` resource with
206
+ `mcp:read` and `mcp:deploy`, which is what the hosted surface and the plain upload routes verify.
207
+ `--token` is the escape hatch for a machine with no browser: it reads the shape of what it was given,
208
+ so a pasted browser session token is stored as a session (sent as a cookie) and an OAuth token as a
209
+ bearer, instead of being sent the wrong way and answering 401. Either way it is a full account
210
+ credential: treat it like a password, and do not commit it.
174
211
 
175
212
  ## `plupin status [dir]`
176
213
 
@@ -201,6 +238,49 @@ A game deployed before the platform recorded bundle sizes reports `unknown`, nev
201
238
 
202
239
  Runs the MCP server over stdio. See [mcp.md](mcp.md).
203
240
 
241
+ ## `plupin connect claude | codex`
242
+
243
+ One command per agent CLI, so an assistant gets both Plupin surfaces without anyone editing JSON:
244
+
245
+ ```sh
246
+ plupin login # once: the access token the hosted surface verifies
247
+ plupin connect claude # ~/.claude.json
248
+ plupin connect codex # ~/.codex/config.toml
249
+ ```
250
+
251
+ | server | transport | tools |
252
+ |---|---|---|
253
+ | `plupin` | stdio, `bunx -y @plupin/cli mcp` | `manifest_check`, `dev_start`, `dev_status`, `dev_stop`, `docs` |
254
+ | `plupin-hosted` | streamable HTTP, `<api>/mcp` | the hosted surface: `emote_new`, `emote_preview`, `emote_push`, `deploy`, `game_*`, `rooms_*`, `docs`, `whoami` |
255
+
256
+ The config is the **user-level** file, not a project one: the hosted entry carries a bearer token and
257
+ a project config is a file that gets committed. Nothing else in that file changes — another server
258
+ added by hand keeps its entry, and Codex's `[mcp_servers.plupin]` table (plus a stale `.env`
259
+ sub-table, plus a copy someone pasted) is replaced in place rather than duplicated. The token is
260
+ written into the file, mode `600`, and never printed.
261
+
262
+ `--api <url>` points the hosted entry somewhere else (dev, a local worker). `CLAUDE_CONFIG_DIR` and
263
+ `CODEX_HOME` move the two files, which is how the tests drive this without touching a real config.
264
+
265
+ After writing, the command asks the hosted surface for `tools/list` with the token it just wrote and
266
+ prints what answered:
267
+
268
+ ```
269
+ $ plupin connect claude
270
+ agent claude
271
+ config /Users/you/.claude.json
272
+ mode 600
273
+ server plupin, plupin-hosted (stdio: bunx -y @plupin/cli mcp)
274
+ hosted https://api.plupin.com/mcp — token written, never printed
275
+ tools 14 from the hosted surface: docs, whoami, manifest_check, ...
276
+ done restart claude so it loads the servers
277
+ ```
278
+
279
+ A refused token is printed as the status the server answered and the config stays written; `401`
280
+ means the token expired, so `plupin login` and run it again. Signed out, or signed in with a pasted
281
+ browser session rather than the OAuth token, only the stdio server is written and the receipt says
282
+ which command to run.
283
+
204
284
  ## Releasing
205
285
 
206
286
  Two packages, one order: **the SDK first, the CLI second.** The CLI bundles these chapters and the
@@ -222,8 +302,8 @@ bun run build && npm pack # -> plupin-game-sdk-0.2.0.tgz
222
302
  npm publish --access public plupin-game-sdk-0.2.0.tgz
223
303
 
224
304
  cd ../cli
225
- bun run build && npm pack # -> plupin-cli-0.1.0.tgz
226
- npm publish --access public plupin-cli-0.1.0.tgz
305
+ bun run build && npm pack # -> plupin-cli-0.2.0.tgz
306
+ npm publish --access public plupin-cli-0.2.0.tgz
227
307
  ```
228
308
 
229
309
  `npm pack` prints every file that goes in. The list must be `dist/` only: `src/` is not packed, and
@@ -233,7 +313,7 @@ Prove the published pair from an empty directory, never from the monorepo:
233
313
 
234
314
  ```sh
235
315
  cd "$(mktemp -d)" && npm init -y
236
- npm install @plupin/game-sdk@0.2.0 @plupin/cli@0.1.0
316
+ npm install @plupin/game-sdk@0.2.0 @plupin/cli@0.2.0
237
317
  ./node_modules/.bin/plupin --help
238
318
  node --input-type=module -e 'import { Room } from "@plupin/game-sdk"; console.log(typeof Room)'
239
319
  ```
@@ -245,8 +325,8 @@ the publish (and only while nothing else depends on it). After that the version
245
325
 
246
326
  | situation | command | what it does |
247
327
  |---|---|---|
248
- | published minutes ago, wrong files | `npm unpublish @plupin/cli@0.1.0 --force` | deletes the version; every lockfile pinning it breaks |
249
- | published, then a bug found | `npm deprecate @plupin/cli@0.1.0 "broken, use 0.1.1"` | keeps the tarball installable, prints the warning on every install |
328
+ | published minutes ago, wrong files | `npm unpublish @plupin/cli@0.2.0 --force` | deletes the version; every lockfile pinning it breaks |
329
+ | published, then a bug found | `npm deprecate @plupin/cli@0.2.0 "broken, use 0.2.1"` | keeps the tarball installable, prints the warning on every install |
250
330
  | always | publish a fixed patch, `npm deprecate` the old one | the only lane that stays open after 72 hours |
251
331
 
252
332
  Deprecate rather than unpublish once anyone may have installed it: an unpublish turns their build
@@ -21,7 +21,7 @@ It is not on the public registry yet. Two ways in until it is:
21
21
  npm pack packages/game-sdk && npm install ./plupin-game-sdk-0.1.0.tgz
22
22
 
23
23
  # or a git dependency, pinned to a tag
24
- npm install "github:himanusia/plus1#v0.3.51" --workspace=packages/game-sdk
24
+ npm install "github:himanusia/plupin#v0.3.51" --workspace=packages/game-sdk
25
25
  ```
26
26
 
27
27
  ## 2. Describe the game
package/dist/docs/mcp.md CHANGED
@@ -30,6 +30,26 @@ answer a terminal would.
30
30
  Rule that will not change: `deploy` refuses unless `confirm: true`. An agent must never publish
31
31
  because it inferred intent.
32
32
 
33
+ ## Emotes over the hosted surface
34
+
35
+ The hosted server (`https://api.plupin.com/mcp`) carries the authoring loop as three tools, so an
36
+ assistant with no terminal can compose and publish a listing:
37
+
38
+ | tool | scope | what it does |
39
+ |---|---|---|
40
+ | `emote_new` | `mcp:read` | returns a validated manifest for an emote (`{ glyph, face, clip }`) or a wearable (`{ color }`) |
41
+ | `emote_preview` | `mcp:read` | renders the headshot the moderator decides on, as a data URL and an image block |
42
+ | `emote_push` | `mcp:deploy` | publishes it into the moderation queue and returns the listing id with `pending` |
43
+
44
+ All three call `@plupin/character/listing`, the module `plupin emote preview` writes to disk, so the
45
+ picture an agent approves is byte-for-byte the picture the server stores. A refusal is the service's
46
+ own sentence (`DAILY_LISTING_LIMIT`, `ACTIVE_LISTING_CAP`, `DUPLICATE_CONTENT`, or the exact field
47
+ and the allowed values), which is what makes it actionable.
48
+
49
+ The stdio server in this document stays local-only on purpose: it writes files and touches no
50
+ network, so it has no `emote_push`. Publish from a terminal (`plupin emote push`) or over the hosted
51
+ endpoint.
52
+
33
53
  ## Rules
34
54
 
35
55
  1. Every tool returns JSON or a document, never prose.
@@ -37,23 +57,102 @@ because it inferred intent.
37
57
  3. Unknown tool names name the tools that do exist.
38
58
  4. Local tools never write to production.
39
59
 
40
- ## Client config
60
+ ## Connect your agent
61
+
62
+ Two commands, one per agent CLI. They write the config the CLI already reads, so nothing is
63
+ hand-edited and no token is pasted by hand:
64
+
65
+ ```sh
66
+ plupin login # once: mints the OAuth access token the hosted surface verifies
67
+ plupin connect claude # -> ~/.claude.json
68
+ plupin connect codex # -> ~/.codex/config.toml
69
+ ```
70
+
71
+ Each writes two servers, because the platform has two surfaces and an agent needs both:
72
+
73
+ | server | transport | what an agent gets |
74
+ |---|---|---|
75
+ | `plupin` | stdio, `bunx -y @plupin/cli mcp` | the local tools in this document: `manifest_check`, `dev_start`, `dev_status`, `dev_stop`, `docs` |
76
+ | `plupin-hosted` | streamable HTTP, `<api>/mcp` | the hosted tools, `emote_new` / `emote_preview` / `emote_push` among them |
77
+
78
+ **Why the user-level file and not a project one.** The hosted entry carries a bearer token, and a
79
+ project config (`.mcp.json` beside the game) is a file that gets committed: one `git add .` would put
80
+ a live account token in a repository, and in its history. The user-level file also works from any
81
+ directory, including a build folder that is not a repository. The token is written into that file,
82
+ mode 600, and `plupin connect` never prints it.
83
+
84
+ After writing, the command asks the hosted surface for `tools/list` with the token it just wrote and
85
+ prints the count, so the receipt is a measurement. A refusal is reported as the status the server
86
+ answered (401 means the token expired: `plupin login` again) and the config is still there.
87
+
88
+ Re-running is safe and idempotent. Only the platform's own entries are touched: another server you
89
+ added by hand and every unrelated key in `~/.claude.json` survive byte for byte, and Codex's
90
+ `[mcp_servers.plupin]` table is replaced in place, duplicates and a stale `[.env]` sub-table removed.
91
+
92
+ ### Claude Code
93
+
94
+ `plupin connect claude` writes these two entries under `mcpServers` in `~/.claude.json`:
41
95
 
42
- Claude Code / any MCP client, run from the repo:
96
+ ```json
97
+ {
98
+ "plupin": {
99
+ "type": "stdio",
100
+ "command": "bunx",
101
+ "args": ["-y", "@plupin/cli", "mcp"]
102
+ },
103
+ "plupin-hosted": {
104
+ "type": "http",
105
+ "url": "https://api.plupin.com/mcp",
106
+ "headers": { "Authorization": "Bearer <the token plupin login stored>" }
107
+ }
108
+ }
109
+ ```
110
+
111
+ `CLAUDE_CONFIG_DIR` moves that file (a second profile, a container), which is also how the CLI's
112
+ tests drive it without touching a real one.
113
+
114
+ ### Codex CLI
115
+
116
+ `plupin connect codex` writes these tables into `~/.codex/config.toml`. `CODEX_HOME` moves the file.
117
+
118
+ ```toml
119
+ [mcp_servers.plupin]
120
+ command = "bunx"
121
+ args = ["-y", "@plupin/cli", "mcp"]
122
+
123
+ [mcp_servers.plupin-hosted]
124
+ url = "https://api.plupin.com/mcp"
125
+ http_headers = { Authorization = "Bearer <the token plupin login stored>" }
126
+ ```
127
+
128
+ `http_headers` is the field Codex reads for a streamable-HTTP server (the same one
129
+ `codex mcp add --url` writes), so the token lives in the 0600 config instead of an environment
130
+ variable every shell has to export. `bearer_token_env_var` is the alternative when the token should
131
+ stay in the environment instead.
132
+
133
+ ### By hand
134
+
135
+ The published package keeps the snippet one line long:
43
136
 
44
137
  ```json
45
138
  {
46
139
  "mcpServers": {
47
- "plus1": {
48
- "command": "bun",
49
- "args": ["run", "/absolute/path/to/plus1/packages/cli/src/bin.ts", "mcp"],
140
+ "plupin": {
141
+ "command": "bunx",
142
+ "args": ["-y", "@plupin/cli", "mcp"],
50
143
  "cwd": "/absolute/path/to/your-game"
51
144
  }
52
145
  }
53
146
  }
54
147
  ```
55
148
 
56
- Once `@plupin/cli` is published, `args` becomes `["-y", "@plupin/cli", "mcp"]`.
149
+ `cwd` is what `manifest_check` and `dev_start` resolve a relative `dir` against; a client that
150
+ starts the server in the project root can leave it out. To run from a checkout instead of the
151
+ published package:
152
+
153
+ ```json
154
+ { "command": "bun", "args": ["run", "/absolute/path/to/plupin/packages/cli/src/bin.ts", "mcp"] }
155
+ ```
57
156
 
58
157
  ## Session
59
158
 
@@ -88,7 +88,7 @@ frame()
88
88
  ## Local play
89
89
 
90
90
  ```bash
91
- bunx plupin dev ./dist --port 8787
91
+ bunx @plupin/cli dev ./dist --port 8787
92
92
  # game http://127.0.0.1:8787
93
93
  # rooms http://127.0.0.1:8787/api/play/dude-theft/rooms
94
94
  ```
@@ -98,12 +98,12 @@ production `RelayRoom` class, so a frame you see locally is a frame the platform
98
98
  game twice and both tabs are in the same room; no `url` override needed because the game and the
99
99
  API share an origin.
100
100
 
101
- `plupin deploy` is not implemented yet: a build folder cannot be published from the CLI today.
101
+ `plupin deploy` ships in the same package, so a build folder can be published from the CLI today.
102
102
 
103
103
  ## Live (planned)
104
104
 
105
105
  ```bash
106
- npx plupin deploy ./dist
106
+ npx @plupin/cli deploy ./dist
107
107
  # → https://dude-theft.plupin.com
108
108
  ```
109
109
 
@@ -0,0 +1,73 @@
1
+ # Randomness
2
+
3
+ Plupin has one source of randomness, and this page is the rule that keeps it that way.
4
+
5
+ ## The invariant
6
+
7
+ > Games never roll their own RNG for anything a player pays for. Paid random outcomes happen on the
8
+ > platform, in one transaction, from the platform's CSPRNG. Free random outcomes may ask the platform
9
+ > for the number, so a game that wants randomness has one place to get it.
10
+
11
+ Two halves, one reason. A player who pays Sigma for a random cosmetic must be able to trust the roll
12
+ and the money move together: they are charged once, they receive what the roll decided, and both are
13
+ recorded. A game cannot provide that — it runs creator code on a game address with no wallet
14
+ authority ([ADR-0018](../architecture/adr/0018-game-address-and-identity.md)) — so a game never
15
+ receives the ability to spend, and the platform never takes the roll from the game.
16
+
17
+ The second half is convenience with the same guarantee: a game that wants its own cosmetic
18
+ randomness asks the platform instead of carrying a generator, so the answer is the same CSPRNG and
19
+ the same arithmetic a paid draw uses.
20
+
21
+ ## What the source is
22
+
23
+ `packages/api/src/domains/random` is the only implementation:
24
+
25
+ - `cryptoUint32()` reads one uint32 from the Workers runtime's WebCrypto
26
+ (`crypto.getRandomValues`). No seed, no counter, no clock, nothing a player can influence, and no
27
+ `Math.random`: a non-cryptographic generator's state can be recovered from its outputs, which is
28
+ exactly the property a paid outcome may not have.
29
+ - `uniformBelow(range)` turns that into an unbiased integer in a range, rejecting the tail values
30
+ that would otherwise make low outcomes slightly likelier.
31
+ - `pickWeighted(entries)` maps one offset onto a weight table. The offset is the audit trail: the
32
+ same table and the same offset always name the same entry.
33
+
34
+ A future external beacon (a lavaRand-style delayed seed) would replace the body of `cryptoUint32` and
35
+ nothing else. No beacon is a dependency today.
36
+
37
+ ## Paid draws
38
+
39
+ A creator publishes a **pool**: 2–24 live listing ids, each with a relative weight, plus the Sigma one
40
+ draw costs. The pool is a listing, so it enters the same moderation queue (`pending` → `live` or
41
+ `rejected` with a reason) and only an admin decision makes it drawable. A pool whose listing was taken
42
+ down loses that entry; a pool with nothing left refuses the draw instead of charging for it.
43
+
44
+ A draw is one transaction in `@plupin/api/domains/gacha`:
45
+
46
+ 1. the draw row, which owns the request key and the CSPRNG offset;
47
+ 2. the Sigma debit (`gacha_draw` in the ledger) and the pool owner's 90% (`gacha_sale`, plus the
48
+ standard creator earning);
49
+ 3. the cosmetic grant into the player's inventory.
50
+
51
+ Any failure rolls all three back, so an empty wallet leaves no row, no item and no ledger entry. A
52
+ repeated request key returns the recorded draw (`replayed: true`) and never re-rolls, including when
53
+ the pool was taken down in between.
54
+
55
+ Rules a player can rely on:
56
+
57
+ - the pool owner cannot draw from their own pool (`SELF_DEALING`);
58
+ - an entry the player authored or already owns is not in the roll;
59
+ - the odds a pool advertises are the live entries' weights, computed by the server;
60
+ - an admin can read every draw with the pool, the item, the price and the stored offset.
61
+
62
+ ## Free rolls, from a game
63
+
64
+ ```ts
65
+ import { rollPlatformRandom } from "@plupin/game-sdk"
66
+
67
+ const result = await rollPlatformRandom([1, 2, 3])
68
+ if (result.status === "ok") grant(result.index)
69
+ ```
70
+
71
+ `POST /api/play/random` answers `{ index, roll, total }`. It takes no session and moves no money,
72
+ which is why it can live on the game origin; it is rate limited per address
73
+ (`LIMIT_RANDOM`, 120/minute). Full option table: [api.md](api.md#randomness).