[wholton]

Summary

Rewrites the bot's image code: MapGenerator, TileGenerator, PlayerAreaGenerator, DrawingUtil and the image code that was scattered across services and models. Image code now lives in layered packages, renders no longer change the game they draw, and queued renders draw from their own copy of the game. Apart from the fog fixes and layout fixes listed below, output is pixel-identical. Golden-image harnesses over 40 real games checked every stage.

Most of the 1,051 changed files are import updates from the package moves. Every commit is small and builds on its own, so it reads best commit by commit.

Structure

• Packages under ti4.image, layered top-down:

  • map: the map canvas and its sections;
  • playerarea, tile, draft and card;
  • draw: shared drawing helpers;
  • io: fonts, caches, encoding, uploads and asset paths.

  draft may also use tile. Otherwise sibling packages never depend on each other. ImagePackageLayeringTest enforces this and fails if ti4.model or ti4.game imports image code.

• Model layer: Mapper, TileHelper, PositionMapper, UnitTokenPosition and BoardPosition moved to ti4.model. The move is scripted, so it can be re-run on another branch to fix conflicts mechanically.

• MapGenerator is replaced by:

  • MapRenderer for the draw order;
  • RenderContext, resolved once per render;
  • one class per section and highlight;
  • MapUploads for the Discord and website uploads.

• TileGenerator is replaced by TileLayers (one painter per tile step), SystemContextImage and focused unit, token and badge classes.

• PlayerAreaGenerator is replaced by one class per player-area part, laid out by PlayerAreasSection.

• DrawingUtil is deleted. Its helpers moved to draw (OutlinedText, PaImage and others), and duplicate copies were merged.

• Scattered image code:

  • The slice, Nucleus, Mantis and template-preview images moved into ti4.image.draft, and the two slice renderers became one.
  • The Jimbo and colour/decal sample commands draw through ImageGrid.
  • Font getters moved from Storage to Fonts, and FileUploadService became ImageUploads.
  • Tile, token and border asset paths now come from ImageResources.

Behaviour changes

• Fog of War:

  • System and tile images requested from a thread under a -private channel used to render unfogged. They now use the same viewer rule as the map.
  • A private view with no seated viewer, such as a GM in a private channel, used to crash with a null-pointer error. It now shows a view with no knowledge instead.
  • "Could not find owner" messages from unit rendering went to the main game channel, which leaked information in fog games. They go to the bot log now.

• Renders no longer change the game. These writes are now explicit steps before or after the render:

  • fog memory;
  • Triad and Grove planet stats;
  • missing debt pool icons;
  • faction emoji normalisation;
  • clearing shown tile distances;
  • creating the neutral player, which only full map renders still do because the objective boxes count it.

  Planets that are no longer in the game are now removed from players on load and save, not while drawing a planet card.

• Letnev commander: the production badge no longer unlocks it as a side effect of drawing. A test checks that adding the fifth non-fighter ship still unlocks it.

• Layout fixes from the MapGenerator rewrite, each its own commit:

  • the canvas height fits what was drawn;
  • the header lays out around the expedition tracker, and strategy cards wrap into even rows;
  • the landscape player-area column is fixed;
  • law and event cards grow to fit their text;
  • game mode badges and the spectators line no longer clip.

Thread safety

• Render copy: MapRenderPipeline.queue and queueImage take a copy of the game on the queueing thread, through an in-memory save and load plus the shown tile distances. The render, the encode, overview suppliers and the website upload use only that copy. The copy takes a median of 1.9 ms per game and 32 ms for the 39-player PBD /game end broken when user no longer exists #1000.
• Mapper reload: Mapper.init() used to clear and refill the maps renders read. It now builds new maps and swaps each in whole.
• Static fields: RenderStaticStateTest fails on any new mutable static field in the render path.
• Tests: RenderThreadSafetyTest covers:
  • the live game changing after a render is queued;
  • two games rendering at once;
  • a Mapper reload during renders.
• Known gaps (compact TODOs):
  • The markers that stop a player-area warning being repeated are still written to the live game.
  • ExecutionLockManager locks can expire while still held.

Performance

• Neighbours: computed once per render with NeighbourMap, and Player.getNeighbouringPlayers builds a neighbour graph instead of being quadratic.

• WebP method 2: about half the encode time. Files are 4–10% larger on normal maps and up to about 21% larger on the widest fog maps. The largest map in the corpus is 7.1 MB, under Discord's 10 MB limit.

• Corpus render time: 118 s down to 47 s. A typical map went from about 710 ms to 440 ms, and PBD Draw relic when purge fragments #100 from 42.6 s to 3.7 s.

• Small changes in the last stage:

  • WebP is encoded only for the Discord upload;
  • colours are looked up in an index;
  • the unit id set is built once per Mapper load;
  • the unused website-only render path is removed.

  None of these was measurable on its own. Encoding is about 74% of render time now.

• Measured and dropped:

  • Encoding a contiguous copy of the canvas saved nothing.
  • A per-render memo for unit lookups would save about 1% of a render and touch 7 call sites.

Verification

• Golden harnesses (gated, off in CI) render 40 real saves:

  • MapRenderGoldenHarness: 3,711 map, tile, context-image and overview renders;
  • ImageGeneratorsGoldenHarness: 684 cases;
  • ScatteredImagesGoldenHarness: 233 cases.

  They compare pixels, website overlays, random-call counts, game state and messages.

• Every stage except the fog fixes was identical in all three harnesses. The Stage 4 run rendered every game from its copy.

• The fog stage's differences were all classified:

  • 8 fog views that used to crash now render;
  • 45 renders no longer send channel messages;
  • all game-state changes come from the moved writes listed above;
  • no other image changed.

• Tests: 1,763 tests pass, with 0 failures.

Not covered by real data: no save in the corpus uses map segments, extra boards or ghost hexes, so those paths were checked with synthetic games only. A testbed check on a live game with segments would be worth doing.

🤖 Generated with Claude Code

[github-actions]

🔬 Test Results

✅ JSON Validation

No JSON files changed.

---

✅ Formatting Checks Passed

All files pass Spotless formatting.

---

✅ JUnit Tests Passed

All tests passed successfully.