Tutoriel sur la creation de mod

Ce tutoriel explique la création de mod dans Factorio. Je ne rentrerais pas dans tous les détails mais surtout comment ce faire un environnement, comment faire du débug et plein d'astuces pour se faciliter la vie.

Introduction

Dans ce tutoriel, je vais donner des conseils et astuces sur la manière de créer un mod. Pour ma part je n'ai fais qu'un mod helper, qui n'est principalement que de l'interface et aucun élément ajouté au jeu.
Je ne rentre pas dans les détails sur le contenu pour faire un mod, c'est trop complexe à expliquer mais ici vous aurez une base pour vous lancez.

A un endroit du tutoriel, il y a un bypass de sécurité Windows, c'est normalement sans risque mais en aucun cas je peux être tenu responsable de dommage sur votre PC.

Liens utiles

Voici une liste des liens utiles

• Mods de Factorio[mods.factorio.com]
  
• API Factorio[lua-api.factorio.com]
  
• Wiki Factorio Modding[wiki.factorio.com]
  
• Visual Studio Code[code.visualstudio.com]
  
• Factorio Mod Debug[marketplace.visualstudio.com]
  
• Lua Users[lua-users.org]
  
• Lua 5.2 Reference Manual[www.lua.org]
  
• mon_mod[mods.factorio.com]

Mise en place d'un Factorio

Pour ma part, j'utilise des versions Zip de Factorio que je télécharge sur le site officiel: Source Factorio[factorio.com].
L'intéret est de pas mélanger son installation de jeu avec celle de travail en plus de permettre de cloner le dossier pour faire un test multi en local ou d'avoir différente version de travail.

Télécharger la version courante zip pour windows et la placer dans le dossier C:\tuto_factorio par exemple.

Décompresser le zip dans le dossier
Ce dossier C:\tuto_factorio\Factorio_1.0.0 sera désigné dans la suite [Factorio_Folder]

Je conseil fortement de créer un raccourci du programme [Factorio_Folder]\bin\x64\factorio.exe à la racine du dossier c'est plus simple dans l'utilisation.
Aller dans le dossier [Factorio_Folder]\bin\x64 et créer le raccourci du fichier factorio.exe
Couper le raccourci et coller à la racine du dossier [Factorio_Folder]
Exécuter une première fois Factorio via le raccourci
Si le message suivant apparait et comme vous avez bien téléchargé le jeu sur le site officiel, vous allez pouvoir passer la sécurité.
Cliquer sur Informations complémentaire.
Puis sur Exécuter quand même.
Après le premier lancement le dossier [Factorio_Folder]\mods est créé et nous servira pour après évidemment.

L'éditeur de LUA

Concernant le logiciel EDI conseillé, prendre Visual Studio Code[code.visualstudio.com] pour avoir le mod debug.
Une fois dans Visual Studio Code il vous faudra activer des extensions selon les besoins.
Taper "factorio" dans la barre de recherche et choisir:

• Factorio Mode Debug pour du debug ou du profilage
  
• Factorio Lua API autocomplete pour avoir de l'auto-completion

Workspace et jonction (ou lien symbolique)

Nous allons définir comme Workspace le dossier C:\tuto_factorio\workspace
Ajouter y un dossier mon_mod

Un élément important c'est qu'en général on va avoir un dossier de travail (workspace) et on ne veut pas le déplacer et pouvoir le dupliquer facilement. En fait il y a beaucoup plus simple en utilisant un lien symbolique (ou jonction)
Ouvrir une commande dos dans le dossier de [Factorio_Folder]\mods et exécuter la commande suivante:

mklink /J [nom_de_mon_mod] [chemin_complet_du_dossier_de_travail]

exemple:

mklink /J mon_mod_1.0.0 C:\tuto_factorio\workspace\mon_mod

On peut omettre le numero de version du mod sur le dossier, si jamais la version est indiqué, il faudra évidemment que ca correspond a l'info.json
Vous remarquerez la petite flèche sur le dossier mon_mod_1.0.0 qui indique la jonction, évidemment si vous cliquez sur le dossier vous vous retrouvez dans le dossier de travail mais le chemin windows est différent. Vous pouvez faire autant de junction sur le dossier de travail que vous voulez et ainsi tester rapidement en local le multi.

Ajouter le dossier dans votre Workspace de Visual Studio Code.
Menu File>Add Folder to Workspace

Création du Mod

Je ne vais pas entrer dans tous les détails qui existe déjà sur le site Wiki Factorio Modding[wiki.factorio.com]

mais la structure de base du dossier est:

• un fichier info.json
  
• un fichier control.lua
  
• un fichier data.lua
  
• un fichier thumbnail.png

Le fichier info.json contient les informations du mod
Attention le nom (name) doit correspondre au nom du dossier ainsi que le numero de version doit correspondre. Le nom du zip final de votre mod devra être la concaténation de "name" et "version", ex: mon_mod_1.0.0

le fichier control.lua est l'emplacement du script qui tournera dans la partie

le fichier data.lua est l'emplacement de la définition des données que l'on ajoute dans le jeu et sera lu au chargement du jeu.

le fichier thumbnail.png est la vignette du mod

vous retrouvez le mod de test ici: mon_mod[mods.factorio.com]

Comment faire du Debug

Configuration

Une fois votre mod créé vous voulez faire du debug ou du profiling sur votre script
Aller dans le menu de gauche avec la flèche et le scarabé
Cliquer sur la flèche qui descend pour ouvrir les options de Run
Sélectionner "Add Config (workspace)"
Un menu déroulant apparait sur la droite
Choisir Factorio Mod Debug
Le fichier launch.json est automatiquement créé et il ne reste qu'a remplir le champ "factorioPath" qui vaut dans notre cas "C:/tuto_factorio/Factorio_1.0.0/bin/x64/factorio.exe" (le chemin de l'exécutable de factorio. attention ici j'ai remplacé les backslashs par des slashs pour le chemin.
Il ne reste plus qu'a exécuté le run (flèche verte) sur "Factorio Mod Debug (workspace)"
le jeu se lance et vous lancez et chargez une partie

