Stagger territory tile rendering across frames

[evanpelle]

relates to #893

Description:

Territory updates were uploaded in one shot per game tick, producing a 10 Hz tile update which looked choppy. This change drips each tick's tile changes across the ~6 render frames between ticks so the fill flows continuously instead of stepping.

Inside TerritoryPass, each changed tile is hashed by ref into one of N buckets (configurable via tileDrip.bucketCount, set to 9 — gives ~50 ms of jitter headroom over the tick period without making attacks feel laggy). One bucket drains per render frame. The stable per-ref hash keeps repeated updates to the same tile in arrival order, so the latest owner always wins.

While in there, moved trail state ownership out of TerritoryPass and into TrailPass where it belongs — the territory shader doesn't sample trailTex, so the colocation was just code-reuse drift.

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory
• I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced

Please put your Discord username so you can be contacted if a bug or regression is found:

evan

[coderabbitai]

Walkthrough

TerritoryPass and TrailPass rendering layers are refactored to split state ownership: TerritoryPass focuses on tiles and introduces drip-bucket buffering for staggered frame uploads, while TrailPass takes full ownership of trail state with CPU storage and dirty-row tracking. Renderer orchestrates the split and manages spawn-phase state. Configuration schema is extended for drip-bucket settings.

Changes

Tile and Trail Rendering Refactoring

Layer / File(s)	Summary
Configuration schema for drip-bucket tile upload staggering src/client/render/gl/RenderSettings.ts, src/client/render/gl/render-settings.json	RenderSettings interface and render-settings.json both add a tileDrip configuration block with bucketCount field to control round-robin bucket count for staggered tile GPU uploads.
TerritoryPass refactored to tile-only ownership with drip-bucket buffering src/client/render/gl/passes/TerritoryPass.ts	TerritoryPass removes all trail-related GPU/CPU state, introduces drip-bucket buffering to queue tile updates into round-robin buckets hashed by tile reference, and adds drainDripBucket/flushAllDripBuckets APIs. Constructor, state tracking, and GPU flushing are simplified to manage cpuTileState only.
TrailPass expanded to own trail state and provide live/CPU upload workflows src/client/render/gl/passes/TrailPass.ts	TrailPass now owns cpuTrailState and dirty-row bookkeeping, tracks live trail reference, and exposes public APIs for setLiveRef, applyLiveDelta, uploadFullState, setTile, clear, and flushTexture. GPU texture flushing chooses between full or partial texSubImage2D updates based on dirty-row bounds.
Renderer wiring for split tile/trail passes and spawn-phase drip-bucket control src/client/render/gl/Renderer.ts	Renderer adds inSpawnPhase state flag, re-wires TerritoryPass constructor to remove trail texture parameter, separates tile and trail uploads across both passes, records spawn-phase state during overlay updates, and routes per-frame texture uploading to conditionally flush all drip buckets (spawn) or drain one bucket (steady-state) and call trailPass.flushTexture.
Documentation of live-mode drip-bucket tile upload semantics src/client/render/CLAUDE.md	CLAUDE.md updated to describe live tile upload mechanism: each tick's changedTiles are hashed into round-robin buckets, renderer drains one bucket per 60Hz frame for stable arrival ordering, and spawn phase flushes all buckets immediately without staggering.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested labels

UI/UX

Poem

