Stop Wiring Combinators by Hand! Factompiler Does It for You

Stop Wiring Combinators by Hand! Factompiler Does It for You

What if I told you that hours of painstaking combinator placement could be reduced to a single command? That the spaghetti nightmare of red and green wires, the mental gymnastics of signal types, the sheer tedium of debugging why your lamp won't blink—all of it could vanish with one simple tool?

Every Factorio player who has ventured into circuit networks knows the pain. You have a brilliant idea: a responsive power grid, a balanced train loader, a dazzling RGB display. Then reality hits. You place the arithmetic combinator. You wire it. You forget which signal carries what. You misclick and connect red instead of green. Three hours later, your "simple" counter has sprawled across twenty tiles of visual chaos, and you're questioning your life choices.

This is exactly why Factompiler exists.

Factompiler—born from the brilliant mind of developer Snagnar—is a compiled language that transforms readable code into optimized Factorio blueprint strings. Write counter.write(counter.read() + 1), run factompile, paste into your game, and watch your circuit hum to life. No manual wiring. No layout headaches. No signal-type amnesia. Just pure, elegant logic that compiles to combinator perfection.

The factory must grow, but your frustration doesn't have to. Let's dive into how this game-changing tool works—and why thousands of Factorio engineers are quietly abandoning hand-built circuits forever.

What Is Factompiler?

Factompiler (often shortened to "Facto") is a domain-specific compiled language that generates Factorio circuit network blueprints. Created by Snagnar and available on GitHub, it represents a radical departure from traditional circuit-building workflows in the legendary factory-building game.

At its core, Factompiler translates high-level code describing circuit logic into precisely placed and wired combinations of arithmetic combinators, decider combinators, constant combinators, and controllable entities. The compiler handles every grungy detail: combinator placement, wire routing (intelligently choosing red versus green to prevent signal collisions), relay pole insertion when distances exceed nine tiles, and even type checking to catch errors before you paste into Factorio.

The project has gained serious traction in the Factorio community for one simple reason: it bridges the gap between how engineers think and how Factorio forces them to work. Instead of reasoning about physical combinator layouts, you reason about signals, memory, conditions, and entities—the actual logic of your circuit. The compiler becomes your tireless intern, translating intentions into implementations.

Factompiler is distributed via PyPI as factompile, supports Python^{↗ Bright Coding Blog} 3.8+, and includes an online compiler for zero-install experimentation. It builds upon the excellent factorio-draftsman library for blueprint generation, standing on the shoulders of open-source giants.

The project's philosophy is deliberately pragmatic: generated circuits may not be absolutely minimal, but they're efficient enough for real gameplay while being vastly easier to create, read, and maintain. When you need that last ounce of optimization, you can always hand-tune the output. But for 95% of circuit designs, Factompiler's output is more than sufficient—and infinitely faster to produce.

Key Features That Make Factompiler Insane

Signal-First Programming Model. Factompiler treats signals as first-class values with explicit types. Write Signal iron = ("iron-plate", 100) and the compiler tracks that type through your entire program. Arithmetic operations like Signal doubled = count * 2 automatically generate the correct arithmetic combinator. Comparisons like Signal isHigh = count > 50 become decider combinators. The language even supports type casting with the pipe operator: Signal copper = iron | "copper-plate".

Intelligent Conditional Values. The condition : value syntax is a stroke of genius. It outputs value when true, zero otherwise—and compiles to a single decider combinator. This is more efficient than the raw Factorio pattern of condition * value, which requires an extra arithmetic combinator for multiplication. Your circuits become cleaner and faster simultaneously.

Persistent Memory Without the Pain. Memory cells in raw Factorio require understanding self-feeding decider combinators—a concept that breaks many brains. In Factompiler, simply declare Memory counter: "signal-A" and use counter.write(counter.read() + 1). The compiler generates the feedback loop automatically. Conditional writes, SR latches, and state machines become readable, maintainable code instead of wire spaghetti.

Entity Control with Dot Notation. Place and control Factorio entities using familiar object syntax. Entity lamp = place("small-lamp", 0, 0) creates the entity; lamp.enable = count > 50 wires its control behavior. The compiler handles all the behind-the-scenes wiring between combinators and entity control ports. Train stops, inserters, power switches—all controllable with clean, logical code.

