acdream/docs/superpowers/specs/2026-06-23-cellobject-draw-batching-design.md

Spec — batch cell-object draws (dense-town FPS, iteration 1) — 2026-06-23

Context

The dense-town (Arwic) FPS investigation (docs/research/2026-06-23-dense-town-fps-attribution-report.md) proved the frame is ~96% CPU-bound — measured GPU is 0.5 ms; the ~8–13 ms frame is CPU work inside OnRender, scaling with how many buildings/cells are in view. The clean-split + [CPU-PHASE] measurement (no glFinish) attributed the CPU cost of RetailPViewRenderer.DrawInside:

phase	ms/frame
cellobjects	3.3–4.5	DrawCellObjectLists — per-cell static draw + per-cell particles
landscape	2.1–2.9	sky + terrain + scenery + late draws
partition	0.7–3.2	entity partition + viewcone build
dynamics	0.6–1.3	dynamics draw + particles
flood / assemble / shells / portalmask	< 0.3 each	NOT the cost (refuted the static guess)

cellobjects is the biggest single lever. Root cause: DrawCellObjectLists calls WbDrawDispatcher.Draw once per visible cell, each call orphaning 6 SSBOs via glBufferData + full state setup (WbDrawDispatcher.cs:1521-1558). This is the same class of bug the shipped cells-shell fix solved for shell geometry (94 per-cell Render calls → 1 batched; 29→75 fps). We apply the same pattern to cell objects.

Target: dense town solidly 144+ fps facing the densest view (~7 ms budget). Iterate hotspots, re-measuring after each. This spec is iteration 1 (cellobjects).

Goal

Collapse the per-cell WbDrawDispatcher.Draw calls in DrawCellObjectLists into a single batched draw covering all visible cells' surviving statics, while preserving every rendering invariant (visibility, transparency order, particle occlusion). Identical pixels, far fewer draw submissions.

Design

RetailPViewRenderer.DrawCellObjectLists (RetailPViewRenderer.cs:772-825) is restructured from one per-cell loop (cull → draw → particles) into two loops:

Loop 1 — cull + accumulate (no GL draws):

_allCellStatics.Clear();          // reused List<WorldEntity> scratch field
_cellObjCells.Clear();            // reused HashSet<uint> scratch field
for (i = OrderedVisibleCells.Count - 1; i >= 0; i--):     // far → near
    cellId = OrderedVisibleCells[i]
    if (!drawableCells.Contains(cellId)) continue
    if (!partition.ByCell.TryGetValue(cellId, out bucket) || bucket.Count == 0) continue
    survivorsBefore = _allCellStatics.Count
    foreach (e in bucket):
        EntitySphere(e, out c, out r)
        if (viewcone.SphereVisibleInCell(cellId, c, r)) _allCellStatics.Add(e)
    if (_allCellStatics.Count > survivorsBefore) _cellObjCells.Add(cellId)
    if (ProbePhantomEnabled) EmitPhantomObjsProbe(cellId, _allCellStatics.Count - survivorsBefore)

One batched draw:

if (_allCellStatics.Count > 0):
    UseIndoorMembershipOnlyRouting()
    DrawEntityBucket(ctx, _allCellStatics, _cellObjCells)   // N WbDispatcher.Draw → 1

Loop 2 — per-cell particles, after statics are in the depth buffer:

for (i = OrderedVisibleCells.Count - 1; i >= 0; i--):     // far → near
    cellId = OrderedVisibleCells[i]
    if (!drawableCells.Contains(cellId)) continue
    if (!partition.ByCell.TryGetValue(cellId, out bucket) || bucket.Count == 0) continue
    _cellStaticScratch.Clear()
    foreach (e in bucket):
        EntitySphere(e, out c, out r)
        if (viewcone.SphereVisibleInCell(cellId, c, r)) _cellStaticScratch.Add(e)
    if (_cellStaticScratch.Count == 0) continue
    foreach (slice in GetCellSlicesOrNoClip(clipAssembly, cellId)):
        ctx.DrawCellParticles?.Invoke(new RetailPViewCellSliceContext(cellId, slice, _cellStaticScratch))

New reused scratch fields on RetailPViewRenderer (cleared per call, render-thread only — match the existing _cellStaticScratch/_dynamicsScratch pattern): private readonly List<WorldEntity> _allCellStatics = new(); and private readonly HashSet<uint> _cellObjCells = new();.

Re-culling in loop 2 is deliberate: it is a handful of sphere-vs-plane dot products per static and is negligible next to the draw-submission cost being removed; it avoids storing per-cell survivor ranges.

Correctness invariants (must hold)

1. Same entity set drawn. Per-cell, the bucket only ever held that cell's entities and the filter was {cellId}; the batched form passes all survivors with the union _cellObjCells, so the dispatcher's visibleCellIds membership gate admits exactly the same set.
2. Transparency compositing. WbDrawDispatcher sorts opaque front-to-back (:1469) and transparent back-to-front by group distance (:1470, CompareTransparentSubmissionOrder). Global batching yields true back-to-front ordering across cells — equal or better than the old per-cell-bucketed order. Opaque is z-buffered (order-independent).
3. Particle occlusion. Particles depth-test but do not write depth; loop 2 runs after the batched static draw so same-cell statics already occupy the depth buffer. (This is the reason for two loops — a single-loop batch would draw particles before the statics and lose same-cell occlusion.)
4. Frame order unchanged elsewhere. Shells, exit-portal masks, and dynamics-last all keep their positions in DrawInside. lbId, neverCullLandblockId, animatedEntityIds are passed exactly as before.
5. No double-draw. Each surviving static is added once to _allCellStatics; the batched draw runs once.

Scope

• In: RetailPViewRenderer.DrawCellObjectLists only.
• Out (explicitly):
  • DrawBuildingLookIns per-cell draws — interior-root only, does not fire at outdoor Arwic; an analogous follow-up if a later profile shows it.
  • Particle-pass consolidation (DrawCellParticles re-walks the particle system per cell) — separate concern, separate fix.
  • landscape (sky-submesh batching) and partition optimization — iteration 2, pursued only if re-measuring after this fix shows we are not solidly 144+.
  • WbDrawDispatcher persistent-SSBO change (Approach 3) — back-pocket follow-on that compounds, if the single remaining draw's SSBO orphaning still shows up.

Testing & acceptance

• dotnet build green, dotnet test green. Pview ordering / cell-object tests must stay green — especially HouseExitWalkReplayTests and any viewcone/cell-object coverage. If no test pins cross-cell cell-object batching, add one asserting the batched survivor set equals the union of per-cell survivor sets.
• Visual (user, faces dense Arwic): all statics present (no missing furniture); no transparency or flame-through-furniture artifacts; FPS up.
• Perf (re-measure [CPU-PHASE] under ACDREAM_FPS_PROF=2, facing densest town): cellobjects drops from ~3.5 ms toward ~0.5 ms; wall falls accordingly. Decide from this whether iteration 2 (landscape + partition) is needed for solidly-144+.
• Retail-faithfulness: pixels identical; this is a draw-mechanism speed change only (per the project steer that render-perf is not faithfulness-gated as long as pixels and game feel are unchanged). No divergence-register row required.

References

• Attribution report: docs/research/2026-06-23-dense-town-fps-attribution-report.md
• Precedent (the blessed pattern): the cells-shell batching fix — RetailPViewRenderer.DrawEnvCellShells (RetailPViewRenderer.cs:664-701), commits 3af7d00 / 8067d3b.
• Dispatcher sort: WbDrawDispatcher.cs:1469-1470, :1750-1756.