| name | esir-factorio-asset-export |
| description | Use when Codex should stage Meshy/Blender spritesheets, animated sheets, shadow sheets, or source icon art as Factorio/ESIR-ready asset drafts with previews, manifests, and Lua prototype snippets without wiring them into the mod. |
ESIR Factorio Asset Export
Use this skill after $meshy-blender-spritesheet, $meshy-api, or any other art workflow has produced source art that should become a Factorio/ESIR asset draft.
Hard Rules
- Stage generated assets under
output/meshy/<asset>/factorio-export/ unless the user explicitly gives another staging path.
- Treat
output/ as ignored generated staging only. Do not leave the only copy of a reusable generator script, hand-written note, or prompt there; promote durable sources to .codex/esir/asset-generators/ or .codex/esir/art-prompts/.
- Do not copy files into
exotic-space-industries-remembrance/graphics/ or edit prototypes unless the user explicitly asks for that follow-up. Promotion remains dry-run unless --execute is passed.
- Do not treat a generated sheet as shippable until the preview has been inspected.
- For generated item or technology icon underlays/overlays, keep each semantic layer as its own transparent PNG and wire the prototype with Factorio
icons entries so the game composites them. A baked composite may be emitted as a preview artifact, but it must not be the only shipped asset unless the user explicitly asks for a flattened icon.
- During preview inspection, reject or rerender drafts whose sprite occupies too little of each frame, loses its silhouette at Factorio scale, touches/cuts off at a frame edge, or has minimal contrast because the material is near-black. If a render manifest includes
alpha_bounds, treat non-empty warnings or margins below the requested min_alpha_margin as a rerender cue.
- For Factorio-bound sprites from Blender or Meshy, prefer preset
render-bundle manifests with base, shadow, light/glow, and mask passes. Treat single-sheet entity/machine exports without a shadow or preset-equivalent manifest as draft-only unless the user explicitly requested no shadow or non-preset output.
- Treat staged
object_mask_0.png as unclassified until review marks it as a runtime-tint mask, manual post-processing source, or unused evidence. The exporter stages masks; it does not mean the prototype is colorable until the Lua layer explicitly includes flags = {"mask"} and apply_runtime_tint = true.
- Runtime-tint masks are for owner-readability only: turrets, vehicles, rolling stock, train stops/remotes, force-facing logistics/control devices, and ownership-critical entities. Do not promote masks for neutral terrain, decoratives, resources, ruins, pure environmental/alien forms, or assets whose baked ESIR chromatic identity should remain fixed.
- For main-pack shipping graphics, omit leading
ei- from staged filename roots and final graphics directories. Keep ei-* only in prototype metadata, snippet hints, and promotion --prototype-name when the prototype uses that internal name.
- Keep Meshy credentials out of this workflow. This skill does not need API keys.
- For item icons, reuse the repo-local
$esir-item-icon-prep behavior instead of hand-building mip strips.
Modes
entity: one-frame or directional entity sheets. Factorio-bound entities should include a separate shadow sheet unless explicitly no-shadow.machine: base machine sheet plus shadow, with optional working_visualisations animation sheet and matching working shadow.icon: source art to a staged 128/64/32 Factorio item icon strip.render-bundle: staged output from the local Factorio rendering preset, such as Render.zip, an extracted Render/.Sheets folder, or raw Render/Object/*.png frame folders, preserving base, shadow, mask, light, glare, and water-reflection sheets. Large exports can emit Factorio stripes; mask sheets still need manual classification before prototype wiring.promote: dry-run or explicitly execute narrow asset copies and marker-delimited prototype patching from a staged manifest, with optional asset-count and prototype-identity guards.gallery: static visual approval HTML over staged manifests and preview/source PNGs.
Read references/factorio-asset-options.md when choosing fields, scale, shifts, or snippet shape.
Command
Run from the repo root:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py <entity|machine|icon|render-bundle|promote|gallery> --help
Entity example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py entity `
--asset-name threshold-array `
--sheet output/meshy/threshold-array/threshold-array-sheet.png `
--render-manifest output/meshy/threshold-array/threshold-array-sheet.manifest.json `
--target-prototype-name ei-threshold-array `
--direction-count 8 `
--scale 0.35 `
--shift 0,-0.2
Machine example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py machine `
--asset-name threshold-array `
--sheet output/meshy/threshold-array/base.png `
--working-sheet output/meshy/threshold-array/working.png `
--working-shadow-sheet output/meshy/threshold-array/working-shadow.png `
--working-frame-count 16 `
--working-line-length 4 `
--snippet-template assembling-machine `
--target-prototype-name ei-threshold-array `
--target-field graphics_set `
--animation-speed 0.6 `
--scale 0.35 `
--shift 0,-0.2
Icon example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py icon `
--asset-name threshold-array `
--source output/meshy/threshold-array/icon-source.png `
--target-prototype-name ei-threshold-array
Render bundle example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py render-bundle `
--asset-name threshold-array `
--bundle Render.zip `
--target-prototype-name ei-threshold-array `
--line-length 8 `
--frame-count 64 `
--scale 0.35 `
--shift 0,-0.2
Raw preset frame pack example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py render-bundle `
--asset-name threshold-array `
--bundle output/meshy/threshold-array/Render `
--preset-manifest output/meshy/threshold-array/Render/factorio-preset-render-manifest.json `
--target-prototype-name ei-threshold-array `
--pack-raw-frames `
--grid 8x8 `
--line-length 8 `
--frame-count 64 `
--emit-water-reflection
Promotion dry-run example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py promote `
--manifest output/meshy/threshold-array/factorio-export/threshold-array.factorio-asset-manifest.json `
--apply-prototype `
--prototype-file exotic-space-industries-remembrance/prototypes/.../target.lua `
--prototype-type assembling-machine `
--prototype-name ei-threshold-array `
--field graphics_set `
--expected-asset-count 4 `
--require-prototype-identity
Gallery example:
python .codex/skills/esir-factorio-asset-export/scripts/export_factorio_asset.py gallery `
--manifest-glob "output/meshy/*/factorio-export/*.factorio-asset-manifest.json" `
--output output/meshy/visual-approval-gallery.html `
--approval-json output/meshy/visual-approval-gallery.json `
--include-snippet
Output
Each run writes staged files only:
- staged PNG asset(s)
- preview PNG(s), including working-animation previews when present
<asset>.factorio-asset-manifest.json<asset>.prototype-snippet.lua
These staged files remain generated review artifacts under ignored output/. Commit final approved PNGs only after promotion into the mod graphics packs, and commit reproducible procedural source scripts under .codex/esir/asset-generators/ instead of under an output source/ folder.
The Lua snippet assumes the staged PNGs will eventually be copied into the graphics folder matching the selected path variable, such as ei_graphics_entity_path or ei_graphics_item_path. Icon snippets are prototype-table field fragments and keep trailing commas for pasteability inside an item prototype. --snippet-template, --target-prototype-type, --target-prototype-name, and --target-field add prototype-aware comments and manifest metadata for safer promotion planning; they do not copy or patch anything. Preset mask sheets remain staged evidence unless the snippet or later prototype patch explicitly wires a mask layer with flags = {"mask"} and apply_runtime_tint = true.
promote prints the exact copy and patch plan by default. It only copies PNGs or edits Lua when --execute is present, and prototype patching requires explicit -- ESIR_ASSET_PROMOTE_START <prototype-name> <field> / -- ESIR_ASSET_PROMOTE_END <prototype-name> <field> markers. Use --prototype-integration data-raw-assignment when a marker block should become a guarded data.raw["type"]["name"].field = ... assignment instead of a raw snippet fragment.