Bundle Operations for Generic Logic. Bundles leverage Factorio's "each" wildcard to operate on multiple signal types simultaneously. Define Bundle resources = {("iron-plate", 100), ("copper-plate", 80)}, then double everything with Bundle doubled = resources * 2. Check if any resource is low with any(resources) < 20. This is how you build circuits that adapt to any item type without hardcoding each possibility.

Automatic Optimizations. The compiler doesn't just translate naively. Common subexpressions are shared across your program. Compound conditions like (a > 5) && (b < 10) fold into single multi-condition decider combinators (using Factorio 2.0 features). Same-type signal additions use wire merging instead of extra combinators. The result is surprisingly efficient output.

Intelligent Wire Routing. Red versus green wire selection happens automatically to avoid signal conflicts. Medium electric poles appear as relays when combinators exceed nine-tile distances. For complex patterns like balanced loaders, signal merging is handled correctly. You literally never think about wire colors or pole placement.

Real-World Use Cases Where Factompiler Dominates

Responsive Power Grid Management

Raw Factorio's power switch circuits are notoriously finicky. Hysteresis—the pattern of turning on at 20% and off at 80% to prevent flickering—requires SR latches that confuse even experienced players. With Factompiler, the backup steam example becomes readable, maintainable, and correct on the first try. Your power grid responds intelligently without the debugging marathon.

Dynamic Train Loading Systems

The legendary MadZuri balanced loader pattern ensures chests fill evenly, but implementing it manually means wiring multiple inserters with complex enable conditions. Factompiler's bundle operations express this logic cleanly: compute negative averages, compare each chest against it, enable inserters conditionally. The compiler generates the entire multi-inserter setup from a few lines of code.

Visual Status Displays and Alerts

RGB color cycling, resource warning lamps, production monitors—these are the showpieces of advanced Factorio bases. They're also incredibly tedious to wire manually. Factompiler's loop syntax generates grids of lamps automatically, while signal expressions handle color calculations. Your base becomes visually informative without the placement nightmare.

Generic Circuit Templates

Because bundles operate on arbitrary signal types, you can write circuits that work across different factory modules. A resource balancer written for iron plates works unchanged for copper plates, circuits, or any other item. This reusability is nearly impossible with hand-built circuits, where every signal type is hardcoded into combinator configurations.

Step-by-Step Installation & Setup Guide

Getting started with Factompiler takes under two minutes. Here's the complete workflow from zero to functioning circuit.

Prerequisites

• Python 3.8 or newer installed
• Factorio (any recent version, though Factorio 2.0 features enable some optimizations)
• Basic familiarity with Factorio's circuit network concepts (helpful but not required)

Installation

Install from PyPI using pip:

pip install factompile

Verify the installation:

factompile --help

You should see command-line options and usage information. If this fails, ensure your Python scripts directory is on your PATH.

Your First Compilation (No File Required)

Test immediately without creating any files:

factompile -i 'Signal x = 42; Entity lamp = place("small-lamp", 0, 0); lamp.enable = x > 20;'

Copy the output blueprint string, open Factorio, import the blueprint, and place it. You'll see a small lamp that lights up because 42 > 20. Congratulations—you've just compiled code into a working Factorio circuit.

Working with Files

Create blink.facto with this content:

Memory counter: "signal-A";
counter.write((counter.read() + 1) % 20);

Entity lamp = place("small-lamp", 0, 0);
lamp.enable = counter.read() < 30;

Compile and save to a file:

factompile blink.facto -o blink.txt

Or output directly to clipboard (platform-dependent):

# Linux with xclip
factompile blink.facto | xclip -selection clipboard

# macOS
factompile blink.facto | pbcopy

# Windows PowerShell
factompile blink.facto | Set-Clipboard

Advanced CLI Options

# Custom blueprint name for organization
factompile program.facto --name "Nuclear Control Logic"

# Add power poles automatically (useful for large circuits)
factompile program.facto --power-poles medium

# Debug output to understand compiler decisions
factompile program.facto --log-level debug

# Raw JSON output for custom processing
factompile program.facto --json

# Disable optimizations for educational inspection
factompile program.facto --no-optimize

Online Compiler (Zero Install)

Visit https://snagnar.github.io/factompile/ to run Factompiler entirely in your browser. Perfect for quick experiments, sharing with friends, or when you're away from your development machine.

