Aller au contenu principal
Voir

Travailler à plusieurs sur un projet PSDK

Un projet PSDK créé avec Pokémon Studio ne contient pas de dépôt Git par défaut. Le mettre sous Git permet à plusieurs makers de travailler sur le même jeu sans s'écraser les modifications. La difficulté propre à PSDK est que les données RMXP sont stockées dans des fichiers .rxdata binaires que Git ne sait pas fusionner. Ce guide explique comment initialiser le dépôt, ce que doit contenir le .gitignore, le workflow .yml qui rend les données RMXP fusionnables, et les règles qui évitent que les contributeurs se marchent dessus.

Avant de commencer, s'assurer d'avoir fait la préparation de l'environnement de développement, qui installe Git et VS Code. La plupart des étapes ci-dessous se font graphiquement dans VS Code et sur le site GitHub ou GitLab. Pour le vocabulaire Git utilisé ici (commit, branche, remote) et la clé SSH optionnelle, voir Découvrir Git. On recommande aussi d'installer l'extension GitLens (voir GitLens).

Mettre son projet sous Git​

Un projet Pokémon Studio n'est qu'un dossier sur le disque. Le mettre sous Git se fait en trois étapes, toutes graphiques : créer un dépôt vide en ligne, ajouter un .gitignore, puis publier le projet depuis VS Code.

Il faut d'abord un compte gratuit GitHub ou GitLab. VS Code demandera de s'y connecter à la première publication, c'est aussi ainsi qu'il obtient l'autorisation de pousser ses commits.

Créer le dépôt sur GitHub ou GitLab​

Cela se fait entièrement depuis le site web.

Sur GitHub :

  1. Cliquer sur le + en haut à droite, puis New repository.
  2. Donner un nom au dépôt, et choisir Private si le projet ne doit pas être public.
  3. Laisser les options Add a README, Add .gitignore et licence décochées, pour que le dépôt reste vide et puisse recevoir le projet existant.
  4. Cliquer sur Create repository.

Sur GitLab :

  1. Cliquer sur New project, puis Create blank project.
  2. Donner un nom au projet et choisir sa visibilité.
  3. Décocher "Initialize repository with a README", pour que le projet reste vide.
  4. Cliquer sur Create project.

On garde la page ouverte : elle affiche l'URL du dépôt dont on aura besoin plus tard. Si on s'est connecté dans VS Code, on copie l'URL HTTPS ; si on a configuré une clé SSH (voir Découvrir Git), on copie l'URL SSH (elle commence par git@).

Ajouter un .gitignore​

Git ne doit pas suivre tout le contenu du dossier. Un projet PSDK mélange trois types de fichiers : les fichiers source qu'on écrit (scripts, données .yml), les fichiers régénérés que le moteur recrée tout seul (le runtime Ruby, les .rxdata compilés), et les fichiers locaux qui n'appartiennent qu'à sa machine (les sauvegardes). Seuls les fichiers source ont leur place dans Git, sinon le dépôt devient énorme et impossible à fusionner.

On crée le fichier à la racine du projet (dans VS Code, clic droit sur la liste des fichiers, New File, le nommer .gitignore) et on colle ceci comme base. C'est celui utilisé par la démo technique officielle de PSDK :

# Runtime du moteur - régénéré par PSDK/Studio, jamais committé
.gameopts
Game.rb
latest.json
psdk.bat
lib/
ruby_builtin_dlls/
pokemonsdk/
ruby.exe
rubyw.exe
msvcrt-ruby300.dll

