@forgeax/engine-render 0.1.29 → 0.1.31

package/src/assembly/device-feature-admission.ts

@@ -1,5 +1,6 @@
 import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
 import { EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES } from '../prepare/extended-lighting/resources';
+import { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES } from './shader-prewarm-policy';
 
 const COMPRESSION_FEATURES: GPUFeatureName[] = [
   'texture-compression-bc',
@@ -7,13 +8,17 @@ const COMPRESSION_FEATURES: GPUFeatureName[] = [
   'texture-compression-astc',
 ];
 
-// The Standard transmission fragment ABI needs 17 sampled textures across its
+// The Standard transmission fragment ABI needs 18 sampled textures across its
 // material, IBL, clustered-light, and SSAO bindings. Ordinary Standard draws
 // use the non-transmission variant and remain valid on the WebGPU minimum of
-// 16. The extended-lighting topology reserves 20, so a device descriptor must
+// 16. The extended-lighting topology reserves 21, so a device descriptor must
 // request that larger limit when the adapter can provide it; adapter limits are
 // not automatically inherited by requestDevice().
-export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
+export { STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES };
+
+export function transmissionBackdropAvailable(limit: number | undefined): boolean {
+  return limit === undefined || limit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+}
 /**
  * The complete Standard physical root can declare all optional texture slots.
  * Its material group therefore needs one more sampled-texture entry than the
@@ -21,7 +26,7 @@ export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
  * provide it; lower-capability devices remain fail-closed at material
  * pipeline admission instead of receiving an invalid WebGPU layout.
  */
-export const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 21;
+export const STANDARD_PHYSICAL_REQUIRED_SAMPLED_TEXTURES = 22;
 
 export interface DeviceFeatureAdmissionOptions {
   readonly gpuPassTiming?: object | undefined;

package/src/assembly/dynamic-geometry-host.ts

@@ -2,7 +2,7 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { FixedTime } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { Transform } from '@forgeax/engine-scene';
-import { err, type Handle, type Result } from '@forgeax/engine-types';
+import { err, type Handle, ok, type Result } from '@forgeax/engine-types';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import type { GpuResidencyCache } from '../device/gpu-residency';
@@ -26,6 +26,15 @@ export interface DynamicGeometryHostImplementation {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
@@ -270,7 +279,188 @@ export function createDynamicGeometryHost(options: {
     else void completion.then(finish, finish);
     return completion;
   };
-  return {
+  const acceptCandidate = (
+    candidate: DynamicGeometryCandidate,
+    ordering: DynamicGeometryOrdering,
+    deferredSupersession?: Set<HostCandidateRecord>,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError> => {
+    synchronizeGeneration();
+    const world = candidate.world as World;
+    const hostRecordById = hostCandidates.get(candidate.candidateId);
+    const hostRecord = candidateRecord(candidate);
+    if (hostRecord === undefined && hostRecordById !== undefined)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-receipt-mismatch',
+          'admission uses the exact host candidate owner and lifecycle credential',
+          'discard the altered credential and use the value returned by preparation',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (hostRecord !== undefined && candidate.state !== 'prepared')
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-candidate-state',
+          'admission consumes a prepared candidate exactly once',
+          'retain the accepted or published candidate receipt instead of admitting it again',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (ordering === undefined || !attachedWorlds.has(world) || ordering.world !== candidate.world)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-world-not-attached',
+          'candidate and fixed-step ordering belong to the same attached World',
+          'attach the World and submit its PhysicsWorld ordering before accepting geometry',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (!candidate.gpuReady)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-gpu-not-ready',
+          'candidate has standard GPU residency before acceptance',
+          'prepare with an existing MeshAsset shared handle and repair residency failures',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (
+      hostRecord === undefined ||
+      !hasRenderableBinding(world, candidate.entity) ||
+      !hasMaterialIdentity(world, candidate.entity, candidate.mesh, candidate.materialIdentity)
+    )
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the candidate is bound to a live ECS MeshFilter and MeshRenderer',
+          'keep the candidate MeshFilter binding intact until the consuming draw',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (meshHandleOf(world, candidate.entity) !== hostRecord.previousMeshHandle)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the old MeshFilter binding remains visible until candidate acceptance',
+          'do not replace the live ECS binding while geometry is prepared',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    const currentFixedStep = fixedStepOf(world);
+    if (
+      currentFixedStep === undefined ||
+      candidate.fixedStep === undefined ||
+      candidate.fixedStep > currentFixedStep ||
+      ordering.fixedStep !== currentFixedStep
+    )
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-ordering-required',
+          'ordering matches the current World tick, no earlier than preparation',
+          'accept a prepared candidate during the current fixed-step admission',
+          {
+            candidateId: candidate.candidateId,
+            actual: {
+              candidate: candidate.fixedStep,
+              currentFixedStep,
+              ordering: ordering.fixedStep,
+            },
+          },
+        ),
+      );
+    if (candidate.physicsEntity !== undefined) {
+      const publication = physicsPublicationOf(world, candidate.physicsEntity, true);
+      if (
+        publication === undefined ||
+        publication.fixedStep !== currentFixedStep ||
+        publication.revision !== candidate.revision
+      )
+        return err(
+          new DynamicGeometryError(
+            'dynamic-geometry-ordering-required',
+            'candidate physicsEntity has the active paired PhysicsWorld admission',
+            'accept geometry inside admitDerivedShapeCandidate commitGeometry, before physics step',
+            { candidateId: candidate.candidateId, actual: publication },
+          ),
+        );
+    }
+    // One ECS MeshFilter has one visible geometry owner.  Once this
+    // candidate is accepted, any older prepared/accepted candidate for the
+    // same entity can no longer become a receipt-bearing draw. Cancel it
+    // after the new ECS swap so its candidate-only residency is no longer
+    // protected as the live draw owner. Published candidates stay
+    // receipt-bound and are retired independently.
+    const superseded = [...hostCandidates.values()].filter(
+      (record) =>
+        record.candidate.candidateId !== candidate.candidateId &&
+        record.world === world &&
+        record.entity === candidate.entity &&
+        !record.published,
+    );
+    const accepted = lifecycle.accept(candidate, ordering);
+    if (!accepted.ok) return accepted;
+    const swapped = world.set(candidate.entity as EntityHandle, MeshFilter, {
+      assetHandle: hostRecord.meshHandle,
+    });
+    if (!swapped.ok) {
+      lifecycle.cancel(accepted.value);
+      hostCandidates.delete(candidate.candidateId);
+      cleanupCandidateResidency(hostRecord);
+      const released = releaseMeshLeases(hostRecord);
+      if (released !== undefined) return err(released);
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the candidate MeshFilter swap commits through the ECS write barrier',
+          'restore the live entity and retry from a fresh candidate',
+          { candidateId: candidate.candidateId, actual: swapped.error },
+        ),
+      );
+    }
+    hostRecord.candidate = accepted.value;
+    hostRecord.accepted = true;
+    if (deferredSupersession === undefined) options.onTopologyChanged?.();
+    // Keep the World handle leased through the final GPU submission; its slot
+    // must not be reused while a retired frame still references the old mesh.
+    // Cleanup happens only after the new ECS MeshFilter is visible. Before
+    // the swap, hasMeshBinding intentionally protects the older candidate's
+    // GPU copy because it is still the live draw owner.
+    if (deferredSupersession !== undefined) {
+      for (const record of superseded) deferredSupersession.add(record);
+      return accepted;
+    }
+    for (const record of superseded) {
+      const completion = cleanupCandidateResidency(record);
+      const cancelled = lifecycle.cancel(record.candidate, completion);
+      if (!cancelled.ok && cancelled.error.code !== 'dynamic-geometry-candidate-not-found') {
+        const restored = world.set(candidate.entity as EntityHandle, MeshFilter, {
+          assetHandle: hostRecord.previousMeshHandle,
+        });
+        lifecycle.cancel(accepted.value);
+        hostCandidates.delete(candidate.candidateId);
+        cleanupCandidateResidency(hostRecord);
+        releasePreviousMeshLease(hostRecord);
+        return err(
+          new DynamicGeometryError(
+            'dynamic-geometry-invalid',
+            'candidate supersession cancels the prior credential atomically',
+            'keep the prior ECS binding and candidate lifecycle intact when supersession fails',
+            {
+              candidateId: candidate.candidateId,
+              actual: {
+                cancelled: cancelled.error,
+                restored: restored.ok ? undefined : restored.error,
+              },
+            },
+          ),
+        );
+      }
+      hostCandidates.delete(record.candidate.candidateId);
+      scheduleCandidateCleanup(record);
+    }
+    return accepted;
+  };
+  const host: DynamicGeometryHostImplementation = {
     prepareDynamicGeometry(input) {
       const generation = synchronizeGeneration();
       const world = input.world as World;
@@ -464,182 +654,64 @@ export function createDynamicGeometryHost(options: {
       });
       return prepared;
     },
-    acceptDynamicGeometry(candidate, ordering) {
+    acceptDynamicGeometry: (candidate, ordering) => acceptCandidate(candidate, ordering),
+    acceptDynamicGeometryCandidates(candidates, ordering) {
       synchronizeGeneration();
-      const world = candidate.world as World;
-      const hostRecordById = hostCandidates.get(candidate.candidateId);
-      const hostRecord = candidateRecord(candidate);
-      if (hostRecord === undefined && hostRecordById !== undefined)
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-receipt-mismatch',
-            'admission uses the exact host candidate owner and lifecycle credential',
-            'discard the altered credential and use the value returned by preparation',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (hostRecord !== undefined && candidate.state !== 'prepared')
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-candidate-state',
-            'admission consumes a prepared candidate exactly once',
-            'retain the accepted or published candidate receipt instead of admitting it again',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (
-        ordering === undefined ||
-        !attachedWorlds.has(world) ||
-        ordering.world !== candidate.world
-      )
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-world-not-attached',
-            'candidate and fixed-step ordering belong to the same attached World',
-            'attach the World and submit its PhysicsWorld ordering before accepting geometry',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (!candidate.gpuReady)
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-gpu-not-ready',
-            'candidate has standard GPU residency before acceptance',
-            'prepare with an existing MeshAsset shared handle and repair residency failures',
-            { candidateId: candidate.candidateId },
-          ),
-        );
+      // The existing lifecycle's candidate budget bounds this group; there is
+      // no second queue or independently tunable batch allocation limit.
       if (
-        hostRecord === undefined ||
-        !hasRenderableBinding(world, candidate.entity) ||
-        !hasMaterialIdentity(world, candidate.entity, candidate.mesh, candidate.materialIdentity)
+        candidates.length === 0 ||
+        candidates.length > hostCandidates.size ||
+        new Set(candidates.map((candidate) => candidate.entity)).size !== candidates.length ||
+        candidates.some(
+          (candidate) =>
+            candidate.world !== ordering?.world || candidateRecord(candidate) === undefined,
+        )
       )
         return err(
           new DynamicGeometryError(
             'dynamic-geometry-invalid',
-            'the candidate is bound to a live ECS MeshFilter and MeshRenderer',
-            'keep the candidate MeshFilter binding intact until the consuming draw',
-            { candidateId: candidate.candidateId },
+            'a geometry group contains owned candidates for distinct entities in one World',
+            'prepare one candidate per entity and accept the nonempty group in its paired physics admission',
           ),
         );
-      if (meshHandleOf(world, candidate.entity) !== hostRecord.previousMeshHandle)
-        return err(
-          new DynamicGeometryError(
+      const accepted: DynamicGeometryCandidate[] = [];
+      const superseded = new Set<HostCandidateRecord>();
+      const rollback = (): void => {
+        const failures: DynamicGeometryError[] = [];
+        for (const candidate of [...accepted].reverse()) {
+          const result = host.cancelDynamicGeometry(candidate);
+          if (!result.ok) failures.push(result.error);
+        }
+        // A returned failure promises old state. A throw deliberately routes
+        // the paired PhysicsWorld into rebuild-required when that proof fails.
+        if (failures.length > 0)
+          throw new DynamicGeometryError(
             'dynamic-geometry-invalid',
-            'the old MeshFilter binding remains visible until candidate acceptance',
-            'do not replace the live ECS binding while geometry is prepared',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      const currentFixedStep = fixedStepOf(world);
-      if (
-        currentFixedStep === undefined ||
-        candidate.fixedStep === undefined ||
-        candidate.fixedStep > currentFixedStep ||
-        ordering.fixedStep !== currentFixedStep
-      )
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-ordering-required',
-            'ordering matches the current World tick, no earlier than preparation',
-            'accept a prepared candidate during the current fixed-step admission',
-            {
-              candidateId: candidate.candidateId,
-              actual: {
-                candidate: candidate.fixedStep,
-                currentFixedStep,
-                ordering: ordering.fixedStep,
-              },
-            },
-          ),
-        );
-      if (candidate.physicsEntity !== undefined) {
-        const publication = physicsPublicationOf(world, candidate.physicsEntity, true);
-        if (
-          publication === undefined ||
-          publication.fixedStep !== currentFixedStep ||
-          publication.revision !== candidate.revision
-        )
-          return err(
-            new DynamicGeometryError(
-              'dynamic-geometry-ordering-required',
-              'candidate physicsEntity has the active paired PhysicsWorld admission',
-              'accept geometry inside admitDerivedShapeCandidate commitGeometry, before physics step',
-              { candidateId: candidate.candidateId, actual: publication },
-            ),
+            'a failed geometry group restores every previous ECS binding',
+            'rebuild the paired World and Renderer before rendering or querying physics',
+            { actual: failures },
           );
+      };
+      for (const candidate of candidates) {
+        const result = acceptCandidate(candidate, ordering, superseded);
+        if (!result.ok) {
+          rollback();
+          return err(result.error);
+        }
+        accepted.push(result.value);
       }
-      // One ECS MeshFilter has one visible geometry owner.  Once this
-      // candidate is accepted, any older prepared/accepted candidate for the
-      // same entity can no longer become a receipt-bearing draw. Cancel it
-      // after the new ECS swap so its candidate-only residency is no longer
-      // protected as the live draw owner. Published candidates stay
-      // receipt-bound and are retired independently.
-      const superseded = [...hostCandidates.values()].filter(
-        (record) =>
-          record.candidate.candidateId !== candidate.candidateId &&
-          record.world === world &&
-          record.entity === candidate.entity &&
-          !record.published,
-      );
-      const accepted = lifecycle.accept(candidate, ordering);
-      if (!accepted.ok) return accepted;
-      const swapped = world.set(candidate.entity as EntityHandle, MeshFilter, {
-        assetHandle: hostRecord.meshHandle,
-      });
-      if (!swapped.ok) {
-        lifecycle.cancel(accepted.value);
-        hostCandidates.delete(candidate.candidateId);
-        cleanupCandidateResidency(hostRecord);
-        const released = releaseMeshLeases(hostRecord);
-        if (released !== undefined) return err(released);
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-invalid',
-            'the candidate MeshFilter swap commits through the ECS write barrier',
-            'restore the live entity and retry from a fresh candidate',
-            { candidateId: candidate.candidateId, actual: swapped.error },
-          ),
-        );
-      }
-      hostRecord.candidate = accepted.value;
-      hostRecord.accepted = true;
-      options.onTopologyChanged?.();
-      // Keep the World handle leased through the final GPU submission; its slot
-      // must not be reused while a retired frame still references the old mesh.
-      // Cleanup happens only after the new ECS MeshFilter is visible. Before
-      // the swap, hasMeshBinding intentionally protects the older candidate's
-      // GPU copy because it is still the live draw owner.
+      // Keep all previous unpublished credentials and leases until every ECS
+      // swap succeeds, so a kth-member rejection can still draw the old group.
       for (const record of superseded) {
         const completion = cleanupCandidateResidency(record);
-        const cancelled = lifecycle.cancel(record.candidate, completion);
-        if (!cancelled.ok && cancelled.error.code !== 'dynamic-geometry-candidate-not-found') {
-          const restored = world.set(candidate.entity as EntityHandle, MeshFilter, {
-            assetHandle: hostRecord.previousMeshHandle,
-          });
-          lifecycle.cancel(accepted.value);
-          hostCandidates.delete(candidate.candidateId);
-          cleanupCandidateResidency(hostRecord);
-          releasePreviousMeshLease(hostRecord);
-          return err(
-            new DynamicGeometryError(
-              'dynamic-geometry-invalid',
-              'candidate supersession cancels the prior credential atomically',
-              'keep the prior ECS binding and candidate lifecycle intact when supersession fails',
-              {
-                candidateId: candidate.candidateId,
-                actual: {
-                  cancelled: cancelled.error,
-                  restored: restored.ok ? undefined : restored.error,
-                },
-              },
-            ),
-          );
-        }
-        hostCandidates.delete(record.candidate.candidateId);
+        const result = lifecycle.cancel(record.candidate, completion);
+        if (!result.ok && result.error.code !== 'dynamic-geometry-candidate-not-found')
+          throw result.error;
         scheduleCandidateCleanup(record);
       }
-      return accepted;
+      options.onTopologyChanged?.();
+      return ok(Object.freeze(accepted));
     },
     dynamicGeometryReceipt(candidate) {
       synchronizeGeneration();
@@ -837,6 +909,7 @@ export function createDynamicGeometryHost(options: {
       return receipts;
     },
   };
+  return host;
 }
 
 /**

package/src/assembly/host-contract.ts

@@ -72,6 +72,15 @@ export interface RendererHostImplementation {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;