Large guide to modding Factorio

[engineer13]

Alright so I have been checking out a lot of info on out there on the forum as well as in the wiki and I have been doing my own tests. This will be my attempt to make a very large mod to explain a large number of concepts for modding because the wiki doesn't have the best info on modding and even the best guides I have found, while they are quite good, are still lacking quite a lot. So let's get this thing started:

Chapter 1: The file system

There are a couple ways you can setup your files and folders, but I'm quite fond of one in particular so I will focus on that.

1. Create a folder in your Factorio mods directory. You can find your mods directory by going to your Factorio folder and clicking the shortcut to the mods folder.
2. Name this folder according to a special format. Let's say you wanted to name your mod foo bar mod and you were making version 1.2.3 (there needs to be 3 numbers). You would name your folder the following foo-bar-mod_1.2.3. The general format is to have your mod's name, with spaces being replaced by dashes, followed by an underscore and then the version.
3. Inside this folder (which shall now be known as your mod's folder, not mods but mod's) you will create three files: info.json, data.lua and control.lua.
4. Depending on your mod you may also want the following folders in your mod's folder: graphics, prototypes, locale and migrations (I don't really know what migrations is for).
5. Inside of the graphics folder you will want an icon folder and an entity folder (I will explain all of this stuff later).
6. Inside of the locale folder you will want an en folder (stands for english or you can have whatever language).
7. There are other assorted files and folders, but it quickly becomes highly dependent on what kind of mod you are making.

Chapter 2: info.json

As was mentioned, you have a file called info.json in your mod's folder. This file is basically just for telling Factorio (and everybody else) about your mod. Go ahead and open up the file with some kind of text editor (I prefer notepad++, but anything should work fine). Go ahead and input all this (copy and paste) into the file:

Code: Select all

{
  "name": "",
  "version": "",
  "title": "",
  "author": "",
  "description": "",
   "dependencies": [""],
}

Now let's go over this. The name line is simple enough; go ahead and input (in the quotes of course) the exact same name you gave to your mod's folder. This has to be the same in order for Factorio to accept your mod although it does need to be missing the underscore and version in other words from our previous example you would just input foo-bar-mod. Next is the version...quite obvious, just put in the version such as 1.2.3. Now we come to the title, this is where you put in what you actually call the mod for example: foo bar mod. You can input spaces and whatever, it's your name. Next is the author, soooooo you. Now we have the description, this is where you get to put a quick description about your mod. There is no particular thing you should put there so whatever you think is a good short...short description is fine. Finally we have the dependencies. If your mod relies on any other mod (even a certain version of the base mod) then this is where you put it. It follows a simple format. Let's say you needed the foo mod at at least version 0.2.0, the bar mod at exactly version 1.0.1 if it is active and the foobar mod of any version then it would look like this:

Code: Select all

"dependencies": ["foo >= 0.2.0", "? bar = 1.0.1", "foobar"]

Now you can delete some of these lines. name, author, version and title are the only required fields (unless you have dependencies). You can get rid of everything else if you want. I also want to mention that there is a homepage line that you can put in there, but I haven't messed with it and if you have a website for your mod then you probably don't need to read a guide on making a mod.

Chapter 3: Items

Alright so you probably want to make some items for you mod. Well here we can talk about the prototypes folder. The prototypes folder has to do with what are called prototypes in Factorio. https://forums.factorio.com/wiki/inde ... efinitions is a (quite incomplete) list of prototypes. Basically a prototype is something to define a list of properties about a given item/entity. Inside the prototypes folder you want to create a file named item.lua. This is the file where you will put all the descriptive code about your mod's items. Go ahead and open item.lua in your preferred text editor. Now let me explain the basic way to create an item.

First you want to place this to surround all the rest of your code:

Code: Select all

data:extend({

})

Now inside of there is where you are going to create all of your items. To create an item you use the following format:

Code: Select all

{
type = "item",
name = "foobar",
icon = "__foo-bar-mod__/graphics/icons/foobaricon.png",
flags = {"goes-to-quickbar"},
subgroup = "ammo",
stack_size = 100,
},

