Official Factorio Wiki - User contributions [en]

User:Sparr/Core Libraries

2020-08-27T19:07:41Z

Sparr: Initial page creation

The factorio core data includes a collection of lua libraries that are used as part of the core and base game definitions. These libraries can be used when writing new mods.

The latest version of these libraries are visible in [https://github.com/wube/factorio-data/tree/master/core/lualib the Factorio Data git repository].

Usage example (for most libraries):

local lib_name = require("lib-name")
lib_name.some_method(...

== autoplace_utils.lua ==
Helper function(s) for building [https://lua-api.factorio.com/latest/Concepts.html#AutoplaceSpecification autoplace specifications]

== biome-visualization-utils.lua ==
??

== bonus-gui-ordering.lua ==
Lookup table for GUI ordering of effect bonuses

== builder.lua ==
Class for creating entities repeatedly on a timer with a defined set of positions

== camera.lua ==
Class for managing automatic camera zooming and panning

== circuit-connector-generated-definitions.lua <br />circuit-connector-sprites.lua ==
Used to generate definitions for circuit connectors on various entities

== crash-site.lua ==
Produces the start-of-game crash site entities

== dataloader.lua ==
Initializes data and defines data.extend() for use in the data stage

== event_handler.lua ==
Manages remote interfaces and event handlers for multiple libraries in the same mod

== flying_tags.lua ==
Creates flying text entities that follow another entity

== kill-score.lua ==
Defines scoring values for kills, relative to production-score.lua

== math2d.lua ==
Helper functions for manipulating and operating on 2D vectors and areas

== math3d.lua ==
Helper functions for operating on 2D, 3D, and 4D vectors

== mod-gui.lua ==
Attempt to standardize abstractions of access to player.gui.left and player.gui.top

== noise/expression-to-ascii-math.lua ==
??

== noise.lua ==
Helper functions for manipulating and operating on [[Types/NoiseExpression|noise expressions]]

== production-score.lua ==
Calculate score value of items produced based on their ingredients

== resource-autoplace.lua ==
Turns resource patch distribution descriptions into [https://lua-api.factorio.com/latest/Concepts.html#AutoplaceSpecification autoplace specifications]

== silo-script.lua ==
Handles tracking of rocket launches

== story.lua <br />story-skeleton.lua ==
Helpers for building a "story" like the Compilatron tutorial

== util.lua ==
Many miscellaneous helper functions for dealing with a wide range of things

Prototype/MapGenPresets

2019-04-20T20:28:54Z

Sparr: remove ambiguous `default`

== Basics ==
Prototype type: '''map-gen-presets'''

The available map gen presets.

== Mandatory properties ==

=== type ===
'''Type''': [[Types/string]]

Must be "map-gen-presets".

=== name ===
'''Type''': [[Types/string]]

Name of the map-gen-presets. Must be "default" since only one instances of this prototype can be defined.

=== the name of a preset ===
'''Type''': [[Types/MapGenPreset]]

Example:

<syntaxhighlight lang="lua">somepreset =
{
default = true,
order = "a"
},</syntaxhighlight>

File talk:4to4 balancer throughput limit demo.gif

2019-04-13T17:56:52Z

Sparr: /* Could demonstrate better */ new section

== Could demonstrate better ==

This illustration does not make the bottleneck obvious. It would be better if the two input belts were saturated and only moving at half speed, and the two output belts half-full. [[User:Sparr|Sparr]] ([[User talk:Sparr|talk]]) 17:56, 13 April 2019 (UTC)

Scenario system

2018-04-20T17:30:58Z

Sparr: /* Installing scenarios */

{{Languages}}

The scenario system allows save-based mods to be created, so that installing mods separately is not necessary. This allows for server side scripting, or to provide a separate objective than the vanilla freeplay (which is actually a scenario, just like the [[campaign]]).

== Creation ==

Creation of a scenario starts in the world editor. The world editor allows an author to save a world that they have created as a scenario. This allows players to add special scripting to the scenario.

There are two ways to create a scenario:

* Running Factorio with the --map2scenario [[Console#Command_Line_Parameters|runtime flag]], which allows specifying a save to transform into a scenario. It is possible to turn a scenario back into a normal save with the --scenario2map runtime flag.
* Via the [[Map editor]].

== Differences between scenarios, saves, and mods ==

There are a few differences between a scenario, a save, and a mod. In a way, a scenario takes parts from both.

* Scenarios, unlike mods, cannot add anything to the game. The only type of scripting allowed in a scenario is scripting that would occur in control.Lua.
* Scenarios generate the exact same world every time when created by the world editor.
* Scenarios do not need to be installed client side, unlike mods. This allows servers to implement small changes to gameplay on their end, such as displaying a MOTD to joining players.
* Scenarios, unlike normal saves, are stored in a different folder.
* Scenarios' maps cannot be extracted directly, the game must be used to convert the scenario back into a save.
* Scenarios can be used to create a bit of a story, as the campaign does.

== Limitations of Scenarios ==

* Currently, scenarios cannot be uploaded to the official mod portal, they must be shared on other community websites.
* Scenarios cannot add anything to the game (Namely, they may not make calls to data:extend()).
* Scenarios count as mods for the purpose of isolating [[achievements]].

== Playing a scenario ==

There are several scenarios included into the game by default. To play a scenario, click Play->Scenarios, and choose either a user scenario, or a scenario from the base game. The Freeplay scenario is the same as the basic game, where the objective is to launch a rocket.

Upon choosing a scenario to play and saving the game, a normal save will be created that encompasses the map itself, and the control.Lua scripting that was provided by the scenario. This can be removed by deleting the script.dat and control.Lua files from the save, turning it into a normal save. Do this at your own risk, as it may break the save depending on how intertwined the scenario is with the save.

== Installing scenarios ==

Scenarios made by other players can be installed into a folder called scenarios in the player's [[application directory|user data directory]]. It can then be played from the scenarios menu.

== See also ==

* [[Campaign]]
* [[Map editor]]
* [[World generator]]

Scenario system

2018-04-20T17:30:30Z

Sparr: /* Installing scenarios */

{{Languages}}

The scenario system allows save-based mods to be created, so that installing mods separately is not necessary. This allows for server side scripting, or to provide a separate objective than the vanilla freeplay (which is actually a scenario, just like the [[campaign]]).

== Creation ==

Creation of a scenario starts in the world editor. The world editor allows an author to save a world that they have created as a scenario. This allows players to add special scripting to the scenario.

There are two ways to create a scenario:

* Running Factorio with the --map2scenario [[Console#Command_Line_Parameters|runtime flag]], which allows specifying a save to transform into a scenario. It is possible to turn a scenario back into a normal save with the --scenario2map runtime flag.
* Via the [[Map editor]].

== Differences between scenarios, saves, and mods ==

There are a few differences between a scenario, a save, and a mod. In a way, a scenario takes parts from both.

* Scenarios, unlike mods, cannot add anything to the game. The only type of scripting allowed in a scenario is scripting that would occur in control.Lua.
* Scenarios generate the exact same world every time when created by the world editor.
* Scenarios do not need to be installed client side, unlike mods. This allows servers to implement small changes to gameplay on their end, such as displaying a MOTD to joining players.
* Scenarios, unlike normal saves, are stored in a different folder.
* Scenarios' maps cannot be extracted directly, the game must be used to convert the scenario back into a save.
* Scenarios can be used to create a bit of a story, as the campaign does.

== Limitations of Scenarios ==

* Currently, scenarios cannot be uploaded to the official mod portal, they must be shared on other community websites.
* Scenarios cannot add anything to the game (Namely, they may not make calls to data:extend()).
* Scenarios count as mods for the purpose of isolating [[achievements]].

== Playing a scenario ==

There are several scenarios included into the game by default. To play a scenario, click Play->Scenarios, and choose either a user scenario, or a scenario from the base game. The Freeplay scenario is the same as the basic game, where the objective is to launch a rocket.

Upon choosing a scenario to play and saving the game, a normal save will be created that encompasses the map itself, and the control.Lua scripting that was provided by the scenario. This can be removed by deleting the script.dat and control.Lua files from the save, turning it into a normal save. Do this at your own risk, as it may break the save depending on how intertwined the scenario is with the save.

== Installing scenarios ==

Scenarios made by other players can be installed into a folder called scenarios in the player's [[user data directory]]. It can then be played from the scenarios menu.

== See also ==

* [[Campaign]]
* [[Map editor]]
* [[World generator]]

Game-tick

2017-05-18T16:47:53Z

Sparr:

{{Languages}}
A game-tick (or just "tick") is 1/60 of a [[Game-second]].

Everything in Factorio is calculated with that base. For example the speed of anything is internally calculated in [[Tile]]/tick.

The real-world duration of a game-tick depends on the speed of your computer, and is at least 1/60th of a second (0,01667 seconds). A tick can last longer when the game stops (say, to autosave) or if the framerate drops below 60FPS.

=== What is done during one tick? ===

[https://www.factorio.com/blog/post/fff-70 This FFF-article] explains what the game engine calculates on every tick.

== See also ==

* [[Time]]
* [http://lua-api.factorio.com/latest/LuaGameScript.html].
* [[Game-second]]
* [[Game-day]]
* [[Units]]

Tutorial:Modding tutorial/Gangsir

2017-05-15T20:39:05Z

Sparr: elaborated on various details

This is a modding tutorial for Factorio version 0.15. 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 created for version 0.15, 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, position in the player table, etc. All players have characters, but no characters have players within them.
; Prototype : A prototype describes a kind of entity, a bit like a template. It defines stats, what the entity actually is, etc. A prototype is used to create an entity, and many functionally identical entities 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.
; Recipe : This is a data structure a bit like a prototype that defines a recipe for the internal crafting engine. A '''technology''' follows a similar setup.

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. 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 at their [http://lua-api.factorio.com/latest/ API site.] Get used to using this site, as it will become a frequent visit you will make while you develop mods. It contains information on [http://lua-api.factorio.com/latest/Classes.html Factorio's classes], information on [http://lua-api.factorio.com/latest/Concepts.html concepts], and information on [http://lua-api.factorio.com/latest/events.html events] that you can hook into. You will need to check this site often, so the author recommends bookmarking it. In addition to this site, 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, and Notepad++ are all viable candidates. This author prefers Emacs, but it does not make a difference in the mod itself.

== How Factorio loads mods ==

=== The data stage ===

When Factorio first initializes, it initializes part of itself, then starts looking for mods. 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 two kinds of dependencies. There are required dependencies, and optional dependencies. 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.

This is the most restricted part of the Factorio init, there's not much you can do here other than declare prototypes for technologies and entities. Stuff 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>. This file is executed, then each mod's <code>data-updates.lua</code>, and finally each mod's <code>data-final-fixes.lua</code>. 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.

=== Migrations ===

[http://lua-api.factorio.com/latest/Migrations.html Migrations] are scripts that are used to "fix" a save after a mod updates. Whenever prototypes change within a mod, migrations must be setup to correct 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 making changes to prototypes that effect prototype name, type, recipe, or technology. These things cannot be dynamically changed, and resetting techs or recipes may be necessary. Try to avoid these changes after shipping the mod out to the public. Try to come up with a finalized version of the prototype 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.

=== Control ===

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. Because this 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 [http://lua-api.factorio.com/latest/Data-Lifecycle.html data life cycle] page on the API site provides the best overview.'''

=== Runtime ===

At this stage, the mod is setup, and the save is running. Access to all tables provided by the game can be done inside of event handlers. (More on those below.)

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

Over time, the community has settled on some conventions for how a mod's directory structure should look. Following these to a T is not necessary, but can simplify things and make discussing mod bugs and improvements with other developers easier. More on directory structure below.

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

Like this tutorial mentioned earlier, there is a somewhat community standard around for how a mod is laid out. This, combined with how the game expects mods to be laid out, limits us slightly. To start out, create a folder in your [[Application directory|user data directory]]/mods folder. This folder must have a specific name, <code>FireArmor_0.1.0</code>. When you're finished, the mod directory should look like this:

* (user data directory, sometimes called .factorio)
** mods
*** FireArmor_0.1.0

Then, inside FireArmor_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
*** FireArmor_0.1.0
**** data.lua
**** info.json

=== The info.json file ===

Then, inside info.json, copy and paste the following into it:

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

To explain each field:

; 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 number. Some mods start at 0.0.1 or 0.1.0, while others follow Factorio versions and start at 0.15.0 (for Factorio version 0.15.X)
; 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.
; contact : Put contact info here, so someone can find you in the event of a problem.
; homepage : The homepage of your mod, put a website here if you have one for the mod. Not required.
; factorio_version : This tells the game what version the mod is for, this must match the version you're developing the mod for, 0.15 in this case.
; dependencies : Any dependencies of your mod. Some form of "base" should always be here, so base gets loaded first.
; 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("prototypes.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 in prototypes, which we're about to create. Create a folder in FireArmor_0.1.0 called <code>prototypes</code>, then inside prototypes, create a file called <code>item.lua</code>. Your mod directory should now match [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/cf505cf536e136bccef3d675bf2fc5648c659d97 this github snapshot].

Notice how our earlier require used the folder and file name in it?

=== 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 copying an existing definition from one of the default lua files provided with an install of Factorio, and the short way just uses a lua function to copy and modify a 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"])

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

At this point, the mod looks like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/2fc7dc944f5d523216762793f7c1bd31c6792b40 this].

=== More on data.raw ===

When Factorio initializes, all prototypes are put into a table called data.raw. This table holds all types, and within those types, individual entities. 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. For example, the player's prototype would be:

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

Because the player is ''the'' player, his type matches his name. You could define a new type of player with a mod. You can see all the prototype fields for an entity in it's long declaration in the Factorio install, at (Install)/data/base/prototypes.

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, 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 must be in data-final-fixes.lua or data-updates.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 [http://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 modified 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 periodically create fire on the ground as we walk with the armor on. The event we're going to use is called on_tick, since we want the fire to be periodically created.

In our mod folder, create a file called <code>control.lua</code>. The game will automatically execute this file, so requiring it in data.lua 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_tick},
function (e)
if e.tick % 60 == 0 then --common trick to reduce how often this runs, we don't want it running every tick, just 1/second
for index,player in pairs(game.players) do --loop through all players on the server
if player.get_inventory(defines.inventory.player_armor).get_item_count("fire-armor") >= 1 then --if they're wearing our armor
game.surfaces[1].create_entity{name="fire-flame",position=player.position, force="neutral"} --create the fire where they're standing
end
end
end
end
)

</pre>

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

At this point, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial/tree/26b75c799834b9a8323d500af11b0233b824d002 this].

=== 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>config.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 config.cfg, 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.

Finally, the mod will look like [https://github.com/TheRealGangsir/FactorioModdingTutorial this].

== 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: __FireArmor__/data.lua:1:__FireArmor__/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 FireArmor::on_tick (ID 0)
__FireArmor__/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].position)
</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 cause a crash. Instead, it'll just not work. The modder is attempting to print a table. [http://lua-api.factorio.com/latest/Concepts.html#Position player.position] is a table of two values, x and y. Trying to print it will just print the memory address of the table.

=== 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 FireArmor::on_tick (ID 0)
Unknown entity name: fire-flam
stack traceback:
__FireArmor__/control.lua:6: in function <__FireArmor__/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 6 of control.lua, inside of an on_tick 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:106: Map tick at moment of crash: 432029
696.148 Error Util.cpp:76: 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.
</pre>

== Extended learning ==

One of the best ways to learn how to mod beyond this is to look at other mods. As all mods can be opened and looked at, 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 ==

* [[Mods]]
* [[Modding overview]]
* [[Modding FAQ]]

Factorio:Wiki rules

2017-05-09T22:56:36Z

Sparr: link to Editor noticeboard

{{Languages}}

Below are the community guidelines for the Official Factorio Wiki. Infringing upon any of these rules will result in either a warning or a temporary/permanent ban, depending on the circumstances. These rules are not final, and are subject to change. Additionally, all admins hold the right to enforce as they see fit, even if the rule they enforce is not specifically enumerated here.

=== Language ===

* The default language is American English, however English pages may also use European English. All pages must have an English version, and should be translated English -> Other. Use of country-specific slang must be avoided, except for localization reasons.
* Any other language has no right to obtain a page name which collides with English.
* No other language has the right to use a page name which means the same or something different in another language.
* Language pages when translated should use the English name with the language code appended to the end of the name. For example, "Transport belt" when translated to German should be named "Transport belt/de".

=== Typo control ===

* Please use the "Show preview" button to view your changes before saving them, to allow yourself to catch incorrect links and typos, and improper formatting. While creating multiple edits to the same page is allowed, it creates clutter on the recent changes screen.
* Please correct all typos found, even if changing the sentence layout is necessary. Comprehension is important.
* Run a spell check of the article to catch spelling errors.

=== Conduct ===

* Be respectful to all editors, and readers. '''All forms of hate are not tolerated''', and will result in a warning and ban.
* '''All forms of vandalism and spam are not tolerated''', and violators will be banned without question.
* Do not edit-war. If a user overwrites your change and you disagree, do not edit the page back and forth, discuss it on the talk page of the page in question. In instances of edit warring, the oldest version is preferred until a decision is reached.
* This ties into the above rule, but assume good faith. If a wiki editor makes a mistake due to human error, the fact that they are new to the community, or any other honest reason, fellow wiki community members must assume good faith. Rather than insulting, berating, or lashing out at the editor, community members should approach situations like these with a helpful and understanding attitude.
* Wiki talk pages are for discussion of their respective page '''only'''. Please keep all discussion of in-game mechanics to the forums or subreddit, the links to which are in the sidebar. An article's talk page is intended for discussion or questions regarding the article's content. It is not a forum for casual discussion. Game suggestions, personal stories, shout-outs, etc. will be removed.
* Similarly, self/other promotional content is forbidden unless it is for ''specific examples and educational purposes''. Edits made that simply show off or enumerate user creations will be removed.
* When making comments or asking questions on a talk page, be sure to sign the end with four tildes (<nowiki>~~~~</nowiki>)
* Always remain civil during discussions.
* While the Wiki can be easily reverted in the event of a mistake, please try to avoid creating work for others.
* Registered users are expected to use a single account for all editing under most circumstances. The use of more than one account by a single individual is known as "sockpuppeting", and is a very high offense. A second account can be used in certain rare circumstances by longtime established, trusted users. Some valid reasons to use a second account may include those below. In those cases, '''it must be made absolutely clear that the accounts are operated by the same individual.'''
** Technical testing
** Bot (automated) accounts
** Administrators who want to use non-admin accounts in less secure editing situations.
* Refrain from using profanity unless it is used within a direct quotation. Preferably, censor the curse with stars.
* Refrain from editing other users' user pages, unless it is to remove broken links.

=== Page layout guidelines and creation of new pages ===

* Typically, a page will start with a short intro, then the content of the page, a history section, and a "see also" section. Please follow this when creating content pages. Categories should be used sparingly.
* Please use sane formatting, and do not Capitalize Words Like This, or L I K E T H I S.
* Do not overuse '''bold''', ''italics'', or <span style="color:#00FF00">colorful text.</span> This detracts from the effect of said text when it is actually necessary.
* If possible, clean white-space from the ends of lines/pages. Many editors can do this for you. Emacs, Notepad++, Sublime Text, and Vim are recommended. This reduces the size of the page.
* Avoid creating unnecessary pages. If the info you are trying to add is related to an entity in-game, please place the info on that entity's page, and so on and so forth.
* See the [[Factorio:Editor noticeboard|Editor noticeboard]] for guidelines on whether the wiki is currently targeting the stable or experimental version of the game.
* [[Upcoming features]] should be referenced with a link to a comment or image posted by a member of Factorio's development staff.
* Mod related documentation is not to be hosted on this wiki. The Official Factorio Wiki is meant for documentation of the base game only. Instead, users looking for documentation or developers looking to provide documentation should do so on their mod's entry in the mod portal, or bundle the documentation with the source code of the mod. ''This wiki does not document nor enumerate mods.''
* Edit in an “encyclopedia” style, avoiding use of the first person or any personal bias. Avoid words like I, me, you, etc.
* Do not create circular links, I.e. do not link a page to itself. While this doesn't do anything, it adds noise to the page that editors have to ignore.
* If making a comment to other editors is necessary, place the comment in comment delimiters, <nowiki></nowiki> so it cannot be seen by users. This is only necessary to explain the page's specific formatting, such as seen on [[News]].
* Work in progress pages '''must''' be created in the author's userspace, and preferably an admin should be asked before merging into the greater Wiki. All WIP pages made outside the userspace will be moved into the author's space.

=== The History section ===

* This Wiki uses a history section on all content pages to track when entities/items are changed in the game. To do this, the Wiki uses the [[Template:History|history]] template, which provided automatic formatting and version linking.
* Bugs and bug fixes must not be placed in the update history section of a page, except for very significant instances. Instead, please document bugs in the bug sections of the official forums. However, bug fixes may be documented on [[Version history]] pages.
* While a history section is not required for information pages such as [[Railway]], all content pages concerning entities or mechanics of the game should have a history, taken from the changelog file provided with a standard Factorio install. The <nowiki>{{history}}</nowiki> template will automatically link to the relevant page in [[Version history]].
* Trivia and general facts are allowed, as long as it does not contain personal opinion and is not conjecture.

=== Media ===

* When possible, avoid putting important text in images, as it is not search-able, and makes finding that info harder.
* When uploading an image, please use a descriptive, unique name, and fill out the description box. Images given a non-descriptive name will be renamed.
* When uploading an updated version of an image, use the "upload a new version of this image" link found on the old file's page. This ensures that all old instances are updated automatically.
* Please mark any duplicated files for deletion with the <nowiki>{{delete}}</nowiki> template. If approved, an admin will delete them. Requests for pages in the requesting user's namespace are always granted.
* If uploading images that are not of Factorio, please ensure you hold rights to upload the image. We don't want to get DMCA requests.
* Please ensure that the image you are uploading is of good quality. Use the PNG filetype when possible.
* See the section [[#Pictures|below]] for more info on uploading images.

=== Templates ===

* Templates are to be used for formatting/common text on many pages. Do not create templates for only a few pages, except for special circumstances.
* Templates should include <nowiki>{{documentation}}</nowiki> inside of noinclude tags, and should have a /doc sub-page to describe the use of the template.
* Avoid making many sequential edits to a commonly used template. This creates strain on Wube's servers to update across all the pages. Preform edits to those templates with a single edit only. If you need to edit a protected template, please contact an admin, as these templates are especially heavily used.
* Templates should be light, contain little content, and have descriptive names.
* Templates must be created within the Template namespace. Please read up on this if you don't know what this means.

=== Page protection ===

* Typically, pages with high amounts of transclusions/importance will be protected, to both protect against vandalism, and to protect the servers from load caused by edits to these pages.
* If an editor needs to make a change to one of these protected pages, please contact an admin.
* If you encounter a page that you feel should/should not be protected, please contact an admin and explain your reasoning.
* We do not protect userspace pages, nor tutorials, as it is unfriendly to those who seek to fix mistakes.

== Pictures ==

=== Picture formats ===

* (100 - 200) x (100-300) px
: For flowing with the text, pictures which explain the text, the browser can embed this into it's own rendering. You can put them left or right, the text should flow around.
* (400 - 600) x (100 - 600) px
: Something like a banner. A big picture which stays alone in its line. You may put simply a ":" in front of it to indent the picture and keep it away from flowing text.
* 300 x 300 px
: This is especially good for gif animations. Gif animations cannot be reduced in size, because Mediawiki re-renders the picture and the result is the first frame of the gif!
* The biggest format for flowing text should be: 600x600px

To re-size an image when it's put onto a page, simply provide the size as an argument to the file:

<nowiki>[[File:example.png|200x200px]]</nowiki>

=== Making pictures out of the game ===

Do's:

* Take pictures at day! Use night or dawn only if you need to explain something that only works at night (for example, the lights).
* Turn off clouds! The shadows in GIF-animations are not useful.
* Steam/smoke is also not that useful.
* Use god mode! [http://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.set_controller]. You can move anywhere on the map and your character won't be in the picture.
* You can [http://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.speed slowdown the game] to find the right moment for the picture. Slowdown is also useful if you use Gifcam, which makes Screenshots in 30 frames/sec only.
* You can also use the peaceful mode to be not disturbed by the natives.
* You can stop the game in the right moment using SHIFT-SPACE key. That also blends the grid in.
* Learn how to use the [[Debug mode]] to add relevant information into the picture.
* Go into the highest zoom level you possibly can without missing any vital information.
* A good in-game picture should be rebuilt so that only the relevant entities/items are shown. Anything in the photo other than what you're trying to show/explain is unnecessary.

Dont's:

* Don't take pictures of clutter! The only stuff in the photo should be the stuff you're trying to show. The exception to clutter: If you're showing what a fully finished factory or setup might look like.
* Don't just take a screenshot. Try to remove all unneeded information from the picture.
* Try to make a picture without the character, except if to show something; then face the character toward it.

See http://www.factorioforums.com/forum/viewtopic.php?f=6&t=2472 for more.

== Taking Screenshots, animations and videos==

=== Taking Screenshots ===

* It's possible to take [http://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.take_screenshot Screenshots out of the game]! The [http://www.youtube.com/watch?v=9yDZM0diiYc second trailer] is made like so. See http://www.factorioforums.com/forum/viewtopic.php?f=18&t=5591
* [http://www.factorioforums.com/forum/viewtopic.php?f=18&t=5591 Calculate screenshot dimensions].

==== Optimizing the picture before upload ====

* Cut as much as possible/nice.
* Resolution should not normally be higher than 600x600 px. Use multiple photos or ask a trusted wiki user if you need a much larger photo.
* ''Do not add text to the photos'' Write any needed text outside the photo on the wiki. You cannot search text that is in a photo and users might not find what they are looking for.
* Sharpen the pictures. For the wiki it looks a lot better to sharpen the pictures once or twice.