REAL Code Examples from the Repository

Let's examine three actual examples from the Factompiler repository, with detailed explanations of what each accomplishes and how the compiler translates it.

Example 1: Basic Memory Counter with Lamp Control

This is the "hello world" of Factompiler—simple but demonstrating core concepts:

Memory counter: "signal-A";
counter.write((counter.read() + 1) % 20);

Entity lamp = place("small-lamp", 0, 0);
lamp.enable = counter.read() < 30;

Before the code: This creates a blinking lamp pattern. The counter increments every tick, wraps at 20, and enables the lamp when the counter reads below 30. Since the counter never reaches 30 (it wraps at 20), the lamp stays continuously on in this specific case—though the pattern demonstrates the syntax.

How it compiles: The Memory declaration creates a decider combinator configured as a feedback loop. The counter.read() call generates a wire tap from that memory cell's output. The (counter.read() + 1) % 20 expression becomes an arithmetic combinator performing addition and modulo operations. The counter.write(...) call wires this arithmetic combinator's output back to the memory cell's input.

The Entity lamp = place(...) line generates a small lamp entity at coordinates (0, 0). The lamp.enable = counter.read() < 30 assignment creates a decider combinator comparing the counter signal against 30, with its output wired to the lamp's enable control port. The compiler automatically routes all wires, choosing colors to avoid conflicts.

After running: Paste the blueprint, power it, and observe the circuit in action. The counter increments visibly in Factorio's debug view, and the lamp responds to the enable signal.

Example 2: HSV to RGB Color Cycling Display

This advanced example generates a stunning 5×5 RGB lamp grid:

Memory hue: "signal-H";
hue.write((hue.read() + 1) % 1530);  # Full HSV cycle

Signal h = hue.read();
Signal sector = h / 255;
Signal pos = h % 255;

# HSV to RGB conversion using conditional values
Signal r = ((sector == 0 || sector == 5) : 255)
         + ((sector == 1) : (255 - pos))
         + ((sector == 4) : pos);
Signal g = ((sector == 0) : pos)
         + ((sector == 1 || sector == 2) : 255)
         + ((sector == 3) : (255 - pos));
Signal b = ((sector == 2) : pos)
         + ((sector == 3 || sector == 4) : 255)
         + ((sector == 5) : (255 - pos));

for y in 0..5 {
    for x in 0..5 {
        Entity lamp = place("small-lamp", x, y, 
            {use_colors: 1, always_on: 1, color_mode: 1});
        lamp.r = r | "signal-red";
        lamp.g = g | "signal-green";
        lamp.b = b | "signal-blue";
    }
}

Before the code: This creates a smoothly color-cycling 5×5 lamp display. The hue value increments through 1530 steps (6 color sectors × 255 positions each), covering the full HSV color wheel. The nested loops place 25 lamps, each receiving the same RGB color signals.

How it compiles: The Memory hue cell drives the animation timing. The sector and position calculations use arithmetic combinators. The RGB signals are built from multiple conditional value expressions—each (condition : value) becomes a decider combinator outputting the value when true, zero otherwise. The additions combine these partial signals into final color values.

The nested for loops are unrolled at compile time, generating 25 separate place operations with computed coordinates. Each lamp entity receives property assignments for red, green, and blue color channels, with type casting to Factorio's signal types (signal-red, signal-green, signal-blue). The compiler handles the massive wire routing automatically—imagine doing this by hand!

After running: Import and place to see a mesmerizing color cycle across your lamp grid. The display updates every tick with smooth hue transitions.

Example 3: SR Latch for Hysteresis Control

This pattern appears constantly in reliable industrial control systems:

Signal battery = ("signal-A", 0);  # Wire this to your accumulator

Memory steam_on: "signal-A";
steam_on.write(1, set=battery < 20, reset=battery >= 80);

Entity steam_switch = place("power-switch", 0, 0);
steam_switch.enable = steam_on.read() > 0;

Before the code: This implements hysteresis for backup steam power. The steam turns on when accumulator charge drops below 20%, and stays on until charge recovers to 80%. This prevents rapid on-off cycling when charge hovers near a single threshold—a classic engineering problem with a clean Factompiler solution.

How it compiles: The Memory steam_on with set and reset parameters generates an SR latch configuration. Internally, this becomes a decider combinator with feedback: the set condition (battery < 20) forces output to 1, the reset condition (battery >= 80) forces output to 0, and the memory retains state when neither condition is active.

