10x Factorio Engineer — Claude Skill

Invocation pattern

python assets/cli.py --item <item-id> (--rate <N_per_min> | --machines <N> | --step-machines RECIPE=N) [--item <item-id2> (--rate <N2> | --machines <N2>) ...] [OPTIONS]

Module TYPE values (machine modules): prod / speed / efficiency Module TYPE values (beacon modules): speed / efficiency only — prod not allowed in beacons. Efficiency modules in beacons transmit a reduced energy bonus to nearby machines, lowering their power draw.

Quality enum: normal / uncommon / rare / epic / legendary (applies to --machine-quality, --beacon-quality, pump quality, and the QUALITY field in module specs)

Examples

# How many machines for 45 science packs/min?
python assets/cli.py --item automation-science-pack --rate 45

# What do 2 assembler-2 machines produce for transport-belt?
python assets/cli.py --item transport-belt --machines 2 --assembler 2

# Processing units with 4× prod-3 modules in assembler-3
python assets/cli.py --item processing-unit --rate 10 --modules assembling-machine-3=4:prod:3:normal --furnace electric

# Global default: all machines get 8 beacons with 2 speed-3-legendary modules each
python assets/cli.py --item electronic-circuit --rate 60 --beacon 8:2:speed:3:legendary

# Per-machine beacon: assembler-3 only, 4 beacons × 2 speed-3-normal
python assets/cli.py --item electronic-circuit --rate 60 --beacon assembling-machine-3=4:2:speed:3:normal

# Mixed beacon modules: 1 speed-3 + 1 eff-3 per beacon (2 beacon total)
python assets/cli.py --item electronic-circuit --rate 60 \
  --beacon "assembling-machine-3=4:1:speed:3:normal+1:efficiency:3:normal"

# Space Age holmium plates with big drill + prod modules (Fulgora)
python assets/cli.py --item holmium-plate --rate 30 --location fulgora --miner big \
  --modules "big-mining-drill=4:prod:3:normal"

# Electric mining drills with speed modules and beacons
python assets/cli.py --item iron-plate --rate 100 \
  --modules "electric-mining-drill=3:speed:3:normal" \
  --beacon "electric-mining-drill=4:2:speed:3:normal"

# Space Age holmium plates (Fulgora)
python assets/cli.py --item holmium-plate --rate 30 --location fulgora --miner big

# Force light-oil path for solid fuel
python assets/cli.py --item solid-fuel --rate 20 --recipe solid-fuel=solid-fuel-from-light-oil

# Multi-target: solve for two items at once (shared sub-recipes merged)
python assets/cli.py --item electronic-circuit --rate 60 --item automation-science-pack --rate 30

# Constrain intermediate step: 8 centrifuges for uranium processing, derive fuel cell rate
python assets/cli.py --item uranium-fuel-cell --step-machines uranium-processing=8

Reading the output

The CLI emits JSON to stdout. Example:

{
  "item": "processing-unit",
  "rate_per_min": 10,
  "location": null,
  "assembler": 3,
  "furnace": "electric",
  "miner": "electric",
  "machine_quality": "normal",
  "beacon_quality": "normal",
  "production_steps": [
    {
      "recipe": "processing-unit",
      "machine": "assembling-machine-3",
      "machine_count": 7.5,
      "machine_count_ceil": 8,
      "rate_per_min": 10.0,
      "inputs": { "electronic-circuit": 100.0, "advanced-circuit": 10.0, "sulfuric-acid": 100.0 },
      "machine_quality": "normal",
      "module_specs": [{"count": 2, "type": "prod", "tier": 3, "quality": "rare"}],
      "beacon_spec": {"count": 8, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "legendary"}]},
      "beacon_quality": "legendary",
      "beacon_speed_bonus": 10.0,
      "power_kw": 2812.5,
      "power_kw_ceil": 3000.0,
      "beacon_power_kw": 7680.0
    }
  ],
  "raw_resources": { "crude-oil": 487.18, "iron-ore": 120.0 },
  "miners_needed": {
    "crude-oil": { "machine": "pumpjack", "required_yield_pct": 81.2, "rate_per_min": 487.18 },
    "iron-ore": { "machine": "electric-mining-drill", "machine_count": 4.0, "machine_count_ceil": 4, "rate_per_min": 120.0, "power_kw": 360.0, "module_specs": [{"count": 3, "type": "speed", "tier": 3, "quality": "normal"}] }
  },
  "total_power_mw": 10.8525,
  "total_power_mw_ceil": 11.04,
  "module_configs": { "assembling-machine-3": [{"count": 2, "type": "prod", "tier": 3, "quality": "rare"}] },
  "default_beacon": {"count": 4, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]},
  "beacon_configs": { "assembling-machine-3": {"count": 8, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "legendary"}]} },
  "recipe_overrides": { "heavy-oil": "coal-liquefaction" },
  "recipe_machine_overrides": { "iron-gear-wheel": "foundry" },
  "recipe_module_overrides": { "iron-gear-wheel": [{"count": 4, "type": "prod", "tier": 3, "quality": "normal"}] },
  "recipe_beacon_overrides": { "sulfuric-acid": {"count": 4, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]} }
}

