Tutoriel Modding Starbound

I/ Introduction & informations

Ce guide vous permettra de créer et de prendre connaissance sur le fonctionnement des mods client-side sur Starbound. Ce tutoriel servira de base pour ceux qui veulent créer leur propres mods et les rendre compatibles sur les serveurs.

Gardez bien à l’esprit que cette documentation n’est pas exhaustive. Si vous voulez faire quelque chose de plus poussée, il va falloir chercher plus loin que ce tutoriel propose.

Vous pouvez utiliser votre éditeur de texte favori comme Notepad++. Je vous conseille personnellement Sublime Text 3 qui permet la coloration syntaxique et l’auto complétion pour les fonctions Starbound grâce à ce package.

IMPORTANT : Le modding de ce tutoriel est basé pour être client-side : c’est à dire que vos mods soient compatible avec n’importe quel serveurs. Si vous souhaitez ajouter du nouveau contenu dans le jeu (nouveaux biomes, blocs, objets à poser…) et que vous voulez les publier sur le workshop, suivez la documentation non-officiel.

II/ Les bases

1 - Ouvrir les fichiers du jeu

Tout d’abord, il faut extraire les fichiers du jeu pour avoir un accès aux ressources comme les sons, les projectiles, les scripts… qui seront utiles pour le modding. Le chemin du dossier Starbound varie selon le système d’exploitation et également si vous avez acheté le jeu depuis Steam et que vous n’avez pas modifié l’emplacement d’installation par défaut.

Sous Windows :

  • Téléchargez ce script, il permet d’extraire les ressources du jeu.
  • Mettez le dans le dossier Starbound qui se trouve à l’emplacement suivant : C:\Program Files (x86)\Steam\SteamApps\common\Starbound. Ensuite double cliquez sur ce fichier et attendez un moment, un dossier unpacked sera créé. Cela peut prendre plus ou moins de temps.

Sous Mac : (Non testé - à confirmer)

  • Ouvrez un Terminal de commande et tapez : cd ~/Library/Application\ Support/Steam/steamapps/common/Starbound/
  • Créez un nouveau dossier avec : mkdir unpacked
  • Allez dans le dossier osx avec la commande : cd ./osx
  • Tapez ./asset_unpacker ../assets/packed.pak ../unpacked et attendez un moment. Si cela prends plus de 20 minutes, quittez le terminal et recommencez la procédure. Si cela ne fonctionne toujours pas, alors vous avez un problème qui n’est pas lié avec le asset_unpacker.
  • Dans Finder rendez vous dans le dossier unpacked précédemment créé en cliquant sur “Go“ sur la barre de menu tout en appuyant sur la touche alt/option (cela va montrer la catégorie “Librairie”, qui est normalement cachée). Cliquez sur Library ensuite Application Support > Steam > steamapps > common > Starbound > unpacked.

Sous Linux :

  • Rendez vous dans le dossier suivant : /home/nomUtilisateur/.steam/steam/steamapps/common/Starbound
  • Lancez un Terminal à cet endroit et marquez : ./linux/asset_unpacker assets/packed.pak unpacked_assets
  • Après un moment, les ressources seront extraites dans le dossier unpacked_assets.

2 - Ouvrir le fichier du personnage

Dans un premier temps, vous devez vous rendre dans le dossier Starbound. Faites impérativement une sauvegarde de votre fichier .player avant toutes modifications !

Sous Windows :

  • Téléchargez ce script, il permet la conversion entre .player et .json très facilement.
  • Mettez le dans le dossier Starbound ( C:\Program Files (x86)\Steam\SteamApps\common\Starbound ).
  • Allez maintenant dans le dossier storage puis dans le dossier player.
  • Trouvez la sauvegarde à éditer. Triez par date afin de voir quel est le dernier personnage utilisé et copiez le .player au même endroit que le script.
  • Ensuite il suffit simplement de glisser-déposer le fichier sur Conversion Joueur.bat et de remplacer la sauvegarde par celle modifiée dans le dossier storage/player. image-center

