@forgeax/engine-render 0.1.6 → 0.1.7

package/src/points-lines/prepare.ts

@@ -0,0 +1,177 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PointsLinesPrepareFailedError } from '../errors/render';
+import type { PointsLinesExpandedGeometry, PointsLinesExpansionCache } from './expansion-cache';
+import {
+  createPointsLinesLaneContract,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+  type PointsLinesLaneContract,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export interface PointsLinesGpuResourceAdapter<Resource> {
+  create(geometry: PointsLinesExpandedGeometry): Result<Resource, Error>;
+  upload(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<number, Error>;
+  validate(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<void, Error>;
+  destroy(resource: Resource): void;
+}
+
+export interface PointsLinesPreparedResource<Resource> {
+  readonly resource: Resource;
+  readonly geometry: PointsLinesExpandedGeometry;
+  readonly snapshot: PointsLinesRetainedSnapshot;
+  readonly uploadedBytes: number;
+  readonly lastKnownGood: true;
+}
+
+export interface PointsLinesPreparationOptions<Resource> {
+  readonly cache: PointsLinesExpansionCache;
+  readonly adapter: PointsLinesGpuResourceAdapter<Resource>;
+}
+
+export interface PointsLinesLanePreparationAdapter<Resource> {
+  readonly contract: PointsLinesLaneContract;
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
+  resetForDeviceLoss(): void;
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
+  inspect(): PointsLinesPreparationInspection<Resource>;
+}
+
+export interface PointsLinesPreparationInspection<Resource> {
+  readonly status: 'empty' | 'resident' | 'rebuild-pending';
+  readonly lastKnownGood: boolean;
+  readonly liveResource: Resource | undefined;
+  readonly liveBytes: number;
+  readonly candidateBytes: number;
+  readonly cacheEntries: number;
+  readonly uploads: number;
+  readonly rebuilds: number;
+  readonly failures: number;
+}
+
+/**
+ * Owns one atomic candidate/LKG pair for a Points/Lines render projection.
+ * GPU resources are supplied by the existing DeviceScope adapter; this class
+ * keeps no backend handle or second resource ledger.
+ */
+export class PointsLinesPreparation<Resource> {
+  private live: PointsLinesPreparedResource<Resource> | undefined;
+  private pendingCandidateBytes = 0;
+  private status: 'empty' | 'resident' | 'rebuild-pending' = 'empty';
+  private uploads = 0;
+  private rebuilds = 0;
+  private failures = 0;
+
+  constructor(private readonly options: PointsLinesPreparationOptions<Resource>) {}
+
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError> {
+    const geometry = this.options.cache.getOrCreate(snapshot, mesh);
+    if (this.live?.geometry.key === geometry.key) {
+      this.live = {
+        ...this.live,
+        snapshot,
+        uploadedBytes: 0,
+      };
+      this.status = 'resident';
+      return ok(this.live);
+    }
+
+    this.pendingCandidateBytes = geometry.derivedBytes;
+    const created = this.options.adapter.create(geometry);
+    if (!created.ok) return this.fail(snapshot, created.error);
+    const candidate = created.value;
+    const uploaded = this.options.adapter.upload(candidate, geometry);
+    if (!uploaded.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, uploaded.error);
+    }
+    this.uploads += 1;
+    const validated = this.options.adapter.validate(candidate, geometry);
+    if (!validated.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, validated.error);
+    }
+
+    const previous = this.live;
+    this.live = {
+      resource: candidate,
+      geometry,
+      snapshot,
+      uploadedBytes: uploaded.value,
+      lastKnownGood: true,
+    };
+    this.pendingCandidateBytes = 0;
+    this.status = 'resident';
+    this.rebuilds += 1;
+    if (previous !== undefined) this.options.adapter.destroy(previous.resource);
+    return ok(this.live);
+  }
+
+  resetForDeviceLoss(): void {
+    if (this.live !== undefined) this.options.adapter.destroy(this.live.resource);
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
+    return this.live;
+  }
+
+  inspect(): PointsLinesPreparationInspection<Resource> {
+    return {
+      status: this.status,
+      lastKnownGood: this.live?.lastKnownGood ?? false,
+      liveResource: this.live?.resource,
+      liveBytes: this.live?.geometry.derivedBytes ?? 0,
+      candidateBytes: this.pendingCandidateBytes,
+      cacheEntries: this.options.cache.size,
+      uploads: this.uploads,
+      rebuilds: this.rebuilds,
+      failures: this.failures,
+    };
+  }
+
+  private fail(
+    snapshot: PointsLinesRetainedSnapshot,
+    cause: Error,
+  ): Result<never, PointsLinesPrepareFailedError> {
+    this.pendingCandidateBytes = 0;
+    this.failures += 1;
+    return err(
+      new PointsLinesPrepareFailedError({
+        owner: 'points-lines',
+        generation: snapshot.meshGeneration,
+        stage: 'prepare',
+        cause: cause.message,
+        lastKnownGood: this.live !== undefined,
+      }),
+    );
+  }
+}
+
+/**
+ * Binds the existing atomic preparation owner to a lane contract. It carries
+ * no RHI handle and does not add a second cache or recovery owner.
+ */
+export function createPointsLinesLanePreparationAdapter<Resource>(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+  options: PointsLinesPreparationOptions<Resource>,
+): PointsLinesLanePreparationAdapter<Resource> {
+  const preparation = new PointsLinesPreparation(options);
+  return {
+    contract: createPointsLinesLaneContract(lane, backend),
+    prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
+    resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    lastKnownGood: () => preparation.lastKnownGood(),
+    inspect: () => preparation.inspect(),
+  };
+}

package/src/points-lines/record.ts

@@ -0,0 +1,125 @@
+import type { PointsLinesExpandedGeometry } from './expansion-cache';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export const POINTS_LINES_MATERIAL_SHADER_ID = 'forgeax::points-lines';
+
+export type PointsLinesLane = 'direct' | 'clustered' | 'cpu-webgl2';
+export type PointsLinesBackend = 'webgpu' | 'wgpu-webgl2' | 'null';
+
+export interface PointsLinesLaneContract {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly authoring: 'shared';
+  readonly evidence: 'runtime' | 'structural-only';
+  readonly material: {
+    readonly source: 'MaterialAsset';
+    readonly shaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+    readonly shadingModel: 'unlit';
+    readonly clusteredLighting: false;
+    readonly lit: false;
+  };
+  readonly graph: {
+    readonly additionalAttachments: 0;
+    readonly additionalPasses: 0;
+  };
+  readonly shadowDrawCount: 0;
+  readonly capabilities: {
+    readonly compute: false;
+    readonly storage: false;
+    readonly indirect: false;
+  };
+}
+
+export interface PointsLinesRecordPlan {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly materialShaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+  readonly component: 'Points' | 'Lines';
+  readonly meshGeneration: number;
+  readonly materialGeneration: number;
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly drawCount: 0 | 1;
+  readonly shadowDrawCount: 0;
+  readonly conservativeMarginPx: number;
+  readonly graph: PointsLinesLaneContract['graph'];
+}
+
+/**
+ * Describes the shared lane boundary without selecting a backend in authoring.
+ * Every lane uses CPU-uploaded triangle expansion; capability flags therefore
+ * stay false, including on WebGPU, and the graph remains the existing pass.
+ */
+export function createPointsLinesLaneContract(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneContract {
+  return {
+    lane,
+    backend,
+    authoring: 'shared',
+    evidence: backend === 'null' ? 'structural-only' : 'runtime',
+    material: {
+      source: 'MaterialAsset',
+      shaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+      shadingModel: 'unlit',
+      clusteredLighting: false,
+      lit: false,
+    },
+    graph: { additionalAttachments: 0, additionalPasses: 0 },
+    shadowDrawCount: 0,
+    capabilities: { compute: false, storage: false, indirect: false },
+  };
+}
+
+/**
+ * Turns one retained expansion into the bounded draw facts consumed by the
+ * existing record pass. The shader expands one quad per point or segment,
+ * so the limits are exactly four vertices and six indices per primitive.
+ */
+export function createPointsLinesRecordPlan(
+  snapshot: PointsLinesRetainedSnapshot,
+  geometry: PointsLinesExpandedGeometry,
+  contract: PointsLinesLaneContract,
+): PointsLinesRecordPlan {
+  const primitiveCount = geometry.pointCount + geometry.segmentCount;
+  const visible = snapshot.visible && primitiveCount > 0;
+  const conservativeMarginPx =
+    snapshot.style?.kind === 'points'
+      ? snapshot.style.sizePx * 0.5
+      : (snapshot.style?.widthPx ?? 0) * 0.5;
+  return {
+    lane: contract.lane,
+    backend: contract.backend,
+    materialShaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+    component: geometry.component,
+    meshGeneration: snapshot.meshGeneration,
+    materialGeneration: snapshot.materialGeneration,
+    vertexCount: primitiveCount * 4,
+    indexCount: primitiveCount * 6,
+    drawCount: visible ? 1 : 0,
+    shadowDrawCount: 0,
+    conservativeMarginPx,
+    graph: contract.graph,
+  };
+}
+
+export interface PointsLinesLaneAdapter {
+  readonly contract: PointsLinesLaneContract;
+  createRecordPlan(
+    snapshot: PointsLinesRetainedSnapshot,
+    geometry: PointsLinesExpandedGeometry,
+  ): PointsLinesRecordPlan;
+}
+
+export function createPointsLinesLaneAdapter(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneAdapter {
+  const contract = createPointsLinesLaneContract(lane, backend);
+  return {
+    contract,
+    createRecordPlan: (snapshot, geometry) =>
+      createPointsLinesRecordPlan(snapshot, geometry, contract),
+  };
+}

package/src/points-lines/snapshot.ts

@@ -0,0 +1,130 @@
+import type { PointShape } from '../components/points';
+
+export interface PointsLinesViewport {
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+}
+
+export type PointsLinesStyle =
+  | { readonly kind: 'points'; readonly sizePx: number; readonly shape: PointShape }
+  | { readonly kind: 'lines'; readonly widthPx: number };
+
+export type PointsLinesInvalidation = 'none' | 'mesh' | 'material' | 'style' | 'view' | 'scene';
+
+/**
+ * Detached facts retained between frames for the Points/Lines owner.
+ *
+ * The snapshot deliberately contains no World, ECS row, AssetRegistry, GPU
+ * handle, or derived triangle data. Mesh and material generations are the
+ * producer-owned fences used by prepare; viewport and projection are the
+ * only camera-owned facts in this projection.
+ */
+export interface PointsLinesRetainedSnapshot {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly component: 'Points' | 'Lines' | undefined;
+  readonly meshHandle: number;
+  readonly meshGeneration: number;
+  readonly materialHandle: number;
+  readonly materialGeneration: number;
+  readonly style: PointsLinesStyle | undefined;
+  readonly layer: number;
+  readonly sortKey: number | undefined;
+  readonly visible: boolean;
+  readonly sourceBounds: Float32Array;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: Float32Array;
+  readonly dedicatedResourceBytes?: number;
+}
+
+export interface PointsLinesSnapshotInput
+  extends Omit<
+    PointsLinesRetainedSnapshot,
+    'sourceBounds' | 'viewport' | 'projection' | 'sortKey'
+  > {
+  readonly sortKey?: number | undefined;
+  readonly sourceBounds: ArrayLike<number>;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: ArrayLike<number>;
+}
+
+export function createPointsLinesSnapshot(
+  input: PointsLinesSnapshotInput,
+): PointsLinesRetainedSnapshot {
+  return {
+    worldId: input.worldId,
+    entityKey: input.entityKey,
+    component: input.component,
+    meshHandle: input.meshHandle,
+    meshGeneration: input.meshGeneration,
+    materialHandle: input.materialHandle,
+    materialGeneration: input.materialGeneration,
+    style: input.style === undefined ? undefined : { ...input.style },
+    layer: input.layer,
+    sortKey: input.sortKey,
+    visible: input.visible,
+    sourceBounds: new Float32Array(input.sourceBounds),
+    viewport: { ...input.viewport },
+    projection: new Float32Array(input.projection),
+    ...(input.component === undefined ? { dedicatedResourceBytes: 0 } : {}),
+  };
+}
+
+export function comparePointsLinesSnapshots(
+  previous: PointsLinesRetainedSnapshot,
+  next: PointsLinesRetainedSnapshot,
+): PointsLinesInvalidation {
+  if (
+    previous.meshHandle !== next.meshHandle ||
+    previous.meshGeneration !== next.meshGeneration ||
+    !sameArray(previous.sourceBounds, next.sourceBounds)
+  ) {
+    return 'mesh';
+  }
+  if (
+    previous.materialHandle !== next.materialHandle ||
+    previous.materialGeneration !== next.materialGeneration
+  ) {
+    return 'material';
+  }
+  if (!sameValue(previous.style, next.style)) return 'style';
+  if (
+    previous.viewport.width !== next.viewport.width ||
+    previous.viewport.height !== next.viewport.height ||
+    previous.viewport.dpr !== next.viewport.dpr ||
+    !sameArray(previous.projection, next.projection)
+  ) {
+    return 'view';
+  }
+  if (
+    previous.worldId !== next.worldId ||
+    previous.entityKey !== next.entityKey ||
+    previous.layer !== next.layer ||
+    previous.sortKey !== next.sortKey ||
+    previous.visible !== next.visible
+  ) {
+    return 'scene';
+  }
+  return 'none';
+}
+
+function sameArray(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+function sameValue(
+  left: PointsLinesStyle | undefined,
+  right: PointsLinesStyle | undefined,
+): boolean {
+  if (left?.kind !== right?.kind) return false;
+  if (left === undefined || right === undefined) return left === right;
+  if (left.kind === 'points' && right.kind === 'points') {
+    return left.sizePx === right.sizePx && left.shape === right.shape;
+  }
+  return left.kind === 'lines' && right.kind === 'lines' && left.widthPx === right.widthPx;
+}

package/src/record/frame-lighting.ts

@@ -57,7 +57,7 @@ import {
 } from './helpers';
 import { getOrCreateFromChain, MESH_SSBO_BYTES, MESH_UBO_FULL_ARRAY_BYTES } from './mesh-ssbo';
 import type { PipelineState, RecordProfileRunner, RenderSystemInternals } from './render-context';
-import { VIEW_UNIFORM_BYTES } from './view-ubo';
+import { POINTS_LINES_VIEW_BYTES, VIEW_UNIFORM_BYTES } from './view-ubo';
 
 function runHdrpClusterProfilePhase<T>(
   runner: RecordProfileRunner | undefined,
@@ -161,6 +161,7 @@ export function buildPerFrameBindGroups(
           b5View,
           pipelineState.shadowParamsBuffer,
           b8View,
+          pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
         ],
         'view-main',
         () => {
@@ -248,10 +249,21 @@ export function buildPerFrameBindGroups(
                   value: b8View,
                 },
               },
+              {
+                binding: 10,
+                resource: {
+                  kind: 'buffer',
+                  value: {
+                    buffer: pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+                    size: POINTS_LINES_VIEW_BYTES,
+                  },
+                },
+              },
               // feat-20260625-spot-light-shadow-mapping w25: the per-spot
               // fragment-read lightViewProj matrices fold into the View UBO
               // (binding 0, `view.spotLightViewProj`) — no standalone binding 9
-              // (WebGL2 fragment uniform-buffer budget). binding 8 is the last.
+              // (WebGL2 fragment uniform-buffer budget). binding 10 is the
+              // dedicated vertex-only Points/Lines viewport UBO.
             ],
           });
           if (!viewBindGroupResult.ok) throw viewBindGroupResult.error;

package/src/record/frame.ts

@@ -206,7 +206,7 @@ import {
   executeCompiledFrameGraph,
   type RenderFeatureGraphCandidate,
 } from './typed-frame-graph';
-import { writeViewUbo } from './view-ubo';
+import { writePointsLinesViewUbo, writeViewUbo } from './view-ubo';
 
 /**
  * A frame-local material table. Repeated snapshot objects share one UBO slot;
@@ -320,6 +320,7 @@ export function recordFrame(
   },
   renderReadLeases?: readonly RenderReadLease[],
   featureGraphCandidate?: RenderFeatureGraphCandidate,
+  pointsLinesOwner?: import('./render-context').PointsLinesRecordOwner,
 ): boolean {
   // The `try / finally` wrapper advances `frameState.frameNumber` exactly
   // once per `recordFrame` invocation regardless of which early-return
@@ -699,6 +700,15 @@ export function recordFrame(
           lights,
           frameState.spotShadowSnapshots,
         );
+        if (pipelineState.pointsLinesViewBuffer !== undefined) {
+          writePointsLinesViewUbo(
+            internals.device.queue,
+            pipelineState.pointsLinesViewBuffer,
+            camera,
+            targetW,
+            targetH,
+          );
+        }
         writeShadowCasterUniforms(
           internals.device.queue,
           pipelineState.shadowCasterCascadeBuffer,
@@ -816,6 +826,7 @@ export function recordFrame(
       materialSlots,
       materialSlotOwners,
       materialSlotCount,
+      pointsLines: pointsLinesOwner,
       materialBgAssemblyCache: frameState.materialBgAssemblyCache,
       directionalShadowCacheReuse: directionalShadowCache.reuse,
       ...(profilePhase !== undefined ? { profilePhase } : {}),

package/src/record/main-pass-geometry.ts

@@ -21,6 +21,8 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import { SKIN_MATERIAL_SHADER_ID } from '../pbr-pipeline';
 import { renderStateHash, variantSetFromVertexLayoutProjection } from '../pipeline-spec';
+import type { PointsLinesRecordPlan } from '../points-lines/record';
+import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
 import { worldEntityKey } from './frame-snapshot';
@@ -40,6 +42,7 @@ import {
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
+import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-ubo';
 
 type GeometryInstanceDraw = {
   readonly instanceBuffer: Buffer;
@@ -115,6 +118,23 @@ function submitSubmeshDraws(
   }
 }
 
+/**
+ * Issues a prepared Points/Lines draw into the already-open geometry pass.
+ * Pass lifetime, attachments, bind groups, and submission remain owned by the
+ * existing main-pass interpreter.
+ */
+export function recordPointsLinesDraw(
+  pass: RhiRenderPassEncoder,
+  plan: PointsLinesRecordPlan,
+): void {
+  if (plan.drawCount === 0) return;
+  if (plan.indexCount > 0) {
+    pass.drawIndexed(plan.indexCount, 1, 0, 0, 0);
+    return;
+  }
+  pass.draw(plan.vertexCount, 1, 0, 0);
+}
+
 /**
  * feat-20260704 M3/w19: per-entity geometry (main colour) draw loop, extracted
  * verbatim from recordMainPass. Walks `c.validatedOrdered`, selects the
@@ -155,6 +175,7 @@ export function recordGeometryDraws(
     msaaActive,
     validatedOrdered,
     splitLdrSprite,
+    viewBindGroup,
   } = c;
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
   let lastVertexBuffer: GpuBuffer | null = null;
@@ -276,6 +297,13 @@ export function recordGeometryDraws(
     const entry = validatedOrdered[i];
     if (entry === undefined) continue;
 
+    // Points/Lines share the Standard geometry pass. Their retained source
+    // is prepared once by the renderer owner, while this loop remains the
+    // sole pass/draw submission owner and preserves the authored topology.
+    const pointsLinesSubmission = c.pointsLines?.prepare(entry, frameState.isHdrpActive);
+    if (entry.source.pointsLines !== undefined && pointsLinesSubmission?.plan.drawCount !== 1)
+      continue;
+
     if (
       passKind === 'forward' &&
       c.gpuDrivenEntityKeys.has(worldEntityKey(entry.source.worldId, entry.source.entityKey))
@@ -316,6 +344,70 @@ export function recordGeometryDraws(
       lastStencilReference = stencilReference;
     }
 
+    if (pointsLinesSubmission !== undefined && entry.source.pointsLines !== undefined) {
+      const pointsLinesMaterial: MaterialSnapshot = {
+        ...entry.source.material,
+        materialShaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+        materialParamSchema:
+          runtime.getParamSchema?.(POINTS_LINES_MATERIAL_SHADER_ID) ??
+          entry.source.material.materialParamSchema,
+      };
+      const materialSlot = materialSlotIndices[i]?.[0] ?? 0;
+      const pointsLinesBindGroup = resolveMaterialBindGroup(
+        materialSlot,
+        pointsLinesMaterial,
+        entry.source.entityKey,
+        entry.world ?? c.world,
+      );
+      const pointsLinesPipeline = resolveMaterialPipeline(
+        POINTS_LINES_MATERIAL_SHADER_ID,
+        {
+          ...pointsLinesMaterial.renderState,
+          cullMode: 'none',
+        },
+        'triangle-list',
+        'uint32',
+        undefined,
+        colorFormatOverride,
+        pointsLinesSubmission.layoutProjection,
+      );
+      if (pointsLinesPipeline === null) continue;
+      if (pipelineState.pointsLinesViewBuffer === undefined) continue;
+      writePointsLinesViewUbo(
+        runtime.device.queue,
+        pipelineState.pointsLinesViewBuffer,
+        c.camera,
+        c.targetW,
+        c.targetH,
+        entry.source.transform.world,
+        entry.source.pointsLines.style,
+        i * POINTS_LINES_VIEW_SLOT_STRIDE,
+      );
+      pass.setBindGroup(
+        0,
+        viewBindGroup as BindGroup,
+        new Uint32Array([i * POINTS_LINES_VIEW_SLOT_STRIDE]),
+        0,
+        1,
+      );
+      pass.setPipeline(pointsLinesPipeline);
+      pass.setVertexBuffer(0, pointsLinesSubmission.vertexBuffer);
+      pass.setIndexBuffer(pointsLinesSubmission.indexBuffer, 'uint32');
+      materialGroup1DynamicOffsets[0] = materialSlot * MATERIAL_PER_ENTITY_STRIDE;
+      pass.setBindGroup(1, pointsLinesBindGroup, materialGroup1DynamicOffsets, 0, 1);
+      const pointsLinesMeshGroup = meshBindGroup ?? meshGroup2;
+      if (pointsLinesMeshGroup === null) continue;
+      pass.setBindGroup(2, pointsLinesMeshGroup, meshGroup2DynamicOffsets);
+      pass.setBindGroup(
+        3,
+        identityInstanceDraws[0]?.instanceBindGroup ??
+          resolveGeometryInstancesBindGroup(c, identityInstanceBuffer),
+      );
+      recordPointsLinesDraw(pass, pointsLinesSubmission.plan);
+      pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+      continue;
+    }
+
     if (entry.mesh.vertexBuffer !== lastVertexBuffer) {
       pass.setVertexBuffer(0, entry.mesh.vertexBuffer.handle);
       lastVertexBuffer = entry.mesh.vertexBuffer;

package/src/record/main-pass-sprite-draws.ts

@@ -203,7 +203,7 @@ export function recordSpritePass(
         ) as never,
       );
 
-    spritePass.setBindGroup(0, viewBindGroup as BindGroup);
+    spritePass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
 
     // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
     // sprite PSO resolution migrated from the dedicated boot-time PSO

package/src/record/main-pass.ts

@@ -10,6 +10,7 @@ import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
 import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
 import { recordGeometryDraws } from './main-pass-geometry';
@@ -535,10 +536,12 @@ export function recordMainPass(
       entityKey: number,
       materialWorld: World = world,
     ): BindGroup =>
-      preparedMaterialBindGroups[materialSlot] ??
-      buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
+      material.materialShaderId !== POINTS_LINES_MATERIAL_SHADER_ID
+        ? (preparedMaterialBindGroups[materialSlot] ??
+          buildPerSubmeshMaterialBg(material, entityKey, materialWorld))
+        : buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
 
-    pass.setBindGroup(0, viewBindGroup as BindGroup);
+    pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
 
     // Track which (mesh-vertex-buffer, mesh-index-buffer, pipeline) combo
     // was last bound so consecutive entities sharing the same combo skip