@ignifx/editor-host 0.20.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/README.md +22 -0
- package/dist/grid.js +1 -1
- package/dist/grid.js.map +1 -1
- package/dist/index.d.ts +26 -26
- package/dist/index.js +61 -63
- package/dist/index.js.map +1 -1
- package/package.json +10 -10
- package/skills/editor-host/SKILL.md +43 -147
- package/skills/editor-host/references/protocol.md +140 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/editor-host",
|
|
3
|
-
"version": "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.
|
|
56
|
-
"@ignifx/3d": "0.
|
|
57
|
-
"@ignifx/core": "0.
|
|
58
|
-
"@ignifx/input": "0.
|
|
59
|
-
"@ignifx/physics": "0.
|
|
60
|
-
"@ignifx/physics-2d": "0.
|
|
61
|
-
"@ignifx/vite-plugin": "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.
|
|
67
|
-
"@ignifx/vite-plugin": "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.
|
|
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.
|
|
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
|
|
46
|
-
|
|
|
47
|
-
| `editorOrigin`
|
|
48
|
-
| `extensions`
|
|
49
|
-
| `bootScene`
|
|
50
|
-
| `heartbeatIntervalMs` | `1000`
|
|
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`
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
|
145
|
-
|
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `HostCapability.
|
|
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`
|
|
162
|
-
| `HostCapability.gameViewOnDemand`, `.gameViewSize`, `.gameView2d`
|
|
163
|
-
| `HostCapability.logRelay`, `isAppErrorData`, `LoggedError`
|
|
164
|
-
| `HOST_TEXT_MAX_LENGTH`, `HOST_LIST_MAX_LENGTH`
|
|
165
|
-
| `EditorHostErrorCode`
|
|
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 })
|
|
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
|
-
- **
|
|
360
|
-
`
|
|
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
|
-
`
|
|
446
|
-
`
|
|
447
|
-
|
|
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`.
|