This wiki is about 0.17, the current experimental version of Factorio.

Information about 0.16, the current stable version of Factorio, can be found on stable.wiki.factorio.com.

In other languages: Русский Українська 中文

Difference between revisions of "Modding"

From Official Factorio Wiki
Jump to: navigation, search
m (substituted links to go to official lua api documentation)
(in-game mod portal has automatic dependency download)
 
(23 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__TOC__
 
 
{{Languages}}
 
{{Languages}}
[[File:Fff-18-entity-graph.jpg|400px|thumb|'Diagram of entities' (objects on the map) class inheritance structure generated by doxygen. Taken From Friday Facts #18 http://www.factorio.com/blog/post/fff-18]]
+
This page tells you how to download and install mods, and gives a quick overview of what you should keep in mind when creating a mod. For more detailed instructions on creating mods, you may view the [[Tutorial:Modding_tutorial| modding tutorial page]]. If you are looking for the modding API, check out the [http://lua-api.factorio.com/latest/ official Factorio Lua API documentation] website. If you wish to know where to install a mod which is in a zipped format, please read the instructions on the [[Application_directory|application directory]] page.
  
==Resources==
+
== Downloading & installing mods ==
This page is a starting point, but you'll often want more depth.
 
* [[Modding FAQ]] page
 
* The [http://www.factorioforums.com/forum/viewforum.php?f=25 Modding Help board] has a great community and focuses on answering modding questions
 
* The [http://lua-api.factorio.com/ Official Lua API documentation] is a great reference for understanding the Factorio functions and types in the game.
 
* You can also find inspiration from any of the mod databases listed on the [[Mods|Mods page]].
 
  
==Licensing==
+
You can download the mods from the following places:
All mods require a license since v0.11. If a mod has no license it is assumed to have a Creative Commons [http://creativecommons.org/licenses/by-nc/4.0 Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)] license.
 
  
See also
+
* [https://mods.factorio.com/ Mod portal (website)]
* [http://www.factorioforums.com/forum/viewtopic.php?f=6&t=6202&p=48971#p48968 Forum post on allowed use of base-mod content]
+
* Mod portal (in-game)
* [http://www.factorio.com/terms-of-service Factorio terms of service]
+
* [https://forums.factorio.com/viewforum.php?f=14&sid=68de6ef9ee46dcd7566653335917752b Mod subforum]
 +
 
 +
=== Mod portal (website) ===
 +
 
 +
Factorio's developers created the [https://mods.factorio.com/ mod portal (website)] to allow the players to share mods. A mod you download from the website comes in the form of a zipped file. To install the mod, you need to copy the zipped file into the mods directory located under the [[Application_directory#User_Data_directory|user data directory]] without unzipping it. You can verify whether or not you installed it correctly by viewing the mods list which you can access through the game's main menu.
 +
 
 +
=== Mod portal (in-game) ===
 +
 
 +
The mods displayed on the [https://mods.factorio.com/ mod portal (website)] should show in the in-game mod portal which you can access through the game's main menu. The differences in the in-game mod portal are that you can use it to both automatically download and install mods, and to enable or disable the mods.
 +
 
 +
=== Mod subforum ===
 +
 
 +
Some mod creators upload their mods to the official [https://forums.factorio.com/viewforum.php?f=14&sid=68de6ef9ee46dcd7566653335917752b mod subforum] to showcase their work without submitting to the mod portal or to get feedbacks from the community on their mods before updating or sending them to the mod portal. An uploaded mod should show as an attachment.  Occasionally, a mod you download from the subforum comes in the form of a zipped file. You need to copy it into the mods directory located under the [[Application_directory#User_Data_directory|user data directory]] to install it — you do not have to unzip it. You can verify whether or not you installed it correctly by viewing the mods list which you can access through the game's main menu.
 +
 
 +
=== Dependencies ===
 +
 
 +
Many mods use Factorio's base mod as their only dependency which you do not have to install separately. However, some mods may require you to install other mods for them to work and can also make suggestions for you to install other mods for them to extend their functionality.
 +
 
 +
==== Required dependency ====
 +
 
 +
When a mod you installed requires you to install another mod for it to work, the other mod, in this case, is a required dependency. The in-game mod portal automatically downloads required dependencies when downloading any mod.
 +
 
 +
==== Optional dependency ====
 +
 
 +
When a mod makes a suggestion to install another mod, but if it does not need that other mod for it to work, the other mod, in this case, is an optional dependency. You can install the optional dependencies which extend the functionality of a mod to enhance your gaming experience with the mod.
 +
 
 +
== Creating mods ==
 +
: ''See also: [[Tutorial:Modding]]''
 +
 
 +
=== API documentation ===
 +
 
 +
* [[Prototype definitions|Prototype documentation]] — What prototypes can be added to the game, and what are their properties
 +
* [http://lua-api.Factorio.com/latest Documentation of the runtime API] — Hook into events and change the world around the player.
 +
* [https://github.com/wube/factorio-data Factorio data github repository] — Tracks changes of the lua prototype definitions in factorio in between releases.
 +
* [[Data.raw]] — Lists the names and types of all built-in prototypes
 +
 
 +
=== Lua scripting ===
 +
 
 +
You need to use the Lua programming language (version 5.2.1) to create any mods in Factorio. The game's mod system injects your code into the startup and to the data construction stage of the game. You can use any text editor to write the code for your mod. Well-known text editors that offer syntax highlighting for Lua are Notepad++ and Sublime Text.
 +
 
 +
Useful resources for Lua:
 +
 
 +
* [http://lua-users.org/wiki/TutorialDirectory Lua tutorial]
 +
* [https://www.lua.org/manual/5.2/ Lua reference manual]
 +
* [https://repl.it/languages/lua Lua REPL] : A Lua read-eval-print-loop, essentially a sandbox.
 +
 
 +
=== Basic structure of a mod ===
 +
 
 +
Factorio's mods are distributed in ZIP archives and contain several important files that Factorio looks for when loading mods. These files are listed below, and the required files are colored red.
 +
 
 +
* ExampleMod_0.0.1.zip
 +
** <span style="color:#FF5555">info.json</span>
 +
** control.lua
 +
** data.lua
 +
** data-updates.lua
 +
** data-final-fixes.lua
  
==Creating a scenario from a saved game (map)==
+
=== Licensing ===
An often asked question is how to make a scenario (something which can be edited in the map editor) from a map:
 
[http://www.factorioforums.com/forum/viewtopic.php?f=18&t=2844 Factorio can convert them] ([http://www.factorioforums.com/forum/viewtopic.php?f=5&t=3801&p=28289#p28289 see also this post]):
 
./bin/prod/factorio --map2scenario mapfoo
 
  
[[Console#Command_Line_Parameters|More about the client parameters]]
+
Every mod requires a license since Factorio '''v0.11'''. If a mod has no license, it is assumed to have a Creative Commons license — [http://creativecommons.org/licenses/by-nc/4.0 Attribution-Noncommercial 4.0 International (CC BY-NC 4.0)]. However, it is possible to purposely make the mod [https://choosealicense.com/licenses/unlicense/ unlicensed], to allow the code within it to be available to the public domain. The most popular distribution licenses for Factorio mods are the [https://choosealicense.com/licenses/mit/ MIT license] and the [https://choosealicense.com/licenses/gpl-3.0/ GPLv3] license.
  
==Creating scenarios with the map editor==
+
Other useful legal links include:
Another first step is also making maps with the ingame editor. That stores the map as a '''scenario''', which is just a directory on disk with some files in it. You can look into those files to get a better understanding as to what they are for, or you can read the following pages:
 
  
 +
* [http://www.factorioforums.com/forum/viewtopic.php?f=6&t=6202&p=48971#p48968 Forum post on allowed use of base-mod content]
 +
* [http://www.factorio.com/terms-of-service Factorio terms of service]
 +
* [https://choosealicense.com/licenses/ Choose a license]
  
 
== See also ==
 
== See also ==
* Tutorial: [http://www.factorioforums.com/forum/viewtopic.php?f=15&t=8613 Create graphics for your mod...], how to generate sprite maps
+
* [[:Category:Technical]] — Documentation of technical formats and API's not related to modding
* [[Modding/Overview|Modding overview]]
 
* [[Script interfaces]]
 
* [[Migration scripts]]
 
* [[Modding FAQ]]
 
* [[Modding Tutorial]]
 
* [http://lua-api.factorio.com/latest/ Official Factorio lua API documentation]
 

Latest revision as of 09:02, 31 March 2019

This page tells you how to download and install mods, and gives a quick overview of what you should keep in mind when creating a mod. For more detailed instructions on creating mods, you may view the modding tutorial page. If you are looking for the modding API, check out the official Factorio Lua API documentation website. If you wish to know where to install a mod which is in a zipped format, please read the instructions on the application directory page.

Downloading & installing mods

You can download the mods from the following places:

Mod portal (website)

Factorio's developers created the mod portal (website) to allow the players to share mods. A mod you download from the website comes in the form of a zipped file. To install the mod, you need to copy the zipped file into the mods directory located under the user data directory without unzipping it. You can verify whether or not you installed it correctly by viewing the mods list which you can access through the game's main menu.

Mod portal (in-game)

The mods displayed on the mod portal (website) should show in the in-game mod portal which you can access through the game's main menu. The differences in the in-game mod portal are that you can use it to both automatically download and install mods, and to enable or disable the mods.

Mod subforum

Some mod creators upload their mods to the official mod subforum to showcase their work without submitting to the mod portal or to get feedbacks from the community on their mods before updating or sending them to the mod portal. An uploaded mod should show as an attachment. Occasionally, a mod you download from the subforum comes in the form of a zipped file. You need to copy it into the mods directory located under the user data directory to install it — you do not have to unzip it. You can verify whether or not you installed it correctly by viewing the mods list which you can access through the game's main menu.

Dependencies

Many mods use Factorio's base mod as their only dependency which you do not have to install separately. However, some mods may require you to install other mods for them to work and can also make suggestions for you to install other mods for them to extend their functionality.

Required dependency

When a mod you installed requires you to install another mod for it to work, the other mod, in this case, is a required dependency. The in-game mod portal automatically downloads required dependencies when downloading any mod.

Optional dependency

When a mod makes a suggestion to install another mod, but if it does not need that other mod for it to work, the other mod, in this case, is an optional dependency. You can install the optional dependencies which extend the functionality of a mod to enhance your gaming experience with the mod.

Creating mods

See also: Tutorial:Modding

API documentation

Lua scripting

You need to use the Lua programming language (version 5.2.1) to create any mods in Factorio. The game's mod system injects your code into the startup and to the data construction stage of the game. You can use any text editor to write the code for your mod. Well-known text editors that offer syntax highlighting for Lua are Notepad++ and Sublime Text.

Useful resources for Lua:

Basic structure of a mod

Factorio's mods are distributed in ZIP archives and contain several important files that Factorio looks for when loading mods. These files are listed below, and the required files are colored red.

  • ExampleMod_0.0.1.zip
    • info.json
    • control.lua
    • data.lua
    • data-updates.lua
    • data-final-fixes.lua

Licensing

Every mod requires a license since Factorio v0.11. If a mod has no license, it is assumed to have a Creative Commons license — Attribution-Noncommercial 4.0 International (CC BY-NC 4.0). However, it is possible to purposely make the mod unlicensed, to allow the code within it to be available to the public domain. The most popular distribution licenses for Factorio mods are the MIT license and the GPLv3 license.

Other useful legal links include:

See also

  • Category:Technical — Documentation of technical formats and API's not related to modding