@ignifx/2d 0.9.0 → 0.11.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
@@ -1,5 +1,5 @@
1
1
  import { Color, Component, DEG_TO_RAD, IgnifxError, Phase, RAD_TO_DEG, RENDERING_SETTINGS_SECTION, Script, Signal, Vec2, array, assertNever, asset, bool, color, createDefaults, decodeProps, defineExtension, defineSchema, describeSchema, entityRef, enumOf, f32, i32, map, optional, record, str, toJsonSchema, u32, vec2, vec4 } from "@ignifx/core";
2
- import { addSprite2D, addSpriteRendererLayer, clearSprite2DLayer, createSprite2DCustomShader, createSprite2DLayer, createSpriteRenderer, disableSprite2DYSort, disposeSpriteRenderer, enableDeviceLostSpriteRecovery, enableSprite2DYSort, getSprite2DHandleIndex, getSprite2DVisibleBoundsToRef, isSprite2DHandleAlive, loadTexture2D, pickSprite2D, registerSpriteRenderer, releaseTexture, removeSprite2D, removeSpriteRendererLayer, setSprite2DShaderParams, setSprite2DYSortHandleBias, sprite2DScreenToWorldToRef, spriteBlendAdditive, spriteBlendAlpha, spriteBlendMultiply, spriteBlendOpaque, spriteBlendPremultiplied, unregisterSpriteRenderer, updateSprite2D } from "@babylonjs/lite";
2
+ import { addSprite2D, addSpriteRendererLayer, clearSprite2DLayer, createSprite2DCustomShader, createSprite2DLayer, createSpriteRenderer, disableSprite2DYSort, disposeSpriteRenderer, enableDeviceLostSpriteRecovery, enableSprite2DYSort, getSprite2DHandleIndex, getSprite2DVisibleBoundsToRef, isSprite2DHandleAlive, loadTexture2D, pickSprite2D, registerSpriteRenderer, releaseTexture, removeSprite2D, removeSpriteRendererLayer, setSprite2DShaderParams, setSprite2DYSortHandleBias, sprite2DScreenToWorldToRef, spriteBlendAdditive, spriteBlendAlpha, spriteBlendMultiply, spriteBlendOpaque, spriteBlendPremultiplied, unregisterSpriteRenderer, updateSprite2D, updateSprite2DIndex } from "@babylonjs/lite";
3
3
  //#region src/augmentation.ts
4
4
  /**
5
5
  * Defines `app.twoD`, pairing with the augmentation above.
@@ -57,8 +57,6 @@ const TwoDErrorCode = {
57
57
  unknownClip: "IGX-1108",
58
58
  /** A tilemap importer was handed a document it cannot read, or an unsupported projection. */
59
59
  unsupportedImport: "IGX-1109",
60
- /** `app.twoD.registerTileObjectFactory` was called twice for one object type. */
61
- duplicateObjectFactory: "IGX-1110",
62
60
  /** A tile coordinate is outside the tilemap layer's bounds. */
63
61
  tileOutOfRange: "IGX-1111",
64
62
  /** A second `twoD()` extension was registered on one app. */
@@ -72,7 +70,11 @@ const TwoDErrorCode = {
72
70
  /** A sprite batch was written to, or resized, after `dispose()`. */
73
71
  batchDisposed: "IGX-1116",
74
72
  /** `app.twoD.createSpriteBatch` was given an atlas handle that has not finished loading. */
75
- batchAtlasNotLoaded: "IGX-1117"
73
+ batchAtlasNotLoaded: "IGX-1117",
74
+ /** `SpriteRenderer.sprite` loaded something that is not a sprite atlas, such as a `#frame:` address. */
75
+ spriteNotAnAtlas: "IGX-1118",
76
+ /** `app.twoD.pickAt` or `pickAllAt` was called from inside a pick's own `filter`. */
77
+ nestedPick: "IGX-1119"
76
78
  };
77
79
  /**
78
80
  * The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
@@ -89,14 +91,15 @@ const TWO_D_ERROR_MESSAGES = Object.freeze({
89
91
  "IGX-1107": "{sortingLayer} is not a sorting layer declared by the sortingLayers settings section.",
90
92
  "IGX-1108": "{asset} declares no clip named {clip}.",
91
93
  "IGX-1109": "{importer} cannot read this document: {reason}.",
92
- "IGX-1110": "A tile object factory for {type} is already registered.",
93
94
  "IGX-1111": "Cell {x},{y} is outside layer {layer}.",
94
95
  "IGX-1112": "The twoD() extension is already registered on this app.",
95
96
  "IGX-1113": "A custom SpriteLayerEffect needs a WGSL fragment body in its shader field.",
96
97
  "IGX-1114": "A sprite batch capacity must be a whole number of at least 1; got {capacity}.",
97
98
  "IGX-1115": "{index} is outside the sprite batch's 0..{capacity} slots.",
98
99
  "IGX-1116": "This sprite batch was disposed; create another one.",
99
- "IGX-1117": "The atlas handle for a sprite batch is {state}, not loaded."
100
+ "IGX-1117": "The atlas handle for a sprite batch is {state}, not loaded.",
101
+ "IGX-1118": "SpriteRenderer.sprite names {address}, which is not a sprite atlas.",
102
+ "IGX-1119": "app.twoD.pickAt and pickAllAt cannot be called from inside a pick filter."
100
103
  });
101
104
  /**
102
105
  * Builds an `IgnifxError` carrying one of this package's codes.
@@ -815,6 +818,29 @@ function pickSprite(layers, xPx, yPx) {
815
818
  return pickSprite2D(layers, xPx, yPx);
816
819
  }
817
820
  /**
821
+ * Shows or hides one sprite by its dense index, leaving every other field alone.
822
+ *
823
+ * @remarks
824
+ * Picking uses this to look **under** a sprite it has rejected: Lite's picker only ever reports the
825
+ * topmost hit in a layer, so the caller hides that hit, picks again, and restores every sprite it
826
+ * hid before returning. Hiding zeroes the GPU size and keeps the true size in Lite's shadow copy,
827
+ * and the Y-sort key is the position plus the bias, so a hide-then-show pair restores the sprite
828
+ * and its draw order exactly (`lib/sprite/sprite-2d.js`, `writeInstance`;
829
+ * `lib/sprite/sprite-2d-y-sort.js`, `keyAt`). The pair marks the slot dirty, which costs one
830
+ * slot's upload on the next frame.
831
+ *
832
+ * @param layer - The layer.
833
+ * @param index - The sprite's dense index, as a pick reported it.
834
+ * @param scratch - The reusable visibility patch.
835
+ * @param visible - Whether the sprite draws.
836
+ *
837
+ * @internal
838
+ */
839
+ function setSpriteVisibleAt(layer, index, scratch, visible) {
840
+ scratch.patch.visible = visible;
841
+ updateSprite2DIndex(layer, index, scratch.patch);
842
+ }
843
+ /**
818
844
  * Compiles a WGSL fragment body into a layer shader (`index.d.ts` 3160).
819
845
  *
820
846
  * @remarks
@@ -956,16 +982,23 @@ var SortingLayerTable = class {
956
982
  * A sprite.
957
983
  *
958
984
  * @remarks
959
- * The `sprite` field is an atlas handle; the frame inside it comes from the address's `#frame:`
960
- * fragment when there is one, and otherwise from {@link SpriteRenderer.frame}, which game code and
961
- * `SpriteAnimator` both write. A sprite whose atlas has not finished loading draws nothing and
962
- * costs nothing.
985
+ * The `sprite` field is an atlas handle, and two members pick the frame inside it.
986
+ * {@link SpriteRenderer.frameName} is the field a scene file stores: a frame name, or `""` for the
987
+ * first frame. {@link SpriteRenderer.frame} is the index drawn now, which `SpriteAnimator` and game
988
+ * code write. Whichever of the two was written last decides the frame; a name is looked up again
989
+ * whenever the atlas changes. A name the atlas does not declare is reported once (`IGX-1106`) and
990
+ * draws the first frame.
991
+ *
992
+ * `sprite` takes the atlas's own address. A `#frame:` address loads a `SpriteAsset`, not an atlas:
993
+ * the sprite draws nothing and reports `IGX-1118` once. A sprite whose atlas has not finished
994
+ * loading draws nothing and costs nothing.
963
995
  *
964
996
  * @example
965
997
  * ```ts
966
998
  * const hero = app.world.createEntity({ name: "hero" });
967
999
  * const sprite = hero.addComponent(SpriteRenderer);
968
1000
  * sprite.sprite = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json");
1001
+ * sprite.frameName = "idle_0";
969
1002
  * sprite.sortingLayer = "Default";
970
1003
  * ```
971
1004
  *
@@ -980,6 +1013,14 @@ var SpriteRenderer = class SpriteRenderer extends Component {
980
1013
  static schema = spriteRendererSchema();
981
1014
  /** The atlas frame index drawn; `SpriteAnimator` writes this. */
