Official Factorio Wiki - User contributions [en]

Console

2023-06-02T08:39:55Z

Jan1i3: /* Research scripts */

{{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 <span style="color:#FF0000">disable achievements for the save game</span>)

__TOC__

=== Using the console ===
The console display can be toggled with the {{keybinding|/}} (slash) or {{keybinding|~}} (tilde) keys.

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 <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>
| Researches all technologies and enables cheat mode. Using the '''all''' option also gives the player some additional items.
|-
| /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.
|-
| /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 <span style="color:#FF0000">achievements will be permanently disabled for the save</span> 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
game.player.force.set_saved_technology_progress(tech, 0)
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 if you replace "BOOL" with "true" or unfreezes it if you replace it with "false".
<syntaxhighlight lang="lua">
/c game.player.surface.freeze_daytime=BOOL
</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 [gps=" .. speaker.position.x .. "," .. speaker.position.y .. "]")
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>

=== 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(game.get_filtered_entity_prototypes{{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>

=== Create 10 fishes ===
This creates 10 fishes around of player. The player must be on the water edge.
<syntaxhighlight lang="lua">
/c local player = game.player
local surface = player.surface
for i = 1, 10 do
local position = surface.find_non_colliding_position('fish', player.position, 10, 1)
if not position then return end
surface.create_entity {name = 'fish', position = position}
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>

=== Connect linked belts ===
If there exist at least two [[Prototype/LinkedBelt|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"].evolution_factor=X
</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>

== 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.x .. ", " .. game.player.position.y)
</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.

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

Disassociate your controls from the player:
<syntaxhighlight lang="lua">
/c game.player.character=nil
</syntaxhighlight>

Then, hover the mouse over the useless player and destroy it by typing:
<syntaxhighlight lang="lua">
/c game.player.selected.destroy()
</syntaxhighlight>

To undo, spawn a player character. This will spawn a new player 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 .. " --> [gps=" .. corpse.position.x .. "," .. corpse.position.y .. "]")
end
</syntaxhighlight>

== Research scripts ==

=== Enable Research Queue ===
Enable the research queue for the player's current team. Can be done after the game has started if it was forgotten during the map's setup.
<syntaxhighlight lang="lua">
/c game.player.force.research_queue_enabled = true
</syntaxhighlight>

=== 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>

=== 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; game.player.force.set_saved_technology_progress('electric-energy-distribution-1', 0)
/c game.player.force.technologies['steel-processing'].researched=false; game.player.force.set_saved_technology_progress('steel-processing', 0)
</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 Resource Spawner Overhaul:
<syntaxhighlight lang="lua">
/c __rso-mod__ 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>

== See also ==

* [[Command line parameters]]
* http://lua-api.factorio.com/latest/ - Factorio API reference for latest version

Prototype/TransportBelt

2021-01-25T23:54:23Z

Jan1i3: Add circuit_connector_sprites. Requesting verification of added property. Sorry for misclick-saving twice

{{Prototype parent|Prototype/TransportBeltConnectable}}
A [[transport belt]].

{{Prototype TOC|transport-belt}}

== Mandatory properties ==
This prototype inherits all the properties from [[Prototype/TransportBeltConnectable]].

{{Prototype property|connector_frame_sprites|[[Types/TransportBeltConnectorFrame|TransportBeltConnectorFrame]]}}

== Optional properties ==

{{Prototype property|circuit_wire_max_distance|[[Types/double|double]]|0|optional=true}}
The maximum circuit wire distance for this entity.

{{Prototype property|draw_copper_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|draw_circuit_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|circuit_wire_connection_point|Array of [[Types/WireConnectionPoint|WireConnectionPoint]]|optional=true}}
Defines how wires visually connect to this transport belt.

{{Prototype property|circuit_connector_sprites|Array of [[Types/CircuitConnectorSprites|CircuitConnectorSprites]]|optional=true}}
The pictures displayed for circuit connections to this transport belt.

{{Prototype property|belt_animation_set|[[Types/table|table]]|optional=true}}
Either this, or <code>animations</code> has to present.

This is the same table as the one used by [[Prototype/TransportBeltConnectable]], with additional properties. If this is present, the belt_animation_set will used for all graphics.

Table with the following additional optional properties:
* east_to_north_index - [[Types/uint8|uint8]] - Default: 5
* north_to_east_index - [[Types/uint8|uint8]] - Default: 6
* west_to_north_index - [[Types/uint8|uint8]] - Default: 7
* north_to_west_index - [[Types/uint8|uint8]] - Default: 8
* south_to_east_index - [[Types/uint8|uint8]] - Default: 9
* east_to_south_index - [[Types/uint8|uint8]] - Default: 10
* south_to_west_index - [[Types/uint8|uint8]] - Default: 11
* west_to_south_index - [[Types/uint8|uint8]] - Default: 12

{{Prototype property|animations|[[Types/RotatedAnimation|RotatedAnimation]]|optional=true}}
Transport belts must have 12 animations. Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|related_underground_belt|[[Types/string|string]]|optional=true}}
The name of the [[Prototype/UndergroundBelt]] which is used in quick-replace fashion when the smart belt dragging behavior is triggered.

Prototype/TransportBelt

2021-01-25T23:49:44Z

Jan1i3:

{{Prototype parent|Prototype/TransportBeltConnectable}}
A [[transport belt]].

{{Prototype TOC|transport-belt}}

== Mandatory properties ==
This prototype inherits all the properties from [[Prototype/TransportBeltConnectable]].

{{Prototype property|connector_frame_sprites|[[Types/TransportBeltConnectorFrame|TransportBeltConnectorFrame]]}}

== Optional properties ==

{{Prototype property|circuit_wire_max_distance|[[Types/double|double]]|0|optional=true}}
The maximum circuit wire distance for this entity.

{{Prototype property|draw_copper_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|draw_circuit_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|circuit_wire_connection_point|Array of [[Types/WireConnectionPoint|WireConnectionPoint]]|optional=true}}
Defines how wires visually connect to this transport belt.

{{Prototype property|circuit_connector_sprites|Array of [[Types/CircuitConnectorSprites|CircuitConnectorSprites]]|optional=true}}
The pictures displayed for circuit connections to this transport belt.

{{Prototype property|belt_animation_set|[[Types/table|table]]|optional=true}}
Either this, or <code>animations</code> has to present.

This is the same table as the one used by [[Prototype/TransportBeltConnectable]], with additional properties. If this is present, the belt_animation_set will used for all graphics.

Table with the following additional optional properties:
* east_to_north_index - [[Types/uint8|uint8]] - Default: 5
* north_to_east_index - [[Types/uint8|uint8]] - Default: 6
* west_to_north_index - [[Types/uint8|uint8]] - Default: 7
* north_to_west_index - [[Types/uint8|uint8]] - Default: 8
* south_to_east_index - [[Types/uint8|uint8]] - Default: 9
* east_to_south_index - [[Types/uint8|uint8]] - Default: 10
* south_to_west_index - [[Types/uint8|uint8]] - Default: 11
* west_to_south_index - [[Types/uint8|uint8]] - Default: 12

{{Prototype property|animations|[[Types/RotatedAnimation|RotatedAnimation]]|optional=true}}
Transport belts must have 12 animations. Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|related_underground_belt|[[Types/string|string]]|optional=true}}
The name of the [[Prototype/UndergroundBelt]] which is used in quickreplace fashion when the smart belt dragging behavior is triggered.