First off we have the type. Type will always be item for an item. When we get to entities it will be a prototype and for recipes it is recipe. It's not complex until you deal with prototypes. Name is just the name of the item. Be careful, this isn't the name that you necessarily want the player to see, this is just the name that you will use in all the rest of your code to reference this item. Also make sure you replace all spaces with dashes in the name. Icon is the path to the image that will be used to represent this item. Always start off the path with "__mod-name__" (two underscores on both sides and the name of your mod in between). This will get the path to your mod's folder for you. The rest is the path to where the image is which will hopefully be in the graphics folder. I like to make a 32x32 image, but technically you can use just about any size you fancy. I also prefer using GIMP for my image editing because it allows me to make the background invisible (unlike paint). Flags has a total of two possible values you can insert: "goes-to-quickbar" or "goes-to-main-inventory". The two different flags are pretty obvious, when you pick up an item does it go to your quickbar or your inventory? Next up we have the subgroup. I'm a little sketchy on the subgroup because there is also a group setting and it gets weird, but let me just say that I know it decides what tab in the crafting window the item falls under. If you don't choose a group/subgroup then it will just be in a new tab called "?" and you can make your own groups/subgroups. Finally we come to stack_size. This is pretty self explanatory, but basically it just decides how many of this item you can stack into a single space of your inventory. There are more options you can add so here is a quick link to the wiki https://forums.factorio.com/wiki/inde ... otype/item. Note, the wiki needs a lot of work on its modding sections. Also one main thing I managed to leave out of my above code is the place_result option. Whatever you set it equal too will be the name of the entity you get when you place the item on the ground. Quick fyi: any name of any item or entity needs to replace the spaces with dashes.

Chapter 4: Entities

Oh god. This is a big subject that I cannot cover anywhere near as well as the previous (and latter with the exception of the control.lua part) sections. First off you need to realize that every single thing that exists on the map (except the land itself which is considered tiles and will not be covered in this guide) is an entity. Every tree, building, turret, enemy and even you. An entity refers to any object that is not in an inventory (and is not a tile). Every item that won't just be like equipment or a module (basically any item that will be put on the ground at any point) needs to have an entity that it is attached to. Creating an entity can be pretty complex. It can be especially infuriating when you want to create something completely different from anything already in the game. Let's have a quick rundown of the basics that every entity needs:

1. Start by making a file called entity.lua in your prototypes folder
2. Encompass all the code in the file just like in the item.lua file with

   Code: Select all

   data:extend({
   
   })

3. Enter the type option again (this is mandatory) which I will explain more in a minute
4. Enter the name option (remember to replace spaces with dashes)
5. Enter all the other stuff

Alright so that was rather vague, but here is what I can tell you. The type option will be completely different for your entities. The type, for an entity, has to be a type of prototype. https://forums.factorio.com/wiki/inde ... efinitions was probably already linked, but this is the list of every prototype in the game currently (meaning this is every one of them you can have as your type, but you can't use the ones that say they are abstract). If you know about Minecraft modding than just understand that this is similar to choosing what block you are going to extend. If you aren't familiar with Minecraft modding than let me try to explain this to you. When you choose a prototype as your entities type that means that your entity gains all of the traits of that prototype and none of any others (except the parent prototypes, gah too much info). What this means is that you can potentially make coding later easier or harder depending on your entity and what you want it to do as well as what prototype you choose for it. Let's say that you are trying to make a car that can move quicker on tracks and slowly on land. You would want to make type = "car" because that will give you all the traits of the car (the ability for the player to enter it and for it to move and the such) and this allows you to enter a lot of easy variables right there in your entity.lua file rather than having to enter a lot more code in your control.lua file later. Also remember that whatever prototype you use has certain variables that have to be entered. For example the car type requires an animation variable, but doesn't accept a picture variable. This means that you need to make an animation for the car and a picture won't help. There is a lot more to creating entities, but I cannot cover it all here without going on for ages so just look at the wiki for more info.

Re: Chapter 4: Entities

After you pick a prototype, you should look for a similar prototype in Factorio/data/base/prototypes/entity. Then use that as a reference for the fields you need to add.

Good advice. Once you have chosen a prototype to use for you entity you will want to go to the base mod and check out the code that they used for the specific entity/prototype that you chose. Like I have been saying, looking at code from other mods (including the base mod) can really help you out with your own code.

Chapter 5: Recipes

Now create a recipe.lua file in your prototypes folder. Again surround your code with the usual. Now recipes are quite a bit easier.

Code: Select all

{
    type = "recipe",
    name = "foobar",
    enabled = "true",
    ingredients = 
    {
      {"iron-stick",100},
    },
    result = "foobar"
  },

