@ignifx/editor-host 0.21.0 → 0.21.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignifx/editor-host",
3
- "version": "0.21.0",
3
+ "version": "0.21.1",
4
4
  "description": "ignifx editor host: runs a project's own engine inside the ignifx editor's scene view and play view, over a versioned protocol.",
5
5
  "keywords": [
6
6
  "ignifx"
@@ -52,19 +52,19 @@
52
52
  "typescript-native": "npm:typescript@7.0.2",
53
53
  "vite": "^8.2.2",
54
54
  "vitest": "^5.0.0",
55
- "@ignifx/2d": "0.21.0",
56
- "@ignifx/3d": "0.21.0",
57
- "@ignifx/core": "0.21.0",
58
- "@ignifx/input": "0.21.0",
59
- "@ignifx/physics": "0.21.0",
60
- "@ignifx/physics-2d": "0.21.0",
61
- "@ignifx/vite-plugin": "0.21.0"
55
+ "@ignifx/2d": "0.21.1",
56
+ "@ignifx/3d": "0.21.1",
57
+ "@ignifx/core": "0.21.1",
58
+ "@ignifx/input": "0.21.1",
59
+ "@ignifx/physics": "0.21.1",
60
+ "@ignifx/physics-2d": "0.21.1",
61
+ "@ignifx/vite-plugin": "0.21.1"
62
62
  },
63
63
  "peerDependencies": {
64
64
  "@babylonjs/lite": "1.34.0",
65
65
  "vite": "^8.2.2",
66
- "@ignifx/core": "0.21.0",
67
- "@ignifx/vite-plugin": "0.21.0"
66
+ "@ignifx/core": "0.21.1",
67
+ "@ignifx/vite-plugin": "0.21.1"
68
68
  },
