@forgeax/engine-render 0.1.26 → 0.1.28

package/src/assembly/host-contract.ts

@@ -2,6 +2,13 @@ import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
 import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
 import type { RenderPipelineAsset } from '@forgeax/engine-types';
+import type {
+  DynamicGeometryCandidate,
+  DynamicGeometryError,
+  DynamicGeometryOrdering,
+  DynamicGeometryPrepareInput,
+  DynamicGeometryReceipt,
+} from '../dynamic-geometry';
 import type { RecoverFailure } from '../errors/recover';
 import type { ObservationUnavailableError, RenderError } from '../errors/render';
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
@@ -54,6 +61,25 @@ export type RendererHostEventListener = (event: RendererHostEvent) => void;
  */
 export interface RendererHostImplementation {
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
+  prepareDynamicGeometry(
+    input: DynamicGeometryPrepareInput,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  acceptDynamicGeometry(
+    candidate: DynamicGeometryCandidate,
+    ordering: DynamicGeometryOrdering,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
+  cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
+  retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
+  publishDynamicGeometry(
+    frame: {
+      readonly frameId: number;
+      readonly deviceGeneration: number;
+      readonly completed?: Promise<unknown>;
+    },
+    worlds?: readonly object[],
+    fixedStep?: number,
+  ): readonly DynamicGeometryReceipt[];
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
   resizeRenderTarget(
     target: RenderTarget,

package/src/assembly/renderer-facade.ts

@@ -3,6 +3,11 @@
 // lease/receipt contract and owns the profile/error projection helpers.
 
 import { err, ok, type RhiError } from '@forgeax/engine-rhi';
+import type {
+  DynamicGeometryCandidate,
+  DynamicGeometryOrdering,
+  DynamicGeometryPrepareInput,
+} from '../dynamic-geometry';
 import { type RecoverFailure, RecoveryFailedError } from '../errors/recover';
 import {
   type RenderError,
@@ -94,6 +99,18 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
             }),
           );
     },
+    prepareDynamicGeometry: (input: DynamicGeometryPrepareInput) =>
+      renderer.prepareDynamicGeometry(input),
+    acceptDynamicGeometry: (
+      candidate: DynamicGeometryCandidate,
+      ordering: DynamicGeometryOrdering,
+    ) => renderer.acceptDynamicGeometry(candidate, ordering),
+    dynamicGeometryReceipt: (candidate: DynamicGeometryCandidate) =>
+      renderer.dynamicGeometryReceipt(candidate),
+    cancelDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
+      renderer.cancelDynamicGeometry(candidate),
+    retireDynamicGeometry: (candidate: DynamicGeometryCandidate) =>
+      renderer.retireDynamicGeometry(candidate),
     createRenderTarget: (descriptor) => renderer.createRenderTarget(descriptor),
     resizeRenderTarget: (target, descriptor) => renderer.resizeRenderTarget(target, descriptor),
     createRenderTargetTextureSource: (target, options) =>

package/src/assembly/webgpu-renderer.ts

@@ -57,6 +57,7 @@ import type {
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { createDynamicGeometryLifecycle } from '../dynamic-geometry';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
 
@@ -165,6 +166,7 @@ import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 import type { RhiBackendPack } from './backend-contract';
 import type { BundlerOptions } from './bundler-contract';
 import { deviceOptionsForAdapter } from './device-feature-admission';
+import { createDynamicGeometryHost } from './dynamic-geometry-host';
 import type { RendererAssemblyImplementation } from './host-contract';
 import {
   allowsUnlitPreparedFallback,
@@ -1109,6 +1111,7 @@ async function makeWebGPURenderer(
   const publishRendererGeneration = (candidate: RendererGeneration): void => {
     publishGeneration(generationPublication, candidate, (value) => value.scope.isAlive());
     activeDeviceScope = candidate.scope;
+    dynamicGeometry.invalidateGeneration(activeDeviceScope.generation);
     internals.generationState.current = activeDeviceScope.generation;
     pipelineState = candidate.pipeline;
     const bindings = candidate.producerBindings;
@@ -2023,6 +2026,7 @@ async function makeWebGPURenderer(
     const fragmentEntry =
       authoredFragmentEntry ??
       (isHdr &&
+      passKind === 'forward' &&
       (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
         ? 'fs_main_hdr'
         : undefined);
@@ -2805,6 +2809,20 @@ async function makeWebGPURenderer(
   const attachedWorlds = new Set<World>();
   const attachedLeases = new Map<RenderReadLease, World>();
   const leasesByWorld = new Map<World, RenderReadLease>();
+  const dynamicGeometry = createDynamicGeometryLifecycle();
+  const dynamicGeometryHost = createDynamicGeometryHost({
+    lifecycle: dynamicGeometry,
+    attachedWorlds,
+    getGpuStore: () => gpuStore,
+    currentGeneration: () => activeDeviceScope.generation,
+    onTopologyChanged: () => renderSystem.invalidateGeometryHistory(),
+    isConsumedByRenderFrame: (candidate) =>
+      renderSystem.isDynamicGeometryConsumed(
+        candidate.world as World,
+        candidate.entity ?? -1,
+        candidate.meshHandle,
+      ),
+  });
   const derivedSystemNames = new Map<World, string>();
   const transformReleases = new Map<World, () => void>();
   const attachmentOwner = {};
@@ -2817,7 +2835,6 @@ async function makeWebGPURenderer(
   const receiptTimings = new WeakMap<FrameReceipt, Promise<VolumeTimingObservation>>();
   let latestReceipt: FrameReceipt | undefined;
   let surfaceReleased = false;
-
   const renderer: RendererAssemblyImplementation = {
     attach(world: World): RenderResult<RenderWorldLease, RenderError> {
       const attached = this.attachScene(world);
@@ -2829,6 +2846,7 @@ async function makeWebGPURenderer(
       leasesByWorld.set(world, lease);
       return ok(lease);
     },
+    ...dynamicGeometryHost,
     createRenderTarget: (descriptor) => renderTargetHost.createRenderTarget(descriptor),
     resizeRenderTarget: (target, descriptor) =>
       renderTargetHost.resizeRenderTarget(target, descriptor),
@@ -2949,6 +2967,7 @@ async function makeWebGPURenderer(
             }),
           ),
         ),
+        dynamicGeometry: dynamicGeometry.inspect(),
         renderScene: renderSystem.renderScene,
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,
@@ -3092,6 +3111,7 @@ async function makeWebGPURenderer(
     },
     detachScene(world: World): void {
       if (!attachedWorlds.delete(world)) return;
+      dynamicGeometryHost.invalidateDynamicGeometryWorld(world);
       for (const [lease, leaseWorld] of attachedLeases) {
         if (leaseWorld === world) {
           lease.dispose();
@@ -3293,6 +3313,27 @@ async function makeWebGPURenderer(
           : worlds.map((world) => leasesByWorld.get(world)).every((lease) => lease !== undefined)
             ? worlds.map((world) => leasesByWorld.get(world) as RenderReadLease)
             : undefined;
+      for (const world of worlds) {
+        if (!world.hasResource('PhysicsWorld')) continue;
+        const physics = world.getResource<{
+          readonly getDerivedAdmission?: () => unknown;
+          readonly getDerivedRecoveryState?: () => string;
+        }>('PhysicsWorld');
+        if (
+          physics?.getDerivedAdmission?.() !== undefined ||
+          physics?.getDerivedRecoveryState?.() === 'rebuild-required'
+        ) {
+          return err(
+            new RendererOperationError('frame-input-invalid', {
+              operation: 'draw',
+              cause: new RendererContractFailureError(
+                'draw',
+                'paired geometry admission must finish physics step and writeback in a healthy World before draw',
+              ),
+            }),
+          );
+        }
+      }
       if (frameRequest !== undefined && worlds.length !== frameRequest.leases.length) {
         return err(
           new RendererOperationError('world-lease-invalid', {
@@ -3479,6 +3520,8 @@ async function makeWebGPURenderer(
         const timingCompletion = timingHost.gpuPassTimingSubmittedWork;
         timingHost.gpuPassTimingSubmittedWork = undefined;
         const reflectionFallbackCompletion = renderSystem.reflectionFallbackCompletion;
+        const queueCompletion = timingCompletion ?? internals.device.queue.onSubmittedWorkDone();
+        gpuStore.trackMeshSubmission(queueCompletion);
         internals.pack.instrumentation?.onFrameBoundary?.();
         if (!isFrameRequest) {
           renderTargetHost.onFrameSubmitted();
@@ -3486,7 +3529,6 @@ async function makeWebGPURenderer(
         }
         const receiptFrameId = ++frameId;
         const receiptGeneration = activeDeviceScope.generation;
-        const queueCompletion = timingCompletion ?? internals.device.queue.onSubmittedWorkDone();
         const completion: FrameReceipt['completed'] = Promise.all([
           queueCompletion,
           reflectionFallbackCompletion ?? Promise.resolve(),
@@ -3608,6 +3650,7 @@ async function makeWebGPURenderer(
           );
         }
         issuedReceipts.add(receipt);
+        dynamicGeometryHost.publishDynamicGeometry(receipt, worlds, frameRequest?.fixedStep);
         return ok(receipt);
       } catch (cause) {
         const error =
@@ -3756,6 +3799,10 @@ async function makeWebGPURenderer(
     dispose(): RenderResult<void, RenderError> {
       if (disposed) return ok(undefined);
       disposed = true;
+      for (const world of attachedWorlds) {
+        dynamicGeometryHost.invalidateDynamicGeometryWorld(world);
+      }
+      dynamicGeometry.dispose();
       for (const continuation of frameContinuations) {
         continuation.terminate({ code: 'disposed' });
       }

package/src/components/sprite-animation.ts

@@ -53,7 +53,7 @@
 //
 // 4-step recipe (charter F1 progressive disclosure — minimum walk-cycle
 // host code; full demo lands in M6 hello-sprite-atlas):
-//   1. Build atlas via `forgeax-engine-remote-asset atlas --input <glob> --name <prefix> --output <dir>`
+//   1. Build atlas via `forgeax asset atlas --input <glob> --name <prefix> --output <dir> --root <project>`
 //      (M5 build-time hook); load the emitted `<name>.atlas.png` plus
 //      `<name>.atlas.meta.json` sidecar.
 //   2. Register the sprite material referencing the atlas

package/src/device/gpu-residency.ts

@@ -1,3 +1,4 @@
+import { type MeshResidencyLease, MeshResidencyLifetime } from './mesh-residency-lifetime';
 // @forgeax/engine-runtime - GpuResidencyCache
 // (feat-20260601-device/gpu-residency-extraction M1; M2 added the deriveRenderData
 // projection seam — see render-data.ts).
@@ -557,6 +558,36 @@ export class GpuResidencyCache {
   // equirect source always resolves to the same cubemap (idempotent, A2).
   private readonly cubemapIdempotentMap: Map<number, Handle<'EquirectAsset', 'shared'>> = new Map();
   private readonly meshGpuHandles: Map<string | number, MeshGpuHandles> = new Map();
+  private readonly meshLifetimes = new WeakMap<MeshGpuHandles, MeshResidencyLifetime>();
+  private readonly retiredMeshes = new Set<MeshGpuHandles>();
+
+  private meshLifetime(entry: MeshGpuHandles): MeshResidencyLifetime {
+    let lifetime = this.meshLifetimes.get(entry);
+    if (lifetime === undefined) {
+      lifetime = new MeshResidencyLifetime(() => {
+        if (!entry.vertexBuffer.isDestroyed) entry.vertexBuffer.destroy();
+        if (entry.indexBuffer !== null && !entry.indexBuffer.isDestroyed)
+          entry.indexBuffer.destroy();
+        this.retiredMeshes.delete(entry);
+      });
+      this.meshLifetimes.set(entry, lifetime);
+    }
+    return lifetime;
+  }
+
+  /** All resident entries conservatively cover main, shadow and cached GPU-driven draws. */
+  trackMeshSubmission(completed: Promise<unknown>): void {
+    for (const entry of this.meshGpuHandles.values()) this.meshLifetime(entry).track(completed);
+  }
+
+  private retireMeshEntry(key: string | number, entry: MeshGpuHandles): void {
+    if (this.meshGpuHandles.get(key) === entry) {
+      this.meshGpuHandles.delete(key);
+      this.meshResidencyEpoch += 1;
+    }
+    this.retiredMeshes.add(entry);
+    this.meshLifetime(entry).retire();
+  }
 
   /**
    * Compose a cache key from the raw handle slot and its owning World. The
@@ -711,11 +742,12 @@ export class GpuResidencyCache {
     this.cubemapGpuHandles.clear();
     this.cubemapIdempotentMap.clear();
 
-    for (const entry of this.meshGpuHandles.values()) {
+    for (const entry of [...this.meshGpuHandles.values(), ...this.retiredMeshes]) {
       destroyBuf(entry.vertexBuffer);
       if (entry.indexBuffer !== null) destroyBuf(entry.indexBuffer);
     }
     this.meshGpuHandles.clear();
+    this.retiredMeshes.clear();
   }
 
   /** Number of candidate-owned GPU resources currently held by this cache. */
@@ -730,6 +762,7 @@ export class GpuResidencyCache {
     }
     return (
       this.meshGpuHandles.size +
+      this.retiredMeshes.size +
       this.textureGpuHandles.size +
       this.samplerGpuHandles.size +
       cubemapResources
@@ -802,27 +835,13 @@ export class GpuResidencyCache {
     const entry = this.meshGpuHandles.get(id);
     if (entry === undefined) return { freed: 0, errors: [] };
 
-    let freed = 0;
-    const errors: RhiError[] = [];
-
-    const destroyBuf = (gpuBuf: GpuBuffer): void => {
-      if (!gpuBuf.isDestroyed) {
-        const r = gpuBuf.destroy();
-        if (r.ok) {
-          freed += 1;
-        } else {
-          errors.push(r.error);
-          if (this.errorRegistry) this.errorRegistry.fire(r.error);
-        }
-      }
+    if (this.meshLifetime(entry).owners > 0) return { freed: 0, errors: [] };
+    this.retireMeshEntry(id, entry);
+    return {
+      freed:
+        Number(entry.vertexBuffer.isDestroyed) + Number(entry.indexBuffer?.isDestroyed ?? false),
+      errors: [],
     };
-
-    destroyBuf(entry.vertexBuffer);
-    if (entry.indexBuffer !== null) destroyBuf(entry.indexBuffer);
-
-    this.meshGpuHandles.delete(id);
-    this.meshResidencyEpoch += 1;
-    return { freed: freed > 0 ? 1 : 0, errors };
   }
 
   evictCubemap(id: number): { freed: number; errors: RhiError[] } {
@@ -862,7 +881,6 @@ export class GpuResidencyCache {
   releaseUnreferenced(liveSet: Set<number>): { freed: number; errors: RhiError[] } {
     let freed = 0;
     const errors: RhiError[] = [];
-    let meshResidencyChanged = false;
     let materialResidencyChanged = false;
     const liveSlots = new Set([...liveSet].map((slot) => String(slot)));
     const isLiveKey = (key: string | number): boolean => {
@@ -916,35 +934,14 @@ export class GpuResidencyCache {
       }
     }
 
-    for (const key of this.meshGpuHandles.keys()) {
-      if (!isLiveKey(key)) {
-        const entry = this.meshGpuHandles.get(key);
-        if (entry !== undefined) {
-          if (!entry.vertexBuffer.isDestroyed) {
-            const r = entry.vertexBuffer.destroy();
-            if (r.ok) {
-              freed += 1;
-            } else {
-              errors.push(r.error);
-              if (this.errorRegistry) this.errorRegistry.fire(r.error);
-            }
-          }
-          if (entry.indexBuffer !== null && !entry.indexBuffer.isDestroyed) {
-            const r = entry.indexBuffer.destroy();
-            if (r.ok) {
-              freed += 1;
-            } else {
-              errors.push(r.error);
-              if (this.errorRegistry) this.errorRegistry.fire(r.error);
-            }
-          }
-          this.meshGpuHandles.delete(key);
-          meshResidencyChanged = true;
-        }
+    for (const [key, entry] of this.meshGpuHandles) {
+      if (!isLiveKey(key) && this.meshLifetime(entry).owners === 0) {
+        this.retireMeshEntry(key, entry);
+        freed +=
+          Number(entry.vertexBuffer.isDestroyed) + Number(entry.indexBuffer?.isDestroyed ?? false);
       }
     }
 
-    if (meshResidencyChanged) this.meshResidencyEpoch += 1;
     if (materialResidencyChanged) this.materialResourceEpoch += 1;
 
     return { freed, errors };
@@ -1096,23 +1093,26 @@ export class GpuResidencyCache {
     return this.meshGpuHandles.get(this.worldKey(handleSlot(handle), worldId));
   }
 
-  /**
-   * Drop one mutable shared mesh's GPU copy after ECS publishes `markChanged`.
-   * The next record pass resolves the same POD and rebuilds residency through
-   * the normal pull path, so ECS remains the payload authority.
-   */
+  /** Candidate leases retain the concrete allocation even after cache invalidation. */
+  retainMeshResidency(
+    handle: Handle<'MeshAsset', 'shared'>,
+    worldId: World | number = 0,
+  ): MeshResidencyLease | undefined {
+    const key = this.worldKey(handleSlot(handle), worldId);
+    const entry = this.meshGpuHandles.get(key);
+    return entry === undefined
+      ? undefined
+      : this.meshLifetime(entry).retain(() => {
+          if (this.meshGpuHandles.get(key) === entry) this.invalidateMesh(handle, worldId);
+          else this.meshLifetime(entry).retire();
+        });
+  }
+
+  /** In-place author changes immediately miss the cache; old submissions keep their allocation. */
   invalidateMesh(handle: number, worldId: World | number = 0): void {
-    // SharedRefMutation publishes the encoded handle value, while the cache
-    // key is derived from the decoded slot. Keep the invalidation path aligned
-    // with getMeshGpuHandles/ensureResident so an in-place ECS payload change
-    // cannot leave the old VBO resident.
     const key = this.worldKey(handleSlot(toShared<'MeshAsset'>(handle)), worldId);
     const entry = this.meshGpuHandles.get(key);
-    if (entry === undefined) return;
-    entry.vertexBuffer.destroy();
-    if (entry.indexBuffer !== null) entry.indexBuffer.destroy();
-    this.meshGpuHandles.delete(key);
-    this.meshResidencyEpoch += 1;
+    if (entry !== undefined) this.retireMeshEntry(key, entry);
   }
 
   /**

package/src/device/mesh-residency-lifetime.ts

@@ -0,0 +1,73 @@
+/** A lease captures one GPU allocation, never a reusable World handle slot. */
+export interface MeshResidencyLease {
+  track(completed: Promise<unknown>): void;
+  release(evict: boolean): Promise<void> | undefined;
+}
+
+/** Shared candidates and queue submissions have one allocation lifetime owner. */
+export class MeshResidencyLifetime {
+  private leases = 0;
+  private retired = false;
+  private eviction: (() => void) | undefined;
+  private readonly submissions = new Set<Promise<unknown>>();
+  private readonly waiters = new Set<() => void>();
+
+  constructor(private destroy: (() => void) | undefined) {}
+
+  get owners(): number {
+    return this.leases;
+  }
+
+  retain(evict: () => void): MeshResidencyLease {
+    this.leases += 1;
+    this.eviction = undefined;
+    let released = false;
+    let completion: Promise<void> | undefined;
+    return {
+      track: (submitted) => this.track(submitted),
+      release: (shouldEvict) => {
+        if (released) return completion;
+        released = true;
+        this.leases -= 1;
+        if (this.leases === 0 && shouldEvict) this.eviction = evict;
+        completion =
+          this.submissions.size === 0
+            ? undefined
+            : new Promise<void>((resolve) => this.waiters.add(resolve));
+        this.flush();
+        return completion;
+      },
+    };
+  }
+
+  track(completed: Promise<unknown>): void {
+    if (this.submissions.has(completed)) return;
+    this.submissions.add(completed);
+    const finish = (): void => {
+      this.submissions.delete(completed);
+      this.flush();
+    };
+    void completed.then(finish, finish);
+  }
+
+  retire(): void {
+    this.retired = true;
+    this.flush();
+  }
+
+  private flush(): void {
+    if (this.submissions.size !== 0) return;
+    if (this.leases === 0 && this.eviction !== undefined) {
+      const evict = this.eviction;
+      this.eviction = undefined;
+      evict();
+    }
+    if (this.retired && this.leases === 0 && this.destroy !== undefined) {
+      const destroy = this.destroy;
+      this.destroy = undefined;
+      destroy();
+    }
+    for (const resolve of this.waiters) resolve();
+    this.waiters.clear();
+  }
+}