@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.
- package/dist/cli.js +2342 -122
- package/dist/docs/README.md +2 -0
- package/dist/docs/api.md +30 -1
- package/dist/docs/character.md +82 -0
- package/dist/docs/checks.md +1 -1
- package/dist/docs/cli.md +90 -10
- package/dist/docs/integration.md +1 -1
- package/dist/docs/mcp.md +105 -6
- package/dist/docs/quickstart.md +3 -3
- package/dist/docs/randomness.md +73 -0
- package/dist/relay-room.mjs +96 -96
- package/package.json +1 -1
package/dist/docs/README.md
CHANGED
|
@@ -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
|
|
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
|
package/dist/docs/character.md
CHANGED
|
@@ -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.
|
package/dist/docs/checks.md
CHANGED
|
@@ -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 (`./.
|
|
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
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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.
|
|
226
|
-
npm publish --access public plupin-cli-0.
|
|
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.
|
|
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.
|
|
249
|
-
| published, then a bug found | `npm deprecate @plupin/cli@0.
|
|
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
|
package/dist/docs/integration.md
CHANGED
|
@@ -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/
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
"
|
|
48
|
-
"command": "
|
|
49
|
-
"args": ["
|
|
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
|
-
|
|
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
|
|
package/dist/docs/quickstart.md
CHANGED
|
@@ -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`
|
|
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).
|