@ignifx/editor-host 0.14.0 → 0.15.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/index.js CHANGED
@@ -187,8 +187,8 @@ const HostKind = {
187
187
  * The play controls send `"heartbeat"`, `"playControls"`, `"logRelay"` and `"queryRuntime"`, plus
188
188
  * `"screenshot"` when the game has a canvas and `"sendInput"` when it has `app.input`. The scene
189
189
  * host sends `"heartbeat"` and whichever of `"gizmos"`, `"screenshot"`, `"viewMode2d"`,
190
- * `"pick2d"`, `"gameView"` and `"thumbnails"` it supports; every `SceneMethod` not tied to one of
191
- * them is required of a 0.3 scene host.
190
+ * `"pick2d"`, `"gameView"`, `"thumbnails"` and `"grid"` it supports; every `SceneMethod` not tied
191
+ * to one of them is required of a 0.3 scene host.
192
192
  *
193
193
  * @public
194
194
  */
@@ -254,7 +254,14 @@ const HostCapability = {
254
254
  * (`RenderViewMethod`). From engine ask E8 (additive in 0.3); without it, the host answers it with
255
255
  * `RpcErrorCode.methodNotFound`.
256
256
  */
257
- thumbnails: "thumbnails"
257
+ thumbnails: "thumbnails",
258
+ /**
259
+ * The scene host draws a grid in the view and answers `setGrid`: a ground grid at `y = 0` in 3D
260
+ * view mode and a unit grid (a pixel grid when zoomed in) over the 2D view. From engine ask E31
261
+ * (additive in 0.3); without it, the scene host answers `setGrid` with
262
+ * `RpcErrorCode.methodNotFound`.
263
+ */
264
+ grid: "grid"
258
265
  };
259
266
  /**
260
267
  * The longest string, in UTF-16 code units, the editor accepts from a host in `ready` (the engine
@@ -1098,7 +1105,12 @@ const SceneMethod = {
1098
1105
  * amendment 2026-10-20). Answers {@link SampleAnimationResult}. A host from before it answers
1099
1106
  * `RpcErrorCode.methodNotFound`. Additive in 0.3.
1100
1107
  */
1101
- sampleAnimation: "sampleAnimation"
1108
+ sampleAnimation: "sampleAnimation",
1109
+ /**
1110
+ * Shows or hides the view's grid and sets its spacing (engine ask E31). Needs
1111
+ * `HostCapability.grid`. Answers `null`. Additive in 0.3.
1112
+ */
1113
+ setGrid: "setGrid"
1102
1114
  };