Sous Mac : (Non testé - à confirmer)

  • Ouvrez un Terminal de commande et tapez : cd ~/Library/Application\ Support/Steam/steamapps/common/Starbound/
  • Allez maintenant dans le dossier storage puis dans le dossier player.
  • Trouvez la sauvegarde à éditer. Triez par date afin de voir quel est le dernier personnage utilisé et copiez le .player dans le dossier osx.
  • Allez maintenant dans le dossier osx avec la commande : cd ../../osx
  • Tapez : ./dump_versioned_json ./Série_de_nombres.player ./Save_joueur.json
  • Pour compiler le JSON en .player : ./dump_versioned_json ./Série_de_nombres.player ./Save_joueur.json
  • Dans Finder allez dans le dossier unpacked précédemment créé en cliquant sur “Go” sur la barre de menu tout en appuyant sur la touche alt/option (cela va montrer la catégorie “Librairie”, qui est normalement cachée) Cliquez sur Library ensuite Application Support > Steam > steamapps > common > Starbound > unpacked.

Sous Linux :

  • Rendez vous dans le dossier suivant : /home/nomUtilisateur/.steam/steam/steamapps/common/Starbound
  • Allez maintenant dans le dossier storage puis dans le dossier player.
  • Trouvez la sauvegarde à éditer. Triez par date afin de voir quel est le dernier personnage utilisé et copiez le .player dans le dossier Starbound.
  • Lancez un terminal depuis le dossier Starbound et marquez : linux/dump_versioned_json ./Série_de_nombres.player ./Save_joueur.json
  • Pour compiler le JSON en .player : linux/make_versioned_json ./Save_joueur.json ./joueur_modif.player
  • Vous pouvez maintenant remplacer la sauvegarde dans storage/player par celle modifiée.

III/ Créer du contenu

1 - Modding JSON : création/modification d’une arme

Avant de commencer :

je vous suggère de prendre connaissance des bases de la syntaxe JSON car la moindre erreur, oubli ou même majuscule cassera le code. Utilisez l’outil suivant pour vérifier la syntaxe de vos code JSON avant de les ajouter en jeu : https://jsonlint.com/

Cette partie se fait essentiellement en jeu. Il est conseillé d’avoir l’accès aux ressources du jeu (assets).

Avant de lancer le jeu installez les mods Quickbar Mini et RexmecK Item Editor Classic : Quickbar modifie l’icône du Matter Manipulator afin d’avoir accès à un panel. RexmecK Item Editor permet d’éditer les objets directement en jeu ce qui offre un gain de temps considérable.

Pour ce test, l’objet à modifier sera un pistolet basique. Faites le apparaître en allant dans votre solo puis en tapant les commandes suivantes : /admin /spawnitem rarepistol /admin Attention l’objet apparaîtra sur votre curseur !

Maintenant ouvrez votre panel et sélectionnez RexmecK Item Editor. image-center Une nouvelle fenêtre apparaît, mettez votre objet dans votre bar d’action en haut sur la case de gauche ce qui correspond à la main principale et sélectionnez là de façon à avoir l’arme dans les main en jeu : image-center Ensuite cliquez sur Scan puis sur Raw Edit. image-center

Le Raw Edit permet de voir tout le code de l’objet scanné et permet donc de mieux visualiser sa composition. Plus l’objet scanné a de lignes plus votre jeu va ralentir, faites attention à cela. Si vous savez ce que vous cherchez vous pouvez utiliser le panel de droite. Pour ce tutoriel on se contentera d’utiliser le Raw edit.

Pour cette partie il y a 2 sous-catégories : L’une pour l’édition du code et l’autre pour appliquer une texture personnalisée sur l’arme.

a) Ajouter / Modifier le code

Comme RexmecK Item Editor ne montre pas toutes les informations, une recherche dans ressources du jeu sera nécessaire. Pour cela si vous êtes sous Windows je vous suggère d’installer le logiciel Agent Ransack qui peut rechercher même à l’intérieur des fichiers. Ici il faut trouver le fichier contenant toutes les informations sur l’objet appelé rarepistol. La recherche m’a retourné : /items/active/weapons/ranged/pistol/rarepistol.activeitem image-center Une fois le fichier ouvert la syntaxe est effectivement en JSON. image-center

Pour cet exemple le type de projectile va être remplacé par le jouet banane (noveltybanana).

Les extensions des fichiers sont d’une grande aide. Les .activeitem sont pour tout ce qui est utilisable en mains, les .object sont des objets plaçable, les .projectile sont des projectiles, ect…