# Sauvegardes locales et scripts de combat compilés
Saves/*
Data/Events/Battle/*.yarbc

# Données RMXP compilées (binaire) - ignorées, mais les versions .yml sont gardées
Data/Actors.rxdata
Data/AnimatedTiles.rxdata
Data/Animations.rxdata
Data/CommonEvents.rxdata
Data/System.rxdata
Data/Tilesets.rxdata
Data/Map*.rxdata
!Data/Map*.rxdata.yml
Data/configs/*.rxdata
!Data/configs/*.rxdata.yml
Data/PSDK/Maplinks.rxdata
!Data/PSDK/Maplinks.rxdata.yml
Data/PSDK/SystemTags.rxdata
!Data/PSDK/SystemTags.rxdata.yml

# Texte compilé et données Studio
Data/Text/Dialogs/*.dat
Data/Studio/psdk.dat

# Artefacts de build
PSDK_Technical_Demo_*.zip
Release/
project.psa

Deux points méritent d'être compris ici :

  • Le runtime du moteur (lib/, ruby.exe, pokemonsdk/, psdk.bat, ...) est fourni par Pokémon Studio ou en clonant le moteur. Il est lourd et spécifique à la machine, donc on ne le committe jamais. Chaque membre de l'équipe le récupère sur sa propre machine.
  • Les données RMXP compilées (.rxdata) sont binaires. Elles sont ignorées, tandis que les lignes !Data/...rxdata.yml gardent explicitement les versions texte .yml suivies. Cette séparation est tout l'objet du workflow yml ci-dessous.

La ligne PSDK_Technical_Demo_*.zip correspond à l'archive de release de la démo. Dans son propre projet, on la remplace par le nom de sa propre archive de release.

Publier son projet avec VS Code​

Le .gitignore en place, VS Code peut publier le projet sans le terminal. Chaque action ci-dessous se lance depuis la palette de commandes : on appuie sur Ctrl+Shift+P et on tape la commande. La position exacte des boutons change selon la version de VS Code et GitLens la réorganise, donc la palette est la façon fiable de trouver une action (astuce : taper Git: liste toutes les actions Git de sa version).

  1. Ouvrir le dossier du projet dans VS Code : File > Open Folder.
  2. Lancer Git: Initialize Repository pour commencer à suivre le dossier.
  3. Ouvrir la vue Source Control (l'icône de branche dans la barre de gauche, ou Ctrl+Shift+G). Comme le .gitignore est déjà là, seuls les bons fichiers apparaissent. On les indexe tous avec le +, on tape un message comme Initial commit, puis on lance Git: Commit (ou on appuie sur Ctrl+Entrée dans le champ de message).
  4. Lancer Git: Add Remote, coller l'URL du dépôt affichée sur le site, et la nommer origin.
  5. Lancer Git: Push pour envoyer le projet. Au tout premier envoi, la commande peut s'appeler Git: Publish Branch, et VS Code peut demander de se connecter à GitHub ou GitLab.
Le premier envoi est long

Un projet PSDK contient des dizaines de milliers de fichiers (graphismes, audio, cartes, données) et peut peser plusieurs centaines de mégaoctets, donc le premier envoi peut prendre plusieurs minutes, voire davantage sur une connexion lente. On le laisse finir sans l'interrompre : VS Code affiche la progression dans la barre d'état en bas. Une fois terminé, on vérifie que la vue Source Control n'affiche plus de modifications en attente, et on rafraîchit la page du dépôt sur GitHub ou GitLab, où les fichiers et le dernier commit doivent maintenant apparaître.

Si on préfère la ligne de commande, la page du dépôt affiche aussi les commandes équivalentes (git init, git add ., git commit, git remote add origin <url>, git push -u origin main).

Versionner les données RMXP : le workflow yml​

Les cartes, animations, événements communs et configurations sont enregistrés par RMXP et Studio sous forme de fichiers .rxdata. Ce sont des fichiers binaires : quand deux makers modifient la même carte, Git ne sait pas fusionner les deux versions. Il ne peut qu'en garder une et jeter l'autre, donc quelqu'un perd toujours son travail.

PSDK résout ça avec un aller-retour entre .rxdata (binaire, utilisé par le jeu) et .yml (texte, utilisé par Git). On committe les .yml, on ignore les .rxdata, et on passe de l'un à l'autre en double-cliquant sur l'un des deux scripts à la racine du projet :

  • convert_rxdata_to_yml.bat convertit les .rxdata en .yml. On double-clique dessus avant chaque commit, pour que la version texte qui arrive dans Git corresponde à ce qu'on vient de faire.
  • convert_yml_to_rxdata.bat reconvertit les .yml en .rxdata. On double-clique dessus après chaque pull, pour que le jeu utilise les données que ses coéquipiers viennent de partager.
Fermer RMXP et Studio d'abord

Toujours sauvegarder et fermer RMXP et Pokémon Studio avant de double-cliquer sur l'un ou l'autre script, dans les deux sens. S'ils restent ouverts, les données qu'ils gardent en mémoire peuvent écraser les fichiers fraîchement convertis au moment où on sauvegarde, annulant silencieusement la conversion (et le travail du coéquipier). Le script ouvre une petite fenêtre de console qui se referme d'elle-même après une seconde ou deux ; pour confirmer que ça a marché, on vérifie que les fichiers .yml (ou .rxdata) viennent de changer, ou on lance le script depuis l'invite de commandes pour lire sa sortie si quelque chose semble anormal.

La première fois qu'on clone le projet, les fichiers .rxdata n'existent pas encore (ils sont ignorés), donc le jeu planterait. Double-cliquer sur convert_yml_to_rxdata.bat une fois après le clone est obligatoire : cela reconstruit les .rxdata depuis les .yml committés.

La règle à retenir est courte :

  • Convertir avant de partager (convert_rxdata_to_yml.bat, puis commit).
  • Restaurer après avoir reçu (pull, puis convert_yml_to_rxdata.bat).

Rejoindre un projet existant​

Quand on rejoint un projet déjà hébergé sur GitHub ou GitLab, on le clone au lieu de le créer. Dans VS Code, on ouvre la palette de commandes (Ctrl+Shift+P), on lance Git: Clone, on colle l'URL du dépôt et on choisit où l'enregistrer.

Les fichiers .rxdata ne sont pas dans le dépôt (ils sont ignorés), donc le jeu ne peut pas encore se lancer. On fait ceci une fois, dans l'ordre :

  1. Ouvrir le projet dans Pokémon Studio une fois, pour qu'il génère le bon psdk.bat, puis fermer Studio.
  2. Double-cliquer sur convert_yml_to_rxdata.bat pour reconstruire les données binaires depuis les .yml committés.

Cette étape de restauration est obligatoire au premier clone, sinon le jeu plante faute de .rxdata. Ensuite, on est configuré exactement comme le reste de l'équipe.

Workflow au quotidien​

Une fois que tout le monde est configuré, la boucle quotidienne sur un projet partagé est toujours la même, et c'est surtout des clics. Supposons qu'on veuille ajouter une nouvelle carte.

1. Récupérer la dernière version. On vérifie que le nom de branche affiché dans la barre d'état (en bas de la fenêtre) est main, puis on lance Git: Pull depuis la palette de commandes (Ctrl+Shift+P). Une fois terminé, RMXP et Studio fermés, on double-clique sur convert_yml_to_rxdata.bat pour appliquer au jeu les dernières modifications de ses coéquipiers.

2. Créer une branche. On lance Git: Create Branch et on la nomme d'après la zone qu'on touche (voir Ne pas se marcher dessus), par exemple maps/nouvelle-ville.

3. Faire le travail dans RMXP et Studio. Quand on est prêt à le partager, on sauvegarde et on ferme RMXP et Studio, puis on double-clique sur convert_rxdata_to_yml.bat pour transformer les données en texte.

4. Committer et pousser. Dans la vue Source Control, on indexe ses modifications avec le +, on tape un message comme Add the new town map, on lance Git: Commit, puis Git: Push pour envoyer la branche en ligne (le bouton bleu Sync Changes dans la barre d'état fait à la fois le pull et le push).

5. Ouvrir la demande. Juste après le push, GitHub affiche une bannière Compare & pull request et GitLab une bannière Create merge request. On clique dessus pour ouvrir une Pull Request (GitHub) ou une Merge Request (GitLab). Un coéquipier la relit, puis elle est fusionnée dans main.

6. Tout le monde lance Git: Pull dans VS Code, puis (RMXP et Studio fermés) double-clique sur convert_yml_to_rxdata.bat pour récupérer la carte.

Cette boucle garde main toujours fonctionnel et permet à plusieurs personnes d'avancer en parallèle, chacune sur sa branche.

Ne pas se marcher dessus​

Même avec le workflow .yml, deux personnes qui modifient la même carte en même temps produisent quand même un conflit pénible. La vraie solution est organisationnelle, pas technique. Ces règles viennent de la façon dont la démo technique de PSDK est maintenue.

Nommer les branches par zone. On préfixe la branche par la partie du projet qu'elle touche : maps/, events/, texts/, resources/. Par exemple maps/nouvelle-ville, events/nouvelle-ville, texts/traduction-nouvelle-ville, resources/nouvelle-ui. Tout le monde voit d'un coup d'oeil ce qu'une branche modifie.

Une seule personne par carte et par catégorie. Pour une carte donnée, le mapping (les tuiles) et l'eventing (les événements) sont deux travaux distincts. Une seule personne doit tenir chaque travail pour une carte donnée à un instant T :

  • Autorisé : le maker A retravaille le mapping de la Map X pendant que le maker B travaille sur les événements de la Map X.
  • Autorisé : le maker A fait le mapping de la Map X et aussi ses événements, car les changements de mapping obligent à adapter certains événements.
  • Interdit : le maker A et le maker B modifient tous les deux le mapping de la Map X (l'un ajoute des tuiles animées, l'autre corrige quelque chose).
  • Interdit : le maker A corrige des événements sur la Map X pendant que le maker B ajoute de nouveaux événements à la Map X.

Communiquer avant de commencer. On demande toujours si quelqu'un travaille déjà sur la carte qu'on veut toucher. La convention de nommage des branches aide, mais un petit message évite le reste.

Faire les conversions Tiled sur sa propre branche. Une conversion de carte Tiled modifie beaucoup de fichiers d'un coup. On la lance sur sa branche et on inclut le résultat dans le commit de cette branche, pour qu'elle n'entre jamais en collision avec la conversion de quelqu'un d'autre.

Résoudre un conflit sur un fichier yml​

Comme les cartes et les données sont versionnées en texte .yml, un conflit est désormais quelque chose qu'on peut réellement corriger au lieu de perdre un fichier. Quand un pull signale un conflit, les fichiers concernés apparaissent sous Merge Changes dans la vue Source Control de VS Code.

On recommande de résoudre les conflits dans VS Code avec l'extension GitLens. On ouvre un fichier .yml en conflit et on clique sur Resolve in Merge Editor. L'éditeur de fusion affiche les deux versions côte à côte, avec les boutons Accept Current Change, Accept Incoming Change et Accept Both Changes pour chaque bloc en conflit. GitLens ajoute l'auteur et l'historique de chaque côté, ce qui aide à décider lequel garder.

Une fois qu'un fichier est correct, on clique sur Complete Merge dans l'éditeur de fusion : le fichier passe dans les modifications indexées. Quand tous les conflits sont réglés, on lance Git: Commit pour terminer, puis (RMXP et Studio fermés) on double-clique sur convert_yml_to_rxdata.bat pour reconstruire les données binaires afin que le jeu reflète le résultat fusionné.

Conclusion​

  • Un projet Pokémon Studio ne contient pas de dépôt Git par défaut. Avec un compte GitHub ou GitLab, on crée le dépôt vide, on ajoute un .gitignore avant le premier commit, puis on publie le projet depuis VS Code.
  • Le .gitignore garde les fichiers source (.yml, scripts) et ignore tout ce qui est régénéré (runtime du moteur, .rxdata binaires) ou local (sauvegardes).
  • Les données RMXP sont binaires et non fusionnables. PSDK les convertit en texte .yml, toujours RMXP et Studio fermés : double-clic sur convert_rxdata_to_yml.bat avant de partager, convert_yml_to_rxdata.bat après avoir reçu, et une fois après le premier clone (ouvrir d'abord le projet dans Studio pour générer psdk.bat).
  • La boucle quotidienne : pull et restore, brancher, travailler, convert, commit, push, puis ouvrir une Pull Request ou Merge Request.
  • Pour éviter les conflits, on nomme les branches par zone, on garde une seule personne par carte et par catégorie, on communique avant de commencer, et on lance les conversions Tiled sur sa propre branche.
  • Les conflits sur les fichiers .yml se résolvent dans l'éditeur de fusion de VS Code, puis convert_yml_to_rxdata.bat reconstruit les données binaires.