Le mode Debug

Mettez un point d'arrêt dans le code, en cliquant sur la gauche du numero de ligne. Ensuite au moment de l'arrêt, sur la partie gauche vous pouvez consulter toutes les valeurs ou directement en passant le curseur sur les variables du fichiers en pause. En video.
Dans certaines situations il n'est pas impossible que le Debug renvois une erreur "Stack overflow" si on reste trop longtemps en arrêt.
Si votre point d'arrêt n'est pas pris en compte vérifier après le lancement que le Debug Adapter for Factorio Mods est bien compatible avec votre version. Evidemment si votre dossier du Mod (directement ou en lien virtuel) n'est pas dans le dossier mods de l'instance Factorio exécutée cela ne fonctionne pas non plus.
Vous pouvez aussi désactivé la mise à jour automatique des extensions pour utiliser le debug dans une version moins récente.
Il faudra dans ce cas installer manuellement le VSIX de la version souhaitée en manuel après l'avoir télécharger sur la page Factorio Mod Debug[marketplace.visualstudio.com] dans l'onglet "Version History" et faire "Install from VSIX".

Le mode Profile

Faites la même chose avec le run (flèche verte) sur "Factorio Mod Debug (Profile) (workspace)"
Vous aurez des informations sur le temps d'exécution de votre script, ca permet de voir la ou il faut faire un effort pour simplifier le code. Attention toute fois cela reste plus une évaluation que le réel temps d'exécution car c'est aussi du LUA qui debug.

Le script LUA

Le script LUA comme tout les scripts n'est pas typés donc une variable peut prendre n'importe quelle valeur il faut faire attention, vous pouvez vous retrouver avec un contenu de variable incorrecte.

Un élément important qui peut avoir un intérêt c'est d'utilisé la notion de classe pour avoir accès à l'héritage. Pour ma part j'utilise l'implémentation de classe de cette page Simple Class[lua-users.org] juste après le titre "Implementation of class()".

Il faut absolument mettre toutes les variables en "local" sinon le mod ne sera pas utilisable en multi.

Les bonnes pratiques

Vous n'êtes pas limité sur la manière de construire votre mod, alors n'hésitez pas à faire des modules pour regrouper les fonctions appartenant à un thème. Je conseillerai même de n'avoir quasiment pas de code dans le fichier control.lua sinon de n'appeler que les premiers scripts.
Vous connaissez surement le mod Helmod[mods.factorio.com] voici son fichier de control.lua

Utilisez un outil de versionning comme Github, déjà vous sauvegardez votre travail et vous pouvez revenir sur des modifications.

Si vous avez des informations que vous voulez garder durant la partie il faut les mettre dans la variable global (c'est une table), tout module ne doit pas voir d'attribut de classe modifié durant son exécution, sinon vous aurez des désynchronisations en multi. D'ou l'intérêt de la classe cité précédemment car vous pouvez normalement mettre des attributs variables à condition que ces dernier soit modifié à chaque run.

FAQ

Mon mod n'apparait pas dans la liste des mods sélectionnable.

Vérifier que le dossier mods du factorio exécuté contient bien le dossier (virtuel ou pas) du mod.

Mon point d'arrêt en debug ne fonctionne pas.

Probablement un problème de version entre Factorio et Factorio Mod Debug, consulter la section "Comment faire du Debug".

j'ai des problèmes de désynchronisation en multi

Le mod doit avoir une variable non local modifié pendant la partie. C'est très compliqué de trouver le problème mais en gros il faut vérifier le code pour trouver une variable non locale.

Est-il possible de faire des thread avec le lua?

Il n'y a pas de multi-thread sur factorio a cause du déterminisme, après s'il y a des problèmes d'exécution faut le faire sur plusieurs ticks

Ma recette n'accepte pas les modules de productivité

Il existe des limitations pour les modules.
En premier lieu sur le module lui même via l'attibut LuaItemPrototype.limitations, cet attribut contient la liste des recettes autorisées s'il est vide il n'y a aucune limitation.

{ "sulfuric-acid", "basic-oil-processing", "advanced-oil-processing", "coal-liquefaction", "heavy-oil-cracking", "light-oil-cracking", "solid-fuel-from-light-oil", ect...}

En second lieu la restriction se fait sur la machine par l'attribut LuaEntityPrototype.allowed_effects ayant pour valeur une table string -> boolean

{consumption=true, speed=true, productivity=false, pollution=true}

Conclusion

Je vais essayer de consolider le tutoriel dans le temps.
Vous pouvez vous inspirer de mon Helmod la source est ici[github.com], c'est certainement le mod avec l'interface la plus complexe et très stable.
Attention aux yeux il y a plus de 20 000 lignes de codes.

[Cats Delesip]

Merci beaucoup pour ce tuto. J'hésitais à me lancer dans l'édition ou la création de mode. Cela aide beaucoup.

[.:Meteor:.]

Merci pour ce petit guide clair et concis

[[ZIG] helfima]

merci content que ca serve à quelque chose

[Poükä]

Merci @helfima pour ce petit tuto.
Cela m'as permis d'avancer sur la maj d'un mod plus maintenu depuis la 0.16 et l'auteur ne répond pas...
J'ai trouvé le lien de ton tuto sur le discord de la commu fr de factorio.
Encore merci.

[F1nger ™]

hhhh