🎨 Tiles and trails now walk their separate paths,
Each bucket drips at 60Hz, no more wrath.
Spawn flushes swift, the steady state stays calm,
A split of state that heals the render balm. 🎬

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: staggering territory tile rendering across frames to improve visual continuity.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description accurately explains the tile dripping mechanism, bucket-based staggering, per-ref hashing, and the trail state ownership refactoring, all matching the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/client/render/CLAUDE.md`:
- Around line 124-128: The doc comment in CLAUDE.md incorrectly states the
default drip bucket count as 12; update the documentation to reflect the actual
default of 9 (tileDrip.bucketCount set in render-settings.json). Edit the
paragraph referencing TerritoryPass, applyLiveDelta, drainDripBucket and
uploadTextures to replace "default 12" with "default 9" and, if present, add a
short note pointing readers to render-settings.json for tuning.

In `@src/client/render/gl/passes/TrailPass.ts`:
- Around line 95-119: setLiveRef and uploadFullState switch the source of trail
data but currently keep previous dirty-row bounds, which can cause only stale
partial ranges to be flushed; reset the dirty-row bounds when switching to a
full or fresh live state. In setLiveRef(trailState: Uint8Array) and
uploadFullState(trailState: Uint8Array) set this.dirtyRowMin to a large sentinel
(e.g. +Infinity or Number.MAX_SAFE_INTEGER) and this.dirtyRowMax to a small
sentinel (e.g. -Infinity or -1) so any queued partial range is cleared before
marking this.trailsDirty = true; ensure applyLiveDelta still updates bounds
normally.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 667b984d-bb1d-49e4-a45e-f61039b46e5e

📥 Commits

Reviewing files that changed from the base of the PR and between 6a8b6a1 and a4bbcc7.

📒 Files selected for processing (6)

• src/client/render/CLAUDE.md
• src/client/render/gl/RenderSettings.ts
• src/client/render/gl/Renderer.ts
• src/client/render/gl/passes/TerritoryPass.ts
• src/client/render/gl/passes/TrailPass.ts
• src/client/render/gl/render-settings.json

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix the documented default bucket count.

Line 127 says default is 12, but this PR sets tileDrip.bucketCount to 9 in render-settings.json. Please align the doc so tuning guidance is accurate.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/client/render/CLAUDE.md` around lines 124 - 128, The doc comment in
CLAUDE.md incorrectly states the default drip bucket count as 12; update the
documentation to reflect the actual default of 9 (tileDrip.bucketCount set in
render-settings.json). Edit the paragraph referencing TerritoryPass,
applyLiveDelta, drainDripBucket and uploadTextures to replace "default 12" with
"default 9" and, if present, add a short note pointing readers to
render-settings.json for tuning.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reset dirty-row bounds on full/snapshot trail uploads.

Line 95 and Line 115 switch upload source to full/live state, but keep old dirty-row bounds. If a partial range was queued before this, the next flush can upload only stale rows and leave the rest of trailTex outdated.

Suggested fix

   setLiveRef(trailState: Uint8Array): void {
     this.liveTrailRef = trailState;
+    this.dirtyRowMin = Infinity;
+    this.dirtyRowMax = -1; // force full upload next flush
     this.trailsDirty = true;
   }
@@
   uploadFullState(trailState: Uint8Array): void {
     this.liveTrailRef = null;
     this.cpuTrailState.set(trailState);
+    this.dirtyRowMin = Infinity;
+    this.dirtyRowMax = -1; // force full upload next flush
     this.trailsDirty = true;
   }
@@
   clear(): void {
     this.cpuTrailState.fill(0);
+    this.dirtyRowMin = Infinity;
+    this.dirtyRowMax = -1; // force full upload next flush
     this.trailsDirty = true;
   }

Also applies to: 127-131

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/client/render/gl/passes/TrailPass.ts` around lines 95 - 119, setLiveRef
and uploadFullState switch the source of trail data but currently keep previous
dirty-row bounds, which can cause only stale partial ranges to be flushed; reset
the dirty-row bounds when switching to a full or fresh live state. In
setLiveRef(trailState: Uint8Array) and uploadFullState(trailState: Uint8Array)
set this.dirtyRowMin to a large sentinel (e.g. +Infinity or
Number.MAX_SAFE_INTEGER) and this.dirtyRowMax to a small sentinel (e.g.
-Infinity or -1) so any queued partial range is cleared before marking
this.trailsDirty = true; ensure applyLiveDelta still updates bounds normally.