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

package/src/components/sprite-region-override.ts

@@ -0,0 +1,105 @@
+// @forgeax/engine-runtime - SpriteRegionOverride (per-entity UV region
+// override, sprite-only).
+//
+// Schema: 1 fixed-length array column `region: 'array<f32, 4>'` carrying a
+// packed UV sub-rectangle `[uMin, vMin, uW, vH]`. The fixed `4` length is
+// enforced at compile time by the ECS schema-vocab keyword
+// `'array<T, N>'` (D-6: prefer compile-time enforcement over runtime
+// fail-fast for length-bound contracts).
+//
+// Why an entity-side override component instead of a render parameter on
+// MaterialRenderer? Plan-strategy section 1 / requirements section 5
+// constraint #1 (Pipeline Isolation R1, M1 ssot): `AssetRegistry` stays
+// append-only / read-only and `MaterialRenderer` schema is frozen.
+// Per-entity render-parameter overrides ride the same rail as Layer /
+// SortKey — one ECS column per entity, read at extract time, never
+// flowing back to the asset.
+//
+// Sprite-only consumption (requirements section 5 constraint #2 + section
+// 7 boundary line 1): `render-system-extract` reads this component ONLY
+// inside the sprite bucket branch (`pipelineTag === 'sprite'` plus the
+// asset-side sprite discriminant). Opaque (`unlit` / `standard`) buckets
+// ignore the column even when the entity happens to carry it; the M3
+// T-15 grep gate
+// (`packages/runtime/src/__tests__/sprite-only-isolation-grep-gate.test.ts`)
+// asserts this file contains zero substring matches against the asset
+// discriminant identifier as a structural lock (charter P5 producer /
+// consumer separation: the component owner never names the asset
+// discriminant directly).
+//
+// Naming: bare `SpriteRegionOverride` (no `Component` suffix per
+// AGENTS.md section Component naming "Single-semantic components drop
+// the Component suffix"). The `Sprite` prefix is intentional — 3D UV
+// region animation lands in a separate component (e.g. future
+// `MaterialRegionOverride`) per OOS-01 to avoid premature 3D
+// generalisation. Plan-strategy section 8 naming convention pins the
+// prefix to make the AC-11 grep gate trivially decidable.
+//
+// @derives `defineComponent` factory (packages/ecs/src/component.ts) —
+//   `'array<f32, 4>'` is on the `SchemaVocabKeyword` whitelist (line ~94
+//   `array<${ManagedArrayElementType}, ${number}>`).
+// @consumes M3 T-16 (`render-system-extract.ts` sprite bucket branch
+//   reads override into `paramSnapshot.region`, post-M3 feat-20260625
+//   ablation -- the pre-ablation per-entity hop through the snapshot
+//   POD layer collapsed into the generic paramSchema-driven path).
+// @produces M4 T-23 (`spriteAnimationTickSystem` writes per-frame UV
+//   slice into `region`).
+//
+// charter mapping: F1 (single-import barrel discovery — joins Layer /
+// SortKey / Transform / SpriteAnimation under a single
+// `from '@forgeax/engine-render'`); P3 (compile-time length=4 lock
+// surfaces mismatched payloads at the TS edge before the column write
+// path observes them); P4 (consistent abstraction — same per-entity
+// override shape AI users already learned for Layer / SortKey).
+//
+// Anchors: plan-strategy section 2 D-6 + section 3.1 SRO + section 4
+// risk R-SCHEMA-2 reaction; plan-tasks.json T-11; research F-5;
+// requirements section AC-01 + section 2.4 + section 5 constraint #2.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity sprite UV region override (sprite-only).
+ *
+ * Carries a fixed-length `Float32Array(4)` of `[uMin, vMin, uW, vH]` that
+ * `render-system-extract` reads in the sprite bucket branch and writes
+ * into `paramSnapshot.region`, replacing the asset-side region for
+ * this entity only (feat-20260625 M3 ablation: the prior per-entity POD
+ * indirection collapsed into the generic paramSchema-driven snapshot).
+ * Opaque buckets ignore this component; the AC-11 grep gate keeps the
+ * producer / consumer separation structural (this file never names the
+ * asset-side sprite discriminant identifier).
+ *
+ * Pair with `SpriteAnimation` to drive the override per frame
+ * (sprite-animation-tick system, M4 T-23). Standalone use (manual region
+ * override without animation) is also supported — set the column once and
+ * the next extract picks up the new value.
+ *
+ * Schema-vocab keyword `'array<f32, 4>'` (D-6) — fixed-length 4 is the
+ * compile-time enforcement axis. `Float32Array` payloads with length !== 4
+ * round-trip fewer / more bytes per the underlying BufferPool slot, but
+ * the slot is sized at schema registration time; AI users keep the
+ * payload exactly four-floats wide.
+ *
+ * @example Spawn a sprite entity that displays the right half of an atlas:
+ *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+ *   import { SpriteRegionOverride } from '@forgeax/engine-render/authoring';
+ *   import { Transform } from '@forgeax/engine-scene';
+ *   import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
+ *
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *     { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
+ *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },
+ *     { component: SpriteRegionOverride,
+ *       data: { region: new Float32Array([0.5, 0, 0.5, 1]) } },
+ *   );
+ *
+ * @example Update the override at runtime (e.g. flip-frame test):
+ *   world.set(entity, SpriteRegionOverride,
+ *     { region: new Float32Array([0, 0, 1, 1]) }).unwrap();
+ */
+export const SpriteRegionOverride = defineComponent('SpriteRegionOverride', {
+  region: { type: 'array<f32, 4>' },
+});