Prototype/TransportBelt

2021-01-25T23:46:58Z

Jan1i3:

{{Prototype parent|Prototype/TransportBeltConnectable}}
A [[transport belt]].

{{Prototype TOC|transport-belt}}

== Mandatory properties ==
This prototype inherits all the properties from [[Prototype/TransportBeltConnectable]].

{{Prototype property|connector_frame_sprites|[[Types/TransportBeltConnectorFrame|TransportBeltConnectorFrame]]}}

== Optional properties ==

{{Prototype property|circuit_wire_max_distance|[[Types/double|double]]|0|optional=true}}
The maximum circuit wire distance for this entity.

{{Prototype property|draw_copper_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|draw_circuit_wires|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|circuit_wire_connection_point|Array of [[Types/WireConnectionPoint|WireConnectionPoint]]|optional=true}}
Defines how wires visually connect to this transport belt.

{{Prototype property|circuit_connector_sprites|Array of [[Types/CircuitConnectorSprites|CircuitConnectorSprites]]|optional=true}}
The pictures displayed for circuit connections to this transport belt.

{{Prototype property|belt_animation_set|[[Types/table|table]]|optional=true}}
Either this, or <code>animations</code> has to present.

This is the same table as the one used by [[Prototype/TransportBeltConnectable]], with additional properties. If this is present, the belt_animation_set will used for all graphics.

Table with the following additional optional properties:
* east_to_north_index - [[Types/uint8|uint8]] - Default: 5
* north_to_east_index - [[Types/uint8|uint8]] - Default: 6
* west_to_north_index - [[Types/uint8|uint8]] - Default: 7
* north_to_west_index - [[Types/uint8|uint8]] - Default: 8
* south_to_east_index - [[Types/uint8|uint8]] - Default: 9
* east_to_south_index - [[Types/uint8|uint8]] - Default: 10
* south_to_west_index - [[Types/uint8|uint8]] - Default: 11
* west_to_south_index - [[Types/uint8|uint8]] - Default: 12

{{Prototype property|animations|[[Types/RotatedAnimation|RotatedAnimation]]|optional=true}}
Transport belts must have 12 animations. Mandatory if <code>belt_animation_set</code> is not present.

{{Prototype property|related_underground_belt|[[Prototype/UndergroundBelt|UndergroundBelt]]|optional=true}}
The underground belt which is used in quickreplace fashion when the smart belt dragging behavior is triggered.

Property tree

2020-12-08T23:13:45Z

Jan1i3: /* String */ Change the bool to indicate "no string" instead of "empty string"

{{Languages}}A PropertyTree (the Factorio class name) is a recursive variant format that holds a key <> value pair where the key may be empty and the value may be only one of the following types:

