@forgeax/engine-render 0.1.7 → 0.1.20

package/dist/chunk-RXZ3RGOU.mjs

@@ -0,0 +1,53 @@
+import { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';
+import { err, ok } from '@forgeax/engine-types';
+
+// src/systems/transparent-sort-config.ts
+var TRANSPARENT_SORT_CONFIG_KEY = "TransparentSortConfig";
+var TRANSPARENT_SORT_MODE_LAYER_Z = 0;
+var TRANSPARENT_SORT_MODE_LAYER_Y = 1;
+var TRANSPARENT_SORT_MODE_LAYER_YZ = 2;
+var TRANSPARENT_SORT_MODE_DISTANCE = 3;
+var TransparentSort = Object.freeze({
+  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,
+  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,
+  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,
+  distance: TRANSPARENT_SORT_MODE_DISTANCE,
+  configure: setTransparentSortConfig
+});
+var DEFAULT_CONFIG = Object.freeze({
+  mode: TRANSPARENT_SORT_MODE_LAYER_Z,
+  yzAlpha: 1
+});
+var VALID_MODES = /* @__PURE__ */ new Set([
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_DISTANCE
+]);
+var EXPECTED_MODE = "mode \u2208 {0, 1, 2, 3}";
+var HINT_MODE = "0=layer-z, 1=layer-y, 2=layer-yz, 3=distance";
+function getTransparentSortConfig(world) {
+  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {
+    return DEFAULT_CONFIG;
+  }
+  return world.getResource(TRANSPARENT_SORT_CONFIG_KEY);
+}
+function setTransparentSortConfig(world, cfg) {
+  if (!VALID_MODES.has(cfg.mode)) {
+    return err(
+      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {
+        receivedMode: cfg.mode,
+        receivedKey: TRANSPARENT_SORT_CONFIG_KEY
+      })
+    );
+  }
+  world.insertResource(TRANSPARENT_SORT_CONFIG_KEY, {
+    mode: cfg.mode,
+    yzAlpha: cfg.yzAlpha
+  });
+  return ok(void 0);
+}
+
+export { TRANSPARENT_SORT_MODE_DISTANCE, TRANSPARENT_SORT_MODE_LAYER_Y, TRANSPARENT_SORT_MODE_LAYER_YZ, TRANSPARENT_SORT_MODE_LAYER_Z, TransparentSort, getTransparentSortConfig };
+//# sourceMappingURL=chunk-RXZ3RGOU.mjs.map
+//# sourceMappingURL=chunk-RXZ3RGOU.mjs.map

