Notes | Contributing | License

Changelog · Translations

Example mod

Lightweight modular example mod with various features and compatibilities

Download the mod  ▶

What it can do

• Filter parameters of commands
• Add switchable commands via map settings
• Double check of commands
• Use built-in error handling of commands
• Use modular structure
• Remotely and safely disable your mod
• Publish your mod on mod portal via GitHub tags
• Auto publishing on mods.portal.com and on GitHub

What it enables you to do

• Handle sounds by a script
• Make switchable, simpler and safer commands
• Make "isolated" modules
• Expand your modules
• More possibilities to control logic
• Quickly publish your mod on mod portal
• Use other's modules/code without adaptation
• Auto publishing everywhere (almost)
• Easy maintaining

Useful stuff

• Factorio modding: https://wiki.factorio.com/Modding
• GitHub service for localization via crowdin: https://github.com/dima74/factorio-mods-localization
• Optimisation tips: https://stigmax.gitbook.io/lua-guide/auxiliary/optimizations & http://lua-users.org/wiki/OptimisationTips & https://springrts.com/wiki/Lua_Performance & https://www.lua.org/gems/sample.pdf & tips (please, notice that Factorio uses lua 5.2.1, so some tips might be irrelevant for Factorio mods!) & Performance Comparison & https://gitspartv.github.io/LuaJIT-Benchmarks/
• EmmyLua Annotations: lua-language-server/wiki/EmmyLua-Annotations
• Untitled GUI Guide: https://github.com/ClaudeMetz/UntitledGuiGuide/wiki (comprehensive tutorial on building custom interfaces)
• Code Completion for jetbrains IDEs: https://forums.factorio.com/viewtopic.php?f=135&p=567132

Stuff used

• Many GitHub Actions to automatically publish to the Factorio mod portal etc
• EditorConfig - helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs
• Factorio's event handler (See Factorio's folder ..\data\core\lualib\event_handler.lua)
• git - version control system
• Visual Studio Code - code editor
• Lua Language Server (Setting without VSCode)
• EmmyLua Annotation
• Some ZwerOxotnik's code
• factorio-mod-luacheck - This GitHub action will run your mod code through luacheck (not full support)
• Auto publishing using many GitHub actions etc (see .github/workflows/autoPublish.yml)

Additional stuff

• FactorioSumnekoLuaPlugin - a plugin for the sumneko.lua vscode extension to help with factorio related syntax and intelisense.
• LuaFormatter - reformats your Lua source code (supports several editors)
• Try another example with preprocessor in lua: https://github.com/ZwerOxotnik/factorio-candran-example

How to start?

• Read this to generate EmmyLua docs for the Factorio API properly
• Change info.json, defines.lua
• Replace my nickname, this project in links, description with your stuff almost everywhere
• Remove unnecessary code, files in /models, /migrations, root folder and create a file there with similar structure in the folder
• Change or delete .github/ISSUE_TEMPLATE/*
• Change or delete .github/workflows/* (please read this)
• Handle files in control.lua
• Change settings in models/BetterCommands/control.lua if you want

Notes

• There are mods/tools that might help you (e.g.: Factorio Library, Rusty's Locale Utilities, Big Data String Libary, Brush tools, Mod generator etc)
• Don't restart your game if you've changed files for control stage
• If you want to develop complex/big project then you'll probably try Factorio-luacheckrc with a GitHub action but you have to mantain .luacheckrc file
• I recommend to use notepad++ when you work with data and notepad2 for hot fixes. For all other cases use any IDE or code editor (e.g.: Visual Studio Code)
• You can store data in entities to support data in blueprints (see an example in LuaCombinator 3)
• Don't add many GUIs at control stage. Factorio's GUI has the highest impact on FPS.

Next updates

• More info about data stage
• More simplification, integrations, examples
• More examples of particular cases on all stages
• Support of EasyAPI (diplomacy, money, chat, etc)
• Probably, I'll add factorio-mod-luacheck
• Some info about lazyAPI someday
• Etc

Requirements

Shell scripts depends on git, 7z, jq.

Installation on Debian and Ubuntu:

sudo apt install p7zip-full jq git -y

Optional Dependencies

• zk-lib - for localization of BetterCommands and event handler, currently

‼️ Important Links (Translations, Discord Support)

If you want to download from this source, then use commands below (requires git).

git clone --recurse-submodules -j8 https://github.com/ZwerOxotnik/factorio-example-mod example-mod
cd example-mod

Contributing

Don't be afraid to contribute! We have many, many things you can do to help out. If you're trying to contribute but stuck, tag @ZwerOxotnik

Alternatively, join the Discord group and send a message there.

Please read the contributing file for other details on how to contribute.

License

I'm interested in distributing code as freely as possible.

Copyright (c) 2021-2022 ZwerOxotnik [email protected]

Licensed under the MIT licence.

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.