@forgeax/engine-render 0.1.2

package/dist/chunk-JMSB7AR4.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-JMSB7AR4.mjs.map
+//# sourceMappingURL=chunk-JMSB7AR4.mjs.map

package/dist/chunk-JMSB7AR4.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-JMSB7AR4.mjs"}

package/dist/chunk-LXNGO6AO.mjs

@@ -0,0 +1,569 @@
+import { Camera, DirectionalLight, GlyphText, Instances, Layer, MeshFilter, MeshRenderer, PointLight, PointLightShadow, PostProcessParams, SceneInstance, SkyboxBackground, Skylight, SortKey, SpotLight, SpriteAnimation, SpriteInstances, SpriteRegionOverride, TileLayer, Tilemap, Visibility, RenderFeatureStageFailedError } from './chunk-YAKEQPWO.mjs';
+import { validateCookedMaterialRecord } from '@forgeax/engine-pack';
+import { ok, err, MATERIAL_TEXTURE_SLOTS } from '@forgeax/engine-types';
+import { Children, Name, worldSetSceneInstantiateHook, SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+
+function invalid(guid, expected, reason) {
+  return err({
+    code: "asset-package-invalid",
+    expected,
+    hint: "recook the render asset and publish its complete cooked payload",
+    detail: { guid, reason }
+  });
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validMaterial(value) {
+  if (!record(value) || value.kind !== "material") return false;
+  if (value.cooked !== void 0 && !validateCookedMaterialRecord(value.cooked).ok) {
+    return false;
+  }
+  if (value.passes !== void 0 && !Array.isArray(value.passes)) return false;
+  if (value.parameters !== void 0 && !Array.isArray(value.parameters)) return false;
+  return value.values === void 0 || record(value.values);
+}
+function resolveMaterialWireRef(value, refs, field, guid) {
+  if (typeof value !== "number") return ok(value);
+  if (!Number.isSafeInteger(value) || value < 0 || refs[value] === void 0) {
+    return err({
+      code: "asset-package-invalid",
+      expected: `${field} to reference a GUID through the material Pack refs[] table`,
+      hint: "recook the material so every texture or sampler ref has a matching refs[] entry",
+      detail: { guid, reason: `${field} refs[${value}] is out of bounds` }
+    });
+  }
+  return ok(refs[value]);
+}
+function resolveMaterialWireRefs(value, refs, guid) {
+  if (refs.length === 0) return ok(value);
+  let changed = false;
+  let parent = value.parent;
+  if (typeof parent === "number") {
+    const resolved = resolveMaterialWireRef(parent, refs, "parent", guid);
+    if (!resolved.ok) return resolved;
+    parent = resolved.value;
+    changed = true;
+  }
+  if (value.values === void 0) {
+    return changed ? ok({ ...value, ...parent === void 0 ? {} : { parent } }) : ok(value);
+  }
+  const textureFields = new Set(
+    value.parameters === void 0 ? MATERIAL_TEXTURE_SLOTS : value.parameters.filter((parameter) => parameter.type === "texture").map((parameter) => parameter.name)
+  );
+  const values = { ...value.values };
+  for (const [field, raw] of Object.entries(values)) {
+    if (typeof raw === "number" && textureFields.has(field)) {
+      const resolved = resolveMaterialWireRef(raw, refs, field, guid);
+      if (!resolved.ok) return resolved;
+      values[field] = resolved.value;
+      changed = true;
+      continue;
+    }
+    if (!record(raw)) continue;
+    const rawRecord = raw;
+    let rewritten;
+    for (const key of ["texture", "sampler"]) {
+      if (!(key in rawRecord)) continue;
+      const resolved = resolveMaterialWireRef(rawRecord[key], refs, `${field}.${key}`, guid);
+      if (!resolved.ok) return resolved;
+      if (resolved.value !== rawRecord[key]) {
+        rewritten ??= { ...rawRecord };
+        rewritten[key] = resolved.value;
+        changed = true;
+      }
+    }
+    if (rewritten !== void 0) {
+      values[field] = rewritten;
+    }
+  }
+  return ok(changed ? { ...value, ...parent === void 0 ? {} : { parent }, values } : value);
+}
+var materialContribution = {
+  kind: { kind: "material" },
+  consumer: "Render MaterialScene",
+  decoder: {
+    async decode({ envelope }) {
+      if (!validMaterial(envelope.payload)) {
+        return invalid(
+          envelope.guid,
+          "a material payload with cooked passes, parameters, and values",
+          "material owner validation failed"
+        );
+      }
+      return resolveMaterialWireRefs(envelope.payload, envelope.refs, envelope.guid);
+    }
+  }
+};
+var samplerContribution = {
+  kind: { kind: "sampler" },
+  consumer: "Render DeviceScope",
+  decoder: {
+    async decode({ envelope }) {
+      return envelope.payload.kind === "sampler" ? ok(envelope.payload) : invalid(envelope.guid, "a sampler payload", "sampler owner validation failed");
+    }
+  }
+};
+var renderPipelineContribution = {
+  kind: { kind: "render-pipeline" },
+  consumer: "Render Pipeline",
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      return payload.kind === "render-pipeline" && payload.pipelineId.trim().length > 0 ? ok(payload) : invalid(
+        envelope.guid,
+        "a render-pipeline payload with a pipelineId",
+        "render-pipeline owner validation failed"
+      );
+    }
+  }
+};
+
+// src/features/morph/morph-bounds.ts
+var MORPH_MAX_TARGETS = 8;
+function finiteVec3(value) {
+  return value.every((component) => Number.isFinite(component));
+}
+function validWeights(weights, expected) {
+  if (weights === void 0 || weights.length !== expected) return false;
+  for (let index = 0; index < weights.length; index++) {
+    if (!Number.isFinite(weights[index] ?? Number.NaN)) return false;
+  }
+  return true;
+}
+function deriveMorphBounds(base, targets, weights) {
+  if (!finiteVec3(base.min) || !finiteVec3(base.max) || targets.length > MORPH_MAX_TARGETS || !validWeights(weights, targets.length)) {
+    return base;
+  }
+  const min = [base.min[0], base.min[1], base.min[2]];
+  const max = [base.max[0], base.max[1], base.max[2]];
+  for (let targetIndex = 0; targetIndex < targets.length; targetIndex++) {
+    const target = targets[targetIndex];
+    const weight = weights[targetIndex] ?? 0;
+    if (target === void 0 || !finiteVec3(target.min) || !finiteVec3(target.max)) return base;
+    for (let axis = 0; axis < 3; axis++) {
+      const low = (weight >= 0 ? target.min[axis] : target.max[axis]) ?? 0;
+      const high = (weight >= 0 ? target.max[axis] : target.min[axis]) ?? 0;
+      min[axis] = (min[axis] ?? 0) + weight * low;
+      max[axis] = (max[axis] ?? 0) + weight * high;
+    }
+  }
+  return {
+    min: [min[0] ?? 0, min[1] ?? 0, min[2] ?? 0],
+    max: [max[0] ?? 0, max[1] ?? 0, max[2] ?? 0]
+  };
+}
+function morphCullDecision(input) {
+  if (!Number.isInteger(input.expectedWeightCount) || input.expectedWeightCount < 0) return "cull";
+  if (!validWeights(input.weights, input.expectedWeightCount)) {
+    return "cull";
+  }
+  for (let index = 0; index < input.expectedWeightCount; index++) {
+    if ((input.weights?.[index] ?? 0) !== 0) return "draw";
+  }
+  return input.baseAabbIntersectsFrustum ? "draw" : "cull";
+}
+function createMorphReentryState() {
+  return { seen: false, visible: false, generation: -1, weights: void 0 };
+}
+function stepMorphReentry(state, input) {
+  const reentered = state.seen && input.visible && (!state.visible || state.generation !== input.generation);
+  const clearStale = reentered && state.weights !== void 0;
+  const weights = Array.from(
+    { length: input.weights.length },
+    (_, index) => input.weights[index] ?? 0
+  );
+  state.seen = true;
+  state.visible = input.visible;
+  state.generation = input.generation;
+  state.weights = new Float32Array(weights);
+  return { frameNumber: input.frameNumber, reentered, clearStale, weights };
+}
+var COMPUTE_STAGE = 4;
+var MORPH_WEIGHTS_BYTES = MORPH_MAX_TARGETS * Float32Array.BYTES_PER_ELEMENT;
+var MORPH_WORKGROUP_SIZE = 64;
+var MORPH_COMPUTE_WGSL = `
+struct MorphWeights { values: array<f32, 8> };
+@group(0) @binding(0) var<storage, read> source: array<vec4<f32>>;
+@group(0) @binding(1) var<storage, read_write> output: array<vec4<f32>>;
+@group(0) @binding(2) var<uniform> weights: MorphWeights;
+
+@compute @workgroup_size(${MORPH_WORKGROUP_SIZE})
+fn morph_main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let vertex = id.x;
+  let vertex_count = arrayLength(&output);
+  if (vertex >= vertex_count) { return; }
+  var position = source[vertex];
+  for (var target_index = 0u; target_index < 8u; target_index = target_index + 1u) {
+    position = position + source[(target_index + 1u) * vertex_count + vertex] * weights.values[target_index];
+  }
+  output[vertex] = position;
+}
+`;
+function stageFailure(stage) {
+  return new RenderFeatureStageFailedError("forgeax.morph", -1, stage, "next-frame");
+}
+function copyWeights(input) {
+  const weights = new Float32Array(MORPH_MAX_TARGETS);
+  for (let index = 0; index < Math.min(input.length, MORPH_MAX_TARGETS); index++) {
+    weights[index] = input[index] ?? 0;
+  }
+  return weights;
+}
+function copySource(renderable, targetCount) {
+  const source = new Float32Array((MORPH_MAX_TARGETS + 1) * renderable.vertexCount * 4);
+  const basePositions = renderable.basePositions;
+  const targetDeltas = renderable.targetDeltas;
+  for (let vertex = 0; vertex < renderable.vertexCount; vertex++) {
+    const base = vertex * 4;
+    source[base] = basePositions?.[vertex * 3] ?? 0;
+    source[base + 1] = basePositions?.[vertex * 3 + 1] ?? 0;
+    source[base + 2] = basePositions?.[vertex * 3 + 2] ?? 0;
+    source[base + 3] = 1;
+    for (let target = 0; target < targetCount; target++) {
+      const sourceBase = (target + 1) * renderable.vertexCount * 4 + vertex * 4;
+      const deltaBase = (target * renderable.vertexCount + vertex) * 3;
+      source[sourceBase] = targetDeltas?.[deltaBase] ?? 0;
+      source[sourceBase + 1] = targetDeltas?.[deltaBase + 1] ?? 0;
+      source[sourceBase + 2] = targetDeltas?.[deltaBase + 2] ?? 0;
+      source[sourceBase + 3] = 0;
+    }
+  }
+  return source;
+}
+function validRenderable(renderable) {
+  return renderable.identity.length > 0 && Number.isInteger(renderable.vertexCount) && renderable.vertexCount > 0 && renderable.targetBounds.length > 0 && renderable.targetBounds.length <= MORPH_MAX_TARGETS && renderable.weights.length === renderable.targetBounds.length;
+}
+function createMorphFeature(options) {
+  const reentry = /* @__PURE__ */ new Map();
+  const prepared = /* @__PURE__ */ new Map();
+  const feature = {
+    identity: "forgeax.morph",
+    requiredCapabilities: ["compute", "storageBuffer"],
+    extract: ({ worlds, frameNumber }) => {
+      const renderables = options.collect({ worlds, frameNumber });
+      const draws = [];
+      let culledCount = 0;
+      let zeroWeightCount = 0;
+      let reentryCount = 0;
+      for (const renderable of renderables) {
+        if (!validRenderable(renderable)) return err(stageFailure("prepare"));
+        const weights = copyWeights(renderable.weights);
+        const decision = morphCullDecision({
+          weights: renderable.weights,
+          expectedWeightCount: renderable.targetBounds.length,
+          baseAabbIntersectsFrustum: renderable.baseAabbIntersectsFrustum
+        });
+        const state = reentry.get(renderable.identity) ?? createMorphReentryState();
+        reentry.set(renderable.identity, state);
+        const transition = stepMorphReentry(state, {
+          frameNumber,
+          visible: decision === "draw",
+          generation: 0,
+          weights
+        });
+        if (decision === "cull") {
+          culledCount += 1;
+          if (weights.every((weight) => weight === 0)) zeroWeightCount += 1;
+          continue;
+        }
+        if (transition.reentered) reentryCount += 1;
+        draws.push({
+          identity: renderable.identity,
+          vertexCount: renderable.vertexCount,
+          targetCount: renderable.targetBounds.length,
+          bounds: deriveMorphBounds(
+            renderable.baseBounds,
+            renderable.targetBounds,
+            renderable.weights
+          ),
+          weights,
+          reentered: transition.reentered,
+          clearStale: transition.clearStale,
+          source: copySource(renderable, renderable.targetBounds.length)
+        });
+      }
+      prepared.clear();
+      return ok({
+        frameNumber,
+        draws,
+        culledCount,
+        zeroWeightCount,
+        reentryCount
+      });
+    },
+    prepare: (data, context) => {
+      if (data.draws.length === 0) return ok(void 0);
+      const gpu = context.gpu;
+      if (gpu === void 0) return err(stageFailure("prepare"));
+      const program = gpu.prepareProgram("morph.compute", {
+        wgsl: MORPH_COMPUTE_WGSL,
+        entryPoints: ["morph_main"],
+        bindings: [
+          {
+            label: "forgeax.morph.bindings",
+            entries: [
+              { binding: 0, visibility: COMPUTE_STAGE, buffer: { type: "read-only-storage" } },
+              { binding: 1, visibility: COMPUTE_STAGE, buffer: { type: "storage" } },
+              { binding: 2, visibility: COMPUTE_STAGE, buffer: { type: "uniform" } }
+            ]
+          }
+        ]
+      });
+      if (!program.ok) return err(program.error);
+      for (const draw of data.draws) {
+        const prefix = `morph.${draw.identity}`;
+        const source = gpu.prepareBuffer(`${prefix}.source`, {
+          size: draw.source.byteLength,
+          usage: ["storage"],
+          data: draw.source
+        });
+        if (!source.ok) return err(source.error);
+        const output = gpu.prepareBuffer(`${prefix}.output`, {
+          size: draw.vertexCount * 16,
+          usage: ["storage", "vertex", "copy-src"]
+        });
+        if (!output.ok) return err(output.error);
+        const weights = gpu.prepareBuffer(`${prefix}.weights`, {
+          size: MORPH_WEIGHTS_BYTES,
+          usage: ["uniform"],
+          data: draw.weights
+        });
+        if (!weights.ok) return err(weights.error);
+        const bindings = gpu.prepareBindings(`${prefix}.bindings`, {
+          program: program.value,
+          entries: [
+            { binding: 0, buffer: source.value },
+            { binding: 1, buffer: output.value },
+            { binding: 2, buffer: weights.value }
+          ]
+        });
+        if (!bindings.ok) return err(bindings.error);
+        prepared.set(draw.identity, {
+          program: program.value,
+          source: source.value,
+          output: output.value,
+          weights: weights.value,
+          bindings: bindings.value
+        });
+      }
+      return ok(void 0);
+    },
+    contribute: (data, context) => {
+      if (data.draws.length === 0) return ok(void 0);
+      const gpu = context.gpu;
+      if (gpu === void 0) return err(stageFailure("contribute"));
+      for (const draw of data.draws) {
+        const state = prepared.get(draw.identity);
+        if (state === void 0) return err(stageFailure("contribute"));
+        const added = context.staging.addComputePass(`morph.${draw.identity}`, {
+          program: state.program,
+          bindings: state.bindings,
+          dispatches: [
+            {
+              entryPoint: "morph_main",
+              workgroups: [Math.max(1, Math.ceil(draw.vertexCount / MORPH_WORKGROUP_SIZE))],
+              bindings: state.bindings
+            }
+          ]
+        });
+        if (!added.ok) return added;
+      }
+      return ok(void 0);
+    },
+    recover: () => {
+      prepared.clear();
+      return ok(void 0);
+    },
+    preparedOutput: (identity) => prepared.get(identity)?.output,
+    dispose: () => {
+      prepared.clear();
+      reentry.clear();
+      return ok(void 0);
+    }
+  };
+  return feature;
+}
+function collectSubtree(world, spawnRoot, visited) {
+  if (visited === void 0) visited = /* @__PURE__ */ new Set();
+  if (visited.has(spawnRoot)) return visited;
+  const queue = [spawnRoot];
+  visited.add(spawnRoot);
+  while (queue.length > 0) {
+    const cur = queue.shift();
+    const childrenData = world.get(cur, Children);
+    if (!childrenData.ok) continue;
+    const list = childrenData.value.entities;
+    for (let i = 0; i < list.length; i++) {
+      const child = list[i];
+      if (visited.has(child)) continue;
+      visited.add(child);
+      queue.push(child);
+    }
+  }
+  return visited;
+}
+
+// src/scene-instances/post-spawn-resolve-joints.ts
+function postSpawnResolveJoints(world, resolver, spawnRoot) {
+  const subtree = collectSubtree(world, spawnRoot);
+  const nameIndex = /* @__PURE__ */ new Map();
+  const nameQuery = world.query({ read: [Name] });
+  if (nameQuery.ok) {
+    for (const row of nameQuery.value) {
+      if (!subtree.has(row.entity)) continue;
+      const nameVal = row.get(Name).value;
+      const list = nameIndex.get(nameVal) ?? [];
+      list.push(row.entity);
+      nameIndex.set(nameVal, list);
+    }
+  }
+  const skinQuery = world.query({ read: [Skin] });
+  if (!skinQuery.ok) return { ok: true };
+  for (const queryRow of skinQuery.value) {
+    const entity = queryRow.entity;
+    if (!subtree.has(entity)) continue;
+    const skeletonHandle = queryRow.get(Skin).skeleton;
+    const skinAsset = resolver.resolveSkinAsset(skeletonHandle);
+    if (skinAsset === void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "skin-asset-unresolved",
+          expected: `SkinAsset registered for skeleton handle ${skeletonHandle} when instantiate triggers postSpawnResolveJoints`,
+          hint: `SkinAsset matching skeletonGuid for handle ${skeletonHandle} was not found in AssetRegistry; verify the SceneAsset.skinGuids[] cross-edge is populated by the importer (gltfImporter scene branch) and that AssetRegistry.load(sceneGuid, sceneAssetKind) recursively loaded each SkinAsset before instantiate (browser-async-pack-fetch path)`,
+          detail: { skinEntity: entity, skeletonHandle }
+        }
+      };
+    }
+    const jointEntityList = [];
+    for (const jointPath of skinAsset.jointPaths) {
+      const pathSegments = jointPath.split("/").filter(Boolean);
+      if (pathSegments.length === 0) continue;
+      const leafName = pathSegments[pathSegments.length - 1];
+      if (leafName === void 0) continue;
+      const nameMatches = nameIndex.get(leafName);
+      if (nameMatches === void 0 || nameMatches.length === 0) {
+        return {
+          ok: false,
+          error: {
+            code: "skin-joint-path-unresolved",
+            expected: `joint entity with Name="${leafName}" exists in the spawned subtree (root entity ${spawnRoot})`,
+            hint: `joint path "${jointPath}" for skin entity ${entity} could not be resolved within spawnRoot ${spawnRoot}'s ChildOf-subtree; verify glTF node names are preserved and instantiateScene seeded a Children mirror`,
+            detail: {
+              skinEntity: entity,
+              path: pathSegments,
+              failedAtIndex: pathSegments.length - 1
+            }
+          }
+        };
+      }
+      if (nameMatches.length > 1) {
+        console.warn(
+          `[Skin] same-name sibling: "${leafName}" matches ${nameMatches.length} entities within spawn subtree of root ${spawnRoot}; using first-match (entity ${nameMatches[0]}) per D-6a`
+        );
+      }
+      jointEntityList.push(nameMatches[0]);
+    }
+    world.set(entity, Skin, {
+      joints: new Uint32Array(jointEntityList)
+    });
+  }
+  return { ok: true };
+}
+
+// src/plugin.ts
+var RENDER_COMPONENTS = [
+  Camera,
+  DirectionalLight,
+  GlyphText,
+  Instances,
+  Layer,
+  MeshFilter,
+  MeshRenderer,
+  PointLight,
+  PointLightShadow,
+  PostProcessParams,
+  SceneInstance,
+  SkyboxBackground,
+  Skylight,
+  SortKey,
+  SpotLight,
+  SpriteAnimation,
+  SpriteInstances,
+  SpriteRegionOverride,
+  TileLayer,
+  Tilemap,
+  Visibility
+];
+function registerRenderComponents(world) {
+  const leases = RENDER_COMPONENTS.map(
+    (component) => world.components.register(component).unwrap()
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+function installSceneInstantiateHook(world) {
+  worldSetSceneInstantiateHook(world, (currentWorld, root) => {
+    if (!currentWorld.hasResource(SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY)) {
+      return { ok: true };
+    }
+    const resolver = currentWorld.getResource(
+      SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY
+    );
+    return postSpawnResolveJoints(currentWorld, resolver, root);
+  });
+  return () => worldSetSceneInstantiateHook(world, null);
+}
+function renderComponentsPlugin() {
+  return {
+    name: "render-components",
+    inject: ["world"],
+    apply(ctx) {
+      ctx.effect(() => registerRenderComponents(ctx.world), "render/components");
+      ctx.effect(() => installSceneInstantiateHook(ctx.world), "render/scene-instantiate-hook");
+    }
+  };
+}
+function rendererPlugin(renderer) {
+  return {
+    name: "renderer",
+    provide: "renderer",
+    apply(ctx) {
+      ctx.provide("renderer", renderer);
+    }
+  };
+}
+function ownedRendererPlugin(renderer) {
+  return {
+    name: "renderer",
+    provide: "renderer",
+    apply(ctx) {
+      ctx.provide("renderer", renderer);
+      ctx.effect(() => () => renderer.dispose(), "render/renderer");
+    }
+  };
+}
+function renderFeaturePlugin(feature) {
+  return {
+    name: `render-feature:${feature.identity}`,
+    inject: ["renderer"],
+    async apply(ctx) {
+      const renderer = ctx.renderer;
+      if (renderer === void 0)
+        throw new Error("render feature plugin requires the renderer service");
+      const installed = await renderer.installRenderFeature(feature);
+      if (!installed.ok) throw installed.error;
+      return async () => {
+        const removed = await renderer.uninstallRenderFeature(feature);
+        if (!removed.ok) throw removed.error;
+      };
+    }
+  };
+}
+
+export { MORPH_COMPUTE_WGSL, MORPH_MAX_TARGETS, collectSubtree, createMorphFeature, createMorphReentryState, deriveMorphBounds, materialContribution, morphCullDecision, ownedRendererPlugin, postSpawnResolveJoints, renderComponentsPlugin, renderFeaturePlugin, renderPipelineContribution, rendererPlugin, samplerContribution, stepMorphReentry };
+//# sourceMappingURL=chunk-LXNGO6AO.mjs.map
+//# sourceMappingURL=chunk-LXNGO6AO.mjs.map