package/dist/chunk-RXZ3RGOU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/systems/transparent-sort-config.ts"],"names":[],"mappings":";;;;AAkGO,IAAM,2BAAA,GAA8B,uBAAA;AAGpC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,6BAAA,GAAgC;AAGtC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,8BAAA,GAAiC;AAGvC,IAAM,eAAA,GAAkB,OAAO,MAAA,CAAO;AAAA,EAC3C,MAAA,EAAQ,6BAAA;AAAA,EACR,MAAA,EAAQ,6BAAA;AAAA,EACR,OAAA,EAAS,8BAAA;AAAA,EACT,QAAA,EAAU,8BAAA;AAAA,EACV,SAAA,EAAW;AACb,CAAU;AAMV,IAAM,cAAA,GAAwC,OAAO,MAAA,CAAO;AAAA,EAC1D,IAAA,EAAM,6BAAA;AAAA,EACN,OAAA,EAAS;AACX,CAAC,CAAA;AAED,IAAM,WAAA,uBAAuC,GAAA,CAAY;AAAA,EACvD,6BAAA;AAAA,EACA,6BAAA;AAAA,EACA,8BAAA;AAAA,EACA;AACF,CAAC,CAAA;AAOD,IAAM,aAAA,GAAgB,0BAAA;AACtB,IAAM,SAAA,GAAY,8CAAA;AA2BX,SAAS,yBAAyB,KAAA,EAAqC;AAC5E,EAAA,IAAI,CAAC,KAAA,CAAM,WAAA,CAAY,2BAA2B,CAAA,EAAG;AACnD,IAAA,OAAO,cAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,CAAM,YAAmC,2BAA2B,CAAA;AAC7E;AAwCO,SAAS,wBAAA,CACd,OACA,GAAA,EACyC;AACzC,EAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,GAAA,CAAI,IAAI,CAAA,EAAG;AAC9B,IAAA,OAAO,GAAA;AAAA,MACL,IAAI,yBAAA,CAA0B,aAAA,EAAe,SAAA,EAAW;AAAA,QACtD,cAAc,GAAA,CAAI,IAAA;AAAA,QAClB,WAAA,EAAa;AAAA,OACd;AAAA,KACH;AAAA,EACF;AACA,EAAA,KAAA,CAAM,eAAsC,2BAAA,EAA6B;AAAA,IACvE,MAAM,GAAA,CAAI,IAAA;AAAA,IACV,SAAS,GAAA,CAAI;AAAA,GACd,CAAA;AACD,EAAA,OAAO,GAAG,MAAS,CAAA;AACrB","file":"chunk-RXZ3RGOU.mjs","sourcesContent":["// @forgeax/engine-runtime - TransparentSortConfig KV resource + helpers.\n//\n// feat-20260520-2d-sprite-layer-mvp M-2 w14 / requirements AC-08 + AC-18\n// path (2)/(3) + AC-19 derivation audit (5).\n//\n// Surface:\n//   - interface  TransparentSortConfig { mode: number; yzAlpha: number }\n//   - constant   TRANSPARENT_SORT_CONFIG_KEY   = 'TransparentSortConfig'\n//   - constants  TRANSPARENT_SORT_MODE_LAYER_Z  = 0  (horizontal-z)\n//                TRANSPARENT_SORT_MODE_LAYER_Y  = 1  (Y-sort)\n//                TRANSPARENT_SORT_MODE_LAYER_YZ = 2  (Y-Z blend)\n//   - helper     getTransparentSortConfig(world): TransparentSortConfig\n//   - helper     setTransparentSortConfig(world, cfg):\n//                  Result<void, ResourceInvalidValueError>\n//\n// 5-view selection table (charter F1 progressive disclosure for AI users\n// reading IDE hover on this header; same SSOT mirrored in\n// apps/hello/sprite/README.md M-4 w33):\n//\n//   | view              | mode | yzAlpha | sortValue formula              |\n//   |:------------------|:----:|:-------:|:--------------------------------|\n//   | horizontal (side) |  0   |   ---   | posZ                            |\n//   | top-down          |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//   | Don't Starve      |  2   |   1.0   | (posY - pivot.y * size.y) + posZ|\n//   | isometric         |  2   |   0.5   | (posY - pivot.y * size.y) + 0.5*posZ |\n//   | JRPG (foot pivot) |  1   |   ---   | -(posY - pivot.y * size.y)      |\n//\n// AC-18 path (2): @fallback getTransparentSortConfig KV missing returns\n//   default; no warn; no throw (legal default state, not an error state).\n// AC-18 path (3): @fallback setTransparentSortConfig mode out-of-range\n//   does NOT silently coerce to mode=0 — returns Result.err with the\n//   4 SSOT fields locked by plan-strategy D-4 so AI users can self-repair\n//   via .code / .expected / .hint / .detail property access (charter P3).\n// AC-18 path (3) carve-out: yzAlpha range is intentionally NOT validated;\n//   mode=0 / mode=1 ignore the field entirely, mode=2 reads it, mode=3\n//   (distance) also reads it for compat but ignores it (squared-distance\n//   formula does not use yzAlpha). The silent-ignore is the documented\n//   charter P3 \"legal default\" boundary.\n//\n// @new-surface KV resource: ECS has no defineResource factory at this\n//   feat's commit time; the TS POD interface + string KV key form is the\n//   minimum-new-surface route. The world resource store\n//   (insertResource / getResource / hasResource) is reused unchanged\n//   (requirements §2.2.G derivation row 5).\n// @derives world.hasResource / world.insertResource / world.getResource\n//   KV API (packages/ecs/src/resource.ts + world.ts: insertResource l.490,\n//   getResource l.498, hasResource l.503).\n// @fallback getTransparentSortConfig KV missing returns\n//   { mode: 0, yzAlpha: 1.0 }; no warn; no throw.\n// @fallback setTransparentSortConfig mode out-of-range returns Result.err\n//   with code='resource-invalid-value'; never silently coerced.\n//\n// charter mapping: F1 (single-import barrel + 5-view JSDoc table on\n// hover) + P3 (structured failure on mode out-of-range; legal-default\n// fallback distinguished from error fallback) + P4 (consistent\n// abstraction — same world.{has,get,insert}Resource KV API as every\n// other engine resource consumer).\n\nimport type { World } from '@forgeax/engine-ecs';\nimport { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';\nimport { err, ok, type Result } from '@forgeax/engine-types';\n\n// ────────────────────────────────────────────────────────────────────────────\n// POD interface + KV key + 3 named mode constants\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Transparent-bucket sort configuration (plain-data POD). Lives as a\n * world-level resource keyed by `TRANSPARENT_SORT_CONFIG_KEY`.\n *\n * Fields:\n *   - `mode \\u2208 {0, 1, 2, 3}` selects the sort formula\n *     (`TRANSPARENT_SORT_MODE_LAYER_Z` / `_LAYER_Y` / `_LAYER_YZ` / `_DISTANCE`).\n *   - `yzAlpha` (mode=2 only) blends Y-axis into Z-axis: 1.0 weights\n *     posZ equally with `posY - pivot.y * size.y` (Don't-Starve style),\n *     0.5 weights posZ at half (isometric). mode=0 / mode=1 ignore the\n *     field (documented charter P3 legal-default boundary).\n */\nexport interface TransparentSortConfig {\n  readonly mode: number;\n  readonly yzAlpha: number;\n}\n\n/** Extract-stage POD consumed by the transparent-sort owner. */\nexport interface TransparentEntry {\n  readonly entityIndex: number;\n  readonly materialHandle: number;\n  readonly layer: number;\n  readonly posX: number;\n  readonly posY: number;\n  readonly posZ: number;\n  readonly pivotY: number;\n  readonly sizeY: number;\n  readonly sortKey?: number | undefined;\n  readonly renderableIndex?: number | undefined;\n}\n\n/** World resource key for `TransparentSortConfig` KV entry. */\nexport const TRANSPARENT_SORT_CONFIG_KEY = 'TransparentSortConfig' as const;\n\n/** horizontal / side-scroller: sortValue = posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_Z = 0;\n\n/** top-down / JRPG: sortValue = -(posY - pivot.y * size.y) (foot pivot Y-sort). */\nexport const TRANSPARENT_SORT_MODE_LAYER_Y = 1;\n\n/** Don't-Starve / isometric: sortValue = (posY - pivot.y * size.y) + yzAlpha * posZ. */\nexport const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;\n\n/** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */\nexport const TRANSPARENT_SORT_MODE_DISTANCE = 3;\n\n/** Grouped authoring values and the single configuration operation. */\nexport const TransparentSort = Object.freeze({\n  layerZ: TRANSPARENT_SORT_MODE_LAYER_Z,\n  layerY: TRANSPARENT_SORT_MODE_LAYER_Y,\n  layerYZ: TRANSPARENT_SORT_MODE_LAYER_YZ,\n  distance: TRANSPARENT_SORT_MODE_DISTANCE,\n  configure: setTransparentSortConfig,\n} as const);\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internal: silent default + mode validity check\n// ────────────────────────────────────────────────────────────────────────────\n\nconst DEFAULT_CONFIG: TransparentSortConfig = Object.freeze({\n  mode: TRANSPARENT_SORT_MODE_LAYER_Z,\n  yzAlpha: 1.0,\n});\n\nconst VALID_MODES: ReadonlySet<number> = new Set<number>([\n  TRANSPARENT_SORT_MODE_LAYER_Z,\n  TRANSPARENT_SORT_MODE_LAYER_Y,\n  TRANSPARENT_SORT_MODE_LAYER_YZ,\n  TRANSPARENT_SORT_MODE_DISTANCE,\n]);\n\n// The expected / hint literals are the SSOT locked by plan-strategy D-4.\n// They MUST round-trip byte-for-byte into ResourceInvalidValueError so AI\n// users can read err.expected / err.hint for self-repair (charter P3).\n// `\\u2208` is the math \"is-element-of\" symbol; the ASCII source escape\n// keeps the file English-only per AGENTS.md §Conventions.\nconst EXPECTED_MODE = 'mode \\u2208 {0, 1, 2, 3}';\nconst HINT_MODE = '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance';\n\n// ────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Read the world's `TransparentSortConfig` resource.\n *\n * @fallback KV missing returns `{ mode: 0, yzAlpha: 1.0 }`\n * (`TRANSPARENT_SORT_MODE_LAYER_Z`, horizontal-z safe default).\n * NO warn, NO throw — KV missing is a legal state (not an error state),\n * mirroring how a sprite-free scene is a legal state for the renderer\n * even though render-system has a transparent bucket. plan-strategy D-2:\n * `hasResource` guard precedes the read so this helper never trips\n * `ResourceNotFoundError` from `world.getResource`.\n *\n * @example\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 0, cfg.yzAlpha === 1.0 when no resource inserted.\n *\n * @example\n *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });\n *   const cfg = getTransparentSortConfig(world);\n *   // cfg.mode === 1, cfg.yzAlpha === 1.0 (yzAlpha ignored by mode=1).\n */\nexport function getTransparentSortConfig(world: World): TransparentSortConfig {\n  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {\n    return DEFAULT_CONFIG;\n  }\n  return world.getResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY);\n}\n\n/**\n * Write the world's `TransparentSortConfig` resource, validating `mode`.\n *\n * Returns `Result<void, ResourceInvalidValueError>`:\n *\n *   - `ok` — mode is in `{0, 1, 2, 3}`; the resource is inserted /\n *     overwritten via `world.insertResource`.\n *   - `err` — mode is out of range; the resource is NOT mutated;\n *     `err.error` is a `ResourceInvalidValueError` instance carrying:\n *       `.code === 'resource-invalid-value'`\n *       `.expected === 'mode \\u2208 {0, 1, 2, 3}'`\n *       `.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'`\n *       `.detail.receivedMode === <the rejected mode>`\n *\n * @fallback mode out-of-range is NEVER silently coerced to mode=0 —\n * `Result.err` is the only fail-mode (charter P3 structured failure).\n * AI users read `.code / .expected / .hint / .detail` properties to\n * self-repair, NOT the human-readable `.message` string.\n *\n * @fallback yzAlpha range is intentionally not validated; mode=0 / mode=1\n * ignore the field, mode=2 reads it. The silent-ignore is the\n * documented charter P3 \"legal default\" boundary (plan-strategy D-4 +\n * AC-18 path (3) carve-out).\n *\n * @example success path:\n *   const r = setTransparentSortConfig(world,\n *     { mode: TRANSPARENT_SORT_MODE_LAYER_YZ, yzAlpha: 0.5 });\n *   if (!r.ok) return r;\n *\n * @example failure path:\n *   const r = setTransparentSortConfig(world, { mode: 99, yzAlpha: 1.0 });\n *   if (!r.ok) {\n *     // r.error.code === 'resource-invalid-value'\n *     // r.error.expected === 'mode \\u2208 {0, 1, 2, 3}'\n *     // r.error.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'\n *     // r.error.detail.receivedMode === 99\n *   }\n */\nexport function setTransparentSortConfig(\n  world: World,\n  cfg: TransparentSortConfig,\n): Result<void, ResourceInvalidValueError> {\n  if (!VALID_MODES.has(cfg.mode)) {\n    return err(\n      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {\n        receivedMode: cfg.mode,\n        receivedKey: TRANSPARENT_SORT_CONFIG_KEY,\n      }),\n    );\n  }\n  world.insertResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY, {\n    mode: cfg.mode,\n    yzAlpha: cfg.yzAlpha,\n  });\n  return ok(undefined);\n}\n"]}