Comme ce pistolet a un élément, sa structure est différente d’une arme classique. Mais cela n’empêche pas sa modification et ne change pas vraiment d’une arme sans élément. image-center La ligne intéressante est celle contenant le projectileType. Elle se trouve dans “primaryAbility”:{}, il faut donc respecter la même chose en jeu pour pouvoir changer son projectile.

De retour en jeu, cliquez sur la ligne “primaryAbility”:{ pour la sélectionner et cliquez sur Line + puis sur Edit et ici tapez “projectileType” : “noveltybanana”, (avec la virgule à la fin) puis cliquez sur Done pour confirmer, sur Save pour terminer l’édition et enfin sur Save pour sauvegarder l’objet modifié dans l’inventaire : il y aura donc l’arme originale et la version modifiée. image-center Vous pouvez tout modifier tant que vous respectez la norme de l’arme et la syntaxe JSON ! Si vous voulez continuer le JSON ou en savoir plus sur ce qui peut être modifié, jetez un oeil sur ce sujet du forum officiel Starbound, fouillez vos ressources du jeu et faites des tests. image-center

b) Appliquer une texture

Pour appliquer une texture personnalisée et la mettre en jeu, vous aurez besoin d’un éditeur d’image / de sprite (comme GIMP ou Aseprite) ainsi que Drawable generator (disponible uniquement sous Windows). Cliquez sur DrawablesGenerator-v1.X.X-win32.zip pour télécharger le logiciel et décompressez le fichier zip où vous voulez. Les X représentent la version du logiciel, cela est susceptible de changer.

Avant de lancer le logiciel, il est préférable de voir le contenu du fichier : /items/active/weapons/ranged/pistol/rarepistol.activeitem

La texture et les animations ne sont pas dans ce fichier. Cependant la ligne “animation” indique le fichier : /items/active/weapons/ranged/gun.animation image-center Comme ce pistolet est généré de façon aléatoire, il est composé de plusieurs parties : butt l’arrière de l’arme. middle le milieu de l’arme. barrel le canon. muzzleFlash la petite animation de tir.

Cela ne sert à rien d’appliquer une texture sur chaques parties sauf si vous voulez faire une arme très poussée et très complète. Pour ce tutoriel on va se limiter à changer le middle.

La valeur qui contient la texture est “image”. On veut modifier que le middle cependant le butt et le barrel auront toujours leur texture de base.

Pour cela il suffit de remplacer les 3 lignes contenant : "image" : "<partImage><paletteSwaps>", par "image" : "/assetmissing.png", Ce qui donnera une texture invisible.

Comme ceci est une animation personnalisé il faut mettre tout le code dans animationCustom” : {},fin que les changements prennent effets. Ce qui donne au final ceci : image-center Je n’ai gardé que les lignes qui sont utile.

properties Définie les propriétés de la texture. centered Centre la texture. Le point de référence de Starbound se situe en 0, 0 qui se trouve en bas à gauche. image Définie la texture. offset Modifie la position de l’arme. transformationGroups Permet de définir le groupe de transformation comme la rotation. Utile pour une utilisation poussée. Laissez le par défaut ici.

Vérifiez si vous n’avez pas fait d’erreurs en collant votre code sur ce site.

Important : Ce site respecte les normes. Sur la capture précédente tout est bon et fonctionnera en jeu mais elle ne respecte pas la norme puisque c’est une partie du code et non le code entier. Le site va le considérer comme faux. La version ci-dessous corrige ce problème pour le site.

image-center

Si vous avez une erreur, regardez le message que le site renvoi et allez à la ligne indiquée. Vérifiez bien que vous n’avez pas oublié ou mis une virgule de trop, que vous avez bien fermé les accolades, les guillemets, etc…

Après avoir trouvé ou créé l’image que vous voulez, lancez DrawablesGeneratorTool.exe. Pour convertir votre image il suffit simplement de la glisser-déposer sur le personnage et la texture apparaîtra. Ensuite décochez Fade Method puis cliquez sur Single Texture Directives et cliquez sur Copy pour copier tout le code. image-center Fade Method permet de réduire l’utilisation de mémoire lors de l’affichage de l’image et accroît les performances. Cependant cela affichera des rectangles si votre personnage a un effet (“glow” ou “minibossglow” par exemple) comme ceci: image-center Une fois le code copié revenez sur votre partie de code pour le coller juste après /assetmissing.png. image-center