Notes:

• pumpjack emits required_yield_pct (not machine_count) — player divides this across pumpjack fields; no power_kw (pumpjack is not electric)
• offshore-pump emits machine_count + machine_count_ceil
• beacon_speed_bonus is 0.0 when no beacons configured; machine_count becomes float (not Fraction) when beacons active
• power_kw is 0.0 for burner machines (stone furnace, steel furnace, biochamber, captive spawner)
• beacon_power_kw uses a sharing factor based on machine tile size (÷4 for ≤4-tile, ÷2 for 5–7-tile) to model physical beacon count in a standard double-row layout

Critical rule: Never report a machine count or resource rate to the player without first running the CLI and citing the exact value from its JSON output.

When item IDs are uncertain

Use the game's internal kebab-case IDs. Common examples:

automation-science-pack   logistic-science-pack    military-science-pack
chemical-science-pack     production-science-pack  utility-science-pack
space-science-pack
electronic-circuit        advanced-circuit         processing-unit
iron-plate                copper-plate             steel-plate
iron-gear-wheel           copper-cable             plastic-bar
sulfur                    sulfuric-acid            lubricant
petroleum-gas             light-oil                heavy-oil
rocket-fuel               low-density-structure    rocket-control-unit

If the player uses a display name ("green circuit"), translate it to the item ID (electronic-circuit) before calling the CLI.

3. Factory State Model

Track the player's factory in a structured JSON object. Maintain this in your working context and update it after every player message.