1103
1115
  /**
1104
1116
  * Scene host → editor: the notifications of protocol 0.3. None has an answer.
@@ -1275,6 +1287,18 @@ const ViewMode = {
1275
1287
  twoD: "2d"
1276
1288
  };
1277
1289
  /**
1290
+ * The smallest grid spacing `setGrid` accepts, in metres.
1291
+ *
1292
+ * @public
1293
+ */
1294
+ const GRID_MIN_SIZE = .001;
1295
+ /**
1296
+ * The largest grid spacing `setGrid` accepts, in metres.
1297
+ *
1298
+ * @public
1299
+ */
1300
+ const GRID_MAX_SIZE = 1e3;
1301
+ /**
1278
1302
  * Tells whether a value is one of an `as const` object's values.
1279
1303
  *
1280
1304
  * @param names - The object.
@@ -1590,6 +1614,20 @@ function isSetAnimateMaterialsParams(value) {
1590
1614
  return isRecord(value) && isBoolean(value["enabled"]);
1591
1615
  }
1592
1616
  /**
1617
+ * Checks the parameters of `setGrid`.
1618
+ *
1619
+ * @param value - The received `params`.
1620
+ * @returns True for an object whose `visible`, if present, is a boolean and whose `size`, if
1621
+ * present, is a number from {@link GRID_MIN_SIZE} to {@link GRID_MAX_SIZE}.
1622
+ *
1623
+ * @public
1624
+ */
1625
+ function isSetGridParams(value) {
1626
+ if (!isRecord(value)) return false;
1627
+ const size = value["size"];
1628
+ return optionalField(value, "visible", isBoolean) && (size === void 0 || isFiniteNumber(size) && size >= .001 && size <= 1e3);
1629
+ }
1630
+ /**
1593
1631
  * Checks one record of `getColliderOutlines`.
1594
1632
  *
1595
1633
  * @param value - The value to test.
@@ -4700,6 +4738,37 @@ var EditorCamera2D = class extends Script {
4700
4738
  }
4701
4739
  };
4702
4740
  //#endregion
4741
+ //#region src/scene/editor-grid.ts
4742
+ /**
4743
+ * The scene view's grid (engine ask E31): a script on the `Scene Grid` entity of the host's
4744
+ * persistent `editor` scene, which moves the grid with the editor camera every frame.
4745
+ */
4746
+ /**
4747
+ * Places the view's grid every frame, where {@link EditorGrid.placement} says.
4748
+ *
4749
+ * @remarks
4750
+ * The host sets both fields: `view` once a canvas has the grid's meshes (never headless), and
4751
+ * `placement` to read the editor cameras and the `setGrid` settings.
4752
+ */
4753
+ var EditorGrid = class extends Script {
4754
+ /** The type id; the host leaves it out of the schemas it reports. */
4755
+ static typeId = "ignifx-editor/EditorGrid";
4756
+ /** The scene view runs in edit mode, where only these scripts get callbacks. */
4757
+ static runInEditMode = true;
4758
+ /** The grid's meshes, or `null` while there is nothing to draw on. */
4759
+ view = null;
4760
+ /**
4761
+ * Reads this frame's grid.
4762
+ *
4763
+ * @returns The placement, or `null` to hide the grid.
4764
+ */
4765
+ placement = () => null;
4766
+ /** Moves the grid after the cameras have moved. */
4767
+ lateUpdate() {
4768
+ this.view?.place(this.placement());
4769
+ }
4770
+ };
4771
+ //#endregion
4703
4772
  //#region src/scene/view-math.ts
4704
4773
  /**
4705
4774
  * The arithmetic of the scene view's methods that needs no GPU: the `pick` unit rule, the ray and
@@ -5230,6 +5299,74 @@ var GizmoDragRelay = class {
5230
5299
  }
5231
5300
  };
5232
5301
  //#endregion
5302
+ //#region src/scene/grid.ts
5303
+ /** Every how many minor lines a major line falls. */
5304
+ const MAJOR_EVERY = 10;
5305
+ /** The 3D grid's spacing grows tenfold for each tenfold of eye height above this many minor lines. */
5306
+ const GROUND_LINES_PER_HEIGHT = 25;
5307
+ /** The 3D grid reaches this many eye heights from the eye before it has faded out. */
5308
+ const GROUND_REACH_PER_HEIGHT = 40;
5309
+ /** The 3D grid reaches at least this many lines from the eye. */
5310
+ const GROUND_MIN_REACH_LINES = 100;
5311
+ /** The 2D grid's lines are never closer than this, in screen pixels; denser ones step up tenfold. */
5312
+ const MIN_LINE_GAP_PX = 8;
5313
+ /**
5314
+ * The 3D view's ground grid: centred under the eye, coarser the higher the eye is, and large enough
5315
+ * that it fades out before its edge is in view.
5316
+ *
5317
+ * @param eye - The editor camera's position, in metres.
5318
+ * @param size - The spacing `setGrid` asked for, in metres.
5319
+ * @param far - The camera's far plane, in metres; the grid stays inside it.
5320
+ * @returns The placement.
5321
+ */
5322
+ function groundGridPlacement(eye, size, far) {
5323
+ const height = Math.max(Math.abs(eye.y), size);
5324
+ const step = size * 10 ** Math.max(0, Math.floor(Math.log10(height / (size * GROUND_LINES_PER_HEIGHT))));
5325
+ const reach = Math.min(Math.max(height * GROUND_REACH_PER_HEIGHT, step * GROUND_MIN_REACH_LINES), far * .9);
5326
+ return {
5327
+ plane: "ground",
5328
+ centerX: eye.x,
5329
+ centerY: eye.z,
5330
+ extent: reach * 2,
5331
+ step,
5332
+ majorEvery: MAJOR_EVERY
5333
+ };
5334
+ }
5335
+ /**
5336
+ * The 2D view's grid: lines `size` apart (tenfold coarser while they would be closer than a few
5337
+ * screen pixels), or one line per layer pixel from {@link PIXEL_GRID_ZOOM} on, with a major line
5338
+ * every `size`. It covers the whole view.
5339
+ *
5340
+ * @param view - What the 2D editor camera shows.
5341
+ * @param size - The spacing `setGrid` asked for, in metres.
5342
+ * @returns The placement.
5343
+ */
5344
+ function screenGridPlacement(view, size) {
5345
+ const pixelsPerMetre = Math.max(view.zoom * view.pixelsPerUnit, Number.MIN_VALUE);
5346
+ const extent = 2 * Math.max(view.widthPx, view.heightPx) / pixelsPerMetre;
5347
+ const base = {
5348
+ plane: "screen",
5349
+ centerX: view.centerX,
5350
+ centerY: view.centerY,
5351
+ extent
5352
+ };
5353
+ if (view.zoom >= 8 && view.pixelsPerUnit > 0) {
5354
+ const step = 1 / view.pixelsPerUnit;
5355
+ return {
5356
+ ...base,
5357
+ step,
5358
+ majorEvery: Math.max(1, Math.round(size / step))
5359
+ };
5360
+ }
5361
+ let step = size;
5362
+ while (step * pixelsPerMetre < MIN_LINE_GAP_PX) step *= MAJOR_EVERY;
5363
+ return {
5364
+ ...base,
5365
+ step,
5366
+ majorEvery: MAJOR_EVERY
5367
+ };
5368
+ }
5369
+ //#endregion
5233
5370
  //#region src/scene/json.ts