{| class="wikitable"
|+PropertyTreeType ([[Data_types#unsigned byte|unsigned byte]])
|-
! Value !! Name
|-
| 0 || [[Property_tree#None|none]]
|-
| 1 || [[Property_tree#Bool|bool]]
|-
| 2 || [[Property_tree#Number|number]]
|-
| 3 || [[Property_tree#String|string]]
|-
| 4 || [[Property_tree#List|list]]
|-
| 5 || [[Property_tree#Dictionary|dictionary]]
|}

== The file format ==

1 [[Data_types#unsigned byte|unsigned byte]] representing the PropertyTreeType.

1 [[Data_types#bool|bool]] the any-type flag (currently not important outside of Factorio internals; default value is false)

== Property Tree Type ==

=== None ===
Nothing

=== Bool ===
1 [[Data_types#bool|bool]]

=== Number ===
1 [[Data_types#double|double]]

=== String ===
1 [[Data_types#bool|bool]] if there is no string - otherwise, if there is a string:

1 [[Data_types#Space optimized|Space optimized]] [[Data_types#unsigned int|unsigned int]] the size of the string

N [[Data_types#byte|byte]] the string contents

=== List ===
Identical to Dictionary

=== Dictionary ===
1 [[Data_types#unsigned int|unsigned int]] the number of PropertyTree elements

For each element:

1 [[Property_tree#String|string]] the dictionary element name or it can be empty if loading a list

1 [[Property_tree]]

[[Category:Technical]]

Prototype/CustomInput

2020-11-24T02:56:26Z

Jan1i3: /* Mandatory properties */ Add empty string for unassigned notice for key_sequence

{{Prototype parent|PrototypeBase}}
Used for custom keyboard shortcuts/keybindings in mods. The key associated with the custom input can be changed in the options. This means that <code>key_sequence</code> is simply the default keybinding.

{{Prototype TOC|custom-input}}

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

=== name ===
:''See [[PrototypeBase#name]]''

Inherited from [[PrototypeBase]]. It is also the name for the event that is raised when they key (combination) is pressed and action is "lua", see [[Tutorial:Script interfaces]].

{{Prototype property|key_sequence|[[Types/string|string]]}}
The default key sequence for this custom input.

* "" (empty string) for unassigned
* "mouse-button-2" etc for mouse buttons, mouse-button-3 for middle mouse button
* "mouse-wheel-up", "mouse-wheel-down", "mouse-wheel-left", "mouse-wheel-right" for mouse wheel (mouse wheel controls do not work for custom inputs!)
* " + " is used to separate modifier keys from normal keys: <code>"ALT + G"</code>
* For modifier keys, the following names are used: "CONTROL", "SHIFT", "ALT", "COMMAND"
* A keybinding can contain an unlimited amount of modifier keys (listed above) but only one normal key (listed below).

<div class="toccolours mw-collapsible mw-collapsed" style="width: 40em;">
These names are available for the normal keys
<pre class="mw-collapsible-content">
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
1
2
3
4
5
6
7
8
9
0
RETURN
ESCAPE
BACKSPACE
TAB
SPACE
MINUS
EQUALS
LEFTBRACKET
RIGHTBRACKET
BACKSLASH
NONUSHASH
SEMICOLON
APOSTROPHE
GRAVE
COMMA
PERIOD
SLASH
CAPSLOCK
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
PRINTSCREEN
SCROLLLOCK
PAUSE
INSERT
HOME
PAGEUP
DELETE
END
PAGEDOWN
RIGHT
LEFT
DOWN
UP
NUMLOCKCLEAR
KP_DIVIDE
KP_MULTIPLY
KP_MINUS
KP_PLUS
KP_ENTER
KP_1
KP_2
KP_3
KP_4
KP_5
KP_6
KP_7
KP_8
KP_9
KP_0
KP_PERIOD
NONUSBACKSLASH
APPLICATION
POWER
KP_EQUALS
F13
F14
F15
F16
F17
F18
F19
F20
F21
F22
F23
F24
EXECUTE
HELP
MENU
SELECT
STOP
AGAIN
UNDO
CUT
COPY
PASTE
FIND
MUTE
VOLUMEUP
VOLUMEDOWN
KP_COMMA
KP_EQUALSAS400
INTERNATIONAL1
INTERNATIONAL2
INTERNATIONAL3
INTERNATIONAL4
INTERNATIONAL5
INTERNATIONAL6
INTERNATIONAL7
INTERNATIONAL8
INTERNATIONAL9
LANG1
LANG2
LANG3
LANG4
LANG5
LANG6
LANG7
LANG8
LANG9
ALTERASE
SYSREQ
CANCEL
CLEAR
PRIOR
RETURN2
SEPARATOR
OUT
OPER
CLEARAGAIN
CRSEL
EXSEL
KP_00
KP_000
THOUSANDSSEPARATOR
DECIMALSEPARATOR
CURRENCYUNIT
CURRENCYSUBUNIT
KP_LEFTPAREN
KP_RIGHTPAREN
KP_LEFTBRACE
KP_RIGHTBRACE
KP_TAB
KP_BACKSPACE
KP_A
KP_B
KP_C
KP_D
KP_E
KP_F
KP_XOR
KP_POWER
KP_PERCENT
KP_LESS
KP_GREATER
KP_AMPERSAND
KP_DBLAMPERSAND
KP_VERTICALBAR
KP_DBLVERTICALBAR
KP_COLON
KP_HASH
KP_SPACE
KP_AT
KP_EXCLAM
KP_MEMSTORE
KP_MEMRECALL
KP_MEMCLEAR
KP_MEMADD
KP_MEMSUBTRACT
KP_MEMMULTIPLY
KP_MEMDIVIDE
KP_PLUSMINUS
KP_CLEAR
KP_CLEARENTRY
KP_BINARY
KP_OCTAL
KP_DECIMAL
KP_HEXADECIMAL
LCTRL
LSHIFT
LALT
LGUI
RCTRL
RSHIFT
RALT
RGUI
MODE
AUDIONEXT
AUDIOPREV
AUDIOSTOP
AUDIOPLAY
AUDIOMUTE
MEDIASELECT
WWW
MAIL
CALCULATOR
COMPUTER
AC_SEARCH
AC_HOME
AC_BACK
AC_FORWARD
AC_STOP
AC_REFRESH
AC_BOOKMARKS
BRIGHTNESSDOWN
BRIGHTNESSUP
DISPLAYSWITCH
KBDILLUMTOGGLE
KBDILLUMDOWN
KBDILLUMUP
EJECT
SLEEP
APP1
APP2
AUDIOREWIND
AUDIOFASTFORWARD
</pre>
</div>

== Optional properties ==

{{Prototype property|alternative_key_sequence|[[Types/string|string]]|optional=true}}
The alternative keybinding for this control. See [[#key_sequence]].

{{Prototype property|linked_game_control|[[Types/string|string]]|""|optional=true}}
When a custom-input is linked to a game control it won't show up in the control-settings GUI and will fire when the linked control is pressed. [https://forums.factorio.com/53591]

<div class="toccolours mw-collapsible mw-collapsed" style="width: 40em;">
List of internal names of game controls
<pre class="mw-collapsible-content">
action-bar-select-page-1
action-bar-select-page-10
action-bar-select-page-2
action-bar-select-page-3
action-bar-select-page-4
action-bar-select-page-5
action-bar-select-page-6
action-bar-select-page-7
action-bar-select-page-8
action-bar-select-page-9
activate-tooltip
add-station-modifier
alt-zoom-in
alt-zoom-out
build
build-ghost
build-with-obstacle-avoidance
cancel-craft
cancel-craft-5
cancel-craft-all
clean-cursor
close-gui
confirm-message
connect-train
copy
copy-entity-settings
craft
craft-5
craft-all
cursor-split
cut
cycle-blueprint-backwards
cycle-blueprint-forwards
cycle-clipboard-backwards
cycle-clipboard-forwards
debug-reset-zoom
debug-reset-zoom-2x
debug-toggle-atlas-gui
debug-toggle-autoplace-gui
debug-toggle-basic
debug-toggle-debug-settings
decrease-ui-scale
disconnect-train
drag-map
drop-cursor
editor-clone-item
editor-delete-item
editor-next-variation
editor-previous-variation
editor-reset-speed
editor-speed-down
editor-speed-up
editor-tick-once
editor-toggle-pause
fast-entity-split
fast-entity-transfer
focus-search
give-blueprint
give-blueprint-book
give-deconstruction-planner
give-upgrade-planner
increase-ui-scale
inventory-split
inventory-transfer
kill-statistics
larger-terrain-building-area
logistic-networks
mine
move-down
move-left
move-right
move-up
next-active-quick-bar
next-weapon
open-character-gui
open-gui
open-item
open-technology-gui
paste
paste-entity-settings
pause-game
pick-item
pick-items
place-in-chat
place-ping
place-tag
previous-active-quick-bar
previous-mod
previous-technology
production-statistics
quick-bar-button-1
quick-bar-button-1-secondary
quick-bar-button-10
quick-bar-button-10-secondary
quick-bar-button-2
quick-bar-button-2-secondary
quick-bar-button-3
quick-bar-button-3-secondary
quick-bar-button-4
quick-bar-button-4-secondary
quick-bar-button-5
quick-bar-button-5-secondary
quick-bar-button-6
quick-bar-button-6-secondary
quick-bar-button-7
quick-bar-button-7-secondary
quick-bar-button-8
quick-bar-button-8-secondary
quick-bar-button-9
quick-bar-button-9-secondary
remove-pole-cables
reset-ui-scale
reverse-rotate
rotate
rotate-active-quick-bars
select-for-blueprint
select-for-cancel-deconstruct
shoot-enemy
shoot-selected
show-info
smaller-terrain-building-area
smart-pipette
stack-split
stack-transfer
temporary-station-modifier
toggle-blueprint-library
toggle-console
toggle-driving
toggle-equipment-movement-bonus
toggle-filter
toggle-gui-debug
toggle-gui-glows
toggle-gui-shadows
toggle-gui-style-view
toggle-map
toggle-menu
toggle-personal-roboport
toggle-tips-and-tricks
undo
zoom-in
zoom-out
</pre></div>

Example to use the same key sequence as the clean-cursor hotkey:
<syntaxhighlight lang="lua">key_sequence = ""
linked_game_control = "clean-cursor"</syntaxhighlight>

{{Prototype property|consuming|[[Types/ConsumingType|ConsumingType]]|"none"|optional=true}}

{{Prototype property|enabled|[[Types/bool|bool]]|true|optional=true}}
If this custom input is enabled. Disabled custom inputs exist but are not used by the game. If disabled, no event is raised when the input is used.

{{Prototype property|enabled_while_spectating|[[Types/bool|bool]]|false|optional=true}}

{{Prototype property|enabled_while_in_cutscene|[[Types/bool|bool]]|false|optional=true}}

{{Prototype property|item_to_create|[[Types/string|string]]|optional=true}}
Name of a [[Prototype/Item]]. It will be created when this input is pressed.

{{Prototype property|action|[[Types/string|string]]|"lua"|optional=true}}
One of "lua", "create-blueprint-item", "toggle-personal-roboport", "toggle-personal-logistic-requests" and "toggle-equipment-movement-bonus".

A lua event is only raised if the action is "lua".

Tutorial:Modding tutorial/Gangsir

2020-11-10T23:14:18Z

Jan1i3: Fix broken LuaPlayer api link

{{Languages}}
This is a modding tutorial for Factorio version 1.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 1.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 or item 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, and many functionally identical entities/items 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.

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 scripting at their [https://lua-api.factorio.com/latest/ API site] and documentation all around prototypes on [[Prototype definitions|this wiki]]. Get used to using these sites, as they will become frequent visits you will make 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. [[Prototype definitions]] contains and links to information all around prototypes, listing their inheritance structure and their properties. You will need to check these sites often, so the author recommends bookmarking them. In addition to these sites, there is 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 here on the wiki: [[Prototype definitions]].

=== Migrations ===

[https://lua-api.factorio.com/latest/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/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 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>, or another file <code>require</code>d by one of these three.

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, etc
* 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_0.1.0</code>. When you're finished, the mod directory should look like this:

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

Then, inside fire-armor_0.1.0, 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_0.1.0
**** 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": "1.0",
"dependencies": ["base >= 1.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, 1.0 in this case.
|-
| dependencies
| Any dependencies of your mod.
|-
| description
| A ''short'' description of your mod.
|}

And that's all for info.json! Next, in the data.lua file:

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

require("item")
</pre>

It's a pretty simple file, all we're doing here is just telling the game to execute the file called item.lua, which we're about to create. Create a file in fire-armor_0.1.0 called <code>item.lua</code>. Notice how our earlier require used the file name in it?

We are creating this file just for our own organisation inside the mod, so there are no naming or other requirements from the game's side. As long as we tell the game to load the file with "require", the file name or its exact location inside the mod does not matter.

=== Prototype creation ===

Now, there are two ways to create prototypes in Factorio. There's the short way, and the long way. The long way requires to create a complete prototype definition based on [[prototype definitions|the documentation]], and the short way just uses a lua function to copy and modify an already existing definition. For the sake of this tutorial, we'll do it the short way.

In item.lua, copy and paste the following:

<pre style="background-color:#AAFFAA!important; color:black">
--item.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,
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
}
}

local recipe = table.deepcopy(data.raw["recipe"]["heavy-armor"])
recipe.enabled = true
recipe.name = "fire-armor"
recipe.ingredients = {{"copper-plate",200},{"steel-plate",50}}
recipe.result = "fire-armor"

data:extend{fireArmor,recipe}

</pre>

What we've just done here is we've copied the definition of heavy armor, then changed it's 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 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 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 indentified 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.<br>
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 type of character with a mod. You can see all the available prototype fields of the charater in the documenation: [[Prototype/Character]].

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/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 wearing our armor
if player.character 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 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. Additionally, don't try submitting it 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.

== 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 mods: __fire-armor__/data.lua:1:__fire-armor__/prototypes/item.lua:36: syntax error near 'true'
</pre>

As of version 0.15, 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 mods:". So, we know that it's a mod that messed up, and by extension, we know it's our mod. 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 indirectly caused by line 1 of data.lua. There's no problem there, so it must be the next entry, line 36 of prototypes/item.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 36 of item.lua, we find:

<pre style="background-color:#DDA0DD!important; color:black">
recipe.enabled true
</pre>

Hmm, that doesn't look right. Can you see what's missing? We left off an = between enabled and true. 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/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.

=== Selective requiring ===

<pre style="background-color:#DDA0DD!important; color:black">
if setting1 then
require("settingOne.lua")
end
</pre>

Selective requiring, aka requiring different lua files based on settings can cause connection rejections as the checksum of the mods will not match, as they load different data. All clients' mods must require the same series of files.

=== 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.

== 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.

=== 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.

== See also ==

* [[Modding]]
* [[Modding FAQ]]

Prototype/Entity

2020-10-18T20:22:29Z

Jan1i3: Update emissions_per_second example to new, correct base game values

{{Prototype parent|PrototypeBase}}
Abstract base of all entities in the game.
Entity is basically everything that can be on the map (except tiles).
For in game script access to entity, take a look at [http://lua-api.factorio.com/latest/LuaEntity.html LuaEntity]

{{Prototype TOC|''abstract''}}

== Extensions ==
<div class="factorio-list">
* [[Prototype/Arrow]] '''arrow'''
* [[Prototype/ArtilleryFlare]] '''artillery-flare'''
* [[Prototype/ArtilleryProjectile]] '''artillery-projectile'''
* [[Prototype/Beam]] '''beam'''
* [[Prototype/CharacterCorpse]] '''character-corpse'''
* [[Prototype/Cliff]] '''cliff'''
* [[Prototype/Corpse]] '''corpse'''
** [[Prototype/RailRemnants]] '''rail-remnants'''
* [[Prototype/DeconstructibleTileProxy]] '''deconstructible-tile-proxy'''
* [[Prototype/EntityGhost]] '''entity-ghost'''
* [[Prototype/EntityParticle]] '''particle''' (for migration, cannot be used)
** [[Prototype/LeafParticle]] '''leaf-particle''' (for migration, cannot be used)
* [[Prototype/EntityWithHealth]] <abstract>
** [[Prototype/Accumulator]] '''accumulator'''
** [[Prototype/ArtilleryTurret]] '''artillery-turret'''
** [[Prototype/Beacon]] '''beacon'''
** [[Prototype/Boiler]] '''boiler'''
** [[Prototype/BurnerGenerator]] '''burner-generator'''
** [[Prototype/Character]] '''character'''
** [[Prototype/Combinator]] <abstract>
*** [[Prototype/ArithmeticCombinator]] '''arithmetic-combinator'''
*** [[Prototype/DeciderCombinator]] '''decider-combinator'''
** [[Prototype/ConstantCombinator]] '''constant-combinator'''
** [[Prototype/Container]] '''container'''
*** [[Prototype/LogisticContainer]] '''logistic-container'''
**** [[Prototype/InfinityContainer]] '''infinity-container'''
** [[Prototype/CraftingMachine]] <abstract>
*** [[Prototype/AssemblingMachine]] '''assembling-machine'''
**** [[Prototype/RocketSilo]] '''rocket-silo'''
*** [[Prototype/Furnace]] '''furnace'''
** [[Prototype/ElectricEnergyInterface]] '''electric-energy-interface'''
** [[Prototype/ElectricPole]] '''electric-pole'''
** [[Prototype/EnemySpawner]] '''unit-spawner'''
** [[Prototype/Fish]] '''fish'''
** [[Prototype/FlyingRobot]] <abstract>
*** [[Prototype/CombatRobot]] '''combat-robot'''
*** [[Prototype/RobotWithLogisticInterface]] <abstract>
**** [[Prototype/ConstructionRobot]] '''construction-robot'''
**** [[Prototype/LogisticRobot]] '''logistic-robot'''
** [[Prototype/Gate]] '''gate'''
** [[Prototype/Generator]] '''generator'''
** [[Prototype/HeatInterface]] '''heat-interface'''
** [[Prototype/HeatPipe]] '''heat-pipe'''
** [[Prototype/Inserter]] '''inserter'''
** [[Prototype/Lab]] '''lab'''
** [[Prototype/Lamp]] '''lamp'''
** [[Prototype/LandMine]] '''land-mine'''
** [[Prototype/Market]] '''market'''
** [[Prototype/MiningDrill]] '''mining-drill'''
** [[Prototype/OffshorePump]] '''offshore-pump'''
** [[Prototype/Pipe]] '''pipe'''
*** [[Prototype/InfinityPipe]] '''infinity-pipe'''
** [[Prototype/PipeToGround]] '''pipe-to-ground'''
** [[Prototype/PlayerPort]] '''player-port'''
** [[Prototype/PowerSwitch]] '''power-switch'''
** [[Prototype/ProgrammableSpeaker]] '''programmable-speaker'''
** [[Prototype/Pump]] '''pump'''
** [[Prototype/Radar]] '''radar'''
** [[Prototype/Rail]] <abstract>
*** [[Prototype/CurvedRail]] '''curved-rail'''
*** [[Prototype/StraightRail]] '''straight-rail'''
** [[Prototype/RailSignalBase]] <abstract>
*** [[Prototype/RailChainSignal]] '''rail-chain-signal'''
*** [[Prototype/RailSignal]] '''rail-signal'''
** [[Prototype/Reactor]] '''reactor'''
** [[Prototype/Roboport]] '''roboport'''
** [[Prototype/SimpleEntity]] '''simple-entity'''
** [[Prototype/SimpleEntityWithOwner]] '''simple-entity-with-owner'''
** [[Prototype/SimpleEntityWithForce]] '''simple-entity-with-force'''
** [[Prototype/SolarPanel]] '''solar-panel'''
** [[Prototype/SpiderLeg]] '''spider-leg'''
** [[Prototype/StorageTank]] '''storage-tank'''
** [[Prototype/TrainStop]] '''train-stop'''
** [[Prototype/TransportBeltConnectable]] <abstract>
*** [[Prototype/Loader1x1]] '''loader-1x1'''
*** [[Prototype/Loader1x2]] '''loader'''
*** [[Prototype/Splitter]] '''splitter'''
*** [[Prototype/TransportBelt]] '''transport-belt'''
*** [[Prototype/UndergroundBelt]] '''underground-belt'''
** [[Prototype/Tree]] '''tree'''
** [[Prototype/Turret]] '''turret'''
*** [[Prototype/AmmoTurret]] '''ammo-turret'''
*** [[Prototype/ElectricTurret]] '''electric-turret'''
*** [[Prototype/FluidTurret]] '''fluid-turret'''
** [[Prototype/Unit]] '''unit'''
** [[Prototype/Vehicle]] <abstract>
*** [[Prototype/Car]] '''car'''
*** [[Prototype/RollingStock]] <abstract>
**** [[Prototype/ArtilleryWagon]] '''artillery-wagon'''
**** [[Prototype/CargoWagon]] '''cargo-wagon'''
**** [[Prototype/FluidWagon]] '''fluid-wagon'''
**** [[Prototype/Locomotive]] '''locomotive'''
*** [[Prototype/SpiderVehicle]] '''spider-vehicle'''
** [[Prototype/Wall]] '''wall'''
* [[Prototype/Explosion]] '''explosion'''
** [[Prototype/FlameThrowerExplosion]] '''flame-thrower-explosion'''
* [[Prototype/FireFlame]] '''fire'''
* [[Prototype/FluidStream]] '''stream'''
* [[Prototype/FlyingText]] '''flying-text'''
* [[Prototype/HighlightBoxEntity]] '''highlight-box'''
* [[Prototype/ItemEntity]] '''item-entity'''
* [[Prototype/ItemRequestProxy]] '''item-request-proxy'''
* [[Prototype/LegacyDecorative]] '''decorative''' (for migration, cannot be used)
* [[Prototype/ParticleSource]] '''particle-source'''
* [[Prototype/Projectile]] '''projectile'''
* [[Prototype/ResourceEntity]] '''resource'''
* [[Prototype/RocketSiloRocket]] '''rocket-silo-rocket'''
* [[Prototype/RocketSiloRocketShadow]] '''rocket-silo-rocket-shadow'''
* [[Prototype/Smoke]] <abstract>
** [[Prototype/SimpleSmoke]] '''smoke''' (for migration, cannot be used)
** [[Prototype/SmokeWithTrigger]] '''smoke-with-trigger'''
* [[Prototype/SpeechBubble]] '''speech-bubble'''
* [[Prototype/Sticker]] '''sticker'''
* [[Prototype/TileGhost]] '''tile-ghost'''
</div>

== Mandatory properties ==
Inherits all properties from [[PrototypeBase]].

{{Prototype property|icons, icon, icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]}}
An icon is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.

The icon will be used in the editor building selection and the bonus gui.
<syntaxhighlight lang="lua">icon = "__base__/graphics/icons/wooden-chest.png"</syntaxhighlight>

== Optional properties ==

=== order ===
:''See [[PrototypeBase#order]]''
Inherited from [[PrototypeBase]].

The order string is taken from the items in <code>placeable_by</code> if they exist, or from an item that has its [[Prototype/Item#place_result|place_result]] set to this entity if it exists.

{{Prototype property|collision_box|[[Types/BoundingBox|BoundingBox]]|Empty=<nowiki>{{0, 0}, {0, 0}} means no collisions.</nowiki>|optional=true}}
Specification of the entity collision boundaries.

Empty collision box is used for smoke, projectiles, particles, explosions etc.
<syntaxhighlight lang="lua">collision_box = {{-0.4, -0.4}, {0.4, 0.4}}</syntaxhighlight>
The {0,0} coordinate in the collision box will match the entity position.

It should be near the center of the collision box, to keep correct entity drawing order. It must include the {0,0} coordinate.

Note, that for buildings, it is customary to leave 0.1 wide border between the edge of the tile and the edge of the building, this lets the player move between the building and electric poles/inserters etc.

{{Prototype property|collision_mask|[[Types/CollisionMask|CollisionMask]]|<nowiki>{"item-layer", "object-layer", "player-layer", "water-tile"}</nowiki>|optional=true}}

Two entities can collide only if they share a layer from the collision mask.

<div class="toccolours mw-collapsible mw-collapsed">
NOTE: '''Some entity types have their own default''' that differs from the above default. They are listed here:
<div class="mw-collapsible-content">
* [[Prototype/Arrow]] - no masks
* [[Prototype/ArtilleryFlare]] - no masks
* [[Prototype/ArtilleryProjectile]] - no masks
* [[Prototype/Beam]] - no masks
* [[Prototype/Car]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/Character]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/CharacterCorpse]] - no masks
* [[Prototype/Cliff]] - <code>{ "item-layer", "object-layer", "player-layer", "water-tile", "not-colliding-with-itself"}</code>
* [[Prototype/Corpse]] - no masks
* [[Prototype/DeconstructibleTileProxy]] - <code>{"ground-tile"}</code>
* [[Prototype/EntityGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/EntityParticle]] - no masks
* [[Prototype/Explosion]] - no masks
* [[Prototype/FireFlame]] - no masks
* [[Prototype/Fish]] - <code>{"ground-tile", "colliding-with-tiles-only"}</code>
* [[Prototype/FluidStream]] - no masks
* [[Prototype/FlyingRobot]] - no masks
* [[Prototype/FlyingText]] - no masks
* [[Prototype/Gate]] - <code>{"item-layer", "object-layer", "player-layer", "water-tile", "train-layer"}</code>
* [[Prototype/HeatPipe]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/HighlightBoxEntity]] - no masks
* [[Prototype/ItemEntity]] - <code>{"item-layer"}</code>
* [[Prototype/ItemRequestProxy]] - no masks
* [[Prototype/LandMine]] - <code>{"object-layer", "water-tile"}</code>
* [[Prototype/LegacyDecorative]] - <code>{"doodad-layer", "not-colliding-with-itself")</code>
* [[Prototype/Loader1x1]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Loader1x2]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/ParticleSource]] - no masks
* [[Prototype/PlayerPort]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/Projectile]] - no masks
* [[Prototype/Rail]] - <code>{"item-layer", "object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/RailSignalBase]] - <code>{"item-layer", "floor-layer"}</code>
* [[Prototype/ResourceEntity]] - <code>{"resource-layer"}</code>
* [[Prototype/RollingStock]] - <code>{"train-layer"}</code>
* [[Prototype/Smoke]] - no masks
* [[Prototype/SpeechBubble]] - no masks
* [[Prototype/Splitter]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Sticker]] - no masks
* [[Prototype/TileGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/TransportBelt]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/UndergroundBelt]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Unit]] - <code>{"player-layer", "train-layer", "not-colliding-with-itself"}</code>
* [[Prototype/Vehicle]] - <code>{"player-layer", "train-layer"}</code>
</div></div>

{{Prototype property|map_generator_bounding_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
Used instead of the collision box during map generation. Allows space entities differently during map generation, for example if the box is bigger, the entities will be placed farther apart.

{{Prototype property|selection_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
Specification of the entity selection area.
When empty the entity will have no selection area (and thus is not selectable).
<syntaxhighlight lang="lua">selection_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
The selection box is usually a little bit bigger than the collision box, for tilable entities (like buildings) it should match the tile size of the building.

{{Prototype property|drawing_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}} (selection_box is used instead)</nowiki>|optional=true}}
Specification of space needed to see the whole entity.

This is used to calculate the correct zoom and positioning in the entity info gui.
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>

{{Prototype property|sticker_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
Used to set the area of the entity that can have stickers on it, currently only used for units to specify the area where the green slow down stickers can appear.
It is optional and the collision box is used when not specified.
<syntaxhighlight lang="lua">sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>

{{Prototype property|hit_visualization_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
Where beams should hit the entity. Useful if the bounding box only covers part of the entity (e.g. feet of the character) and beams only hitting there would look weird.

{{Prototype property|trigger_target_mask|[[Types/TriggerTargetMask|TriggerTargetMask]]|optional=true}}

{{Prototype property|flags|[[Types/EntityPrototypeFlags|EntityPrototypeFlags]]|optional=true}}

{{Prototype property|minable|[[Types/MinableProperties|MinableProperties]]|not minable|optional=true}}

{{Prototype property|subgroup|[[Types/string|string]]|optional=true}}
The name of the subgroup this entity should be sorted into in the map editor building selection.

{{Prototype property|allow_copy_paste|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|selectable_in_game|[[Types/bool|bool]]|true|optional=true}}

{{Prototype property|selection_priority|[[Types/uint8|uint8]]|50|optional=true}}
The entity with the higher number is selectable before the entity with the lower number.

{{Prototype property|remove_decoratives|[[Types/string|string]]|"automatic"|optional=true}}
Either "automatic", "true" or "false". Whether this entity should remove decoratives that collide with it when this entity is built.

{{Prototype property|emissions_per_second|[[Types/double|double]]|0|optional=true}}
Amount of emissions created (positive number) or cleaned (negative number) every second by the entity.
This is passive, and it is independent concept of the emissions of machines, these are created actively depending on the power consumption.
Currently used just for trees.

<syntaxhighlight lang="lua">emissions_per_second = -0.001 -- cleaning effect of big tree</syntaxhighlight>

{{Prototype property|shooting_cursor_size|[[Types/double|double]]|optional=true}}
The cursor size used when shooting at this entity.

{{Prototype property|created_smoke|[[Types/CreateTrivialSmokeEffectItem|CreateTrivialSmokeEffectItem]]|optional=true}}
The smoke that is shown when the entity is placed. Default is using the "smoke-building" smoke.

{{Prototype property|working_sound|[[Types/WorkingSound|WorkingSound]]|optional=true}}
Will also work on entities that don't actually do work.

{{Prototype property|created_effect|[[Types/Trigger|Trigger]]|optional=true}}
The effect/trigger that happens when the entity is placed.

{{Prototype property|build_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|mined_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|mining_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|rotated_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|vehicle_impact_sound|[[Types/Sound|Sound]]|optional=true}}
When playing this sound, the volume is scaled by the speed of the vehicle when colliding with this entity.

{{Prototype property|open_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|close_sound|[[Types/Sound|Sound]]|optional=true}}

{{Prototype property|radius_visualisation_specification|[[Types/RadiusVisualisationSpecification|RadiusVisualisationSpecification]]|optional=true}}

{{Prototype property|build_base_evolution_requirement|[[Types/double|double]]|0|optional=true}}

{{Prototype property|alert_icon_shift|[[Types/vector|vector]]|optional=true}}

{{Prototype property|alert_icon_scale|[[Types/float|float]]|optional=true}}

{{Prototype property|fast_replaceable_group|[[Types/string|string]]|""|optional=true}}
This allows you to replace an entity that's already placed, with a different one in your inventory. For example, replacing a burner inserter with a fast inserter.

This is simply a string, so any string can be used here. The entity that should be replaced simply has to use the same string here.

The ones the game uses are:

"container"
"furnace"
"transport-belt"
"electric-pole"
"steam-engine"
"inserter"
"long-handed-inserter"
"pipe"
"assembling-machine"
"wall"
"loader"
"rail-signal"
"mining-drill"
"pumpjack"

{{Prototype property|next_upgrade|[[Types/string|string]]|optional=true}}
Name of the entity that will be automatically selected as the upgrade of this entity when using the [[upgrade planner]] without configuration.

This entity may not have 'not-upgradable' flag set and must be minable. This entity mining result must not contain item product with "hidden" flag set. Mining results with no item products are allowed. The entity may not be a [[Prototype/RollingStock]].<br>
The upgrade target entity needs to have the same bounding box, collision mask, and fast replaceable group as this entity. The upgrade target entity must have least 1 item that builds it that isn't hidden.

{{Prototype property|placeable_by|[[Types/ItemToPlace|ItemToPlace]] or [[Types/table|table]] of [[Types/ItemToPlace|ItemToPlace]]|optional=true}}
Item that when placed creates this entity. Determines which item is picked when "Q" (smart pipette) is used on the entity, determines which item is needed in a blueprint of this entity.

The item count specified here can't be larger than the stack size of that item.

{{Prototype property|remains_when_mined|[[Types/string|string]] or [[Types/table|table]] of [[Types/string|string]]|optional=true}}
The entity that remains when this one is mined, deconstructed or fast-replaced. The entity wont actually be spawned if it would collide with the entity that is in the process of being mined.

{{Prototype property|additional_pastable_entities|[[Types/table|table]] of [[Types/string|string]]|optional=true}}
Entities this entity prototype can be pasted on to in addition to the standard supported types.
This is used to allow copying between types that aren't compatible on the C++ code side, by allowing mods to receive the [https://lua-api.factorio.com/latest/events.html#on_entity_settings_pasted on_entity_settings_pasted] event for the given entity and do the setting pasting via script.

{{Prototype property|tile_width|[[Types/uint32|uint32]]|calculated by the collision box width rounded up.|optional=true}}
Used to determine how the center of the entity should be positioned when building (unless the offgrid [[Types/EntityPrototypeFlags|flag]] is specified).
When the tile width is odd, the center will be in the center of the tile, when it is even, the center is on the tile transition.

{{Prototype property|tile_height|[[Types/uint32|uint32]]|calculated by the collision box height rounded up.|optional=true}}

{{Prototype property|autoplace|[[Types/AutoplaceSpecification|AutoplaceSpecification]]|nil (entity is not autoplacable)|optional=true}}
Used to specify the rules for placing this entity during map generation.

{{Prototype property|map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|friendly_map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|enemy_map_color|[[Types/Color|Color]]|optional=true}}

{{Prototype property|water_reflection|[[Types/WaterReflectionDefinition|WaterReflectionDefinition]]|optional=true}}
May also be defined inside <code>graphics_set</code> instead of directly in the entity prototype. This is useful for entities that use the a <code>graphics_set</code> property to define their graphics, becausen then all graphics can be in defined one place.

== Example ==
<syntaxhighlight lang="lua">{
type = "container",
name = "wooden-chest",
icon = "__base__/graphics/icons/wooden-chest.png",
flags = {"placeable-neutral", "player-creation"},
minable = {mining_time = 1, result = "wooden-chest"},
max_health = 100,
corpse = "small-remnants",
collision_box = {{-0.35, -0.35}, {0.35, 0.35}},
fast_replaceable_group = "container",
selection_box = {{-0.5, -0.5}, {0.5, 0.5}},
inventory_size = 16,
open_sound = { filename = "__base__/sound/wooden-chest-open.ogg" },
close_sound = { filename = "__base__/sound/wooden-chest-close.ogg" },
vehicle_impact_sound = { filename = "__base__/sound/car-wood-impact.ogg", volume = 1.0 },
picture =
{
filename = "__base__/graphics/entity/wooden-chest/wooden-chest.png",
priority = "extra-high",
width = 46,
height = 33,
shift = {0.25, 0.015625}
},
circuit_wire_connection_point =
{
shadow =
{
red = {0.734375, 0.453125},
green = {0.609375, 0.515625},
},
wire =
{
red = {0.40625, 0.21875},
green = {0.40625, 0.375},
}
},
circuit_connector_sprites = get_circuit_connector_sprites({0.1875, 0.15625}, nil, 18),
circuit_wire_max_distance = 9
}</syntaxhighlight>

Types/BeamAttackParameters

2020-02-07T14:32:11Z

Jan1i3: /* source_offset */ Fix Types/vector link

Extends [[Types/BaseAttackParameters]].

== Optional properties ==
Inherits all properties from [[Types/BaseAttackParameters]].

=== source_direction_count ===
'''Type''': [[Types/uint32]]

'''Default''': 0

=== source_offset ===
'''Type''': [[Types/vector]]

Types/MapGenPreset

2019-11-22T16:51:20Z

Jan1i3: Defaul typo

== Basics ==
A map gen preset. Used in [[Prototype/MapGenPresets]].

== Mandatory properties ==

=== order ===
'''Type''': [[Types/Order]]

Specifies the ordering in the [[world generator]] gui.

== Optional properties ==

=== default ===
'''Type''': [[Types/bool]]

'''Default''': true

Whether this is the default preset. If set to true, this preset may not have any other properties besides this and order.

=== basic_settings ===
'''Type''': [[Types/table]]

All properties can be omitted, if not set they will just use the existing values.

==== terrain_segmentation ====
'''Type''': [[Types/MapGenSize]]

Shown as water frequency in the world generator GUI.

==== water ====
'''Type''': [[Types/MapGenSize]]

Shown as water size in the world generator GUI.

==== default_enable_all_autoplace_controls ====
'''Type''': [[Types/bool]]

==== autoplace_controls ====
'''Type''': [[Types/table]]

Table of [[Data.raw#autoplace-control]] name keys mapped to table values. Each table can have the following fields:
* frequency - [[Types/MapGenSize]]
* size - [[Types/MapGenSize]]
* richness - [[Types/MapGenSize]]

Example:

<syntaxhighlight lang="lua">autoplace_controls =
{
["iron-ore"] = { richness = "very-good"},
["enemy-base"] = { size = "very-big"},
["trees"] = { richness = "very-good", size = "very-big", frequency="very-low"},
["dirt"] = { size = "very-big", frequency="very-low"}
}</syntaxhighlight>

==== autoplace_settings ====
'''Type''': [[Types/table]]

==== property_expression_names ====
'''Type''': [[Types/table]]

Map of property name (e.g. "elevation") to name of noise expression that will provide it. Entries may be ommitted.

==== starting_points ====
'''Type''': [[Types/table]] of [[Types/Position]]

Array of the positions of the starting areas.

==== seed ====
'''Type''': [[Types/uint32]]

Read by the game, but not used or set in the GUI.

==== width ====
'''Type''': [[Types/uint32]]

==== height ====
'''Type''': [[Types/uint32]]

==== starting_area ====
'''Type''': [[Types/MapGenSize]]

Size of the starting area.

==== peaceful_mode ====
'''Type''': [[Types/bool]]

==== cliff_settings ====
'''Type''': [https://lua-api.factorio.com/latest/Concepts.html#CliffPlacementSettings CliffPlacementSettings]

=== advanced_settings ===
'''Type''': [[Types/table]]

All properties can be omitted, if not set they will just use the existing values.

==== pollution ====
'''Type''': [[Types/table]]

{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| diffusion_ratio || [[Types/double]] || Must be <= 0.25.
|-
| ageing || [[Types/double]] || Also known as dissipation rate. Must be >= 0.5.
|-
| enemy_attack_pollution_consumption_modifier || [[Types/double]]
|-
| min_pollution_to_damage_trees || [[Types/double]]
|-
| pollution_restored_per_tree_damage || [[Types/double]]
|-
|}

==== enemy_evolution ====
'''Type''': [[Types/table]]

{| class="wikitable"
|-
! Property name !! Type
|-
| enabled || [[Types/bool]]
|-
| time_factor || [[Types/double]]
|-
| destroy_factor || [[Types/double]]
|-
| pollution_factor || [[Types/double]]
|-
|}

==== enemy_expansion ====
'''Type''': [[Types/table]]

{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| enabled || [[Types/bool]]
|-
| max_expansion_distance || [[Types/double]]
|-
| settler_group_min_size || [[Types/double]]
|-
| settler_group_max_size || [[Types/double]]
|-
| min_expansion_cooldown || [[Types/double]] || In ticks.
|-
| max_expansion_cooldown || [[Types/double]] || In ticks.
|-
|}

==== difficulty_settings ====
'''Type''': [[Types/table]]

{| class="wikitable"
|-
! Property name !! Type !! Comment
|-
| recipe_difficulty || [[Types/uint8]] || 0 is normal, 1 is expensive
|-
| technology_difficulty || [[Types/uint8]] || 0 is normal, 1 is expensive
|-
| technology_price_multiplier || [[Types/double]]
|-
| research_queue_setting || [[Types/string]] || Either "after-victory", "always" or "never".
|-
|}