69
69
  "peerDependenciesMeta": {
70
70
  "@ignifx/vite-plugin": {
@@ -3,7 +3,7 @@ name: editor-host
3
3
  description: Connects an ignifx project to the ignifx editor with @ignifx/editor-host: the Vite plugin that serves the editor's scene view from the project's own dev server, the virtual:ignifx/editor play controls a game's main.ts hands its app to (play, pause, step, stop, playState, playStateChanged, playStats, screenshot, queryRuntime, sendInput), and the host half of the editor protocol 0.3 over a MessagePort (hello/ready, heartbeat, and the scene document methods openScene, applyOps, readBack, select, pick, pickRect, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings, setAnimateMaterials, getColliderOutlines, sampleAnimation, sampleSpriteAnimation), including the 2D view mode. Use when wiring a project or template for the editor, when the user mentions @ignifx/editor-host, editorHostPlugin, attachEditorPlayControls, virtual:ignifx/editor, startEditorHost or /__ignifx_editor__/, or when debugging why the editor cannot connect to a view or why the scene view disagrees with the editor's document.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.21.0"
6
+ ignifx-version: "0.21.1"
7
7
  ---
8
8
 
9
9
  # @ignifx/editor-host
@@ -25,7 +25,7 @@ editor's, even though its name starts with `editor-`.
25
25
 
26
26
  ## Environment
27
27
 
28
- - Engine: ignifx `0.21.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
28
+ - Engine: ignifx `0.21.1`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
29
29
  - Peers: `@ignifx/core` and `@babylonjs/lite` (the scene view's gizmos); for the `./vite` entry,
30
30
  `@ignifx/vite-plugin` and `vite`.
31
31
  - A development dependency of the project, at the same version as its `@ignifx/core`.
@@ -42,12 +42,12 @@ export default defineConfig({
42
42
  });
43
43
  ```
44
44
 
45
- | Option | Default | Meaning |
46
- | --------------------- | ---------------------- | --------------------------------------------------------------------------- |
47
- | `editorOrigin` | required | The editor's origin; the only one that may frame the scene view or connect |
48
- | `extensions` | `"/src/extensions.ts"` | Module exporting `extensions()`; the scene view uses `[]` when it is absent |
49
- | `bootScene` | none | A scene address the scene view loads before it starts |
50
- | `heartbeatIntervalMs` | `1000` | Milliseconds between `heartbeat` notifications in both views |
45
+ | Option | Default | Meaning |
46
+ | --- | --- | --- |
47
+ | `editorOrigin` | required | The editor's origin; the only one that may frame the scene view or connect |
48
+ | `extensions` | `"/src/extensions.ts"` | Module exporting `extensions()`; the scene view uses `[]` when it is absent |
49
+ | `bootScene` | none | A scene address the scene view loads before it starts |
50
+ | `heartbeatIntervalMs` | `1000` | Milliseconds between `heartbeat` notifications in both views |
51
51
 
52
52
  Add `/// <reference types="@ignifx/editor-host/client" />` beside `@ignifx/vite-plugin/client` so
53
53
  `virtual:ignifx/editor` is typed.
@@ -137,32 +137,34 @@ host.dispose();
137
137
 
138
138
  ## Core APIs
139
139
 
140
- `skills/ignifx/references/api/editor-host.md` and `editor-host-vite.md` have the generated surface.
141
-
142
- | Member | What it does |
143
- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
144
- | `editorHostPlugin(options)` (`/vite`) | The two Vite plugins: the scene view's page (dev only) and `virtual:ignifx/editor` |
145
- | `attachEditorPlayControls(app)` | From `virtual:ignifx/editor`: hands the game's app to the editor; returns a detach |
146
- | `startEditorHost(options)` | Starts the scene view's host and its edit-mode app; resolves to a disposable `EditorHost` |
147
- | `listenForEditorPlayControls(options)` | What `virtual:ignifx/editor` calls in development: keeps the editor's port until `attach(app)` starts the controls on it |
148
- | `startEditorPlayControls(app, options)` | The play controls on their own, listening from the call |
149
- | `EDITOR_CONNECT_MESSAGE_TYPE`, `isEditorConnectMessage` | The window message that carries the port, and its check |
150
- | `PROTOCOL_VERSION`, `RpcErrorCode`, `isRpcMessage`, `isPlayState` | The protocol 0.3 values and checks, mirrored from `@ignifx/editor-protocol`; before 1.0 the major and minor must both match |
151
- | `SceneMethod`, `SceneNotification`, `SceneOp`, `isApplyOpsParams`, … | The scene document methods, notifications, the thirteen ops, and their guards |
152
- | `EditorHost.editorScene` | The persistent `editor` scene instance holding the host's own objects |
153
- | `EditorHost.assetChanged(change)` | Reloads an asset changed on disk in place and sends `assetReloaded`; the generated page calls it on `ignifx:asset-changed` |
154
- | `PlayMethod`, `PlayState` | `play`, `pause`, `step`, `stop`, and what each answers; `playState` reads the state without changing it |
155
- | `PlayNotification`, `PlayPhase`, `isPlayStateReport` | `playStateChanged` and `playState`'s `{ state: "playing" \| "paused" \| "stopped", frameCount, time }` |
156
- | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
157
- | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
158
- | `RenderViewMethod`, `HostCapability.gameView`, `.thumbnails` | `setGameView`/`gameViewFrame`: the document's own camera as an image; `renderThumbnail`: a model or prefab rendered alone |
159
- | `HostCapability.thumbnailMaterials`, `.thumbnailAtlases`, `.thumbnailTextures` | `renderThumbnail` also takes a `.material.json` (on a sphere), an `.atlas.json` and a `.png`/`.jpg`/`.jpeg`/`.webp` (fitted, transparent) |
140
+ `skills/ignifx/references/api/editor-host.md` and `editor-host-vite.md` in the `ignifx` package have
141
+ the generated surface. What each protocol method takes, answers and refuses is in
142
+ [`references/protocol.md`](references/protocol.md).
143
+
144
+ | Member | What it does |
145
+ | --- | --- |
146
+ | `editorHostPlugin(options)` (`/vite`) | The two Vite plugins: the scene view's page (dev only) and `virtual:ignifx/editor` |
147
+ | `attachEditorPlayControls(app)` | From `virtual:ignifx/editor`: hands the game's app to the editor; returns a detach |
148
+ | `startEditorHost(options)` | Starts the scene view's host and its edit-mode app; resolves to a disposable `EditorHost` |
149
+ | `listenForEditorPlayControls(options)` | What `virtual:ignifx/editor` calls in development: keeps the editor's port until `attach(app)` starts the controls on it |
150
+ | `startEditorPlayControls(app, options)` | The play controls on their own, listening from the call |
151
+ | `EDITOR_CONNECT_MESSAGE_TYPE`, `isEditorConnectMessage` | The window message that carries the port, and its check |
152
+ | `PROTOCOL_VERSION`, `RpcErrorCode`, `isRpcMessage`, `isPlayState` | The protocol 0.3 values and checks, mirrored from `@ignifx/editor-protocol`; before 1.0 the major and minor must both match |
153
+ | `SceneMethod`, `SceneNotification`, `SceneOp`, `isApplyOpsParams`, … | The scene document methods, notifications, the thirteen ops, and their guards |
154
+ | `EditorHost.editorScene` | The persistent `editor` scene instance holding the host's own objects |
155
+ | `EditorHost.assetChanged(change)` | Reloads an asset changed on disk in place and sends `assetReloaded`; the generated page calls it on `ignifx:asset-changed` |
156
+ | `PlayMethod`, `PlayState` | `play`, `pause`, `step`, `stop`, and what each answers; `playState` reads the state without changing it |
157
+ | `PlayNotification`, `PlayPhase`, `isPlayStateReport` | `playStateChanged` and `playState`'s `{ state: "playing" \| "paused" \| "stopped", frameCount, time }` |
158
+ | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
159
+ | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
160
+ | `RenderViewMethod`, `HostCapability.gameView`, `.thumbnails` | `setGameView`/`gameViewFrame`: the document's own camera as an image; `renderThumbnail`: a model or prefab rendered alone |
161
+ | `HostCapability.thumbnailMaterials`, `.thumbnailAtlases`, `.thumbnailTextures` | `renderThumbnail` also takes a `.material.json` (on a sphere), an `.atlas.json` and a `.png`/`.jpg`/`.jpeg`/`.webp` (fitted, transparent) |
160
162
  | `LightProbeBakeMethod`, `HostCapability.bakeLightProbes`, `isBakeLightProbesResult` | `bakeLightProbes { volume, counts? \| spacing?, directLight?, sky?, rays? }` bakes a `LightProbeVolume` over the live world and answers the `.probes.json` document; `bakeProgress` (≤ 10/s), `cancelBake`; a document change cancels it |
161
- | `SceneMethod.pickRect`, `HostCapability.pickRect`, `PICK_RECT_MAX_ENTITIES` | Box selection: the document entities whose drawn bounds a view rectangle overlaps or contains, capped at 2 000 with `truncated` |
162
- | `HostCapability.gameViewOnDemand`, `.gameViewSize`, `.gameView2d` | `gameViewFrame` answers while the host is hidden, takes `width`/`height`, and renders a `Camera2D` scene's sprites |
163
- | `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
164
- | `HOST_TEXT_MAX_LENGTH`, `HOST_LIST_MAX_LENGTH` | The editor's caps on a report's strings (1 MiB) and lists (4096); both views clip to them, a string ending `… [clipped]` |
165
- | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
163
+ | `SceneMethod.pickRect`, `HostCapability.pickRect`, `PICK_RECT_MAX_ENTITIES` | Box selection: the document entities whose drawn bounds a view rectangle overlaps or contains, capped at 2 000 with `truncated` |
164
+ | `HostCapability.gameViewOnDemand`, `.gameViewSize`, `.gameView2d` | `gameViewFrame` answers while the host is hidden, takes `width`/`height`, and renders a `Camera2D` scene's sprites |
165
+ | `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
166
+ | `HOST_TEXT_MAX_LENGTH`, `HOST_LIST_MAX_LENGTH` | The editor's caps on a report's strings (1 MiB) and lists (4096); both views clip to them, a string ending `… [clipped]` |
167
+ | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
166
168
 
167
169
  ## Recipes
168
170
 
@@ -305,7 +307,7 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
305
307
  own dev server. A mismatch is silent by design: the host just never connects.
306
308
  - **Every view reload needs a new port.** A transferred `MessagePort` cannot be posted twice; the
307
309
  editor makes a fresh `MessageChannel` on each `load`, and the host closes the previous port.
308
- - **The scene view runs in edit mode** (`createApp({ editMode: true })`, ADR-0028): a script gets no
310
+ - **The scene view runs in edit mode** (`createApp({ editMode: true })`): a script gets no
309
311
  callback unless its class sets `static runInEditMode = true`, and physics does not step. Pass
310
312
  `editMode: false` to `startEditorHost` to run it as a second copy of the game. The play view is the
311
313
  game's own app and is never in edit mode.
@@ -315,124 +317,16 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
315
317
  - **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
316
318
  module graph sends a full reload to every page when an update reaches a module that does not
317
319
  accept it.
318
- - **An op's build problems come back with its command.** `applyOps` answers
319
- `{ applied, failures, warnings }`. `warnings` holds `{ code, message }` issues, as `openScene`'s
320
- does, for everything the subtrees its ops built or rebuilt reported: an override that names
321
- nothing in the prefab, or a reference that resolves nowhere in the document. The op still
322
- applies. Each issue is also a `log` warning for the Console. The answer is the record tied to the
323
- command. A host from before this field sends no `warnings`.
324
- - **A schema says what its class requires and what it extends.** A component's `getSchemas` entry
325
- carries `requires` (the type ids `addComponent` adds when missing) and `extends` (the registered
326
- classes its class derives from, nearest first; `[]` when none). The engine counts a component
327
- whose class extends a required one as present, so a required id is present on an entity when a
328
- component has that id or lists it in `extends`. A host from before `extends` sends no such member.
329
320
  - **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
330
321
  its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
331
322
  `readBack` and `frame` answer `noScene` while no scene is open.
332
- - **The play view's `screenshot` needs a running game.** It takes the scene view's parameters and
333
- answers the same `{ dataUrl, width, height }` from the game's canvas, paused or not. While the
334
- frame loop does not run (before Play, after `stop` or `step`) it answers `notPlaying`, and before
335
- the first frame `notReady`. Only a game with a canvas lists `screenshot` in `ready`; an older or
336
- headless play view answers `methodNotFound`.
337
- - **The play view's `queryRuntime` reads one live entity.** `{ entity: uid, components?: typeId[] }`
338
- answers the entity as `serializeEntity` writes it (serialized props only, no expressions), with at
339
- most 64 components, prop strings clipped to 64 Ki, objects cut to 256 keys, keys and names
340
- clipped to 256 characters (`omittedEntries` counts the keys, items and tags left out), and the
341
- whole answer within 262,144 characters of JSON: components past the budget, in order, are counted
342
- in `omittedComponents`. An
343
- unknown uid answers `unknownEntity`; a stopped game `notPlaying`. A paused or stepped game
344
- answers, so pause, `step`, `queryRuntime` reads a game frame by frame. Spawned entities get new
345
- uids each run; a scene's own keep their file uids.
346
- - **The play view's `sendInput` drives the game's own input.** `{ events }` (1 to 64) of
347
- `{ type: "keydown" | "keyup", control: "w" }` (a `<Keyboard>` control name) and
348
- `{ type: "pointermove" | "pointerdown" | "pointerup", x, y, button? }` (`x`, `y` as 0–1 fractions of
349
- the canvas) go to `app.input.simulateEvent` and resolve on the game's next frame; nothing reaches
350
- the DOM, the editor's window or the OS. A bad event or unknown key answers `invalidParams` and
351
- queues nothing; a stopped game `notPlaying`. A stepped game resolves the events only on its next
352
- `step`, so step after sending. A held key stays down until its `keyup`. Only a game
353
- with `app.input` lists `sendInput`; others answer `methodNotFound`.
354
323
  - **The scene view keeps the project's `rendering.msaaSamples`.** The gizmos and the outline draw in
355
324
  core's render overlay (`app.renderer.openOverlay()`), which works at every MSAA setting.
356
325
  - **A headless host lists only `heartbeat`.** Without a canvas there are no gizmos, no `screenshot`,
357
326
  and every `pick` misses without a `ray`; `setGizmo` and `screenshot` then answer `methodNotFound`. In headless
358
327
  tests, asset loads after `start()` settle only when something calls `app.step()`.
359
- - **A `pick` carries the camera ray, hit or miss.** On a canvas the answer adds
360
- `ray: { origin, direction }` (world space, from the editor camera's `screenToRay` at the converted
361
- backing pixel) and, when the ray crosses `z = 0` ahead of the camera, `plane: [x, y, 0]`. A 3D
362
- editor drops an asset where `ray` meets `y = 0`; a 2D one uses `plane`.
363
- - **Box selection is `pickRect`.** `pickRect { x0, y0, x1, y1, unit, mode? }` takes two opposite
364
- corners in `pick`'s unit and answers `{ entities, truncated }`: the document entities whose drawn
365
- bounds (each visible mesh's 8 bounds corners projected through the editor camera; sprites and
366
- tilemaps too in 2D view mode) overlap the rectangle, or with `mode: "contain"` lie wholly inside
367
- it and in front of the camera, in document order. A prefab member counts for its instance root,
368
- as with `pick`; an entity that draws nothing (a light, an empty) is never listed.
369
- - **The 2D view mode needs a canvas, not a dependency.** On a canvas the host lists `viewMode2d` and
370
- `pick2d`. `openScene` and `sceneOpened` report `viewMode`: `"2d"` for `twoD.mode: "sprite"` or a
371
- scene whose cameras are all `Camera2D`. `setViewMode { mode: "2d" }` enables the host's own
372
- `Camera2D` (priority 1 000 000) and makes the 3D editor camera orthographic over the same
373
- rectangle; the level's `Camera2D` is never changed. In 2D mode `frame` fits sprite quads and
374
- tilemaps, and `pick` and clicks use `app.twoD.pickAt` (unpickable sprites included): a hit's
375
- `point` is on `z = 0` and its `distance` is `null`. The host finds `app.twoD` and the 2D classes
376
- by name, so a project without `@ignifx/2d` still gets an orthographic 2D view of its meshes.
377
- - **A pose on demand.** `sampleAnimation { entity, state, normalizedTime, parameters? }` calls
378
- `Animator.sample` on the entity's `Animator` and answers `{ posed }`; the edit-mode view keeps
379
- the pose until the next sample. `posed` is `false` while the clips load, when the model lacks a clip the state names, and
380
- always headless. Names are capped at 256 characters and `parameters` at 64 values. An
381
- entity without an `Animator`, or an engine refusal such as an unknown state (`data.code`
382
- `IGX-1202`), is `invalidParams`. The host finds `ignifx/Animator` by type id, so a project
383
- without `@ignifx/3d` simply has none.
384
- - **A sprite frame on demand.** Every scene host lists the `spriteAnimation` capability and answers
385
- `sampleSpriteAnimation { entity, clip, frame }` or `{ entity, clip, time }` (exactly one of the
386
- two; `time` in seconds) with `{ posed }`: it calls `SpriteAnimator.sample(clip, frame)` or
387
- `sampleTime(clip, time)` from `@ignifx/2d`, which writes the frame onto the entity's
388
- `SpriteRenderer` and stops playback there. `posed` is `false` while the animation document or the
389
- atlas loads. An entity without a `SpriteAnimator`, or an unknown clip (`data.code` `IGX-1108`), is
390
- `invalidParams`. The host finds `ignifx/SpriteAnimator` by type id, as it does the `Animator`.
391
- - **Settings over the protocol.** `describeSettings` answers `{ sections, values }`: core's
392
- `describeSettings(app)` with each section's `settingsJsonSchema` entry as `propsSchema`, and the
393
- values the app resolved, in the settings form (`{ x, y, z }`, `{ r, g, b, a }`). No notification
394
- announces settings; ask again after the project's settings change.
395
- - **Materials and collider gizmos.** `setAnimateMaterials { enabled }` sets
396
- `app.renderer.animateMaterialsInEditMode` (on at every start, so re-send it after `ready`).
397
- `getColliderOutlines { entities }` answers `{ outlines }`: per enabled collider of each open
398
- entity, its uid, the component's uid, `isTrigger`, and world-space `lines` (six numbers a
399
- segment), read from `app.physics` / `app.physics2d` by shape, plus `truncated` when the request
400
- passed 256 entities or the lines 600 000 numbers. Edit mode keeps physics bodies on the
401
- transforms the editor moves without stepping, so the outlines and physics queries follow.
402
- - **The grid.** With a canvas the scene host lists the `grid` capability and draws a grid: a
403
- ground grid at `y = 0` in 3D view mode (depth-tested, centred under the eye, coarser the higher
404
- the eye, faded out before its edge) and a faint grid over the 2D view (one line per layer pixel
405
- from zoom 8). `setGrid { visible?, size?, overlay?, height? }` sets the whole grid each call; a field left out takes
406
- its default (`visible: true`, `size: 1` metre, 0.001 to 1000). The grid starts visible at every
407
- load, so re-send the editor's state after `ready`. It is never picked or saved, and never in the
408
- play view; `screenshot` includes it while it is visible. With the `gridOverlay` capability,
409
- `setGrid` also takes `overlay` (default `false`: the 3D grid draws over the scene, fainter, so a
410
- floor mesh does not hide it) and `height` (default `0`: the 3D grid plane's world y, -100 000 to
411
- 100 000 metres); an older host ignores both.
412
- - **Live tilemap painting.** With a canvas the scene host lists `tilemapCells` and answers
413
- `setTilemapCells { asset, layer, cells }`: `cells` are flat `[index, tile, …]` pairs in the
414
- `.tilemap.json` file's order (row-major, top row first), `layer` a layer name or index. Every
415
- loaded `Tilemap` of the open scene whose `map` is `asset` is written with `Tilemap.setCells`, so
416
- the view shows the paint at once; the answer is `{ tilemaps, changed }`. The file is not
417
- written: save it, or a reopen shows the file's cells again.
418
- - **Editor lines.** With a canvas the scene host lists `editorLines` and draws the editor's own
419
- line sets over the view in 3D and 2D: `setEditorLines { id, lines, color? }` (six numbers a
420
- segment, world metres, as `getColliderOutlines` answers; `color` `[r, g, b, a?]`) replaces the
421
- set `id`, `clearEditorLines { id? }` removes one or all. At most 64 sets of 100 000 segments;
422
- never picked, saved or drawn in the game view; re-send them after `ready`.
423
- - **A changed asset reloads in place, not the view.** The scene view's page hands every
424
- `ignifx:asset-changed` event to `host.assetChanged`, which calls `app.assets.reload(address)` for an
425
- asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
426
- `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
427
- through another prefab, with their uids, transforms, overrides and document children; `readBack`
428
- then writes the new prefab's hash. An override the new prefab no longer has, like any problem
429
- building an op's subtree, is a `log` warning worded as a reopen's (an op's problems also come back
430
- in `applyOps`' `warnings`). A rebuilt subtree resolves its
431
- references, the ones its overrides hold included, against the whole document, as a reopen does,
432
- and so do the references into it from the rest of the document, other instances' overrides
433
- included. The host sends `assetReloaded { address, type, entities }` (the rebuilt instance
434
- roots) once the new value is in. A texture, a removed file and the open document's own file are
435
- left alone and send nothing.
328
+ - **View state resets at every load.** The grid, the editor's line sets and
329
+ `setAnimateMaterials` start from their defaults whenever a view loads, so re-send them after `ready`.
436
330
  - **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
437
331
  in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
438
332
 
@@ -442,6 +336,8 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
442
336
 
443
337
  ## Where to look next
444
338
 
445
- `docs/architecture/17-editor-host.md` for the design, the protocol and the security rules ·
446
- `packages/editor-host/api/editor-host.api.md` and `editor-host-vite.api.md` for the exact surface ·
447
- `skills/ignifx/SKILL.md` for the engine.
339
+ [`references/protocol.md`](references/protocol.md) for each protocol method's parameters, answers and
340
+ limits. The entry skill is `skills/ignifx/SKILL.md` in the `ignifx` package: `node_modules/ignifx/` in
341
+ an installed project, the repository root in the engine repository. Under it,
342
+ `references/api/editor-host.md` and `references/api/editor-host-vite.md` have every exact signature,
343
+ and `references/concepts/lifecycle.md` §8 covers edit mode.
@@ -0,0 +1,140 @@
1
+ # Editor protocol: method reference
2
+
3
+ What each method of the editor protocol takes, answers and refuses, beyond the tables in
4
+ [`../SKILL.md`](../SKILL.md). The scene view and the play view are separate hosts with separate
5
+ method sets; a host lists what it supports in the `capabilities` of its `ready` answer, and a method
6
+ it does not have answers `methodNotFound`.
7
+
8
+ ## Scene view: the document
9
+
10
+ **An op's build problems come back with its command.** `applyOps` answers
11
+ `{ applied, failures, warnings }`. `warnings` holds `{ code, message }` issues, as `openScene`'s
12
+ does, for everything the subtrees its ops built or rebuilt reported: an override that names
13
+ nothing in the prefab, or a reference that resolves nowhere in the document. The op still
14
+ applies. Each issue is also a `log` warning for the Console. The answer is the record tied to the
15
+ command. A host from before this field sends no `warnings`.
16
+
17
+ **A schema says what its class requires and what it extends.** A component's `getSchemas` entry
18
+ carries `requires` (the type ids `addComponent` adds when missing) and `extends` (the registered
19
+ classes its class derives from, nearest first; `[]` when none). The engine counts a component
20
+ whose class extends a required one as present, so a required id is present on an entity when a
21
+ component has that id or lists it in `extends`. A host from before `extends` sends no such member.
22
+
23
+ **Settings over the protocol.** `describeSettings` answers `{ sections, values }`: core's
24
+ `describeSettings(app)` with each section's `settingsJsonSchema` entry as `propsSchema`, and the
25
+ values the app resolved, in the settings form (`{ x, y, z }`, `{ r, g, b, a }`). No notification
26
+ announces settings; ask again after the project's settings change.
27
+
28
+ **A changed asset reloads in place, not the view.** The scene view's page hands every
29
+ `ignifx:asset-changed` event to `host.assetChanged`, which calls `app.assets.reload(address)` for an
30
+ asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
31
+ `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
32
+ through another prefab, with their uids, transforms, overrides and document children; `readBack`
33
+ then writes the new prefab's hash. An override the new prefab no longer has, like any problem
34
+ building an op's subtree, is a `log` warning worded as a reopen's (an op's problems also come back
35
+ in `applyOps`' `warnings`). A rebuilt subtree resolves its
36
+ references, the ones its overrides hold included, against the whole document, as a reopen does,
37
+ and so do the references into it from the rest of the document, other instances' overrides
38
+ included. The host sends `assetReloaded { address, type, entities }` (the rebuilt instance
39
+ roots) once the new value is in. A texture, a removed file and the open document's own file are
40
+ left alone and send nothing.
41
+
42
+ ## Scene view: picking and the view
43
+
44
+ **A `pick` carries the camera ray, hit or miss.** On a canvas the answer adds
45
+ `ray: { origin, direction }` (world space, from the editor camera's `screenToRay` at the converted
46
+ backing pixel) and, when the ray crosses `z = 0` ahead of the camera, `plane: [x, y, 0]`. A 3D
47
+ editor drops an asset where `ray` meets `y = 0`; a 2D one uses `plane`.
48
+
49
+ **Box selection is `pickRect`.** `pickRect { x0, y0, x1, y1, unit, mode? }` takes two opposite
50
+ corners in `pick`'s unit and answers `{ entities, truncated }`: the document entities whose drawn
51
+ bounds (each visible mesh's 8 bounds corners projected through the editor camera; sprites and
52
+ tilemaps too in 2D view mode) overlap the rectangle, or with `mode: "contain"` lie wholly inside
53
+ it and in front of the camera, in document order. A prefab member counts for its instance root,
54
+ as with `pick`; an entity that draws nothing (a light, an empty) is never listed.
55
+
56
+ **The 2D view mode needs a canvas, not a dependency.** On a canvas the host lists `viewMode2d` and
57
+ `pick2d`. `openScene` and `sceneOpened` report `viewMode`: `"2d"` for `twoD.mode: "sprite"` or a
58
+ scene whose cameras are all `Camera2D`. `setViewMode { mode: "2d" }` enables the host's own
59
+ `Camera2D` (priority 1 000 000) and makes the 3D editor camera orthographic over the same
60
+ rectangle; the level's `Camera2D` is never changed. In 2D mode `frame` fits sprite quads and
61
+ tilemaps, and `pick` and clicks use `app.twoD.pickAt` (unpickable sprites included): a hit's
62
+ `point` is on `z = 0` and its `distance` is `null`. The host finds `app.twoD` and the 2D classes
63
+ by name, so a project without `@ignifx/2d` still gets an orthographic 2D view of its meshes.
64
+
65
+ **The grid.** With a canvas the scene host lists the `grid` capability and draws a grid: a
66
+ ground grid at `y = 0` in 3D view mode (depth-tested, centred under the eye, coarser the higher
67
+ the eye, faded out before its edge) and a faint grid over the 2D view (one line per layer pixel
68
+ from zoom 8). `setGrid { visible?, size?, overlay?, height? }` sets the whole grid each call; a field left out takes
69
+ its default (`visible: true`, `size: 1` metre, 0.001 to 1000). The grid starts visible at every
70
+ load, so re-send the editor's state after `ready`. It is never picked or saved, and never in the
71
+ play view; `screenshot` includes it while it is visible. With the `gridOverlay` capability,
72
+ `setGrid` also takes `overlay` (default `false`: the 3D grid draws over the scene, fainter, so a
73
+ floor mesh does not hide it) and `height` (default `0`: the 3D grid plane's world y, -100 000 to
74
+ 100 000 metres); an older host ignores both.
75
+
76
+ **Editor lines.** With a canvas the scene host lists `editorLines` and draws the editor's own
77
+ line sets over the view in 3D and 2D: `setEditorLines { id, lines, color? }` (six numbers a
78
+ segment, world metres, as `getColliderOutlines` answers; `color` `[r, g, b, a?]`) replaces the
79
+ set `id`, `clearEditorLines { id? }` removes one or all. At most 64 sets of 100 000 segments;
80
+ never picked, saved or drawn in the game view; re-send them after `ready`.
81
+
82
+ **Materials and collider gizmos.** `setAnimateMaterials { enabled }` sets
83
+ `app.renderer.animateMaterialsInEditMode` (on at every start, so re-send it after `ready`).
84
+ `getColliderOutlines { entities }` answers `{ outlines }`: per enabled collider of each open
85
+ entity, its uid, the component's uid, `isTrigger`, and world-space `lines` (six numbers a
86
+ segment), read from `app.physics` / `app.physics2d` by shape, plus `truncated` when the request
87
+ passed 256 entities or the lines 600 000 numbers. Edit mode keeps physics bodies on the
88
+ transforms the editor moves without stepping, so the outlines and physics queries follow.
89
+
90
+ ## Scene view: posing and painting
91
+
92
+ **A pose on demand.** `sampleAnimation { entity, state, normalizedTime, parameters? }` calls
93
+ `Animator.sample` on the entity's `Animator` and answers `{ posed }`; the edit-mode view keeps
94
+ the pose until the next sample. `posed` is `false` while the clips load, when the model lacks a clip the state names, and
95
+ always headless. Names are capped at 256 characters and `parameters` at 64 values. An
96
+ entity without an `Animator`, or an engine refusal such as an unknown state (`data.code`
97
+ `IGX-1202`), is `invalidParams`. The host finds `ignifx/Animator` by type id, so a project
98
+ without `@ignifx/3d` simply has none.
99
+
100
+ **A sprite frame on demand.** Every scene host lists the `spriteAnimation` capability and answers
101
+ `sampleSpriteAnimation { entity, clip, frame }` or `{ entity, clip, time }` (exactly one of the
102
+ two; `time` in seconds) with `{ posed }`: it calls `SpriteAnimator.sample(clip, frame)` or
103
+ `sampleTime(clip, time)` from `@ignifx/2d`, which writes the frame onto the entity's
104
+ `SpriteRenderer` and stops playback there. `posed` is `false` while the animation document or the
105
+ atlas loads. An entity without a `SpriteAnimator`, or an unknown clip (`data.code` `IGX-1108`), is
106
+ `invalidParams`. The host finds `ignifx/SpriteAnimator` by type id, as it does the `Animator`.
107
+
108
+ **Live tilemap painting.** With a canvas the scene host lists `tilemapCells` and answers
109
+ `setTilemapCells { asset, layer, cells }`: `cells` are flat `[index, tile, …]` pairs in the
110
+ `.tilemap.json` file's order (row-major, top row first), `layer` a layer name or index. Every
111
+ loaded `Tilemap` of the open scene whose `map` is `asset` is written with `Tilemap.setCells`, so
112
+ the view shows the paint at once; the answer is `{ tilemaps, changed }`. The file is not
113
+ written: save it, or a reopen shows the file's cells again.
114
+
115
+ ## Play view
116
+
117
+ **The play view's `screenshot` needs a running game.** It takes the scene view's parameters and
118
+ answers the same `{ dataUrl, width, height }` from the game's canvas, paused or not. While the
119
+ frame loop does not run (before Play, after `stop` or `step`) it answers `notPlaying`, and before
120
+ the first frame `notReady`. Only a game with a canvas lists `screenshot` in `ready`; an older or
121
+ headless play view answers `methodNotFound`.
122
+
123
+ **The play view's `queryRuntime` reads one live entity.** `{ entity: uid, components?: typeId[] }`
124
+ answers the entity as `serializeEntity` writes it (serialized props only, no expressions), with at
125
+ most 64 components, prop strings clipped to 64 Ki, objects cut to 256 keys, keys and names
126
+ clipped to 256 characters (`omittedEntries` counts the keys, items and tags left out), and the
127
+ whole answer within 262,144 characters of JSON: components past the budget, in order, are counted
128
+ in `omittedComponents`. An
129
+ unknown uid answers `unknownEntity`; a stopped game `notPlaying`. A paused or stepped game
130
+ answers, so pause, `step`, `queryRuntime` reads a game frame by frame. Spawned entities get new
131
+ uids each run; a scene's own keep their file uids.
132
+
133
+ **The play view's `sendInput` drives the game's own input.** `{ events }` (1 to 64) of
134
+ `{ type: "keydown" | "keyup", control: "w" }` (a `<Keyboard>` control name) and
135
+ `{ type: "pointermove" | "pointerdown" | "pointerup", x, y, button? }` (`x`, `y` as 0–1 fractions of
136
+ the canvas) go to `app.input.simulateEvent` and resolve on the game's next frame; nothing reaches
137
+ the DOM, the editor's window or the OS. A bad event or unknown key answers `invalidParams` and
138
+ queues nothing; a stopped game `notPlaying`. A stepped game resolves the events only on its next
139
+ `step`, so step after sending. A held key stays down until its `keyup`. Only a game
140
+ with `app.input` lists `sendInput`; others answer `methodNotFound`.