5234
5371
  /**
5235
5372
  * The uid of a referenced entity or component.
@@ -6727,6 +6864,12 @@ var SceneHost = class {
6727
6864
  space: GizmoSpace.world,
6728
6865
  snap: null
6729
6866
  };
6867
+ /** The script that moves the grid, on the `editor` scene's `Scene Grid` entity. */
6868
+ #grid = null;
6869
+ #gridSettings = {
6870
+ visible: true,
6871
+ size: 1
6872
+ };
6730
6873
  #drag;
6731
6874
  #gameView = new GameView();
6732
6875
  #thumbnails;
@@ -6783,6 +6926,7 @@ var SceneHost = class {
6783
6926
  this.#requireMirror(RenderViewMethod.renderThumbnail);
6784
6927
  return thumbnails.render(params);
6785
6928
  });
6929
+ if (has(HostCapability.grid)) methods.set(SceneMethod.setGrid, (params) => this.#setGrid(params));
6786
6930
  this.methods = new Map([...methods].map(([name, handler]) => [name, async (params) => this.#serial(() => handler(params))]));
6787
6931
  }
6788
6932
  /**
@@ -6794,7 +6938,7 @@ var SceneHost = class {
6794
6938
  return this.#editorScene;
6795
6939
  }
6796
6940
  /**
6797
- * Prepares the app before it starts: the persistent `editor` scene with the editor camera, and
6941
+ * Prepares the app before it starts: the persistent `editor` scene with the editor camera and grid, and
6798
6942
  * the log, error and hot-reload relays.
6799
6943
  *
6800
6944
  * @param app - The scene view's app, created and not yet started.
@@ -6804,7 +6948,11 @@ var SceneHost = class {
6804
6948
  this.#mirror = new DocumentMirror(app);
6805
6949
  const scene = app.world.createScene(EDITOR_SCENE_NAME, { persistent: true });
6806
6950
  this.#editorScene = scene;
6807
- app.registerComponents([EditorCamera, EditorCamera2D]);
6951
+ app.registerComponents([
6952
+ EditorCamera,
6953
+ EditorCamera2D,
6954
+ EditorGrid
6955
+ ]);
6808
6956
  const eye = app.world.createEntity("Editor Camera", { scene });
6809
6957
  this.#eye = eye.addComponent(Camera, {
6810
6958
  fov: 50,
@@ -6826,6 +6974,11 @@ var SceneHost = class {
6826
6974
  twoD.attach(this.#eye, isCamera2DLike(camera2D) ? camera2D : null);
6827
6975
  twoD.pixelsPerUnit = () => twoDServiceOf(app)?.pixelsPerUnit ?? 100;
6828
6976
  this.#camera2D = twoD;
6977
+ if (this.methods.has(SceneMethod.setGrid)) {
6978
+ const grid = app.world.createEntity("Scene Grid", { scene }).addComponent(EditorGrid);
6979
+ grid.placement = () => this.#gridPlacement();
6980
+ this.#grid = grid;
6981
+ }
6829
6982
  this.#cleanups.push(relayAppReports(app, {
6830
6983
  log: (params) => {
6831
6984
  this.#notify(SceneNotification.log, params);
@@ -6849,12 +7002,17 @@ var SceneHost = class {
6849
7002
  const app = this.#requireApp();
6850
7003
  this.#canvas = canvas;
6851
7004
  if (canvas !== null && !app.isHeadless && this.methods.has(SceneMethod.setGizmo) && isDomCanvas(canvas)) {
6852
- const view = createEditorView(app.lite, await app.renderer.openOverlay(), canvas);
7005
+ const overlay = await app.renderer.openOverlay();
7006
+ const view = createEditorView(app.lite, overlay, canvas);
6853
7007
  view.onDrag((phase, drag) => {
6854
7008
  this.#onDrag(phase, drag);
6855
7009
  });
6856
7010
  this.#view = view;
6857
7011
  this.#applyGizmo();
7012
+ if (this.methods.has(SceneMethod.setGrid) && this.#grid !== null) {
7013
+ const { createEditorGrid } = await import("./grid.js");
7014
+ this.#grid.view = createEditorGrid(app.lite, overlay);
7015
+ }
6858
7016
  const onClick = (click) => {
6859
7017
  this.#onClick(click).catch((error) => {
6860
7018
  const params = {
@@ -6988,6 +7146,10 @@ var SceneHost = class {
6988
7146
  dispose() {
6989
7147
  for (const pending of this.#reloads) pending.cancel();
6990
7148
  for (const cleanup of this.#cleanups.splice(0)) cleanup();
7149
+ if (this.#grid !== null) {
7150
+ this.#grid.view?.dispose();
7151
+ this.#grid.view = null;
7152
+ }
6991
7153
  this.#view?.dispose();
6992
7154
  this.#view = null;
6993
7155
  this.#gameView.dispose();
@@ -7191,6 +7353,35 @@ var SceneHost = class {
7191
7353
  return null;
7192
7354
  }
7193
7355
  /**
7356
+ * `setGrid`: shows or hides the view's grid and sets its spacing. A field left out takes its
7357
+ * default.
7358
+ *
7359
+ * @param params - `{ visible?, size? }`.
7360
+ * @returns `null`.
7361
+ */
7362
+ #setGrid(params) {
7363
+ this.#requireMirror(SceneMethod.setGrid);
7364
+ if (!isSetGridParams(params)) throw new InvalidParamsError("setGrid takes { visible?: boolean, size?: number from 0.001 to 1000 }.");
7365
+ this.#gridSettings = {
7366
+ visible: params.visible ?? true,
7367
+ size: params.size ?? 1
7368
+ };
7369
+ return null;
7370
+ }
7371
+ /**
7372
+ * Where the grid draws this frame: on the ground under the 3D editor camera, or over the 2D view.
7373
+ *
7374
+ * @returns The placement, or `null` while the grid is hidden.
7375
+ */
7376
+ #gridPlacement() {
7377
+ const { visible, size } = this.#gridSettings;
7378
+ if (!visible) return null;
7379
+ const camera2D = this.#camera2D;
7380
+ if (this.#viewMode === ViewMode.twoD && camera2D !== null) return screenGridPlacement(camera2D.view(), size);
7381
+ const eye = this.#eye;
7382
+ return eye === null ? null : groundGridPlacement(eye.transform.position, size, eye.far);
7383
+ }
7384
+ /**
7194
7385
  * `getColliderOutlines`: the world-space outlines of the requested entities' colliders, from the
7195
7386
  * project's physics extensions, for the editor's collider gizmos. Changes nothing.
7196
7387
  *
@@ -7536,7 +7727,11 @@ var SceneHost = class {
7536
7727
  * @returns The set.
7537
7728
  */
7538
7729
  #schemas() {
7539
- return schemaSet(this.#requireApp(), /* @__PURE__ */ new Set([EditorCamera.typeId, EditorCamera2D.typeId]));
7730
+ return schemaSet(this.#requireApp(), /* @__PURE__ */ new Set([
7731
+ EditorCamera.typeId,
7732
+ EditorCamera2D.typeId,
7733
+ EditorGrid.typeId
7734
+ ]));
7540
7735
  }
