Ritn mod conventions¶
This guide describes the structure and the shared rules of the mods of the Ritn ecosystem. It is meant for a developer who writes or takes over a mod, and for an AI working on it: each rule is worded to be applied as is. When in doubt, copy the reference mod rather than inventing.
Two variants exist:
| Variant | When | Reference mod |
|---|---|---|
| With RitnLib | general case: the mod depends on RitnLib and uses its classes | RitnLobbyGame, RitnCharacters |
| Standalone | public tool that must not depend on anything | gvv (0.6) — local copy of RitnLib's base classes |
Rules marked (both) apply in every case.
1. Folder layout (both)¶
<Mod>/
├─ info.json
├─ changelog.txt Factorio changelog format, strict
├─ settings.lua settings stage (at the root)
├─ data.lua data stage: loads defines then prototypes/
├─ control.lua control stage: defines → classes → modules
├─ core/
│ ├─ defines.lua path registry
│ ├─ setup-classes.lua loads the classes (in inheritance order)
│ ├─ modules.lua list of the modules sent to the event handler
│ └─ migrations.lua one migration per version (if storage)
├─ classes/ one class per file (Ritn<Mod>Xxx / Gvv<Xxx>)
├─ gui/ windows: getElement / getContent
├─ modules/ one module per domain
├─ lualib/ utility functions (local … return modules)
├─ prototypes/ data stage only
├─ mods/ compatibility, one file per mod
├─ locale/<language>/<mod>.cfg
├─ types/<mod>-globals.lua LuaLS meta-file (in the zip)
└─ docs/ maintainer docs (left out of the zip)
Rules:
- One file = one responsibility. No "catch-all" file.
- prototypes/ holds only data stage code; classes/, gui/, modules/ only control stage code.
2. Path registry defines (both)¶
Every require goes through a registry. No file writes a hard-coded path: if a file moves, only the
registry changes.
With RitnLib — the mod adds its registry inside RitnLib's (RitnLobbyGame/core/defines.lua):
-- FR : Registre partagé de RitnLib (ou __RitnLib__.defines)
-- EN : RitnLib shared registry (or __RitnLib__.defines)
if not ritnlib then
require("__RitnBaseGame__.core.defines")
end
-- FR : Nom du mod et dossier racine
-- EN : Mod name and root folder
local name = "RitnLobbyGame"
local dir = "__" .. name .. "__"
local defines = {}
defines.name = name
defines.directory = dir
-- FR : Chargement des classes
-- EN : Classes loading
defines.setup = dir .. ".core.setup-classes"
-- FR : Classes du mod
-- EN : Mod classes
defines.class = {
guiLobby = dir .. ".classes.RitnGuiLobby",
}
-- FR : Modules envoyés à l'event handler
-- EN : Modules sent to the event handler
defines.modules = {
core = dir .. ".core.modules",
events = dir .. ".modules.events",
}
-- FR : Description des fenêtres
-- EN : Windows description
defines.gui = {
lobby = dir .. ".gui.lobby",
}
-- FR : Prototypes (data stage)
-- EN : Prototypes (data stage)
defines.prototypes = {
customInputs = dir .. ".prototypes.custom-inputs",
}
-- FR : Clé courte du mod dans le registre partagé
-- EN : Short key of the mod inside the shared registry
ritnlib.defines.lobby = defines
Standalone — the mod creates its own global (gvv/core/defines.lua):
-- FR : Nom du mod et dossier racine
-- EN : Mod name and root folder
local name = "gvv"
local directory = "__" .. name .. "__"
-- FR : Registre des chemins (classes, gui, modules...)
-- EN : Path registry (classes, gui, modules...)
local defines = {
name = name,
directory = directory,
class = {
gui_main = directory .. ".classes.GvvGuiMain",
},
modules = {
core = directory .. ".core.modules",
},
}
-- FR : Global du mod
-- EN : Mod global
if not gvv then
gvv = {}
end
gvv.defines = defines
Rules:
- The registry is loaded at the data stage and the control stage (require("core.defines") first).
- require is forbidden during the game (inside an event, a command, a remote.call): everything that
must be required is required while control.lua loads. Otherwise Factorio raises
"Require can't be used outside of control.lua parsing".
3. control.lua bootstrap (both)¶
-- FR : Registre des chemins
-- EN : Path registry
require("core.defines")
-- FR : Classes (globales)
-- EN : Classes (globals)
require(<registry>.setup)
-- FR : Modules envoyés à l'event handler
-- EN : Modules sent to the event handler
local event_handler = require(<registry>.event)
local modules = require(<registry>.modules.core)
local listener = event_handler.add_libraries(modules)
-- FR : Rend le storage du mod lisible par gvv (si gvv est installé)
-- EN : Makes the mod storage readable by gvv (if gvv is installed)
if script.active_mods["gvv"] then
require("__gvv__.gvv")()
end
-- FR : Tests en jeu avec RitnTest (développement seulement)
-- EN : In-game tests with RitnTest (development only)
if script.active_mods["RitnTest"] then
require("__RitnTest__.interface")
end
- Event handler:
__core__.lualib.event_handler(exposed by RitnLib asritnlib.defines.event). - The last two lines do nothing if gvv / RitnTest are not installed.
4. Classes (both)¶
- Created by the class factory (
ritnlib.classFactorywith RitnLib, local copycore/class.luawhen standalone):X = factory.newclass(Parent, function(self, ...) Parent.init(self, ...) end). - Global (
_G), prefixed by the mod:RitnLobbyGuiRequest,GvvGuiTree. One class per file, loaded bycore/setup-classes.luain inheritance order (parent before child). - Temporary wrappers: an instance is created on each event (
X(event)) and dropped afterwards. Never an instance insidestorage: data goes there, not objects. object_nameholds the class name (e.g.self.object_name = "GvvGuiTree").- A method that returns nothing useful returns
self(chaining). - Methods tolerate a missing player or a closed window (
isPresent,nilelements) without error.
5. Modules and events (both)¶
Each file of modules/ handles one domain and returns a table for the event handler:
-- FR : Nouveau joueur : ses données sont créées
-- EN : New player: their data is created
local function on_player_created(event)
storage.players[event.player_index] = {}
end
-- FR : Module envoyé à l'event handler
-- (optionnels : on_init, on_load, on_configuration_changed, add_commands)
-- EN : Module sent to the event handler
-- (optional: on_init, on_load, on_configuration_changed, add_commands)
local module = {events = {}}
module.events[defines.events.on_player_created] = on_player_created
return module
core/modules.lua gathers them:
-- FR : Liste des modules envoyés à l'event handler
-- EN : List of the modules sent to the event handler
local modules = {}
-- FR : Cycle de vie du mod
-- EN : Mod life cycle
modules.events = require(<registry>.modules.events)
-- FR : Évènements des fenêtres
-- EN : Windows events
modules.gui = require(<registry>.modules.gui)
return modules
Rules:
- No direct script.on_event inside a module: everything goes through the event handler. Documented
exception: an on_tick enabled / disabled by a setting (gvv), registered again in on_load from storage.
- on_load must never write into storage (desync).
- A GUI handler is protected: the error is shown to the player and written to the log
(log(...) with the call stack), so that it can be found again (bug reports, tests).
6. GUI (both)¶
Description inside gui/<window>.lua¶
-- FR : Description des éléments (specs passées à LuaGuiElement.add)
-- EN : Elements description (specs given to LuaGuiElement.add)
local function getElement(gui_name)
local element = {
-- FR : Cadre principal
-- EN : Main frame
frame = {
main = <Class>Element(gui_name, "frame", "main"):vertical():get(),
},
-- FR : Bouton fermer
-- EN : Close button
button = {
close = <Class>Element(gui_name, "sprite-button", "close")
:spritePath("utility/close")
:get(),
},
}
return element
end
-- FR : Chemins des éléments depuis gui[1], sans le préfixe gui_name
-- EN : Element paths from gui[1], without the gui_name prefix
local function getContent()
local content = {
frame = {
main = { "frame-main" },
},
button = {
close = { "frame-main", "button-close" },
},
}
return content
end
return {
getElement = getElement,
getContent = getContent,
}
<Class>Element = RitnLibGuiElement (with RitnLib) or the local copy (GvvGuiElement).
Element naming¶
- Name =
gui_name-type-name, e.g.gvv_main-button-close,lobby-button-create. - None of the three parts contains
-(the name is split on-). Use_inside a part. gui_nameprefixed by the mod (gvv_main,mymod_panel): names must be unique insideplayer.gui, across all the windows of all the mods.- Long types are shortened:
sprite-button→button,scroll-pane→pane,empty-widget→empty,list-box→listbox,drop-down→dropdown,tabbed-pane→tabbed,text-box→textbox. - The action of an element is
type-name(e.g.button-close), followed by the event name for events other than the click (listbox-result-selection_state_changed).
Window class¶
- Inherits from
RitnLibGui(or the local copyGvvGui). - Extension contract: the sub-class fills
gui[1](container),content(=getContent()),gui_action, then writes its action methods. - Actions:
- with RitnLib:
gui_action = { [gui_name] = { [action] = true } }and the action is served by agui_action_<gui_name>remote interface (see the Full GUI pattern guide); - standalone:
gui_action = { ["button-close"] = "action_close" }, the method is called directly. - Dynamic data inside
element.tags(tree row, entry index…), never encoded in the name beyondname. - No GUI element reference inside
storage: an element is found again through its path (getElement). - Properties set at creation only (
numeric,allow_decimal,column_count,minimum_value,clear_and_focus_on_right_click…): put them in the spec, not afteradd. - Centred free window:
auto_center = trueafter its size is given.
7. Data stage (both)¶
data.luaonly doesrequire("core.defines")then the files ofprototypes/through the registry.- Prototype names prefixed by the mod (
_gvv-mod,ritnmods-…): never a clash with the game. - Compatibility between Ritn mods (gameplay mods): each mod creates
ritnmods.<mod>in itsdata.lua(if not ritnmods then ritnmods = {} end), with its detection flags and shared data; the others read it. One file per third-party mod insidemods/, guarded byif ritnmods.<mod>.<flag> then. - A variable that no longer exists in the game (e.g. an old global of
style.lua) isnil: do not rely on undocumented game globals.
8. storage and migrations (both)¶
- Per-player data:
storage.players[player_index], created on first use. - What goes into
storage: serialisable data (numbers, strings, tables, API Lua objects). Never: class instances, functions, GUI element references. core/migrations.lua: one entry per version, run inon_configuration_changedwhen the mod changes version (mod_changes[<mod>].old_version), in order, protected and logged (log).
9. Code style (both)¶
- FR + EN comments: each block of code has its comment, French then English:
- One statement per line, no one-line function, no compact code.
- Line endings: keep the file's own (CRLF in most mods, LF in part of RitnLib).
Never convert a whole file; check with
git ls-files --eol. - Files copied from another mod (e.g. RitnLib classes when standalone): header
-- FR : Source : RitnLib (Ritn), <file> (<class>), version x.y.z+ the differences.
10. LuaLS annotations (both)¶
Format of the RitnLib gold standard: EN then FR, separated by a Unicode line ─ (U+2500), tags after the FR:
---**EN**
---
---Description: Closes the main window.
---
---──────────────────────────────
---
---**FR**
---
---Description: Ferme la fenêtre principale.
---@param ignore_save? boolean
---@return GvvGuiMain self Chainable
function GvvGuiMain:close(ignore_save)
- Every function, method and class gets its block when it is created, never "later": the code is written directly in its final state (no annotation pass afterwards).
- An empty line is required between a simple
-- …comment and a---block. - Inline descriptions of
@param/@field: short, in English. ⚠only for a verified fact (side effect, snapshot, beta, deprecated), in both languages.
Class — one continuous block stuck to the assignment, then cast at the end of newclass(...):
---**EN**
---
---Description: Panel of MyMod.
---
---⚠ Temporary wrapper, created on each event.
---Do not store the instance in `storage`.
---
---──────────────────────────────
---
---**FR**
---
---Description: Panneau de MyMod.
---
---⚠ Wrapper temporaire, créé à chaque évènement.
---Ne pas stocker l'instance dans `storage`.
---@class MyModGuiPanel : RitnLibGui
---@field object_name string "MyModGuiPanel"
---@operator call(table): MyModGuiPanel
---@type MyModGuiPanel
MyModGuiPanel = ritnlib.classFactory.newclass(RitnLibGui, function(self, event)
...
end) --[[@as MyModGuiPanel]]
- Do not re-declare inherited
@fields (except the ones the child overrides, likeobject_name). - Mirror: each global class is copied into
types/<mod>-globals.lua(---@meta,---@diagnostic disable), same@class/@field/@operator, thenMyModGuiPanel = {}. Both places change together. This file is shipped in the zip (autocompletion for the developers of the mods depending on yours).
11. Repository and publishing (both)¶
info.json:factorio_version, exact dependencies (RitnLib >= x.y, optional?, hidden(?)).changelog.txtin the Factorio format (dashes line,Version:,Date:, indented categories)..gitattributes:export-ignorefordocs,tests,.github,.claude… (left out of the zip).- Bilingual Markdown files: FR line ended by two spaces, EN line right below.
-
Publishing through a git tag (
release.ymlworkflow:git archiveof the tag). -
Living
docs/architecture.md: updated on every structural change (new layer, class family, module, event,storagekey, remote interface).
12. In-game tests (both)¶
Test in the real game before calling a task done: an out-of-game test sees neither the real API nor the
require restriction during the game. Errors are read in factorio-current.log (hence the log() of §5).
The RitnTest development mod (on GitHub, not on the portal; never on a public server) drives the real game through RCON: fake GUI events sent
to the mod handlers, GUI reading, screenshots, eval inside the mod VM. The tested mod adds the RitnTest
line of §3; it does nothing for someone who doesn't have RitnTest.
13. AI kit (both)¶
The ai/ folder of RitnLib holds what you need to start:
- AGENTS.md and CLAUDE.md: the rules for the AI, to copy to the mod root;
- skills/ritn-mod-conventions/: Claude Code skill, to copy into .claude/skills/;
- template/with-ritnlib/ and template/standalone/: mod skeletons ready to copy (rename MyMod).
To test in game with an AI: the skills/factorio-mod-ritntest/ skill of the RitnTest repository. New to Lua:
see Getting started with an AI.
For an AI — action rules¶
- Read before writing:
core/defines.lua,core/modules.lua, the class and thegui/file concerned, then copy the existing style. The reference mod of the variant prevails. - Never: write a hard-coded
requirepath,requireduring the game, store a class instance or a GUI element instorage, put a-inside a part of an element name, write intostoragefromon_load. - Always: FR + EN comments, the file's line endings kept, annotations in the §10 format, a new class
added to the registry and to
setup-classes.lua, a new module added tocore/modules.lua, a migration for every change of thestoragestructure. - Error inside a GUI handler: write it to the log (call stack included), not only to the chat.
- Test in game (by hand, or with an RCON tool) before calling a task done; an out-of-game test sees neither the
requirerestrictions nor the real API.
See also¶
- Full GUI pattern — GUI with RitnLib in detail.
- 4-layer architecture, Temporary wrappers.
- ADR-0004 — FR + EN strategy.