@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/tilemap-owner-boundary.unit.test.ts

@@ -0,0 +1,66 @@
+import { World } from '@forgeax/engine-ecs';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import {
+  resetTilemapChunkExtractCache,
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
+import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
+
+describe('tilemap extraction owner boundary', () => {
+  it('recognizes canonical scene ChildOf and Transform tokens', () => {
+    const world = new World();
+    const tileset = {
+      kind: 'tileset' as const,
+      atlases: ['test/atlas'],
+      tileWidth: 1,
+      tileHeight: 1,
+      columns: 1,
+      rows: 1,
+      regions: [{ x: 0, y: 0, width: 1, height: 1 }],
+      tiles: [{ regionIndex: 0 }],
+    };
+    const lookup = makeTilemapAssetLookup(tileset);
+    const tilemap = world
+      .spawn(
+        {
+          component: Tilemap,
+          data: {
+            cols: 1,
+            rows: 1,
+            tileSize: [1, 1],
+            chunkSize: 1,
+            tileset: 'test/tileset',
+          },
+        },
+        { component: Transform, data: {} },
+      )
+      .unwrap();
+    world
+      .spawn(
+        {
+          component: TileLayer,
+          data: {
+            tiles: new Uint32Array([1]),
+            layerOrder: 0,
+            dirty: 1,
+            sortScope: 0,
+          },
+        },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+
+    resetTilemapChunkExtractCache();
+    tilemapChunkExtractSystem(world, lookup);
+
+    const derived = world
+      .inspect()
+      .archetypes.find(
+        (arch) =>
+          arch.componentNames.includes('MeshFilter') && arch.componentNames.includes('Transform'),
+      );
+    expect(derived?.entityCount).toBe(1);
+  });
+});

package/src/__tests__/tilemap-region-pack.test.ts

@@ -0,0 +1,149 @@
+// tilemap-region-pack.test - per-cell entity Transform packing in cell units
+// (feat-20260608 M0 baseline rebuild).
+//
+// Asserts the M0 1x1 unit-cell packing rules baked into
+// `spawnDerivedRenderEntities`:
+//
+//   posX = (cellX + 0.5) * tileSizeX
+//   posY = (cellY + 0.5) * tileSizeY
+//   scaleX = +/- tileSizeX (sign encodes flipH)
+//   scaleY = +/- tileSizeY (sign encodes flipV)
+//   quatZ / quatW = D ? SQRT1_2 : 0 / D ? SQRT1_2 : 1
+//
+// M0 boundary: width/heightCells / pivotX/Y are NOT consumed yet (M2
+// `feat-20260608` D-2 widens the form). 1x1 unit-cell only.
+//
+// Anchors: plan-tasks m0-t9; plan-strategy §D-1 per-cell entity TRS;
+// plan-strategy §M0 (1x1 unit-cell baseline only).
+
+import { World } from '@forgeax/engine-ecs';
+import { encodeTileBits } from '@forgeax/engine-graphics-extras';
+import { Layer, MeshFilter } from '@forgeax/engine-render';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import type { TilesetAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { encodeSortScope } from '../../../render/src/components/tile-layer';
+import {
+  resetTilemapChunkExtractCache,
+  resetTilemapDerivedEntityTracker,
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
+import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
+
+function setup(opts: {
+  cols: number;
+  rows: number;
+  tileSize: readonly [number, number];
+  tiles: Uint32Array;
+}) {
+  const world = new World();
+  const tileset: TilesetAsset = {
+    kind: 'tileset',
+    atlases: ['test/atlas'],
+    tileWidth: 16,
+    tileHeight: 16,
+    columns: opts.cols,
+    rows: opts.rows,
+    regions: [{ x: 0, y: 0, width: 16, height: 16 }],
+    tiles: [{ regionIndex: 0 }],
+  };
+  const lookup = makeTilemapAssetLookup(tileset);
+  const tilemap = world
+    .spawn(
+      {
+        component: Tilemap,
+        data: {
+          cols: opts.cols,
+          rows: opts.rows,
+          tileSize: opts.tileSize,
+          chunkSize: 4,
+          tileset: 'test/tileset',
+        },
+      },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+  world.spawn(
+    {
+      component: TileLayer,
+      data: { tiles: opts.tiles, layerOrder: 0, dirty: 1, sortScope: encodeSortScope('per-cell') },
+    },
+    { component: ChildOf, data: { parent: tilemap } },
+  );
+  resetTilemapChunkExtractCache();
+  resetTilemapDerivedEntityTracker();
+  return { world, lookup };
+}
+
+function readDerivedTransforms(world: World): Array<{
+  posX: number;
+  posY: number;
+  scaleX: number;
+  scaleY: number;
+  quatZ: number;
+  quatW: number;
+}> {
+  const out: Array<{
+    posX: number;
+    posY: number;
+    scaleX: number;
+    scaleY: number;
+    quatZ: number;
+    quatW: number;
+  }> = [];
+  const query = world.query({ read: [Transform], with: [MeshFilter, Layer] }).unwrap();
+  for (const row of query) {
+    const t = row.get(Transform);
+    out.push({
+      posX: t.pos[0] ?? 0,
+      posY: t.pos[1] ?? 0,
+      scaleX: t.scale[0] ?? 1,
+      scaleY: t.scale[1] ?? 1,
+      quatZ: t.quat[2] ?? 0,
+      quatW: t.quat[3] ?? 1,
+    });
+  }
+  return out;
+}
+
+describe('tilemap region pack — M0 1x1 unit-cell Transform field assertions', () => {
+  it('non-unit tileSize: posX/posY follow (cellX + 0.5) * tileSize', () => {
+    const tiles = new Uint32Array(2);
+    tiles[0] = 1; // (0, 0)
+    tiles[1] = 1; // (1, 0)
+    const { world, lookup } = setup({ cols: 2, rows: 1, tileSize: [32, 16], tiles });
+    tilemapChunkExtractSystem(world, lookup);
+    const xs = readDerivedTransforms(world)
+      .map((t) => t.posX)
+      .sort((a, b) => a - b);
+    expect(xs[0]).toBeCloseTo(0.5 * 32, 5);
+    expect(xs[1]).toBeCloseTo(1.5 * 32, 5);
+  });
+
+  it('default tileSize (1, 1) on a 1x1 cell anchored at (0, 0)', () => {
+    const tiles = new Uint32Array([1]);
+    const { world, lookup } = setup({ cols: 1, rows: 1, tileSize: [1, 1], tiles });
+    tilemapChunkExtractSystem(world, lookup);
+    const transforms = readDerivedTransforms(world);
+    expect(transforms.length).toBe(1);
+    const t = transforms[0];
+    if (t === undefined) throw new Error('expected one derived Transform');
+    expect(t.posX).toBeCloseTo(0.5, 5);
+    expect(t.posY).toBeCloseTo(0.5, 5);
+    expect(t.scaleX).toBe(1);
+    expect(t.scaleY).toBe(1);
+    expect(t.quatZ).toBe(0);
+    expect(t.quatW).toBe(1);
+  });
+
+  it('flipH alone negates scaleX, flipV alone negates scaleY (per-cell sign)', () => {
+    const tiles = new Uint32Array([encodeTileBits(1, true, false, false, false)]);
+    const { world, lookup } = setup({ cols: 1, rows: 1, tileSize: [1, 1], tiles });
+    tilemapChunkExtractSystem(world, lookup);
+    const t = readDerivedTransforms(world)[0];
+    if (t === undefined) throw new Error('expected one derived Transform');
+    expect(t.scaleX).toBe(-1);
+    expect(t.scaleY).toBe(1);
+  });
+});

package/src/__tests__/tilemap-spawn-flip-pivot.test.ts

@@ -0,0 +1,270 @@
+// tilemap-spawn-flip-pivot.test - 32 case H/V/D flip x pivot matrix
+// (feat-20260608 M2 / m2-t1; plan-strategy §D-2).
+//
+// Asserts the per-cell entity Transform produced by
+// `spawnDerivedRenderEntities` for the multi-cell + custom pivot form:
+//
+//   basePivotForX = D ? pivotY : pivotX
+//   basePivotForY = D ? pivotX : pivotY
+//   effectivePivotX = H ? (1 - basePivotForX) : basePivotForX
+//   effectivePivotY = V ? (1 - basePivotForY) : basePivotForY
+//   posX = (cellX + effectivePivotX + (0.5 - effectivePivotX) * widthCells)
+//          * tileSizeX
+//   posY = (cellY + effectivePivotY + (0.5 - effectivePivotY) * heightCells)
+//          * tileSizeY
+//   scaleX = (H ? -1 : 1) * widthCells  * tileSizeX
+//   scaleY = (V ? -1 : 1) * heightCells * tileSizeY
+//   quatZ  = D ? Math.SQRT1_2 : 0
+//   quatW  = D ? Math.SQRT1_2 : 1
+//
+// The matrix iterates H/V/D in {false, true}^3 (8 combinations) x
+// pivot in {0.0, 0.2, 0.5, 0.8} (4 combinations applied to both X and Y) =
+// 32 cases. R-3 numerical anchor: V flip x pivotY=0.2, heightCells=4
+// drives a 2.4-cell delta in the offset (0.5 - effectivePivotY) *
+// heightCells term (1.2 -> -1.2). Total Transform.posY delta versus the
+// no-flip form is 1.8 cells (delta-eff + delta-offset = 0.6 - 2.4).
+//
+// FALSIFY mode `invert-pivot-on-vflip`: the implementation must use
+// effectivePivotY = 1 - pivotY under V flip. If a future regression
+// breaks that, the same test fails - which is the intended falsifier
+// signal (plan-strategy §D-2 + AC-10).
+//
+// Anchors: plan-tasks m2-t1; plan-strategy §D-2 (formula first-line +
+// 32 case matrix); plan-decisions L-3 (pivot ground truth) + L-4
+// (`requirements.md §AC-10 falsifier` charter F1 alignment).
+
+import { World } from '@forgeax/engine-ecs';
+import { encodeTileBits } from '@forgeax/engine-graphics-extras';
+import { Layer, MeshFilter } from '@forgeax/engine-render';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import type { TilesetAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { encodeSortScope } from '../../../render/src/components/tile-layer';
+import {
+  resetTilemapChunkExtractCache,
+  resetTilemapDerivedEntityTracker,
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
+import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
+
+const SQRT1_2 = Math.SQRT1_2;
+
+interface Setup {
+  widthCells: number;
+  heightCells: number;
+  pivotX: number;
+  pivotY: number;
+  cellX: number;
+  cellY: number;
+  flipH: boolean;
+  flipV: boolean;
+  flipDiagonal: boolean;
+  tileSize: readonly [number, number];
+}
+
+function expectedTransform(s: Setup): {
+  posX: number;
+  posY: number;
+  scaleX: number;
+  scaleY: number;
+  quatZ: number;
+  quatW: number;
+} {
+  const basePivotForX = s.flipDiagonal ? s.pivotY : s.pivotX;
+  const basePivotForY = s.flipDiagonal ? s.pivotX : s.pivotY;
+  const effX = s.flipH ? 1 - basePivotForX : basePivotForX;
+  const effY = s.flipV ? 1 - basePivotForY : basePivotForY;
+  return {
+    posX: (s.cellX + effX + (0.5 - effX) * s.widthCells) * s.tileSize[0],
+    posY: (s.cellY + effY + (0.5 - effY) * s.heightCells) * s.tileSize[1],
+    scaleX: (s.flipH ? -1 : 1) * s.widthCells * s.tileSize[0],
+    scaleY: (s.flipV ? -1 : 1) * s.heightCells * s.tileSize[1],
+    quatZ: s.flipDiagonal ? SQRT1_2 : 0,
+    quatW: s.flipDiagonal ? SQRT1_2 : 1,
+  };
+}
+
+function readDerivedTransform(world: World): {
+  posX: number;
+  posY: number;
+  scaleX: number;
+  scaleY: number;
+  quatZ: number;
+  quatW: number;
+} {
+  const query = world.query({ read: [Transform], with: [MeshFilter, Layer] }).unwrap();
+  for (const row of query) {
+    const t = row.get(Transform);
+    return {
+      posX: t.pos[0] ?? 0,
+      posY: t.pos[1] ?? 0,
+      scaleX: t.scale[0] ?? 1,
+      scaleY: t.scale[1] ?? 1,
+      quatZ: t.quat[2] ?? 0,
+      quatW: t.quat[3] ?? 1,
+    };
+  }
+  throw new Error('expected one derived Transform but found none');
+}
+
+function runOneCase(s: Setup): {
+  posX: number;
+  posY: number;
+  scaleX: number;
+  scaleY: number;
+  quatZ: number;
+  quatW: number;
+} {
+  const world = new World();
+  const tileset: TilesetAsset = {
+    kind: 'tileset',
+    atlases: ['test/atlas'],
+    tileWidth: 16,
+    tileHeight: 16,
+    columns: 1,
+    rows: 1,
+    regions: [{ x: 0, y: 0, width: 16, height: 16 }],
+    tiles: [
+      {
+        regionIndex: 0,
+        widthCells: s.widthCells,
+        heightCells: s.heightCells,
+        pivotX: s.pivotX,
+        pivotY: s.pivotY,
+      },
+    ],
+  };
+  const lookup = makeTilemapAssetLookup(tileset);
+  const cols = Math.max(s.cellX + s.widthCells + 1, 16);
+  const rows = Math.max(s.cellY + s.heightCells + 1, 16);
+  const tilemap = world
+    .spawn(
+      {
+        component: Tilemap,
+        data: {
+          cols,
+          rows,
+          tileSize: s.tileSize,
+          chunkSize: 16,
+          tileset: 'test/tileset',
+        },
+      },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+  const tiles = new Uint32Array(cols * rows);
+  tiles[s.cellY * cols + s.cellX] = encodeTileBits(1, s.flipH, s.flipV, s.flipDiagonal, false);
+  world.spawn(
+    {
+      component: TileLayer,
+      data: { tiles, layerOrder: 0, dirty: 1, sortScope: encodeSortScope('per-cell') },
+    },
+    { component: ChildOf, data: { parent: tilemap } },
+  );
+  resetTilemapChunkExtractCache();
+  resetTilemapDerivedEntityTracker();
+  tilemapChunkExtractSystem(world, lookup);
+  return readDerivedTransform(world);
+}
+
+describe('spawnDerivedRenderEntities — 32 case H/V/D flip x pivot matrix (M2)', () => {
+  const widthCells = 3;
+  const heightCells = 4;
+  const tileSizeX = 16;
+  const tileSizeY = 16;
+  const cellX = 5;
+  const cellY = 10;
+  const pivots = [0.0, 0.2, 0.5, 0.8] as const;
+
+  for (const flipH of [false, true] as const) {
+    for (const flipV of [false, true] as const) {
+      for (const flipDiagonal of [false, true] as const) {
+        for (const pivot of pivots) {
+          const tag = `H=${flipH ? 1 : 0} V=${flipV ? 1 : 0} D=${flipDiagonal ? 1 : 0} pivot=${pivot}`;
+          it(`case ${tag} matches plan-strategy §D-2 formula`, () => {
+            const setup: Setup = {
+              widthCells,
+              heightCells,
+              pivotX: pivot,
+              pivotY: pivot,
+              cellX,
+              cellY,
+              flipH,
+              flipV,
+              flipDiagonal,
+              tileSize: [tileSizeX, tileSizeY],
+            };
+            const got = runOneCase(setup);
+            const want = expectedTransform(setup);
+            expect(got.posX).toBeCloseTo(want.posX, 4);
+            expect(got.posY).toBeCloseTo(want.posY, 4);
+            expect(got.scaleX).toBeCloseTo(want.scaleX, 4);
+            expect(got.scaleY).toBeCloseTo(want.scaleY, 4);
+            expect(got.quatZ).toBeCloseTo(want.quatZ, 5);
+            expect(got.quatW).toBeCloseTo(want.quatW, 5);
+          });
+        }
+      }
+    }
+  }
+
+  // R-3 numerical anchor: V flip x pivotY=0.2 must shift the (0.5 - eff)
+  // offset by exactly 2.4 cells (0.6 cell-budget x heightCells=4). The
+  // total posY delta versus the no-flip form is 1.8 cells (delta-eff =
+  // -0.6 cell + delta-offset = -2.4 cell ... wait: posY_vflip - posY_nf
+  // = -1.8 cells * tileSize). The 2.4-cell budget below isolates the
+  // (0.5 - effectivePivotY) * heightCells term so the falsifier is
+  // independent of the (eff - pivot) shift.
+  it('R-3 anchor: V flip x pivotY=0.2 offset budget = 2.4 cell', () => {
+    const baseSetup: Setup = {
+      widthCells,
+      heightCells,
+      pivotX: 0.5,
+      pivotY: 0.2,
+      cellX,
+      cellY,
+      flipH: false,
+      flipV: false,
+      flipDiagonal: false,
+      tileSize: [tileSizeX, tileSizeY],
+    };
+    const noFlipPosY = expectedTransform(baseSetup).posY;
+    const vFlipPosY = expectedTransform({ ...baseSetup, flipV: true }).posY;
+    const totalDeltaCells = (noFlipPosY - vFlipPosY) / tileSizeY;
+    // Total delta = (0.5 - 0.2) * 4 - ((1 - 0.2) - 0.2) - (0.5 - (1-0.2)) * 4
+    //             = 1.2 - 0.6 - (-1.2) = 1.8 cells
+    expect(totalDeltaCells).toBeCloseTo(1.8, 5);
+
+    const noFlipOffset = (0.5 - 0.2) * heightCells;
+    const vFlipOffset = (0.5 - (1 - 0.2)) * heightCells;
+    const offsetDeltaCells = noFlipOffset - vFlipOffset;
+    expect(offsetDeltaCells).toBeCloseTo(2.4, 5);
+
+    // Round-trip the actual implementation under V flip + pivotY=0.2
+    // and confirm the formula-predicted posY matches.
+    const got = runOneCase({ ...baseSetup, flipV: true });
+    expect(got.posY).toBeCloseTo(vFlipPosY, 4);
+  });
+
+  it('unit-cell + center pivot retains the M0 1x1 baseline (AC-14 non-degradation)', () => {
+    const got = runOneCase({
+      widthCells: 1,
+      heightCells: 1,
+      pivotX: 0.5,
+      pivotY: 0.5,
+      cellX: 0,
+      cellY: 0,
+      flipH: false,
+      flipV: false,
+      flipDiagonal: false,
+      tileSize: [16, 16],
+    });
+    expect(got.posX).toBeCloseTo(0.5 * 16, 5);
+    expect(got.posY).toBeCloseTo(0.5 * 16, 5);
+    expect(got.scaleX).toBe(16);
+    expect(got.scaleY).toBe(16);
+    expect(got.quatZ).toBe(0);
+    expect(got.quatW).toBe(1);
+  });
+});

package/src/__tests__/tilemap-uv-inset.test.ts

@@ -0,0 +1,201 @@
+// tilemap-uv-inset.test - half-texel inset on resolveTilesetMaterial
+// (feat-20260608 M2 / m2-t3; plan-strategy §D-7 step 3).
+//
+// `resolveTilesetMaterial` is M2's UV-inset step on top of the M0
+// baseline. It packs the region rectangle into normalized UV space such
+// that GPU bilinear filtering at sub-pixel boundaries can never sample
+// beyond the region rectangle (charter P3 - default behaviour does not
+// silently bleed colours from the adjacent atlas tile).
+//
+// Inset formula (atlas extent in pixels, output in normalised [0, 1]^2):
+//
+//   uvU      = region.x      / atlasWidth  + 0.5 / atlasWidth
+//   uvV      = region.y      / atlasHeight + 0.5 / atlasHeight
+//   uvWidth  = region.width  / atlasWidth  - 1   / atlasWidth
+//   uvHeight = region.height / atlasHeight - 1   / atlasHeight
+//
+// The 0.5 / atlasWidth term inset both edges by exactly half a texel,
+// so any GPU bilinear filter sampling at the region edge stays inside
+// the region instead of sampling the adjacent atlas tile.
+//
+// FALSIFY rationale: a regression that strips the inset (returns to the
+// M0 baseline `u = region.x / atlasWidth`, `w = region.width / atlasWidth`)
+// fails the numerical inset assertion below, locking the behaviour.
+//
+// Anchors: plan-tasks m2-t3; plan-strategy §D-7 step 3; charter P3
+// (default behaviour avoids silently introducing visual defects).
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Layer, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { type MaterialAsset, type TilesetAsset, toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { encodeSortScope } from '../../../render/src/components/tile-layer';
+import {
+  resetTilemapChunkExtractCache,
+  resetTilemapDerivedEntityTracker,
+  tilemapChunkExtractSystem,
+} from '../../../render/src/tilemap-chunk-extract-system';
+import { makeTilemapAssetLookup } from './helpers/tilemap-assets';
+
+interface AtlasMeta {
+  atlasWidth: number;
+  atlasHeight: number;
+  columns: number;
+  rows: number;
+  tileWidth: number;
+  tileHeight: number;
+}
+
+function makeTileset(opts: {
+  guid: string;
+  atlas: AtlasMeta;
+  regions: ReadonlyArray<{ x: number; y: number; width: number; height: number }>;
+}): TilesetAsset {
+  return {
+    kind: 'tileset',
+    atlases: ['test/atlas'],
+    tileWidth: opts.atlas.tileWidth,
+    tileHeight: opts.atlas.tileHeight,
+    columns: opts.atlas.columns,
+    rows: opts.atlas.rows,
+    regions: opts.regions,
+    tiles: opts.regions.map((_, i) => ({ regionIndex: i })),
+  };
+}
+
+function spawnAndExtract(
+  tileset: TilesetAsset,
+  layerTiles: Uint32Array,
+  cols = 1,
+  rows = 1,
+): World {
+  const world = new World();
+  const lookup = makeTilemapAssetLookup(tileset);
+  const tilemap = world
+    .spawn(
+      {
+        component: Tilemap,
+        data: { cols, rows, tileSize: [1, 1], chunkSize: 4, tileset: 'test/tileset' },
+      },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+  world.spawn(
+    {
+      component: TileLayer,
+      data: { tiles: layerTiles, layerOrder: 0, dirty: 1, sortScope: encodeSortScope('per-cell') },
+    },
+    { component: ChildOf, data: { parent: tilemap } },
+  );
+  resetTilemapChunkExtractCache();
+  resetTilemapDerivedEntityTracker();
+  tilemapChunkExtractSystem(world, lookup);
+  return world;
+}
+
+function readDerivedMaterialRegions(world: World): number[][] {
+  const out: number[][] = [];
+  const query = world.query({ read: [MeshRenderer], with: [MeshFilter, Layer] }).unwrap();
+  for (const row of query) {
+    const handleRaw = row.get(MeshRenderer).materials[0];
+    if (handleRaw === undefined) continue;
+    const matRes = resolveAssetHandle<MaterialAsset>(
+      world,
+      toShared<'MaterialAsset'>(handleRaw as unknown as number),
+    );
+    if (!matRes.ok) continue;
+    const region = matRes.value.values?.region as readonly number[] | undefined;
+    if (region !== undefined) out.push([...region]);
+  }
+  return out;
+}
+
+describe('resolveTilesetMaterial — half-texel UV inset (M2)', () => {
+  it('top-left region inset: u = x/W + 0.5/W; w = width/W - 1/W (32x32 atlas, 16x16 region)', () => {
+    const tileset = makeTileset({
+      guid: 'tileset/uv-inset/top-left',
+      atlas: {
+        atlasWidth: 32,
+        atlasHeight: 32,
+        columns: 2,
+        rows: 2,
+        tileWidth: 16,
+        tileHeight: 16,
+      },
+      regions: [{ x: 0, y: 0, width: 16, height: 16 }],
+    });
+    const world = spawnAndExtract(tileset, new Uint32Array([1]));
+    const regions = readDerivedMaterialRegions(world);
+    expect(regions.length).toBe(1);
+    const r = regions[0];
+    if (r === undefined) throw new Error('expected one derived material region');
+    // u = 0/32 + 0.5/32 = 0.015625
+    // v = 0/32 + 0.5/32 = 0.015625
+    // w = 16/32 - 1/32 = 0.46875
+    // h = 16/32 - 1/32 = 0.46875
+    expect(r[0]).toBeCloseTo(0.015625, 6);
+    expect(r[1]).toBeCloseTo(0.015625, 6);
+    expect(r[2]).toBeCloseTo(0.46875, 6);
+    expect(r[3]).toBeCloseTo(0.46875, 6);
+  });
+
+  it('bottom-right region inset: u = 16/32 + 0.5/32; w = 16/32 - 1/32 (32x32 atlas, 16x16 region)', () => {
+    const tileset = makeTileset({
+      guid: 'tileset/uv-inset/bottom-right',
+      atlas: {
+        atlasWidth: 32,
+        atlasHeight: 32,
+        columns: 2,
+        rows: 2,
+        tileWidth: 16,
+        tileHeight: 16,
+      },
+      regions: [{ x: 16, y: 16, width: 16, height: 16 }],
+    });
+    const world = spawnAndExtract(tileset, new Uint32Array([1]));
+    const regions = readDerivedMaterialRegions(world);
+    expect(regions.length).toBe(1);
+    const r = regions[0];
+    if (r === undefined) throw new Error('expected one derived material region');
+    expect(r[0]).toBeCloseTo(0.515625, 6);
+    expect(r[1]).toBeCloseTo(0.515625, 6);
+    expect(r[2]).toBeCloseTo(0.46875, 6);
+    expect(r[3]).toBeCloseTo(0.46875, 6);
+  });
+
+  it('adjacent tile insets stay >= 1 texel apart (prevents GPU bilinear bleed)', () => {
+    const tileset = makeTileset({
+      guid: 'tileset/uv-inset/adjacent',
+      atlas: {
+        atlasWidth: 64,
+        atlasHeight: 32,
+        columns: 4,
+        rows: 2,
+        tileWidth: 16,
+        tileHeight: 16,
+      },
+      regions: [
+        { x: 0, y: 0, width: 16, height: 16 },
+        { x: 16, y: 0, width: 16, height: 16 },
+      ],
+    });
+    const world = spawnAndExtract(tileset, new Uint32Array([1, 2]), /* cols= */ 2, /* rows= */ 1);
+    const regions = readDerivedMaterialRegions(world);
+    expect(regions.length).toBe(2);
+    const [first, second] = regions.sort((a, b) => (a[0] ?? 0) - (b[0] ?? 0));
+    if (first === undefined || second === undefined) {
+      throw new Error('expected two derived material regions');
+    }
+    // First region right edge in normalized UV: u_right = u + w
+    //   = (0/64 + 0.5/64) + (16/64 - 1/64) = 0.5/64 + 15/64 = 15.5/64
+    // Second region left edge: u_left = 16/64 + 0.5/64 = 16.5/64
+    // Gap = 16.5/64 - 15.5/64 = 1/64 = 1 texel of atlasWidth.
+    const firstRight = (first[0] ?? 0) + (first[2] ?? 0);
+    const secondLeft = second[0] ?? 0;
+    const gap = secondLeft - firstRight;
+    expect(gap).toBeGreaterThanOrEqual(1 / 64 - 1e-6);
+  });
+});