Info for Contributors

For those interested in contributing to Factorio Access, this page has some general information about how Factorio mods work, and how this mod in particular works.

This document has last been updated for Mod Version 0.12.0.

How you can contribute

Factorio Access welcomes many kinds of contributions. For example, you can join in conversations about Issues, preferably on GitHub but also on the Discord server. Discussions can include bug reports and feature suggestions and also the development timeline. We usually coordinate on the #coding-and-contributing channel on Discord.

You can also contribute to the code by proposing or selecting an issue to tackle and then submitting a pull request to our main branch about it.

We also welcome contributors to assist with keeping the mod wiki updated. You can edit wiki pages if you are logged in to GitHub.

Dev environment setup

Our normal way for us to receive your proposed code changes is via a GitHub pull request, but you can get in touch with us on Discord about alternatives. These instructions assume a default setup where you fork the mod's repository and use Visual Studio Code. Lots of setup variations are possible though, so take these instructions with a grain of salt, and ask for help with deviations, if needed.

1. Create a fork on GitHub, which gives you your own copy of the repository.
2. Replace the FactorioAccess mod folder in "%appdata%\Factorio\mods\" with a clone of your fork, so that your changes can be tested in game right away.
3. Ensure you have a somewhat up to date version of VS Code installed.
4. Open a new VS Code window, and from there open that newly created FactorioAccess folder.
5. VS Code may or may not prompt you to install some extensions, in either case install the recommended extensions. You can find recommended extensions in the "Extensions" tab, under the "Recommended" section. We generally recommend using the "Factorio Modding Toolkit (FMTK)" and "Factorio Lua API autocomplete". Meanwhile, we require using "StyLua"`so you may wish to set it up to run every time you save.
6. Save your VS Code workspace using the "Save Workspace As..." menu option, under the "File" tab. You can save it anywhere you'll remember and you should use that file to reopen your VS Code workspace whenever you want to restart working on Factorio Access. This workspace file is used to store your VS Code settings that are not shared by different developers, like folder locations.
7. Update your working branch of the repository, using either the "main" branch or the "next-update" branch. We reserve the main branch for tested and stable feature that are ready for release, while ongoing work is collected on other branches.
8. The code is now ready for editing but we recommend setting up VS Code for testing as well. If you'd like to do live debugging while still hearing what's going on, you'll need a special version of the mod launcher that doesn't have a console. You can find that linked here. It should be placed next to factorio.exe in the folder "Factorio\bin\x64\ ".
9. To get the Factorio Modding Tool Kit (FMTK) working you'll need to select your Factorio version to use for testing in VS Code. Rather than pointing to "factorio.exe", you should set it to the launcher downloaded in the previous step. This can be accomplished using CONTROL + SHIFT + P and typing in the option for "Factorio: select version".
10. Pick a save file of yours that you'd like to do your debugging on and rename it to "test.zip".
11. Back in VS Code, open up any lua file you'd like to debug, set any breakpoints you'd like, and press F5 to run it. Hopefully, you'll hear Hello Factorio like usual and be dumped into your test game.

Factorio data lifecycle

Factorio allows mods to run Lua code either during the startup of the game before the main menu loads, or during runtime after a save file loads.

The startup process includes the settings stage where mods are configured, and the prototype stage where mods define new prototypes for game content such as sound effects, input keybinds, custom buildings, and more.

The runtime stage takes place alongside normal gameplay, and allows interaction with the game world. Code execution is based on events being fired for mods to react to, with the API functionality being provided via various classes that have been defined specifically for mods.

Like other mods, Factorio Access reacts to three types of events: listened in-game events such as an entity taking damage, player input events such as a key being pressed, and scheduled events such as a function scheduled to be called once per second.

Factorio runs everything on a single main thread so that the game is deterministic, although it is highly optimized to use multiple threads for independent subtasks. The game runs with 60 game ticks per second, and multiple events can be called on the same tick.

Read more about the data lifecycle on this official documentation page.

Data structures used in Factorio Access

During runtime, the API allows you to reference game objects directly, using read and/or write permissions for their listed properties. Game objects include the surface, which is the world made up of tiles, and covered in entities. Every non-simple entity has a unit_number that is unique to itself, and a class name explaining what kind of it is and what it can do. It also has a type which is an abstract class that groups it along with similar entities. Usually doing something in the mod begins with referencing an entity or a tile. Some entities have inventories, and the slots of the inventories can be referenced in order to access the items in them.

Referencing existing game objects, including custom objects created by mods, is something done by any mod. Meanwhile, some mods like Factorio Access also need to save and read some data so that they can remember things in between events. For this purpose, mods can define custom Lua tables and save them as global variables, which persist between events but not between different game sessions. The Access mod's most extensively used custom table is global.players, where mod-related data for each player is stored separately. This table is usually referenced in the code using a variable named "pindex", which is the index number for a particular player. Note that the mod's custom global.players table is completely different from Factorio's internal table named game.players, but both tables are used extensively.

Other aspects of the runtime can be referenced as well, such as the graphics rendering system, or the remote calls system for interfacing with other mods. Read more about the runtime stage on the API page for runtime.

Most of the mod work done by the mod uses simple Lua data types, and using global data tables that are only one or two layers deep. However, as of version 0.11, the mod is also setting up more complex data structures to let it do things like audio menus in a more elegant way, but this work is still underway.

Key mod files

Standard files

The standard files for Factorio mods include the following:

• settings.lua is where mod settings are defined in an API-interfaced way. This file is not added yet for this mod but it will be.

• settings-updates.lua is where the settings of other mods are overwritten.

• data.lua is where vanilla prototypes are overwritten and mod prototypes are introduced, including sound files, keybinds, and new custom buildings.

• data-updates.lua is where the prototypes of other mods are overwritten.

• control.lua is where all runtime behavior is defined.

Lua module files

The scripts folder contains all the runtime stage code for this mod, separated into Lua modules with one file per module. All of these modules get loaded by control.lua and some of them require others as dependencies. Modules have been defined and organized according to the game features they relate to. Some notable modules are:

• fa-utils.luacontains utility functions that are used across the mod, including position and direction processing, string processing, and the like.

• building-tools.luacontains building related functions, including basic functions and advanced helper functions. It is worth noting that the mod does not (and can not?) use any of the built-in smart building features of the base game.

• graphics.lua and mouse.lua contain mod functions related to drawing things in the world, or updating GUI's, or moving the mouse pointer on the screen. If there are issues related to these features, sighted developers can start debugging here. There are other places where the mod draws stuff but those tend to be simple graphics for debugging assistance.

• localising.luacontains the mod's own helper functions for fetching localized strings that can be concatenated, which cannot be done easily with the API alone.

Config change files

The mod has a number of ".ini" files in the folder named config_changes. These files define which game settings are changed by the Factorio Access launcher during game configuration. There are multiple files to allow for existing players to only get the new changes when they update while not overwriting any customisations. If you want to change a setting between releases, it should go into a new file, that way players that are up to date with all the previous suggestions will receive the new setting. If you want to update a setting that was already changed, it should still go in a new file, and ideally that setting wold be deleted from the old file that set it. That way new players don't have to have that setting changed twice which would be annoying if they're doing it interactively. Removal of settings is the only substantial change that should be made to old files, but comments can be updated anytime. All new setting changes for a particular release can go into one new file and the first two letters of that file should start with the next alphabetical options ie. AG_whatever.ini follows AF_something_or_other.ini and BA_wow_the_two_letters_was_a_good_idea.ini follows AZ_another_non_descript_name.ini.

Locale files

As noted previously, localising.luacontains the mod's own helper functions for fetching localized strings that can be concatenated, which cannot be done easily with the API alone.

The mod has some ".cfg" files in the locale folder, where localised strings are defined and stored. Only the English locale is properly available at the moment and we have not yet converted most of the mod from simple strings to localisable strings. Translators will be welcomed to create copies of these files for other languages when the structures of the files are more complete.

Key mod functions

API functions

• on_init() runs when the mod is loaded for the first time.

• on_load() runs when the mod is loaded after the first time.

• on_tick() is run on every tick and is used to schedule regularly called functions.

• game.print(string) prints a string to the game console for all players, but this is NOT vocalized.

Mod custom functions

• schedule(...) can be called to schedule a particular function after a selected number of ticks. At the moment it can only be used within control.lua.

• printout(string, pindex) prints a string to the launcher for the vocalizer to read.

Mod menu system

Factorio allows every player to open at most one menu window at a time. Based on this, the current menu is tracked in the global variable named players[pindex].menu. The following menus have been defined:

• inventory: the character GUI sector where the main inventory is browsed.

• crafting: the character GUI sector where all available recipes for your force can be browsed.

• crafting-queue: the character GUI sector where ongoing crafting requests are listed, and can be canceled before they are completed.

• player_trash: the character GUI sector where the character's logistic trash inventory can be browsed after this feature is unlocked.

• technology: The technology tree menu, called from the character GUI for convenience.

• building: This term applies for the menu of any building that is opened. Has multiple sectors that you can switch between by pressing "TAB".

• vehicle: This term applies for the menu of any individual vehicle that is opened.Has multiple sectors that you can switch between by pressing "TAB".

• building_no_sectors: This term applies for the menu of any building that is opened but has no sectors.

• travel: The menu for the fast travel feature.

• structure-travel: The menu for the structure travel feature, also called the B Stride feature.

• warnings: The warnings list menu.

• rail_builder: The rail builder menu for automatically building rail structures.

• belt: The menu for the transport belt analyzer.

• pump: The menu for the offshore pump building assistant.

• train_menu: The menu for a train (but not its individual vehicles).

• spider_menu: The menu for a spidertron.

• train_stop_menu: The menu for a train stop.

• roboport_menu: The menu for a roboport, also pertaining to its logistic network.

• blueprint_menu: The menu for a blueprint item.

• blueprint_book_menu: The menu for a blueprint book item (partially implemented).

• circuit_network_menu: The menu for a machine in a circuit network, also pertaining to its circuit network in general.

• signal_selector: The menu for browsing all available circuit network signals.

Note 1: The scanner tool does not have its own menu but its features can be used only when no menus are open.

Typical release process

1. Contributors are notified so that the final reviews and merges of pull requests are carried out.
2. A release preparation branch is opened.
3. All commit messages since the last release are reviewed and the change log (md) is written accordingly. Automatic change log generation can be used as a starting point here.
4. A final session of holistic testing is done to validate all the change log notes and to check for bugs. The scope of this may vary. Fixes and change log tweaks are done accordingly.
5. The info.json file is updated.
6. The summary section of the changelog md version is copied to the txt version.
7. The README file is updated to reflect the latest versions of the controls.
8. The release PR is merged. No further file changes beyond this point.
9. The new release folder is created by modifying a copy of the latest one. The new launcher file is added, if it has been updated. The folder is zipped.
10. The update tag and zip package are released on Git Hub.
11. The release announcement is posted on Discord.
12. The release package is modified such that only the Factorio Access folder is taken. It is zipped and named and uploaded to the official mod portal.

More resources

• All kinds of info about Factorio Access can be found this wiki.

• The Factorio Wiki has some modding tutorials listed on this page. In particular consider the Modding Tutorial by Gangsir.

• If you would like discuss possible contributions, suggestions, or other topics about the mod, feel free to get in contact on our Discord server, linked here.