The battery signal declaration creates an input point—wire your accumulator's charge percentage to this network. The power switch entity receives the memory cell's output as its enable signal, completing the control loop.

After running: Wire an accumulator to the input network, connect steam engines to the power switch's output side, and observe reliable hysteresis behavior. Your power grid gains intelligent, flicker-free backup response.

Advanced Usage & Best Practices

Leverage Function Inlining for Reusable Logic. Factompiler functions are inlined at compile time—there's zero runtime overhead. Extract common patterns like clamping, scaling, or deadband filtering into functions. Your source stays DRY while output remains efficient.

Use Bundles for Generic Designs. When you find yourself writing nearly identical logic for different items, refactor to bundles. A single balanced loader design works for any resource type, making your blueprint library vastly more reusable.

Pin Wire Colors for External Integration. When your Factompiler circuit must interface with existing manual wiring, use explicit wire color pinning to prevent conflicts. The compiler respects these constraints while optimizing unrestricted connections.

Start with Online Compiler for Exploration. Before installing, prototype ideas at snagnar.github.io/factompile/. The instant feedback loop accelerates learning dramatically.

Inspect Debug Output to Learn. Run with --log-level debug to see compiler decisions about combinator placement, wire routing, and optimization choices. This builds intuition for how high-level constructs map to low-level Factorio primitives.

Version Control Your .facto Files. Unlike binary blueprints, Factompiler source is human-readable text. Git diff shows exactly what changed between circuit revisions. Code review your factory's logic!

Comparison with Alternatives

Hand-built circuits offer ultimate control but consume enormous time and mental energy. Blueprint libraries provide instant gratification until you need something slightly different—then you're back to manual editing. Factompiler uniquely combines rapid creation, easy modification, parametric reusability, and compile-time safety. The tradeoff is learning a small language, but the productivity multiplier is extraordinary.

FAQ

Does Factompiler work with Factorio 1.1 or only 2.0? Factompiler generates blueprints compatible with both versions. Factorio 2.0 enables some additional optimizations (like multi-condition decider combinators), but all generated circuits function correctly in 1.1.

Can I edit generated blueprints manually after compilation? Absolutely. The output is standard Factorio blueprint format. Hand-tweak for absolute minimalism, or use as-is for immediate deployment. Many users iterate in Factompiler, then apply final polish manually.

How do I debug when my circuit doesn't behave as expected? Use --log-level debug to trace compiler decisions. In Factorio, use the circuit network visualization (Alt-mode) to inspect signal values. The type checker catches many errors before you even paste—read error messages carefully.

Is there IDE support for syntax highlighting? Yes! Install the Facto VS Code extension for syntax highlighting and basic language support. More editor support is community-driven.

Can I import existing blueprints into Factompiler source? Not directly—reverse compilation isn't supported. However, understanding existing blueprints helps you recreate them more cleanly in Factompiler. The language spec and examples cover common patterns.

Does Factompiler support multiplayer and modded Factorio? Generated blueprints work in multiplayer. Modded entities are supported if they're in the entity reference; check doc/ENTITY_REFERENCE.md or extend as needed.

How active is development? Should I depend on this for long-term projects? The project shows healthy activity with CI pipelines, code coverage tracking, and responsive issue management. As with any open-source tool, pin your dependency versions and participate in the community to ensure longevity.

Conclusion: The Factory Must Grow—Faster

Factompiler represents a genuine paradigm shift for Factorio circuit design. By treating combinators as compilation targets rather than manual construction materials, it liberates engineers to focus on what matters: the logic that makes factories intelligent, responsive, and beautiful.

The evidence is overwhelming. Hours become minutes. Debugging becomes reading type errors. Spaghetti becomes structured code. Reuse becomes copy-paste of text files rather than fragile blueprint modifications.

My honest assessment? If you build circuits in Factorio with any regularity, learning Factompiler pays for itself within your first serious project. The initial language learning curve is modest—smaller than mastering raw combinator behavior—and the productivity dividend compounds forever.

Ready to stop wiring combinators by hand? Clone the repository, pip install factompile, or try the online compiler right now. Your future self—staring at a clean, working circuit that took five minutes instead of five hours—will thank you.

The factory must grow. Now it can grow faster.