@jgengine/editor 0.14.0 → 0.15.0

package/skills/jgengine-editor/reference.md

@@ -48,6 +48,50 @@ The bridge is trustworthy so agents author instead of hardcoding — every path
 - **One decode/migrate boundary.** `decodeEditorDocument` (`@jgengine/core/editor`) validates every field with a path-specific diagnostic (`$.markers[2].position`) and migrates forward; `import_document` and a `push_document_patch` **snapshot** both clear it, so a malformed or old document fails or migrates loudly rather than corrupting a live session.
 - **Document-global id uniqueness.** Placeable ids (markers/volumes/paths/notes) are one namespace: adds re-id on collision, and a single imported document that reuses an id is rejected with its path — a duplicate-id import is impossible. Combine paths (`mergeEditorDocuments`, duplicate, overlay) re-id instead.
 - **Schema-validated input.** `decodeEditorBridgeRequest` type-checks each field a method understands against the per-method schema before it reaches `handle` — a fuzzed value (string where a number belongs, scalar where an object belongs) is rejected at the `--rpc`/HTTP/stdio/agent-tool boundary, never cast in blind. Missing/unknown fields are left to `handle`'s guards so the boundary stays forward-compatible.
+- **Guards name the expected param.** A required field left off (or supplied under the wrong key) is caught by the verb's own guard and answered with the param it wanted, not a downstream crash — e.g. `import_document` without `json` returns `import_document requires a \`json\` param …` instead of letting the missing value reach `JSON.parse` as the literal string `"undefined"`.
+
+## Path / route authoring
+
+Author a new path (route, road, patrol lane, scatter region outline) headlessly with **`add_path`** — no `export_document`/`import_document` roundtrip. It dispatches the `addPath` session command (one undoable edit) and mutates `EditorDocument.paths`:
+
+```sh
+bun packages/editor/src/mcp/cli.ts --game <id> \
+  --rpc '{"method":"add_path","id":"patrol_1","points":[{"x":0,"z":0},{"x":10,"z":5},{"x":20,"z":0}],"label":"Patrol"}' --save
+```
+
+- **Required:** `id` and `points` (≥2 ordered `{x,z}`; `y` optional, defaults to `0`). Fewer than two points is rejected `ok:false`.
+- **Optional:** `kind` (defaults to `route`), `width`, `color`, `label`, `meta` — `meta` is validated against the kind's registered schema, same as `set_path`.
+- **Id collisions re-id.** Placeable ids are one document-global namespace, so a colliding `id` is minted a `_copy` suffix; the response's `result` carries the id the path actually landed under. Patch it afterwards with `set_path`/`set_meta`, or make gameplay reference the stable id/kind rather than copying coordinates.
+
+## Marker authoring
+
+Place a new point marker (a spawn, checkpoint, pickup, bounty, or a game's own custom kind) headlessly with **`add_marker`** — the one-shot counterpart to `add_path`, no `export_document`/`import_document` roundtrip and no hand-editing the JSON. It dispatches the `addMarker` session command (one undoable edit) and mutates `EditorDocument.markers`:
+
+```sh
+bun packages/editor/src/mcp/cli.ts --game <id> \
+  --rpc '{"method":"add_marker","id":"stash_pier","kind":"stash","x":168,"z":232,"label":"Pier'\''s end","meta":{"value":300}}' --save
+```
+
+- **Required:** `id`, `kind`, and `x`/`z` (`y` optional, defaults to `0`). A game reads its own custom kinds off the document (`editorLayers.markers.filter(m => m.kind === "stash")`), so no engine change is needed to introduce one.
+- **Optional:** `color`, `label`, `rotationY`, `meta` — `meta` is validated against the kind's registered schema when one exists (custom kinds skip validation), same as `set_marker`.
+- **Id collisions re-id** exactly as `add_path`; the response's `result` carries the id the marker landed under. Use `place_asset` instead when the marker should carry a mesh (it stamps `catalogId`/`meta.assetId`); `add_marker` is for logical, mesh-free markers.
+
+### Click-to-place custom kinds in the GUI
+
+`add_marker` is the *scripted* path (an agent/CLI types coordinates). To let a **designer click the world to drop** a game's own logical kind (a stash, checkpoint, bounty…), register it as a placeable scene kind with **`definePlaceableMarkerKind`** (`@jgengine/core/scene/sceneKinds`) — the light path that skips a full studio's schema/resolver:
+
+```ts
+// Games/<id>/src/editorKinds.ts — imported for its side effect by the game's editorLayers.ts
+import { definePlaceableMarkerKind } from "@jgengine/core/scene/sceneKinds";
+export const STASH_KIND = definePlaceableMarkerKind({
+  kind: "stash", label: "Stash", category: "My Game", accent: "#38d6c4",
+  fields: [{ type: "number", key: "value", label: "Payout ($)", default: 300, min: 0, step: 50 }],
+});
+```
+
+- The kind then appears as a click-to-place tool in the editor `+ Add` menu, grouped under its `category`: pick it, click the world to drop a marker, Shift-click to keep placing, tune the `fields` in the Inspector. The runtime is unchanged — the game still reads the kind off `editorLayers.markers`.
+- **Load path:** register from a module the editor loads. Importing your `editorKinds.ts` (side effect) from `editorLayers.ts` covers it — `loadGameLayers` imports `editorLayers.ts` for every editor session, and the game runtime imports it too, so one registration serves both.
+- `fields` also gives `add_marker`/`set_marker`/`set_meta` a schema to validate that kind's `meta` against; omit `fields` for a bare placeable marker.
 
 ## Pure API (`@jgengine/editor`)