package/src/components/tile-layer.ts

@@ -0,0 +1,167 @@
+// @forgeax/engine-runtime - TileLayer (one render layer of a Tilemap).
+//
+// Schema (4 fields):
+//   tiles       array<u32>  per-cell tile id (packed Tiled .tmj wire form);
+//                           length == parent.Tilemap.cols * rows.
+//   layerOrder  i32         render-order key (higher = drawn on top).
+//   dirty       u8          0 means clean, non-zero means dirty - the next
+//                           tilemap-chunk-extract-system pass rebuilds derived
+//                           per-cell entities for this layer.
+//   sortScope   u8 (TS:     0 = 'layer'    (default) - terrain semantics:
+//               closed                       every derived entity in this
+//               'layer' |                    layer shares one Layer.value
+//               'per-cell'                   (layerOrder << 20), so the
+//               union)                       whole layer Y-sorts as a single
+//                                            bucket. AI users grep
+//                                            `sortScope: 'layer'` to confirm.
+//                           1 = 'per-cell' - object semantics: each derived
+//                                            entity carries its own foot-Y
+//                                            key; preserves per-cell entity
+//                                            derivation for Y-interleave
+//                                            with sprite entities sharing
+//                                            the same Layer.value.
+//
+//   Storage rationale (D-V-3 R-NEW-1 fallback / round-2): ECS schema does not
+//   yet support `values: ['layer', 'per-cell']` literal-union constraints
+//   on a `'string'` column, so the on-disk shape is `u8` (0/1) but every
+//   AI-facing TS surface (`TileLayerData.sortScope`) is the closed
+//   `'layer' | 'per-cell'` string union. The bridge functions
+//   `encodeSortScope` / `decodeSortScope` are the SSOT for the two-way
+//   mapping (charter F1 — single grep target).
+//
+// Each TileLayer entity attaches to a Tilemap entity via ChildOf (the parent
+// field carries the Tilemap entity). M0 supports multiple TileLayer entities
+// per Tilemap (each rendered as an independent z-ordered layer).
+//
+// charter mapping: F1 (single-import barrel + single grep target for
+// `sortScope`), P1 (progressive disclosure — `'layer'` / `'per-cell'`
+// reads directly without a magic-number table), P3 (dirty flag is
+// explicit - silent re-extraction is forbidden), P4 (handle-free row
+// schema mirrors MeshFilter / MeshRenderer conventions).
+
+import { defineComponent, type EcsError, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { Result } from '@forgeax/engine-types';
+
+/**
+ * Closed string-literal union for the TileLayer.sortScope field. AI users
+ * grep `sortScope` and land on this single SSOT type alias; switch
+ * statements over this type are exhaustive without a default arm.
+ *
+ *   - 'layer'    - terrain semantics; whole layer shares one Layer.value
+ *                  bucket and Y-sorts together (chunkIndex is folded into 0).
+ *   - 'per-cell' - object semantics; each derived entity gets its own
+ *                  chunkIndex tiebreak so it can Y-interleave with
+ *                  sprite entities carrying the same Layer.value (e.g. a
+ *                  player sprite riding the same SPRITE_LAYER_VALUE).
+ */
+export type SortScope = 'layer' | 'per-cell';
+
+/** Compact authoring values for the stored u8 sort-scope field. */
+export const TilemapSort = Object.freeze({
+  layer: 0 as const,
+  perCell: 1 as const,
+});
+
+/**
+ * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,
+ * `'per-cell'` -> 1). The compile-time exhaustive switch guards against
+ * silent drift if the union ever grows; adding a new literal here without
+ * adding its arm fails typecheck (charter P3 — closed unions never default).
+ */
+export function encodeSortScope(scope: SortScope): 0 | 1 {
+  switch (scope) {
+    case 'layer':
+      return TilemapSort.layer;
+    case 'per-cell':
+      return TilemapSort.perCell;
+  }
+}
+
+/**
+ * Bridge: on-disk u8 -> `SortScope`. Defaults to `'layer'` for any value
+ * outside `{0, 1}` (defensive — the column is typed `u8` so out-of-range
+ * values can only appear if a future schema migration loosens the bound;
+ * the default preserves terrain semantics which is the safer of the two).
+ */
+export function decodeSortScope(raw: number | undefined): SortScope {
+  return raw === 1 ? 'per-cell' : 'layer';
+}
+
+/**
+ * Public TileLayer field shape (`world.spawn({ component: TileLayer, data:
+ * { ... } })` payload). `sortScope` is the closed string union surfaced to
+ * AI users; the runtime row encodes it as `u8` via `encodeSortScope` at
+ * spawn time so on-disk storage stays compact.
+ *
+ * Treat as the `TileLayer` data SSOT — `defineComponent` schema below
+ * mirrors it field-for-field with the bridge `sortScope: u8` in place of
+ * the union literal.
+ */
+export interface TileLayerData {
+  readonly tiles: Uint32Array;
+  readonly layerOrder?: number;
+  readonly dirty?: number;
+  readonly sortScope?: SortScope;
+}
+
+/**
+ * TileLayer component (M0 baseline rebuild + round-2 sortScope rename).
+ *
+ * AI users typically spawn a TileLayer + ChildOf pair pointing at an
+ * existing Tilemap entity:
+ *
+ * @example
+ *   const tilesArray = new Uint32Array(cols * rows);
+ *   tilesArray[5 * cols + 7] = 1; // tile id 1 at cell (7, 5)
+ *   world.spawn(
+ *     { component: TileLayer, data: { tiles: tilesArray, layerOrder: 0 } },
+ *     { component: ChildOf,  data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Object-layer variant (Y-interleave with sprite entities):
+ *
+ * > NOTE: schema storage is `u8` (ECS schema does not support
+ * > string-literal-union column constraints; see R-NEW-2). The
+ * > AI-user surface is the closed `SortScope` string union, but
+ * > `world.spawn` requires the numeric encoding — pass through
+ * > `encodeSortScope('per-cell')` rather than the literal string.
+ *
+ * @example
+ *   world.spawn(
+ *     { component: TileLayer, data: {
+ *         tiles: objectTiles,
+ *         layerOrder: 1000,
+ *         sortScope: encodeSortScope('per-cell'),
+ *       } },
+ *     { component: ChildOf, data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Defaults: `layerOrder = 0`, `dirty = 0`, `sortScope = 'layer'` (stored
+ * as `u8 = 0`, i.e. `encodeSortScope('layer')`). `tiles` has no default -
+ * AI users supply the per-cell array at spawn time. To trigger a re-build
+ * after mutating tiles in place, call `markTileLayerDirty(world, layer)`.
+ */
+export const TileLayer = defineComponent('TileLayer', {
+  tiles: { type: 'array<u32>' },
+  layerOrder: { type: 'i32', default: 0 },
+  dirty: { type: 'u8', default: 0 },
+  sortScope: { type: 'u8', default: 0 },
+});
+
+/**
+ * Mark a TileLayer entity dirty so the next `tilemapChunkExtractSystem`
+ * pass purges and re-spawns its derived per-cell entities. Use this after
+ * mutating `TileLayer.tiles` (e.g. an in-place patch via a column view).
+ *
+ * Returns the underlying ECS write result - on `err` branch the caller
+ * can read `.code` to recover (`'stale-entity'` if the layer was
+ * despawned, `'component-not-present'` if the entity is missing the
+ * TileLayer column; both kebab-case literals are members of the closed
+ * `EcsErrorCode` union).
+ */
+export function markTileLayerDirty(
+  world: World,
+  layerEntity: EntityHandle,
+): Result<void, EcsError> {
+  return world.set(layerEntity, TileLayer, { dirty: 1 });
+}

package/src/components/tilemap.ts

@@ -0,0 +1,48 @@
+// @forgeax/engine-runtime - Tilemap (grid + tileset reference).
+//
+// Schema (5 fields):
+//   cols       u32               total grid columns
+//   rows       u32               total grid rows
+//   tileSize   array<f32, 2>     per-cell world [width, height] (default [1, 1];
+//                                feat-20260709 M3: collapsed from the tileSizeX
+//                                / tileSizeY scalar pair into one inline column)
+//   chunkSize  u32               per-chunk axis-length in cells (default 16)
+//   tileset    string                durable TilesetAsset GUID
+//
+// Naming: single-semantic Tilemap (AGENTS.md §Component naming drops
+// `Component` suffix). One Tilemap entity per grid; TileLayer entities
+// attach via ChildOf relationship and supply the per-cell tile id array
+// for a single render-layer.
+//
+// charter mapping: F1 (single-import barrel from `@forgeax/engine-runtime`),
+// P1 (progressive disclosure - defaults cover the common case), P4 (durable
+// asset identity stays separate from World-local handles).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Tilemap component (M0 baseline rebuild).
+ *
+ * A Tilemap entity carries grid metadata + a single durable `tileset` GUID. The
+ * actual per-cell tile id array lives on attached `TileLayer` entities
+ * (one per render layer; ChildOf points back to the Tilemap entity).
+ *
+ * Defaults:
+ *   - `tileSize = [1, 1]` (unit-cell world coordinates).
+ *   - `chunkSize = 16` (tilemap-chunk-extract-system chunks 16x16 cells).
+ *
+ * @example Spawn a 32x32 unit-cell Tilemap referencing a TilesetAsset:
+ *   const tilemap = world.spawn(
+ *     { component: Tilemap, data: { cols: 32, rows: 32, tileset } },
+ *     { component: Transform, data: {} },
+ *   ).unwrap();
+ */
+export const Tilemap = defineComponent('Tilemap', {
+  cols: { type: 'u32', default: 0 },
+  rows: { type: 'u32', default: 0 },
+  // tileSize carries an explicit layer-2 default [1,1] (unit cell); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  tileSize: { type: 'array<f32, 2>', default: new Float32Array([1, 1]) },
+  chunkSize: { type: 'u32', default: 16 },
+  tileset: { type: 'string' },
+});

package/src/components/visibility.ts

@@ -0,0 +1,53 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Numeric labels stored by the public Visibility enum field. */
+export const VisibilityStateValue = Object.freeze({
+  inherited: 0,
+  hidden: 1,
+  visible: 2,
+} as const);
+
+/** Author visibility intent accepted by the Visibility component. */
+export type VisibilityState = keyof typeof VisibilityStateValue;
+
+/**
+ * Decode the stored u32 without treating an unknown value as a valid state.
+ * Invalid values are rejected at ECS write boundaries; undefined remains an
+ * explicit signal for readers that inspect externally corrupted columns.
+ */
+export function visibilityStateFromU32(value: number): VisibilityState | undefined {
+  switch (value) {
+    case VisibilityStateValue.inherited:
+      return 'inherited';
+    case VisibilityStateValue.hidden:
+      return 'hidden';
+    case VisibilityStateValue.visible:
+      return 'visible';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Author intent for render participation. Omitted state is inherited and is
+ * therefore visible when no valid parent intent is available.
+ */
+export const Visibility = defineComponent(
+  'Visibility',
+  {
+    state: {
+      type: 'enum',
+      default: VisibilityStateValue.inherited,
+      labels: VisibilityStateValue,
+    },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Visibility to author render participation intent.',
+      diagnostics: 'Compare the ECS state with resolveVisibility and renderer.visibilityStats.',
+      recovery: 'Use structured ECS write errors and repair the owning scene relation.',
+      boundaries:
+        'Visibility does not own camera, picking, lifecycle, assets, or VFX shadow policy.',
+    },
+  },
+);

package/src/construct-renderer.ts

@@ -0,0 +1,67 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { RhiBackendPack } from './assembly/backend-contract';
+import type { BundlerOptions } from './assembly/factory';
+import { createRenderer, exposeRenderer } from './assembly/factory';
+import type {
+  RendererHostImplementation,
+  RendererLegacyHostAdapter,
+} from './assembly/host-contract';
+import { type RenderError, RendererContractFailureError } from './errors/render';
+import type { Renderer, RendererOptions, RenderResult } from './render-contract';
+
+export type {
+  EngineEnvironmentErrorDetail,
+  RhiBackendInstrumentation,
+  RhiBackendPack,
+} from './assembly/backend-contract';
+export { EngineEnvironmentError } from './assembly/backend-contract';
+export type { RendererLegacyHostAdapter } from './assembly/host-contract';
+export type { BundlerOptions };
+
+export type RendererFeatureAssemblyHost = Pick<
+  RendererLegacyHostAdapter,
+  'installRenderFeature' | 'uninstallRenderFeature'
+>;
+
+export interface RendererHostAssembly {
+  readonly renderer: Renderer;
+  readonly debugDrawHost: RendererHostImplementation;
+  readonly featureHost: RendererFeatureAssemblyHost;
+  readonly assets: AssetRegistry;
+}
+
+export async function constructRendererHost(
+  canvas: unknown,
+  options?: RendererOptions,
+  bundler?: BundlerOptions,
+  backend?: RhiBackendPack,
+): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+  try {
+    const implementation = await createRenderer(canvas, options, bundler, backend);
+    const ready = await implementation.initialization;
+    if (!ready.ok) {
+      return {
+        ok: false,
+        error: new RendererContractFailureError(
+          'construct',
+          `${ready.error.code}: ${ready.error.hint}`,
+        ),
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        renderer: exposeRenderer(implementation),
+        debugDrawHost: implementation,
+        featureHost: implementation,
+        assets: implementation.assetRegistry,
+      },
+    };
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return {
+      ok: false,
+      error: new RendererContractFailureError('construct', detail),
+    };
+  }
+}

package/src/debug-draw-glue.ts

@@ -0,0 +1,48 @@
+// @forgeax/engine-render - typed debug overlay graph contribution.
+//
+// App owns the concrete DebugDraw instance and injects its declaration-only
+// capability through the Renderer host. Render owns graph ordering and pass
+// encoding without depending on the debug-draw package.
+
+import { mat4 } from '@forgeax/engine-math';
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import type { Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTarget } from './render-pipeline';
+
+export function addTypedDebugOverlayPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  output: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  return graph.addRasterPass('debug-overlay', {
+    accesses: [{ resource: output.view, usage: 'color-attachment' }],
+    colorAttachments: [{ view: output.view, loadOp: 'load', storeOp: 'store' }],
+    encode: ({ pass, frame }) => {
+      const projection = mat4.create();
+      if (frame.camera.projection === 'orthographic') {
+        mat4.orthographic(
+          projection,
+          frame.camera.orthoLeft,
+          frame.camera.orthoRight,
+          frame.camera.orthoBottom,
+          frame.camera.orthoTop,
+          frame.camera.near,
+          frame.camera.far,
+        );
+      } else {
+        mat4.perspective(
+          projection,
+          frame.camera.fov,
+          frame.camera.aspect,
+          frame.camera.near,
+          frame.camera.far,
+        );
+      }
+      const view = mat4.invert(mat4.create(), frame.camera.world);
+      const result = frame.runtime.debugOverlay?.encode(
+        pass,
+        mat4.multiply(mat4.create(), projection, view),
+      );
+      if (result !== undefined && !result.ok) throw result.error;
+    },
+  });
+}