factoriax.assets.build_atlas

factoriax.assets.build_atlas#

Build the Factoriax sprite atlas from the procedural drawing code.

Generates factoriax/assets/atlas.png and the sidecar factoriax/assets/atlas.json per the layout documented in factoriax/assets/atlas.layout.md. The JAX renderer reads sprites from this atlas. Every visual that the play view shows for terrain, for machines, and for the player flows through it.

The sprites come from factoriax.playground.ui.icons, the drawing module that the editor and the play HUD already read. Both renderers therefore take one set of sprites, and the editor cannot drift away from the play view. The earlier atlas of flat colors did drift.

The atlas is RGBA. render_map() of the JAX renderer mixes the machine layer and the player layer onto the terrain, through the alpha channel. Three rules follow from this:

  • Block cells are opaque (alpha=255 everywhere). Terrain is the ground truth and always paints in full.

  • Machine cells keep the transparent corners that render_item_icon() produces, so placed machines read as objects sitting on terrain.

  • A player cell and a biter cell mix with the layer under them. A player that steps onto a belt therefore does not hide that belt.

Directional categories carry one cell per Direction:

  • Machines: rows 1-4 hold variants for direction LEFT, RIGHT, UP, DOWN respectively. Non-directional machines (PALLET, ASSEMBLER, FURNACE, SCIENCE_LAB, ROCKET) are rendered once and duplicated across all four rows so a uniform gather works at render time.

  • Player: misc row col 0 holds the biter. Cols 1..32 hold eight players × four directions packed as (player_idx, direction), so player p direction d_idx lives at 1 + p * 4 + d_idx. Players beyond eight wrap modulo eight to match factoriax.playground.ui.icons.PLAYER_COLORS.

    uv run python -m factoriax.assets.build_atlas uv run python -m factoriax.assets.build_atlas –out custom_dir/

Two runs of this module give the same bytes. tests/test_atlas_fresh.py makes sure of this, and CI runs that test.

factoriax.assets.build_atlas.build_atlas(out_png: Path, out_json: Path) → None#

Build atlas.png and atlas.json into the given paths.

The function is deterministic: running it twice into the same directory produces byte-identical files. CI verifies this via tests/test_atlas_fresh.py.

Parameters:

  • out_png – Path to write the atlas PNG.

  • out_json – Path to write the sidecar JSON.

factoriax.assets.build_atlas.main() → None#

CLI entry point.