Comment contribuer aux scripts PSDK
[!NOTE] Pour lire ce fichier correctement, ouvrez-le dans Visual Studio Code (VSCode) puis appuyez sur CTRL+K, puis V. Cela ouvrira l'aperçu du fichier. Vous pouvez également le lire sur le dépôt officiel GitLab de PSDK. Bonne lecture !
Forker PSDK
- Rendez-vous sur le dépôt PSDK
- Cliquez sur le bouton fork
Configurer votre dépôt local
Dans votre dossier Pokémon SDK, ouvrez cmd.bat et entrez les commandes suivantes :
cd pokemonsdk-
git remote set-url origin votre_url_ssh- Vous pouvez obtenir l'URL en cliquant sur
clonedans les détails de votre fork PSDK. Prenez l'URL SSH, sinon il sera difficile de push.
- Vous pouvez obtenir l'URL en cliquant sur
git pull
Créer une nouvelle fonctionnalité ou un correctif
Vous devez respecter la convention de nommage des branches :
- Les branches de fonctionnalité sont nommées ainsi :
feature/us-ID nom - Les branches de correctif sont nommées ainsi :
bugfix/us-ID nom
Pour créer votre nouvelle fonctionnalité/correctif, entrez les commandes suivantes dans votre dossier pokemonsdk :
git checkout developmentgit pullgit checkout -b nom_de_la_branche
Vous serez maintenant en mesure de travailler sur ce que vous devez faire.
Note : Vous ne devez jamais commit sur development. Votre branche development locale doit rester identique à celle du dépôt officiel (pokemonsdk/pokemonsdk). Si vous commitez dessus par erreur, vos futures branches divergeront et ne pourront plus rebase proprement. Pour réparer, placez-vous sur development et exécutez :
git reset --hard origin/development
Quand vous commitez sur votre branche
Si votre branche a pour but de corriger un bug, assurez-vous que le dernier commit contient le texte suivant dans le message de commit : Fix #id_de_l_issue
Quand vous mergerez avec la branche officielle development, cela fermera l'issue.
Avant de merger sur development
- Vous ne devez pas commit vos changements sur la branche
development. Vous devez faire une merge request depuis votre branche feature/bugfix vers la branche development officielle (pokemonsdk/pokemonsdk). - Vous devez tester votre fonctionnalité ou votre correctif.
- Le projet PSDK doit pouvoir démarrer
- Toutes les fonctionnalités de PSDK doivent fonctionner comme avant (sauf celle que vous avez corrigée, évidemment)
- Votre fonctionnalité/correctif ne doit pas introduire de nouveau bug (nous ne vous en voudrons pas si vous n'avez pas remarqué de nouveaux bugs)
- Vous devez toujours vous assurer que votre branche est à jour avec la branche development en utilisant la fonctionnalité git rebase
- Vous devez résoudre tous les conflits
:warning: Veuillez noter que toute Merge Request causant des régressions ou ne respectant pas ces conditions pourra être rejetée et/ou fermée.
Créer la Merge Request (MR)
- Dans
Source branch- Sélectionnez votre projet
- Sélectionnez la branche que vous souhaitez merger avec la branche
developmentde PSDK
- Dans
Target branch- Sélectionnez le projet
pokemonsdk/pokemonsdk - Sélectionnez la branche
development
- Sélectionnez le projet
- Cliquez sur le bouton
Compare branches and continue
Vous verrez l'interface New Merge Request
- Dans le titre, mettez un titre un peu plus explicite que le nom de la branche et commencez toujours par un verbe :
Fixs'il s'agit d'un correctifAddouImplements'il s'agit d'une nouvelle fonctionnalitéUpdateouChanges'il s'agit d'une mise à jour de fonctionnalitéRewriteouRefactorizeouImproveouReworks'il s'agit d'une refactorisation ou d'une améliorationRemoveouReverts'il s'agit d'une suppression de code
- Dans la description, avec la template fournie
- décrivez l'objectif de la merge
- ajoutez les références aux issues si nécessaire
- indiquez si vous avez ajouté des fichiers qui ne sont pas censés se trouver dans le dossier
pokemonsdk(des graphismes par exemple)- Vous pouvez fournir un lien vers une archive 7z qui ajoute toutes les nouvelles ressources en l'extrayant simplement à la racine du projet
- Assignez la review à un mainteneur du code si possible
- Ajoutez des labels pour rendre la merge request plus explicite sur son champ d'application
- Ajoutez le label
Need to be testeddans tous les cas
- Ajoutez le label
- Cochez
Delete source branch when merge request is accepted. - Cochez
Squash commits when merge request is accepted. - Cliquez sur le bouton
Submit merge request
Après avoir soumis la Merge Request
Si votre merge request n'a pas été remarquée ou n'a pas été mergée après une semaine, vous devriez contacter les contributeurs ou les testeurs de PSDK via le Discord Pokémon Workshop (vous trouverez un lien sur le site web). Bien qu'un webhook automatique rapporte toutes les actions sur le dépôt principal GitLab à la communauté, il peut arriver qu'une merge request passe inaperçue à cause de nouveaux commentaires ou de nouvelles merge requests. Si cela arrive, faites-le savoir à un membre de l'équipe et nous traiterons votre merge request au plus vite !
:warning: Veuillez noter que l'auteur de la MR ne doit pas marquer comme résolus les fils de discussion ouverts par les reviewers. Les reviewers fermeront les fils de discussion dès que leurs commentaires auront été traités par des corrections ou que leurs questions auront reçu une réponse.
Les règles de code
PSDK est un projet Ruby. Il utilise des outils qui fonctionnent bien avec Ruby.
Quel éditeur utiliser ?
Pour éditer les scripts :
- Vous devez utiliser Visual Studio Code.
- Vous devrez installer
ruby3.0.6 avec le devkit (MSYS2 sur Windows, Ruby Installer vous donne le choix de l'installer).
Configurer les extensions requises pour que votre code suive les bonnes pratiques
Si vous ne configurez pas ces extensions, votre code pourrait ne pas suivre les bonnes pratiques et les futures reviews de code le signaleront. En supposant que vous utilisez VSCode, voici les étapes à suivre.
- Installez l'extension VSCode "Ruby LSP"
- Installez l'extension VSCode "Ruby Solargraph"
- Ouvrez un cmd en administrateur, puis lancez cette commande :
gem install solargraph && gem install ruby-lsp - Dans VSCode (en supposant que vous utilisez VSCode en anglais), appuyez sur CTRL+P, puis '>', puis sélectionnez "Preferences: Open User Settings (JSON)"
- Dans ce JSON, collez ceci entre les accolades présentes (ou après votre propre configuration si vous en avez déjà une), et n'oubliez pas les virgules :
"editor.tabSize": 2,
"solargraph.diagnostics": true,
"solargraph.formatting": false,
"rubyLsp.enabledFeatures": {
"codeActions": true,
"diagnostics": true,
"documentHighlights": true,
"documentLink": true,
"documentSymbols": true,
"foldingRanges": true,
"formatting": true,
"hover": true,
"inlayHint": true,
"onTypeFormatting": true,
"selectionRanges": true,
"semanticHighlighting": true,
"completion": true,
"codeLens": true,
"definition": true,
"workspaceSymbol": true,
"signatureHelp": true,
"typeHierarchy": true
},
"rubyLsp.formatter": "none",
"rubyLsp.rubyExecutablePath": "C:\\Ruby30\\bin"
- Sur la dernière ligne, assurez-vous de remplacer
C:\\Ruby30\\binpar le chemin du dossier bin de votre version de Ruby. En général, il sera situé dans C:, et s'appellera Ruby30 (pour Ruby 3.0), Ruby31 (pour Ruby 3.1), etc. Ruby LSP pourrait ne pas se lancer si ce n'est pas correctement configuré. - Redémarrez VSCode, puis vérifiez en bas à droite de VSCode que les messages "No bundle found" et "No .ruby-version-file found" s'affichent, dans cet ordre. Si c'est le cas, c'est bon signe.
- Attendez quelques secondes car Ruby LSP peut être un peu lent à s'initialiser selon votre matériel.
- Rubocop devrait maintenant surveiller votre code. Vous pouvez tester si c'est le cas en écrivant votre pire morceau de code, comme plusieurs guard clauses sans aucun saut de ligne ou une seule valeur de retour entourée de parenthèses. Si une ligne bleue apparaît sous votre monstruosité, alors vous avez terminé cette étape !
Quel dossier ouvrir avec VS Code ?
Avec VS Code vous devrez ouvrir le dossier scripts du dépôt local pokemonsdk. Ce dossier est configuré pour définir toutes les règles rubocop que PSDK utilise.
Quelles sont les règles de code exactes ?
Dans un script
- Tout code que vous écrivez ne doit pas être souligné en bleu ou en orange. Si vous pensez qu'une des règles est stupide, dites-le nous afin que nous puissions discuter d'un changement potentiel.
- Vous ne devez pas perdre de temps à corriger les anciennes lignes soulignées en vert ou en orange.
- Vous devez documenter votre code en utilisant le format YARD (Liste des tags).
- Découper vos méthodes (aussi appelées fonctions) en méthodes plus petites permet aux makers de patcher facilement des parties du code au lieu de réécrire de plus gros morceaux.
- Si Solargraph ne parvient pas à vous donner la bonne complétion pour une variable d'instance, utilisez
# @type [ClassName]avant de créer la variable d'instance.
Nommage des scripts
Tous les scripts PSDK sont nommés ainsi : XXX Nom.rb
- X est un chiffre entre 0 et 9, cela permet le tri entre les scripts
- Nom doit être le nom de la classe/module + le contexte quand la classe est séparée en plusieurs scripts.
Note : Les anciens scripts portent le nom suivant Module__Classe, ne faites plus cela, le dossier nous indique déjà le module.
Dans quel module placer les nouvelles fonctionnalités ?
Voici la liste officielle des modules PSDK avec leur signification :
Scheduler: Ce module ne sert pas à contenir des classes. C'est le module responsable de l'exécution detasksà certains moments du jeu sans ajouter de lignes dans les scripts pour appeler explicitement vos fonctionnalités. Un tutoriel sur son utilisation sera fait plus tard, vous pouvez consulter le script00100 PSDK_Taskpour voir comment il est utilisé.Studio: Ce module contient toutes les classes et helpers dedead data. Lesdead datasont les données stockées dans les fichiers.rxdata,.csvou.dat, ce sont des données que PSDK ne doit pas éditer/modifier/sauvegarder et qu'il utilise comme source d'information (la courbe d'expérience d'un Pokémon par exemple).Yuki: C'est un ancien module datant de l'époque où PSDK n'existait pas encore. Il contient toutes les fonctionnalités créées parNuriYuri. Vous ne devez jamais ajouter de script à l'intérieur. (Mais vous pouvez corriger certaines fonctionnalités)PFM: Ce module contient toutes les classes et helpers deliving data. Lesliving datasont les données manipulées pendant leruntimeet qui peuvent être sauvegardées dans le fichier de sauvegarde du joueur.UI: Ce module contient toutes les classes dédiées à l'affichagegraphique. Ces classes ne doivent pas contenir de logique (ou juste un minimum si cela aide l'affichage, comme un ajustement d'index). La plupart des classes dansUIdoivent hériter deUI::SpriteStack,SpriteouUI::Window.GamePlay: Ce module contient toutes les scènes qui sont appelées et stockées dans la variable globale$scene. Si vous créez une nouvelle scène, vous devez la faire hériter deGamePlay::Base(ou d'une classe spécialisée deGamePlay::Base) et vous ne devez jamais modifier les fonctionsmainni lire/écrire la variable$scene. Un tutoriel sera fait plus tard surGamePlay::Base.BattleUI: Ce module contient toute l'UI du système de combat. C'est en quelque sorte la même chose queUImaisUIn'est pas inclus dedans, donc vous devez écrire explicitementUI::ClassNamesi vous utilisez une classe deUIdansBattleUI.Battle: Ce module contient toutes les classes liées au système de combat (Scene,Logic,Visual,AIetMove).
Si vous écrivez une fonctionnalité, vous devez l'écrire dans le module correct en fonction de ce que la fonctionnalité fait. Quand vous créez une scène, il est important de ne pas écrire de code graphique à l'intérieur de la scène (faites-le dans UI avec une classe dédiée) et d'instancier la classe UI dans un init_xxx de votre Scene. (Cela permet au maker ou à une classe spécialisée de changer l'UI utilisée en modifiant la méthode init_xxx).
Règles spécifiques
Comme vous pourrez le constater dans PSDK (en mettant de côté les scripts de base RMXP), nous faisons les choses d'une certaine manière. Voici les règles que vous devez suivre pour être compatible avec PSDK ou écrire de bons scripts :
Ne jamais utiliser for ni les Ranges dynamiques
Le mot-clé for est interdit car sa signification en Ruby n'est pas la même qu'en C ou en algorithmique.
for i in 0...5 do
p i
end
Est strictement identique à :
(0...5).each do |i|
p i
end
Ruby possède un système d'itération/énumération puissant, vous devez utiliser les méthodes suivantes au lieu des boucles for :
-
int.times { |i| ... }au lieu de :for i in 0...int do ... end -
min.upto(max) { |i| ... }au lieu de :for i in min..max do ... end -
max.downto(min) { |i| ... }au lieu de :for i in min..max do j = max - (i - min) ... end -
beg.step(last, step_val) { |i| ... }au lieu de :for i in beg..last do next if i % step_val != 0 ... end -
Utilisez
var = Array.new(size) do |i| ... next(element) endau lieu de :
var = [] for i in 0...size do ... var.push(element) end -
ary.select { |element| condition }au lieu de :result = [] for i in 0...ary.size do result.push(ary[i]) if condition endAlternativement, utilisez
rejectpour effectuer l'opération inverse. -
ary.collect { |element| transformation }ouary.map { |element| transformation }au lieu de :array = ary.clone for i in 0...ary.size do array[i] = transformation end -
ary.any? { |element| condition }au lieu de :result = false for i in 0...ary.size do next unless condition result = true break end -
ary.all? { |element| condition }au lieu de :result = true for i in 0...ary.size do next if condition result = false break end -
ary.inject(0) { |sum, element| sum + element.property }si vous avez besoin d'obtenir la somme d'une propriété des éléments d'un tableau. (Comme la somme totale des niveaux de l'équipe).
Note sur la syntaxe des blocks : Si le code tient sur une seule ligne, on utilise la syntaxe { |*params| }, si le code utilise plusieurs lignes, on utilise la syntaxe do |i| lignes end. Rubocop vous le signalera si vous ne respectez pas cette règle.
Nous déconseillons fortement l'utilisation de Ranges dynamiques lorsque ce n'est pas nécessaire car cela crée des objets inutiles alors qu'il existe d'autres alternatives.
Si vous voulez permettre la personnalisation par les makers, utilisez des méthodes ou des constantes
Par exemple si l'utilisateur veut changer le fond de l'UI pour un fond plus sombre, vous pouvez utiliser une constante COLORS qui liste tous les identifiants de couleur que vous utilisez dans l'interface. Ainsi le maker peut changer le contenu de COLORS pour utiliser des couleurs plus adaptées à son UI.
Si vous n'utilisez qu'une ou deux couleurs, vous pouvez créer des méthodes comme default_color ou highlight_color qui retournent l'identifiant de la couleur que vous utilisez.
La même chose s'applique pour les noms de fichiers, les window builders, etc.
Ne pas écrire toute la logique dans update dans les Scènes
Le mieux est de faire hériter votre Scène de GamePlay::BaseCleanUpdate et de définir :
update_inputspour la logique des inputs (non appelé si des messages sont en cours de traitement)update_mouse(moved)pour la logique de la souris (non appelé si update_inputs retourne false ou si des messages sont en cours de traitement)update_graphicspour mettre à jour les animations graphiques à chaque frame
Ne pas mettre à jour les textes à chaque frame
Le texte est un processus lourd, vous devez le mettre à jour uniquement quand c'est nécessaire et si la mise à jour peut changer quelque chose. Par ailleurs, la scène ne devrait pas gérer les objets texte directement, elle devrait uniquement gérer des objets UI::ClassName qui sont des spécialisations de UI::SpriteStack ou UI::Window.
Appeler la méthode data= de UI::ClassName uniquement si le contenu affiché change
Le système UI de PSDK repose sur une méthode data= pour le texte, les sprites, les stacks ou les windows dynamiques. Cela permet d'indiquer quoi afficher sans tout écrire dans la Scène. Vous devez appeler cette méthode uniquement quand l'index change (méthode index_changed de GamePlay::Base) ou quand l'objet d'affichage doit être modifié (mise à jour de ses informations internes comme l'objet tenu par un Pokémon).
Rendre privées les méthodes qui ne doivent pas être appelées hors de la classe
Dans une classe, certaines méthodes comme init_ui ne doivent pas être appelées de l'extérieur (encapsulation). Rendez-les privées en les plaçant à la fin du script après le mot-clé private.
Exemple :
class Thing < GamePlay::BaseCleanUpdate
def initialize
super
init_ui
end
def update_inputs
# ...
end
private
def
@viewport = Viewport.create(:main, 500)
end
def init_ui
@ui = UI::Thing.new(@viewport)
end
end
Utiliser attr_reader au lieu de attr_accessor et définir la méthode property=
Cette règle a pour but de garantir que vous validez toutes les données. Par exemple, définir les PV d'un Pokémon ne doit pas autoriser de valeur Float pour les PV et doit mettre à jour le hp_rate (pour aider les barres de PV).
Définir des méthodes property_text au lieu d'utiliser format, sprintf, etc.
Quand une propriété doit être affichée dans une UI, il est préférable de définir une méthode property_text qui génère la chaîne de caractères que l'UI doit afficher. De cette façon, vous réduisez le code et la duplication dans les UIs puisque vous n'avez qu'à ajouter un SymText avec :property_text en paramètre.
Ne jamais utiliser les noms set_ ou get_
Nous faisions cela par le passé mais c'est une mauvaise idée. Dans la documentation web, cela sépare les méthodes puisqu'elles sont triées par nom (et cela rend aussi plus difficile pour quelqu'un de trouver la méthode).
Privilégiez le nom direct de la propriété ou la méthode property=. Si vous avez une spécialisation comme une propriété qui est un identifiant entier mais que vous voulez retourner le db_symbol, ajoutez la spécialisation après le nom de la propriété : property_db_symbol par exemple. (Comme nous l'avons fait pour property_text).
Toujours utiliser return explicitement
Ruby permet de retourner implicitement la dernière expression évaluée, mais dans PSDK on utilise toujours return explicitement. De même, dans les blocks qui retournent une valeur, on utilise toujours next explicitement.
# Bon
def level_text
return "Lv. #{@level}"
end
var = Array.new(size) do |i|
next(i * 2)
end
# Mauvais
def level_text
"Lv. #{@level}"
end
var = Array.new(size) do |i|
i * 2
end
Essayer de limiter le nombre de lignes d'un script à 500 ou 1000
Si le script a trop de lignes, il fait trop de choses (pas de séparation Graphique / Logique, God Classes). Nous ne devrions pas avoir ce genre de chose. Si le script est trop long (parce qu'il affiche différents menus par exemple), vous avez différentes façons de procéder :
- Utilisez la spécialisation : La façon dont
Party_Menuest fait est mauvaise, il fait trop de choses et devrait être séparé en différentes classes spécialisées. - Découpez le script en scripts contextuels : La solution que nous avons adoptée pour la plupart des scripts. Vous pouvez mettre l'initialisation dans le premier script, l'update dans le deuxième, les éléments spécifiques à la souris dans le troisième, etc.
- Faites une meilleure séparation des actions. Si votre logique est trop compliquée (comme la logique de combat), ne la mettez pas dans la Scène, créez une classe dédiée. Quand on lit les quelques lignes d'un script, on doit comprendre ce qui est fait sans lire le contenu des méthodes.