Alright so this is an easy description. Type is simple enough, recipe. Once again name is really easy and the same as the name for the item that this recipe creates. The enabled option has two possible states, "true" and "false". This decides whether the recipe is available to be crafted or not. A good exampled (and probably the only one) for why you would initially have it disabled is for an item that needs to be researched before it can be crafted. The ingredients option leads to a table that tells what all items are required to craft this recipe. In this case we only need 100 iron sticks to craft the foobar. You can expand this by adding more items (though their format needs to be exactly the same as the iron sticks' format). To find out the name you need to use you can just take the actual name of the item in game and then replace the spaces with dashes (and always use lower case). Finally the result just tells what item is made when you complete the recipe. You can of course set it up to make multiple of the item or of other items (?). I haven't ever done that and have done no research on it, but if you are really curious then just look it up or go into the base folder and look at their recipe.lua. This is a good time to mention that you can look at the base mod as well as any other mod that anyone else has created to get some good ideas as well as just a feel for how all of this works.

Chapter 6: Technology

This is similar to recipes (it's basically just recipes with slightly different parameters). Create technology.lua in your prototypes folder and start with the normal code.

Code: Select all

{
      type = "technology",
      name = "foobartech", --lol foobar tech.  Let's learn how to *bleep* things up beyond all repair
      icon = "__foobar__/graphics/icons/foobartech.png",
      effects =
      {
        {
            type = "unlock-recipe",
            recipe = "foobar"
        },
      },
      prerequisites = {"foo", "bar"},
      unit =
      {
        count = 10,
        ingredients =
        {
          {"science-pack-1", 2},
          {"science-pack-2", 1},
        },
        time = 10
      }
  }

Alright so let's explain this quickly. Type is obvious. Name is just what you want this tech to be called in your files (not necessarily in the game). Icon is obvious. Effects allows you to choose what items are unlocked by researching this. You can add more effects in that table for more items to be unlocked. The type for the effect is always the same and the recipe just has to be the same as the name you gave that particular recipe. Prerequisites tells you what technologies you have to have already researched. The unit table allows you to choose what all science packs are required to research the tech as well as how long it will take. The ingredients is just the same as for the recipes except that you are using science packs instead of any resource. The count variable decides how many iterations you have to go through using the number of science packs that the ingredients call for. The time variable decides how long it takes a lab to go through one iteration. Again if you need any help I would recommend looking at code from other mods as that might help you out.

Chapter 7: Names/locale folder

Alright so let's move over to the locale folder you created and then into the en (or whatever language) folder. This part is extremely simple. This is where you get to place the actual names that your stuff will have in the game. There are different ways you can do this. You could just make a file called local.cfg or something similar and then put all the code in there, but I prefer a different method that is better for larger mods. Create three different files: item.cfg, entity.cfg and tech.cfg. In each one you will follow a simple format. At the top write [item-name] and then just write the item name and then the name you want the item to have in the game like this: foo-bar=foo bar. You can also, at some point, write [item-description] and then below that write the same things except that you put the wanted description instead of the wanted name. For the other files you do the same thing except you replace item with technology or entity. That's all there is to it.

Chapter 8: data.lua

Remember that data.lua that you made a while back in your mod's folder? Yeah we are just now getting to it. Technically you can put all of the info you put for your items and entities and recipes and so on into this file, but I prefer this method of breaking everything up. It makes it a lot easier to read and understand. All you have to do here is add some required stuff. Basically the only things you need to worry about including in here is all the files you put in your prototypes folder. Here is an example of what it might look like:

Code: Select all

require("prototypes.technology")
require("prototypes.entity")
require("prototypes.item")

Not exactly very difficult. If you add more files to the prototypes folder you may need to include those as well (keep in mind this is only looking for lua files). I think you also have to include migration scripts in here, but I'm not sure.

Chapter 9: Migration scripts

Alright so I know I said I don't know a lot about this stuff, but I did a little research and so I know a bit. Basically a migration script is used for when you are updating your mod and you decide to change items. Obviously there could be people who were using your mod and so their save has some of these items that you have discarded. The migration script allows you to tell Factorio to change these items in their save to one of your new items. I don't really know anything further than that. Here is what I used to discover this https://forums.factorio.com/forum/vie ... 749#p21749.

Chapter 10: control.lua and lua script

Oh dear lord help me now. This is the one section that will be even worse than the entities. Alright so let's take a look at your mod's folder. See that control.lua I had you make a long time ago? Yeah it feels like ages doesn't it? Alright let's open it up and in the process open the can of worms that it is. So this is where you get to actually make your stuff do stuff. First off make sure to write this at the top:

Code: Select all

require "util"
require "defines"

You may not use one of these or perhaps neither, but who cares they can be useful. Basically these are just a couple of libraries that open up more commands to you. Now at this point let me just tell you that I'm not going to sit here and teach you lua. There are plenty of well made guides and tutorials on that so go search for that stuff. Basically this is where you are going to combine normal lua with all the stuff that Factorio has. I'm not even going to begin trying to describe all of the commands you have so let me just refer you to the wiki (although it's absolutely terrible at explaining this stuff too) https://forums.factorio.com/wiki/inde ... Lua/Events https://forums.factorio.com/wiki/inde ... e=Lua/Game. Those should give you very very slightly decent info to get you started on what all the lua code portion of modding is all about. Like I said I'm gonna try to see if I can't update some of the stuff on the wiki because even most of the stuff it does explain is not explained well enough in my opinion.



Alright that was all I got (I do believe I covered just about everything). I do want to say that I probably made mistakes or didn't explain some stuff well enough so please let me know (I want this to be quite expansive, but the further I went on the harder that became). If you have any questions than please feel free to ask (I know I said you can look at the code of other mods and learn a lot, but you don't have to do that before you ask me a question). I would like to recommend the following tutorials because they each have their own unique uses (I'm definitely not trying to say that mine is better than either because it probably isn't, but I am saying that neither of these is in anyway perfect) https://forums.factorio.com/wiki/inde ... g_Tutorial https://forums.factorio.com/forum/vie ... f=34&t=709 (really like this one even though it is based on the wiki). I will hopefully be able to start "fixing" the wiki pretty soon so that it becomes a lot more noob friendly for learning how to mod because it is currently just a whole bunch of trial and error for figuring out how some of this stuff works. Regardless I hope you guys will now start pointing out all the flaws in my writing .

[Koub]

Stickied by Koub : I think this post deserves to be stickied. There is already a guide, but it is pretty old, and outdated. Moreover, I did find this guide helpful.
@Ssilk : If you think it should be merged with the old modding guide, it's ok for me too.
[Edit] : @Ssilk : You're right, hadn't thought about all that.

[ssilk]

This is the old thread: https://forums.factorio.com/forum/vie ... f=34&t=709

Koub: No. not merging. Think in terms of "how would I want to have it", and I won't have it so, that I need to read through all of the other thread to find an updated version. And think also of this: The thread owner has a bit more rights for his thread (he can change the topic name), than an replier, so if you do that, you need also to moderate it more. And we're only two yet.

[DaveMcW]

Re: Chapter 4: Entities

After you pick a prototype, you should look for a similar prototype in Factorio/data/base/prototypes/entity. Then use that as a reference for the fields you need to add.

[tpzker]

What version is this for? Looking for 0.12 or 0.13 modding documentation, would be helpful to know what version. The most updated I could find was 0.10. Very outdated.

[EncryptingWolf]

Nice tutorial, It's a very good intro to modding, any chance of an update

What version is this for? Looking for 0.12 or 0.13 modding documentation, would be helpful to know what version. The most updated I could find was 0.10. Very outdated.

If your just looking for dockementation, here is the official lua api: http://lua-api.factorio.com/

If you want a tuorial then here:
https://www.youtube.com/watch?v=8lPNOOVYeMU
It's a updated youtube video by klonan and it only covers till this post's chapter 8. It was made in August 2015, it works for 0.13 if you do the following:

Add to info.json:
"factorio_version": "0.13",

If you are on steam the file path has changed:

Base mod (For coding examples): C:\Program Files (x86)\Steam\steamapps\common\Factorio\data\base

Mod's folder(your mod, didn't change): %AppData%\Factorio\mods

[Marbelus]

This is incredibly informative and helpful. It will help in a mod we are creating. Thank you very much!

[Optera]

You should add information about how mods are loaded and especially how to properly use data.lua, data-updates.lua and data.final-fixes.lua
I've seen way too many mods using data-final-fixes to generate entities when they really should use dependency and data.

[meems]

If your going to sticky the OP post, can you at least update it to keep it accurate?
I'm hoping to start modding. With a >3 year old modding community I was hoping there would be a clear path already cut here. But this guide fails on its 1st step into the dark forest of code.

Anyone know a modding guide that gets at least one step without failing?

[Rseding91]

Anyone know a modding guide that gets at least one step without failing?

You're going to need to put a little more effort into it than that. If you can't get past something like a folder not existing you're never going to get anywhere with this... Just make the folder and continue with the guide.

[meems]

Code: Select all

"dependencies": ["foo >= 0.2.0", "? bar = 1.0.1", "foobar"]

What does the conspicuous and unexplained ' ? ' do?

[meems]

Anyone know a modding guide that gets at least one step without failing?

You're going to need to put a little more effort into it than that. If you can't get past something like a folder not existing you're never going to get anywhere with this... Just make the folder and continue with the guide.

I'm putting the effort in. I've created a temporary dir while I wait for the correct location of this mod folder to become known.
I don't know if the location of the mod directory has to be specific or can be anywhere.
You suggest its ok to create my own. Fine, I will try that thanks. Someone update the OP guide?

[daniel34]

Just make the folder and continue with the guide.

He is using the steam version, just making a mods folder there won't work because the mods are still stored in %appdata% and it's the shortcuts that are missing.

To find the mods folder just enter %appdata%\Factorio\mods in any explorer window.

Code: Select all

"dependencies": ["foo >= 0.2.0", "? bar = 1.0.1", "foobar"]

What does the conspicuous and unexplained ' ? ' do?

A question mark before the mod name shows an optional dependency. In the code example the mods foo and foobar are required (the mod won't work without them), bar is optional and the mod works without it. If bar is also installed it is guaranteed to be loaded before the mod.

EDIT: Adil is currently working on an updated modding tutorial for the wiki, see here for the current progress: https://wiki.factorio.com/User:Adil/Modding_tutorial

[meems]

thks Daniel, that was useful.

I note the guide says

Name this folder according to a special format. Let's say you wanted to name your mod foo bar mod and you were making version 1.2.3 (there needs to be 3 numbers). You would name your folder the following foo-bar-mod_1.2.3. The general format is to have your mod's name, with spaces being replaced by dashes, followed by an underscore and then the version

but later says

Now inside of there is where you are going to create all of your items. To create an item you use the following format:

Code: Select all

    {
    type = "item",
    name = "foobar",
    icon = "__foo-bar-mod__/graphics/icons/foobaricon.png",
    flags = {"goes-to-quickbar"},
    subgroup = "ammo",
    stack_size = 100,
    },

the icon field appears to be a file address, if so i would have expected

"__foo-bar-mod_1.2.3.__/graphics/icons/foobaricon.png "
not
"__foo-bar-mod__/graphics/icons/foobaricon.png "

Does factorio fill in the missing version numbers in the folder name?

[meems]

Tried to run factorio with the guide mod template but got this error.

I think this is the wrong way to go about learning to mod. Writing stuff from scratch just gives 100 ways to subtly fail, computers fail with the slightest of errors, and its very hard for a beginner to figure out the error.
The foolproof way to learn code is to take existing working code and mod it slightly. I will try this method.

[daniel34]

I think this is the wrong way to go about learning to mod. Writing stuff from scratch just gives 100 ways to subtly fail, computers fail with the slightest of errors, and its very hard for a beginner to figure out the error.
The foolproof way to learn code is to take existing working code and mod it slightly. I will try this method.

I agree, that's usually also advice I give and the way I learned to mod Factorio. At first look at a few (small) mods to see how the work and what parts a mod has and how they interact with each other, then take a mod you're interested in and change it, or try to add functionality.

Regarding your info.json:

• the last line before the closing } is not allowed to have a comma, all others need to have one
• dependencies can't have an empty string inside the way you did it, you could leave it empty e.g. [] but the usual convention is to define the base version there: "dependencies": ["base >= 0.14"]
• since 0.13 you also need the following line for it to work: "factorio_version" : "0.14"

the icon field appears to be a file address, if so i would have expected
"__foo-bar-mod_1.2.3.__/graphics/icons/foobaricon.png "
not
"__foo-bar-mod__/graphics/icons/foobaricon.png "

Does factorio fill in the missing version numbers in the folder name?

Yes it does, otherwise you could have lots of places in your code where the version number was used and you had to change each of them everytime you change the version number.

[meems]

thks again, that seemed to fix the prob. Factorio loaded 1 second longer b4 complaining of an error in my technology.lua
there could be a lot of work ahead down this path, but I've switched to looking at other working mods.


The 'simple Sapling' mod on the mod portal doesn't work. The resource compression one does though. Think I'll try gut it to get an empty mod template.

[Mooncat]

It would be nice if someone can update the guide so it teaches people to add prefix on their prototype names.
As the number of mods keeps increasing, the chance of having conflict between mods due to identical prototype names also increases. Adding the mod ID as the prefix to your prototype names can avoid this in an easy way.
e.g. change the name "foobar" to "foo-bar-mod_foobar"

[eradicator]

*snap*

If you're looking for an example mod Hand Crank Generator was originally written (by me :P) as an example mod, and has extensive comments on why things are done the way they are.

It demonstrates among others:

• general localization, mod settings localization, localization of dynamic hotkeys
• hotkeys
• in-game mod-settings
• basic control.lua events
• basic item/recipe/entity creation

[Jürgen Erhard]

since 0.13 you also need the following line for it to work: "factorio_version" : "0.14"

And since 0.15 it needs "0.15" there

IOW: Bitrot is eating this guide too. And, meems, there is nothing foolproof ever.