Plus la texture est grande plus le code sera long et plus votre jeu ou même votre éditeur de texte risque de ralentir. Ne mettez pas de texture démesurément grande sous le risque de corrompre votre personnage.

Maintenant il faut ajouter tout le code en jeu et on ne peut copier/coller le code que s’il est sur une seule ligne. Pour cela il y a un raccourci sous Sublime Text 3 et Notepad++ : sélectionner tout le code que vous voulez mettre sur une seule ligne (ou CTRL+A) puis faites CTRL+J, ce qui placera tout le code sur une seule ligne et copier le tout avec CTRL+C. image-center

De retour en jeu, scannez votre objet et cliquez sur la ligne “parameters”:{ pour la sélectionner et cliquez sur Line + puis sur Edit et coller tout le code précédemment copié. Cliquez sur Done pour confirmer, sur Save pour terminer l’édition et enfin sur Save pour sauvegarder l’objet modifié dans l’inventaire. image-center Si la texture est mal positionnée il faut changer l’offset. Trouvez la ligne contenant votre texture, puis modifiez la valeur de l’offset. Faites plusieurs tests si nécessaire. image-center Ici j’ai déplacé la texture de 0.5 sur la droite et de 0.1 vers le haut

La texture personnalisée est placée et visible par tout le monde même sur les serveurs ! image-center Si vous voulez retexturer un projectile, un véhicule comme l’hoverbike ou une particule, la procédure reste la même (/assetmissing.png<directive>). Si vous voulez en savoir plus sur les directives regardez ce lien.

2 - Modding JSON : modification d’une armure

Pour ce test l’objet à modifier sera une armure (peu importe l’armure, cela n’a strictement aucune importance) pour lui ajouter des effets et modifier ses statistiques.

Faites apparaître l’objet en allant dans votre solo puis en tapant les commandes suivantes : /admin /spawnitem hylotltier6schest /admin Attention l’objet apparaîtra sur votre curseur !

Avant d’ouvrir RexmecK Item Editor, il faut savoir quelles effets ajouter.

Les armures peuvent appliquer des statusEffects dont la majorité se trouvent dans /stats/effects puis dans un dossier qui leur est affecté. Pour cette partie, les effets xenonglow et minibossglow vont être appliqués. Maintenant ouvrez votre panel, sélectionnez RexmecK Item Editor, scannez l’objet puis cliquez sur Raw Edit. Cliquez sur “parameters”:{ puis Line +, Edit et enfin ajouter la ligne "statusEffects" : ["xenonglow", "minibossglow"],

Sauvegardez le tout et équipez vous de votre armure modifiée.

image-center Les 2 effets ont été ajoutés.

Pour changer les statistiques de l’armure, rendez vous tout en bas du code et changez la valeur “amount” des valeurs : puissance, protection, énergie, points de vie. image-center Bien que vous pouvez changer les valeurs de protections et de vie comme vous le souhaitez vous ne serez pas réellement invincible puisque les dégâts élémentaires comme le feu, le poison vous causera des dégâts.

Pire encore pour les dégâts de lave ou lorsque vous mourez de faim car ces derniers baissent les PV par leur pourcentages. Toucher la limite de fond d’une planète ou tomber de l’outpost vous tuera instantanément.

3 - Modding Lua : création d’une Tech

Avant de commencer, je vous suggère de prendre connaissance de la base de programmation en Lua.

Pour créer une tech il vous faudra créer un nouveau mod (vous pouvez également l’implémenter dans un mod existant mais cela est déconseillé si vous débutez).

Pour cela, rendez vous dans le dossier de Starbound puis allez dans le dossier mods (s’il n’existe pas, faites un nouveau dossier avec cette même orthographe). Il vous faudra créer un nouveau dossier avec n’importe quel nom, et placer ce fichier .metadata dans ce dossier (ne pas le renommer, le laisser en .metadata)

Ouvrez le ensuite avec votre éditeur de texte et remplacez les noms dans les rectangles. Vous pouvez trouver la liste complète ainsi que leur significations. image-center Inutile de toucher aux autres lignes, vous pouvez sauvegarder et fermer. Si tout va bien votre mod devrait déjà apparaître dans la liste ci-dessous. image-center