Incremental Pixi.js Quality Improvements for Structure Icon Rendering

[Skigim]

Purpose

Apply incremental, low-risk quality fixes to the Pixi.js structure icon path to improve correctness, cleanup, and maintainability without changing gameplay behavior or architecture.

---

Objectives

• Remove O(n) render lookups by replacing array state with a unit-id keyed map in StructureIconsLayer.ts.
• Eliminate avoidable allocations (outline filters, dot graphics churn, temporary colorization canvas).
• Fix known correctness/lifecycle issues:
  • async ghost-state race
  • texture cache GPU leak on invalidation
  • inconsistent child destruction
  • missing renderer/stage disposal path
• Replace Pixi namespace import style with named imports in:
  • StructureIconsLayer.ts
  • StructureDrawingUtils.ts
• Consolidate magic numbers into named constants.

---

Description

Scope is limited to StructureIconsLayer.ts and StructureDrawingUtils.ts, with independent incremental steps:

1. Array → map for render records keyed by unit id.
2. Reuse static red/green/white outline filters.
3. Move or stage async ghost action lookup so render reads synchronous cached state.
4. Destroy cached textures before map eviction during cache invalidation.
5. Convert to named Pixi imports.
6. Standardize container destruction with child cleanup.
7. Extract zoom/query/filter/size magic numbers into constants.
8. Ensure dot rendering assets are shared/reused consistently.
9. Add explicit dispose lifecycle (renderer, stage, cache, canvas) and hook into teardown path if available.
10. Reuse one offscreen canvas/context in image colorization helper.

Overlap / coordination:

• Complements issue Handle graphics context loss for PixiJS #2147 (context-loss handling), especially lifecycle and texture cleanup.
• Likely low-conflict with PR Perf/refactor: buildableUnits #3193; both are adjacent to ghost/buildability flow.

Verification:

• Run npm test.
• Manual check: dot/icon/level transitions across zoom, ghost outline correctness.
• DevTools sanity: lower lingering texture count after invalidation and fewer minor GC spikes.

---

skigim

[Skigim]

@VariableVince you seem to have done the most work with the pixi system, so would want to confirm with you.

[VariableVince]

@Skigim no sorry i wouldn't be the right person for this, DevelopingTom (IngloriousTom) or Vivacious Box (Mr Box) might be.

This seems AI made by the way. Did you have actual proposals for fixes or quality/performance improvements?

[Skigim]

@Skigim no sorry i wouldn't be the right person for this, DevelopingTom (IngloriousTom) or Vivacious Box (Mr Box) might be.

This seems AI made by the way. Did you have actual proposals for fixes or quality/performance improvements?

I understand the concern, especially with the massive amount of low effort AI submissions I'm sure many maintainers are getting these days. Let me address it openly. This comment will not be touched by AI in any way.

Yes, I use AI in my workflow and to draft PRs for clarity and readability, particularly since I'm incredibly bad at markdown formatting and tend to write in a way that can be "wall of text" in nature and difficult to read. However, the ideas and the work is primarily driven by my own research.

In this issue, for example - There is an open issue #2147 which would be directly addressed by a proper teardown path for cached textures as I mentioned in this issue (step 4). Texture cache invalidation deletes keys but doesn’t destroy Pixi textures first.(StructureDrawingUtils.ts:99-103, StructureDrawingUtils.ts:449)

O(1) lookups instead of O(n) keeps us from running the entire array to find and update each structure. Currently we store them at StructureIconsLayer:82 and do linear passes at 323, 554 (.find) and 754 (.filter).

For the sake of time I'll leave it at this for now, but I promise I am fully aware of the limitations of AI and use it responsibly in my workflows. I confess I was a bit offended at the way you asked if I had "actual proposals" but considering the current landscape I do understand the frustration with what can look like another thoughtless AI crapshot.

[VariableVince]

@Skigim no sorry i wouldn't be the right person for this, DevelopingTom (IngloriousTom) or Vivacious Box (Mr Box) might be.
This seems AI made by the way. Did you have actual proposals for fixes or quality/performance improvements?

I understand the concern, especially with the massive amount of low effort AI submissions I'm sure many maintainers are getting these days. Let me address it openly. This comment will not be touched by AI in any way.

Yes, I use AI in my workflow and to draft PRs for clarity and readability, particularly since I'm incredibly bad at markdown formatting and tend to write in a way that can be "wall of text" in nature and difficult to read. However, the ideas and the work is primarily driven by my own research.

In this issue, for example - There is an open issue #2147 which would be directly addressed by a proper teardown path for cached textures as I mentioned in this issue (step 4). Texture cache invalidation deletes keys but doesn’t destroy Pixi textures first.(StructureDrawingUtils.ts:99-103, StructureDrawingUtils.ts:449)

O(1) lookups instead of O(n) keeps us from running the entire array to find and update each structure. Currently we store them at StructureIconsLayer:82 and do linear passes at 323, 554 (.find) and 754 (.filter).

For the sake of time I'll leave it at this for now, but I promise I am fully aware of the limitations of AI and use it responsibly in my workflows. I confess I was a bit offended at the way you asked if I had "actual proposals" but considering the current landscape I do understand the frustration with what can look like another thoughtless AI crapshot.

Yeah sorry, that came across harsh and not how i should have worded it. AI is used in the way you do throughout the repo, so no worries there :)

It sounds good to me in principle though, been hoping for someone to be able to fix #2147 for a long time actually. But i'm not knowledgeable enough on it alas. However a PR would probably be welcomed?

Scamiv (Vimacs) is also working on a further move to (native) WebGL, later to WebGPU (which WebGL probably as fallback). So it could maybe be good to allign with him on this too in the Dev discord server? I'm tryout33 there btw.