982
1015
  #frame = 0;
1016
+ /** The frame's name as the scene file stores it; `""` is the first frame. */
1017
+ #frameName = "";
1018
+ /** Whether `frameName` was written after `frame`, so the name decides the index. */
1019
+ #isFrameByName = true;
1020
+ /** The atlas the name was last looked up in, so a new atlas looks it up again. */
1021
+ #resolvedAtlas = null;
1022
+ /** What was last reported (`atlas#frame`, or the non-atlas value), so each problem is reported once. */
1023
+ #reported = null;
983
1024
  /** The Lite handle, or `null` while the sprite is not in a layer. */
984
1025
  #handle = null;
985
1026
  /** The key of the layer the handle currently lives in, or `null`. */
@@ -1018,25 +1059,58 @@ var SpriteRenderer = class SpriteRenderer extends Component {
1018
1059
  this.#isDirty = true;
1019
1060
  }
1020
1061
  /**
1021
- * The atlas frame drawn.
1062
+ * The atlas frame index drawn.
1063
+ *
1064
+ * @remarks
1065
+ * When {@link SpriteRenderer.frameName} was written last, this is that frame's index once the
1066
+ * atlas has loaded. The index is not saved: a scene file stores `frameName`.
1022
1067
  *
1023
1068
  * @returns The frame index.
1024
1069
  */