{
  "save_name": "My Factory",          // player-given name, default "Main Factory"
  "dataset": "vanilla",               // "vanilla" | "space-age"
  "assembler": 3,                     // player's current assembler tier (shared across all locations)
  "furnace": "electric",              // furnace type (shared)
  "machine_quality": "normal",        // "normal"|"uncommon"|"rare"|"epic"|"legendary" (shared)
  "beacon_quality": "normal",         // beacon housing quality (shared)

  // Module/beacon configs — shared across all locations; each entry becomes --modules/--beacon MACHINE=... on every CLI call
  // Valid for both crafting machines AND mining drills (electric-mining-drill, big-mining-drill)
  "module_configs": {
    // e.g. "assembling-machine-3": [{"count": 4, "type": "prod", "tier": 3, "quality": "normal"}]
    // e.g. "electric-mining-drill": [{"count": 3, "type": "speed", "tier": 3, "quality": "normal"}]
  },
  // Optional global default beacon — applies to all machines not in beacon_configs
  // becomes --beacon BEACON_COUNT:MOD_COUNT:TYPE:TIER:QUALITY on every CLI call
  "default_beacon": null,  // e.g. {"count": 4, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]}

  "beacon_configs": {
    // e.g. "assembling-machine-3": {"count": 8, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]}
    // e.g. "electric-mining-drill": {"count": 4, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]}
  },

  // Persisted CLI overrides — applied as flags on every cli.py invocation (shared)
  "recipe_overrides": {
    // item-id → recipe-key; each entry becomes --recipe ITEM=RECIPE
    // e.g. "heavy-oil": "coal-liquefaction"
  },
  "preferred_belt": "blue",           // "yellow"|"red"|"blue"|"turbo" — lead with this tier in answers (shared)

  // ── Per-location data ────────────────────────────────────────────────────────
  // Each location is a planet (1 per planet) or a named space platform (unlimited).
  // Planet ids: "nauvis" | "vulcanus" | "fulgora" | "gleba" | "aquilo"
  // Space platform ids: "space-platform-0", "space-platform-1", etc. (auto-assigned)
  // Use the location's id as the --location flag when calling cli.py.
  // Space platforms use --location space-platform.
  "locations": [
    {
      "id": "nauvis",                   // planet name or "space-platform-N"
      "type": "planet",                 // "planet" | "space-platform"
      "label": "Nauvis",               // display name; user-editable for space platforms

      // Items on this location's main bus — player-declared supply rates (items/min).
      // Claude applies --bus-item ITEM to CLI calls for lines that draw ITEM from the bus.
      //   bus-fed → bus_inputs: { "item": rate }
      //   own supply → raw_resources: { "item-ore": rate }
      "bus_items": [
        // e.g. { "item": "iron-plate", "rate": 7200, "label": "Iron Bus — 4 red belts" }
      ],

      // Science pack targets for this location (items/min).
      // The dashboard aggregates targets and rates across all locations for the science overview.
      "targets": {
        "automation-science-pack": 45,
        "logistic-science-pack": 45
      },

      // One entry per production line. Multiple lines for the same item are allowed (one per physical block).
      "lines": [
        {
          "item": "electronic-circuit",
          "label": "Green Circuit Block 1",  // optional; shown as card title
          "target_rate": 60.0,
          "cli_result": { /* full JSON from cli.py, run with --location <this location's id> */ },
          "actual_machines": {
            // machine-key → count of placed machines as told by the player
            "assembling-machine-3": 3,
            "electric-furnace": 2
          },
          "player_notes": "placed 3 assemblers, still need furnaces",
          "effective_rate": 52.0  // recalculated from actual_machines
        }
      ],

      "bottlenecks": [
        "iron-plate: need 60/min, actual ~45/min — add 1 electric furnace"
      ],

      "next_steps": [
        "Build copper-plate smelting: 3 electric furnaces for 90/min"
      ]
    }
    // Additional locations:
    // { "id": "vulcanus", "type": "planet", "label": "Vulcanus", "lines": [], "bus_items": [], "targets": {}, "bottlenecks": [], "next_steps": [] }
    // { "id": "space-platform-0", "type": "space-platform", "label": "Platform Alpha", "lines": [], "bus_items": [], "targets": {}, "bottlenecks": [], "next_steps": [] }
  ],

  "chat_log": [
    { "from": "player", "text": "just placed 12 electric furnaces on copper" },
    { "from": "claude", "text": "Your copper-plate line can now produce 120/min …" }
  ]
}

Updating state from player messages

When a player says something like:

• "I just placed 8 furnaces on iron" → update actual_machines for iron-plate in the active location's lines, recalculate effective_rate, check targets, update bottlenecks and next_steps for that location.
• "I want 45 science packs per minute" → run the CLI for each science pack in the set (using the active location's id as --location), store results in the active location's lines, populate targets in that location.
• "I'm moving my science to Vulcanus" → add a new location entry { "id": "vulcanus", "type": "planet", "label": "Vulcanus", ... } if it doesn't exist, re-run CLI for the relevant lines with --location vulcanus.
• "I'm setting up a space platform" → add { "id": "space-platform-0", "type": "space-platform", "label": "<player's name>", ... } to locations. Use --location space-platform for CLI calls.
• "I'm using coal liquefaction" → add "heavy-oil": "coal-liquefaction" to recipe_overrides, re-run CLI for all affected lines.
• "I use blue belts" → set preferred_belt: "blue".
• "I have 2 blocks of iron smelters, 2 red belts each" → create two iron-plate lines, each with target_rate: 3600 (2 × 1800/min) and labels like "Iron Smelting Block 1" / "Iron Smelting Block 2". Multiple lines with the same item are valid — one per physical block.
• "I use 4 prod-3 modules in all assemblers" → set module_configs["assembling-machine-3"] = [{"count": 4, "type": "prod", "tier": 3, "quality": "normal"}], re-run CLI for all affected lines.
• "I use 3 speed-3 modules in my mining drills" → set module_configs["electric-mining-drill"] = [{"count": 3, "type": "speed", "tier": 3, "quality": "normal"}], re-run CLI for all affected lines (the drill count in miners_needed will reflect the speed bonus).
• "I have 8 beacons with 2 speed-3 modules on each assembler-3" → set beacon_configs["assembling-machine-3"] = {"count": 8, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]}, re-run CLI for all affected lines.
• "I use 4 beacons with 2 speed-3 modules on every machine" → set default_beacon = {"count": 4, "modules": [{"count": 2, "type": "speed", "tier": 3, "quality": "normal"}]}, re-run CLI for all lines.
• "I have N red belts of iron plate on the bus" → add/update bus_items entry: { "item": "iron-plate", "rate": N × 1800 }. Belt throughputs: yellow=900, red=1800, blue=2700, turbo=3600 items/min. For new lines that draw iron-plate from the bus, add --bus-item iron-plate to the CLI call so bus_inputs is populated in the cli_result. If the player says a block has its own supply for an item that's also on the bus, run WITHOUT --bus-item for that item — the item appears in raw_resources instead and Bus Balance is unaffected.
• When adding any new line where bus_items exist: apply --bus-item ITEM for ingredients the player says come from the bus. Mention the assumption once: "I'll assume X, Y come from the bus since they're declared as bus items — let me know if any have their own miners/supply."
• When a new production line is added for a manufactured intermediate (plates, circuits, plastic, etc.), automatically add it to bus_items with the line's effective_rate as the rate. Exception: science packs and other end-product lines are not added to the bus.

