How to build your own Factorio mods

This is a do-it-yourself walkthrough. You will install two programs, download a working starter mod, drop it into Factorio’s mods folder, enable it, and confirm a new recipe appears in-game. Then you edit the files.

Programs to install

1. Factorio 2.0 (Steam or standalone) — the game loads your Lua; there is no separate compiler. Space Age is optional for this hello mod.

2. [Visual Studio Code](https://code.visualstudio.com/) — free editor. After install, open Extensions (Ctrl/Cmd+Shift+X) and install Sumneko Lua (publisher: sumneko) for syntax highlighting.

Optional later: Git for version control, and a Wube account on the Factorio Mod Portal when you are ready to publish.

Find your mods folder

Factorio reads mods from the user data directory (not the Steam install folder):

Windows: %APPDATA%\Factorio\mods — paste that into File Explorer’s address bar.

macOS: ~/Library/Application Support/factorio/mods — in Finder: Go → Go to Folder… and paste the path.

Linux: ~/.factorio/mods

If the mods folder does not exist, create it. Log files live next to it (factorio-current.log) when something fails to load.

Official reference: Application directory and Mod structure.

Download the starter mod

Beltworks ships a complete tiny mod you can install as-is:

Zip (easiest): bw-hello-mod_0.1.0.zip — drop this file into the mods folder.

Unpacked files: browse the folder — or copy that folder into mods as bw-hello-mod_0.1.0.

What it does: adds an unlocked recipe Hello gears — 1 iron plate → 2 iron gear wheels — and prints a welcome line when you create a new player.

Enable it in Factorio

1. Quit Factorio completely if it is open.

2. Put bw-hello-mod_0.1.0.zip (or the bw-hello-mod_0.1.0 folder) inside your mods directory from the section above.

3. Launch Factorio → Mods (main menu).

4. Find Beltworks Hello Mod, enable it, confirm, let the game reload.

5. Start a new freeplay / sandbox save (or load an existing one).

6. You should see the welcome print. Open crafting and search Hello gears. Craft it once with an iron plate in inventory.

If the mod is missing from the list: folder/zip name is wrong, or info.json failed to parse — open factorio-current.log in the Factorio user data folder and search for bw-hello-mod.

Open the files in VS Code

1. In VS Code: File → Open Folder… and select …/mods/bw-hello-mod_0.1.0 (unzip first if you only have the zip).

2. You should see these files:

bw-hello-mod_0.1.0/
  info.json
  data.lua
  control.lua
  locale/en/bw-hello-mod.cfg

info.json (required)

Identity for the game and Mod Portal. name must match the folder/zip prefix. factorio_version is "2.0" for current Factorio.

{
  "name": "bw-hello-mod",
  "version": "0.1.0",
  "title": "Beltworks Hello Mod",
  "author": "Beltworks",
  "factorio_version": "2.0",
  "description": "Starter example from the Beltworks modding guide.",
  "dependencies": ["base >= 2.0.0"]
}

data.lua (prototypes)

Runs at load time. This is where items, recipes, entities, and technologies are defined — not in control.lua.

data:extend({
  {
    type = "recipe",
    name = "bw-hello-gears",
    localised_name = {"recipe-name.bw-hello-gears"},
    category = "crafting",
    enabled = true,
    energy_required = 0.5,
    ingredients = {
      { type = "item", name = "iron-plate", amount = 1 }
    },
    results = {
      { type = "item", name = "iron-gear-wheel", amount = 2 }
    }
  }
})

control.lua (runtime)

Runs inside a save. Use events for players and the world. You cannot invent new prototype types here.

script.on_event(defines.events.on_player_created, function(event)
  local player = game.get_player(event.player_index)
  if not player then return end
  player.print({"bw-hello-mod.welcome"})
end)

locale/en/bw-hello-mod.cfg

[recipe-name]
bw-hello-gears=Hello gears (Beltworks example)

[bw-hello-mod]
welcome=bw-hello-mod loaded. Open crafting and search for Hello gears.

Change something (your first edit)

1. In data.lua, change amount = 2 on the gear result to amount = 5.

2. Save the file.

3. In Factorio: Mods → Sync / restart so data stage reloads (or quit and relaunch).

4. Craft Hello gears again — you should get 5 gears per plate.

That loop — edit Lua → reload mods → test in a throwaway save — is the whole development workflow.

Data stage vs control stage

Data (data.lua, data-updates.lua, data-final-fixes.lua): what exists (prototypes). No players, no surfaces.

Control (control.lua): what happens in a running game (events, GUI, commands).

Wrong stage is the #1 beginner bug: “create an item” belongs in data; “give the player an item on research” belongs in control.

Package a zip yourself

When you bump the version in info.json (for example to 0.1.1):

1. Rename the folder to bw-hello-mod_0.1.1 (name_version).

2. Zip so the archive contains that folder at the top level.

macOS / Linux:

cd ~/Library/Application\ Support/factorio/mods
zip -r bw-hello-mod_0.1.1.zip bw-hello-mod_0.1.1

Windows (PowerShell from the mods folder):

Compress-Archive -Path .\bw-hello-mod_0.1.1 -DestinationPath .\bw-hello-mod_0.1.1.zip

Publish on the Mod Portal

1. Create an account at mods.factorio.com.

2. Upload the zip (name_version.zip).

3. Add a description, optional thumbnail.png (about 144×144), and a changelog.txt if you want history in-game.

Portal rules and API docs: lua-api.factorio.com — start with Tutorials and Prototype definitions.

Blueprints and mods

Blueprint strings store prototype names. If your mod adds entities, players need your mod installed to import those designs on Beltworks. Prefer additive content over renaming vanilla internals, and list required mods on the print page.

What to build next

1. Change the hello recipe ingredients/results again and reload.

2. Add a second recipe in the same data:extend({ ... }) table.

3. Read Wube’s mod structure and open any small QoL mod’s zip from the Portal to compare file layouts.

4. Only then add settings (settings.lua) or custom entities.