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

package/src/systems/skin-palette-allocator.ts

@@ -0,0 +1,251 @@
+// @forgeax/engine-runtime - Skin palette buffer allocator (M2 / T-24).
+//
+// Per-renderer mutable state: vertex-stage palette buffer(s) holding
+// pre-multiplied joint matrices (M_i = joint_world * IBM_i) for every
+// skinned entity in a frame. Two backends (split at construction by
+// `useStorageBuffer`):
+//
+//   STORAGE PATH  (`useStorageBuffer = true`, `maxStorageBuffersPerShaderStage
+//                  >= 8` — i.e. WebGPU spec default device).
+//     One shared GPU buffer grows at 1.5x (Bevy skin.rs alignment,
+//     plan-strategy D-4). Every entity's slice is `{ buffer: shared,
+//     byteOffset: cursor }`. Record-stage builds ONE BG against the
+//     shared buffer + `bindingWindowBytes` entry size; per-draw
+//     `setBindGroup(_, bg, [_, dynOffset = slice.byteOffset])` slides
+//     the static window across the buffer. WebGPU rule
+//     `dynOffset + entry.size <= buffer.size` is satisfied because the
+//     allocator extends `buffer.size` to `cursor + bindingWindowBytes`
+//     after every slice.
+//
+//   UNIFORM PATH  (`useStorageBuffer = false`, browser uniform fallback —
+//                  `maxStorageBuffersPerShaderStage = 0`).
+//     `maxUniformBufferBindingSize` floor is 16 KiB; the static binding
+//     window alone is 16320 B, leaving room for ZERO additional
+//     entities behind a shared dynOffset. The shared-BG model collapses,
+//     so each entity gets its OWN small UBO of size = `bindingWindowBytes`
+//     (= MAX_JOINTS * 64 = 16320, which is `<= maxUniformBufferBindingSize`).
+//     Slice returns `{ buffer: per-entity, byteOffset: 0 }`. Record-stage
+//     BG cache key includes `slice.buffer` so each entity gets its own
+//     BG (cached per-buffer pointer; pool reuse keeps createBuffer
+//     amortized across frames).
+//
+//   Concept that does NOT branch by path: `bindingWindowBytes`. It is
+//   the static `pbr-skin-mesh-array-bgl @binding(1)` BG entry size,
+//   identical on both paths (WGSL declares the same layout). Record-
+//   stage uses it verbatim when constructing the BG. dynOffset[1]
+//   on the uniform path is always 0 (entry size already equals buffer
+//   size); on the storage path it walks 0, 1536, 3072, ... .
+//
+// CPU pre-multiply (path-agnostic): writeJointPalette(slice, ibm, jointWorld)
+//   -> mat4 per joint: M_i = joint_world_i * IBM_i
+//   -> queue.writeBuffer(slice.buffer, slice.byteOffset, payload).
+//
+// feat-20260523-skin-skeleton-animation M2 / T-24;
+// feat-20260612-skin-palette-per-frame-upload M6 (uniform fallback split).
+
+import type { Mat4 } from '@forgeax/engine-math';
+import { mat4 } from '@forgeax/engine-math';
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { SkinPaletteOverflowError } from '../errors/render';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import type { SkinPaletteSlice } from './skin-palette-types';
+
+const MAT4_BYTES = 64; // 16 f32 * 4 bytes
+// MAX_JOINTS = 255 matches `pbr-skin-mesh-array-bgl @binding(1)` static BG
+// entry size: 255 * 64 = 16320 B. The number is the MAX joints a single
+// skinned entity may have. On the storage path the shared buffer holds
+// many entities back-to-back; on the uniform path each entity owns one
+// 16320 B buffer.
+const MAX_JOINTS = 255;
+const BINDING_WINDOW_BYTES = MAX_JOINTS * MAT4_BYTES; // 16320
+// WebGPU `minStorageBufferOffsetAlignment` default (spec floor) — every
+// dynamic offset passed to setBindGroup must be a multiple of this. The shared
+// storage path packs many entities back-to-back, so each slice's start must be
+// rounded up to this boundary; otherwise a slice whose predecessor's joint
+// footprint (jointCount * 64) is not a multiple of 256 (e.g. 33 joints -> 2112)
+// lands on an unaligned offset and trips `Dynamic Offset[1] is not 256 byte
+// aligned` at draw time.
+const PALETTE_OFFSET_ALIGN = 256;
+
+export interface SkinPaletteAllocator {
+  /**
+   * Static BG entry size for `pbr-skin-mesh-array-bgl @binding(1)`. Always
+   * `MAX_JOINTS * 64 = 16320`; consumers (record stage) bind this size
+   * when building the BG. Path-independent.
+   */
+  readonly bindingWindowBytes: number;
+  /**
+   * True when this allocator is in storage-path mode (single shared
+   * buffer + dynOffset). False on the uniform fallback (per-entity
+   * buffer + dynOffset always 0). Record-stage reads this only for
+   * shape assertions in tests; production code branches via
+   * `slice.buffer` identity (shared vs per-entity), not this flag.
+   */
+  readonly useStorageBuffer: boolean;
+  /**
+   * Allocate a slice for `jointCount` joints. Returns the buffer + byte
+   * offset the record stage should bind. Storage path returns the same
+   * shared buffer for every call; uniform path mints (or pool-reuses) a
+   * per-entity buffer and returns it with `byteOffset: 0`. Both paths
+   * guarantee BG validation: storage extends the shared buffer's size,
+   * uniform sizes the per-entity buffer to exactly `bindingWindowBytes`.
+   *
+   * @throws if storage path buffer would exceed
+   *         `device.limits.maxStorageBufferBindingSize`
+   */
+  allocateSlice(jointCount: number): SkinPaletteSlice;
+  /**
+   * Write joint matrices into the slice's buffer at the slice's offset.
+   * Computes M_i = jointWorldTransforms[i] * ibm[i] per joint.
+   *
+   * `jointWorlds[i]` is taken straight from `Skin.joints[i]` entity's
+   * `Transform.world` view (a 16-float column-major Float32Array
+   * written by propagateTransforms); zero recompose, premultiplies
+   * directly against the IBM.
+   */
+  writeJointPalette(
+    slice: SkinPaletteSlice,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Mat4[],
+  ): void;
+  /**
+   * Reset for next frame. Storage path: cursor rewinds, shared buffer
+   * stays. Uniform path: per-entity buffer cursor rewinds (pool entries
+   * stay allocated and round-robin to the next frame's first entity).
+   */
+  resetForFrame(): void;
+}
+
+export function createSkinPaletteAllocator(
+  device: RhiDevice,
+  maxBindingSize: number,
+  useStorageBuffer = true,
+): SkinPaletteAllocator {
+  // Storage path: shared buffer state.
+  let storageBuffer: Buffer | null = null;
+  let storageCapacity = 0;
+  let storageCursor = 0;
+
+  // Uniform path: per-entity buffer pool. `pool` is the pre-allocated
+  // 16320 B UBO ring; `poolCursor` advances per allocateSlice within a
+  // frame and rewinds in resetForFrame, so a 3-entity scene reuses 3
+  // entries across frames (createBuffer fires only when the per-frame
+  // entity count grows past the historical max). 16320 B / entry
+  // bounded by maxUniformBufferBindingSize (>= 16384 by spec floor).
+  const pool: Buffer[] = [];
+  let poolCursor = 0;
+
+  function ensureStorageCapacity(needed: number): void {
+    if (storageBuffer !== null && needed <= storageCapacity) return;
+    let newCapacity = storageCapacity === 0 ? BINDING_WINDOW_BYTES : storageCapacity;
+    while (newCapacity < needed) {
+      // 1.5x grow, then next multiple of 256 for alignment (plan-strategy D-4).
+      newCapacity = (newCapacity + (newCapacity >> 1) + 255) & ~255;
+    }
+    if (newCapacity > maxBindingSize) {
+      throw new SkinPaletteOverflowError(newCapacity, maxBindingSize);
+    }
+    const bufRes = device.createBuffer({
+      label: 'skin-palette',
+      size: newCapacity,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!bufRes.ok) throw bufRes.error;
+    storageBuffer = bufRes.value;
+    storageCapacity = newCapacity;
+  }
+
+  function acquirePoolBuffer(): Buffer {
+    if (poolCursor < pool.length) {
+      const reused = pool[poolCursor];
+      // biome-ignore lint/style/noNonNullAssertion: poolCursor < pool.length guarantees the slot is set
+      return reused!;
+    }
+    if (BINDING_WINDOW_BYTES > maxBindingSize) {
+      throw new SkinPaletteOverflowError(BINDING_WINDOW_BYTES, maxBindingSize);
+    }
+    const bufRes = device.createBuffer({
+      label: 'skin-palette',
+      size: BINDING_WINDOW_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!bufRes.ok) throw bufRes.error;
+    pool.push(bufRes.value);
+    return bufRes.value;
+  }
+
+  function allocateSlice(jointCount: number): SkinPaletteSlice {
+    if (useStorageBuffer) {
+      // Storage path: shared buffer + dynOffset window.
+      // WebGPU validates `dynOffset + entry.size <= buffer.size` per
+      // setBindGroup, so the buffer must extend a full BINDING_WINDOW_BYTES
+      // past `byteOffset` -- not just `jointCount * 64`. Pre-M6 used the
+      // latter and tripped `Dynamic Offset[1] out of bounds` on entity 2+.
+      const offset = storageCursor;
+      const needed = offset + BINDING_WINDOW_BYTES;
+      ensureStorageCapacity(needed);
+      // biome-ignore lint/style/noNonNullAssertion: ensureStorageCapacity throws if buffer cannot be created
+      const buffer = storageBuffer!;
+      // Cursor advances by the actual joint footprint, then rounds up to
+      // PALETTE_OFFSET_ALIGN so the NEXT slice's byteOffset stays a valid
+      // dynamic offset (WebGPU requires 256-byte alignment). Slices still pack
+      // near-tightly (at most 255 B slack between them). Only the last slice's
+      // window may overhang into uninitialized buffer space, which is benign
+      // (shader reads only `jointCount` matrices).
+      storageCursor =
+        (offset + jointCount * MAT4_BYTES + (PALETTE_OFFSET_ALIGN - 1)) &
+        ~(PALETTE_OFFSET_ALIGN - 1);
+      return { jointCount, byteOffset: offset, buffer };
+    }
+    // Uniform fallback: each slice gets its own 16320 B UBO.
+    const buffer = acquirePoolBuffer();
+    poolCursor += 1;
+    return { jointCount, byteOffset: 0, buffer };
+  }
+
+  function writeJointPalette(
+    slice: SkinPaletteSlice,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Mat4[],
+  ): void {
+    const count = Math.min(slice.jointCount, ibms.length, jointWorlds.length);
+    if (count === 0) return;
+    const payload = new Float32Array(count * 16);
+    const temp = mat4.create();
+    const ibm = mat4.create();
+    for (let i = 0; i < count; i++) {
+      const ibmFlat = ibms[i];
+      const jw = jointWorlds[i];
+      if (ibmFlat === undefined || jw === undefined) continue;
+      for (let k = 0; k < 16; k++) {
+        ibm[k] = ibmFlat[k] ?? 0;
+      }
+      mat4.multiply(temp, jw, ibm);
+      const base = i * 16;
+      for (let j = 0; j < 16; j++) {
+        payload[base + j] = temp[j] ?? 0;
+      }
+    }
+    const res = device.queue.writeBuffer(slice.buffer, slice.byteOffset, payload);
+    if (!res.ok) throw res.error;
+  }
+
+  function resetForFrame(): void {
+    storageCursor = 0;
+    poolCursor = 0;
+  }
+
+  return {
+    bindingWindowBytes: BINDING_WINDOW_BYTES,
+    useStorageBuffer,
+    allocateSlice,
+    writeJointPalette,
+    resetForFrame,
+  };
+}

package/src/systems/skin-palette-types.ts

@@ -0,0 +1,14 @@
+import type { Buffer } from '@forgeax/engine-rhi';
+
+/**
+ * Per-draw palette slice metadata shared by the extract producer and the
+ * palette allocator. The slice carries the buffer identity so storage and
+ * uniform fallback paths converge at the record binding owner.
+ */
+export interface SkinPaletteSlice {
+  readonly jointCount: number;
+  /** Byte offset into buffer; uniform fallback slices always use zero. */
+  readonly byteOffset: number;
+  /** GPU buffer containing the slice's joint matrices. */
+  readonly buffer: Buffer;
+}

package/src/systems/transparent-sort-config.ts

@@ -0,0 +1,233 @@
+// @forgeax/engine-runtime - TransparentSortConfig KV resource + helpers.
+//
+// feat-20260520-2d-sprite-layer-mvp M-2 w14 / requirements AC-08 + AC-18
+// path (2)/(3) + AC-19 derivation audit (5).
+//
+// Surface:
+//   - interface  TransparentSortConfig { mode: number; yzAlpha: number }
+//   - constant   TRANSPARENT_SORT_CONFIG_KEY   = 'TransparentSortConfig'
+//   - constants  TRANSPARENT_SORT_MODE_LAYER_Z  = 0  (horizontal-z)
+//                TRANSPARENT_SORT_MODE_LAYER_Y  = 1  (Y-sort)
+//                TRANSPARENT_SORT_MODE_LAYER_YZ = 2  (Y-Z blend)
+//   - helper     getTransparentSortConfig(world): TransparentSortConfig
+//   - helper     setTransparentSortConfig(world, cfg):
+//                  Result<void, ResourceInvalidValueError>
+//
+// 5-view selection table (charter F1 progressive disclosure for AI users
+// reading IDE hover on this header; same SSOT mirrored in
+// apps/hello/sprite/README.md M-4 w33):
+//
+//   | view              | mode | yzAlpha | sortValue formula              |
+//   |:------------------|:----:|:-------:|:--------------------------------|
+//   | horizontal (side) |  0   |   ---   | posZ                            |
+//   | top-down          |  1   |   ---   | -(posY - pivot.y * size.y)      |
+//   | Don't Starve      |  2   |   1.0   | (posY - pivot.y * size.y) + posZ|
+//   | isometric         |  2   |   0.5   | (posY - pivot.y * size.y) + 0.5*posZ |
+//   | JRPG (foot pivot) |  1   |   ---   | -(posY - pivot.y * size.y)      |
+//
+// AC-18 path (2): @fallback getTransparentSortConfig KV missing returns
+//   default; no warn; no throw (legal default state, not an error state).
+// AC-18 path (3): @fallback setTransparentSortConfig mode out-of-range
+//   does NOT silently coerce to mode=0 — returns Result.err with the
+//   4 SSOT fields locked by plan-strategy D-4 so AI users can self-repair
+//   via .code / .expected / .hint / .detail property access (charter P3).
+// AC-18 path (3) carve-out: yzAlpha range is intentionally NOT validated;
+//   mode=0 / mode=1 ignore the field entirely, mode=2 reads it, mode=3
+//   (distance) also reads it for compat but ignores it (squared-distance
+//   formula does not use yzAlpha). The silent-ignore is the documented
+//   charter P3 "legal default" boundary.
+//
+// @new-surface KV resource: ECS has no defineResource factory at this
+//   feat's commit time; the TS POD interface + string KV key form is the
+//   minimum-new-surface route. The world resource store
+//   (insertResource / getResource / hasResource) is reused unchanged
+//   (requirements §2.2.G derivation row 5).
+// @derives world.hasResource / world.insertResource / world.getResource
+//   KV API (packages/ecs/src/resource.ts + world.ts: insertResource l.490,
+//   getResource l.498, hasResource l.503).
+// @fallback getTransparentSortConfig KV missing returns
+//   { mode: 0, yzAlpha: 1.0 }; no warn; no throw.
+// @fallback setTransparentSortConfig mode out-of-range returns Result.err
+//   with code='resource-invalid-value'; never silently coerced.
+//
+// charter mapping: F1 (single-import barrel + 5-view JSDoc table on
+// hover) + P3 (structured failure on mode out-of-range; legal-default
+// fallback distinguished from error fallback) + P4 (consistent
+// abstraction — same world.{has,get,insert}Resource KV API as every
+// other engine resource consumer).
+
+import type { World } from '@forgeax/engine-ecs';
+import { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// POD interface + KV key + 3 named mode constants
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Transparent-bucket sort configuration (plain-data POD). Lives as a
+ * world-level resource keyed by `TRANSPARENT_SORT_CONFIG_KEY`.
+ *
+ * Fields:
+ *   - `mode \u2208 {0, 1, 2, 3}` selects the sort formula
+ *     (`TRANSPARENT_SORT_MODE_LAYER_Z` / `_LAYER_Y` / `_LAYER_YZ` / `_DISTANCE`).
+ *   - `yzAlpha` (mode=2 only) blends Y-axis into Z-axis: 1.0 weights
+ *     posZ equally with `posY - pivot.y * size.y` (Don't-Starve style),
+ *     0.5 weights posZ at half (isometric). mode=0 / mode=1 ignore the
+ *     field (documented charter P3 legal-default boundary).
+ */
+export interface TransparentSortConfig {
+  readonly mode: number;
+  readonly yzAlpha: number;
+}
+
+/** Extract-stage POD consumed by the transparent-sort owner. */
+export interface TransparentEntry {
+  readonly entityIndex: number;
+  readonly materialHandle: number;
+  readonly layer: number;
+  readonly posX: number;
+  readonly posY: number;
+  readonly posZ: number;
+  readonly pivotY: number;
+  readonly sizeY: number;
+  readonly sortKey?: number | undefined;
+  readonly renderableIndex?: number | undefined;
+}
+
+/** World resource key for `TransparentSortConfig` KV entry. */
+export const TRANSPARENT_SORT_CONFIG_KEY = 'TransparentSortConfig' as const;
+
+/** horizontal / side-scroller: sortValue = posZ. */
+export const TRANSPARENT_SORT_MODE_LAYER_Z = 0;
+
+/** top-down / JRPG: sortValue = -(posY - pivot.y * size.y) (foot pivot Y-sort). */
+export const TRANSPARENT_SORT_MODE_LAYER_Y = 1;
+
+/** Don't-Starve / isometric: sortValue = (posY - pivot.y * size.y) + yzAlpha * posZ. */
+export const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;
+
+/** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */
+export const TRANSPARENT_SORT_MODE_DISTANCE = 3;
+
+/** Grouped authoring values and the single configuration operation. */
+export const 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,
+} as const);
+
+// ────────────────────────────────────────────────────────────────────────────
+// Internal: silent default + mode validity check
+// ────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: TransparentSortConfig = Object.freeze({
+  mode: TRANSPARENT_SORT_MODE_LAYER_Z,
+  yzAlpha: 1.0,
+});
+
+const VALID_MODES: ReadonlySet<number> = new Set<number>([
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_DISTANCE,
+]);
+
+// The expected / hint literals are the SSOT locked by plan-strategy D-4.
+// They MUST round-trip byte-for-byte into ResourceInvalidValueError so AI
+// users can read err.expected / err.hint for self-repair (charter P3).
+// `\u2208` is the math "is-element-of" symbol; the ASCII source escape
+// keeps the file English-only per AGENTS.md §Conventions.
+const EXPECTED_MODE = 'mode \u2208 {0, 1, 2, 3}';
+const HINT_MODE = '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read the world's `TransparentSortConfig` resource.
+ *
+ * @fallback KV missing returns `{ mode: 0, yzAlpha: 1.0 }`
+ * (`TRANSPARENT_SORT_MODE_LAYER_Z`, horizontal-z safe default).
+ * NO warn, NO throw — KV missing is a legal state (not an error state),
+ * mirroring how a sprite-free scene is a legal state for the renderer
+ * even though render-system has a transparent bucket. plan-strategy D-2:
+ * `hasResource` guard precedes the read so this helper never trips
+ * `ResourceNotFoundError` from `world.getResource`.
+ *
+ * @example
+ *   const cfg = getTransparentSortConfig(world);
+ *   // cfg.mode === 0, cfg.yzAlpha === 1.0 when no resource inserted.
+ *
+ * @example
+ *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,
+ *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });
+ *   const cfg = getTransparentSortConfig(world);
+ *   // cfg.mode === 1, cfg.yzAlpha === 1.0 (yzAlpha ignored by mode=1).
+ */
+export function getTransparentSortConfig(world: World): TransparentSortConfig {
+  if (!world.hasResource(TRANSPARENT_SORT_CONFIG_KEY)) {
+    return DEFAULT_CONFIG;
+  }
+  return world.getResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY);
+}
+
+/**
+ * Write the world's `TransparentSortConfig` resource, validating `mode`.
+ *
+ * Returns `Result<void, ResourceInvalidValueError>`:
+ *
+ *   - `ok` — mode is in `{0, 1, 2, 3}`; the resource is inserted /
+ *     overwritten via `world.insertResource`.
+ *   - `err` — mode is out of range; the resource is NOT mutated;
+ *     `err.error` is a `ResourceInvalidValueError` instance carrying:
+ *       `.code === 'resource-invalid-value'`
+ *       `.expected === 'mode \u2208 {0, 1, 2, 3}'`
+ *       `.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'`
+ *       `.detail.receivedMode === <the rejected mode>`
+ *
+ * @fallback mode out-of-range is NEVER silently coerced to mode=0 —
+ * `Result.err` is the only fail-mode (charter P3 structured failure).
+ * AI users read `.code / .expected / .hint / .detail` properties to
+ * self-repair, NOT the human-readable `.message` string.
+ *
+ * @fallback yzAlpha range is intentionally not validated; mode=0 / mode=1
+ * ignore the field, mode=2 reads it. The silent-ignore is the
+ * documented charter P3 "legal default" boundary (plan-strategy D-4 +
+ * AC-18 path (3) carve-out).
+ *
+ * @example success path:
+ *   const r = setTransparentSortConfig(world,
+ *     { mode: TRANSPARENT_SORT_MODE_LAYER_YZ, yzAlpha: 0.5 });
+ *   if (!r.ok) return r;
+ *
+ * @example failure path:
+ *   const r = setTransparentSortConfig(world, { mode: 99, yzAlpha: 1.0 });
+ *   if (!r.ok) {
+ *     // r.error.code === 'resource-invalid-value'
+ *     // r.error.expected === 'mode \u2208 {0, 1, 2, 3}'
+ *     // r.error.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'
+ *     // r.error.detail.receivedMode === 99
+ *   }
+ */
+export function setTransparentSortConfig(
+  world: World,
+  cfg: TransparentSortConfig,
+): Result<void, ResourceInvalidValueError> {
+  if (!VALID_MODES.has(cfg.mode)) {
+    return err(
+      new ResourceInvalidValueError(EXPECTED_MODE, HINT_MODE, {
+        receivedMode: cfg.mode,
+        receivedKey: TRANSPARENT_SORT_CONFIG_KEY,
+      }),
+    );
+  }
+  world.insertResource<TransparentSortConfig>(TRANSPARENT_SORT_CONFIG_KEY, {
+    mode: cfg.mode,
+    yzAlpha: cfg.yzAlpha,
+  });
+  return ok(undefined);
+}