Official Factorio Wiki - User contributions [en]

Console

2026-01-26T00:32:56Z

PennyJim: Add evolution surface parameter

{{Languages}}
The '''console''' is Factorio's in-game command-line interface. See [[command line parameters]] for the command line interface of the Factorio executable.

The in-game console can be used for:

* Chatting with other players
* Occasional status updates
* Running commands / scripts / cheats

There are three types of commands:

* '''[[#Normal commands|Normal]]''' - Display information about the game and customize your experience.
* '''[[#Multiplayer commands|Multiplayer]]''' - Message filtering, banning users, etc.
* '''[[#Scripting and cheat commands|Scripting/Cheating]]''' - Run small Lua scripts (but they disable achievements for the save game)

__TOC__

=== Using the console ===
The console display can be toggled with the {{Keybinding|grave}} key (<code>`</code>). This is the key located to the left of the <code>1</code> key, above <code>Tab</code>.

You can customize the keys via '''Settings menu → Controls → Toggle chat (and Lua console)'''.
When the console is open, you'll see a blinking cursor at the bottom of the screen; type your message or command and hit '''Return''' to send it (this will also close the console).
Documentation about message and command prefixes can be found further down this page.

The console supports [[rich text]] tags. These tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations. Ctrl + Alt-clicking the map or ground will automatically insert a GPS tag and post it into the console. Shift-clicking most things with the console open will insert a tag for that thing into the console.

When the console is closed, only the most recent messages/commands will be displayed, but they will gradually fade away (opening the console will immediately re-display all recent messages).
Note that by default, all executed commands are made visible to all users. The fade-out time can be changed via '''Settings menu → Interface → Chat message delay'''.

The console can be cleared with the '''/clear''' command.

Use the {{keybinding|↑}} and {{keybinding|↓}} keys to scroll through the console history. The {{keybinding|Tab}} key provides intelligent code completion on commands, options and player names.

== Normal commands ==

{| class="wikitable"
|-
! style="width:25%"| Command
! style="width:25%"| Example
! style="width:46%"| Description
! style="width:4%"| Admin only
|-
| /alerts <enable/disable/mute/unmute> <alert>
| /alerts disable turret_fire
| Enables, disables, mutes, or unmutes the given [[alerts|alert]] type. Available alerts: entity_destroyed, entity_under_attack, not_enough_construction_robots, no_material_for_construction, not_enough_repair_packs, platform_tile_building_blocked, turret_out_of_ammo, turret_fire, custom, no_storage, train_out_of_fuel, train_no_path, no_platform_storage, collector_path_blocked, unclaimed_cargo, no_roboport_storage, pipeline_overextended.
| No
|-
| /clear
| /clear
| Clears the console.
| No
|-
| /color <color>
| /color 20 255 255
| Changes your color. Can either be one of the pre-defined colors or [[:Wikipedia:RGB_color_space|RGB value]] in the format of “# # #”. Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
| No
|-
| /evolution [surface]
| /evolution nauvis
| Prints info about the alien evolution factor for all surfaces or optionally only the given one.
| No
|-
| /help [command]
| /help
| Prints a list of available commands, the optional argument can specify the command that should be described.
| No
|-
| /h [command]
| /h
| Same as /help.
| No
|-
| /mute-programmable-speaker <mute/unmute> <local/everyone>
| /mute-programmable-speaker mute local
| Mutes or unmutes the global sounds created by the Programmable Speaker. Use “local” to mute just the local client. Admins can use “everyone” to mute the sounds for everyone on the server.
| No
|-
| /perf-avg-frames <number>
| /perf-avg-frames 100
| Number of ticks/updates used to average performance counters. Default is 100. Value of 5-10 is recommended for fast convergence, but numbers will jitter more rapidly.
| No
|-
| /permissions
| /permissions
| Opens the [[permissions]] GUI.
| Yes
|-
| /permissions <action> <parameters>
| /permissions add-player DeveloperGroup kovarex
| Available actions are add-player <group> <player>, create-group <name>, delete-group <group>, edit-group <group> <input_action> <true/false>, get-player-group <player>, remove-player <group> <player>, rename-group <group> <new_name> and reset
| Yes
|-
| /reset-tips
| /reset-tips
| Resets the state of the tips and tricks as if the game was just started for the first time.
| No
|-
| /screenshot [x resolution] [y resolution] [zoom]
| /screenshot
| Takes a screenshot with the GUI hidden, centered on the player. It is saved in the "script-output" subfolder of your [[User data directory]]. Resolution is optional and defaults to the current window size. Zoom is optional and defaults to 1.
| No
|-
| /seed
| /seed
| Prints the starting map seed.
| No
|-
| /time
| /time
| Prints info about how old the map is.
| No
|-
| /toggle-action-logging
| /toggle-action-logging
| Toggles logging all input actions performed by the game. This value isn’t persisted between game restarts and only affects your local game in multiplayer sessions.
| Yes
|-
| /toggle-heavy-mode
| /toggle-heavy-mode
| Used to investigate [[Desynchronization#Using_heavy_mode_command|desyncs]]. Will slow down the game and make multiplayer unplayable.
| Yes
|-
| /unlock-shortcut-bar
| /unlock-shortcut-bar
| Unlocks all [[shortcut bar]] items, including blueprint string import, copy & paste, deconstruction and upgrade planner.
| No
|-
| /unlock-tips
| /unlock-tips
| Unlocks all tips and tricks entries.
| No
|-
| /version
| /version
| Prints the current game version.
| No
|-
|}

== Multiplayer commands ==
{| class="wikitable"
|-
! style="width:25%"| Command
! style="width:25%"| Example
! style="width:46%"| Description
! style="width:4%"| Admin only
|-
| <message>
| Hello team!
| Console input that does not start with {{keybinding|/}} is shown as a chat message to your team.
| No
|-
| /admin
| /admin
| Opens the player management GUI.
| Yes
|-
| /admins
| /admins
| Prints a list of game admins.
| No
|-
| /ban <player> <reason>
| /ban xTROLLx Throwing grenades in base
| Bans the specified player.
| Yes
|-
| /bans
| /bans
| Prints a list of banned players.
| No
|-
| /banlist <add/remove/get/clear> <player>
| /banlist get
| Adds or removes a player from the banlist. Same as /ban or /unban.
| No
|-
| /config
| /config
| Opens the server configuration GUI.
| Yes
|-
| /config <get/set> <option> <value>
| /config set password hunter2
| Gets or sets various multiplayer game settings. Available configs are: afk-auto-kick, allow-commands, allow-debug-settings, autosave-interval, autosave-only-on-server, ignore-player-limit-for-returning-players, max-players, max-upload-speed, only-admins-can-pause, password, require-user-verification, visibility-lan, visibility-public. The units for the options afk-auto-kick and autosave-interval are in minutes.
| Yes
|-
| /delete-blueprint-library <player>
| /delete-blueprint-library everybody confirm
| Deletes the blueprint library storage for the given offline player from the save file. Enter “everybody confirm” to delete the storage of all offline players.
| Yes
|-
| /demote <player>
| /demote AzureDiamond
| Demotes the player from admin.
| Yes
|-
| /ignore <player>
| /ignore Cthon98
| Prevents the chat from showing messages from this player. Admin messages are still shown.
| No
|-
| /ignores
| /ignores
| Prints a list of ignored players.
| No
|-
| /kick <player> <reason>
| /kick xTROLLx Throwing grenades in base
| Kicks the specified player.
| Yes
|-
| /mute <player>
| /mute Cthon98
| Prevents the player from saying anything in chat.
| Yes
|-
| /mutes
| /mutes
| All players that are muted (can’t talk in chat).
| No
|-
| /open <player>
| /open AzureDiamond
| Opens another player’s inventory.
| Yes
|-
| /o <player>
| /o AzureDiamond
| Same as /open.
| Yes
|-
| /players [online/o/count/c]
| /players
| Prints a list of players in the game. (parameter online/o, it prints only players that are online, count/c prints only count)
| No
|-
| /p [online/o/count/c]
| /p o c
| Same as /players.
| No
|-
| /promote <player>
| /promote AzureDiamond
| Promotes the player to admin.
| Yes
|-
| /purge <player>
| /purge Cthon98
| Clears all the messages from this player from the chat log.
| Yes
|-
| /reply <message>
| /reply oh, really?
| Replies to the last player that whispered to you.
| No
|-
| /r <message>
| /r oh, really?
| Same as /reply.
| No
|-
| /server-save
| /server-save
| Saves the game on the server in a multiplayer game.
| Yes
|-
| /shout <message>
| /shout Hello world!
| Sends a message to all players including other forces.
| No
|-
| /s <message>
| /s Hello world!
| Same as /shout.
| No
|-
| /swap-players <player> [player]
| /swap-players AzureDiamond
| Swaps your character with the given player’s character, or if two players are given swaps the two player characters.
| Yes
|-
| /unban <player>
| /unban xTROLLx
| Unbans the specified player.
| Yes
|-
| /unignore <player>
| /unignore Cthon98
| Allows the chat to show messages from this player.
| No
|-
| /unmute <player>
| /unmute Cthon98
| Allows the player to talk in chat again.
| Yes
|-
| /whisper <player> <message>
| /whisper AzureDiamond that's what I see
| Sends a message to the specified player.
| No
|-
| /w <player> <message>
| /w AzureDiamond that's what I see
| Same as /whisper.
| No
|-
| /whitelist <add/remove/get/clear> [player]
| /whitelist get
| Adds or removes a player from the whitelist, where only whitelisted players can join the game. Enter nothing for “player” when using “get” to print a list of all whitelisted players. An empty whitelist disables the whitelist functionality allowing anyone to join.
| No
|}

== Scripting and cheat commands ==
{| class="wikitable"
|-
! Command
! Description
|-
| /cheat [all/<planet-name>/<platform-name>/off]
| Researches all technologies and enables cheat mode (allowing free crafting of any item).
* Using the '''all''' option also gives the player some additional items.
* Specifying a ''planet-name'' or ''platform-name'' also moves the player to the origin of the specified planet or platform.
* Using the '''off''' option turns cheat mode off.
|-
| /command <command>
| Executes a Lua command (if allowed).
|-
| /c <command>
| Executes a Lua command (if allowed).
|-
| /editor
| Toggles the map editor.
|-
| /measured-command <command>
| Executes a Lua command (if allowed) and measures time it took.
|-
| /mc <command>
| Executes a Lua command (if allowed) and measures time it took.
|-
| /silent-command <command>
| Executes a Lua command (if allowed) without printing it to the console.
|-
| /sc <command>
| Executes a Lua command (if allowed) without printing it to the console.
|}

This is a very powerful feature, which also allows cheating, and as such achievements will be permanently disabled for the save as soon as you use a script command.

== Basic example scripts ==

=== Use it as calculator ===
<syntaxhighlight lang="lua">
/c game.player.print(1234*5678)
</syntaxhighlight>

=== Zoom beyond normal bounds ===
Note that zooming too far out can cause performance hits. Be careful.
<syntaxhighlight lang="lua">
/c game.player.zoom=0.1
</syntaxhighlight>
In freeplay, the farthest you can zoom out is 0.3. In the map editor, it is 0.1. Smaller zoom values will be clamped.

=== Mine faster ===
<syntaxhighlight lang="lua">
/c game.player.force.manual_mining_speed_modifier=1000
</syntaxhighlight>

=== Craft faster ===
<syntaxhighlight lang="lua">
/c game.player.force.manual_crafting_speed_modifier=1000
</syntaxhighlight>

=== Unlock and research all technologies ===
<syntaxhighlight lang="lua">
/c game.player.force.research_all_technologies()
</syntaxhighlight>

Undo this with the command in the next section.

Note: Specific technologies can be researched using the [[map editor]] by shift clicking the "start research" button on the technology GUI.

=== Unresearch all technologies ===
This does not reset manually applied bonuses
<syntaxhighlight lang="lua">
/c for _, tech in pairs(game.player.force.technologies) do
tech.researched=false
end
</syntaxhighlight>

Note: Specific technologies can be unresearched using the [[map editor]] by clicking the "un-research" button on the technology GUI.

=== Reset your force ===
This resets all data for your force, including kill and production statistics, technologies, bonuses and charting status.
<syntaxhighlight lang="lua">
/c game.player.force.reset()
</syntaxhighlight>

=== Always show rail block visualization ===
Permanently show the rail block visualization instead of only when holding a rail signal. Disable by replacing true with false.

<syntaxhighlight lang="lua">
/c game.player.game_view_settings.show_rail_block_visualisation = true
</syntaxhighlight>

=== Set all trains to Automatic mode ===
Set all trains to automatic mode - for example after building them with a blueprint.

<syntaxhighlight lang="lua">
/c for key,ent in pairs (game.player.surface.find_entities_filtered{name="locomotive"}) do
ent.train.manual_mode = false
end
</syntaxhighlight>

== Inventory manipulation scripts ==

=== Cheat mode ===
Allows for infinite free crafting. Disable by replacing true with false.
<syntaxhighlight lang="lua">
/c game.player.cheat_mode=true
</syntaxhighlight>

=== Refill resources (refill oil, iron etc.) ===
While holding the cursor over a resource tile in-game:
<syntaxhighlight lang="lua">
/c game.player.selected.amount=7500
</syntaxhighlight>

Alternatively you can refill all resources in the map with the following command. Change ore.amount to the desired value.
<syntaxhighlight lang="lua">
/c surface = game.player.surface
for _, ore in pairs(surface.find_entities_filtered({type="resource"})) do
ore.amount = 10000
end
</syntaxhighlight>

=== Add items to the player's inventory ===
Replace iron-plate with the [[data.raw|internal name]] of the item desired.
<syntaxhighlight lang="lua">
/c game.player.insert{name="iron-plate", count=100}
</syntaxhighlight>

For instance, here's a stack of the god-mode energy system interface:
<syntaxhighlight lang="lua">
/c game.player.insert{name="electric-energy-interface"}
</syntaxhighlight>

There are several god-mode items available:

* <code>infinity-chest</code>
* <code>infinity-pipe</code>
* <code>electric-energy-interface</code>
* <code>heat-interface</code>

Add a powerful armor with equipment and some tools for construction:
<syntaxhighlight lang="lua">
/c local player = game.player
player.insert{name="power-armor-mk2", count = 1}
local p_armor = player.get_inventory(5)[1].grid
p_armor.put({name = "fission-reactor-equipment"})
p_armor.put({name = "fission-reactor-equipment"})
p_armor.put({name = "fission-reactor-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "energy-shield-mk2-equipment"})
p_armor.put({name = "energy-shield-mk2-equipment"})
p_armor.put({name = "personal-roboport-mk2-equipment"})
p_armor.put({name = "night-vision-equipment"})
p_armor.put({name = "battery-mk2-equipment"})
p_armor.put({name = "battery-mk2-equipment"})
player.insert{name="construction-robot", count = 25}
</syntaxhighlight>

Adding [[Quality|higher quality]] items looks like this:
<syntaxhighlight lang="lua">
/c game.player.insert{name="iron-plate", quality="legendary", count=100}
</syntaxhighlight>

=== Increase player inventory slots ===
Gives 100 additional bonus inventory slots to your entire force. Used by the [[Toolbelt (research)]].
<syntaxhighlight lang="lua">
/c game.player.force.character_inventory_slots_bonus=100
</syntaxhighlight>

== World manipulation scripts ==

=== Reveal the map around the player ===

Reveals the map around the player, similar to a [[radar]].
<syntaxhighlight lang="lua">
/c local radius=150
game.player.force.chart(game.player.surface, {{game.player.position.x-radius, game.player.position.y-radius}, {game.player.position.x+radius, game.player.position.y+radius}})
</syntaxhighlight>
or from start position
<syntaxhighlight lang="lua">
/c local radius=150
game.player.force.chart(game.player.surface, {{x = -radius, y = -radius}, {x = radius, y = radius}})
</syntaxhighlight>
Change 150 to the desired radius, higher values take longer.

=== Hide revealed map ===

Hides all revealed chunks, inverted map revealing.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local force = game.player.force
for chunk in surface.get_chunks() do
force.unchart_chunk({x = chunk.x, y = chunk.y}, surface)
end
</syntaxhighlight>

=== Reveal all generated map ===

Revels all of the generated map to the player's team.
<syntaxhighlight lang="lua">
/c game.player.force.chart_all()
</syntaxhighlight>

=== Delete chunks ===
If much of the map is revealed, it increases the size of the save file. The following command cancels the generation of all chunks that are currently queued for generation and removes chunks outside a 32 chunks radius around 0,0. Note that this will remove player entities if there are any on these chunks.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface;
game.player.force.cancel_charting(surface);
local chunk_radius = 32;
for chunk in surface.get_chunks() do
if (chunk.x < -chunk_radius or chunk.x > chunk_radius or chunk.y < -chunk_radius or chunk.y > chunk_radius) then
surface.delete_chunk(chunk)
end
end
</syntaxhighlight>

=== Delete unrevealed chunks ===
This command deletes chunks that are not revealed by the player. Can be used after the command for [[#Hide revealed map|hiding revealed map]] to delete the chunks not covered by radar.

<syntaxhighlight lang="lua">/c local surface = game.player.surface
local force = game.player.force
for chunk in surface.get_chunks() do
if not force.is_chunk_charted(surface, chunk) then
surface.delete_chunk(chunk)
end
end</syntaxhighlight>

=== Turn off night ===
Enables eternal day.
<syntaxhighlight lang="lua">
/c game.player.surface.always_day=true
</syntaxhighlight>

=== Change game speed ===
0.5 is half speed, 1 is default, 2 is double speed, etc. Minimum is 0.01. This can be used for a lot of things like when you know you will have to wait for long periods of time for something to complete. Increasing will decrease performance, be careful.
<syntaxhighlight lang="lua">
/c game.speed=X
</syntaxhighlight>

=== Freeze time ===
Stops the advancement of the time. Unfreezes it if you by replace "true" with "false".
<syntaxhighlight lang="lua">
/c game.player.surface.freeze_daytime=true
</syntaxhighlight>

=== Remove all pollution ===
<syntaxhighlight lang="lua">
/c game.player.surface.clear_pollution()
</syntaxhighlight>

=== Completely turn off pollution ===

<syntaxhighlight lang="lua">
/c for _, surface in pairs(game.surfaces) do
surface.clear_pollution()
end
game.map_settings.pollution.enabled = false
</syntaxhighlight>

=== Add a lot of pollution ===
<syntaxhighlight lang="lua">
/c game.player.surface.pollute(game.player.position, 1000000)
</syntaxhighlight>

=== Where speakers are, who placed them ===
<syntaxhighlight lang="lua">
/c local speakers = game.player.surface.find_entities_filtered{force = game.player.force, type="programmable-speaker"}
for key, speaker in pairs(speakers) do
game.player.print(speaker.last_user.name .. " placed a speaker at " .. speaker.gps_tag)
end
</syntaxhighlight>

=== Disable friendly fire for your force ===
<syntaxhighlight lang="lua">
/c game.player.force.friendly_fire = false
</syntaxhighlight>

=== Add new resource patch ===
This creates a new 11×11 patch of resources, centered on the player character, where the ground is not water.
The patch it creates is perfectly square but it randomizes the amount similar to natural generation, with fewer ore at the edges and more ore in the center.
The default numbers result in a patch with 2500-3000 ore.

If you want a larger patch, change "local size = 5" to a larger number.
A larger patch will have exponentially more ore.
Entering a number above 30 is not recommended.

If you want a richer patch, change "local density = 10" to a larger number.
Entering a very large number shouldn't hurt anything but you probably don't need to go above 100.

To choose which resource is spawned, change "stone" near the bottom to "iron-ore", "copper-ore", "coal", or "uranium-ore".

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local ore=nil
local size=5
local density=10
for y=-size, size do
for x=-size, size do
a=(size+1-math.abs(x))*10
b=(size+1-math.abs(y))*10
if a<b then
ore=math.random(a*density-a*(density-8), a*density+a*(density-8))
end
if b<a then
ore=math.random(b*density-b*(density-8), b*density+b*(density-8))
end
if surface.get_tile(game.player.position.x+x, game.player.position.y+y).collides_with("ground_tile") then
surface.create_entity({name="stone", amount=ore, position={game.player.position.x+x, game.player.position.y+y}})
end
end
end
</syntaxhighlight>

For more flexibility, the [[map editor]] can also be used to create/alter/remove resource patches.

=== Remove resources around the player ===
Removes all resource patches from the ground in a 50 x 50 area around the player.

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local size=50
local pos=game.player.position

for _, e in pairs(surface.find_entities_filtered{area={{pos.x-size, pos.y-size},{pos.x+size, pos.y+size}}, type="resource"})
do e.destroy()
end
</syntaxhighlight>

=== Add new oil patch ===
This creates 9 crude oil patches in a 3×3 square.
<syntaxhighlight lang="lua">
/c for y=0,2 do
for x=0,2 do
game.player.surface.create_entity({name="crude-oil", amount=100000, position={game.player.position.x+x*7-7, game.player.position.y+y*7-7}})
end
end
</syntaxhighlight>

or randomly without any collision:
<syntaxhighlight lang="lua">
/c local position=nil
for i=1,9 do
position=game.player.surface.find_non_colliding_position("crude-oil", game.player.position, 0, i/2+1.5)
if position then
game.player.surface.create_entity({name="crude-oil", amount=100000, position=position})
end
end
</syntaxhighlight>

=== Add new water patch ===

This creates a small pond in a 4x2 square.
<syntaxhighlight lang="lua">
/c
local waterTiles = {}
for y=2,4 do
for x=-2,2 do
table.insert(waterTiles, {name="water", position={game.player.position.x+x, game.player.position.y+y}})
end
game.player.surface.set_tiles(waterTiles)
end
</syntaxhighlight>

=== Regenerate resources ===
For solid resources like iron, destroys all resource entities and creates resource entities as in the original map generation. For fluid resources like oil, sets the yield of all existing resource entities to the original amount. Regenerates resources on the entire surface.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
for _, e in pairs(surface.find_entities_filtered{type="resource"}) do
if e.prototype.infinite_resource then
e.amount = e.initial_amount
else
e.destroy()
end
end
local non_infinites = {}
for resource, prototype in pairs(prototypes.get_entity_filtered{{filter="type", type="resource"}}) do
if not prototype.infinite_resource then
table.insert(non_infinites, resource)
end
end
surface.regenerate_entity(non_infinites)
for _, e in pairs(surface.find_entities_filtered{type="mining-drill"}) do
e.update_connections()
end
</syntaxhighlight>

=== Count entities ===
Counts all entities whose name includes the string in local entity.
<syntaxhighlight lang="lua">
/c local entity="belt"
local surface=game.player.surface
local count=0
for key, ent in pairs(surface.find_entities_filtered({force=game.player.force})) do
if string.find(ent.name,entity) then
count=count+1
end
end
game.player.print(count)
</syntaxhighlight>

=== Turn off cliff generation ===
Sets size to "none". Only effective on chunks that are generated after using this command. Use [[#Remove all cliffs]] to delete existing cliffs.

<syntaxhighlight lang="lua">
/c local mgs = game.player.surface.map_gen_settings
mgs.cliff_settings.cliff_elevation_0 = 1024
game.player.surface.map_gen_settings = mgs</syntaxhighlight>

=== Remove all cliffs ===
Removes all cliffs existing cliffs from the world. Use [[#Turn off cliff generation]] to turn off cliff generation in new chunks.

<syntaxhighlight lang="lua">
/c for _, v in pairs(game.player.surface.find_entities_filtered{type="cliff"}) do
v.destroy()
end</syntaxhighlight>

=== Delete all decoratives ===
Delete the decoratives that can be found in the world.

<syntaxhighlight lang="lua">
/c game.player.surface.destroy_decoratives({})</syntaxhighlight>

=== Change map generation settings ===
This allows to change the map generation settings for new chunks; it does not alter already generated chunks. [[#Delete chunks|Deleted chunks]] are affected by the setting change because they are newly generated when they get explored again.

To change resource generation settings, replace "iron-ore" with the [[Data.raw#resource|resource]] that should be changed and replace "very-high" with the desired [https://lua-api.factorio.com/latest/concepts/MapGenSize.html MapGenSize] in the following command. Replace "iron-ore" with "enemy-base" to change the enemy base generation settings.

<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local resource = "iron-ore"
local mgs = surface.map_gen_settings
mgs.autoplace_controls[resource].size = "very-high"
mgs.autoplace_controls[resource].frequency = "very-high"
mgs.autoplace_controls[resource].richness = "very-high"
surface.map_gen_settings = mgs</syntaxhighlight>

To change water generation settings, replace "very-high" with the desired [https://lua-api.factorio.com/latest/concepts/MapGenSize.html MapGenSize] in the following command.

<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.water = "very-high" --[[ size]]
mgs.terrain_segmentation = "very-high" --[[ frequency]]
surface.map_gen_settings = mgs </syntaxhighlight>

=== Making a structure indestructible ===
This makes it impossible for an entity to be damaged or killed, e.g. by biters. Hover over the entity and then run:
<syntaxhighlight lang="lua">
/c game.player.selected.destructible = false
</syntaxhighlight>

=== Connect linked belts ===
If there exist at least two [https://lua-api.factorio.com/latest/prototypes/LinkedBeltPrototype.html linked belts], and one of them has the "Entity tag" <code>in</code>, and another linked belt has the "Entity tag" <code>out</code>, then the following command should link these two linked belts.

<syntaxhighlight lang="lua">
/c local i = game.get_entity_by_tag('in')
local o = game.get_entity_by_tag('out')
i.linked_belt_type = 'input'
o.linked_belt_type = 'output'
i.connect_linked_belts(o)
</syntaxhighlight>

=== Deactivate cars and tanks ===
The [[car]] and [[tank]] can be used like larger, 2x3 chests, but doing this at a large scale can have a negative performance impact. Deactivating them reduces their performance impact, though it also prevents them from being driven or moved by belts.

Deactivate selected car or tank (hover with mouse then enter command):
<syntaxhighlight lang="lua">
/c game.player.selected.active = false
</syntaxhighlight>

Deactivate all cars and tanks on surface:
<syntaxhighlight lang="lua">
/c for _, v in pairs(game.player.surface.find_entities_filtered{type="car"}) do
v.active = false
end
</syntaxhighlight>

== Enemy/evolution scripts ==

=== Set evolution factor ===
Ranges from 0 (new game) to 1.
<syntaxhighlight lang="lua">
/c game.forces["enemy"].set_evolution_factor(X, game.player.surface)
</syntaxhighlight>

=== Disable time-based evolution & increases pollution-based evolution ===
<syntaxhighlight lang="lua">
/c game.map_settings.enemy_evolution.time_factor=0
/c game.map_settings.enemy_evolution.pollution_factor=game.map_settings.enemy_evolution.pollution_factor*2
</syntaxhighlight>

The "2" at the end of the last command will double the default pollution factor. You can substitute another number to increase (or decrease) the pollution factor further.

=== Kill all biters on the "enemy" force ===
Note that this will kill only mobile units, spawners will not be killed.
<syntaxhighlight lang="lua">
/c game.forces["enemy"].kill_all_units()
</syntaxhighlight>

=== Kill all enemies ===
This will kill all biters, bases and worms. Anything that is an enemy will be completely destroyed. This only affects enemies in the generated world, so any unexplored parts of the map which still need to be generated will still have enemies. You can [[#Prevent biters being on newly generated chunks|prevent biters being on newly generated chunks]] if desired.
<syntaxhighlight lang="lua">
/c local surface=game.player.surface
for key, entity in pairs(surface.find_entities_filtered({force="enemy"})) do
entity.destroy()
end
</syntaxhighlight>

=== Kill all nearby enemies ===

This will kill all biters, bases and worms in a configurable radius. The default, 250 tiles, is about two zoomed-out screen widths on full HD. After destruction, it shows how many objects were destroyed.

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local pp = game.player.position
local cnt = 0
for key, entity in pairs(surface.find_entities_filtered({force="enemy", radius=250, position=pp })) do
cnt = cnt+1
entity.destroy()
end
game.player.print(cnt)
</syntaxhighlight>

=== Enable/Disable peaceful mode ===
Enabling peaceful mode prevents biter attacks until provoked. Substitute true for false to disable. Already existing biters are not affected by this command so attacks could continue for a while after activating peaceful mode.
<syntaxhighlight lang="lua">
/c game.player.surface.peaceful_mode = true
</syntaxhighlight>

=== Enable/Disable biter expansion ===
Biter expansion allows biters to create new nests, it is enabled by default. Substitute true for false to disable.
<syntaxhighlight lang="lua">
/c game.map_settings.enemy_expansion.enabled = true
</syntaxhighlight>

=== Prevent biters being on newly generated chunks ===
On newly generated chunks no biters will be present, however all current biters will remain unaffected. Equivalent of setting the Enemy Base Size to None under the Terrain settings during map generation but achieved mid game by [[#Change map generation settings|changing map generation settings]].
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.autoplace_controls["enemy-base"].size = "none"
surface.map_gen_settings = mgs
</syntaxhighlight>

Instead of the command, it is also possible to use a GUI in the [[map editor]] to changing map generation settings mid game. Access the map editor with <code>/editor</code>, go to the "Surfaces" tab and click "Edit map gen settings".

== Player character scripts ==
Commands concerning the player directly.
=== Get player position ===
Prints coordinates of your current position.
<syntaxhighlight lang="lua">
/c game.player.print(game.player.position)
</syntaxhighlight>

=== Teleport player ===
Moves the player to the specified location. You should be able to teleport to a specific player if you obtain their coordinates via them executing the previous command and giving them to you.
<syntaxhighlight lang="lua">
/c game.player.teleport({X, Y})
</syntaxhighlight>

To teleport to the world's origin, use 0,0.

To teleport to a different planet / surface, use:
<syntaxhighlight lang="lua">
/c game.player.teleport({X, Y}, 'surface_name')
</syntaxhighlight>

=== Enable god mode ===
God mode removes your player character allowing you to fly over obstacles and take no damage.

Disassociate your controls from the character and destroy it:
<syntaxhighlight lang="lua">
/c game.player.character.destroy()
</syntaxhighlight>

To undo, spawn a player character. This will spawn a new character at the spawn point of the world, and connect your controls to it.
<syntaxhighlight lang="lua">
/c game.player.create_character()
</syntaxhighlight>

=== Enable long reach ===
Enables long reach, which allows the player to build and interact with entities at a greater distance. The default reach is 10.
<syntaxhighlight lang="lua">
/c local reach = 10000
game.player.force.character_build_distance_bonus = reach
game.player.force.character_reach_distance_bonus = reach
game.player.force.character_resource_reach_distance_bonus = reach
game.player.force.character_item_drop_distance_bonus = reach
</syntaxhighlight>

=== Find player corpses ===
Pings player corpses on the map.
<syntaxhighlight lang="lua">
/c local found_corpses = game.player.surface.find_entities_filtered{type="character-corpse"}
for _,corpse in pairs(found_corpses) do
local player = game.get_player(corpse.character_corpse_player_index)
local name = player and player.name or "????"
game.player.print(name .. " --> " .. corpse.gps_tag)
end
</syntaxhighlight>

=== Run faster ===
<syntaxhighlight lang="lua">
/c game.player.character_running_speed_modifier=3
</syntaxhighlight>

== Research scripts ==
=== Enable faster research ===
<syntaxhighlight lang="lua">
/c game.player.force.laboratory_speed_modifier=1
</syntaxhighlight>
-0.5 is half speed, 0 is normal speed, 1 is double speed, 2 is triple etc.

=== Research specific technologies ===
The internal technology names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.technologies['electric-energy-distribution-1'].researched=true
/c game.player.force.technologies['steel-processing'].researched=true
</syntaxhighlight>

To research a high level of an infinite technology, set its level:
<syntaxhighlight lang="lua">
/c game.player.force.technologies['worker-robots-speed-7'].level = 100
/c game.player.force.technologies['mining-productivity-3'].level = 100
</syntaxhighlight>

=== Unresearch specific technologies ===
The internal technology names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.technologies['electric-energy-distribution-1'].researched=false
/c game.player.force.technologies['steel-processing'].researched=false
</syntaxhighlight>

=== Enabling specific recipes ===
The internal recipe/item names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.recipes["electric-energy-interface"].enabled=true
/c game.player.force.recipes["rocket-silo"].enabled=true
/c game.player.force.recipes.loader.enabled=true
/c game.player.force.recipes["fast-loader"].enabled = true
/c game.player.force.recipes["express-loader"].enabled = true
</syntaxhighlight>

=== Enable all recipes ===
<syntaxhighlight lang="lua">
/c for name, recipe in pairs(game.player.force.recipes) do recipe.enabled = true end
</syntaxhighlight>

=== Resetting technology effects to default ===
This will reset the enabled/unlocked state of all recipes to what they would be purely based on the currently researched technologies, as well as resetting other technology effects like mining speed, etc. Any manual modifications to these effects and recipe unlocks will be undone.
<syntaxhighlight lang="lua">
/c game.player.force.reset_technology_effects()
</syntaxhighlight>
Note: Can be used as a quick workaround when recipes are unavailable after adding or changing mods even though the technology unlocking them has already been researched.

=== Enable ghosts for destroyed entities ===
This is normally unlocked through researching [[construction robotics (research)]], but this command unlocks it independent of the research.
<syntaxhighlight lang="lua">
/c game.player.force.create_ghost_on_entity_death = true
</syntaxhighlight>

== Modding tools ==
A list of the internal names of most things in the vanilla game can also be found on [[data.raw]].

=== Access a mod's data ===
If the first word of the command is __mod-name__ it will run in the context of the mod with the same name. For instance, this command prints the data from the Even Distribution mod:
<syntaxhighlight lang="lua">
/c __even-distribution__ game.player.print(serpent.dump(storage))
</syntaxhighlight>

=== Print to console the tile under the player ===
<syntaxhighlight lang="lua">
/c game.player.print(game.player.surface.get_tile(game.player.position).name)
</syntaxhighlight>

=== Write all researched technologies to file ===
<syntaxhighlight lang="lua">
/c local list = {}
for _, tech in pairs(game.player.force.technologies) do
if tech.researched then
list[#list+1] = tech.name
end
end
game.write_file("techs.lua", serpent.block(list) .. "\n", true)
</syntaxhighlight>

=== Write all enabled recipes to file ===
<syntaxhighlight lang="lua">
/c local list = {}
for _, recipe in pairs(game.player.force.recipes) do
if recipe.enabled then
list[#list+1] = recipe.name
end
end
game.write_file("recipes.lua", serpent.block(list) .. "\n", true)
</syntaxhighlight>

=== Write mod list to file ===
Write all currently active mods and their version to the file script-output/mods.txt in the [[user data directory]].

<syntaxhighlight lang="lua">
/c helpers.write_file("mods.txt", serpent.block(script.active_mods))
</syntaxhighlight>

=== Exporting production statistics ===
Export production statistics out of the game into external JSON files.

<syntaxhighlight lang="lua">/c local timescales = {
[defines.flow_precision_index.five_seconds] = "5s",
[defines.flow_precision_index.one_minute] = "1min",
[defines.flow_precision_index.ten_minutes] = "10min",
[defines.flow_precision_index.one_hour] = "1h",
[defines.flow_precision_index.ten_hours] = "10h",
[defines.flow_precision_index.fifty_hours] = "50h",
[defines.flow_precision_index.two_hundred_fifty_hours] = "250h",
[defines.flow_precision_index.one_thousand_hours] = "1000h"
}
for surface_name, _ in pairs(game.surfaces) do
local flowdata = game.player.force.get_item_production_statistics(surface_name)
for timescale_index, timescale_name in pairs(timescales) do
local tbl = {}
local totals = flowdata.input_counts
for item_name, _ in pairs(totals) do
local row = {item_name}
for i = 1, 300 do
table.insert(row, flowdata.get_flow_count{name=item_name, category="input", precision_index=timescale_index, sample_index=i, count=true})
end
table.insert(tbl, row)
end
helpers.write_file("stats-" .. surface_name .. "-" .. timescale_name .. ".json", helpers.table_to_json(tbl), false)
end
end
game.player.print("Export done")</syntaxhighlight>

== History ==
{{History|1.1.92|
* Added a notification when a technology is researched.
* Added /enable-research-queue console command to enable the research queue without disabling achievements.}}

== See also ==
* [[Command line parameters]]
* https://lua-api.factorio.com/latest/index-runtime.html - Factorio API reference for latest version

{{C|Modding}}

Tutorial:Mod settings

2025-07-06T19:59:31Z

PennyJim: /* The type property */ Went to kindergarten to learn to count :P

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* localised_name - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* localised_description - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* [https://lua-api.factorio.com/latest/types/Order.html order] - [https://lua-api.factorio.com/latest/types/string.html string] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are five types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/double.html double] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.
** Defines the default value of the setting.

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [https://lua-api.factorio.com/latest/types/Order.html Order].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-string-test-setting=Localized test setting name

[mod-setting-description]
my-mod-string-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, "runtime-global" and "runtime-per-user" are additonally available. They can be accessed as follows:
* "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]).
* "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===
* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==
* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

[[Category:Modding]]

Tutorial:Mod settings

2025-05-14T01:59:01Z

PennyJim: /* Reading settings */ Refine the wording of the clarification + Split the different types into more legibly different things

{{Languages}}
This tutorial aims to explain how to create and use mod settings. Basic knowledge of modding is assumed, so you should have at least understood [[Tutorial:Modding tutorial/Gangsir|Gangsir's modding tutorial]].

== Overview ==
Each mod can specify settings that users can change. The values of these settings can be accessed from inside the data stage or the control stage depending on their [[#The_setting_type_property|setting_type]] and allow to conditionally create or modify prototypes and to add configuration options to control scripts. They allow modders to easily create a graphical interface for their configuration options, instead of using on text files that have to be edited manually by users.

== Location ==

Mod settings are defined in the [https://lua-api.factorio.com/latest/Data-Lifecycle.html settings stage]. This stage is loaded before the data stage. There are three files in which settings can be defined:
* settings.lua
* settings-updates.lua
* settings-final-fixes.lua

First the settings.lua file is called for each mod, in the order of their dependencies and then in the [[:Wikipedia:natural sort order|natural sort order]]. After settings.lua has been called for all mods, the settings-updates.lua file is called for each mod (in the same order) and finally the settings-final-fixes.lua file is called for each mod (in the same order). These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. The settings are all defined in the same stage and their user defined values are not available, therefore mods cannot conditionally create settings depending on the values of other mod settings. Since the settings stage gets loaded first, there is also no prototype data or [http://lua-api.factorio.com/latest/LuaRemote.html remote interface] available.

The "mod-settings.dat" file stored in the [[Application_directory#User_Data_directory|mods folder]] for the game contains the local players settings between game sessions similar to the player-data.json file.

== Creation ==

Mod settings are defined and modified by using the data table during the settings stage. This works [[Tutorial:Modding_tutorial/Gangsir#Prototype_creation|the same way as other prototypes]]. An example would be:
<syntaxhighlight lang="lua">
data:extend({
{
type = "bool-setting",
name = "my-mod-test-setting",
setting_type = "runtime-global",
default_value = true
}
})
</syntaxhighlight>

As you can see, the setting has multiple properties. Each setting supports the following standard prototype properties:
* name - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
* localised_name - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* localised_description - [https://lua-api.factorio.com/latest/types/LocalisedString.html LocalisedString] - Optional.
* [https://lua-api.factorio.com/latest/types/Order.html order] - [https://lua-api.factorio.com/latest/types/string.html string] - Optional.

In addition to the standard properties, mod settings also contain:

* hidden - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
* setting_type - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.

=== The name property ===

The name of the settings prototype should be unique to avoid mod conflicts since the mod settings are global across all mods. Because of that it is recommened to prefix mod settings with your mod name, "my-mod" in this example.

=== The type property ===

There are four types of mod settings:

* bool-setting - a true/false checkbox
* int-setting - a signed 64 bit integer textfield (or selection dropdown)
* double-setting - a double precision floating point textfield (or selection dropdown)
* string-setting - a string textfield (or selection dropdown)
* color-setting - a color picker (sliders), with whole number textfields. Includes alpha.

Depending on the type, the prototype also allows or requires additional properties, these are listed below.

==== bool-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Mandatory.
** Defines the default value of the setting, in this case whether the checkbox is checked or not.
* forced_value - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional.
** Only loaded if <code>hidden = true</code>. This forces the setting to be of this value. This can be useful for mod compatiblity.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]


==== int-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/int64.html int64] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a texfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== double-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/double.html double] - Mandatory.
** Defines the default value of the setting.
* minimum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the lowest possible number.
* maximum_value - [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Defines the highest possible number.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/double.html double] - Optional.
** Makes it possible to force the player to choose between the defined numbers, creates a dropdown instead of a textfield.
** If only one allowed value is given, the settings is forced to be of that value.

==== string-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/string.html string] - Mandatory.
** Defines the default value of the setting.
* allow_blank - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Defines whether it's possible for the user to set the textfield to empty and apply the setting.
* auto_trim - [https://lua-api.factorio.com/latest/types/boolean.html boolean] - Optional. - Default: false
** Whether values that are input by the user should have whitespace removed from both ends of the string.
* allowed_values - array of [https://lua-api.factorio.com/latest/types/string.html string] - Optional.
** Makes it possible to force the player to choose between the defined strings, creates a dropdown instead of a textfield. The strings in the dropdown can be localized (translated) and can have a tooltip, see below.
** If only one allowed value is given, the settings is forced to be of that value.

==== color-setting ====
* default_value - [https://lua-api.factorio.com/latest/types/Color.html Color] - Mandatory.
** Defines the default value of the setting.

=== The order property ===

The order property can be used to change how the mod settings are ordered in the settings gui. Mod settings are sorted
* first by mod
* then by the setting "order" string
* then finally by the setting name.

For more info on how to use the order string, see [https://lua-api.factorio.com/latest/types/Order.html Order].

=== The hidden property ===

The hidden property can be used to hide mod settings from GUIs, so that they cannot be seen or changed by players. However, other mods can still access hidden settings.[https://forums.factorio.com/83316]

=== The setting_type property ===
[[File:Mod_settings_gui.png|right|300px|thumb|The mod settings gui. Can be reached from the main menu → Settings → Mod settings.]]
There are the overall kinds of settings:

* '''startup''': This kind of setting is available in the prototype stage, and can not be changed runtime. They have to be set to the same values for all players on a server.
* '''runtime-global''': This kind of setting is global to an entire save game and can be changed runtime. On servers, only admins can change these settings.
* '''runtime-per-user''': This kind of setting is only available runtime in the control.lua stage and each player has their own instance of this setting. When a player joins a server their local setting of "keep mod settings per save" determines if the local settings they have set are synced to the loaded save or if the save's settings are used.

This "setting_type" also determines in which tab the setting is showed in the mod settings menu.

=== Locale ===
The locale for mod settings works like any other locale in the game. The names of the groups for the setting name and description (tooltip) are "mod-setting-name" and "mod-setting-description". The dropdown items of a string setting can be localized in the "string-mod-setting" group, but the game falls back to just showing the name of the dropdown item if no localization is found. An example for mod setting localization that would be set within "locale/en/locale.cfg", is:
<pre>
[mod-setting-name]
my-mod-string-test-setting=Localized test setting name

[mod-setting-description]
my-mod-string-test-setting=Localized test setting description

[string-mod-setting]
#<setting-name>-<dropdown-item-name>=<translated dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized string

[string-mod-setting-description]
#<setting-name>-<dropdown-item-name>=<tooltip of dropdown item>
my-mod-string-test-setting-item-1=Item 1 localized tooltip

</pre>

== Usage ==
=== Reading settings ===
When accessing any mod setting, you will have to specifically access the ''value'' of the setting. The data type of the value depends on the type of the setting. For string settings that use a selection of allowed values, the value of the setting is one of the original string values defined in the prototype, the localization is ignored. See also: [http://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting concept].

In the prototype stage you can access settings of the setting_type "startup" by indexing <code>settings.startup</code> with the name of the setting. Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "int-setting",
name = "my-mod-stone-wall-stack-size",
setting_type = "startup",
minimum_value = 1,
default_value = 100
}
})

--in data.lua:
data.raw.item["stone-wall"].stack_size = settings.startup["my-mod-stone-wall-stack-size"].value
</syntaxhighlight>

<div class="plainlinks">
In the control stage, "runtime-global" and "runtime-per-user" are additonally available. They can be accessed as follows:
* "runtime-global" (the ''current'' settings, under the Map tab in Mod Settings) can be accessed using <code>settings.global["setting-name"]</code> (see [https://lua-api.factorio.com/latest/LuaSettings.html LuaSettings]).
* "runtime-per-user" are accessed using <code>settings.get_player_settings([https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>])["setting-name"]</code> or <code>game.players[[https://lua-api.factorio.com/latest/Concepts.html#PlayerIdentification <PlayerIdentification>]].mod_settings["setting-name"]</code>.
</div>
Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
},
{
type = "bool-setting",
name = "my-mod-kill-player-on-entity-built",
setting_type = "runtime-per-user",
default_value = false
}
})

--in control.lua:
script.on_init(function()
if settings.global["my-mod-always-difficult"].value == "yes" then
game.difficulty_settings.recipe_difficulty = 1
game.difficulty_settings.technology_difficulty = 1
game.difficulty_settings.technology_price_multiplier = 4
end
end)

script.on_event(defines.events.on_built_entity, function(event)
local setting_value = settings.get_player_settings(event.player_index)["my-mod-kill-player-on-entity-built"].value
if setting_value then
game.get_player(event.player_index).die()
end
end)
</syntaxhighlight>

=== Writing to your own settings ===
It is possible for mods to write to their own runtime (global or per player) mod settings. This is done by writing a new [https://lua-api.factorio.com/latest/Concepts.html#ModSetting ModSetting] table to the setting.

Example:
<syntaxhighlight lang="lua">
--in settings.lua:
data:extend({
{
type = "string-setting",
name = "my-mod-always-difficult",
setting_type = "runtime-global",
default_value = "yes",
allowed_values = {"yes", "no"}
}
})

--in control.lua:
script.on_event(defines.events.on_rocket_launched, function()
settings.global["my-mod-always-difficult"] = {value = "yes"}
end)
</syntaxhighlight>

=== Changing another mod's settings ===
After creating a setting in the settings stage, it is stored in data.raw until the end of the stage, so it can be altered from another mod.

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].order = "abc"
</syntaxhighlight>

If the intent is to force the setting to be of a certain value that cannot be modified by players, the properties [[#The_hidden_property|hidden]], allowed_values and forced_value can be used. Modifying existing settings of other mods can be useful for mod packs or other mod compatibility goals.[https://forums.factorio.com/viewtopic.php?p=531322#p531322]

Example:
<syntaxhighlight lang="lua">
--in settings-updates.lua:
data.raw["string-setting"]["my-mod-always-difficult"].hidden = true
data.raw["string-setting"]["my-mod-always-difficult"].allowed_values = {"no"}
data.raw["string-setting"]["my-mod-always-difficult"].default_value = "no"
</syntaxhighlight>

=== Tips ===
* Do not conditionally 'require(...)' things depending on mod settings: This breaks the CRC checks and people will get errors trying to use your mod in multiplayer. 'require(...)' everything and then conditionally add the values to data.raw using the settings.
* You should cache the settings table inside the event you use it in. Accessing it is relatively expensive (about as expensive as accessing game.*prototypes[...]), so when accessing it mutliple times within the same event, you should set a local variable to it (within the event) to improve performance.
** If you want to cache startup/and runtime settings outside of events, you will have to makes sure that the local variable of settings of the setting_type "runtime-global" are updated in the <code>on_runtime_mod_setting_changed</code> event.
* If you want to detect whether a certain mod is installed in the settings stage, you can use <code>if mods["another-mods-name"] then</code>, just like in the data stage.

== See also ==
* [https://forums.factorio.com/viewtopic.php?p=207275 Forum post documenting mod settings]
* [https://forums.factorio.com/viewtopic.php?p=305644#p305644 per_user is not a valid property and has no effects!]
* [http://lua-api.factorio.com/latest/LuaSettings.html Lua api documentation on the settings table]

[[Category:Modding]]

Desynchronization

2025-03-03T02:41:27Z

PennyJim: Repair API links

A desynchronization (desync) is a disagreement of the game state between the server and at least one client in a multiplayer game, this means the parties no longer run the simulation identically.

== How desyncs happen ==
Desyncs are errors and should not occur during regular play, they can be caused by:
* a bug in Factorio code
* a bug in a mod/scenario
* a miscalculation on server or client hardware
Networking-, latency or performance problems do ''not'' cause desyncs.

=== Factorio multiplayer architecture ===
Factorio multiplayer code uses deterministic lockstep to synchronize clients. This is a method of synchronizing a game from one computer to another by sending only the user inputs that control that game, rather than networking the state of the objects in the game itself. It means that all players' games need to simulate every single tick of the game identically. If any computer does something ever-so-slightly different, a desynchronization (desync) occurs. The game includes processes to ensure any issues with network traffic do not cause desyncs.

=== Player experience of desyncs ===
When a client detects a desync, it disconnects the player and starts to download files from the server (map and game state information) to include them in the [[#Desync_report|Desync report]], this will take longer than the normal map download. After the download is finished and the desync report has been generated the player is offered the options to view the report, quit or reconnect to continue playing. Depending on the cause of the desync, the client might immediately desync again when reconnecting.

[[File:Desync report notification.jpg]]

=== Desync report ===
The desync report will help mod/scenario makers or Factorio developers to fix the underlying bug, it contains both the player's and server's copy of the save game (map and game state). The player's copy is from when the desync occurred and titled ''desynced-level''. With the server's copy being from when the automatic reconnection was made and titled ''reference-level.zip''. A copy of the players Factorio log file is included titled ''log.txt''. As the report contains two copies of the save game it may have a large file size. Furthermore, the save files that are made for the desync report contain more data than normal save files, further increasing their size.

The desync report does not state the cause of the desync but rather is a record of the game state at the time of the desync.

=== Next Steps ===
The next steps after a desync occurs is to start a desync investigation. In many situations restarting the server will work around the desync in the short term and allow all players to rejoin until the conditions for the bug to occur are re-created. However, a server restart isn't guaranteed success and may lead to no players being able to rejoin the server without desyncing.

== Desync Investigations ==
In most cases when desyncs occur and mods or scenarios are being used they are the cause and need to be handled first. If they are found to not be the cause then it should be reported as a [[#Desync_reporting_of_core_Factorio_game|core Factorio desync]]. In both cases identifying the activity that triggers the desync is an important step. For example, whether it is tied to a player's action or activity that happens in the game (i.e. a train arriving at a station) or is a time-related event. In some cases, the desync may not be reproducible and so only a code investigation can work towards a fix.

When desyncs occur and mods/scenarios are in the use there are 2 different approaches that can be taken to help get the issue fixed. The code investigation approach requires you to be familiar with Factorio modding and its coding rules. The less technical method is to identify the mod and activity that causes the desync through trial and error so it can be reported to the mod author.

=== Identifying desync causing mod through trial and error ===
This is a less technical method aiming to identify the mod and its activity that seems to cause the desync so it can be reported to the mod/scenario author. The activity that causes the desync should be established prior to these activities being done to confirm if they are having an impact. These steps may affect the gameplay and should be done on a test save.
* Removing any newly added mods and rolling back (returning to the previous version) any updated mods to see if the issue still occurs.
* Removing mods from the game to rule them out as the cause.
Once the desync can no longer be reproduced the suspected mod can be re-added/updated and the desync recreated to confirm the mod and activity are the cause of the desync. As these steps require the server to be restarted this may in itself fix any desyncs in the short term until the conditions for the bug to occur are re-created.

=== Code investigations with mods/scenarios involved ===
The desync report is a useful reference for investigating desyncs but it does not state the cause of the desync. Comparing the desync files and use of heavy mode can assist in identifying which mods and activities to review initially. Ideally, it is supplemented by an account of what was occurring and being done by players at the point of the desync occurring to assist with narrowing down the activities of code to review. However in many complicated scenarios this may not be known prior to the investigation.

==== Code that causes desyncs ====
There are a number of ways mod and scenario code can cause desyncs, such as due to incorrect variable scoping, requiring or API event handling. Examples of these can be found in [[Tutorial:Modding tutorial/Gangsir#Multiplayer_and_desyncs|Gangsir's modding tutorial multiplayer and desyncs section]], with the full technical definition of usage constraints for API events in the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Factorio API data lifecycle]. Not all instances of non-compliance will lead to desyncs or errors, but most will. For this reason, it is recommended to always maintain compliance to avoid risk and time-consuming testing. Instances of non-compliance found should be raised to the code author.

==== Comparing game state & save files ====
The desync report files and heavy mode dumps contain a number of files that can be compared by any text comparison tool to look for differences. These files are generally sequelized dumps of Lua tables or c++ game objects and so are only partially human readable. The less human readable items can include floating point numbers serilaised (0x.HEXp+HEX) and ''magic'' unique identifier numbers for prototype instances in the c++ game state. These numbers and reference ids should generally be the same between files as the in-game entity they reference normally won't have changed between the 2 save game states being obtained.
When the data differs between files the source code of that mod/scenario must be examined for all interactions with that data item for any instances of non-compliance.

==== Examining the desync files ====
Within each savegame's zip in the desync report are a number of files that when compared can show data changes. As the server copy of the save is obtained after the desync there may be genuine differences between the files. So differences aren't hard evidence of the cause of a desync, but only a pointer on where to investigate further.

* script.dat - contains the scenario and mods [https://lua-api.factorio.com/latest/auxiliary/storage.html Factorio storage tables]. Generally, the save's persistent data should be the same between the 2 saves. On rare occasions, there can be a difference due to how the information is written out to the file. Should a mod causes a player's game to desync it can cause the player's game to stop processing other mod activity mid tick. This can lead those mod's global tables to have differences between the player and the server copies despite having no code defects themselves.
* level_with_tags_tick_XXXX.dat - contains the current game state together with additional saving tags to aid human readability. This can show if entity states or chat messages differ. ''level.dat'' is the same information, but without the descriptive tags for data values.

==== Using heavy mode command ====
[[Console#Normal_commands|Heavy mode]] is an in-game option that can be enabled to make Factorio save and load the game every tick. This allows Factorio to highlight if there are any changes in the game state between the save and subsequent load. Should a state change occur, a message is shown in-game and the save and load game states recorded to a ''dumps'' folder in the players [[Application directory#User_data_directory|user data folder]].
Typically this process will trigger for incorrect changing of data as part of the on_load event or local/global variables being changed and not persisted. The recorded game state is a dump of the internal game state, including entities, but does not include the mod's global table. This allows the checking if an entity's state has become different between the load and save state.

This process can be used to partially test a mod for multiplayer compliance without the need of multiple players or a server.

=== Desync reporting of core Factorio game ===
If no mod or scenario were involved in the desync, the desync report and activity information should be posted to the [https://forums.factorio.com/53851 Factorio forums bug report section].

== See also ==
* [https://www.factorio.com/blog/post/fff-63 FFF 63] - How heavy mode works

[[Category:Technical]]

Tutorial:Modding tutorial

2025-01-04T19:37:13Z

PennyJim: Update the broken API link

These tutorials range from teaching the first steps of modding to in-depth explanations of individual mechanics:

* [[Tutorial:Modding tutorial/Gangsir|Modding tutorial/Gangsir]] — A simple modding tutorial that suits beginners well.
* [[Tutorial:Mod structure|Mod structure]] — More details on how mods need to be structured in order to be loaded by the game.
* [[Tutorial:Scripting|Scripting]] — A small tutorial that focuses on run-time scripting and provides some info on how to use the story script.
* [[Tutorial:Mod settings|Mod settings]] — A comprehensive tutorial about how to create and use mod settings.
* [[Tutorial:Localisation|Localisation]] — A tutorial about how to format and use localisation, which is how mods are translated.
* [[Tutorial:Inspecting a live mod|Inspecting a live mod]] — An annotated tour of a mod that is live on the mod portal right now.
* [[Tutorial:Mod changelog format|Mod changelog format]] — The formatting requirements for the mod changelog.txt file.
* [[Tutorial:Script interfaces|Script interfaces]] — A small tutorial about script interfaces ([https://lua-api.factorio.com/latest/classes/LuaRemote.html LuaRemote]) and custom keyboard shortcuts.
* <s>[https://togos.github.io/togos-example-noise-programs/ Noise Expressions] — A tutorial about generating terrain, complete with [https://mods.factorio.com/mod/togos-example-noise-programs example mod].</s> (Shows the 1.1 format which has significantly changed for 2.0)
* [https://github.com/ClaudeMetz/UntitledGuiGuide/wiki Untitled GUI Guide] — A tutorial about building custom interfaces that also expands into more advanced parts of GUI modding.
* [https://forums.factorio.com/106661 Controller modding guide / FAQ] — A guide about building your mod to support controllers (game pads).

=== Additional info ===
* [https://lua-api.factorio.com/latest Modding API docs] - Overview page of the modding API documentation website
** [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation]
** [https://lua-api.factorio.com/latest/index-runtime.html Documentation of the runtime API]
* [[Scenario system]] — Save-based mods ("soft mods") and their limitations
* [https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations guide] — All information about mod migrations
* [https://github.com/wube/factorio-data Factorio data github repository] — Tracks changes of the lua prototype definitions in Factorio in between releases
* [[Tutorial:Modding FAQ|Modding FAQ]]

=== Third-Party Tools ===
There is a wide variety of tools contributed by community members to help in mod development, such as plugins for IDEs to provide auto-completion, debuggers, as well as scripts to automate common tasks regarding translations or packaging.

* [https://forums.factorio.com/viewforum.php?f=135 Factorio sub-forum for mod development tools]
<noinclude>{{Languages}}
== See also ==
* [[Tutorials]]
* [[Modding]]
* [[:Category:Technical]] — Documentation of technical formats and API's not related to modding

[[Category:Modding]]
</noinclude>

Tutorial:Modding tutorial

2025-01-04T19:35:39Z

PennyJim: Cross out the outdated NoiseExpression tutorial

These tutorials range from teaching the first steps of modding to in-depth explanations of individual mechanics:

* [[Tutorial:Modding tutorial/Gangsir|Modding tutorial/Gangsir]] — A simple modding tutorial that suits beginners well.
* [[Tutorial:Mod structure|Mod structure]] — More details on how mods need to be structured in order to be loaded by the game.
* [[Tutorial:Scripting|Scripting]] — A small tutorial that focuses on run-time scripting and provides some info on how to use the story script.
* [[Tutorial:Mod settings|Mod settings]] — A comprehensive tutorial about how to create and use mod settings.
* [[Tutorial:Localisation|Localisation]] — A tutorial about how to format and use localisation, which is how mods are translated.
* [[Tutorial:Inspecting a live mod|Inspecting a live mod]] — An annotated tour of a mod that is live on the mod portal right now.
* [[Tutorial:Mod changelog format|Mod changelog format]] — The formatting requirements for the mod changelog.txt file.
* [[Tutorial:Script interfaces|Script interfaces]] — A small tutorial about script interfaces ([http://lua-api.factorio.com/latest/LuaRemote.html LuaRemote]) and custom keyboard shortcuts.
* <s>[https://togos.github.io/togos-example-noise-programs/ Noise Expressions] — A tutorial about generating terrain, complete with [https://mods.factorio.com/mod/togos-example-noise-programs example mod].</s> (Shows the 1.1 format which has significantly changed for 2.0)
* [https://github.com/ClaudeMetz/UntitledGuiGuide/wiki Untitled GUI Guide] — A tutorial about building custom interfaces that also expands into more advanced parts of GUI modding.
* [https://forums.factorio.com/106661 Controller modding guide / FAQ] — A guide about building your mod to support controllers (game pads).

=== Additional info ===
* [https://lua-api.factorio.com/latest Modding API docs] - Overview page of the modding API documentation website
** [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation]
** [https://lua-api.factorio.com/latest/index-runtime.html Documentation of the runtime API]
* [[Scenario system]] — Save-based mods ("soft mods") and their limitations
* [https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations guide] — All information about mod migrations
* [https://github.com/wube/factorio-data Factorio data github repository] — Tracks changes of the lua prototype definitions in Factorio in between releases
* [[Tutorial:Modding FAQ|Modding FAQ]]

=== Third-Party Tools ===
There is a wide variety of tools contributed by community members to help in mod development, such as plugins for IDEs to provide auto-completion, debuggers, as well as scripts to automate common tasks regarding translations or packaging.

* [https://forums.factorio.com/viewforum.php?f=135 Factorio sub-forum for mod development tools]
<noinclude>{{Languages}}
== See also ==
* [[Tutorials]]
* [[Modding]]
* [[:Category:Technical]] — Documentation of technical formats and API's not related to modding

[[Category:Modding]]
</noinclude>

Tutorial:Modding tutorial/Gangsir

2024-12-13T23:12:36Z

PennyJim: Update references of `global` to `storage` - Some rewording in places might be recommended

{{Languages}}
This is a modding tutorial for Factorio version 2.0. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

== Overview ==
Before we start the tutorial, a few things to note:

<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>

This tutorial was updated to version 2.0, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

== Terminology used in modding ==

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

; Mod : A script or series of scripts that allow modifications to the game through the API.
; Entity : An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.
; Character : The actual entity that the player manipulates the world through.
; Player : All the data that defines a player, such as username, online time or the current zoom level.
; Prototype : A prototype describes an instance of an entity, item or recipe etc, a bit like a template. It defines stats, like what an entity actually is, an item's stack size, a recipe's ingredients etc. A prototype is used to create an instance of an entity/item/etc, and many functionally identical entities/items/etc will use the same prototype.
; Surface : A surface is a bit like a dimension. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By default, there is only one surface in Factorio, referred to internally as "nauvis", or <code style="background-color:#DDA0DD; color:black">game.surfaces[1]</code>, but mods may create additional surfaces through the API.
; Event : An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, etc. More on this in the control scripting section.
; Item : Items are what is moved around in inventories, by inserters and on belts, etc. Each item in-game is an instance of the respective item prototype.

More terminology may be declared and defined later in this tutorial.

== Before beginning to mod ==

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the [[Factorio:About|about page]], but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua (version 5.2.1). This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation of mods on at their [https://lua-api.factorio.com/latest/ API doc site]. Get used to using this site, as you will be frequently visiting it while you develop mods. The scripting API site contains information on [https://lua-api.factorio.com/latest/classes.html Factorio's classes] and information on [https://lua-api.factorio.com/latest/events.html events] that you can hook into. The [https://lua-api.factorio.com/latest/index-prototype.html prototype documentation] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, there are also many resources to be found created by the community, such as this tutorial.

=== Setup ===

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is recommended. Emacs, Vim, Sublime Text, VSCode, and Notepad++ are all viable candidates.

== How Factorio loads mods ==

=== Load order ===
Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies, entities, items and more. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

All prototypes are documented on the modding API documentation website: [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation].

=== Migrations ===

[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid changing prototype names and technology unlocks. Prototypes names cannot be dynamically changed and technology unlocks of already researched technologies do not apply automatically, making migrations necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Runtime stage ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. During the play session, access to all tables provided by the game can be done inside of event handlers. (More on those below.) Because the control.lua is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html data life cycle] page on the API site provides the best overview.'''

The control stage documented is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

The game expects mod to be laid out [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor

Then, inside fire-armor, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor
**** data.lua
**** info.json

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "2.0",
"dependencies": ["base >= 2.0"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a of the format "number.number.number".
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 2.0 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A short description of your mod, which appears in game. The mod portal is better for a long description.
|}

And that's all for info.json!

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. One way requires to create a complete prototype definition based on [https://lua-api.factorio.com/latest/index-prototype.html the documentation]. Another way uses a Lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it both ways.

In the data.lua file, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"]) -- copy the table that defines the heavy armor item into the fireArmor variable

fireArmor.name = "fire-armor"
fireArmor.icons = {
{
icon = fireArmor.icon,
icon_size = fireArmor.icon_size,
tint = {r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
}
}

-- create the recipe prototype from scratch
local recipe = {
type = "recipe",
name = "fire-armor",
enabled = true,
energy_required = 8, -- time to craft in seconds (at crafting speed 1)
ingredients = {
{type = "item", name = "copper-plate", amount = 200},
{type = "item", name = "steel-plate", amount = 50}
},
results = {{type = "item", name = "fire-armor", amount = 1}}
}

data:extend{fireArmor, recipe}

</pre>

What we've just done here is we've copied the definition of the heavy armor item, then changed its properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all prototype types, and within those types, individual prototypes identified by name: <code>local prototype = data.raw["prototype-type"]["internal-name"]</code>. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. We can find [[heavy armor]]'s prototype type and internal name in the infobox of its page on this wiki and just copy it from there. 
Alternatively, we can find the items prototype type and internal name by opening the game, inserting the item into our inventory and then pressing {{Keybinding|shift|ctrl|F}} while hovering over the item. This will open the prototype explorer GUI, which has rows showing the name and type of the item.

As another example, the [[player|character]]'s prototype would be, according to the infobox on the page:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["character"]["character"]
</pre>

Because the character is ''the'' character, his type matches his name. You could define a new character with a mod. You can see all the available prototype fields of the character in the documentation: [https://lua-api.factorio.com/latest/prototypes/CharacterPrototype.html CharacterPrototype].

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua if you want to run after all other mods, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["container"]["iron-chest"].max_health = 1000
</pre>

The reason why this code is in data-final-fixes.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to create fire on the ground as we walk with the armor on. The event we're going to use is called [https://lua-api.factorio.com/latest/events.html#on_player_changed_position on_player_changed_position], since we want the fire to be created when the player moves.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event(defines.events.on_player_changed_position,
function(event)
local player = game.get_player(event.player_index) -- get the player that moved
-- if they're currently controlling the character
if player.controller_type == defines.controllers.character then
-- and wearing our armor
if player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
-- create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player character is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [https://lua-api.factorio.com/latest/defines.html#defines.inventory here].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create a locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>any_name_can_be_here.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside the .cfg file, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it.

If you want to share a mod with other users, it needs to be a zip file. For that, simply zip the <code>fire-armor</code> folder and then rename the archive to <code>fire-armor_0.1.0</code> so that it follows the expected mod zip name pattern of <code>mod-name_version</code>. Keep in mind to not submit this tutorial mod to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Extended learning ==
One of the best ways to learn how to mod beyond this is to look at other mods. The [[Tutorial:Inspecting a live mod]] is a good starting point for touring a particularly well-commented mod. As all mods can be opened and inspected, looking at the mods of experienced modders can help significantly when making your own mod.

Something you'll see a lot in other mods or the base game are <code>require</code> statements. These load other files, so you can split up long code files and organize your mod however you like.

For example, if you wanted to put some of your data stage code into a file called "foo.lua" in a folder called "bar", your mod folder would look like this:

* fire-armor
** bar
*** foo.lua
** data.lua
** control.lua
** info.json

And you would need to add this to data.lua:
<pre style="background-color:#DDA0DD!important; color:black">
require("bar.foo")
</pre>

=== Keeping your mod working ===
As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The Lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
</pre>

You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mod "fire-armor":". So, we know that it's our mod that messed up. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was caused by line 39 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 39 of data.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
name = "fire-armor,
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an " after armor before the comma. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
__fire-armor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [https://lua-api.factorio.com/latest/LuaPlayer.html A player] is a table of several values. Trying to print it simply print "LuaPlayer" instead of providing useful data.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
Unknown entity name: fire-flam
stack traceback:
__fire-armor__/control.lua:7: in function <__fire-armor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 7 of control.lua, inside of an on_player_changed_position event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:190: Map tick at moment of crash: 432029
696.148 Error Util.cpp:97: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
Please also include the save file(s), any mods you may be using, and any steps you know of to reproduce the crash.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/storage.html storage] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the storage table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

=== Comparison by reference ===

Be cautious of comparing tables by reference. In multiplayer syncing, tables deserialized from the server state will be new objects, not equal by reference to any table initialized by client code.

<pre style="background-color:#DDA0DD!important; color:black">
if a == b then
</pre>
<pre style="background-color:#DDA0DD!important; color:black">
if a ~= b then
</pre>
If <code>a</code> and <code>b</code> are tables in the above conditionals, there will for example be different results between server and client if <code>a</code> is created locally and <code>b</code> is downloaded from the server.

Note that LuaObjects provided by the game have their equality operator overwritten to prevent this behaviour, so code such as <code>LuaEntityA ~= LuaEntityB</code> will not desync.
However, this does not apply when LuaObjects are used as keys in tables:
<pre style="background-color:#DDA0DD!important; color:black">
if table[LuaObject] then
</pre>
This will desync in the same way as described for the plain tables <code>a</code> and <code>b</code> above. For entities it is recommended to use [https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.unit_number LuaEntity.unit_number] as the table key instead of the whole entity.

== See also ==
* [[Modding]]
* [[Tutorial:Modding tutorial|Modding tutorial overview]]

[[Category:Modding]]

Blueprint string format

2024-11-14T23:26:30Z

PennyJim: Quick pass to fix invalid concept links

{{Cleanup|Needs to be updated for 2.0}}
[[File:blueprint_string_preview.png|thumb|340px|right|Preview of a blueprint string.]]This is a technical description of the blueprint string format, used to share blueprints with other users.

A blueprint string is a JSON representation of the blueprint, compressed with zlib deflate using compression level 9 and then encoded using base64 with a version byte in front of the encoded string. The version byte is currently 0 (for all Factorio versions through 1.1).
So to get the JSON representation of a blueprint from a blueprint string, skip the first byte, base64 decode the string, and finally decompress using zlib inflate.

== Json representation of a blueprint/blueprint book ==

The json representation of a blueprint or blueprint book is one large object inside another "wrapping" object, its key inside that object is either blueprint or blueprint-book.

=== Blueprint book object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| item
| String, the name of the item that was saved ("blueprint-book" in vanilla).
| String
|-
| label
| String, the name of the blueprint set by the user.
| String
|-
| label_color
| The color of the label of this blueprint. Optional. [[#Color object]].
| Object
|-
| blueprints
| The actual content of the blueprint book, array of objects containing an "index" key and 0-based value and a "blueprint" key with a [[#Blueprint object]] as the value.
| Array
|-
| active_index
| Index of the currently selected blueprint, 0-based.
| Integer
|-
| icons
| The icons of the blueprint book set by the user, array of [[#Icon object]]s.
| Array
|-
| description
| The description of the blueprint book. Optional.
| String
|-
| version
| The map version of the map the blueprint was created in, see [[Version string format]].
| Integer (long)
|}

=== Blueprint object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| item
| String, the name of the item that was saved ("blueprint" in vanilla).
| String
|-
| label
| String, the name of the blueprint set by the user.
| String
|-
| label_color
| The color of the label of this blueprint. Optional. [[#Color object]].
| Object
|-
| entities
| The actual content of the blueprint, array of [[#Entity object]]s.
| Array
|-
| tiles
| The tiles included in the blueprint, array of [[#Tile object]]s.
| Array
|-
| icons
| The icons of the blueprint set by the user, array of [[#Icon object]]s.
| Array
|-
| schedules
| The schedules for trains in this blueprint, array of [[#Schedule object]]s.
| Array
|-
| description
| The description of the blueprint. Optional.
| String
|-
| snap-to-grid
| The dimensions of the grid to use for snapping. Optional. [[#Position object]].
| Object
|-
| absolute-snapping
| Whether the blueprint uses absolute or relative snapping. Optional.
| Boolean
|-
| position-relative-to-grid
| Offset relative to the global absolute snapping grid. Optional. [[#Position object]].
| Object
|-
| version
| The map version of the map the blueprint was created in.
| Integer (long)
|}

=== Icon object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| index
| Index of the icon, 1-based.
| Integer
|-
| signal
| The icon that is displayed, [[#SignalID object]].
| Object
|}

=== SignalID object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| name
| Name of the signal prototype this signal is set to.
| String
|-
| type
| Type of the signal. See [https://lua-api.factorio.com/stable/concepts/SignalIDType.html SignalIDType] for possible values. '''Note for 2.x:''' property is optional and defaults to "item".
| String
|}

=== Entity object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| entity_number
| Index of the entity, 1-based.
| Integer
|-
| name
| Prototype name of the entity (e.g. "offshore-pump").
| String
|-
| position
| [[#Position object]], position of the entity within the blueprint.
| Object
|-
| direction
| Direction of the entity, uint (optional). '''Note for 2.x:''' Direction appears to be double the previous values
| Integer
|-
| orientation
| Orientation of cargo wagon or locomotive, value 0 to 1 (optional).
| Floating Point
|-
| connections
| Circuit connection, object with keys starting from 1, values are [[#Connection object]]s (optional).
| Object
|-
| neighbours
| Copper wire connections, array of entity_numbers (optional).
| Array
|-
| control_behavior
| [[#Control behavior object]] of this entity (optional).
| Object
|-
| items
| Item requests by this entity, this is what defines the item-request-proxy when the blueprint is placed, optional. [[#Item request object]]
| Object
|-
| recipe
| Name of the recipe prototype this assembling machine is set to, optional, string.
| String
|-
| bar
| Used by [[Prototype/Container]], optional. The index of the first inaccessible item slot due to limiting with the red "bar". 0-based [[Types/ItemStackIndex]].
| Integer
|-
| ammo_inventory
| Ammo inventory of an entity (e.g. [[Spidertron]]), optional. [[#Inventory object]]
| Object
|-
| trunk_inventory
| Boot/Luggage inventory of an entity (e.g. storage inventory of a Spidertron), optional. [[#Inventory object]]
| Object
|-
| inventory
| Cargo wagon inventory configuration, optional. [[#Inventory object]]
| Object
|-
| infinity_settings
| Used by [[Prototype/InfinityContainer]], optional. [[#Infinity settings object]]
| Object
|-
| type
| Type of the underground belt or loader, optional. Either "input" or "output".
| String
|-
| input_priority
| Input priority of the splitter, optional. Either "right" or "left", "none" is omitted.
| String
|-
| output_priority
| Output priority of the splitter, optional. Either "right" or "left", "none" is omitted.
| String
|-
| filter
| Filter of the splitter, optional. Name of the item prototype the filter is set to, string.
| String
|-
| filters
| Filters of the filter inserter or loader, optional. Array of [[#Item filter object]]s.
| Array
|-
| filter_mode
| Filter mode of the filter inserter, optional. Either "whitelist" or "blacklist".
| String
|-
| override_stack_size
| The stack size the inserter is set to, optional. [[Types/uint8]].
| Integer
|-
| drop_position
| The drop position the inserter is set to, optional. [[#Position object]].
| Object
|-
| pickup_position
| The pickup position the inserter is set to, optional. [[#Position object]].
| Object
|-
| request_filters
| Used by [[Prototype/LogisticContainer]], optional. [[#Logistic filter object]].
| Array
|-
| request_from_buffers
| Boolean. Whether this requester chest can request from buffer chests.
| Boolean
|-
| parameters
| Used by [[Programmable speaker]], optional. [[#Speaker parameter object]].
| Object
|-
| alert_parameters
| Used by [[Programmable speaker]], optional. [[#Speaker alert parameter object]]
| Object
|-
| auto_launch
| Used by the rocket silo, optional. Boolean, whether auto launch is enabled.
| Boolean
|-
| variation
| Used by [[Prototype/SimpleEntityWithForce]] or [[Prototype/SimpleEntityWithOwner]], optional. [[Types/GraphicsVariation]]
|
|-
| color
| Color of the [[Prototype/SimpleEntityWithForce]], [[Prototype/SimpleEntityWithOwner]], or train station, optional. [[#Color object]].
| Object
|-
| station
| The name of the train station, optional.
| String
|-
| manual_trains_limit
| The manually set train limit of the train station, optional.
| Integer
|-
| switch_state
| The current state of the power switch, optional.
| Boolean
|-
| tags
| Dictionary of arbitrary data, optional. [https://lua-api.factorio.com/latest/concepts/Tags.html Tags].
| Object
|}

=== Inventory object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| filters
| Array of [[#Item filter object]]s.
| Array
|-
| bar
| The index of the first inaccessible item slot due to limiting with the red "bar". 0-based, optional. [[Types/ItemStackIndex]].
| Integer
|}

=== Schedule object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| schedule
| Array of [[#Schedule Record object]]s.
| Array
|-
| locomotives
| Array of entity numbers of locomotives using this schedule.
| Array
|}

=== Schedule Record object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| station
| The name of the stop for this schedule record.
| String
|-
| wait_conditions
| Array of [[#Wait Condition object]]s.
| Array
|-
| temporary
| Whether this is a temporary schedule record. Optional.
| Boolean
|}

=== Wait Condition object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| type
| One of "time", "inactivity", "full", "empty", "item_count", "circuit", "robots_inactive", "fluid_count", "passenger_present", "passenger_not_present".
| String
|-
| compare_type
| Either "and", or "or". Tells how this condition is to be compared with the preceding conditions in the corresponding wait_conditions array.
| String
|-
| ticks
| Number of ticks to wait or of inactivity. Only present when type is "time" or "inactivity". Optional.
| uint
|-
| condition
| [https://lua-api.factorio.com/latest/concepts/CircuitCondition.html CircuitCondition object], only present when type is "item_count", "circuit" or "fluid_count".
| Object
|}

=== Tile object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| name
| Prototype name of the tile (e.g. "concrete")
| String
|-
| position
| [[#Position object]], position of the entity within the blueprint.
| Object
|}

=== Position object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| x
| X position within the blueprint, 0 is the center.
| Floating point
|-
| y
| Y position within the blueprint, 0 is the center.
| Floating point
|}

=== Connection object ===
Object containing information about the connections to other entities formed by red or green wires.

{| class="wikitable"
! Key !! Description !! Data type
|-
| 1
| First connection point. The default for everything that doesn't have multiple connection points.[[#Connection point object]]
| Object
|-
| 2
| Second connection point. For example, the "output" part of an arithmetic combinator.[[#Connection point object]]
| Object
|}

=== Connection point object ===
The actual point where a wire is connected to. Contains information about where it is connected to.

{| class="wikitable"
! Key !! Description !! Data type
|-
| red
| An array of [[#Connection data object]] containing all the connections from this point created by red wire.
| Array
|-
| green
| An array of [[#Connection data object]] containing all the connections from this point created by green wire.
| Array
|}

=== Connection data object ===
Information about a single connection between two connection points.

{| class="wikitable"
! Key !! Description !! Data type
|-
| entity_id
| ID of the entity this connection is connected with.
| Integer
|-
| circuit_id
| The circuit connector id of the entity this connection is connected to, see [https://lua-api.factorio.com/latest/defines.html#defines.circuit_connector_id defines.circuit_connector_id].
| Integer
|}

=== Item request object ===
1 or more instances of key/value pairs.
Key is the name of the item, string.
Value is the amount of items to be requested, [[Types/ItemCountType]].

=== Item filter object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| name
| Name of the item prototype this filter is set to.
| String
|-
| index
| Index of the filter, 1-based.
| Integer
|}

=== Infinity settings object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| remove_unfiltered_items
| Boolean. Whether the "remove unfiltered items" checkbox is checked.
| Boolean
|-
| filters
| Filters of the infinity container, optional. Array of [[#Infinity filter object]]s.
| Array
|}

=== Infinity filter object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| name
| Name of the item prototype the filter is set to, string.
| String
|-
| count
| Number the filter is set to, [[Types/ItemCountType]].
| Integer
|-
| mode
| Mode of the filter. Either "at-least", "at-most", or "exactly".
| String
|-
| index
| Index of the filter, 1-based.
| Integer
|}

=== Logistic filter object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| name
| Name of the item prototype this filter is set to.
| String
|-
| index
| Index of the filter, 1-based.
| Integer
|-
| count
| Number the filter is set to, [[Types/ItemCountType]]. Is 0 for storage chests.
| Integer
|}

=== Speaker parameter object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| playback_volume
| [[Types/double]]. Volume of the speaker.
| Floating point
|-
| playback_globally
| Boolean, whether global playback is enabled.
| Boolean
|-
| allow_polyphony
| Boolean, whether polyphony is allowed.
| Boolean
|}

=== Speaker alert parameter object ===
{| class="wikitable"
! Key !! Description !! Data type
|-
| show_alert
| Boolean, whether an alert is shown.
| Boolean
|-
| show_on_map
| Boolean, whether an alert icon is shown on the map.
| Boolean
|-
| icon_signal_id
| The icon that is displayed with the alert, [[#SignalID object]].
| Object
|-
| alert_message
| String, message of the alert.
| String
|}

=== Color object ===

{| class="wikitable"
! Key !! Description !! Data type
|-
| r
| red, number from 0 to 1.
| Floating point
|-
| g
| green, number from 0 to 1.
| Floating point
|-
| b
| blue, number from 0 to 1.
| Floating point
|-
| a
| transparency, number from 0 to 1.
| Floating point
|}

=== Control behavior object ===

'''ALL fields are optional''' and depend on the type of the entity.

{| class="wikitable"
|-
! Key !! Description !! Data type
|-
| logistic_condition
| [https://lua-api.factorio.com/latest/concepts/CircuitCondition.html CircuitCondition]
| Object
|-
| connect_to_logistic_network
| Whether this entity is connected to the logistic network and enables/disables based on logistic_condition.
| Boolean
|-
| circuit_close_signal
| Whether this rail signal can be closed by circuit_condition.
| Boolean
|-
| circuit_read_signal
| Whether or not to read the state of this rail/chain signal.
| Boolean
|-
| red_output_signal
| [[#SignalID]] to use if the rail/chain signal is currently red.
| Object
|-
| orange_output_signal
| [[#SignalID]] to use if the rail/chain signal is currently orange.
| Object
|-
| green_output_signal
| [[#SignalID]] to use if the rail/chain signal is currently green.
| Object
|-
| blue_output_signal
| [[#SignalID]] to use if the chain signal is currently blue.
| Object
|-
| circuit_condition
| [https://lua-api.factorio.com/latest/concepts/CircuitCondition.html CircuitCondition]
| Object
|-
| circuit_enable_disable
| Enable or disable based on circuit_condition.
| Boolean
|-
| send_to_train
| Send circuit values to the train to use in schedule conditions.
| Boolean
|-
| read_from_train
| Get the currently stopped trains cargo.
| Boolean
|-
| read_stopped_train
| Get the currently stopped trains ID.
| Boolean
|-
| train_stopped_signal
| [[#SignalID]] to output the train ID on.
| Object
|-
| set_trains_limit
| Whether this stations trains limit will be set through circuit values.
| Boolean
|-
| trains_limit_signal
| [[#SignalID]] to use to set the trains limit.
| Object
|-
| read_trains_count
| Whether to read this stations currently on route trains count.
| Boolean
|-
| trains_count_signal
| [[#SignalID]] to output the on route trains count on.
| Object
|-
| read_logistics
| Whether this roboport should output the contents of its network.
| Boolean
|-
| read_robot_stats
| Whether this roboport should output the robot stats of its network.
| Boolean
|-
| available_logistic_output_signal
| [[#SignalID]] to output available logistic robots on.
| Object
|-
| total_logistic_output_signal
| [[#SignalID]] to output the total count of logistic robots on.
| Object
|-
| available_construction_output_signal
| [[#SignalID]] to output available construction robots on.
| Object
|-
| total_construction_output_signal
| [[#SignalID]] to output the total count of construction robots on.
| Object
|-
| circuit_open_gate
| Whether to limit the gate opening with circuit_condition.
| Boolean
|-
| circuit_read_sensor
| Whether to send the wall-gate proximity sensor to the circuit network.
| Boolean
|-
| output_signal
| [[#SignalID]] to output the wall-gate sensor / accumulator charge on.
| Object
|-
| circuit_read_hand_contents
| Whether to read this belts content or inserters hand.
| Boolean
|-
| circuit_contents_read_mode
| [https://lua-api.factorio.com/latest/defines.html#defines.control_behavior.transport_belt.content_read_mode defines.control_behavior.transport_belt.content_read_mode]
| Integer
|-
| circuit_mode_of_operation
|
| Integer
|-
| circuit_hand_read_mode
| [https://lua-api.factorio.com/latest/defines.html#defines.control_behavior.inserter.hand_read_mode defines.control_behavior.inserter.hand_read_mode]
| Integer
|-
| circuit_set_stack_size
| Whether to set the inserters stack size from a circuit signal.
| Boolean
|-
| stack_control_input_signal
| [[#SignalID]] to use to set the inserters stack size.
| Object
|-
| circuit_read_resources
| Whether this miner should output its remaining resource amounts to the circuit network.
| Boolean
|-
| circuit_resource_read_mode
| [https://lua-api.factorio.com/latest/defines.html#defines.control_behavior.mining_drill.resource_read_mode defines.control_behavior.mining_drill.resource_read_mode]
| Integer
|-
| is_on
| Whether this constant combinator is currently on or off.
| Boolean
|-
| filters
| Array of <s>[https://lua-api.factorio.com/latest/concepts/BlueprintLogisticFilter.html ConstantCombinatorParameters].</s> It's now a kind of [https://lua-api.factorio.com/latest/concepts/LogisticSections.html LogisticSections] instead.
''We might be missing a type for it specifically.''
| Array
|-
| arithmetic_conditions
| [https://lua-api.factorio.com/latest/concepts/ArithmeticCombinatorParameters.html ArithmeticCombinatorParameters]
| Object
|-
| decider_conditions
| [https://lua-api.factorio.com/latest/concepts/DeciderCombinatorParameters.html DeciderCombinatorParameters]
| Object
|-
| circuit_parameters
| [https://lua-api.factorio.com/latest/concepts/ProgrammableSpeakerCircuitParameters.html ProgrammableSpeakerCircuitParameters]
| Object
|-
| use_colors
| Whether this lamp should use colors or not.
| Boolean
|}

[[Category:Technical]]

== Example code ==

On a typical Bash command line, the blueprint can be decoded like so:

<syntaxhighlight lang="bash">echo "$blueprint_string" | cut -c2- | base64 -d | pigz -d</syntaxhighlight>

If you don't have <code>pigz</code> installed, you can use <code>zlib-flate -uncompress</code> instead (part of "qpdf").

How to decode a string to Lua table:
<syntaxhighlight lang="lua">
local str="$blueprint_string";

local bp_to_table=function(instr)

--[[version and the body part]]
local version=string.sub(instr,1,1);
local body=string.sub(instr,2);
--[[then decode it]]
local json_str=game.decode_string(body);
--[[then turn it into table]]
local output=game.json_to_table(json_str);

return output;
end

--[[and this could test if it print properly]]
game.print( serpent.block( bp_to_table(str) ) );

</syntaxhighlight>

Tutorial:Localisation

2024-11-09T22:19:06Z

PennyJim: Update plural_for_parameter's 2.0 syntax

{{Languages}}Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called '''localisation'''.

== File format ==
Translations are stored as .cfg files, with the following format:

<pre>welcome-message=Hello world
[category]
title=Category related title
# Comment
; Another comment</pre>
Any whitespace after or before <code>=</code> is included in the key or string, so <code>title =Category related title</code> will give an unknown key error if you are looking for the <code>title</code> key, since it is the <code>title </code> key.

<code>category</code> can be one of the existing locale categories, which permits implicit search mechanisms to find translations, but may also be another key, such as <code>[my-mod-messages]</code>. These are accessible the same as other translations, e.g. <code>{"my-mod-messages.hello"}</code>

These files are located within the language code of the language in the locale folder of the mod, so as an English example <code>__mod__/locale/en/any_name_here.cfg</code>. There can be more than 1 file per language, all of them will be read.

== Localising simple strings ==
The simplest localisation is of items, entities etc. If we say the item is <code>iron-plate</code>, the game will then search all loaded locale files for <code>item-name.iron-plate</code> and <code>item-description.iron-plate</code>, which in the locale file looks like this:

<pre>[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.</pre>
If found in the locale, the label is set to this string. If not found, the game will instead show: <code>Unknown key: "item-name.iron-plate"</code>

In script, the localised string is formatted as <code>{"category.name"}</code>, so <code>game.print({"item-name.iron-plate"})</code> prints ''Iron plate''.

It is possible to use [[rich text]] features in the localised text if the location where the text is shown supports it, e.g. in the chat, prototype names and prototype tooltips.

<code>\n</code> can be used for line breaks if the location where the text is shown supports multiline text.

The list of all localization categories used by the base game is:

{| class="mw-collapsible mw-collapsed wikitable"
|-
!Localization categories
|-
|<code>[achievement-description]</code>
|-
|<code>[achievement-name]</code>
|-
|<code>[ammo-category-name]</code>
|-
|<code>[autoplace-control-names]</code>
|-
|<code>[controls]</code>
|-
|<code>[damage-type-name]</code>
|-
|<code>[decorative-name]</code>
|-
|<code>[entity-description]</code>
|-
|<code>[entity-name]</code>
|-
|<code>[equipment-name]</code>
|-
|<code>[fluid-name]</code>
|-
|<code>[fuel-category-name]</code>
|-
|<code>[item-description]</code>
|-
|<code>[item-group-name]</code>
|-
|<code>[item-limitation]</code>
|-
|<code>[item-name]</code>
|-
|<code>[map-gen-preset-description]</code>
|-
|<code>[map-gen-preset-name]</code>
|-
|<code>[mod-description]</code>
|-
|<code>[mod-name]</code>
|-
|<code>[modifier-description]
|-
|<code>[programmable-speaker-instrument]</code>
|-
|<code>[programmable-speaker-note]</code>
|-
|<code>[recipe-name]</code>
|-
|<code>[shortcut]</code>
|-
|<code>[story]</code>
|-
|<code>[string-mod-setting]</code>
|-
|<code>[technology-description]</code>
|-
|<code>[technology-name]</code>
|-
|<code>[tile-name]</code>
|-
|<code>[tips-and-tricks-item-description]</code>
|-
|<code>[tips-and-tricks-item-name]</code>
|-
|<code>[virtual-signal-description]</code>
|-
|<code>[virtual-signal-name]</code>
|}

== Localising with parameters ==
For more complex strings, localisation parameters can be used. For instance we want to show ''Time left: 10 minutes.''

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

<pre>time-left=Time left: __1__ minutes.</pre>
So it is used like this:

<syntaxhighlight lang="lua">game.print({"time-left", 10})</syntaxhighlight>
It also works with multiple parameters:

<syntaxhighlight lang="lua">game.print({"time-left", 10, 45})</syntaxhighlight>
<pre>time-left=Time left: __1__ minutes and __2__ seconds.</pre>
Which results in ''Time left: 10 minutes and 45 seconds.''

=== Built-in parameters ===
For some situations, we use localisation to show control schemes. For instance we want to say:

<pre>technology-prompt=Use T to open the technology screen</pre>
However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

<pre>technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.</pre>
We can also use this for items and entities:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>
<pre>tiny-gun-turret=Tiny __ENTITY__gun-turret__</pre>

==== List of built-in parameters ====
<code>name</code> is the name of an internal game control or a prototype name, depending on context. <code>n</code> can be 1 or 2, it's used in parameters that control [[#Localising_alternate_input_names|alternate input names]]. For a list of internal game control names, see [https://lua-api.factorio.com/latest/types/LinkedGameControl.html CustomInputPrototype::linked_game_control].
* <code>__CONTROL__name__</code> - The combination of modifiers and input, such as "Control + Alt + Left-click", or "Not set".
* <code>__CONTROL_MODIFIER__name__</code> - The modifiers, such as "ControlShift", or, "No modifier selected."
* <code>__CONTROL_STYLE_BEGIN__</code>
* <code>__CONTROL_STYLE_END__</code>
* <code>__CONTROL_LEFT_CLICK__</code> is replaced with <code>control-keys.mouse-button-1</code> or <code>control-keys.controller-b</code>[https://crowdin.com/project/factorio/discussions/214]
* <code>__CONTROL_RIGHT_CLICK__</code> is replaced with <code>control-keys.mouse-button-2</code> or <code>control-keys.controller-x</code>
* <code>__CONTROL_KEY_SHIFT__</code> is replaced with <code>control-keys.shift</code> or <code>control-keys.controller-leftshoulder</code>
* <code>__CONTROL_KEY_CTRL__</code> is replaced with <code>control-keys.control</code> or <code>control-keys.controller-rightshoulder</code>
* <code>__ALT_CONTROL_LEFT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-1-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-b</code>)
* <code>__ALT_CONTROL_RIGHT_CLICK__n__</code> is replaced with <code>control-keys.mouse-button-2-alt-n</code> or <code>control-keys.controller-button-alt-n</code> (with parameter <code>control-keys.controller-x</code>)
* <code>__REMARK_COLOR_BEGIN__</code>
* <code>__REMARK_COLOR_END__</code>
* <code>__ALT_CONTROL__n__name__</code>
* <code>__CONTROL_MOVE__</code> - The Movement keys, squished together. Example: "WASD", from a conventional QWERTY English keyboard.
* <code>__ENTITY__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/EntityPrototype.html EntityPrototype] subclass.
* <code>__ITEM__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/ItemPrototype.html ItemPrototype] or subclass.
* <code>__TILE__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/TilePrototype.html TilePrototype].
* <code>__FLUID__name__</code> - The localised name of the [https://lua-api.factorio.com/latest/prototypes/FluidPrototype.html FluidPrototype].

=== Plurals ===
Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

<pre>format-days=__1__ __plural_for_parameter__1__{1=day|rest=days}__</pre>
This results in "1 day" and "2 days" / "500 days" etc.

The number after <code>__plural_for_parameter__</code> denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |.
The text in front of the = determines for what the plural form is used. Options for this are:
* a simple number, e.g. "1".
* Multiple numbers, e.g. "2,3,4".
* What the number ends with, e.g. "ends in 11" or "ends in 1"
* Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
* "rest" to give the default plural.

'''Starting with version 2.0''', there have to be two underscores surrounding the number that denotes which parameter is used to determine the plural: <code>__plural_for_parameter__1__{1=day|rest=days}__</code>

Plural forms may be empty or contain other keys such as __1__ or spaces. This allows rather large plural forms:

<pre>__plural_for_parameter__1__{1=__1__ player is|rest=__1__ players are}__ connecting</pre>

The system chooses the first fitting plural that it encounters when multiple would fit:
<pre>__plural_for_parameter__1__{ends in 12=option 1|ends in 2=option 2|rest=option 3}__</pre>
This will result in "option 1" for 12 and in "option 2" for 22 and in "option 3" for numbers not ending with 2.

=== Concatenating localised strings ===
The special locale key: <code>""</code> is used to concatenate, as the table format does not support concatenation:

<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>
Will result in: ''Iron plate: 60''

=== Localising alternate input names ===

In the introduction campaign, a special locale system is used for informing players how to do certain actions with their mouse.
The normal form is to use eg:
<pre>how-to-build=Use __CONTROL__build__ to place a building</pre>
which results in "Use Left mouse button to place a building". A more natural phrasing would be "Left-click to place a building", which can be achieved by using the following:
<pre>how-to-build=__ALT_CONTROL__1__build__ to place a building</pre>

These "alt" versions are controlled by a few special locale keys, mouse-button-X-alt-1 and mouse-button-X-alt-2. In English, form 1 produces eg "Left-click", and form 2 produces eg "Left-clicking". Only two alt forms ("1" and "2") are available at the moment, but if this a problem for some languages, more forms may be added in the future.
Extra mouse buttons, mouse scroll and keyboard keys are handled through the mouse-button-n-alt-1/2, mouse-wheel-alt-1/2 and keyboard-alt-1/2 keys, which just take the normal name and prepend something like "Press/Pressing", or "Scroll/Scrolling".

When translating to another language, you can use whatever forms you want here, but the important part is that you are consistent when you use the alt-forms everywhere else. It does not necessarily make sense to just copy the usages of alt forms from the English locale, and for some languages it may be more natural to simply not use this system at all.

== Accessing the localised result in code ==
While usually unneeded, it is possible to read the resulting localised text in code, for example to search in localised names. See [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.request_translation LuaPlayer::request_translation] and [https://lua-api.factorio.com/latest/events.html#on_string_translated on_string_translated event].

== Default Behavior(s) for finding an Unspecified Localised String ==
If a localised_string is not defined in the prototype for certain prototype classes, e.g. entity, item, Factorio may have a default search behavior.

Determining an item's localised name:
Note: the angle brackets are meant to mean a generic term, they are not part of the actual string. Also, place_result and placed_as_equipment_result are strings, and Factorio fetches the matching prototype to examine.

# if localised_name is provided in the item prototype and it is not empty {}, use the provided value
# else if there is place_result and it has localised_name that is not an empty table: {}, use the localised_name of place_result
# else if there is place_result with an empty localised_name, use {"entity-name.<entity prototype name>"}
# else if there is placed_as_equipment_result and it has a localised_name that is not an empty table: {}, use the localised_name of placed_as_equipment_result
# else if there is placed_as_equipment_result with empty localised_name, use {"equipment-name.<equipment name>"}
# else use default {"item-name.<item name>"}

Reference: [https://forums.factorio.com/viewtopic.php?p=494243#p494243]

Example: The transport-belt item does not have a localised_name, so 1->2. There is a place result, but not localised_name in the entity prototype. 2->3. The place result lacks a localised_name. Use the localised string {"entity-name.transport-belt"}

Such defaults often include a "leading key" using [<group>-name] or [<group>-description] (such as [recipe-name], [mod-setting-description]). However, each prototype may have a distinct search behavior before using those, based on presence/absence of values in the prototype. [[Prototype/Recipe]] for example may use the first product's localised_name, or the main_product's localised_name, or the localised string found in {"recipe-name.<recipe name>"], depending on values provided (and lacking) in the prototype.

== See also ==
* [[Types/LocalisedString|LocalisedString data stage doc]]
* [https://lua-api.factorio.com/latest/Concepts.html#LocalisedString LocalisedString control stage doc]

[[Category:Modding]]

Talk:Version history/2.0.0

2024-11-08T23:35:30Z

PennyJim:

== Maybe we should replace [space-age] with {{SA}} ==

[space-age] is a rich text tag that turns into the icon in game, it would be more accurate to replicate it. I don't feel confident enough to make that decision on my own. If anything, maybe we use a slightly different template that has `[space-age]` as the alt text? Regardless of what we choose to do, [[User:Bilka|Bilka]] will need to update their bot to do the conversion as well -- [[User:PennyJim|PennyJim]] ([[User talk:PennyJim|talk]]) 23:35, 8 November 2024 (UTC)

== Kovarex enrichment process is '''NOT''' unlocked by automation, logistic and chemical science packs only. ==

According to patch notes "Kovarex enrichment process" should be unlocked by red, green and blue packs but need also space ones. ~~ [[User:Mefisto1029|Mefisto1029]] ([[User talk:Mefisto1029|talk]]) 10:29, 23 October 2024 (UTC)
: This is only changed when the space age mod is active. Without the mod active (so, without the expansion), the technology does not require space science packs. I adjusted the [[Infobox:Kovarex_enrichment_process_(research)]] accordingly, now that the template supports this. -- [[User:Bilka|Bilka]] ([[User talk:Bilka|talk]]) - Admin 12:34, 24 October 2024 (UTC)

Rich text

2024-11-07T20:04:51Z

PennyJim: Add the [space-age] tag

{{Languages}}
Rich text formatting in allows the use of tags within most of the game's textboxes to change the visual formatting of text or to embed interactable images/entities. Predefined text tags are employed for this purpose.

== Tags ==

Tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations.
Ctrl+alt clicking the map or ground will automatically insert a gps tag and post it into [[console|chat]].

Shift clicking most things with the console open will insert a tag for that thing into chat. The chat and many other textboxes in the game have a button on the right edge that opens an icon selector. This can be used to easily insert rich text tags of recipes, items, fluids, virtual signals and entities into the textbox.

When used in chat, the tag image will be followed by a text description, except for the img tag.
Used elsewhere only the image is shown.

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description

|-
| [img=class/name] 
[img=class.name] 
[img=sprite-prototype-name]
| [img=item.iron-plate] 
[img=quantity-time] 
[img=utility/played_green]
| [[File:Iron_plate.png|28px]] 
[[File:Time_icon.png|28px]] 
[[File:Played green.png|28px]]
| Embeds only a small inline game graphic. The period format must be used in game save names. This tag uses [https://lua-api.factorio.com/latest/Concepts.html#SpritePath sprite paths]:
class is any of: item, entity, technology, recipe, item-group, fluid, tile, virtual-signal, achievement, equipment, space-location or utility.

name: see below

sprite-prototype-name is the [[Data.raw#sprite|internal-name]] of a [[Prototype/Sprite|sprite prototype]].

|-
| [item=name]
| [item=iron-plate]
| [[File:Iron_plate.png|28px]] [Item: Iron plate]
| name is the internal-name of the item

|-
| [entity=name]
| [entity=small-biter]
| [[File:Small_biter.png|28px]] [Entity: Small biter]
| name is the internal-name of the entity

|-
| [technology=name]
| [technology=logistics]
| [[File:Logistics_(research).png|28px]] [Technology: Logistics]
| name is the internal-name of the technology

|-
| [recipe=name]
| [recipe=basic-oil-processing]
| [[File:Basic_oil_processing.png|28px]] [Recipe: Basic oil processing]
| name is the internal-name of the recipe, usually the item name

|-
| [item-group=name]
| [item-group=combat]
| [[File:Item-group_military.png|28px]] [Item Group: Combat]
| name is any of: logistics, production, intermediate-products, combat, fluids or signals

|-
| [fluid=name]
| [fluid=water]
| [[File:Water.png|28px]] [Fluid: Water]
| name is the internal name of the fluid

|-
| [tile=name]
| [tile=grass-3]
| [[File:Grass_3.png|28px]] [Tile: Grass 3]
| name is the internal name of the tile, usually the lowercase name with hyphens replacing spaces as written from the map editor

|-
| [virtual-signal=name]
| [virtual-signal=signal-A]
| [[File:Signal-A.png|28px]] [Virtual Signal: Signal A]
| name is the word signal followed by either an uppercase letter, number, color, each, everything or anything

|-
| [achievement=name]
| [achievement=minions]
| [[File:Minions-achievement.png|28px]] [Achievement: Minions]
| name is the internal-name of the achievement, usually the lowercase name with hyphens replacing spaces

|-
| [gps=x,y]
[gps=x,y,surface]
| [gps=0,0]
| [[File:Map.png|28px]] [Location: 0,0]
| Embeds a map location and marks the location on the map of other players.
x is the x point coordinate 
y is the y point coordinate 
surface is the current surface. Is only added if the player Ctrl+alt clicks on a surface that is not the default surface. When the player is on another surface than surface, clicking the tag does nothing. Mods must handle this case with [https://lua-api.factorio.com/latest/events.html#on_player_clicked_gps_tag on_player_clicked_gps_tag]
|-
| [special-item=blueprint_string]
|
| [[File:Blueprint.png|28px]] [Blueprint]
| Embeds a blueprint. Players can get a blueprint item by clicking the icon.
blueprint_string is the blueprint string of a blueprint, deconstruction planner or upgrade planners

|-
| [armor=player]
| [armor=Player]
| [[File:Power_armor_MK2.png|28px]] [Armor: Player]
| Embeds the armor of a player. Allows other players to see the equipment installed.
player is the name of the player

|-
| [train=number]
| [train=93]
| [[File:Locomotive.png|28px]] [Train: 2]
| Embeds a reference to a train. Clicking the icon will open the train GUI for that train.
number is the internal unit number of the train

|-
| [train-stop=number]
| [train-stop=100]
| [[File:Train_stop.png|28px]] [Train Stop: Trangar]
| Embeds a reference to a train stop. Clicking the icon will open the GUI for that train stop.
number is the internal unit number of the train stop

|-
| [tooltip=text,tooltip locale key]
| [tooltip=Hover to see "Iron plate",item-name.iron-plate]
| [[File:Custom-tag-icon.png|28px]] Hover to see "Iron plate"
| Shows the given text with a tooltip that is specified with a [[Tutorial:Localisation#Localising_simple_strings|locale key]].

|-
| [quality=tier] 
[item=name,quality=tier] 
[entity=name,quality=tier] 

|[quality=normal] 
[item=iron-plate,quality=normal] 
[entity=small-biter,quality=uncommon] 

| [[File:Quality normal.png|28px]] [Quality: Normal] 
[[File:Iron_plate.png|28px]] [Item: Iron plate] 
[[File:Uncommon small biter.png|28px]] [Entity: Uncommon Small biter] 
|
[[Quality]] can also be optionally specified on the following tags: item, entity, recipe, fluid, and virtual-signal 
It can also be added to the other tags that use name, but they ignore it.

The normal quality is the default quality and won't modify tags. Any other quality won't exist without [[Space Age]] and Quality

tier is the internal-name of the quality

|-
| [planet=name]
| [planet=gleba]
| [[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a planet.
Available planets in Space Age are: nauvis, gleba, fulgora, vulcanus, and aquilo.

[[Nauvis]] is part of the base game and will always be available.

|-
| [space-location=name]
| [space-location=shattered-planet]
[space-location=gleba]
| [[File:Shattered Planet.png|28px]] [Space location: Shattered Planet]
[[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a space-location in Space Age.
Available locations in Space Age are: nauvis, gleba, fulgora, vulcanus, aquilo, solar-system-edge, and shattered-planet.

For the planet's listed in the section above 'planet' will be used as the text prefix instead of 'space-location'

|-
| [space-age]
| [space-age]
| [[File:Space_age_icon.png|28px]]
| Embeds the Space Age icon.
|}

== Text modifiers ==
[[File:Fonts.png|right|thumbnail|100px|Different fonts displayed in-game. (Click to enlarge.)]]

The color and font of text can be changed

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description
|-
| [color=rgb]...[/color] 
[color=#rrggbb]...[/color] 
[color=#aarrggbb]...[/color] 
[color=rgb]...[.color] 
[color=#rrggbb]...[.color] 
[color=#aarrggbb]...[.color]
| [color=red]Red[/color] text 
[color=1,0,0]Red[/color] text 
[color=255,0,0]Red[/color] text 
[color=#ff0000]Red[/color] text
| Red text
| rgb is a comma separated RGB color ranging from 0 to 1 or 0 to 255, or a color name
Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
|-
| [font=font-name]...[/font] 
[font=font-name]...[.font]
| [font=default-bold]Bold text[/font]
| Bold text
| font-name is the name of the [[Data.raw#font|Factorio font]] to render
|}

== See also ==
* [[Console]]
* [[Data.raw]] for the list of internal names of recipes, technologies, fluids, etc.

{{C|GUI}}

Rich text

2024-11-07T19:55:25Z

PennyJim: Clarify that Nauvis is always defined.

{{Languages}}
Rich text formatting in allows the use of tags within most of the game's textboxes to change the visual formatting of text or to embed interactable images/entities. Predefined text tags are employed for this purpose.

== Tags ==

Tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations.
Ctrl+alt clicking the map or ground will automatically insert a gps tag and post it into [[console|chat]].

Shift clicking most things with the console open will insert a tag for that thing into chat. The chat and many other textboxes in the game have a button on the right edge that opens an icon selector. This can be used to easily insert rich text tags of recipes, items, fluids, virtual signals and entities into the textbox.

When used in chat, the tag image will be followed by a text description, except for the img tag.
Used elsewhere only the image is shown.

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description

|-
| [img=class/name] 
[img=class.name] 
[img=sprite-prototype-name]
| [img=item.iron-plate] 
[img=quantity-time] 
[img=utility/played_green]
| [[File:Iron_plate.png|28px]] 
[[File:Time_icon.png|28px]] 
[[File:Played green.png|28px]]
| Embeds only a small inline game graphic. The period format must be used in game save names. This tag uses [https://lua-api.factorio.com/latest/Concepts.html#SpritePath sprite paths]:
class is any of: item, entity, technology, recipe, item-group, fluid, tile, virtual-signal, achievement, equipment, space-location or utility.

name: see below

sprite-prototype-name is the [[Data.raw#sprite|internal-name]] of a [[Prototype/Sprite|sprite prototype]].

|-
| [item=name]
| [item=iron-plate]
| [[File:Iron_plate.png|28px]] [Item: Iron plate]
| name is the internal-name of the item

|-
| [entity=name]
| [entity=small-biter]
| [[File:Small_biter.png|28px]] [Entity: Small biter]
| name is the internal-name of the entity

|-
| [technology=name]
| [technology=logistics]
| [[File:Logistics_(research).png|28px]] [Technology: Logistics]
| name is the internal-name of the technology

|-
| [recipe=name]
| [recipe=basic-oil-processing]
| [[File:Basic_oil_processing.png|28px]] [Recipe: Basic oil processing]
| name is the internal-name of the recipe, usually the item name

|-
| [item-group=name]
| [item-group=combat]
| [[File:Item-group_military.png|28px]] [Item Group: Combat]
| name is any of: logistics, production, intermediate-products, combat, fluids or signals

|-
| [fluid=name]
| [fluid=water]
| [[File:Water.png|28px]] [Fluid: Water]
| name is the internal name of the fluid

|-
| [tile=name]
| [tile=grass-3]
| [[File:Grass_3.png|28px]] [Tile: Grass 3]
| name is the internal name of the tile, usually the lowercase name with hyphens replacing spaces as written from the map editor

|-
| [virtual-signal=name]
| [virtual-signal=signal-A]
| [[File:Signal-A.png|28px]] [Virtual Signal: Signal A]
| name is the word signal followed by either an uppercase letter, number, color, each, everything or anything

|-
| [achievement=name]
| [achievement=minions]
| [[File:Minions-achievement.png|28px]] [Achievement: Minions]
| name is the internal-name of the achievement, usually the lowercase name with hyphens replacing spaces

|-
| [gps=x,y]
[gps=x,y,surface]
| [gps=0,0]
| [[File:Map.png|28px]] [Location: 0,0]
| Embeds a map location and marks the location on the map of other players.
x is the x point coordinate 
y is the y point coordinate 
surface is the current surface. Is only added if the player Ctrl+alt clicks on a surface that is not the default surface. When the player is on another surface than surface, clicking the tag does nothing. Mods must handle this case with [https://lua-api.factorio.com/latest/events.html#on_player_clicked_gps_tag on_player_clicked_gps_tag]
|-
| [special-item=blueprint_string]
|
| [[File:Blueprint.png|28px]] [Blueprint]
| Embeds a blueprint. Players can get a blueprint item by clicking the icon.
blueprint_string is the blueprint string of a blueprint, deconstruction planner or upgrade planners

|-
| [armor=player]
| [armor=Player]
| [[File:Power_armor_MK2.png|28px]] [Armor: Player]
| Embeds the armor of a player. Allows other players to see the equipment installed.
player is the name of the player

|-
| [train=number]
| [train=93]
| [[File:Locomotive.png|28px]] [Train: 2]
| Embeds a reference to a train. Clicking the icon will open the train GUI for that train.
number is the internal unit number of the train

|-
| [train-stop=number]
| [train-stop=100]
| [[File:Train_stop.png|28px]] [Train Stop: Trangar]
| Embeds a reference to a train stop. Clicking the icon will open the GUI for that train stop.
number is the internal unit number of the train stop

|-
| [tooltip=text,tooltip locale key]
| [tooltip=Hover to see "Iron plate",item-name.iron-plate]
| [[File:Custom-tag-icon.png|28px]] Hover to see "Iron plate"
| Shows the given text with a tooltip that is specified with a [[Tutorial:Localisation#Localising_simple_strings|locale key]].

|-
| [quality=tier] 
[item=name,quality=tier] 
[entity=name,quality=tier] 

|[quality=normal] 
[item=iron-plate,quality=normal] 
[entity=small-biter,quality=uncommon] 

| [[File:Quality normal.png|28px]] [Quality: Normal] 
[[File:Iron_plate.png|28px]] [Item: Iron plate] 
[[File:Uncommon small biter.png|28px]] [Entity: Uncommon Small biter] 
|
[[Quality]] can also be optionally specified on the following tags: item, entity, recipe, fluid, and virtual-signal 
It can also be added to the other tags that use name, but they ignore it.

The normal quality is the default quality and won't modify tags. Any other quality won't exist without [[Space Age]] and Quality

tier is the internal-name of the quality

|-
| [planet=name]
| [planet=gleba]
| [[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a planet.
Available planets in Space Age are: nauvis, gleba, fulgora, vulcanus, and aquilo.

[[Nauvis]] is part of the base game and will always be available.

|-
| [space-location=name]
| [space-location=shattered-planet]
[space-location=gleba]
| [[File:Shattered Planet.png|28px]] [Space location: Shattered Planet]
[[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a space-location in Space Age.
Available locations in Space Age are: nauvis, gleba, fulgora, vulcanus, aquilo, solar-system-edge, and shattered-planet.

For the planet's listed in the section above 'planet' will be used as the text prefix instead of 'space-location'

|}

== Text modifiers ==
[[File:Fonts.png|right|thumbnail|100px|Different fonts displayed in-game. (Click to enlarge.)]]

The color and font of text can be changed

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description
|-
| [color=rgb]...[/color] 
[color=#rrggbb]...[/color] 
[color=#aarrggbb]...[/color] 
[color=rgb]...[.color] 
[color=#rrggbb]...[.color] 
[color=#aarrggbb]...[.color]
| [color=red]Red[/color] text 
[color=1,0,0]Red[/color] text 
[color=255,0,0]Red[/color] text 
[color=#ff0000]Red[/color] text
| Red text
| rgb is a comma separated RGB color ranging from 0 to 1 or 0 to 255, or a color name
Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
|-
| [font=font-name]...[/font] 
[font=font-name]...[.font]
| [font=default-bold]Bold text[/font]
| Bold text
| font-name is the name of the [[Data.raw#font|Factorio font]] to render
|}

== See also ==
* [[Console]]
* [[Data.raw]] for the list of internal names of recipes, technologies, fluids, etc.

{{C|GUI}}

Rich text

2024-11-07T19:26:01Z

PennyJim: Add space-location as a class option for img tag

{{Languages}}
Rich text formatting in allows the use of tags within most of the game's textboxes to change the visual formatting of text or to embed interactable images/entities. Predefined text tags are employed for this purpose.

== Tags ==

Tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations.
Ctrl+alt clicking the map or ground will automatically insert a gps tag and post it into [[console|chat]].

Shift clicking most things with the console open will insert a tag for that thing into chat. The chat and many other textboxes in the game have a button on the right edge that opens an icon selector. This can be used to easily insert rich text tags of recipes, items, fluids, virtual signals and entities into the textbox.

When used in chat, the tag image will be followed by a text description, except for the img tag.
Used elsewhere only the image is shown.

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description

|-
| [img=class/name] 
[img=class.name] 
[img=sprite-prototype-name]
| [img=item.iron-plate] 
[img=quantity-time] 
[img=utility/played_green]
| [[File:Iron_plate.png|28px]] 
[[File:Time_icon.png|28px]] 
[[File:Played green.png|28px]]
| Embeds only a small inline game graphic. The period format must be used in game save names. This tag uses [https://lua-api.factorio.com/latest/Concepts.html#SpritePath sprite paths]:
class is any of: item, entity, technology, recipe, item-group, fluid, tile, virtual-signal, achievement, equipment, space-location or utility.

name: see below

sprite-prototype-name is the [[Data.raw#sprite|internal-name]] of a [[Prototype/Sprite|sprite prototype]].

|-
| [item=name]
| [item=iron-plate]
| [[File:Iron_plate.png|28px]] [Item: Iron plate]
| name is the internal-name of the item

|-
| [entity=name]
| [entity=small-biter]
| [[File:Small_biter.png|28px]] [Entity: Small biter]
| name is the internal-name of the entity

|-
| [technology=name]
| [technology=logistics]
| [[File:Logistics_(research).png|28px]] [Technology: Logistics]
| name is the internal-name of the technology

|-
| [recipe=name]
| [recipe=basic-oil-processing]
| [[File:Basic_oil_processing.png|28px]] [Recipe: Basic oil processing]
| name is the internal-name of the recipe, usually the item name

|-
| [item-group=name]
| [item-group=combat]
| [[File:Item-group_military.png|28px]] [Item Group: Combat]
| name is any of: logistics, production, intermediate-products, combat, fluids or signals

|-
| [fluid=name]
| [fluid=water]
| [[File:Water.png|28px]] [Fluid: Water]
| name is the internal name of the fluid

|-
| [tile=name]
| [tile=grass-3]
| [[File:Grass_3.png|28px]] [Tile: Grass 3]
| name is the internal name of the tile, usually the lowercase name with hyphens replacing spaces as written from the map editor

|-
| [virtual-signal=name]
| [virtual-signal=signal-A]
| [[File:Signal-A.png|28px]] [Virtual Signal: Signal A]
| name is the word signal followed by either an uppercase letter, number, color, each, everything or anything

|-
| [achievement=name]
| [achievement=minions]
| [[File:Minions-achievement.png|28px]] [Achievement: Minions]
| name is the internal-name of the achievement, usually the lowercase name with hyphens replacing spaces

|-
| [gps=x,y]
[gps=x,y,surface]
| [gps=0,0]
| [[File:Map.png|28px]] [Location: 0,0]
| Embeds a map location and marks the location on the map of other players.
x is the x point coordinate 
y is the y point coordinate 
surface is the current surface. Is only added if the player Ctrl+alt clicks on a surface that is not the default surface. When the player is on another surface than surface, clicking the tag does nothing. Mods must handle this case with [https://lua-api.factorio.com/latest/events.html#on_player_clicked_gps_tag on_player_clicked_gps_tag]
|-
| [special-item=blueprint_string]
|
| [[File:Blueprint.png|28px]] [Blueprint]
| Embeds a blueprint. Players can get a blueprint item by clicking the icon.
blueprint_string is the blueprint string of a blueprint, deconstruction planner or upgrade planners

|-
| [armor=player]
| [armor=Player]
| [[File:Power_armor_MK2.png|28px]] [Armor: Player]
| Embeds the armor of a player. Allows other players to see the equipment installed.
player is the name of the player

|-
| [train=number]
| [train=93]
| [[File:Locomotive.png|28px]] [Train: 2]
| Embeds a reference to a train. Clicking the icon will open the train GUI for that train.
number is the internal unit number of the train

|-
| [train-stop=number]
| [train-stop=100]
| [[File:Train_stop.png|28px]] [Train Stop: Trangar]
| Embeds a reference to a train stop. Clicking the icon will open the GUI for that train stop.
number is the internal unit number of the train stop

|-
| [tooltip=text,tooltip locale key]
| [tooltip=Hover to see "Iron plate",item-name.iron-plate]
| [[File:Custom-tag-icon.png|28px]] Hover to see "Iron plate"
| Shows the given text with a tooltip that is specified with a [[Tutorial:Localisation#Localising_simple_strings|locale key]].

|-
| [quality=tier] 
[item=name,quality=tier] 
[entity=name,quality=tier] 

|[quality=normal] 
[item=iron-plate,quality=normal] 
[entity=small-biter,quality=uncommon] 

| [[File:Quality normal.png|28px]] [Quality: Normal] 
[[File:Iron_plate.png|28px]] [Item: Iron plate] 
[[File:Uncommon small biter.png|28px]] [Entity: Uncommon Small biter] 
|
[[Quality]] can also be optionally specified on the following tags: item, entity, recipe, fluid, and virtual-signal 
It can also be added to the other tags that use name, but they ignore it.

The normal quality is the default quality and won't modify tags. Any other quality won't exist without [[Space Age]] and Quality

tier is the internal-name of the quality

|-
| [planet=name]
| [planet=gleba]
| [[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a planet in Space Age. Available planets are: nauvis, gleba, fulgora, vulcanus, and aquilo.

|-
| [space-location=name]
| [space-location=shattered-planet]
[space-location=gleba]
| [[File:Shattered Planet.png|28px]] [Space location: Shattered Planet]
[[File:Gleba.png|28px]] [Planet: Gleba]
| name is the internal name of a space-location in Space Age. Available locations are: nauvis, gleba, fulgora, vulcanus, aquilo, solar-system-edge, and shattered-planet.
For the planet's listed in the section above 'planet' will be used as the text prefix instead of 'space-location'
|}

== Text modifiers ==
[[File:Fonts.png|right|thumbnail|100px|Different fonts displayed in-game. (Click to enlarge.)]]

The color and font of text can be changed

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description
|-
| [color=rgb]...[/color] 
[color=#rrggbb]...[/color] 
[color=#aarrggbb]...[/color] 
[color=rgb]...[.color] 
[color=#rrggbb]...[.color] 
[color=#aarrggbb]...[.color]
| [color=red]Red[/color] text 
[color=1,0,0]Red[/color] text 
[color=255,0,0]Red[/color] text 
[color=#ff0000]Red[/color] text
| Red text
| rgb is a comma separated RGB color ranging from 0 to 1 or 0 to 255, or a color name
Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
|-
| [font=font-name]...[/font] 
[font=font-name]...[.font]
| [font=default-bold]Bold text[/font]
| Bold text
| font-name is the name of the [[Data.raw#font|Factorio font]] to render
|}

== See also ==
* [[Console]]
* [[Data.raw]] for the list of internal names of recipes, technologies, fluids, etc.

{{C|GUI}}

Console

2024-11-07T02:40:32Z

PennyJim: Remove enable-research-queue (The command no longer exists because it now can't be disabled)

{{Languages}}
The '''console''' is Factorio's in-game command-line interface. See [[command line parameters]] for the command line interface of the Factorio executable.

The in-game console can be used for:

* Chatting with other players
* Occasional status updates
* Running commands / scripts / cheats

There are three types of commands:

* '''[[#Normal commands|Normal]]''' - Display information about the game and customize your experience.
* '''[[#Multiplayer commands|Multiplayer]]''' - Message filtering, banning users, etc.
* '''[[#Scripting and cheat commands|Scripting/Cheating]]''' - Run small Lua scripts (but they disable achievements for the save game)

__TOC__

=== Using the console ===
The console display can be toggled with the {{Keybinding|grave}} key (<code>`</code>). This is the key located to the left of the <code>1</code> key, above <code>Tab</code>.

