@ignifx/editor-host 0.10.0 → 0.12.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/error-codes.d.ts +3 -3
- package/dist/error-codes.js +3 -3
- package/dist/error-codes.js.map +1 -1
- package/dist/index.d.ts +262 -15
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1727 -741
- package/dist/index.js.map +1 -1
- package/dist/vite.d.ts +8 -3
- package/dist/vite.d.ts.map +1 -1
- package/dist/vite.js +305 -7
- package/dist/vite.js.map +1 -1
- package/package.json +10 -6
- package/skills/editor-host/SKILL.md +49 -16
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: editor-host
|
|
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), 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, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings), including the 2D view mode (an editor Camera2D and app.twoD.pickAt picking). 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.
|
|
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), 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, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings, setAnimateMaterials, getColliderOutlines, sampleAnimation), including the 2D view mode (an editor Camera2D and app.twoD.pickAt picking). 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.12.0"
|
|
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.12.0`; 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`.
|
|
@@ -38,7 +38,7 @@ import { editorHostPlugin } from "@ignifx/editor-host/vite";
|
|
|
38
38
|
import { defineConfig } from "vite";
|
|
39
39
|
|
|
40
40
|
export default defineConfig({
|
|
41
|
-
plugins: [ignifx(), editorHostPlugin({ editorOrigin: process.env.IGNIFX_EDITOR_ORIGIN ?? "ignifx://app" })],
|
|
41
|
+
plugins: [ignifx(), editorHostPlugin({ editorOrigin: process.env.IGNIFX_EDITOR_ORIGIN ?? "ignifx-editor://app" })],
|
|
42
42
|
});
|
|
43
43
|
```
|
|
44
44
|
|
|
@@ -55,7 +55,7 @@ Add `/// <reference types="@ignifx/editor-host/client" />` beside `@ignifx/vite-
|
|
|
55
55
|
## Mental model
|
|
56
56
|
|
|
57
57
|
```
|
|
58
|
-
editor window (ignifx://app)
|
|
58
|
+
editor window (ignifx-editor://app)
|
|
59
59
|
├── <iframe> scene view http://127.0.0.1:<port>/__ignifx_editor__/
|
|
60
60
|
│ generated module → startEditorHost({ extensions(), scripts, settings, manifest })
|
|
61
61
|
│ owns its app, in edit mode; hostKind "scene"
|
|
@@ -68,6 +68,7 @@ each view ◀── MessagePort ──▶ editor JSON-RPC 2.0, protocol 0.3
|
|
|
68
68
|
connect (window message, origin-checked) → hello → ready → ping/pong, heartbeat
|
|
69
69
|
scene view: schemasChanged → openScene → applyOps… / readBack / select / pick / frame / setGizmo / screenshot
|
|
70
70
|
/ setViewMode / getSchemas / describeSettings (on request only)
|
|
71
|
+
/ setAnimateMaterials / getColliderOutlines / sampleAnimation
|
|
71
72
|
← sceneOpened, selectionChanged, transformDragging/Dragged, hotReloaded, assetReloaded,
|
|
72
73
|
hostError, log
|
|
73
74
|
play view: play / pause / step / stop / playState / playStats
|
|
@@ -85,7 +86,8 @@ carry `Content-Security-Policy: frame-ancestors <editorOrigin>`.
|
|
|
85
86
|
The editor owns the scene document; the scene view mirrors it. `openScene` sends the whole file
|
|
86
87
|
object (it may hold unsaved edits) and the host builds it with `world.loadSceneFile`, keeping the
|
|
87
88
|
file's uids. Every command the editor applies to its document goes to the host as `applyOps`, the
|
|
88
|
-
same ops; any failure means the mirror drifted, and the editor resends `openScene`.
|
|
89
|
+
same ops; any failure means the mirror drifted, and the editor resends `openScene`. The answer's
|
|
90
|
+
`warnings` lists what building the command's entities reported, as `openScene`'s does. What the user
|
|
89
91
|
does in the view comes back as notifications (`selectionChanged`, `transformDragged`) that the
|
|
90
92
|
editor turns into commands. The host never edits the document. When a script's hot reload changes a
|
|
91
93
|
field's default, the host gives the field its new default wherever the document leaves it out, and
|
|
@@ -101,14 +103,14 @@ A headless scene-view host and the editor's side of the handshake, in one Node p
|
|
|
101
103
|
import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
|
|
102
104
|
|
|
103
105
|
const frameWindow = new EventTarget();
|
|
104
|
-
const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
|
|
106
|
+
const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
|
|
105
107
|
|
|
106
108
|
// The editor's side: a fresh channel, with one end posted to the view's window.
|
|
107
109
|
const channel = new MessageChannel();
|
|
108
110
|
frameWindow.dispatchEvent(
|
|
109
111
|
new MessageEvent("message", {
|
|
110
112
|
data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
|
|
111
|
-
origin: "ignifx://app",
|
|
113
|
+
origin: "ignifx-editor://app",
|
|
112
114
|
ports: [channel.port2],
|
|
113
115
|
}),
|
|
114
116
|
);
|
|
@@ -151,6 +153,7 @@ host.dispose();
|
|
|
151
153
|
| `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
|
|
152
154
|
| `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
|
|
153
155
|
| `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
|
|
156
|
+
| `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]` |
|
|
154
157
|
| `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
|
|
155
158
|
|
|
156
159
|
## Recipes
|
|
@@ -187,13 +190,13 @@ import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorPlayControls
|
|
|
187
190
|
|
|
188
191
|
const app = await createApp({ headless: true });
|
|
189
192
|
const pageWindow = new EventTarget();
|
|
190
|
-
const controls = startEditorPlayControls(app, { editorOrigin: "ignifx://app", messageTarget: pageWindow });
|
|
193
|
+
const controls = startEditorPlayControls(app, { editorOrigin: "ignifx-editor://app", messageTarget: pageWindow });
|
|
191
194
|
|
|
192
195
|
const channel = new MessageChannel();
|
|
193
196
|
pageWindow.dispatchEvent(
|
|
194
197
|
new MessageEvent("message", {
|
|
195
198
|
data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
|
|
196
|
-
origin: "ignifx://app",
|
|
199
|
+
origin: "ignifx-editor://app",
|
|
197
200
|
ports: [channel.port2],
|
|
198
201
|
}),
|
|
199
202
|
);
|
|
@@ -231,12 +234,12 @@ app.dispose();
|
|
|
231
234
|
import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
|
|
232
235
|
|
|
233
236
|
const frameWindow = new EventTarget();
|
|
234
|
-
const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
|
|
237
|
+
const host = await startEditorHost({ editorOrigin: "ignifx-editor://app", headless: true, messageTarget: frameWindow });
|
|
235
238
|
const channel = new MessageChannel();
|
|
236
239
|
frameWindow.dispatchEvent(
|
|
237
240
|
new MessageEvent("message", {
|
|
238
241
|
data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
|
|
239
|
-
origin: "ignifx://app",
|
|
242
|
+
origin: "ignifx-editor://app",
|
|
240
243
|
ports: [channel.port2],
|
|
241
244
|
}),
|
|
242
245
|
);
|
|
@@ -290,7 +293,7 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
|
|
|
290
293
|
the build half is what turns it into an empty function. Without the plugin the import does not
|
|
291
294
|
resolve.
|
|
292
295
|
- **`editorOrigin` is exact.** It must equal `event.origin` as the browser reports it, with no path or
|
|
293
|
-
trailing slash: `ignifx://app` for the packaged editor, `http://localhost:<port>` for the editor's
|
|
296
|
+
trailing slash: `ignifx-editor://app` for the packaged editor, `http://localhost:<port>` for the editor's
|
|
294
297
|
own dev server. A mismatch is silent by design: the host just never connects.
|
|
295
298
|
- **Every view reload needs a new port.** A transferred `MessagePort` cannot be posted twice; the
|
|
296
299
|
editor makes a fresh `MessageChannel` on each `load`, and the host closes the previous port.
|
|
@@ -304,6 +307,17 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
|
|
|
304
307
|
- **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
|
|
305
308
|
module graph sends a full reload to every page when an update reaches a module that does not
|
|
306
309
|
accept it.
|
|
310
|
+
- **An op's build problems come back with its command.** `applyOps` answers
|
|
311
|
+
`{ applied, failures, warnings }`. `warnings` holds `{ code, message }` issues, as `openScene`'s
|
|
312
|
+
does, for everything the subtrees its ops built or rebuilt reported: an override that names
|
|
313
|
+
nothing in the prefab, or a reference that resolves nowhere in the document. The op still
|
|
314
|
+
applies. Each issue is also a `log` warning for the Console. The answer is the record tied to the
|
|
315
|
+
command. A host from before this field sends no `warnings`.
|
|
316
|
+
- **A schema says what its class requires and what it extends.** A component's `getSchemas` entry
|
|
317
|
+
carries `requires` (the type ids `addComponent` adds when missing) and `extends` (the registered
|
|
318
|
+
classes its class derives from, nearest first; `[]` when none). The engine counts a component
|
|
319
|
+
whose class extends a required one as present, so a required id is present on an entity when a
|
|
320
|
+
component has that id or lists it in `extends`. A host from before `extends` sends no such member.
|
|
307
321
|
- **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
|
|
308
322
|
its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
|
|
309
323
|
`readBack` and `frame` answer `noScene` while no scene is open.
|
|
@@ -324,18 +338,37 @@ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with
|
|
|
324
338
|
tilemaps, and `pick` and clicks use `app.twoD.pickAt` (unpickable sprites included): a hit's
|
|
325
339
|
`point` is on `z = 0` and its `distance` is `null`. The host finds `app.twoD` and the 2D classes
|
|
326
340
|
by name, so a project without `@ignifx/2d` still gets an orthographic 2D view of its meshes.
|
|
341
|
+
- **A pose on demand.** `sampleAnimation { entity, state, normalizedTime, parameters? }` calls
|
|
342
|
+
`Animator.sample` on the entity's `Animator` and answers `{ posed }`; the edit-mode view keeps
|
|
343
|
+
the pose until the next sample. `posed` is `false` while the clips load, when the model lacks a clip the state names, and
|
|
344
|
+
always headless. Names are capped at 256 characters and `parameters` at 64 values. An
|
|
345
|
+
entity without an `Animator`, or an engine refusal such as an unknown state (`data.code`
|
|
346
|
+
`IGX-1202`), is `invalidParams`. The host finds `ignifx/Animator` by type id, so a project
|
|
347
|
+
without `@ignifx/3d` simply has none.
|
|
327
348
|
- **Settings over the protocol.** `describeSettings` answers `{ sections, values }`: core's
|
|
328
349
|
`describeSettings(app)` with each section's `settingsJsonSchema` entry as `propsSchema`, and the
|
|
329
350
|
values the app resolved, in the settings form (`{ x, y, z }`, `{ r, g, b, a }`). No notification
|
|
330
351
|
announces settings; ask again after the project's settings change.
|
|
352
|
+
- **Materials and collider gizmos.** `setAnimateMaterials { enabled }` sets
|
|
353
|
+
`app.renderer.animateMaterialsInEditMode` (on at every start, so re-send it after `ready`).
|
|
354
|
+
`getColliderOutlines { entities }` answers `{ outlines }`: per enabled collider of each open
|
|
355
|
+
entity, its uid, the component's uid, `isTrigger`, and world-space `lines` (six numbers a
|
|
356
|
+
segment), read from `app.physics` / `app.physics2d` by shape, plus `truncated` when the request
|
|
357
|
+
passed 256 entities or the lines 600 000 numbers. Edit mode keeps physics bodies on the
|
|
358
|
+
transforms the editor moves without stepping, so the outlines and physics queries follow.
|
|
331
359
|
- **A changed asset reloads in place, not the view.** The scene view's page hands every
|
|
332
360
|
`ignifx:asset-changed` event to `host.assetChanged`, which calls `app.assets.reload(address)` for an
|
|
333
361
|
asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
|
|
334
362
|
`spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
|
|
335
363
|
through another prefab, with their uids, transforms, overrides and document children; `readBack`
|
|
336
|
-
then writes the new prefab's hash.
|
|
337
|
-
|
|
338
|
-
|
|
364
|
+
then writes the new prefab's hash. An override the new prefab no longer has, like any problem
|
|
365
|
+
building an op's subtree, is a `log` warning worded as a reopen's (an op's problems also come back
|
|
366
|
+
in `applyOps`' `warnings`). A rebuilt subtree resolves its
|
|
367
|
+
references, the ones its overrides hold included, against the whole document, as a reopen does,
|
|
368
|
+
and so do the references into it from the rest of the document, other instances' overrides
|
|
369
|
+
included. The host sends `assetReloaded { address, type, entities }` (the rebuilt instance
|
|
370
|
+
roots) once the new value is in. A texture, a removed file and the open document's own file are
|
|
371
|
+
left alone and send nothing.
|
|
339
372
|
- **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
|
|
340
373
|
in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
|
|
341
374
|
|