7541
7736
  /**
7542
7737
  * The app, once {@link SceneHost.prepare} has run.
@@ -7641,7 +7836,8 @@ async function startEditorHost(options) {
7641
7836
  HostCapability.logRelay,
7642
7837
  HostCapability.hotReloadDefaults,
7643
7838
  HostCapability.gameView,
7644
- ...canRenderThumbnails(options) ? [HostCapability.thumbnails] : []
7839
+ ...canRenderThumbnails(options) ? [HostCapability.thumbnails] : [],
7840
+ HostCapability.grid
7645
7841
  ] : [
7646
7842
  HostCapability.heartbeat,
7647
7843
  HostCapability.logRelay,
@@ -8475,6 +8671,6 @@ function listenForEditorPlayControls(options) {
8475
8671
  };
8476
8672
  }
8477
8673
  //#endregion
8478
- export { ApplyOpFailureCode, COLLIDER_OUTLINES_MAX_ENTITIES, COLLIDER_OUTLINES_MAX_NUMBERS, DEFAULT_HEARTBEAT_INTERVAL_MS, EDITOR_CONNECT_MESSAGE_TYPE, EditorHostErrorCode, GAME_VIEW_DEFAULT_SIZE, GAME_VIEW_MAX_SIZE, GizmoMode, GizmoSpace, HOST_LIST_MAX_LENGTH, HOST_TEXT_MAX_LENGTH, HandshakeMethod, HostCapability, HostKind, HostNotification, JSON_RPC_VERSION, PROTOCOL_VERSION, PickUnit, PlayMethod, PlayNotification, PlayPhase, QUERY_RUNTIME_MAX_COMPONENTS, QUERY_RUNTIME_MAX_JSON_LENGTH, QUERY_RUNTIME_MAX_KEYS, QUERY_RUNTIME_MAX_STRING_LENGTH, RenderViewMethod, RpcErrorCode, SAMPLE_ANIMATION_MAX_NAME_LENGTH, SAMPLE_ANIMATION_MAX_PARAMETERS, SCREENSHOT_MAX_SIZE, SEND_INPUT_MAX_EVENTS, SceneMethod, SceneNotification, SceneOpKind, ScreenshotFormat, THUMBNAIL_DEFAULT_SIZE, THUMBNAIL_MAX_SIZE, TRANSFORM_DRAGGING_INTERVAL_MS, ViewMode, isAppErrorData, isApplyOpsParams, isApplyOpsResult, isAssetReloadedParams, isColliderOutlineRecord, isColliderOutlineSet, isEditorConnectMessage, isEditorOrigin, isEntitySelection, isFrameParams, isGameViewFrameParams, isGameViewFrameResult, isGameViewState, isHostErrorParams, isHotReloadedParams, isIncompatibleProtocolData, isInvalidSceneFileData, isJsonObject, isJsonValue, isLogParams, isOpenSceneParams, isOpenSceneResult, isPickParams, isPickResult, isPlayState, isPlayStateReport, isPlayStats, isProtocolVersion, isQueryRuntimeParams, isQueryRuntimeResult, isReadBackParams, isReadBackResult, isReadyResult, isRenderThumbnailParams, isRpcMessage, isSampleAnimationParams, isSampleAnimationResult, isSceneFile, isSceneFileAssetRef, isSceneFileComponent, isSceneFileEntity, isSceneFileInstance, isSceneFileOverride, isSceneFileTransform, isSceneIssue, isSceneOp, isSceneOpenedParams, isSchemaSet, isScreenshotParams, isScreenshotResult, isSendInputEvent, isSendInputParams, isSendInputResult, isSetAnimateMaterialsParams, isSetGameViewParams, isSetGizmoParams, isSetViewModeParams, isSettingsSet, isThumbnailResult, isTransformDraggedParams, isTransformDraggingParams, listenForEditorPlayControls, protocolVersionIsCompatible, startEditorHost, startEditorPlayControls };
8674
+ export { ApplyOpFailureCode, COLLIDER_OUTLINES_MAX_ENTITIES, COLLIDER_OUTLINES_MAX_NUMBERS, DEFAULT_HEARTBEAT_INTERVAL_MS, EDITOR_CONNECT_MESSAGE_TYPE, EditorHostErrorCode, GAME_VIEW_DEFAULT_SIZE, GAME_VIEW_MAX_SIZE, GRID_MAX_SIZE, GRID_MIN_SIZE, GizmoMode, GizmoSpace, HOST_LIST_MAX_LENGTH, HOST_TEXT_MAX_LENGTH, HandshakeMethod, HostCapability, HostKind, HostNotification, JSON_RPC_VERSION, PROTOCOL_VERSION, PickUnit, PlayMethod, PlayNotification, PlayPhase, QUERY_RUNTIME_MAX_COMPONENTS, QUERY_RUNTIME_MAX_JSON_LENGTH, QUERY_RUNTIME_MAX_KEYS, QUERY_RUNTIME_MAX_STRING_LENGTH, RenderViewMethod, RpcErrorCode, SAMPLE_ANIMATION_MAX_NAME_LENGTH, SAMPLE_ANIMATION_MAX_PARAMETERS, SCREENSHOT_MAX_SIZE, SEND_INPUT_MAX_EVENTS, SceneMethod, SceneNotification, SceneOpKind, ScreenshotFormat, THUMBNAIL_DEFAULT_SIZE, THUMBNAIL_MAX_SIZE, TRANSFORM_DRAGGING_INTERVAL_MS, ViewMode, isAppErrorData, isApplyOpsParams, isApplyOpsResult, isAssetReloadedParams, isColliderOutlineRecord, isColliderOutlineSet, isEditorConnectMessage, isEditorOrigin, isEntitySelection, isFrameParams, isGameViewFrameParams, isGameViewFrameResult, isGameViewState, isHostErrorParams, isHotReloadedParams, isIncompatibleProtocolData, isInvalidSceneFileData, isJsonObject, isJsonValue, isLogParams, isOpenSceneParams, isOpenSceneResult, isPickParams, isPickResult, isPlayState, isPlayStateReport, isPlayStats, isProtocolVersion, isQueryRuntimeParams, isQueryRuntimeResult, isReadBackParams, isReadBackResult, isReadyResult, isRenderThumbnailParams, isRpcMessage, isSampleAnimationParams, isSampleAnimationResult, isSceneFile, isSceneFileAssetRef, isSceneFileComponent, isSceneFileEntity, isSceneFileInstance, isSceneFileOverride, isSceneFileTransform, isSceneIssue, isSceneOp, isSceneOpenedParams, isSchemaSet, isScreenshotParams, isScreenshotResult, isSendInputEvent, isSendInputParams, isSendInputResult, isSetAnimateMaterialsParams, isSetGameViewParams, isSetGizmoParams, isSetGridParams, isSetViewModeParams, isSettingsSet, isThumbnailResult, isTransformDraggedParams, isTransformDraggingParams, listenForEditorPlayControls, protocolVersionIsCompatible, startEditorHost, startEditorPlayControls };
8479
8675
 
8480
8676
  //# sourceMappingURL=index.js.map