Always re-derive bottlenecks after any state change:

• A line is a bottleneck if effective_rate < target_rate * 0.95.
• A raw resource is a bottleneck if the player hasn't confirmed miners/pumps for it yet.

Machine names in bottlenecks and next_steps strings: always use the full kebab-case machine ID (e.g. assembling-machine-3, electric-furnace), never shorthand like AM3. The dashboard's humanizeText() function converts these IDs to friendly names automatically.

4. Answering Planning Questions

Step-by-step

1. Identify the item(s) and rate(s) the player is asking about.
2. Run python assets/cli.py with the appropriate flags from factory state: --assembler, --furnace, --location (when set), --machine-quality, --beacon-quality, --modules MACHINE=... for every entry in module_configs, --beacon BEACON_COUNT:MOD_COUNT:TYPE:TIER:QUALITY if default_beacon is set, --beacon MACHINE=BEACON_COUNT:MOD_COUNT:TYPE:TIER:QUALITY for every entry in beacon_configs, --recipe ITEM=RECIPE for every entry in recipe_overrides.
3. Parse the JSON output.
4. Format a human-readable answer:
   • Lead with the machine count for the target step.
   • Follow with inputs: how many machines/miners for key ingredients.
   • Include belt count for the output, leading with the preferred_belt tier (default blue if unset).
   • Call out any raw resource rates that are large or non-obvious.
5. Update the factory state and chat log.

Answer format (example)

45 automation-science-packs/min needs:

• 3 assembling-machine-3s for automation-science-pack
• 2 assembling-machine-3s for iron-gear-wheel
• 2 electric-furnaces for iron-plate
• 3 electric-mining-drills on iron-ore (60/min)
• Output on yellow belt: 0.05 lanes (trivial — one belt is plenty)

5. Factory Dashboard Artifact

The dashboard is a published application/vnd.ant.html artifact at a permanent URL. Claude does NOT generate or regenerate it during gameplay sessions. The player publishes it once from 10x-factorio-engineer/assets/dashboard.html and it stays live.

Dashboard capabilities

• Reads/writes FACTORY_STATE via window.storage (cross-device, Anthropic server-side) with localStorage fallback for same-device persistence
• In-artifact chat powered by window.claude.complete() — player can ask light questions and report machine placements directly in the dashboard
• Import / Export buttons for syncing state with CLI sessions

State sync: CLI → Dashboard

At the end of a CLI planning session, output the full FACTORY_STATE JSON in a code block so the player can paste it into the dashboard's Import panel:

{
  "save_name": "My Factory",
  "location": null,
  ...
}

State sync: Dashboard → CLI

At the start of a CLI session, ask the player to Export from the dashboard and paste the JSON. Use it as the initial factory state for the session.

When to mention the dashboard

• On session start: "Open your dashboard to follow along."
• At session end: "Here's your updated FACTORY_STATE — paste it into the dashboard Import panel."
• If the player asks "show me the dashboard": remind them to open their published URL.

6. Session Start Protocol

When starting a new session:

1. Greet the player briefly and ask what they're working on today.
2. If they mention an existing factory, ask:
   • Dataset (vanilla / Space Age)?
   • Assembler tier?
   • Using productivity modules?
3. Initialize the factory state and offer to launch the dashboard.

7. Common Workflows

"How many machines do I need for X at Y/min?"