1025
1070
  get frame() {
1071
+ if (this.#isFrameByName) this.#resolveFrameName(this.atlas);
1026
1072
  return this.#frame;
1027
1073
  }
1028
1074
  /**
1029
- * Sets the atlas frame drawn, marking the sprite for the next sync when it changes.
1075
+ * Sets the atlas frame drawn by index, marking the sprite for the next sync when it changes. The
1076
+ * index then wins over {@link SpriteRenderer.frameName} until `frameName` is written again.
1030
1077
  *
1031
1078
  * @param value - The frame index.
1032
1079
  */
1033
1080
  set frame(value) {
1081
+ this.#isFrameByName = false;
1034
1082
  if (value !== this.#frame) {
1035
1083
  this.#frame = value;
1036
1084
  this.#isDirty = true;
1037
1085
  }
1038
1086
  }
1039
1087
  /**
1088
+ * The frame a scene file says this sprite draws, by the name the atlas gives it.
1089
+ *
1090
+ * @remarks
1091
+ * A schema field: scene files store it and the inspector edits it. `""` draws the first frame.
1092
+ * Writing it makes the name decide the frame until {@link SpriteRenderer.frame} is written, so a
1093
+ * `SpriteAnimator` still animates a sprite that names a still frame, and a scene saved meanwhile
1094
+ * keeps the name. A name the atlas does not declare is reported once through `app.onError`
1095
+ * (`IGX-1106`) and draws the first frame.
1096
+ *
1097
+ * @returns The frame name, or `""`.
1098
+ */
1099
+ get frameName() {
1100
+ return this.#frameName;
1101
+ }
1102
+ /**
1103
+ * Picks the frame drawn by name.
1104
+ *
1105
+ * @param value - A frame name the atlas declares, or `""` for the first frame.
1106
+ */
1107
+ set frameName(value) {
1108
+ this.#frameName = value;
1109
+ this.#isFrameByName = true;
1110
+ this.#resolvedAtlas = null;
1111
+ this.#isDirty = true;
1112
+ }
1113
+ /**
1040
1114
  * The Babylon Lite objects the component uses. Unstable escape hatch
1041
1115
  * (`CONSTITUTION.md` §3.4).
1042
1116
  *
@@ -1076,7 +1150,30 @@ var SpriteRenderer = class SpriteRenderer extends Component {
1076
1150
  */
1077
1151
  get atlas() {
1078
1152
  const handle = this.sprite;
1079
- return handle?.state === "loaded" ? handle.value : null;
1153
+ return handle?.state === "loaded" && handle.value instanceof SpriteAtlasAsset ? handle.value : null;
1154
+ }
1155
+ /**
1156
+ * The atlas to draw from, with the frame name looked up in it. The sync system calls this once
1157
+ * per sprite per frame, before anything else.
1158
+ *
1159
+ * @remarks
1160
+ * A loaded `sprite` handle whose value is not an atlas is reported once (`IGX-1118`) and draws
1161
+ * nothing; a frame name the atlas does not declare is reported once (`IGX-1106`) and draws the
1162
+ * first frame. Neither throws, so one bad sprite never stops the sync.
1163
+ *
1164
+ * @returns The atlas, or `null` when there is nothing to draw.
1165
+ *
1166
+ * @internal
1167
+ */
1168
+ prepareSync() {
1169
+ const atlas = this.atlas;
1170
+ if (atlas === null) {
1171
+ const handle = this.sprite;
1172
+ if (handle?.state === "loaded") this.#reportNotAnAtlas(handle.address, handle.value);
1173
+ return null;
1174
+ }
1175
+ if (this.#isFrameByName) this.#resolveFrameName(atlas);
1176
+ return atlas;
1080
1177
  }
1081
1178
  /**
1082
1179
  * Whether anything about this sprite needs writing to Lite this frame.
@@ -1151,6 +1248,76 @@ var SpriteRenderer = class SpriteRenderer extends Component {
1151
1248
  this.#handle = handle;
1152
1249
  this.#layerKey = key;
1153
1250
  }
1251
+ /**
1252
+ * Turns {@link SpriteRenderer.frameName} into the index drawn, once per atlas.
1253
+ *
1254
+ * @param atlas - The loaded atlas, or `null` while it is loading.
1255
+ */
1256
+ #resolveFrameName(atlas) {
1257
+ const name = this.#frameName;
1258
+ if (name !== "" && (atlas === null || atlas === this.#resolvedAtlas)) return;
1259
+ this.#resolvedAtlas = atlas;
1260
+ let index = name === "" ? 0 : atlas?.frameIndex(name) ?? 0;
1261
+ if (index < 0) {
1262
+ index = 0;
1263
+ if (atlas !== null) this.#reportUnknownFrame(atlas, name);
1264
+ }
1265
+ if (index !== this.#frame) {
1266
+ this.#frame = index;
1267
+ this.#isDirty = true;
1268
+ }
1269
+ }
1270
+ /**
1271
+ * Reports a frame name the atlas does not declare, once per atlas and name.
1272
+ *
1273
+ * @param atlas - The atlas.
1274
+ * @param name - The name it lacks.
1275
+ */
1276
+ #reportUnknownFrame(atlas, name) {
1277
+ const key = `${atlas.address}#${name}`;
1278
+ if (this.#reported === key || this.isDestroyed) return;
1279
+ this.#reported = key;
1280
+ const error = twoDError(TwoDErrorCode.unknownFrame, `${atlas.address} declares no frame named ${name}; ${this.entity.name} draws its first frame.`, {
1281
+ context: {
1282
+ atlas: atlas.address,
1283
+ frame: name,
1284
+ entity: this.entity.name
1285
+ },
1286
+ hint: `Set SpriteRenderer.frameName to one of: ${atlas.frameNames().join(", ")}.`
1287
+ });
1288
+ this.app.onError.emit({
1289
+ error,
1290
+ source: "system",
1291
+ phase: null,
1292
+ entity: this.entity,
1293
+ component: this
1294
+ });
1295
+ }
1296
+ /**
1297
+ * Reports a `sprite` handle whose value is not an atlas, once per value.
1298
+ *
1299
+ * @param address - The handle's address.
1300
+ * @param value - What it loaded.
1301
+ */
1302
+ #reportNotAnAtlas(address, value) {
1303
+ if (this.#reported === value || this.isDestroyed) return;
1304
+ this.#reported = value;
1305
+ const hash = address.indexOf("#");
1306
+ const error = twoDError(TwoDErrorCode.spriteNotAnAtlas, `SpriteRenderer.sprite on ${this.entity.name} names ${address}, which is not a sprite atlas; the sprite draws nothing.`, {
1307
+ context: {
1308
+ address,
1309
+ entity: this.entity.name
1310
+ },
1311
+ hint: hash < 0 ? "Name an .atlas.json file in sprite." : `Name the atlas in sprite (${address.slice(0, hash)}) and the frame in frameName.`
1312
+ });
1313
+ this.app.onError.emit({
1314
+ error,
1315
+ source: "system",
1316
+ phase: null,
1317
+ entity: this.entity,
1318
+ component: this
1319
+ });
1320
+ }
1154
1321
  };
1155
1322
  /**
1156
1323
  * The `SpriteRenderer` schema.
@@ -1160,6 +1327,7 @@ var SpriteRenderer = class SpriteRenderer extends Component {
1160
1327
  function spriteRendererSchema() {
1161
1328
  return defineSchema({
1162
1329
  sprite: asset(SpriteAtlasAsset, { tooltip: "The atlas this sprite draws a frame of." }),
1330
+ frameName: str("", { tooltip: "The atlas frame drawn, by name; empty draws the first frame." }),
1163
1331
  color: color("#ffffffff", { tooltip: "Tint multiplied into every texel." }),
1164
1332
  flipX: bool(false, { tooltip: "Mirror horizontally." }),
1165
1333
  flipY: bool(false, { tooltip: "Mirror vertically." }),
@@ -1590,6 +1758,39 @@ var SpriteAnimator = class SpriteAnimator extends Component {
1590
1758
  if (this.#clip !== null && this.#clip.frames.length > 0) this.#isPlaying = true;
1591
1759
  }
1592
1760
  /**
1761
+ * Shows one frame of a clip without playing it, for an editor preview (ADR-0028) or a held pose.
1762
+ * Playback stops on that frame and no `onEvent` or `onClipEnded` fires;
1763
+ * {@link SpriteAnimator.resume} plays on from there.
1764
+ *
1765
+ * @param name - The clip's name.
1766
+ * @param frameIndex - The frame within the clip, counting from `0`; clamped to the clip's frames.
1767
+ * @returns `true` when the frame was written; `false` while the document or the atlas is still
1768
+ * loading, or when the clip has no frames.
1769
+ * @throws IgnifxError with code `IGX-1108` when the document declares no such clip.
1770
+ *
1771
+ * @example
1772
+ * ```ts
1773
+ * animator.sample("run", 2);
1774
+ * ```
1775
+ */
1776
+ sample(name, frameIndex) {
1777
+ const clips = this.asset;
1778
+ const atlas = this.#atlas();
1779
+ if (clips === null || atlas === null) return false;
1780
+ const clip = clips.requireClip(name, atlas);
1781
+ const last = clip.frames.length - 1;
1782
+ if (last < 0) return false;
1783
+ const cursor = Math.min(Math.max(Math.trunc(frameIndex), 0), last);
1784
+ const rate = clip.fps * this.speed;
1785
+ this.#clip = clip;
1786
+ this.#cursor = cursor;
1787
+ this.#elapsed = rate > 0 ? cursor / rate : 0;
1788
+ this.#isPlaying = false;
1789
+ this.#hasAutoPlayed = true;
1790
+ this.#writeFrame();
1791
+ return true;
1792
+ }
1793
+ /**
1593
1794
  * Advances playback by one frame's worth of scaled time. The animation system calls this in
1594
1795
  * `PostUpdate`.
1595
1796
  *
@@ -2779,9 +2980,10 @@ function releaseAtlasTexture(texture) {
2779
2980
  * are all queryable, nothing is uploaded, and `asset.lite.atlas` is `null`
2780
2981
  * (`docs/architecture/07-rendering.md` §6).
2781
2982
  *
2782
- * `parseFragment` is what makes `"2d/hero.atlas.json#frame:idle_0"` work: the base document is
2983
+ * `parseFragment` is what makes `"2d/hero.atlas.json#frame:idle_0"` load: the base document is
2783
2984
  * loaded once and shared, and the fragment handle resolves to a {@link SpriteAsset} naming one
2784
- * frame of it.
2985
+ * frame of it. That is for code; a `SpriteRenderer` names the atlas and picks the frame with its
2986
+ * `frameName` field.
2785
2987
  */
2786
2988
  /**
2787
2989
  * The centre pivot a frame that declares none uses.
@@ -4174,9 +4376,9 @@ var TilemapRenderer = class TilemapRenderer extends Component {
4174
4376
  * Forces every chunk to be rebuilt on the next sync.
4175
4377
  *
4176
4378
  * @remarks
4177
- * `Tilemap.onTileChanged` is what normally calls this — a rewritten cell has to reach the sprite
4178
- * that draws it, and rebuilding the chunk is both simpler and, for anything short of a per-frame
4179
- * rewrite, cheaper than tracking one sprite per cell.
4379
+ * A rewritten cell does not need this: `Tilemap.setTile` and `setCells` stamp the chunk they
4380
+ * touched, and the next sync rebuilds just that chunk — simpler and, for anything short of a
4381
+ * per-frame rewrite, cheaper than tracking one sprite per cell.
4180
4382
  *
4181
4383
  * @internal
4182
4384
  */
@@ -4209,7 +4411,7 @@ var TilemapRenderer = class TilemapRenderer extends Component {
4209
4411
  const chunksY = Math.ceil(definition.height / chunkSize);
4210
4412
  const window = this.#chunkWindow(bounds, chunkSize, cellSize, pixelsPerUnit, chunksX, chunksY);
4211
4413
  let written = 0;
4212
- for (const [key, chunk] of this.#chunks) if (!inWindow(chunk.chunkX, chunk.chunkY, window)) this.#drop(registry, key, chunk);
4414
+ for (const [key, chunk] of this.#chunks) if (!inWindow(chunk.chunkX, chunk.chunkY, window) || map.chunkStamp(chunk.chunkX, chunk.chunkY) !== chunk.stamp) this.#drop(registry, key, chunk);
4213
4415
  for (let chunkY = window.minY; chunkY <= window.maxY; chunkY += 1) for (let chunkX = window.minX; chunkX <= window.maxX; chunkX += 1) {
4214
4416
  const key = `${String(chunkX)},${String(chunkY)}`;
4215
4417
  if (this.#chunks.has(key)) continue;
@@ -4304,6 +4506,7 @@ var TilemapRenderer = class TilemapRenderer extends Component {
4304
4506
  const originY = matrix[13] ?? 0;
4305
4507
  const sizePx = cellSize * pixelsPerUnit;
4306
4508
  const sprites = [];
4509
+ const stamp = map.chunkStamp(chunkX, chunkY);
4307
4510
  for (let layerIndex = 0; layerIndex < definition.layers.length; layerIndex += 1) {
4308
4511
  const layer = definition.layers[layerIndex];
4309
4512
  if (layer === void 0) continue;
@@ -4325,7 +4528,8 @@ var TilemapRenderer = class TilemapRenderer extends Component {
4325
4528
  this.#chunks.set(`${String(chunkX)},${String(chunkY)}`, {
4326
4529
  chunkX,
4327
4530
  chunkY,
4328
- sprites
4531
+ sprites,
4532
+ stamp
4329
4533
  });
4330
4534
  return sprites.length;
4331
4535
  }
@@ -5524,6 +5728,10 @@ const DEFAULT_CHUNK_SIZE = 32;
5524
5728
  * const level = app.world.createEntity({ name: "level" }).addComponent(Tilemap);
5525
5729
  * level.map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json");
5526
5730
  * level.setTile(0, 3, 2, 0); // carve a hole in the ground layer
5731
+ * level.setCells([
5732
+ * { layer: 0, x: 4, y: 2, tileId: 0 },
5733
+ * { layer: 0, x: 5, y: 2, tileId: 0 },
5734
+ * ]);
5527
5735
  * ```
5528
5736
  *
5529
5737
  * @public
@@ -5545,6 +5753,14 @@ var Tilemap = class Tilemap extends Component {
5545
5753
  #collisionDirty = true;
5546
5754
  /** Bumped on every collision rebuild, so a physics backend can skip unchanged frames. */
5547
5755
  #version = 0;
5756
+ /** Bumped once per `setTile` or `setCells` call that changed a cell, and on a layout change. */
5757
+ #tileVersion = 0;
5758
+ /** Per render chunk, the `#tileVersion` of its last change; row-major, `#stampChunksX` wide. */
5759
+ #chunkStamps = /* @__PURE__ */ new Uint32Array(0);
5760
+ /** The chunk size `#chunkStamps` was laid out for; `0` forces a new layout. */
5761
+ #stampChunkSize = 0;
5762
+ /** How many chunk columns `#chunkStamps` has. */
5763
+ #stampChunksX = 0;
5548
5764
  #onTileChanged = new Signal();
5549
5765
  #onCollisionChanged = new Signal();
5550
5766
  /**
@@ -5560,6 +5776,7 @@ var Tilemap = class Tilemap extends Component {
5560
5776
  onAttach() {
5561
5777
  this.#grids = [];
5562
5778
  this.#built = null;
5779
+ this.#stampChunkSize = 0;
5563
5780
  this.#collision = EMPTY_COLLISION;
5564
5781
  this.#collisionDirty = true;
5565
5782
  }
@@ -5571,7 +5788,7 @@ var Tilemap = class Tilemap extends Component {
5571
5788
  this.#built = null;
5572
5789
  }
5573
5790
  /**
5574
- * Emitted whenever `setTile` changes a cell.
5791
+ * Emitted whenever `setTile` or `setCells` changes a cell.
5575
5792
  *
5576
5793
  * @returns The signal.
5577
5794
  */
@@ -5634,9 +5851,10 @@ var Tilemap = class Tilemap extends Component {
5634
5851
  * the tilemap entity's origin, with adjacent full-cell tiles merged into as few counter-clockwise
5635
5852
  * rectangles as possible.
5636
5853
  *
5637
- * @returns The collision data.
5854
+ * @returns The collision data; empty until the map has loaded.
5638
5855
  */
5639
5856
  get collisionData() {
5857
+ this.#ensureGrids();
5640
5858
  if (this.#collisionDirty) this.#rebuildCollision();
5641
5859
  return this.#collision;
5642
5860
  }
@@ -5667,21 +5885,14 @@ var Tilemap = class Tilemap extends Component {
5667
5885
  */
5668
5886
  setTile(layer, x, y, tileId) {
5669
5887
  this.#ensureGrids();
5670
- const definition = this.definition;
5888
+ const declared = this.#checkCell(layer, x, y);
5671
5889
  const grid = this.#grids[layer];
5672
- const declared = definition?.layers[layer];
5673
- if (grid === void 0 || declared === void 0 || !inRange(x, y, declared.width, declared.height)) throw twoDError(TwoDErrorCode.tileOutOfRange, `Cell ${String(x)},${String(y)} is outside layer ${String(layer)}.`, {
5674
- context: {
5675
- x,
5676
- y,
5677
- layer
5678
- },
5679
- hint: "Check the cell against Tilemap.layerSize; cell (0, 0) is the bottom-left."
5680
- });
5681
5890
  const offset = y * declared.width + x;
5682
- const previous = grid[offset] ?? 0;
5683
- if (previous === tileId) return;
5891
+ const previous = grid?.[offset] ?? 0;
5892
+ if (grid === void 0 || previous === tileId) return;
5893
+ this.#tileVersion += 1;
5684
5894
  grid[offset] = tileId;
5895
+ this.#stampCell(x, y);
5685
5896
  if (declared.collision) this.#collisionDirty = true;
5686
5897
  this.#onTileChanged.emit({
5687
5898
  layer,
@@ -5692,6 +5903,82 @@ var Tilemap = class Tilemap extends Component {
5692
5903
  });
5693
5904
  }
5694
5905
  /**
5906
+ * Writes many tiles as one change.
5907
+ *
5908
+ * @remarks
5909
+ * Each write means what the same `setTile` call means, applied in order, so a cell named twice
5910
+ * ends with the later id. The batch is checked before anything is written: one out-of-range cell
5911
+ * throws and leaves the map untouched. The renderer rebuilds each touched chunk once and the
5912
+ * collision surface merges once, however many cells changed; `onTileChanged` then fires once per
5913
+ * changed cell, after every write has landed.
5914
+ *
5915
+ * @param cells - The writes.
5916
+ * @returns How many writes changed a cell.
5917
+ * @throws IgnifxError with code `IGX-1111` when a cell is outside its layer.
5918
+ *
5919
+ * @example
5920
+ * ```ts
5921
+ * // Clear a 3x3 room on layer 0.
5922
+ * const cells: TileWrite[] = [];
5923
+ * for (let y = 4; y < 7; y += 1) {
5924
+ * for (let x = 2; x < 5; x += 1) {
5925
+ * cells.push({ layer: 0, x, y, tileId: 0 });
5926
+ * }
5927
+ * }
5928
+ * level.setCells(cells);
5929
+ * ```
5930
+ */
5931
+ setCells(cells) {
5932
+ this.#ensureGrids();
5933
+ for (let index = 0; index < cells.length; index += 1) {
5934
+ const cell = cells[index];
5935
+ if (cell !== void 0) this.#checkCell(cell.layer, cell.x, cell.y);
5936
+ }
5937
+ const changes = [];
5938
+ const definition = this.definition;
5939
+ for (let index = 0; index < cells.length; index += 1) {
5940
+ const cell = cells[index];
5941
+ const grid = cell === void 0 ? void 0 : this.#grids[cell.layer];
5942
+ const declared = cell === void 0 ? void 0 : definition?.layers[cell.layer];
5943
+ if (cell === void 0 || grid === void 0 || declared === void 0) continue;
5944
+ const offset = cell.y * declared.width + cell.x;
5945
+ const previous = grid[offset] ?? 0;
5946
+ if (previous === cell.tileId) continue;
5947
+ if (changes.length === 0) this.#tileVersion += 1;
5948
+ grid[offset] = cell.tileId;
5949
+ this.#stampCell(cell.x, cell.y);
5950
+ if (declared.collision) this.#collisionDirty = true;
5951
+ changes.push({
5952
+ layer: cell.layer,
5953
+ x: cell.x,
5954
+ y: cell.y,
5955
+ previous,
5956
+ current: cell.tileId
5957
+ });
5958
+ }
5959
+ for (let index = 0; index < changes.length; index += 1) {
5960
+ const change = changes[index];
5961
+ if (change !== void 0) this.#onTileChanged.emit(change);
5962
+ }
5963
+ return changes.length;
5964
+ }
5965
+ /**
5966
+ * When a render chunk's tiles last changed, so a `TilemapRenderer` rebuilds only the chunks a
5967
+ * `setTile` or `setCells` touched.
5968
+ *
5969
+ * @param chunkX - The chunk's column, in chunks of `chunkSize` cells.
5970
+ * @param chunkY - The chunk's row.
5971
+ * @returns An opaque stamp; it differs from the last one read exactly when the chunk changed.
5972
+ *
5973
+ * @internal
5974
+ */
5975
+ chunkStamp(chunkX, chunkY) {
5976
+ this.#ensureGrids();
5977
+ this.#ensureStamps();
5978
+ if (chunkX < 0 || chunkX >= this.#stampChunksX) return this.#tileVersion;
5979
+ return this.#chunkStamps[chunkY * this.#stampChunksX + chunkX] ?? this.#tileVersion;
5980
+ }
5981
+ /**
5695
5982
  * A layer's size, in cells.
5696
5983
  *
5697
5984
  * @param layer - The layer's index.
@@ -5772,6 +6059,58 @@ var Tilemap = class Tilemap extends Component {
5772
6059
  this.#collisionDirty = true;
5773
6060
  }
5774
6061
  /**
6062
+ * Checks a cell against its layer.
6063
+ *
6064
+ * @param layer - The layer's index.
6065
+ * @param x - The column.
6066
+ * @param y - The row.
6067
+ * @returns The layer's declaration.
6068
+ * @throws IgnifxError with code `IGX-1111` when the cell is outside the layer.
6069
+ */
6070
+ #checkCell(layer, x, y) {
6071
+ const declared = this.definition?.layers[layer];
6072
+ if (this.#grids[layer] === void 0 || declared === void 0 || !inRange(x, y, declared.width, declared.height)) throw twoDError(TwoDErrorCode.tileOutOfRange, `Cell ${String(x)},${String(y)} is outside layer ${String(layer)}.`, {
6073
+ context: {
6074
+ x,
6075
+ y,
6076
+ layer
6077
+ },
6078
+ hint: "Check the cell against Tilemap.layerSize; cell (0, 0) is the bottom-left."
6079
+ });
6080
+ return declared;
6081
+ }
6082
+ /**
6083
+ * Stamps the chunk holding a cell with the current tile version.
6084
+ *
6085
+ * @param x - The column.
6086
+ * @param y - The row.
6087
+ */
6088
+ #stampCell(x, y) {
6089
+ this.#ensureStamps();
6090
+ const chunkSize = this.#stampChunkSize;
6091
+ const chunkX = Math.floor(x / chunkSize);
6092
+ const index = Math.floor(y / chunkSize) * this.#stampChunksX + chunkX;
6093
+ if (chunkX < this.#stampChunksX && index < this.#chunkStamps.length) this.#chunkStamps[index] = this.#tileVersion;
6094
+ }
6095
+ /**
6096
+ * Lays the chunk stamps out for the current map and chunk size.
6097
+ *
6098
+ * @remarks
6099
+ * A new layout stamps every chunk with a fresh version, so whatever a renderer built under the
6100
+ * old one is rebuilt.
6101
+ */
6102
+ #ensureStamps() {
6103
+ const chunkSize = Math.max(1, this.chunkSize);
6104
+ if (chunkSize === this.#stampChunkSize) return;
6105
+ const definition = this.definition;
6106
+ const chunksX = definition === null ? 0 : Math.ceil(definition.width / chunkSize);
6107
+ const chunksY = definition === null ? 0 : Math.ceil(definition.height / chunkSize);
6108
+ this.#tileVersion += 1;
6109
+ this.#chunkStamps = new Uint32Array(chunksX * chunksY).fill(this.#tileVersion);
6110
+ this.#stampChunkSize = chunkSize;
6111
+ this.#stampChunksX = chunksX;
6112
+ }
6113
+ /**
5775
6114
  * Builds the mutable grids from the document, flipping each layer bottom-row-first.
5776
6115
  */
5777
6116
  #ensureGrids() {
@@ -5779,6 +6118,7 @@ var Tilemap = class Tilemap extends Component {
5779
6118
  if (loaded === null || loaded === this.#built) return;
5780
6119
  this.#built = loaded;
5781
6120
  this.#collisionDirty = true;
6121
+ this.#stampChunkSize = 0;
5782
6122
  const grids = [];
5783
6123
  const layers = loaded.definition.layers;
5784
6124
  for (let index = 0; index < layers.length; index += 1) {
@@ -5986,7 +6326,7 @@ var TwoDSyncSystem = class {
5986
6326
  const sprite = sprites[index];
5987
6327
  if (sprite === void 0) continue;
5988
6328
  this.#seen.add(sprite);
5989
- const atlas = sprite.atlas;
6329
+ const atlas = sprite.prepareSync();
5990
6330
  if (atlas === null || atlas.lite.atlas === null) continue;
5991
6331
  const entity = sprite.entity;
5992
6332
  const isStatic = entity.isStatic;
@@ -6422,6 +6762,16 @@ function createSpriteBatch(runtime, options) {
6422
6762
  //#endregion
6423
6763
  //#region src/service/two-d-service.ts
6424
6764
  /**
6765
+ * How many hits `app.twoD.pickAllAt` returns when no `limit` is given.
6766
+ *
6767
+ * @remarks
6768
+ * Every hit costs one more scan of its layer, so an unbounded walk over a dense stack is quadratic;
6769
+ * 64 is far deeper than any click-cycle needs. Pass `limit: Infinity` to walk the whole stack.
6770
+ *
6771
+ * @public
6772
+ */
6773
+ const DEFAULT_PICK_ALL_LIMIT = 64;
6774
+ /**
6425
6775
  * The 2D service.
6426
6776
  *
6427
6777
  * @example
@@ -6436,7 +6786,6 @@ function createSpriteBatch(runtime, options) {
6436
6786
  */
6437
6787
  var TwoDService = class {
6438
6788
  #runtime;
6439
- #factories = /* @__PURE__ */ new Map();
6440
6789
  /** Reused by `pickAt`, so picking allocates nothing. */
6441
6790
  #pickLayers = [];
6442
6791
  /** Reused by `visibleWorldBounds`. */
@@ -6453,6 +6802,14 @@ var TwoDService = class {
6453
6802
  };
6454
6803
  /** A one-element array reused by `pickAt`, because Lite's picker takes a list. */
6455
6804
  #oneLayer = [];
6805
+ /** The layers of the sprites a pick hid to look under them, restored before it returns. */
6806
+ #hiddenLayers = [];
6807
+ /** The dense indices matching {@link TwoDService.#hiddenLayers}. */
6808
+ #hiddenIndices = [];
6809
+ /** The visibility patch a pick hides and restores sprites with. */
6810
+ #visibility = createSpriteVisibilityScratch();
6811
+ /** Whether a pick is walking, so one called from its own `filter` is refused. */
6812
+ #picking = false;
6456
6813
  /**
6457
6814
  * Builds the service.
6458
6815
  *
@@ -6547,33 +6904,142 @@ var TwoDService = class {
6547
6904
  * Picks the topmost sprite under a viewport pixel (`docs/architecture/11-2d-toolkit.md` §5).
6548
6905
  *
6549
6906
  * @remarks
6550
- * Picking is a CPU test against every world layer's instance data, in draw order — no GPU
6551
- * readback and no frame of latency, which is what makes it usable from a click handler. It
6552
- * resolves only `SpriteRenderer` components: a tilemap's tiles have no component, so use
6907
+ * Picking is a CPU test against every layer's instance data, in draw order — no GPU readback and
6908
+ * no frame of latency, which is what makes it usable from a click handler. It resolves only
6909
+ * `SpriteRenderer` components: a tilemap's tiles have no component, so use
6553
6910
  * `Tilemap.worldToCell` for those.
6554
6911
  *
6912
+ * A sprite that is rejected — unpickable, destroyed, ignored, refused by `options.filter`, or a
6913
+ * tile or batch slot with no component — does not occlude: the pick goes on to the sprite under
6914
+ * it in the same sorting layer, then to the layers below.
6915
+ *
6916
+ * Cost: one scan of a layer's sprites per sprite examined in it. With nothing rejected that is one
6917
+ * scan per layer; looking under `m` rejected sprites in a layer of `n` costs `O(m·n)`, and every
6918
+ * hidden sprite costs one slot upload on the next frame.
6919
+ *
6555
6920
  * @param xPx - The viewport x, in pixels from the left edge.
6556
6921
  * @param yPx - The viewport y, in pixels from the top edge.
6922
+ * @param options - A filter, an ignore list, and whether unpickable sprites count.
6557
6923
  * @returns The hit, or `null` for a miss.
6924
+ * @throws IgnifxError with code `IGX-1119` when called from inside a pick's `filter`.
6925
+ *
6926
+ * @example
6927
+ * ```ts
6928
+ * // An editor selecting what the game cannot pick, minus locked entities.
6929
+ * const hit = app.twoD.pickAt(x, y, {
6930
+ * includeUnpickable: true,
6931
+ * filter: (entity) => !locked.has(entity),
6932
+ * });
6933
+ * ```
6558
6934
  */
6559
- pickAt(xPx, yPx) {
6935
+ pickAt(xPx, yPx, options) {
6936
+ return this.#pick(xPx, yPx, options, 1, null);
6937
+ }
6938
+ /**
6939
+ * Picks every sprite under a viewport pixel, topmost first.
6940
+ *
6941
+ * @remarks
6942
+ * The order is the draw order reversed: sorting layers front to back, and within a layer the
6943
+ * order `pickAt` would have reached them in. The same sprites are rejected as by
6944
+ * {@link TwoDService.pickAt}. Use it for click-cycling through a stack.
6945
+ *
6946
+ * Cost: one scan of a layer's sprites per sprite examined in it, so `k` hits over a layer of `n`
6947
+ * cost `O(k·n)`; hence the default `limit` of {@link DEFAULT_PICK_ALL_LIMIT}.
6948
+ *
6949
+ * @param xPx - The viewport x, in pixels from the left edge.
6950
+ * @param yPx - The viewport y, in pixels from the top edge.
6951
+ * @param options - A limit, a filter, an ignore list, and whether unpickable sprites count.
6952
+ * @returns The hits, freshly allocated; empty for a miss or a `limit` below 1.
6953
+ * @throws IgnifxError with code `IGX-1119` when called from inside a pick's `filter`.
6954
+ *
6955
+ * @example
6956
+ * ```ts
6957
+ * const stack = app.twoD.pickAllAt(x, y);
6958
+ * const next = stack[(stack.findIndex((hit) => hit.entity === selected) + 1) % stack.length];
6959
+ * ```
6960
+ */
6961
+ pickAllAt(xPx, yPx, options) {
6962
+ const out = [];
6963
+ const limit = options?.limit ?? 64;
6964
+ if (!(limit >= 1)) return out;
6965
+ this.#pick(xPx, yPx, options, limit, out);
6966
+ return out;
6967
+ }
6968
+ /**
6969
+ * The walk behind `pickAt` and `pickAllAt`.
6970
+ *
6971
+ * @param xPx - The viewport x.
6972
+ * @param yPx - The viewport y.
6973
+ * @param options - The caller's options.
6974
+ * @param limit - How many hits to accept before stopping.
6975
+ * @param out - Where to push every accepted hit, or `null` to return the first.
6976
+ * @returns The first accepted hit, or `null`.
6977
+ */
6978
+ #pick(xPx, yPx, options, limit, out) {
6979
+ if (this.#picking) throw twoDError(TwoDErrorCode.nestedPick, "app.twoD.pickAt was called from inside a pick filter.", { hint: "Collect what the filter needs before picking, or pick again after this pick returns." });
6980
+ this.#picking = true;
6560
6981
  const layers = this.#runtime.layers.collectLayers(false, this.#pickLayers);
6561
- for (let index = layers.length - 1; index >= 0; index -= 1) {
6562
- const layer = layers[index];
6563
- if (layer === void 0) continue;
6564
- const point = screenToLayer(layer.view, xPx, yPx, this.#pickPoint);
6565
- this.#oneLayer[0] = layer;
6566
- const hit = pickSprite(this.#oneLayer, point.x, point.y);
6567
- if (hit === null) continue;
6568
- const component = this.#runtime.layers.componentAt(hit.layer, hit.spriteIndex);
6569
- if (component !== null && component.pickable && !component.isDestroyed) return {
6570
- entity: component.entity,
6571
- component,
6572
- u: hit.u,
6573
- v: hit.v
6574
- };
6982
+ let found = null;
6983
+ let accepted = 0;
6984
+ try {
6985
+ for (let index = layers.length - 1; index >= 0 && accepted < limit; index -= 1) {
6986
+ const layer = layers[index];
6987
+ if (layer === void 0) continue;
6988
+ const point = screenToLayer(layer.view, xPx, yPx, this.#pickPoint);
6989
+ this.#oneLayer[0] = layer;
6990
+ for (let hit = pickSprite(this.#oneLayer, point.x, point.y); hit !== null;) {
6991
+ const component = this.#runtime.layers.componentAt(hit.layer, hit.spriteIndex);
6992
+ if (component !== null && this.#accepts(component, options)) {
6993
+ const pick = {
6994
+ entity: component.entity,
6995
+ component,
6996
+ u: hit.u,
6997
+ v: hit.v
6998
+ };
6999
+ accepted += 1;
7000
+ if (out === null) {
7001
+ found = pick;
7002
+ break;
7003
+ }
7004
+ out.push(pick);
7005
+ if (accepted >= limit) break;
7006
+ }
7007
+ setSpriteVisibleAt(hit.layer, hit.spriteIndex, this.#visibility, false);
7008
+ this.#hiddenLayers.push(hit.layer);
7009
+ this.#hiddenIndices.push(hit.spriteIndex);
7010
+ hit = pickSprite(this.#oneLayer, point.x, point.y);
7011
+ }
7012
+ }
7013
+ } finally {
7014
+ this.#restoreHidden();
7015
+ this.#picking = false;
6575
7016
  }
6576
- return null;
7017
+ return found;
7018
+ }
7019
+ /**
7020
+ * Whether a candidate sprite passes the pick's rules.
7021
+ *
7022
+ * @param component - The candidate.
7023
+ * @param options - The caller's options.
7024
+ * @returns `true` to accept it.
7025
+ */
7026
+ #accepts(component, options) {
7027
+ if (component.isDestroyed) return false;
7028
+ if (!component.pickable && options?.includeUnpickable !== true) return false;
7029
+ if (options === void 0) return true;
7030
+ const entity = component.entity;
7031
+ if (options.ignore?.includes(entity) === true) return false;
7032
+ return options.filter === void 0 || options.filter(entity, component);
7033
+ }
7034
+ /** Shows every sprite a pick hid, last hidden first. */
7035
+ #restoreHidden() {
7036
+ for (let index = this.#hiddenLayers.length - 1; index >= 0; index -= 1) {
7037
+ const layer = this.#hiddenLayers[index];
7038
+ const spriteIndex = this.#hiddenIndices[index];
7039
+ if (layer !== void 0 && spriteIndex !== void 0) setSpriteVisibleAt(layer, spriteIndex, this.#visibility, true);
7040
+ }
7041
+ this.#hiddenLayers.length = 0;
7042
+ this.#hiddenIndices.length = 0;
6577
7043
  }
6578
7044
  /**
6579
7045
  * Claims a fixed-capacity crowd of sprites that no entity owns
@@ -6620,50 +7086,6 @@ var TwoDService = class {
6620
7086
  return true;
6621
7087
  }
6622
7088
  /**
6623
- * Registers the factory that turns one kind of tilemap object into an entity
6624
- * (`docs/architecture/11-2d-toolkit.md` §2.5).
6625
- *
6626
- * @param type - The object `type` the map writes.
6627
- * @param factory - Builds the entity, or returns `null` to spawn nothing.
6628
- * @throws IgnifxError with code `IGX-1110` when a factory for the type is already registered.
6629
- *
6630
- * @example
6631
- * ```ts
6632
- * app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
6633
- * const player = world.createEntity({ name: "player" });
6634
- * player.transform.position2D = new Vec2(position.x, position.y);
6635
- * return player;
6636
- * });
6637
- * ```
6638
- */
6639
- registerTileObjectFactory(type, factory) {
6640
- if (this.#factories.has(type)) throw twoDError(TwoDErrorCode.duplicateObjectFactory, `A tile object factory for ${type} is already registered.`, {
6641
- context: { type },
6642
- hint: "Unregister the first one, or give the second object type its own name."
6643
- });
6644
- this.#factories.set(type, factory);
6645
- }
6646
- /**
6647
- * Removes a tile-object factory.
6648
- *
6649
- * @param type - The object type.
6650
- * @returns `true` when a factory was registered.
6651
- */
6652
- unregisterTileObjectFactory(type) {
6653
- return this.#factories.delete(type);
6654
- }
6655
- /**
6656
- * The factory registered for an object type.
6657
- *
6658
- * @param type - The object type.
6659
- * @returns The factory, or `null`.
6660
- *
6661
- * @internal
6662
- */
6663
- tileObjectFactory(type) {
6664
- return this.#factories.get(type) ?? null;
6665
- }
6666
- /**
6667
7089
  * Converts a viewport pixel into a world point through the active camera.
6668
7090
  *
6669
7091
  * @param xPx - The viewport x.
@@ -6778,113 +7200,18 @@ function spriteClearColor(app) {
6778
7200
  };
6779
7201
  }
6780
7202
  //#endregion
6781
- //#region src/tilemap/spawn-objects.ts
6782
- /**
6783
- * Run the game's tile-object factories once per scene load, on `world.onSceneLoaded`.
6784
- * `awake` and `onEnable` have finished by then, so factories can use the scene's components.
6785
- */
7203
+ //#region src/version.ts
6786
7204
  /**
6787
- * Runs the registered factory for every object in every `Tilemap` in a scene.
7205
+ * The `@ignifx/2d` version this build was cut from, reported as `Extension.version`
7206
+ * (`docs/architecture/04-extensions.md` §1).
6788
7207
  *
6789
7208
  * @remarks
6790
- * An object whose `type` has no registered factory is skipped silently: a map routinely carries
6791
- * markers a given game does not use, and refusing to load the scene over one would make maps and
6792
- * code impossible to version independently. A factory that throws is reported to `app.onError`
6793
- * and the remaining objects still spawn, which is the same containment the frame loop gives a
6794
- * script callback.
6795
- *
6796
- * A `Tilemap` whose document has not finished loading spawns nothing now; the next scene load, or
6797
- * an explicit {@link spawnTilemapObjects} call, does it.
6798
- *
6799
- * @param app - The app.
6800
- * @param service - The 2D service holding the factory registry.
6801
- * @param scene - The scene that just loaded.
6802
- *
6803
- * @internal
6804
- */
6805
- function spawnTileObjects(app, service, scene) {
6806
- const tilemaps = app.world.components(Tilemap);
6807
- for (let index = 0; index < tilemaps.length; index += 1) {
6808
- const tilemap = tilemaps[index];
6809
- if (tilemap === void 0 || tilemap.entity.scene !== scene) continue;
6810
- spawnTilemapObjects(app, service, tilemap);
6811
- }
6812
- }
6813
- /**
6814
- * Runs the registered factory for every object in one tilemap.
6815
- *
6816
- * @param app - The app.
6817
- * @param service - The 2D service holding the factory registry.
6818
- * @param tilemap - The tilemap whose objects layer to walk.
6819
- * @returns The entities that were created, in document order.
6820
- *
6821
- * @example
6822
- * ```ts
6823
- * app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
6824
- * const player = world.createEntity({ name: "player" });
6825
- * player.transform.position2D = new Vec2(position.x, position.y);
6826
- * return player;
6827
- * });
6828
- * ```
6829
- *
6830
- * @public
6831
- */
6832
- function spawnTilemapObjects(app, service, tilemap) {
6833
- const definition = tilemap.definition;
6834
- if (definition === null) return EMPTY;
6835
- const matrix = tilemap.entity.transform.worldMatrix;
6836
- const originX = matrix[12] ?? 0;
6837
- const originY = matrix[13] ?? 0;
6838
- const spawned = [];
6839
- for (let index = 0; index < definition.objects.length; index += 1) {
6840
- const object = definition.objects[index];
6841
- if (object === void 0) continue;
6842
- const factory = service.tileObjectFactory(object.type);
6843
- if (factory === null) continue;
6844
- try {
6845
- const entity = factory({
6846
- world: app.world,
6847
- name: object.name,
6848
- type: object.type,
6849
- position: {
6850
- x: originX + object.x,
6851
- y: originY + object.y
6852
- },
6853
- size: {
6854
- x: object.width,
6855
- y: object.height
6856
- },
6857
- properties: object.properties,
6858
- tilemap: tilemap.entity
6859
- });
6860
- if (entity !== null) spawned.push(entity);
6861
- } catch (error) {
6862
- app.onError.emit({
6863
- error,
6864
- source: "extension",
6865
- phase: null,
6866
- entity: tilemap.entity,
6867
- component: tilemap
6868
- });
6869
- }
6870
- }
6871
- return spawned;
6872
- }
6873
- /** The result of spawning from a tilemap with nothing loaded. */
6874
- const EMPTY = Object.freeze([]);
6875
- //#endregion
6876
- //#region src/version.ts
6877
- /**
6878
- * The package's own version, reported as `Extension.version`
6879
- * (`docs/architecture/04-extensions.md` §1). First-party packages ship one version line, so this
6880
- * tracks `package.json` and the release tooling bumps both together.
6881
- */
6882
- /**
6883
- * The `@ignifx/2d` version this build was cut from.
7209
+ * The build stamps it from `package.json`; code run from source, such as this repository's tests,
7210
+ * sees `"0.0.0"`.
6884
7211
  *
6885
7212
  * @public
6886
7213
  */
6887
- const VERSION = "0.0.0";
7214
+ const VERSION = "0.11.0";
6888
7215
  //#endregion
6889
7216
  //#region src/extension.ts
6890
7217
  /**
@@ -7000,7 +7327,8 @@ function registerTwoD(ctx, options) {
7000
7327
  });
7001
7328
  ctx.registerSystem(new TwoDAnimationSystem(runtime), {
7002
7329
  phase: Phase.PostUpdate,
7003
- order: 0
7330
+ order: 0,
7331
+ editMode: "skip"
7004
7332
  });
7005
7333
  ctx.registerAssetLoader(createSpriteAtlasLoader());
7006
7334
  ctx.registerAssetLoader(createSpriteAnimationLoader());
@@ -7008,7 +7336,6 @@ function registerTwoD(ctx, options) {
7008
7336
  ctx.registerComponents(components());
7009
7337
  runtime.setSceneHandler((scene) => {
7010
7338
  applySceneSettings(app, runtime, settings, scene);
7011
- spawnTileObjects(app, service, scene);
7012
7339
  });
7013
7340
  const removeCameraSource = app.renderer.addCameraSource((world) => selectCamera(world) !== null);
7014
7341
  ctx.onDispose(() => {
@@ -7092,7 +7419,7 @@ function spriteAtlasFileSchema() {
7092
7419
  sampling: enumOf(["linear", "nearest"], "linear", { tooltip: "Min/mag filter; nearest for pixel art." }),
7093
7420
  premultipliedAlpha: bool(false, { tooltip: "Whether the image's RGB is already multiplied by its alpha." }),
7094
7421
  frames: array(record({
7095
- name: str("", { tooltip: "The frame's name; what #frame: addresses." }),
7422
+ name: str("", { tooltip: "The frame's name; what SpriteRenderer.frameName names." }),
7096
7423
  x: f32(0, {
7097
7424
  min: 0,
7098
7425
  tooltip: "The left edge, in image pixels."
@@ -7117,7 +7444,7 @@ function spriteAtlasFileSchema() {
7117
7444
  x: 0,
7118
7445
  y: 0
7119
7446
  }, { tooltip: "The untrimmed size, when the packer trimmed the frame." })
7120
- }), [], { tooltip: "The frames, in the order they are indexed. Each is a record of name (str, what #frame: addresses), x/y (f32, the top-left corner in image pixels), w/h (f32, the size in image pixels), pivot (vec2 in [0,1] of the frame; [0,0] is top-left) and sourceSize (vec2, the untrimmed size when the packer trimmed the frame)." })
7447
+ }), [], { tooltip: "The frames, in the order they are indexed. Each is a record of name (str, what SpriteRenderer.frameName names), x/y (f32, the top-left corner in image pixels), w/h (f32, the size in image pixels), pivot (vec2 in [0,1] of the frame; [0,0] is top-left) and sourceSize (vec2, the untrimmed size when the packer trimmed the frame)." })
7121
7448
  });
7122
7449
  }
7123
7450
  /**
@@ -7202,7 +7529,7 @@ function tilemapFileSchema() {
7202
7529
  }), [], { tooltip: "The tile layers, back to front." }),
7203
7530
  objects: array(record({
7204
7531
  name: str("", { tooltip: "The object's name." }),
7205
- type: str("", { tooltip: "The object's type; what selects a TileObjectFactory." }),
7532
+ type: str("", { tooltip: "The object's type, which `ignifx import tilemap` writes as the entity's tag." }),
7206
7533
  x: f32(0, { tooltip: "The bottom-left corner, in world metres." }),
7207
7534
  y: f32(0, { tooltip: "The bottom-left corner, in world metres." }),
7208
7535
  width: f32(0, {
@@ -7213,7 +7540,7 @@ function tilemapFileSchema() {
7213
7540
  min: 0,
7214
7541
  tooltip: "The height, in world metres."
7215
7542
  })
7216
- }), [], { tooltip: "The objects layer." }),
7543
+ }), [], { tooltip: "The objects layer: authoring data that `ignifx import tilemap` moves into a scene." }),
7217
7544
  properties: map(str(), { tooltip: "The map's custom properties." })
7218
7545
  });
7219
7546
  }
@@ -8292,6 +8619,6 @@ function readArray(source, key) {
8292
8619
  return isUnknownArray(value) ? value : [];
8293
8620
  }
8294
8621
  //#endregion
8295
- export { Camera2D, Camera2DFollow, DEFAULT_CHUNK_SIZE, DEFAULT_CLIP_FPS, DEFAULT_ORTHOGRAPHIC_SIZE, DEFAULT_PIXELS_PER_UNIT, DEFAULT_REFERENCE_RESOLUTION, DEFAULT_SORTING_LAYER, EMPTY_TILE_ID, LDTK_DEFAULT_INTGRID_COLLIDERS, LDTK_INTGRID_TILESET_NAME, ParallaxLayer, SORTING_LAYER_ORDER_STEP, SPRITE_ANIMATION_ASSET_TYPE, SPRITE_ANIMATION_FILE_EXTENSIONS, SPRITE_ANIMATION_FORMAT, SPRITE_ANIMATION_FORMAT_VERSION, SPRITE_ATLAS_ASSET_TYPE, SPRITE_ATLAS_FILE_EXTENSIONS, SPRITE_ATLAS_FORMAT, SPRITE_ATLAS_FORMAT_VERSION, SPRITE_BLEND_MODES, SPRITE_EFFECT_KINDS, SPRITE_FRAME_FRAGMENT_PREFIX, SortingLayerTable, SpriteAnimationAsset, SpriteAnimator, SpriteAtlasAsset, SpriteLayerEffect, SpriteLayerRegistry, SpriteRenderer, TILEMAP_ASSET_TYPE, TILEMAP_FILE_EXTENSIONS, TILEMAP_FORMAT, TILEMAP_FORMAT_VERSION, TINT_EFFECT_WGSL, TWO_D_ANIMATION_ORDER, TWO_D_ERROR_MESSAGES, TWO_D_MODES, TWO_D_SETTINGS_SECTION, TWO_D_SYNC_ORDER, Tilemap, TilemapAsset, TilemapRenderer, TwoDAnimationSystem, TwoDErrorCode, TwoDService, TwoDSyncSystem, VERSION, asepriteFrameName, createSpriteAnimationLoader, createSpriteAtlasLoader, createTilemapLoader, decodeTileRle, defaultTwoDSettings, defineSpriteAnimation, defineSpriteAtlas, defineTilemap, describeSchemas, describeSpriteAnimationFormat, describeSpriteAtlasFormat, describeTilemapFormat, describeTwoDSchemas, encodeTileRle, fieldInstancesToRecord, findTileset, gridAtlas, importAsepriteAnimations, importAsepriteAtlas, importLdtkLevel, importTexturePackerAtlas, importTiledMap, isFullCellSolid, mergeTileCollisions, normalisePath, parseSpriteFragment, pivotedPositionToRef, pixelsToWorldToRef, readVec2, resolveClipFrames, resolveRelative, selectCamera, sizeForZoom, snapPixel, snapZoomToInteger, spawnTilemapObjects, spriteAnimationFileSchema, spriteAnimationJsonSchema, spriteAtlasFileSchema, spriteAtlasJsonSchema, spriteLayerKey, spriteRotationFromLite, spriteRotationToLite, tileCollisionInfo, tileFrameName, tiledPropertiesToRecord, tilemapFileSchema, tilemapJsonSchema, twoD, twoDError, twoDSettingsSchema, viewRotationToLite, worldToPixelsToRef, zoomForSize };
8622
+ export { Camera2D, Camera2DFollow, DEFAULT_CHUNK_SIZE, DEFAULT_CLIP_FPS, DEFAULT_ORTHOGRAPHIC_SIZE, DEFAULT_PICK_ALL_LIMIT, DEFAULT_PIXELS_PER_UNIT, DEFAULT_REFERENCE_RESOLUTION, DEFAULT_SORTING_LAYER, EMPTY_TILE_ID, LDTK_DEFAULT_INTGRID_COLLIDERS, LDTK_INTGRID_TILESET_NAME, ParallaxLayer, SORTING_LAYER_ORDER_STEP, SPRITE_ANIMATION_ASSET_TYPE, SPRITE_ANIMATION_FILE_EXTENSIONS, SPRITE_ANIMATION_FORMAT, SPRITE_ANIMATION_FORMAT_VERSION, SPRITE_ATLAS_ASSET_TYPE, SPRITE_ATLAS_FILE_EXTENSIONS, SPRITE_ATLAS_FORMAT, SPRITE_ATLAS_FORMAT_VERSION, SPRITE_BLEND_MODES, SPRITE_EFFECT_KINDS, SPRITE_FRAME_FRAGMENT_PREFIX, SortingLayerTable, SpriteAnimationAsset, SpriteAnimator, SpriteAtlasAsset, SpriteLayerEffect, SpriteLayerRegistry, SpriteRenderer, TILEMAP_ASSET_TYPE, TILEMAP_FILE_EXTENSIONS, TILEMAP_FORMAT, TILEMAP_FORMAT_VERSION, TINT_EFFECT_WGSL, TWO_D_ANIMATION_ORDER, TWO_D_ERROR_MESSAGES, TWO_D_MODES, TWO_D_SETTINGS_SECTION, TWO_D_SYNC_ORDER, Tilemap, TilemapAsset, TilemapRenderer, TwoDAnimationSystem, TwoDErrorCode, TwoDService, TwoDSyncSystem, VERSION, asepriteFrameName, createSpriteAnimationLoader, createSpriteAtlasLoader, createTilemapLoader, decodeTileRle, defaultTwoDSettings, defineSpriteAnimation, defineSpriteAtlas, defineTilemap, describeSchemas, describeSpriteAnimationFormat, describeSpriteAtlasFormat, describeTilemapFormat, describeTwoDSchemas, encodeTileRle, fieldInstancesToRecord, findTileset, gridAtlas, importAsepriteAnimations, importAsepriteAtlas, importLdtkLevel, importTexturePackerAtlas, importTiledMap, isFullCellSolid, mergeTileCollisions, normalisePath, parseSpriteFragment, pivotedPositionToRef, pixelsToWorldToRef, readVec2, resolveClipFrames, resolveRelative, selectCamera, sizeForZoom, snapPixel, snapZoomToInteger, spriteAnimationFileSchema, spriteAnimationJsonSchema, spriteAtlasFileSchema, spriteAtlasJsonSchema, spriteLayerKey, spriteRotationFromLite, spriteRotationToLite, tileCollisionInfo, tileFrameName, tiledPropertiesToRecord, tilemapFileSchema, tilemapJsonSchema, twoD, twoDError, twoDSettingsSchema, viewRotationToLite, worldToPixelsToRef, zoomForSize };
8296
8623
 
8297
8624
  //# sourceMappingURL=index.js.map