You can customize the keys via '''Settings menu → Controls → Toggle chat (and Lua console)'''.
When the console is open, you'll see a blinking cursor at the bottom of the screen; type your message or command and hit '''Return''' to send it (this will also close the console).
Documentation about message and command prefixes can be found further down this page.

The console supports [[rich text]] tags. These tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations. Ctrl + Alt-clicking the map or ground will automatically insert a GPS tag and post it into the console. Shift-clicking most things with the console open will insert a tag for that thing into the console.

When the console is closed, only the most recent messages/commands will be displayed, but they will gradually fade away (opening the console will immediately re-display all recent messages).
Note that by default, all executed commands are made visible to all users. The fade-out time can be changed via '''Settings menu → Interface → Chat message delay'''.

The console can be cleared with the '''/clear''' command.

Use the {{keybinding|↑}} and {{keybinding|↓}} keys to scroll through the console history. The {{keybinding|Tab}} key provides intelligent code completion on commands, options and player names.

== Normal commands ==

{| class="wikitable"
|-
! style="width:25%"| Command
! style="width:25%"| Example
! style="width:46%"| Description
! style="width:4%"| Admin only
|-
| /alerts <enable/disable/mute/unmute> <alert>
| /alerts disable turret_fire
| Enables, disables, mutes, or unmutes the given [[alerts|alert]] type. Available alerts: entity_destroyed, entity_under_attack, not_enough_construction_robots, no_material_for_construction, not_enough_repair packs, turret_fire, custom, no_storage, train_out_of_fuel, fluid_mixing.
| No
|-
| /clear
| /clear
| Clears the console.
| No
|-
| /color <color>
| /color 20 255 255
| Changes your color. Can either be one of the pre-defined colors or [[:Wikipedia:RGB_color_space|RGB value]] in the format of “# # #”. Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
| No
|-
| /evolution
| /evolution
| Prints info about the alien evolution factor.
| No
|-
| /help [command]
| /help
| Prints a list of available commands, the optional argument can specify the command that should be described.
| No
|-
| /h [command]
| /h
| Same as /help.
| No
|-
| /mute-programmable-speaker <mute/unmute> <local/everyone>
| /mute-programmable-speaker mute local
| Mutes or unmutes the global sounds created by the Programmable Speaker. Use “local” to mute just the local client. Admins can use “everyone” to mute the sounds for everyone on the server.
| No
|-
| /perf-avg-frames <number>
| /perf-avg-frames 100
| Number of ticks/updates used to average performance counters. Default is 100. Value of 5-10 is recommended for fast convergence, but numbers will jitter more rapidly.
| No
|-
| /permissions
| /permissions
| Opens the [[permissions]] GUI.
| Yes
|-
| /permissions <action> <parameters>
| /permissions add-player DeveloperGroup kovarex
| Available actions are add-player <group> <player>, create-group <name>, delete-group <group>, edit-group <group> <input_action> <true/false>, get-player-group <player>, remove-player <group> <player>, rename-group <group> <new_name> and reset
| Yes
|-
| /reset-tips
| /reset-tips
| Resets the state of the tips and tricks as if the game was just started for the first time.
| No
|-
| /screenshot [x resolution] [y resolution] [zoom]
| /screenshot
| Takes a screenshot with the GUI hidden, centered on the player. It is saved in the "script-output" subfolder of your [[User data directory]]. Resolution is optional and defaults to the current window size. Zoom is optional and defaults to 1.
| No
|-
| /seed
| /seed
| Prints the starting map seed.
| No
|-
| /time
| /time
| Prints info about how old the map is.
| No
|-
| /toggle-action-logging
| /toggle-action-logging
| Toggles logging all input actions performed by the game. This value isn’t persisted between game restarts and only affects your local game in multiplayer sessions.
| Yes
|-
| /toggle-heavy-mode
| /toggle-heavy-mode
| Used to investigate [[Desynchronization#Using_heavy_mode_command|desyncs]]. Will slow down the game and make multiplayer unplayable.
| Yes
|-
| /unlock-shortcut-bar
| /unlock-shortcut-bar
| Unlocks all [[shortcut bar]] items, including blueprint string import, copy & paste, deconstruction and upgrade planner.
| No
|-
| /unlock-tips
| /unlock-tips
| Unlocks all tips and tricks entries.
| No
|-
| /version
| /version
| Prints the current game version.
| No
|-
|}

== Multiplayer commands ==
{| class="wikitable"
|-
! style="width:25%"| Command
! style="width:25%"| Example
! style="width:46%"| Description
! style="width:4%"| Admin only
|-
| <message>
| Hello team!
| Console input that does not start with {{keybinding|/}} is shown as a chat message to your team.
| No
|-
| /admin
| /admin
| Opens the player management GUI.
| Yes
|-
| /admins
| /admins
| Prints a list of game admins.
| No
|-
| /ban <player> <reason>
| /ban xTROLLx Throwing grenades in base
| Bans the specified player.
| Yes
|-
| /bans
| /bans
| Prints a list of banned players.
| No
|-
| /banlist <add/remove/get/clear> <player>
| /banlist get
| Adds or removes a player from the banlist. Same as /ban or /unban.
| No
|-
| /config
| /config
| Opens the server configuration GUI.
| Yes
|-
| /config <get/set> <option> <value>
| /config set password hunter2
| Gets or sets various multiplayer game settings. Available configs are: afk-auto-kick, allow-commands, allow-debug-settings, autosave-interval, autosave-only-on-server, ignore-player-limit-for-returning-players, max-players, max-upload-speed, only-admins-can-pause, password, require-user-verification, visibility-lan, visibility-public. The units for the options afk-auto-kick and autosave-interval are in minutes.
| Yes
|-
| /delete-blueprint-library <player>
| /delete-blueprint-library everybody confirm
| Deletes the blueprint library storage for the given offline player from the save file. Enter “everybody confirm” to delete the storage of all offline players.
| Yes
|-
| /demote <player>
| /demote AzureDiamond
| Demotes the player from admin.
| Yes
|-
| /ignore <player>
| /ignore Cthon98
| Prevents the chat from showing messages from this player. Admin messages are still shown.
| No
|-
| /ignores
| /ignores
| Prints a list of ignored players.
| No
|-
| /kick <player> <reason>
| /kick xTROLLx Throwing grenades in base
| Kicks the specified player.
| Yes
|-
| /mute <player>
| /mute Cthon98
| Prevents the player from saying anything in chat.
| Yes
|-
| /mutes
| /mutes
| All players that are muted (can’t talk in chat).
| No
|-
| /open <player>
| /open AzureDiamond
| Opens another player’s inventory.
| Yes
|-
| /o <player>
| /o AzureDiamond
| Same as /open.
| Yes
|-
| /players [online/o/count/c]
| /players
| Prints a list of players in the game. (parameter online/o, it prints only players that are online, count/c prints only count)
| No
|-
| /p [online/o/count/c]
| /p o c
| Same as /players.
| No
|-
| /promote <player>
| /promote AzureDiamond
| Promotes the player to admin.
| Yes
|-
| /purge <player>
| /purge Cthon98
| Clears all the messages from this player from the chat log.
| Yes
|-
| /reply <message>
| /reply oh, really?
| Replies to the last player that whispered to you.
| No
|-
| /r <message>
| /r oh, really?
| Same as /reply.
| No
|-
| /server-save
| /server-save
| Saves the game on the server in a multiplayer game.
| Yes
|-
| /shout <message>
| /shout Hello world!
| Sends a message to all players including other forces.
| No
|-
| /s <message>
| /s Hello world!
| Same as /shout.
| No
|-
| /swap-players <player> [player]
| /swap-players AzureDiamond
| Swaps your character with the given player’s character, or if two players are given swaps the two player characters.
| Yes
|-
| /unban <player>
| /unban xTROLLx
| Unbans the specified player.
| Yes
|-
| /unignore <player>
| /unignore Cthon98
| Allows the chat to show messages from this player.
| No
|-
| /unmute <player>
| /unmute Cthon98
| Allows the player to talk in chat again.
| Yes
|-
| /whisper <player> <message>
| /whisper AzureDiamond that's what I see
| Sends a message to the specified player.
| No
|-
| /w <player> <message>
| /w AzureDiamond that's what I see
| Same as /whisper.
| No
|-
| /whitelist <add/remove/get/clear> [player]
| /whitelist get
| Adds or removes a player from the whitelist, where only whitelisted players can join the game. Enter nothing for “player” when using “get” to print a list of all whitelisted players. An empty whitelist disables the whitelist functionality allowing anyone to join.
| No
|}

== Scripting and cheat commands ==
{| class="wikitable"
|-
! Command
! Description
|-
| /cheat [all/<planet-name>/<platform-name>/off]
| Researches all technologies and enables cheat mode (allowing free crafting of any item).
* Using the '''all''' option also gives the player some additional items.
* Specifying a ''planet-name'' or ''platform-name'' also moves the player to the origin of the specified planet or platform.
* Using the '''off''' option turns cheat mode off.
|-
| /command <command>
| Executes a Lua command (if allowed).
|-
| /c <command>
| Executes a Lua command (if allowed).
|-
| /editor
| Toggles the map editor.
|-
| /measured-command <command>
| Executes a Lua command (if allowed) and measures time it took.
|-
| /mc <command>
| Executes a Lua command (if allowed) and measures time it took.
|-
| /silent-command <command>
| Executes a Lua command (if allowed) without printing it to the console.
|-
| /sc <command>
| Executes a Lua command (if allowed) without printing it to the console.
|}

This is a very powerful feature, which also allows cheating, and as such achievements will be permanently disabled for the save as soon as you use a script command.

== Basic example scripts ==

=== Use it as calculator ===
<syntaxhighlight lang="lua">
/c game.player.print(1234*5678)
</syntaxhighlight>

=== Zoom beyond normal bounds ===
Note that zooming too far out can cause performance hits. Be careful.
<syntaxhighlight lang="lua">
/c game.player.zoom=0.1
</syntaxhighlight>

=== Mine faster ===
<syntaxhighlight lang="lua">
/c game.player.force.manual_mining_speed_modifier=1000
</syntaxhighlight>

=== Craft faster ===
<syntaxhighlight lang="lua">
/c game.player.force.manual_crafting_speed_modifier=1000
</syntaxhighlight>

=== Unlock and research all technologies ===
<syntaxhighlight lang="lua">
/c game.player.force.research_all_technologies()
</syntaxhighlight>

Undo this with the command in the next section.

Note: Specific technologies can be researched using the [[map editor]] by shift clicking the "start research" button on the technology GUI.

=== Unresearch all technologies ===
This does not reset manually applied bonuses
<syntaxhighlight lang="lua">
/c for _, tech in pairs(game.player.force.technologies) do
tech.researched=false
end
</syntaxhighlight>

Note: Specific technologies can be unresearched using the [[map editor]] by clicking the "un-research" button on the technology GUI.

=== Reset your force ===
This resets all data for your force, including kill and production statistics, technologies, bonuses and charting status.
<syntaxhighlight lang="lua">
/c game.player.force.reset()
</syntaxhighlight>

=== Always show rail block visualization ===
Permanently show the rail block visualization instead of only when holding a rail signal. Disable by replacing true with false.

<syntaxhighlight lang="lua">
/c game.player.game_view_settings.show_rail_block_visualisation = true
</syntaxhighlight>

=== Set all trains to Automatic mode ===
Set all trains to automatic mode - for example after building them with a blueprint.

<syntaxhighlight lang="lua">
/c for key,ent in pairs (game.player.surface.find_entities_filtered{name="locomotive"}) do
ent.train.manual_mode = false
end
</syntaxhighlight>

== Inventory manipulation scripts ==

=== Cheat mode ===
Allows for infinite free crafting. Disable by replacing true with false.
<syntaxhighlight lang="lua">
/c game.player.cheat_mode=true
</syntaxhighlight>

=== Refill resources (refill oil, iron etc.) ===
While holding the cursor over a resource tile in-game:
<syntaxhighlight lang="lua">
/c game.player.selected.amount=7500
</syntaxhighlight>

Alternatively you can refill all resources in the map with the following command. Change ore.amount to the desired value.
<syntaxhighlight lang="lua">
/c surface = game.player.surface
for _, ore in pairs(surface.find_entities_filtered({type="resource"})) do
ore.amount = 10000
end
</syntaxhighlight>

=== Add items to the player's inventory ===
Replace iron-plate with the [[data.raw|internal name]] of the item desired.
<syntaxhighlight lang="lua">
/c game.player.insert{name="iron-plate", count=100}
</syntaxhighlight>

For instance, here's a stack of the god-mode energy system interface:
<syntaxhighlight lang="lua">
/c game.player.insert{name="electric-energy-interface"}
</syntaxhighlight>

There are several god-mode items available:

* <code>infinity-chest</code>
* <code>infinity-pipe</code>
* <code>electric-energy-interface</code>
* <code>heat-interface</code>

Add a powerful armor with equipment and some tools for construction:
<syntaxhighlight lang="lua">
/c local player = game.player
player.insert{name="power-armor-mk2", count = 1}
local p_armor = player.get_inventory(5)[1].grid
p_armor.put({name = "fusion-reactor-equipment"})
p_armor.put({name = "fusion-reactor-equipment"})
p_armor.put({name = "fusion-reactor-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "exoskeleton-equipment"})
p_armor.put({name = "energy-shield-mk2-equipment"})
p_armor.put({name = "energy-shield-mk2-equipment"})
p_armor.put({name = "personal-roboport-mk2-equipment"})
p_armor.put({name = "night-vision-equipment"})
p_armor.put({name = "battery-mk2-equipment"})
p_armor.put({name = "battery-mk2-equipment"})
player.insert{name="construction-robot", count = 25}
</syntaxhighlight>

=== Increase player inventory slots ===
Gives 100 additional bonus inventory slots to your entire force. Used by the [[Toolbelt (research)]].
<syntaxhighlight lang="lua">
/c game.player.force.character_inventory_slots_bonus=100
</syntaxhighlight>

== World manipulation scripts ==

=== Reveal the map around the player ===

Reveals the map around the player, similar to a [[radar]].
<syntaxhighlight lang="lua">
/c local radius=150
game.player.force.chart(game.player.surface, {{game.player.position.x-radius, game.player.position.y-radius}, {game.player.position.x+radius, game.player.position.y+radius}})
</syntaxhighlight>
or from start position
<syntaxhighlight lang="lua">
/c local radius=150
game.player.force.chart(game.player.surface, {{x = -radius, y = -radius}, {x = radius, y = radius}})
</syntaxhighlight>
Change 150 to the desired radius, higher values take longer.

=== Hide revealed map ===

Hides all revealed chunks, inverted map revealing.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local force = game.player.force
for chunk in surface.get_chunks() do
force.unchart_chunk({x = chunk.x, y = chunk.y}, surface)
end
</syntaxhighlight>

=== Reveal all generated map ===

Revels all of the generated map to the player's team.
<syntaxhighlight lang="lua">
/c game.player.force.chart_all()
</syntaxhighlight>

=== Delete chunks ===
If much of the map is revealed, it increases the size of the save file. The following command cancels the generation of all chunks that are currently queued for generation and removes chunks outside a 32 chunks radius around 0,0. Note that this will remove player entities if there are any on these chunks.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface;
game.player.force.cancel_charting(surface);
local chunk_radius = 32;
for chunk in surface.get_chunks() do
if (chunk.x < -chunk_radius or chunk.x > chunk_radius or chunk.y < -chunk_radius or chunk.y > chunk_radius) then
surface.delete_chunk(chunk)
end
end
</syntaxhighlight>

=== Delete unrevealed chunks ===
This command deletes chunks that are not revealed by the player. Can be used after the command for [[#Hide revealed map|hiding revealed map]] to delete the chunks not covered by radar.

<syntaxhighlight lang="lua">/c local surface = game.player.surface
local force = game.player.force
for chunk in surface.get_chunks() do
if not force.is_chunk_charted(surface, chunk) then
surface.delete_chunk(chunk)
end
end</syntaxhighlight>

=== Turn off night ===
Enables eternal day.
<syntaxhighlight lang="lua">
/c game.player.surface.always_day=true
</syntaxhighlight>

=== Change game speed ===
0.5 is half speed, 1 is default, 2 is double speed, etc. Minimum is 0.01. This can be used for a lot of things like when you know you will have to wait for long periods of time for something to complete. Increasing will decrease performance, be careful.
<syntaxhighlight lang="lua">
/c game.speed=X
</syntaxhighlight>

=== Freeze time ===
Stops the advancement of the time. Unfreezes it if you by replace "true" with "false".
<syntaxhighlight lang="lua">
/c game.player.surface.freeze_daytime=true
</syntaxhighlight>

=== Remove all pollution ===
<syntaxhighlight lang="lua">
/c game.player.surface.clear_pollution()
</syntaxhighlight>

=== Completely turn off pollution ===

<syntaxhighlight lang="lua">
/c for _, surface in pairs(game.surfaces) do
surface.clear_pollution()
end
game.map_settings.pollution.enabled = false
</syntaxhighlight>

=== Add a lot of pollution ===
<syntaxhighlight lang="lua">
/c game.player.surface.pollute(game.player.position, 1000000)
</syntaxhighlight>

=== Where speakers are, who placed them ===
<syntaxhighlight lang="lua">
/c local speakers = game.player.surface.find_entities_filtered{force = game.player.force, type="programmable-speaker"}
for key, speaker in pairs(speakers) do
game.player.print(speaker.last_user.name .. " placed a speaker at " .. speaker.gps_tag)
end
</syntaxhighlight>

=== Disable friendly fire for your force ===
<syntaxhighlight lang="lua">
/c game.player.force.friendly_fire = false
</syntaxhighlight>

=== Add new resource patch ===
This creates a new 11×11 patch of resources, centered on the player character, where the ground is not water.
The patch it creates is perfectly square but it randomizes the amount similar to natural generation, with fewer ore at the edges and more ore in the center.
The default numbers result in a patch with 2500-3000 ore.

If you want a larger patch, change "local size = 5" to a larger number.
A larger patch will have exponentially more ore.
Entering a number above 30 is not recommended.

If you want a richer patch, change "local density = 10" to a larger number.
Entering a very large number shouldn't hurt anything but you probably don't need to go above 100.

To choose which resource is spawned, change "stone" near the bottom to "iron-ore", "copper-ore", "coal", or "uranium-ore".

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local ore=nil
local size=5
local density=10
for y=-size, size do
for x=-size, size do
a=(size+1-math.abs(x))*10
b=(size+1-math.abs(y))*10
if a<b then
ore=math.random(a*density-a*(density-8), a*density+a*(density-8))
end
if b<a then
ore=math.random(b*density-b*(density-8), b*density+b*(density-8))
end
if surface.get_tile(game.player.position.x+x, game.player.position.y+y).collides_with("ground-tile") then
surface.create_entity({name="stone", amount=ore, position={game.player.position.x+x, game.player.position.y+y}})
end
end
end
</syntaxhighlight>

For more flexibility, the [[map editor]] can also be used to create/alter/remove resource patches.

=== Remove resources around the player ===
Removes all resource patches from the ground in a 50 x 50 area around the player.

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local size=50
local pos=game.player.position

for _, e in pairs(surface.find_entities_filtered{area={{pos.x-size, pos.y-size},{pos.x+size, pos.y+size}}, type="resource"})
do e.destroy()
end
</syntaxhighlight>

=== Add new oil patch ===
This creates 9 crude oil patches in a 3×3 square.
<syntaxhighlight lang="lua">
/c for y=0,2 do
for x=0,2 do
game.player.surface.create_entity({name="crude-oil", amount=100000, position={game.player.position.x+x*7-7, game.player.position.y+y*7-7}})
end
end
</syntaxhighlight>

or randomly without any collision:
<syntaxhighlight lang="lua">
/c local position=nil
for i=1,9 do
position=game.player.surface.find_non_colliding_position("crude-oil", game.player.position, 0, i/2+1.5)
if position then
game.player.surface.create_entity({name="crude-oil", amount=100000, position=position})
end
end
</syntaxhighlight>

=== Regenerate resources ===
For solid resources like iron, destroys all resource entities and creates resource entities as in the original map generation. For fluid resources like oil, sets the yield of all existing resource entities to the original amount. Regenerates resources on the entire surface.
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
for _, e in pairs(surface.find_entities_filtered{type="resource"}) do
if e.prototype.infinite_resource then
e.amount = e.initial_amount
else
e.destroy()
end
end
local non_infinites = {}
for resource, prototype in pairs(prototypes.get_entity_filtered{{filter="type", type="resource"}}) do
if not prototype.infinite_resource then
table.insert(non_infinites, resource)
end
end
surface.regenerate_entity(non_infinites)
for _, e in pairs(surface.find_entities_filtered{type="mining-drill"}) do
e.update_connections()
end
</syntaxhighlight>

=== Count entities ===
Counts all entities whose name includes the string in local entity.
<syntaxhighlight lang="lua">
/c local entity="belt"
local surface=game.player.surface
local count=0
for key, ent in pairs(surface.find_entities_filtered({force=game.player.force})) do
if string.find(ent.name,entity) then
count=count+1
end
end
game.player.print(count)
</syntaxhighlight>

=== Turn off cliff generation ===
Sets size to "none". Only effective on chunks that are generated after using this command. Use [[#Remove all cliffs]] to delete existing cliffs.

<syntaxhighlight lang="lua">
/c local mgs = game.player.surface.map_gen_settings
mgs.cliff_settings.cliff_elevation_0 = 1024
game.player.surface.map_gen_settings = mgs</syntaxhighlight>

=== Remove all cliffs ===
Removes all cliffs existing cliffs from the world. Use [[#Turn off cliff generation]] to turn off cliff generation in new chunks.

<syntaxhighlight lang="lua">
/c for _, v in pairs(game.player.surface.find_entities_filtered{type="cliff"}) do
v.destroy()
end</syntaxhighlight>

=== Delete all decoratives ===
Delete the decoratives that can be found in the world.

<syntaxhighlight lang="lua">
/c game.player.surface.destroy_decoratives({})</syntaxhighlight>

=== Change map generation settings ===
This allows to change the map generation settings for new chunks; it does not alter already generated chunks. [[#Delete chunks|Deleted chunks]] are affected by the setting change because they are newly generated when they get explored again.

To change resource generation settings, replace "iron-ore" with the [[Data.raw#resource|resource]] that should be changed and replace "very-high" with the desired [https://lua-api.factorio.com/latest/Concepts.html#MapGenSize MapGenSize] in the following command. Replace "iron-ore" with "enemy-base" to change the enemy base generation settings.

<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local resource = "iron-ore"
local mgs = surface.map_gen_settings
mgs.autoplace_controls[resource].size = "very-high"
mgs.autoplace_controls[resource].frequency = "very-high"
mgs.autoplace_controls[resource].richness = "very-high"
surface.map_gen_settings = mgs</syntaxhighlight>

To change water generation settings, replace "very-high" with the desired [https://lua-api.factorio.com/latest/Concepts.html#MapGenSize MapGenSize] in the following command.

<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.water = "very-high" --[[ size]]
mgs.terrain_segmentation = "very-high" --[[ frequency]]
surface.map_gen_settings = mgs </syntaxhighlight>

=== Making a structure indestructible ===
This makes it impossible for an entity to be damaged or killed, e.g. by biters. Hover over the entity and then run:
<syntaxhighlight lang="lua">
/c game.player.selected.destructible = false
</syntaxhighlight>

=== Connect linked belts ===
If there exist at least two [https://lua-api.factorio.com/latest/prototypes/LinkedBeltPrototype.html linked belts], and one of them has the "Entity tag" <code>in</code>, and another linked belt has the "Entity tag" <code>out</code>, then the following command should link these two linked belts.

<syntaxhighlight lang="lua">
/c local i = game.get_entity_by_tag('in')
local o = game.get_entity_by_tag('out')
i.linked_belt_type = 'input'
o.linked_belt_type = 'output'
i.connect_linked_belts(o)
</syntaxhighlight>

== Enemy/evolution scripts ==

=== Set evolution factor ===
Ranges from 0 (new game) to 1.
<syntaxhighlight lang="lua">
/c game.forces["enemy"].set_evolution_factor(X, game.player.surface)
</syntaxhighlight>

=== Disable time-based evolution & increases pollution-based evolution ===
<syntaxhighlight lang="lua">
/c game.map_settings.enemy_evolution.time_factor=0
/c game.map_settings.enemy_evolution.pollution_factor=game.map_settings.enemy_evolution.pollution_factor*2
</syntaxhighlight>

The "2" at the end of the last command will double the default pollution factor. You can substitute another number to increase (or decrease) the pollution factor further.

=== Kill all biters on the "enemy" force ===
Note that this will kill only mobile units, spawners will not be killed.
<syntaxhighlight lang="lua">
/c game.forces["enemy"].kill_all_units()
</syntaxhighlight>

=== Kill all enemies ===
This will kill all biters, bases and worms. Anything that is an enemy will be completely destroyed. This only affects enemies in the generated world, so any unexplored parts of the map which still need to be generated will still have enemies. You can [[#Prevent biters being on newly generated chunks|prevent biters being on newly generated chunks]] if desired.
<syntaxhighlight lang="lua">
/c local surface=game.player.surface
for key, entity in pairs(surface.find_entities_filtered({force="enemy"})) do
entity.destroy()
end
</syntaxhighlight>

=== Kill all nearby enemies ===

This will kill all biters, bases and worms in a configurable radius. The default, 250 tiles, is about two zoomed-out screen widths on full HD. After destruction, it shows how many objects were destroyed.

<syntaxhighlight lang="lua">
/c local surface=game.player.surface
local pp = game.player.position
local cnt = 0
for key, entity in pairs(surface.find_entities_filtered({force="enemy", radius=250, position=pp })) do
cnt = cnt+1
entity.destroy()
end
game.player.print(cnt)
</syntaxhighlight>

=== Enable/Disable peaceful mode ===
Enabling peaceful mode prevents biter attacks until provoked. Substitute true for false to disable. Already existing biters are not affected by this command so attacks could continue for a while after activating peaceful mode.
<syntaxhighlight lang="lua">
/c game.player.surface.peaceful_mode = true
</syntaxhighlight>

=== Enable/Disable biter expansion ===
Biter expansion allows biters to create new nests, it is enabled by default. Substitute true for false to disable.
<syntaxhighlight lang="lua">
/c game.map_settings.enemy_expansion.enabled = true
</syntaxhighlight>

=== Prevent biters being on newly generated chunks ===
On newly generated chunks no biters will be present, however all current biters will remain unaffected. Equivalent of setting the Enemy Base Size to None under the Terrain settings during map generation but achieved mid game by [[#Change map generation settings|changing map generation settings]].
<syntaxhighlight lang="lua">
/c local surface = game.player.surface
local mgs = surface.map_gen_settings
mgs.autoplace_controls["enemy-base"].size = "none"
surface.map_gen_settings = mgs
</syntaxhighlight>

Instead of the command, it is also possible to use a GUI in the [[map editor]] to changing map generation settings mid game. Access the map editor with <code>/editor</code>, go to the "Surfaces" tab and click "Edit map gen settings".

== Player character scripts ==
Commands concerning the player directly.
=== Get player position ===
Prints coordinates of your current position.
<syntaxhighlight lang="lua">
/c game.player.print(game.player.position)
</syntaxhighlight>

=== Teleport player ===
Moves the player to the specified location. You should be able to teleport to a specific player if you obtain their coordinates via them executing the previous command and giving them to you.
<syntaxhighlight lang="lua">
/c game.player.teleport({X, Y})
</syntaxhighlight>

To teleport to the world's origin, use 0,0.

To teleport to a different planet / surface, use:
<syntaxhighlight lang="lua">
/c game.player.teleport({X, Y}, 'surface_name')
</syntaxhighlight>

=== Enable god mode ===
God mode removes your player character allowing you to fly over obstacles and take no damage.

Disassociate your controls from the character and destroy it:
<syntaxhighlight lang="lua">
/c game.player.character.destroy()
</syntaxhighlight>

To undo, spawn a player character. This will spawn a new character at the spawn point of the world, and connect your controls to it.
<syntaxhighlight lang="lua">
/c game.player.create_character()
</syntaxhighlight>

=== Enable long reach ===
Enables long reach, which allows the player to build and interact with entities at a greater distance. The default reach is 10.
<syntaxhighlight lang="lua">
/c local reach = 10000
game.player.force.character_build_distance_bonus = reach
game.player.force.character_reach_distance_bonus = reach
</syntaxhighlight>

=== Find player corpses ===
Pings player corpses on the map.
<syntaxhighlight lang="lua">
/c local found_corpses = game.player.surface.find_entities_filtered{type="character-corpse"}
for _,corpse in pairs(found_corpses) do
local player = game.get_player(corpse.character_corpse_player_index)
local name = player and player.name or "????"
game.player.print(name .. " --> " .. corpse.gps_tag)
end
</syntaxhighlight>

=== Run faster ===
<syntaxhighlight lang="lua">
/c game.player.character_running_speed_modifier=3
</syntaxhighlight>

== Research scripts ==
=== Enable faster research ===
<syntaxhighlight lang="lua">
/c game.player.force.laboratory_speed_modifier=1
</syntaxhighlight>
-0.5 is half speed, 0 is normal speed, 1 is double speed, 2 is triple etc.

=== Research specific technologies ===
The internal technology names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.technologies['electric-energy-distribution-1'].researched=true
/c game.player.force.technologies['steel-processing'].researched=true
</syntaxhighlight>

To research a high level of an infinite technology, set its level:
<syntaxhighlight lang="lua">
/c game.player.force.technologies['worker-robots-speed-6'].level = 100
/c game.player.force.technologies['mining-productivity-4'].level = 100
</syntaxhighlight>

=== Unresearch specific technologies ===
The internal technology names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.technologies['electric-energy-distribution-1'].researched=false
/c game.player.force.technologies['steel-processing'].researched=false
</syntaxhighlight>

=== Enabling specific recipes ===
The internal recipe/item names can be found in the infoboxes on their respective pages.
<syntaxhighlight lang="lua">
/c game.player.force.recipes["electric-energy-interface"].enabled=true
/c game.player.force.recipes["rocket-silo"].enabled=true
/c game.player.force.recipes.loader.enabled=true
/c game.player.force.recipes["fast-loader"].enabled = true
/c game.player.force.recipes["express-loader"].enabled = true
</syntaxhighlight>

=== Enable all recipes ===
<syntaxhighlight lang="lua">
/c for name, recipe in pairs(game.player.force.recipes) do recipe.enabled = true end
</syntaxhighlight>

=== Resetting technology effects to default ===
This will reset the enabled/unlocked state of all recipes to what they would be purely based on the currently researched technologies, as well as resetting other technology effects like mining speed, etc. Any manual modifications to these effects and recipe unlocks will be undone.
<syntaxhighlight lang="lua">
/c game.player.force.reset_technology_effects()
</syntaxhighlight>
Note: Can be used as a quick workaround when recipes are unavailable after adding or changing mods even though the technology unlocking them has already been researched.

== Modding tools ==
A list of the internal names of most things in the vanilla game can also be found on [[data.raw]].

=== Access a mod's data ===
If the first word of the command is __mod-name__ it will run in the context of the mod with the same name. For instance, this command prints the data from the Even Distribution mod:
<syntaxhighlight lang="lua">
/c __even-distribution__ game.player.print(serpent.dump(global))
</syntaxhighlight>

=== Print to console the tile under the player ===
<syntaxhighlight lang="lua">
/c game.player.print(game.player.surface.get_tile(game.player.position).name)
</syntaxhighlight>

=== Write all researched technologies to file ===
<syntaxhighlight lang="lua">
/c local list = {}
for _, tech in pairs(game.player.force.technologies) do
if tech.researched then
list[#list+1] = tech.name
end
end
game.write_file("techs.lua", serpent.block(list) .. "\n", true)
</syntaxhighlight>

=== Write all enabled recipes to file ===
<syntaxhighlight lang="lua">
/c local list = {}
for _, recipe in pairs(game.player.force.recipes) do
if recipe.enabled then
list[#list+1] = recipe.name
end
end
game.write_file("recipes.lua", serpent.block(list) .. "\n", true)
</syntaxhighlight>

=== Write mod list to file ===
Write all currently active mods and their version to the file script-output/mods.txt in the [[user data directory]].

<syntaxhighlight lang="lua">
/c game.write_file("mods.txt", serpent.block(game.active_mods))
</syntaxhighlight>

== History ==
{{History|1.1.92|
* Added a notification when a technology is researched.
* Added /enable-research-queue console command to enable the research queue without disabling achievements.}}

== See also ==
* [[Command line parameters]]
* https://lua-api.factorio.com/latest/index-runtime.html - Factorio API reference for latest version

{{C|Modding}}

Tutorial:Modding tutorial/Gangsir

2024-11-03T22:51:20Z

PennyJim: Fix typo (controller the character :facepalm:)

{{Languages}}
This is a modding tutorial for Factorio version 2.0. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

== Overview ==
Before we start the tutorial, a few things to note:

<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>

This tutorial was updated to version 2.0, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

== Terminology used in modding ==

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

; Mod : A script or series of scripts that allow modifications to the game through the API.
; Entity : An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.
; Character : The actual entity that the player manipulates the world through.
; Player : All the data that defines a player, such as username, online time or the current zoom level.
; Prototype : A prototype describes an instance of an entity, item or recipe etc, a bit like a template. It defines stats, like what an entity actually is, an item's stack size, a recipe's ingredients etc. A prototype is used to create an instance of an entity/item/etc, and many functionally identical entities/items/etc will use the same prototype.
; Surface : A surface is a bit like a dimension. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By default, there is only one surface in Factorio, referred to internally as "nauvis", or <code style="background-color:#DDA0DD; color:black">game.surfaces[1]</code>, but mods may create additional surfaces through the API.
; Event : An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, etc. More on this in the control scripting section.
; Item : Items are what is moved around in inventories, by inserters and on belts, etc. Each item in-game is an instance of the respective item prototype.

More terminology may be declared and defined later in this tutorial.

== Before beginning to mod ==

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the [[Factorio:About|about page]], but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua (version 5.2.1). This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation of mods on at their [https://lua-api.factorio.com/latest/ API doc site]. Get used to using this site, as you will be frequently visiting it while you develop mods. The scripting API site contains information on [https://lua-api.factorio.com/latest/classes.html Factorio's classes] and information on [https://lua-api.factorio.com/latest/events.html events] that you can hook into. The [https://lua-api.factorio.com/latest/index-prototype.html prototype documentation] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, there are also many resources to be found created by the community, such as this tutorial.

=== Setup ===

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is recommended. Emacs, Vim, Sublime Text, VSCode, and Notepad++ are all viable candidates.

== How Factorio loads mods ==

=== Load order ===
Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies, entities, items and more. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

All prototypes are documented on the modding API documentation website: [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation].

=== Migrations ===

[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid changing prototype names and technology unlocks. Prototypes names cannot be dynamically changed and technology unlocks of already researched technologies do not apply automatically, making migrations necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Runtime stage ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. During the play session, access to all tables provided by the game can be done inside of event handlers. (More on those below.) Because the control.lua is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html data life cycle] page on the API site provides the best overview.'''

