How to build your own Factorio mods

Factorio’s modding system is one of the game’s strengths: data-driven prototypes in Lua, a clear load order, and a first-party Mod Portal. This guide is a practical map of how to build your own mod—from a minimal hello-world package to something you can share—without drowning in every API edge case.

What a mod can change

Mods typically do one or more of:

Add or tweak items, recipes, entities, technologies, and UI (data stage).

React to players and the running world—events, commands, GUI (control / runtime stage).

Ship locale strings, thumbnails, and settings players can toggle.

Cosmetic HUD mods, quality-of-life helpers, overhaul packs, and planet/content expansions all use the same packaging rules; they differ in how much prototype data and runtime logic they ship.

Tools you need

A legal Factorio install (Steam or standalone) matching the API you target (1.1 vs 2.0 / Space Age).

A text editor with Lua support (VS Code is common).

Optional: the Factorio Modding Toolkit / community formatters, and git for version control.

You do not need a separate compiler. Factorio loads Lua packages from a mods folder (or zips) at startup.

Anatomy of a mod

A minimal mod is a folder (or `.zip`) whose name usually includes the version, containing at least:

info.json

Manifest metadata: unique name, version, title, author, Factorio version factor, description, and dependencies. Wrong `factorio_version` or dependency ranges is the #1 reason a mod fails to appear or load.

Thumbnail (optional but expected for Portal mods)

A small image so players recognize your mod in lists.

data.lua / data-updates.lua / data-final-fixes.lua

Prototype definitions and edits. Load order across mods is controlled by dependencies and these three phases so overhaul packs can resolve conflicts predictably.

control.lua

Runtime scripts: event handlers (`on_built_entity`, research finished, player created, etc.). Not every mod needs this—pure recipe packs may be data-only.

locale/

Translated strings. Even English-only mods should ship locale files so names stay consistent.

settings.lua (optional)

Startup / runtime settings exposed in the options UI.

Data stage vs control stage

This distinction is the core mental model:

Data stage runs when the game loads mods—before a save exists. You define what exists (prototypes). You cannot touch players or a live surface here.

Control stage runs in a loaded game. You respond to events and mutate the world. You cannot invent new prototype types here; you only use what data stage registered.

Newcomers often try to “create an item” from `control.lua`. That belongs in `data.lua`. Conversely, “give the player an item when they finish a research” belongs in control.

Dependencies and compatibility

Declare hard dependencies when you require another mod’s prototypes. Use optional dependencies when you integrate if present. Overhaul mods should be explicit; QoL mods should avoid hard-locking the entire ecosystem.

Test against:

Vanilla (and Space Age if you claim support).

A small set of popular QoL mods your audience likely runs.

Multiplayer if you touch sync-sensitive state—desyncs are usually “I stored non-deterministic data” bugs.

Creating a minimal first mod

1. Create a folder under your user mods directory named like `my-first-mod_0.1.0`.

2. Add `info.json` with a unique `name`, `version`, `title`, `author`, and compatible `factorio_version`.

3. Add `data.lua` that either adds a trivial recipe/item or logs nothing—just enough to prove load.

4. Enable the mod in the Factorio mods UI and restart.

5. Check `factorio-current.log` if it fails—almost always JSON typos, bad paths, or version mismatches.

Iterate in tiny steps. A loading error with a clear stack beat a 2,000-line mystery crash.

Testing blueprints with your mod

Blueprints store entity and recipe names. If your mod renames or removes prototypes, old strings break. If you add entities, Beltworks users need your mod installed to import those designs.

Good habits:

Prefer additive content over renaming vanilla internals.

Version your mod carefully; note breaking changes in the changelog.

When you publish a showcase blueprint on Beltworks, list required mods and versions in the description.

Packaging and the Mod Portal

For distribution, zip the mod so the archive root contains `info.json` (not an extra nested junk folder). Upload through Wube’s Mod Portal with a clear description, screenshots, and license notes.

Semantic versioning helps players and dependency declarations: bump minor for features, major for breaking prototype changes.

Performance and multiplayer ethics

Avoid per-tick work without need; event-driven logic scales better.

Do not hide malicious behavior in mods—Wube and the community take this seriously.

Keep network-safe state for MP; local-only assumptions cause desyncs.

Learning path (authoritative sources)

1. Ship the minimal mod above so packaging is muscle memory.

2. Read Wube’s official modding documentation for data stages, events, and style.

3. Study a small published QoL mod’s source on the Portal or GitHub to see real structure.

4. Only then attempt an overhaul or new planet-scale content.

How this fits Beltworks

Beltworks hosts blueprint strings. Mods change which strings are legal. If you are building content mods, treat blueprints as part of your release: example builds, starter books, and migration notes. Link those releases on Beltworks with accurate mod requirements so players are not stuck debugging console errors that are really missing dependencies.

Summary

A Factorio mod is a versioned Lua package with `info.json`, optional data and control scripts, and clear dependencies. Master the data-vs-control split, test on disposable saves, publish through the Mod Portal, and document blueprint prerequisites when your content adds new entities. That workflow—not clever one-liners—is what separates a weekend experiment from a mod people trust.