@forgeax/engine-render 0.1.2

package/src/__tests__/gpu-driven-production.integration.test.ts

@@ -0,0 +1,609 @@
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh, deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { createProfiler } from '@forgeax/engine-profiler';
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { Camera, MeshFilter, MeshRenderer } from '../components';
+import { constructRenderer } from '../construct-renderer';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import { GpuBuffer } from '../gpu-resource';
+import { GpuScene } from '../gpu-scene';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_UNIFORM,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import { Materials } from '../materials';
+import { makeZeroCameraFallbackSnapshot } from '../record';
+import {
+  buildRenderCandidateDomain,
+  type RenderCandidateDomain,
+} from '../render-dispatch-membership';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { RenderSceneProjection } from '../render-scene-projection';
+import type { MeshGpuHandles } from '../render-system';
+import type {
+  ExtractedFrame,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
+
+const EMPTY_RESOURCE_CLASS = JSON.stringify({ textures: [], samplers: [], video: [] });
+
+function snapshot(entityKey: number, assetHandle: number): RenderableSnapshot {
+  const material = {
+    baseColor: new Float32Array([0.25 * entityKey, 0.5, 0.75]),
+    metallic: 0,
+    roughness: 1,
+    materialShaderId: 'forgeax::default-unlit',
+  } as MaterialSnapshot;
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  return {
+    assetHandle,
+    transform: { world },
+    localAabb: new Float32Array([-0.25, -0.25, -0.25, 0.25, 0.25, 0.25]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        submeshIndex: 0,
+        passIndex: 0,
+        queue: 2000,
+        kind: 'indexed',
+        first: 0,
+        count: 3,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'forgeax::default-unlit|triangle-list|null',
+        materialResourceClass: EMPTY_RESOURCE_CLASS,
+      },
+    ],
+  };
+}
+
+function mesh(device: RhiNullDevice, indexed = true): MeshGpuHandles {
+  const vertex = device
+    .createBuffer({
+      size: 144,
+      usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const index = indexed
+    ? device
+        .createBuffer({
+          size: 8,
+          usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+        })
+        .unwrap()
+    : null;
+  return {
+    vertexBuffer: new GpuBuffer(device, vertex),
+    indexBuffer: index === null ? null : new GpuBuffer(device, index),
+    vboBytes: 144,
+    iboBytes: indexed ? 8 : 0,
+    indexCount: indexed ? 3 : 0,
+    indexFormat: 'uint16',
+    layoutProjection: deriveVertexLayoutProjection({
+      position: new Float32Array(9),
+      normal: new Float32Array(9),
+      uv: new Float32Array(6),
+      tangent: new Float32Array(12),
+    }),
+    vertexCount: 3,
+    indexed,
+    topology: 'triangle-list',
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 3,
+        materialSlot: 0,
+        topology: 'triangle-list',
+      },
+    ],
+  };
+}
+
+function candidateDomainFrame(domain: RenderCandidateDomain): ExtractedFrame {
+  return {
+    cameras: [],
+    lights: {
+      directional: undefined,
+      directionalCount: 0,
+      point: [],
+      spot: [],
+      lightViewProj: undefined,
+      splitPlanes: undefined,
+      cascadeCount: undefined,
+      cascadeBlend: undefined,
+      shadowMapSize: undefined,
+      depthBias: undefined,
+      normalBias: undefined,
+      pcfKernelSize: undefined,
+      pointShadow: [],
+      directionalCsmConfig: undefined,
+      directionalCsmDirection: undefined,
+    },
+    renderables: [...domain.renderables],
+    dispatch: [...domain.dispatch],
+    candidateRenderables: domain.renderables,
+    candidateDispatch: domain.dispatch,
+    candidateDispatchMembership: domain.membership,
+    candidateDomain: domain,
+    environment: { kind: 'none', worldId: 0, skylightCount: 0, skyboxCount: 0 },
+    frustumStats: { culled: 0, total: 0 },
+    visibilityStats: { explicitlyHidden: 0 },
+    postProcessParams: new Map(),
+    visibilitySnapshots: [],
+    featureVisibilitySnapshots: [],
+    hiddenEntityReports: [],
+  };
+}
+
+describe('GPU-driven production projection', () => {
+  it('joins compact candidate ownership by identity after projection removal', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const first = { ...snapshot(1, 3), candidateIndex: 0 };
+    const second = { ...snapshot(2, 3), candidateIndex: 1 };
+    const third = { ...snapshot(3, 3), candidateIndex: 2 };
+    const projection = new RenderSceneProjection();
+    const initialDelta = projection.apply([
+      { kind: 'create', snapshot: first },
+      { kind: 'create', snapshot: second },
+      { kind: 'create', snapshot: third },
+    ]);
+    const availability = GpuScene.create(device, 3).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    availability.scene.sync(projection, initialDelta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+
+    const firstRecord = projection.record(0, first.entityKey);
+    expect(firstRecord).toBeDefined();
+    const removalDelta = projection.apply([
+      {
+        kind: 'remove',
+        worldId: 0,
+        entityKey: first.entityKey,
+        ...(firstRecord === undefined ? {} : { expectedGeneration: firstRecord.generation }),
+      },
+    ]);
+    topology.apply(removalDelta);
+    availability.scene.sync(projection, removalDelta).unwrap();
+
+    const staleProjectionSnapshots = projection.materialize();
+    expect(staleProjectionSnapshots.map((candidate) => candidate.candidateIndex)).toEqual([1, 2]);
+    const compactCandidates = staleProjectionSnapshots.map((candidate, candidateIndex) => ({
+      ...candidate,
+      candidateIndex,
+    }));
+    const domain = buildRenderCandidateDomain(compactCandidates, []);
+    const production = new GpuDrivenProduction(device, {
+      createShaderModule: () => ok(shader),
+    });
+    const visibility = production.prepareCpuVisibility({
+      scene: {
+        scene: availability.scene,
+        plan: topology.plan(),
+        slots: projection.slotsSnapshot(),
+        projection,
+      },
+      frame: candidateDomainFrame(domain),
+      camera: undefined,
+    });
+    const main = visibility?.views.find((view) => view.viewId === 'main');
+    expect(main?.stableIds).toEqual([1, 2]);
+    expect(main?.compactVisible.map((item) => item.candidateIndex)).toEqual([0, 1]);
+
+    production.dispose();
+    availability.scene.dispose();
+  });
+
+  it('projects aligned multi-batch compute work into one indirect raster pass', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap() as RhiNullDevice;
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const viewLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 0x1, buffer: { type: 'uniform' } }],
+      })
+      .unwrap();
+    const viewUniform = device
+      .createBuffer({ size: 784, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
+      .unwrap();
+    const viewBindGroup = device
+      .createBindGroup({
+        layout: viewLayout,
+        entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: viewUniform } } }],
+      })
+      .unwrap();
+    const first = snapshot(1, 3);
+    const firstDraw = first.gpuDrivenDraws?.[0];
+    expect(firstDraw).toBeDefined();
+    if (firstDraw === undefined) return;
+    const second = snapshot(2, 4);
+    const secondDraw = second.gpuDrivenDraws?.[0];
+    expect(secondDraw).toBeDefined();
+    if (secondDraw === undefined) return;
+    const preparedMaterial = {
+      ...second.material,
+      materialHandle: 42,
+      renderState: { cullMode: 'none' as const, depthCompare: 'less-equal' as const },
+    };
+    const renderables = [
+      {
+        ...first,
+        gpuDrivenDraws: [
+          firstDraw,
+          { ...firstDraw, first: 3 },
+          { ...firstDraw, submeshIndex: 1, queue: 4000, first: 6 },
+        ],
+      },
+      {
+        ...second,
+        material: preparedMaterial,
+        materials: [preparedMaterial],
+        gpuDrivenDraws: [
+          {
+            ...secondDraw,
+            kind: 'non-indexed' as const,
+            pipelineClass:
+              'forgeax::default-unlit|triangle-list|{"cullMode":"none","depthCompare":"less-equal"}',
+          },
+        ],
+      },
+    ];
+    const projection = new RenderSceneProjection();
+    const delta = projection.apply(
+      renderables.map((renderable) => ({ kind: 'create' as const, snapshot: renderable })),
+    );
+    const availability = GpuScene.create(device, 2).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    availability.scene.sync(projection, delta).unwrap();
+    const topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    expect(topology.plan()).toMatchObject({
+      candidateCount: 4,
+      visibleCapacity: 193,
+      batches: [
+        { visibleBase: 0 },
+        { visibleBase: 64 },
+        { visibleBase: 128 },
+        { visibleBase: 192 },
+      ],
+    });
+    const production = new GpuDrivenProduction(device, {
+      createShaderModule: () => ok(shader),
+    });
+    const meshes = new Map([
+      [3, mesh(device)],
+      [4, mesh(device, false)],
+    ]);
+    const prepared = production
+      .prepare({
+        scene: {
+          scene: availability.scene,
+          plan: topology.plan(),
+          slots: projection.slotsSnapshot(),
+        },
+        camera: makeZeroCameraFallbackSnapshot(),
+        meshes,
+        viewBindGroupLayout: viewLayout,
+        meshResidencyEpoch: 1,
+        hdrp: false,
+      })
+      .unwrap();
+    expect(prepared).toBeDefined();
+    if (prepared === undefined) return;
+    expect([...prepared.ownedItemKeys]).toEqual(['0:1:0:0', '0:2:0:0']);
+    expect(production.inspect()).toMatchObject({
+      gpuOwnedSnapshotsMaterialized: 2,
+      filteredPlanBuilds: 1,
+      candidateUploadBytes: 84,
+      batchUploadBytes: 84,
+      viewBindGroupCreates: 1,
+    });
+
+    const stable = production
+      .prepare({
+        scene: {
+          scene: availability.scene,
+          plan: topology.plan(),
+          slots: projection.slotsSnapshot(),
+        },
+        camera: makeZeroCameraFallbackSnapshot(),
+        meshes,
+        viewBindGroupLayout: viewLayout,
+        meshResidencyEpoch: 1,
+        hdrp: false,
+      })
+      .unwrap();
+    expect(stable?.topologySignature).toBe(prepared.topologySignature);
+    expect(production.inspect()).toMatchObject({
+      gpuOwnedSnapshotsMaterialized: 0,
+      filteredPlanBuilds: 0,
+      candidateUploadBytes: 0,
+      batchUploadBytes: 0,
+      viewConstantsUploadBytes: 112,
+      viewBindGroupCreates: 0,
+      batchBindGroupCreates: 0,
+    });
+
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const gpu = prepared.project(graph, 'rgba8unorm', 1).unwrap();
+    const color = graph
+      .createTexture('gpu-driven-production-color', {
+        format: 'rgba8unorm',
+        size: { width: 1, height: 1 },
+      })
+      .unwrap();
+    const colorView = graph.view(color).unwrap();
+    graph
+      .addRasterPass('main', {
+        accesses: [...gpu.accesses, { resource: colorView, usage: 'color-attachment' }],
+        colorAttachments: [
+          {
+            view: colorView,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          },
+        ],
+        encode: ({ pass, resources }) => gpu.encode(viewBindGroup, pass, resources),
+      })
+      .unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes.at(-1)).toMatchObject({
+      name: 'main',
+      dependencies: ['gpu-driven.frustum-compact', 'gpu-driven.finalize-indirect'],
+    });
+    const encoder = device.createCommandEncoder({ label: 'gpu-driven-production' }).unwrap();
+    compiled.execute({ viewBindGroup, encoder } as RenderPipelineFrame).unwrap();
+    encoder.finish().unwrap();
+    expect(device.framePassNames).toEqual([
+      'gpu-driven.view-reset',
+      'gpu-driven.frustum-compact',
+      'gpu-driven.finalize-indirect',
+      'main',
+    ]);
+    expect(device.totalDispatchCount).toBe(3);
+    expect(device.totalDrawCount).toBe(3);
+
+    const replacement = GpuScene.create(device, 2).unwrap();
+    expect(replacement.status).toBe('available');
+    if (replacement.status !== 'available') return;
+    replacement.scene.sync(projection, delta).unwrap();
+    const replacementPrepared = production
+      .prepare({
+        scene: {
+          scene: replacement.scene,
+          plan: topology.plan(),
+          slots: projection.slotsSnapshot(),
+        },
+        camera: makeZeroCameraFallbackSnapshot(),
+        meshes,
+        viewBindGroupLayout: viewLayout,
+        meshResidencyEpoch: 1,
+        hdrp: false,
+      })
+      .unwrap();
+    expect(replacementPrepared?.topologySignature).not.toBe(prepared.topologySignature);
+
+    production.dispose();
+    replacement.scene.dispose();
+    availability.scene.dispose();
+  });
+
+  it('keeps an overlay material on the CPU while Geometry stays GPU-driven', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(
+      JSON.stringify({
+        schemaVersion: '1.0.0',
+        entries: [
+          { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
+          { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+          { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
+        ],
+      }),
+    )}`;
+    const canvas = {
+      width: 1,
+      height: 1,
+      getContext: () => null,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    const profiler = createProfiler();
+    const renderer = await constructRenderer(
+      canvas,
+      { profiler, rhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect((await renderer.ready).ok).toBe(true);
+    const world = new World();
+    const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+    expect(renderer.attachWorld(world).ok).toBe(true);
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+    const overlayMaterial = world.allocSharedRef(
+      'MaterialAsset',
+      Materials.unlit([1, 0, 0, 1], {
+        castShadow: false,
+        queue: 4000,
+        renderState: { depthCompare: 'always', depthWriteEnabled: false },
+      }),
+    );
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshRenderer, data: { materials: [overlayMaterial] } },
+      )
+      .unwrap();
+
+    for (let frame = 0; frame < 4; frame += 1) {
+      world.update(1 / 60).unwrap();
+      expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+      await Promise.resolve();
+    }
+    const device = renderer.device as RhiNullDevice;
+    device.totalDrawCount = 0;
+    const captureResult = profiler.startCapture({
+      frameLimit: 1,
+      eventLimit: 128,
+      detail: 'passes',
+    });
+    expect(captureResult.ok).toBe(true);
+    if (!captureResult.ok) throw new Error(captureResult.error.code);
+    world.update(1 / 60).unwrap();
+    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
+    const artifactResult = captureResult.value.finish();
+    expect(artifactResult.ok).toBe(true);
+    if (!artifactResult.ok) throw new Error(artifactResult.error.code);
+    const artifact = artifactResult.value;
+    expect(renderer.perFramePassNames).toEqual(
+      expect.arrayContaining([
+        'gpu-driven.view-reset',
+        'gpu-driven.frustum-compact',
+        'gpu-driven.finalize-indirect',
+        'main',
+      ]),
+    );
+    expect(device.totalDrawCount).toBe(2);
+    expect(artifact.records).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'phase',
+          source: 'render',
+          phase: 'record/graph-execute/forward/geometry-loop',
+        }),
+      ]),
+    );
+    expect(renderer.renderScene).toMatchObject({
+      worldEntitiesScanned: 0,
+      projectionRecords: 2,
+      topology: { batchCount: 2, candidateCount: 2 },
+      gpu: { status: 'resident' },
+      gpuDriven: {
+        gpuOwnedSnapshotsMaterialized: 0,
+        filteredPlanBuilds: 0,
+        candidateUploadBytes: 0,
+        batchUploadBytes: 0,
+        batchBindGroupCreates: 0,
+        viewBindGroupCreates: 0,
+        validatedGpuOwnedRows: 0,
+        cpuFallbackDrawItems: 1,
+      },
+    });
+    renderer.dispose();
+  });
+
+  it('keeps a stable multi-World composition resident and patches one World transform', async () => {
+    const manifest = `data:application/json,${encodeURIComponent(
+      JSON.stringify({
+        schemaVersion: '1.0.0',
+        entries: [
+          { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
+          { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+          { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
+        ],
+      }),
+    )}`;
+    const canvas = {
+      width: 1,
+      height: 1,
+      getContext: () => null,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    const renderer = await constructRenderer(canvas, { rhi }, { shaderManifestUrl: manifest });
+    expect((await renderer.ready).ok).toBe(true);
+    const cameraWorld = new World();
+    const sceneWorld = new World();
+    const cubeHandle = sceneWorld.internSharedRef(
+      'MeshAsset',
+      createPrimitiveMesh('cube').unwrap(),
+    );
+    expect(renderer.attachWorld(cameraWorld).ok).toBe(true);
+    expect(renderer.attachWorld(sceneWorld).ok).toBe(true);
+    cameraWorld
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 5] } },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+    const rendered = sceneWorld
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+
+    for (let frame = 0; frame < 4; frame += 1) {
+      cameraWorld.update(1 / 60).unwrap();
+      sceneWorld.update(1 / 60).unwrap();
+      expect(
+        renderer.draw([cameraWorld, sceneWorld], { cameraOwner: 0, resourceOwner: 0 }).ok,
+      ).toBe(true);
+      await Promise.resolve();
+    }
+    expect(renderer.renderScene).toMatchObject({
+      worldEntitiesScanned: 0,
+      projectionRecords: 1,
+      topology: { batchCount: 1, candidateCount: 1 },
+      gpu: { status: 'resident' },
+      gpuDriven: { cpuFallbackDrawItems: 0, validatedGpuOwnedRows: 0 },
+    });
+    const sceneWorldId = renderer.meshMaterialBindings[0]?.worldId;
+    expect(sceneWorldId).toBeDefined();
+
+    cameraWorld.update(1 / 60).unwrap();
+    sceneWorld.update(1 / 60).unwrap();
+    expect(renderer.draw([sceneWorld, cameraWorld], { cameraOwner: 1, resourceOwner: 1 }).ok).toBe(
+      true,
+    );
+    expect(renderer.meshMaterialBindings[0]?.worldId).toBe(sceneWorldId);
+
+    sceneWorld.set(rendered, Transform, { pos: [1, 0, 0] }).unwrap();
+    cameraWorld.update(1 / 60).unwrap();
+    sceneWorld.update(1 / 60).unwrap();
+    expect(renderer.draw([sceneWorld, cameraWorld], { cameraOwner: 1, resourceOwner: 1 }).ok).toBe(
+      true,
+    );
+    expect(renderer.renderScene).toMatchObject({
+      worldEntitiesScanned: 0,
+      fullRebuilds: 2,
+      transformUpdates: 1,
+      projectionRecords: 1,
+    });
+    renderer.dispose();
+  });
+});

package/src/__tests__/gpu-driven-scaling.unit.test.ts

@@ -0,0 +1,90 @@
+import { mat4 } from '@forgeax/engine-math';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { BatchTopology } from '../gpu-driven/batch-topology';
+import { RenderSceneProjection } from '../render-scene-projection';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+
+const ENTITY_COUNT = 100_000;
+const material = {
+  baseColor: new Float32Array([0.25, 0.5, 0.75]),
+  metallic: 0,
+  roughness: 1,
+  materialShaderId: 'forgeax::default-unlit',
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number): RenderableSnapshot {
+  return {
+    assetHandle: 1,
+    transform: { world: new Float32Array(mat4.identity(mat4.create())) },
+    localAabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+    gpuDrivenDraws: [
+      {
+        submeshIndex: 0,
+        passIndex: 0,
+        queue: 2000,
+        kind: 'indexed',
+        first: 0,
+        count: 36,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'forgeax::default-unlit|triangle-list|null',
+        materialResourceClass: '{"textures":[],"samplers":[],"video":[]}',
+      },
+    ],
+  };
+}
+
+describe('GPU-driven scaling contract', () => {
+  let projection: RenderSceneProjection;
+  let topology: BatchTopology;
+  let materialized: readonly RenderableSnapshot[];
+  let stablePlan: ReturnType<BatchTopology['plan']>;
+  let stableMaterializationReused = false;
+  let stablePlanReused = false;
+  let delta: ReturnType<RenderSceneProjection['apply']>;
+  let topologyChanged = true;
+
+  beforeAll(() => {
+    projection = new RenderSceneProjection();
+    projection.reset(Array.from({ length: ENTITY_COUNT }, (_, index) => snapshot(index)));
+    materialized = projection.materialize();
+    topology = new BatchTopology();
+    topology.rebuild(projection.slotsSnapshot());
+    stablePlan = topology.plan();
+    stableMaterializationReused = projection.materialize() === materialized;
+    stablePlanReused = topology.plan() === stablePlan;
+
+    const moved = mat4.identity(mat4.create());
+    moved[12] = 3;
+    delta = projection.apply([
+      { kind: 'update-transform', worldId: 0, entityKey: 50_000, world: moved },
+    ]);
+    topologyChanged = topology.apply(delta);
+  });
+
+  it('projects 100k candidates into one capacity-exact batch', () => {
+    expect(stablePlan).toMatchObject({
+      candidateCount: ENTITY_COUNT,
+      visibleCapacity: ENTITY_COUNT,
+      batches: [{ visibleCapacity: ENTITY_COUNT }],
+    });
+  });
+
+  it('reuses materialization and topology identities while static', () => {
+    expect(stableMaterializationReused).toBe(true);
+    expect(stablePlanReused).toBe(true);
+  });
+
+  it('patches one transform without rebuilding topology', () => {
+    expect(delta).toMatchObject({ updated: 1, created: 0, removed: 0 });
+    expect(topologyChanged).toBe(false);
+    expect(topology.plan()).toBe(stablePlan);
+    expect(topology.inspect()).toMatchObject({ patches: 0, candidateCount: ENTITY_COUNT });
+  });
+});