The control stage documented is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

The game expects mod to be laid out [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor

Then, inside fire-armor, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor
**** data.lua
**** info.json

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "2.0",
"dependencies": ["base >= 2.0"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a of the format "number.number.number".
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 2.0 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A short description of your mod, which appears in game. The mod portal is better for a long description.
|}

And that's all for info.json!

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. One way requires to create a complete prototype definition based on [https://lua-api.factorio.com/latest/index-prototype.html the documentation]. Another way uses a Lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it both ways.

In the data.lua file, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"]) -- copy the table that defines the heavy armor item into the fireArmor variable

fireArmor.name = "fire-armor"
fireArmor.icons = {
{
icon = fireArmor.icon,
icon_size = fireArmor.icon_size,
tint = {r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
}
}

-- create the recipe prototype from scratch
local recipe = {
type = "recipe",
name = "fire-armor",
enabled = true,
energy_required = 8, -- time to craft in seconds (at crafting speed 1)
ingredients = {
{type = "item", name = "copper-plate", amount = 200},
{type = "item", name = "steel-plate", amount = 50}
},
results = {{type = "item", name = "fire-armor", amount = 1}}
}

data:extend{fireArmor, recipe}

</pre>

What we've just done here is we've copied the definition of the heavy armor item, then changed its properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all prototype types, and within those types, individual prototypes identified by name: <code>local prototype = data.raw["prototype-type"]["internal-name"]</code>. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. We can find [[heavy armor]]'s prototype type and internal name in the infobox of its page on this wiki and just copy it from there. 
Alternatively, we can find the items prototype type and internal name by opening the game, inserting the item into our inventory and then pressing {{Keybinding|shift|ctrl|F}} while hovering over the item. This will open the prototype explorer GUI, which has rows showing the name and type of the item.

As another example, the [[player|character]]'s prototype would be, according to the infobox on the page:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["character"]["character"]
</pre>

Because the character is ''the'' character, his type matches his name. You could define a new character with a mod. You can see all the available prototype fields of the character in the documentation: [https://lua-api.factorio.com/latest/prototypes/CharacterPrototype.html CharacterPrototype].

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua if you want to run after all other mods, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["container"]["iron-chest"].max_health = 1000
</pre>

The reason why this code is in data-final-fixes.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to create fire on the ground as we walk with the armor on. The event we're going to use is called [https://lua-api.factorio.com/latest/events.html#on_player_changed_position on_player_changed_position], since we want the fire to be created when the player moves.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event(defines.events.on_player_changed_position,
function(event)
local player = game.get_player(event.player_index) -- get the player that moved
-- if they're currently controlling the character
if player.controller_type == defines.controllers.character then
-- and wearing our armor
if player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
-- create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player character is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [https://lua-api.factorio.com/latest/defines.html#defines.inventory here].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create a locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>any_name_can_be_here.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside the .cfg file, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it.

If you want to share a mod with other users, it needs to be a zip file. For that, simply zip the <code>fire-armor</code> folder and then rename the archive to <code>fire-armor_0.1.0</code> so that it follows the expected mod zip name pattern of <code>mod-name_version</code>. Keep in mind to not submit this tutorial mod to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Extended learning ==
One of the best ways to learn how to mod beyond this is to look at other mods. The [[Tutorial:Inspecting a live mod]] is a good starting point for touring a particularly well-commented mod. As all mods can be opened and inspected, looking at the mods of experienced modders can help significantly when making your own mod.

Something you'll see a lot in other mods or the base game are <code>require</code> statements. These load other files, so you can split up long code files and organize your mod however you like.

For example, if you wanted to put some of your data stage code into a file called "foo.lua" in a folder called "bar", your mod folder would look like this:

* fire-armor
** bar
*** foo.lua
** data.lua
** control.lua
** info.json

And you would need to add this to data.lua:
<pre style="background-color:#DDA0DD!important; color:black">
require("bar.foo")
</pre>

=== Keeping your mod working ===
As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The Lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
</pre>

You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mod "fire-armor":". So, we know that it's our mod that messed up. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was caused by line 39 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 39 of data.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
name = "fire-armor,
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an " after armor before the comma. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
__fire-armor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [https://lua-api.factorio.com/latest/LuaPlayer.html A player] is a table of several values. Trying to print it simply print "LuaPlayer" instead of providing useful data.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
Unknown entity name: fire-flam
stack traceback:
__fire-armor__/control.lua:7: in function <__fire-armor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 7 of control.lua, inside of an on_player_changed_position event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:190: Map tick at moment of crash: 432029
696.148 Error Util.cpp:97: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
Please also include the save file(s), any mods you may be using, and any steps you know of to reproduce the crash.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

=== Comparison by reference ===

Be cautious of comparing tables by reference. In multiplayer syncing, tables deserialized from the server state will be new objects, not equal by reference to any table initialized by client code.

<pre style="background-color:#DDA0DD!important; color:black">
if a == b then
</pre>
<pre style="background-color:#DDA0DD!important; color:black">
if a ~= b then
</pre>
If <code>a</code> and <code>b</code> are tables in the above conditionals, there will for example be different results between server and client if <code>a</code> is created locally and <code>b</code> is downloaded from the server.

Note that LuaObjects provided by the game have their equality operator overwritten to prevent this behaviour, so code such as <code>LuaEntityA ~= LuaEntityB</code> will not desync.
However, this does not apply when LuaObjects are used as keys in tables:
<pre style="background-color:#DDA0DD!important; color:black">
if table[LuaObject] then
</pre>
This will desync in the same way as described for the plain tables <code>a</code> and <code>b</code> above. For entities it is recommended to use [https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.unit_number LuaEntity.unit_number] as the table key instead of the whole entity.

== See also ==
* [[Modding]]
* [[Tutorial:Modding tutorial|Modding tutorial overview]]

[[Category:Modding]]

Tutorial:Modding tutorial/Gangsir

2024-11-03T22:49:37Z

PennyJim: Tweak formatting

{{Languages}}
This is a modding tutorial for Factorio version 2.0. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

== Overview ==
Before we start the tutorial, a few things to note:

<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>

This tutorial was updated to version 2.0, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

== Terminology used in modding ==

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

; Mod : A script or series of scripts that allow modifications to the game through the API.
; Entity : An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.
; Character : The actual entity that the player manipulates the world through.
; Player : All the data that defines a player, such as username, online time or the current zoom level.
; Prototype : A prototype describes an instance of an entity, item or recipe etc, a bit like a template. It defines stats, like what an entity actually is, an item's stack size, a recipe's ingredients etc. A prototype is used to create an instance of an entity/item/etc, and many functionally identical entities/items/etc will use the same prototype.
; Surface : A surface is a bit like a dimension. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By default, there is only one surface in Factorio, referred to internally as "nauvis", or <code style="background-color:#DDA0DD; color:black">game.surfaces[1]</code>, but mods may create additional surfaces through the API.
; Event : An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, etc. More on this in the control scripting section.
; Item : Items are what is moved around in inventories, by inserters and on belts, etc. Each item in-game is an instance of the respective item prototype.

More terminology may be declared and defined later in this tutorial.

== Before beginning to mod ==

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the [[Factorio:About|about page]], but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua (version 5.2.1). This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation of mods on at their [https://lua-api.factorio.com/latest/ API doc site]. Get used to using this site, as you will be frequently visiting it while you develop mods. The scripting API site contains information on [https://lua-api.factorio.com/latest/classes.html Factorio's classes] and information on [https://lua-api.factorio.com/latest/events.html events] that you can hook into. The [https://lua-api.factorio.com/latest/index-prototype.html prototype documentation] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, there are also many resources to be found created by the community, such as this tutorial.

=== Setup ===

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is recommended. Emacs, Vim, Sublime Text, VSCode, and Notepad++ are all viable candidates.

== How Factorio loads mods ==

=== Load order ===
Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies, entities, items and more. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

All prototypes are documented on the modding API documentation website: [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation].

=== Migrations ===

[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid changing prototype names and technology unlocks. Prototypes names cannot be dynamically changed and technology unlocks of already researched technologies do not apply automatically, making migrations necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Runtime stage ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. During the play session, access to all tables provided by the game can be done inside of event handlers. (More on those below.) Because the control.lua is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html data life cycle] page on the API site provides the best overview.'''

The control stage documented is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

The game expects mod to be laid out [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor

Then, inside fire-armor, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor
**** data.lua
**** info.json

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "2.0",
"dependencies": ["base >= 2.0"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a of the format "number.number.number".
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 2.0 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A short description of your mod, which appears in game. The mod portal is better for a long description.
|}

And that's all for info.json!

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. One way requires to create a complete prototype definition based on [https://lua-api.factorio.com/latest/index-prototype.html the documentation]. Another way uses a Lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it both ways.

In the data.lua file, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"]) -- copy the table that defines the heavy armor item into the fireArmor variable

fireArmor.name = "fire-armor"
fireArmor.icons = {
{
icon = fireArmor.icon,
icon_size = fireArmor.icon_size,
tint = {r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
}
}

-- create the recipe prototype from scratch
local recipe = {
type = "recipe",
name = "fire-armor",
enabled = true,
energy_required = 8, -- time to craft in seconds (at crafting speed 1)
ingredients = {
{type = "item", name = "copper-plate", amount = 200},
{type = "item", name = "steel-plate", amount = 50}
},
results = {{type = "item", name = "fire-armor", amount = 1}}
}

data:extend{fireArmor, recipe}

</pre>

What we've just done here is we've copied the definition of the heavy armor item, then changed its properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all prototype types, and within those types, individual prototypes identified by name: <code>local prototype = data.raw["prototype-type"]["internal-name"]</code>. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. We can find [[heavy armor]]'s prototype type and internal name in the infobox of its page on this wiki and just copy it from there. 
Alternatively, we can find the items prototype type and internal name by opening the game, inserting the item into our inventory and then pressing {{Keybinding|shift|ctrl|F}} while hovering over the item. This will open the prototype explorer GUI, which has rows showing the name and type of the item.

As another example, the [[player|character]]'s prototype would be, according to the infobox on the page:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["character"]["character"]
</pre>

Because the character is ''the'' character, his type matches his name. You could define a new character with a mod. You can see all the available prototype fields of the character in the documentation: [https://lua-api.factorio.com/latest/prototypes/CharacterPrototype.html CharacterPrototype].

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua if you want to run after all other mods, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["container"]["iron-chest"].max_health = 1000
</pre>

The reason why this code is in data-final-fixes.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to create fire on the ground as we walk with the armor on. The event we're going to use is called [https://lua-api.factorio.com/latest/events.html#on_player_changed_position on_player_changed_position], since we want the fire to be created when the player moves.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event(defines.events.on_player_changed_position,
function(event)
local player = game.get_player(event.player_index) -- get the player that moved
-- if they're currently controller the character
if player.controller_type == defines.controllers.character then
-- and wearing our armor
if player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
-- create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player character is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [https://lua-api.factorio.com/latest/defines.html#defines.inventory here].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create a locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>any_name_can_be_here.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside the .cfg file, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it.

If you want to share a mod with other users, it needs to be a zip file. For that, simply zip the <code>fire-armor</code> folder and then rename the archive to <code>fire-armor_0.1.0</code> so that it follows the expected mod zip name pattern of <code>mod-name_version</code>. Keep in mind to not submit this tutorial mod to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Extended learning ==
One of the best ways to learn how to mod beyond this is to look at other mods. The [[Tutorial:Inspecting a live mod]] is a good starting point for touring a particularly well-commented mod. As all mods can be opened and inspected, looking at the mods of experienced modders can help significantly when making your own mod.

Something you'll see a lot in other mods or the base game are <code>require</code> statements. These load other files, so you can split up long code files and organize your mod however you like.

For example, if you wanted to put some of your data stage code into a file called "foo.lua" in a folder called "bar", your mod folder would look like this:

* fire-armor
** bar
*** foo.lua
** data.lua
** control.lua
** info.json

And you would need to add this to data.lua:
<pre style="background-color:#DDA0DD!important; color:black">
require("bar.foo")
</pre>

=== Keeping your mod working ===
As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The Lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
</pre>

You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mod "fire-armor":". So, we know that it's our mod that messed up. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was caused by line 39 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 39 of data.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
name = "fire-armor,
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an " after armor before the comma. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
__fire-armor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [https://lua-api.factorio.com/latest/LuaPlayer.html A player] is a table of several values. Trying to print it simply print "LuaPlayer" instead of providing useful data.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
Unknown entity name: fire-flam
stack traceback:
__fire-armor__/control.lua:7: in function <__fire-armor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 7 of control.lua, inside of an on_player_changed_position event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:190: Map tick at moment of crash: 432029
696.148 Error Util.cpp:97: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
Please also include the save file(s), any mods you may be using, and any steps you know of to reproduce the crash.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

=== Comparison by reference ===

Be cautious of comparing tables by reference. In multiplayer syncing, tables deserialized from the server state will be new objects, not equal by reference to any table initialized by client code.

<pre style="background-color:#DDA0DD!important; color:black">
if a == b then
</pre>
<pre style="background-color:#DDA0DD!important; color:black">
if a ~= b then
</pre>
If <code>a</code> and <code>b</code> are tables in the above conditionals, there will for example be different results between server and client if <code>a</code> is created locally and <code>b</code> is downloaded from the server.

Note that LuaObjects provided by the game have their equality operator overwritten to prevent this behaviour, so code such as <code>LuaEntityA ~= LuaEntityB</code> will not desync.
However, this does not apply when LuaObjects are used as keys in tables:
<pre style="background-color:#DDA0DD!important; color:black">
if table[LuaObject] then
</pre>
This will desync in the same way as described for the plain tables <code>a</code> and <code>b</code> above. For entities it is recommended to use [https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.unit_number LuaEntity.unit_number] as the table key instead of the whole entity.

== See also ==
* [[Modding]]
* [[Tutorial:Modding tutorial|Modding tutorial overview]]

[[Category:Modding]]

Tutorial:Modding tutorial/Gangsir

2024-11-03T22:36:32Z

PennyJim: Update references of 1.1 to 2.0, and fix a crash with map view

{{Languages}}
This is a modding tutorial for Factorio version 2.0. In this tutorial, the author will explain how Factorio works behind the scenes, how to modify Factorio, where to find documentation, and explain concepts.

== Overview ==
Before we start the tutorial, a few things to note:

<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>

<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>

This tutorial was updated to version 2.0, so any ''viewers in the future should take note that some minor changes may have been made'', and should look at the changelogs up to the current version.

== Terminology used in modding ==

Before we start the tutorial, a few terms and definitions should be laid out, to ensure the reader understands.

; Mod : A script or series of scripts that allow modifications to the game through the API.
; Entity : An entity in Factorio is anything in the game that is not a concept, event, or tile. Examples of entities include the character, an assembling machine, a biter, etc. This can be 'machines' or free-moving objects like the character.
; Character : The actual entity that the player manipulates the world through.
; Player : All the data that defines a player, such as username, online time or the current zoom level.
; Prototype : A prototype describes an instance of an entity, item or recipe etc, a bit like a template. It defines stats, like what an entity actually is, an item's stack size, a recipe's ingredients etc. A prototype is used to create an instance of an entity/item/etc, and many functionally identical entities/items/etc will use the same prototype.
; Surface : A surface is a bit like a dimension. It is composed of terrain, such as grass, sand, and water, and all the entities on the surface. By default, there is only one surface in Factorio, referred to internally as "nauvis", or <code style="background-color:#DDA0DD; color:black">game.surfaces[1]</code>, but mods may create additional surfaces through the API.
; Event : An event is a recurring...event, that is triggered internally by the game. There are several events that mods may connect functions to, such as <code style="background-color:#DDA0DD; color:black">on_entity_died</code>, etc. More on this in the control scripting section.
; Item : Items are what is moved around in inventories, by inserters and on belts, etc. Each item in-game is an instance of the respective item prototype.

More terminology may be declared and defined later in this tutorial.

== Before beginning to mod ==

Before we can start modding Factorio, we must understand what Factorio is. You may be tempted to answer in lieu of the [[Factorio:About|about page]], but that is what a player would say. Since we are trying to become a modder, we need a more detailed explanation. Factorio is a game that is coded in the language C++, with an API provided by Wube (the developers of Factorio) to mod Factorio in the programming language Lua (version 5.2.1). This API allows adding scripts to the Factorio init process, to modify it without the source code of the base game being exposed, or modifying memory. This may be different than other games that offer modding, but this is a more professional and proper way of supporting modding.

To aid in the use of this API, the devs have kindly provided fairly comprehensive documentation of mods on at their [https://lua-api.factorio.com/latest/ API doc site]. Get used to using this site, as you will be frequently visiting it while you develop mods. The scripting API site contains information on [https://lua-api.factorio.com/latest/classes.html Factorio's classes] and information on [https://lua-api.factorio.com/latest/events.html events] that you can hook into. The [https://lua-api.factorio.com/latest/index-prototype.html prototype documentation] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, there are also many resources to be found created by the community, such as this tutorial.

=== Setup ===

The best way to develop a mod is to develop it in a place where it can be easily tested. When the tutorial gets to making the mod, this will be explained further. Additionally, using an editor that allows ease of typing and Lua language support is recommended. Emacs, Vim, Sublime Text, VSCode, and Notepad++ are all viable candidates.

== How Factorio loads mods ==

=== Load order ===
Within stages, mods are loaded by dependency, then by alphabetical order. This is ''very important'' to understand, as it can cause you problems if you neglect it and try to add inter-mod support to your mod.

Factorio has three kinds of dependencies. There are required dependencies, and optional dependencies. The third kind, restrictive dependencies, does not affect mod order and instead prevents the game from loading if the other mod is found. Required dependencies are loaded first, always. The game will fail to initialize if one of these is not present. Optional dependencies are loaded first if present, but do not have to be present. This is useful for enabling bonus features if mods are used together. Required dependencies should be used for mod libraries, and similar infrastructure.

=== The settings stage ===
The very first mod stage that is loaded when Factorio initializes is the settings stage. This stage is used to define all mod settings that are later shown in the in-game mod settings GUI, and has no other functions or possibilities. When running through this stage, the game looks through all mods for a file called <code>settings.lua</code>. After settings.lua has been executed for all mods, each mod's <code>settings-updates.lua</code> is executed, and finally each mod's <code>settings-final-fixes.lua</code> is called. These 3 different phases of the settings stage allow to change settings of other mods without needing to rely on dependencies to load last. All other files to be loaded will need to be required. All the files run here should contain nothing but setting definitions and code to produce setting definitions.

The settings stage does not have access to prototype or runtime data because it is loaded before those stages. The settings are expected to have a certain format, and all additional code will be discarded once the stage is over.

Mod settings are not covered in this tutorial, see [[Tutorial:Mod settings]] for further info on them.

=== The data stage ===

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies, entities, items and more. Things like manipulating files, affecting the world, etc, are blocked/unavailable. In fact, any functions or changes made will be discarded, as the lua session is terminated. You also cannot mess with the data table, it will error or be ignored. When using <code>data:extend({})</code>, it expects a specific format, more on this later.

When running through this stage, the game looks through all mods for a file called <code>data.lua</code>. After data.lua has been executed for all mods, each mod's <code>data-updates.lua</code> is executed, and finally each mod's <code>data-final-fixes.lua</code> is called. These 3 different phases of the data stage allow to change data of other mods without needing to rely on dependencies to load last. For example, the base mod creates barrelling recipes for all (then present) fluids in data-updates.lua. This means that if you add a fluid in data.lua, the base mod's data-updates.lua will add barreling recipes for it, regardless of whether your mod depends on base. Of course this also means that if you add a fluid in data-final-fixes.lua, it is created after the barrelling code runs in data-updates.lua, so no barrelling recipe gets created, even when desired. Because of this and similar mod interactions, it is recommended to create prototypes as early as possible. So, don't use data-final-fixes.lua to exclude a fluid from barreling, instead create it in data.lua and utilize "auto_barrel = false" on the fluid.

All other files to be loaded will need to be required. All the files run here should contain nothing but prototype definitions and code to produce prototype definitions. More on requiring files later.

All prototypes are documented on the modding API documentation website: [https://lua-api.factorio.com/latest/index-prototype.html Prototype documentation].

=== Migrations ===

[https://lua-api.factorio.com/latest/auxiliary/migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototype names change within a mod, migrations must be setup to replace all the old instances of the prototyped entity in the world. This must be done for all updated entities, or the old entities will be removed from the world, which is an unprofessional fallback that makes users dislike you. While this tutorial will not discuss migrations, there are many resources on migrations to be found around the community, and the API site.

To avoid having to write migrations, avoid changing prototype names and technology unlocks. Prototypes names cannot be dynamically changed and technology unlocks of already researched technologies do not apply automatically, making migrations necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of prototype names that you can base the mod around. Of course, migrations are unnecessary if the user simply starts a new world with each mod update, but do not expect the community to do this.

=== Runtime stage ===

Within most mods is a file called <code>control.lua</code>. This file contains scripting that makes the mod do things during the game, rather than just adding entities to the game. During this stage, each mod's control.lua is run, in it's own lua instance (this means no inter-communication without special setup) which it will own for the rest of the play session. During the play session, access to all tables provided by the game can be done inside of event handlers. (More on those below.) Because the control.lua is run every time a save file is created or loaded you don't need to restart the game to see changes made to the control.lua file. Simply restarting or reloading a save will re-run this stage. '''There are a few other caveats to this stage, reading the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html data life cycle] page on the API site provides the best overview.'''

The control stage documented is documented on [https://lua-api.factorio.com/latest/index-runtime.html lua-api.factorio.com].

== The major components to any Factorio mod ==

Within the average mod, there are several components that make the mod function.

Mods that define new entities will need to declare these entities in <code>data.lua</code>, <code>data-updates.lua</code>, <code>data-final-fixes.lua</code>.

Mods with in-game effects will also need a <code>control.lua</code> file, to add scripting.

Mods with configurable user settings will use <code>settings.lua</code> to describe those settings.

Mods that define any game element with a readable name may also provide a <code>locale</code> directory and subdirectories with names/descriptions in one or more languages.

The mod that we'll make in this tutorial will include both data.lua prototypes and control.lua scripting, to give you a feel for both.

== The tutorial mod ==

And now for the moment you've been waiting for. Let's start making your first mod. You'll need:

* A recent install of Factorio
* A text editor, such as Emacs, Vim, Sublime Text, VSCode, or Notepad++.
* An understanding of the tutorial above
* An understanding of Lua as a programming language. Enough to know the syntax and how it works. If you have prior programming experience, it should not be difficult to pick up.

Once you have all of these things, we can begin.

For this mod, we're going to make a set of armor that leaves behind damaging fire behind you as you walk. It will be fully resistant to fire, but weaker towards physical damage than heavy armor, making it an armor for hit and run attacks.

=== Creation of the directory structure ===

The game expects mod to be laid out [[Tutorial:Mod structure|in a certain way]]. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>fire-armor</code>. You don't need to zip anything for now, that will come later when you're done working on the mod. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor

Then, inside fire-armor, create two files, <code>info.json</code> and <code>data.lua</code>. The directory should now look like:

* (user data directory, sometimes called .factorio)
** mods
*** fire-armor
**** data.lua
**** info.json

=== The info.json file ===

Then, inside [[Tutorial:Mod_structure#info.json|info.json]], copy and paste the following into it:

<pre style="background-color:#AAFFAA!important; color:black">
{
"name": "fire-armor",
"version": "0.1.0",
"title": "Fire Armor",
"author": "You",
"factorio_version": "2.0",
"dependencies": ["base >= 2.0"],
"description": "This mod adds in fire armor that leaves behind damaging fire as you walk around."
}
</pre>

To explain each field:

{| class="wikitable"
! Item
! Explanation
|-
| name
| This is the internal name of your mod, it is used to identify your mod in code.
|-
| version
| This is the version of your mod. This can be anything you want, provided it's a of the format "number.number.number".
|-
| title
| The pretty title of your mod, this will be displayed on the mods screen and when you submit it to the mod portal.
|-
| author
| Your name! You can change this in the example above.
|-
| factorio_version
| This tells the game what version the mod is for, this must match the version you're developing the mod for, 2.0 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A short description of your mod, which appears in game. The mod portal is better for a long description.
|}

And that's all for info.json!

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. One way requires to create a complete prototype definition based on [https://lua-api.factorio.com/latest/index-prototype.html the documentation]. Another way uses a Lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it both ways.

In the data.lua file, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--data.lua

local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"]) -- copy the table that defines the heavy armor item into the fireArmor variable

fireArmor.name = "fire-armor"
fireArmor.icons = {
{
icon = fireArmor.icon,
icon_size = fireArmor.icon_size,
tint = {r=1,g=0,b=0,a=0.3}
},
}

fireArmor.resistances = {
{
type = "physical",
decrease = 6,
percent = 10
},
{
type = "explosion",
decrease = 10,
percent = 30
},
{
type = "acid",
decrease = 5,
percent = 30
},
{
type = "fire",
decrease = 0,
percent = 100
}
}

-- create the recipe prototype from scratch
local recipe = {
type = "recipe",
name = "fire-armor",
enabled = true,
energy_required = 8, -- time to craft in seconds (at crafting speed 1)
ingredients = {
{type = "item", name = "copper-plate", amount = 200},
{type = "item", name = "steel-plate", amount = 50}
},
results = {{type = "item", name = "fire-armor", amount = 1}}
}

data:extend{fireArmor, recipe}

</pre>

What we've just done here is we've copied the definition of the heavy armor item, then changed its properties, and injected it into the Factorio init with data:extend. The first line of code is probably the most interesting. <code>table.deepcopy</code> copies a table fully into another table. We do this from data.raw. The <code>data</code> part is a table, which will be used by the game to setup the Factorio universe. In fact, it contains the function <code>extend(self, prototypes)</code> and a table called <code>raw</code>. The former is a customary way to add new stuff to the latter. It is actually data.raw that holds the prototypes for the game. (You can view the implementation in the file [https://github.com/wube/factorio-data/blob/master/core/lualib/dataloader.lua /factorio/data/core/lualib/dataloader.lua]). It is important to note that data.raw only exists during the data loading stage of the game. During the control stage, when the game is running and being played, you cannot read this data; instead you read processed values through the API from the various types like LuaEntityPrototype.

In addition to defining the item prototype, we also define a recipe for it. This is necessary if you want to be able to craft the thing. We also set it to enabled so it doesn't need a technology to unlock.

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all prototype types, and within those types, individual prototypes identified by name: <code>local prototype = data.raw["prototype-type"]["internal-name"]</code>. You saw earlier how we deepcopied from the definition of heavy armor, and modified some fields. In fact, let's go over each part of the deepcopy line:

<pre style="background-color:#DDA0DD!important; color:black">
local fireArmor = table.deepcopy(data.raw["armor"]["heavy-armor"])
</pre>

We assign a variable called fireArmor that holds our copy of the heavy armor definition. Notice how in data.raw, there is a type table that holds all armors, and the specific armor we're looking for is called heavy-armor. We can find [[heavy armor]]'s prototype type and internal name in the infobox of its page on this wiki and just copy it from there. 
Alternatively, we can find the items prototype type and internal name by opening the game, inserting the item into our inventory and then pressing {{Keybinding|shift|ctrl|F}} while hovering over the item. This will open the prototype explorer GUI, which has rows showing the name and type of the item.

As another example, the [[player|character]]'s prototype would be, according to the infobox on the page:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["character"]["character"]
</pre>

Because the character is ''the'' character, his type matches his name. You could define a new character with a mod. You can see all the available prototype fields of the character in the documentation: [https://lua-api.factorio.com/latest/prototypes/CharacterPrototype.html CharacterPrototype].

You may be thinking at this point, "Can I modify Factorio's existing prototypes without making new ones?" Well, the answer is yes! You would simply access the data.raw table during init, in data-final-fixes.lua if you want to run after all other mods, and change a property. For example, make the iron chest instead have 1000 health:

<pre style="background-color:#DDA0DD!important; color:black">
data.raw["container"]["iron-chest"].max_health = 1000
</pre>

The reason why this code is in data-final-fixes.lua is because that is the last file run, after all mod files have been run. This prevents (to a degree) your changes from being messed with by other mods. Of course, it is still possible to have incompatibilities. You should note any that you know of in your mod's description. Again, the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html dev's documentation] on this should be looked at.

This can also be applied to other mods, not just Factorio's base. You could mod a mod, as long as you add the mod (that you modified with your mod) to your dependencies so it gets loaded first.

=== The control scripting ===

And now, to finalize the mod, we have to make it be more than just simple armor. Let's think about what we want the armor to do. We want the armor to create fire on the ground as we walk with the armor on. The event we're going to use is called [https://lua-api.factorio.com/latest/events.html#on_player_changed_position on_player_changed_position], since we want the fire to be created when the player moves.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it is not necessary.

Inside control.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black;">
--control.lua

script.on_event(defines.events.on_player_changed_position,
function(event)
local player = game.get_player(event.player_index) -- get the player that moved
-- if they're currently controller the character
if player.controller_type == defines.controllers.character
-- And wearing our armor
and player.get_inventory(defines.inventory.character_armor).get_item_count("fire-armor") >= 1 then
-- create the fire where they're standing
player.surface.create_entity{name="fire-flame", position=player.position, force="neutral"}
end
end
)

</pre>

I've used lua comments in the code above to explain each step. It's fairly easy to understand, and it shows how you would get the current armor that the player character is wearing, with defines.inventory.character_armor, which is an inventory constant. You can read the list of defines [https://lua-api.factorio.com/latest/defines.html#defines.inventory here].

=== Locale ===

If you've already tried loading up Factorio and trying the mod so far (which you can at this point without it crashing), you may have noticed that the item name of the armor says "Unknown key". This means that Factorio has the internal name, but it doesn't know what it should look like to the user. So, we need to create a locale for our mod.

In the mod folder, create a folder called <code>locale</code>, then create another folder inside that called <code>en</code>, then a file called <code>any_name_can_be_here.cfg</code>.

If you know another language, you can also translate your mod by making other language code files inside locale, such as de for German.

Inside the .cfg file, paste the following:

<pre style="background-color:#AAFFAA!important; color:black">

[item-name]
fire-armor=Fire armor

[item-description]
fire-armor=An armor that seems to catch the ground itself on fire when you take a step. It's warm to the touch.
</pre>

Notice how this is not a lua file. Locale is handled with C config files, so the format is different.

== The finished tutorial mod ==

Well, the mod is finished. Since this mod is only a tutorial, there isn't much balance to it.

If you want to share a mod with other users, it needs to be a zip file. For that, simply zip the <code>fire-armor</code> folder and then rename the archive to <code>fire-armor_0.1.0</code> so that it follows the expected mod zip name pattern of <code>mod-name_version</code>. Keep in mind to not submit this tutorial mod to the mod portal as your own, since it's from the Wiki.

However, you're free to take this mod and modify it for your own use, changing recipes, adding technologies, whatever.

== Extended learning ==
One of the best ways to learn how to mod beyond this is to look at other mods. The [[Tutorial:Inspecting a live mod]] is a good starting point for touring a particularly well-commented mod. As all mods can be opened and inspected, looking at the mods of experienced modders can help significantly when making your own mod.

Something you'll see a lot in other mods or the base game are <code>require</code> statements. These load other files, so you can split up long code files and organize your mod however you like.

For example, if you wanted to put some of your data stage code into a file called "foo.lua" in a folder called "bar", your mod folder would look like this:

* fire-armor
** bar
*** foo.lua
** data.lua
** control.lua
** info.json

And you would need to add this to data.lua:
<pre style="background-color:#DDA0DD!important; color:black">
require("bar.foo")
</pre>

=== Keeping your mod working ===
As Factorio evolves, things will change. Previously, you probably ignored the modding part of the changelog, you now need to read it and see if any changes affect your mod(s). If so, you'll need to fix them. If there's something wrong with your mod, the game will fail to init and explain why.

== Resolving common errors in modding ==

As you continue to write mods from scratch instead of from a tutorial, you may encounter the infamous error. There are several types of errors that you can encounter in modding Factorio, and knowing how to deal with these errors will allow you to continue working.

=== Syntax errors ===

The Lua programming language expects things to be laid out a certain way. If you miss a bracket, = sign, or dot, you will encounter a syntax error. As an example, see the error below:

<pre style="background-color:#DDA0DD!important; color:black">
Failed to load mod "fire-armor": __fire-armor__/data.lua:39: unfinished string near '"fire-armor,'
</pre>

You'll see an error like the one above whenever you make a syntax error within the prototype definitions. The game will offer to restart, disable the troubling mod, disable all mods, or exit. Let's dissect the error, shall we?

Right away, we see the reason why Factorio didn't start normally. "Failed to load mod "fire-armor":". So, we know that it's our mod that messed up. Whenever the Lua engine of Factorio has a syntax error, it will print a mini stack-trace that follows through all requires, listing the call order. First, we see that the problem was caused by line 39 of data.lua. After stating where it is line-wise, it will attempt to give you an estimate of where in the line the problem is. Don't trust this estimate, only roughly trust the line number, plus or minus a few lines.

Going to line 39 of data.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
name = "fire-armor,
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an " after armor before the comma. Thus, syntax error. Fixing these can be difficult for new programmers, who don't know what to look for.

=== Illogical actions, indexing nil ===

In lua, "nothing" is defined as the keyword nil. This is similar to null in other programming languages. Whenever the programmer tries to access something in a table that is nil, they will get an error like the following:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
__fire-armor__/control.lua:3: attempt to index field '?' (a nil value)
</pre>

The "attempt to index field ..." error is often caused by the modder making an assumption that didn't work out. These types of errors will always be identifiable by their signature line, "attempt to index field". If we look at line 3 of control.lua (where the error is), we see:

<pre style="background-color:#DDA0DD!important; color:black">
game.print(game.players[23])
</pre>

What assumption has the modder made here? Well, there's actually two problems with this line. The first thing is that the modder has assumed that <code>game.players[23]</code> is a valid player, which isn't the case; this is why we get the "index field '?'" bit. The game doesn't know what the field is that we tried to index, because it hasn't been created yet. These errors are difficult to debug unless you know the ins and outs of the modding API well.

The second issue is a lot more subtle, and won't work. The modder is attempting to print a userdata table. [https://lua-api.factorio.com/latest/LuaPlayer.html A player] is a table of several values. Trying to print it simply print "LuaPlayer" instead of providing useful data.

=== Error while running event ===

Another common type of error in Factorio is the "Error while running event" error. This type of error only happens in control.lua scripting, and it happens when something goes wrong in an event function, such as a syntax error. '''Note that syntax errors in control.lua do not stop the game from starting, but may trigger after a save is loaded'''. There are a great deal of errors under this broad category, here's an example:

<pre style="background-color:#DDA0DD!important; color:black">
Error while running event fire-armor::on_player_changed_position (ID 82)
Unknown entity name: fire-flam
stack traceback:
__fire-armor__/control.lua:7: in function <__fire-armor__/control.lua:2>
</pre>

As you saw with the prototypes syntax error, Factorio gives a small traceback and the error name itself. In this case, we've attempted to spawn an entity called "fire-flam" on line 7 of control.lua, inside of an on_player_changed_position event hook. Fire-flam isn't a real entity type, so we crashed.

These types of errors can range from being a simple fix (like the one above, add the missing e), or can be very difficult.

=== Internal errors ===

The most rare form of error and the worst form is the internal error. This is an error with the C++ code of the game, and there's nothing you can do but report it to the devs. Mods occasionally cause these, and almost all of them are considered bugs, as mods ''should not'' be able to cause these, if that makes sense. They often get thrown into the logs.

An example:

<pre style="background-color:#DDA0DD!important; color:black">
696.148 Error FlowStatistics.cpp:236: FlowStatistics attempted to save value larger than uint16 as uint16. Exiting to prevent save corruption.
Logger::writeStacktrace skipped.
696.148 Error CrashHandler.cpp:190: Map tick at moment of crash: 432029
696.148 Error Util.cpp:97: Unexpected error occurred. If you're running the latest version of the game you can help us solve the problem by posting the contents of the log file on the Factorio forums.
Please also include the save file(s), any mods you may be using, and any steps you know of to reproduce the crash.
</pre>

== Multiplayer and desyncs ==

The reader may be wondering at this point how Factorio handles multiplayer with mods. It's fairly simple, but is still worth considering.

Factorio is [https://en.wikipedia.org/wiki/Deterministic_algorithm deterministic], which means that when you provide a constant input, you get a constant output, with no variance. Every client and the server all reach the same points at the same time in simulation, so they all agree on what happened. When this differs, the players experience a ''desync''.

; Desync : Misalignment with server and clients. Client 1 expected A, but got B. All other clients got A. Thus, Client 1 will desync. Desync can also happen when all clients have information (for example a variable) but a client that recently joined the game doesn't. That client will be desynced.
: ''See also: [[Desynchronization]]''

Desyncs happen a lot to new devs of Factorio mods, because they are unaware that a particular piece of code they used causes desyncs. As a general rule, there are a few things that should never be done.

=== Use local variables that are not final outside of event hooks ===

<pre style="background-color:#DDA0DD!important; color:black">
local globalLocal = 1
script.on_event(defines.events.on_player_built_item, function()
globalLocal = math.random()
end)
</pre>

If the modder places a local variable outside of an event hook that gets changed during runtime, desyncs will happen when that variable is utilised to modify the game state (i.e. manipulate an entity, print text to players). If making a "global" variable is necessary, place the variable in the [https://lua-api.factorio.com/latest/auxiliary/global.html global] table instead. The game syncs this table between all clients, so they can all be aware of and reach the same conclusion as each other.

=== Conditional event subscribing ===

Mods in factorio may subscribe to events in order to be notified when they happen. This allows mods to react to events when they occur. Typically, event subscription is done at the top level of a lua file.

Doing event subscription inside of a conditional, function, or other event is dangerous, as doing it incorrectly will lead to desyncs. Basically, since both the server and client need to reach the same conclusion after running code, conditional subscription can lead to certain clients or the server being subscribed to an event when the others are not, causing desyncs.

=== Improper use of on_load ===

Another way to cause desyncs is to make improper actions inside of an on_load call, which some players new to modding might try to do. According to the [https://lua-api.factorio.com/latest/LuaBootstrap.html#LuaBootstrap.on_load documentation], the on_load functionality is meant for 3 purposes '''only''':

* Re-register conditional event handlers
* Re-setup meta tables
* Create local references to tables stored in the global table

Doing anything else will cause desyncs. The game will catch most attempts, crashing instead and terminating the mod.

=== Comparison by reference ===

Be cautious of comparing tables by reference. In multiplayer syncing, tables deserialized from the server state will be new objects, not equal by reference to any table initialized by client code.

<pre style="background-color:#DDA0DD!important; color:black">
if a == b then
</pre>
<pre style="background-color:#DDA0DD!important; color:black">
if a ~= b then
</pre>
If <code>a</code> and <code>b</code> are tables in the above conditionals, there will for example be different results between server and client if <code>a</code> is created locally and <code>b</code> is downloaded from the server.

Note that LuaObjects provided by the game have their equality operator overwritten to prevent this behaviour, so code such as <code>LuaEntityA ~= LuaEntityB</code> will not desync.
However, this does not apply when LuaObjects are used as keys in tables:
<pre style="background-color:#DDA0DD!important; color:black">
if table[LuaObject] then
</pre>
This will desync in the same way as described for the plain tables <code>a</code> and <code>b</code> above. For entities it is recommended to use [https://lua-api.factorio.com/latest/LuaEntity.html#LuaEntity.unit_number LuaEntity.unit_number] as the table key instead of the whole entity.

== See also ==
* [[Modding]]
* [[Tutorial:Modding tutorial|Modding tutorial overview]]

[[Category:Modding]]

Rich text

2024-10-23T17:24:17Z

PennyJim: Make quality its own section, and use a baked image instead of trying to overlay images

{{Languages}}
Rich text formatting in allows the use of tags within most of the game's textboxes to change the visual formatting of text or to embed interactable images/entities. Predefined text tags are employed for this purpose.

== Tags ==

Tags are useful for sharing blueprints, marking map locations in chat or adding icons to map markers and train stations.
Ctrl+alt clicking the map or ground will automatically insert a gps tag and post it into [[console|chat]].

Shift clicking most things with the console open will insert a tag for that thing into chat. The chat and many other textboxes in the game have a button on the right edge that opens an icon selector. This can be used to easily insert rich text tags of recipes, items, fluids, virtual signals and entities into the textbox.

When used in chat, the tag image will be followed by a text description, except for the img tag.
Used elsewhere only the image is shown.

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description

|-
| [img=class/name] 
[img=class.name] 
[img=sprite-prototype-name]
| [img=item.iron-plate] 
[img=quantity-time] 
[img=utility/played_green]
| [[File:Iron_plate.png|28px]] 
[[File:Time_icon.png|28px]] 
[[File:Played green.png|28px]]
| Embeds only a small inline game graphic. The period format must be used in game save names. This tag uses [https://lua-api.factorio.com/latest/Concepts.html#SpritePath sprite paths]:
class is any of: item, entity, technology, recipe, item-group, fluid, tile, virtual-signal, achievement, equipment or utility.

name: see below

sprite-prototype-name is the [[Data.raw#sprite|internal-name]] of a [[Prototype/Sprite|sprite prototype]].

|-
| [item=name]
| [item=iron-plate]
| [[File:Iron_plate.png|28px]] [Item: Iron plate]
| name is the internal-name of the item

|-
| [entity=name]
| [entity=small-biter]
| [[File:Small_biter.png|28px]] [Entity: Small biter]
| name is the internal-name of the entity

|-
| [technology=name]
| [technology=logistics]
| [[File:Logistics_(research).png|28px]] [Technology: Logistics]
| name is the internal-name of the technology

|-
| [recipe=name]
| [recipe=basic-oil-processing]
| [[File:Basic_oil_processing.png|28px]] [Recipe: Basic oil processing]
| name is the internal-name of the recipe, usually the item name

|-
| [item-group=name]
| [item-group=combat]
| [[File:Item-group_military.png|28px]] [Item Group: Combat]
| name is any of: logistics, production, intermediate-products, combat, fluids or signals

|-
| [fluid=name]
| [fluid=water]
| [[File:Water.png|28px]] [Fluid: Water]
| name is the internal name of the fluid

|-
| [tile=name]
| [tile=grass-3]
| [[File:Grass_3.png|28px]] [Tile: Grass 3]
| name is the internal name of the tile, usually the lowercase name with hyphens replacing spaces as written from the map editor

|-
| [virtual-signal=name]
| [virtual-signal=signal-A]
| [[File:Signal-A.png|28px]] [Virtual Signal: Signal A]
| name is the word signal followed by either an uppercase letter, number, color, each, everything or anything

|-
| [achievement=name]
| [achievement=minions]
| [[File:Minions-achievement.png|28px]] [Achievement: Minions]
| name is the internal-name of the achievement, usually the lowercase name with hyphens replacing spaces

|-
| [gps=x,y]
[gps=x,y,surface]
| [gps=0,0]
| [[File:Map.png|28px]] [Location: 0,0]
| Embeds a map location and marks the location on the map of other players.
x is the x point coordinate 
y is the y point coordinate 
surface is the current surface. Is only added if the player Ctrl+alt clicks on a surface that is not the default surface. When the player is on another surface than surface, clicking the tag does nothing. Mods must handle this case with [https://lua-api.factorio.com/latest/events.html#on_player_clicked_gps_tag on_player_clicked_gps_tag]
|-
| [special-item=blueprint_string]
|
| [[File:Blueprint.png|28px]] [Blueprint]
| Embeds a blueprint. Players can get a blueprint item by clicking the icon.
blueprint_string is the blueprint string of a blueprint, deconstruction planner or upgrade planners

|-
| [armor=player]
| [armor=Player]
| [[File:Power_armor_MK2.png|28px]] [Armor: Player]
| Embeds the armor of a player. Allows other players to see the equipment installed.
player is the name of the player

|-
| [train=number]
| [train=93]
| [[File:Locomotive.png|28px]] [Train: 2]
| Embeds a reference to a train. Clicking the icon will open the train GUI for that train.
number is the internal unit number of the train

|-
| [train-stop=number]
| [train-stop=100]
| [[File:Train_stop.png|28px]] [Train Stop: Trangar]
| Embeds a reference to a train stop. Clicking the icon will open the GUI for that train stop.
number is the internal unit number of the train stop

|-
| [tooltip=text,tooltip locale key]
| [tooltip=Hover to see "Iron plate",item-name.iron-plate]
| [[File:Custom-tag-icon.png|28px]] Hover to see "Iron plate"
| Shows the given text with a tooltip that is specified with a [[Tutorial:Localisation#Localising_simple_strings|locale key]].

|-
| [quality=tier] 
[item=name,quality=tier] 
[entity=name,quality=tier] 

|[quality=normal] 
[item=iron-plate,quality=normal] 
[entity=small-biter,quality=uncommon] 

| [[File:Quality normal.png|28px]] [Quality: Normal] 
[[File:Iron_plate.png|28px]] [Item: Iron plate] 
[[File:Uncommon small biter.png|28px]] [Entity: Uncommon Small biter] 
|
[[Quality]] can also be optionally specified on the following tags: item, entity, recipe, fluid, and virtual-signal 
It can also be added to the other tags that use name, but they ignore it.

The normal quality is the default quality and won't modify tags. Any other quality won't exist without [[Space Age]] and Quality

tier is the internal-name of the quality

|}

== Text modifiers ==
[[File:Fonts.png|right|thumbnail|100px|Different fonts displayed in-game. (Click to enlarge.)]]

The color and font of text can be changed

{| class="wikitable"
|-
! style="width:20%"| Syntax
! style="width:15%"| Example Input
! style="width:15%"| Example Result
! style="width:50%"| Description
|-
| [color=rgb]...[/color] 
[color=#rrggbb]...[/color] 
[color=#aarrggbb]...[/color] 
[color=rgb]...[.color] 
[color=#rrggbb]...[.color] 
[color=#aarrggbb]...[.color]
| [color=red]Red[/color] text 
[color=1,0,0]Red[/color] text 
[color=255,0,0]Red[/color] text 
[color=#ff0000]Red[/color] text
| Red text
| rgb is a comma separated RGB color ranging from 0 to 1 or 0 to 255, or a color name
Available colors: default, red, green, blue, orange, yellow, pink, purple, white, black, gray, brown, cyan, acid.
|-
| [font=font-name]...[/font] 
[font=font-name]...[.font]
| [font=default-bold]Bold text[/font]
| Bold text
| font-name is the name of the [[Data.raw#font|Factorio font]] to render
|}

== See also ==
* [[Console]]
* [[Data.raw]] for the list of internal names of recipes, technologies, fluids, etc.

{{C|GUI}}

File:Uncommon small biter.png

2024-10-23T16:48:54Z

PennyJim:

The icon for a small biter with the uncommon quality tag on it. It doesn't perfectly match the base game, but it's visually almost identical.

The quality icon was simply scaled down to 32x32 before overlaying it on top of the 64x64 icon

File:Quality uncommon.png

2024-10-23T16:39:24Z

PennyJim:

The uncommon quality tier icon

File:Quality normal.png

2024-10-23T16:32:19Z

PennyJim:

The icon for the normal quality