Très inspiré par et basé sur le « [Gamemakin](https://gamemak.in) UE4 Style Guide » disponible sur [GitHub](https://github.com/Allar/ue5-style-guide).
Godot propose quelques conseils sur la façon de travailler pour son propre projet dans une section [Les meilleures pratiques](https://docs.godotengine.org/fr/stable/tutorials/best_practices/index.html) ainsi qu’un [Guide de style](https://docs.godotengine.org/fr/stable/development/editor/editor_style_guide.html#editor-style-guide) et un [Bonnes pratiques pour les contributeurs au moteur](https://docs.godotengine.org/fr/stable/community/contributing/best_practices_for_engine_contributors.html) destinés à celles qui souhaitent contribuer au développement du moteur lui-même.
## Principes de base
### Un manuel vivant
Ce manuel a vocation à rendre la contribution plus efficace, Khaganat est ouvert à la discussion et possède un canal XMPP où on peut échanger sur tout cela : [https://khaganat.net/irc/](https://khaganat.net/irc/).
### Respectez la loi
Khaganat respecte la loi française et vous demande de faire de même, donc merci de ne rien introduire d’illégal dans le projet par vos actions. En particulier :
- ne réemployez pas le travail d’autrui si vous n’en avez pas reçu l’autorisation explicite
- respectez les licences d’usage des éléments que vous souhaitez copier depuis un autre projet, en particulier si l’attribution est demandée (comme avec les licences CC BY)
- avant d’y apporter des éléments externes, vérifiez-en la compatibilité avec les licences du projet Khaganat
## Terminologie
### Identifiants
Un `Identifiant` est ce qu’on appelle communément un « nom » : celui d’un objet 3D, d’un fichier de son, d’un répertoire, d’une variable ou d’un script…
#### Caractères autorisés dans les identifiants
Dans un `Identifiant`, jamais on n’utilise un de ces caractères :
* les espaces
* les barres obliques ou barres obliques inverses `\`, `/`
* des symboles du genre `#!@$%`
* des caractères Unicode
Un `Identifiant` ne doit donc comprendre que les caractères suivants :
Ces règles permettent la plus grande compatibilité entre systèmes et pays.
#### L’usage des casses
Il y a plusieurs façon d’écrire les `Identifiants`, dont voici les plus courants (dénommés par leurs désignation en anglais, conventionnelle).
##### PascalCase
On met une majuscule à chaque mot et on supprime les espaces : `Coffre avec poignees` devient `CoffreAvecPoignees`.
##### camelCase
C’est similaire au PascalCase, sauf que la première lettre du premier mot est en minuscule : `Coffre avec poignees` devient `coffreAvecPoignees`.
Plus de précisions sur [Wikipédia](https://fr.wikipedia.org/wiki/Camel_case).
##### snake_case
Les espaces sont remplacés par des underscores « _ » : `Coffre avec poignees` devient `coffre_avec_poignees`
Bien que par convention, on puisse choisir de mettre ou pas des majuscules aux mots, nous retenons l’idée de tout mettre en minuscule pour nos usages du snake_case. `Coffre avec poignees` devient donc `coffre_avec_poignees`
Plus de précisions sur [Wikipédia](https://fr.wikipedia.org/wiki/Snake_case).
Les espaces sont remplacés par des tirets (le signe moins) « - » : `Coffre avec poignees` devient `coffre-avec-poignees`.
La désignation de cette casse n’est pas définitive, *kebab-case* semblant le plus fréquent, mais lisp l’utilise aussi depuis de très nombreuses années.
Les termes `Variable` et `Propriété` sont généralement interchangeables, mais si ils sont utilisés dans le même contexte, cela signifie plus précisément :
- pour `Propriété` que cela désigne une variable dans une classe.
- pour `Variable`, cela désigne généralement un argument de fonction ou une variable locale dans une fonction. Dans une classe, cela peut indiquer un statut à préciser/ définir.
Indépendamment de leur extension, les fichiers peuvent comporter trois parties, séparées chacune de la précédente par un **underscore** : préfixe, corps et suffixe. Le préfixe et le suffixe sont déterminés par le type de fichier (son extension donc).
Sauf indication contraire, tous les éléments internes aux fichiers Blender doivent être écrits en *kebab-case*. Le recours à un préfixe ou suffixe sera indiqué le cas échéant.
Les *Objects* doivent être rassemblé dans des sous-collections pertinentes, et il faut veiller à ce que l’*Object Data qui y est associé soit nommé de façon identique.*
Le dépôt de référence et sa branche principale « main » doivent avoir un historique le plus propre possible. C’est la raison pour laquelle il convient de toujours travailler par le biais de forks et de merge requests via la forge gitlab de Khaganat : https://git.numenaute.org/khaganat.
Cela permet à chaque contributrice de travailler en local via son propre fork distant. Elle peut ensuite proposer son code une fois prêt via une merge request qui sera auditée par une autre contributrice ayant l’accès au dépôt principal (rôle de **developper**, **maintainer** voire **owner** du dépôt principal). C’est lors de cette étape de validation avant fusion/merge qu’un contrôle sera opéré non seulement sur le code en lui-même, mais également sur la rédaction du message de [commit](#les-commits).
En cliquant sur le bouton « Fork » sur le projet principal, vous allez créer une copie distante sur la forge Gitlab, ce sera votre dépôt de développement depuis lequel vous pourrez opérer des merge request. Vous pouvez le gérer comme bon vous semble, mais dans le doute, vous pouvez laisser les options proposées par défaut si vous comptez simplement vous en servir comme base pour contribuer au code.
Une fois votre dépôt distant créé (appelé _origin remote_ dans le jargon Git), vous allez le copier sur votre ordinateur local pour travailler, cela se fait via la commande `git clone`.
Pour obtenir l’adresse à cloner, il faut cliquer sur le bouton « Clone » de l’interface gitlab sur la page d’accueil du dépôt. Vous pourrez choisir soit par _https_, soit par _ssh_. Préférez toujours de passer par _ssh_.
Une étape essentielle est ensuite d’ajouter le dépôt principal sur une branche locale de façon à pouvoir récupérer la dernière version du code du dépôt principal quand vous travaillez sur vos propres implémentations. Cela se fait en ajoutant une référence, appelée conventionnellement _upstream_ et pointant vers le dépôt principal, dont l’adresse est indiquée par le même bouton « Clone » sur sa page gitlab.
Et si jamais vous souhaitez ensuite mettre à jour votre dépôt distant (votre _fork_) :
git push
Cela enverra les modifications du dépôt principal que vous avez récupérées en local (via _upstream_) vers votre dépôt distant, ce qui le mettra à jour avec le dépôt du projet.
Pour implémenter votre code, il va falloir créer une branche dédiée, depuis la branche `main`. Vérifiez que vus êtes bien sur la bnranche `main` avant de la créer car c’est de celle-ci, la plus à jour possible depuis `upstream` (la branche `main` distante du dépôt principal), que vous devez travailler :
Vous pouvez ensuite basculer dessus pour commencer le travail
git checkout preference-file-creation
#### Mise à jour de la branche
Pensez à la mettre à jour régulièrement avec `upstream` afin de garantir la compatibilité de votre code avec les derniers ajouts :
git pull --rebase upstream main
L’option `rebase` permet de garantir que les changements que vous avez apportés seront intégrés à la fin de la branche, ce qui fait que seuls vos commits vous feront dévier du code de la branche `main` du dépôt officiel, sans occasionner de merge préalable. Cela simplifiera le merge ultérieur.
Si jamais lors du rebase, des conflits apparaissent, git s’arrêtera et vous demandera de régler le conflit (comme lors d’un merge classique), ce que vous ferez avec votre éditeur habituel. Puis vous reprendrez la suite du `rebase` avec la commande :
git rebase --continue
Recommencez autant de fois que nécessaire la gestion des conflits jusqu’à la fin de l’opération.
En cas de doute, si vous pensez avoir fait une erreur, vous pouvez annuler toute l’opération très aisément pour retrouver votre dépôt dans son état précédant le rebase avec la commande :
#### Envoyer ses modifications locales sur son propre dépôt de fork, distant
Une fois vos modifications réalisées sur votre branche, si cela fait un moment qu’elle n’a pas été mise à jour par rapport au projet principal, vous pouvez vous assurer que vos modificatins sont prises en compte en dernier (et ne provoquent pas de conflit) en tapant :
git pull --rebase upstream main
Vous pouvez ensuite envoyer vos modifications locales sur votre dépôt distant `origin` dans la branche sur laquelle vous travaillez :
git push origin preference-file-creation
#### Faire la demande de merge request
Vous devez vous connecter avec votre compte sur le serveur gitlab, aller dans votre fork distant et là, cliquer sur « merge request » dans la colonne de gauche. Puis vous cliquez sur « New merge request ».
Une nouvelle page s’ouvre alors. Normalement vous aurez kles deux dépôts corrects indiqués, à savir votre fork distant dans la partie gauche et le dépôt originel du projet dans la partie droite. Vous devez indiquer dans sa partie gauche votre branche de travail (`preference-file-creation` dans notre exemple) et ce sera la branche `main` du projet principal qui sera la cible (complété ainsi par défaut si tout va bien). Vous pouvez ensuite cliquer sur « compare branch and continue ».
Vous pouvez laisser le titre de votre commit ou le changer pour permettre de comprendre plus rapidement ce dont il s’agit. Vous pouvez compléter la description également. Vous pouvez laisser le reste tel qu’indiqué par défaut.
À partir de là, vous pourrez échanger avec les responsables du dépôt principal dans l’espace « Activity ». Vous avez les onglets « Overview », « Commits », « Pipelines » et « Changes » qui permettent de suivre ce que la Merge request comporte comme contenu.
#### Valider une « merge request » d’une contributrice
Si vous êtes suffisament impliquées dans le projet, vous aurez la possibiltié de valider des Merge request pour que la contribution soit ajoutée au dépôt principal. Vous pouvez voir les Merge requests en attente sur le dépôt principal du projet avec la section à gauche « Merge requests ». Vous avez sur la page plusieurs onglets, « Open », « Merged », « Closed » et « All ». C’est le premier qu’il convient de consulter pour les demandes en cours. Cela vous fournit une liste, vous pouvez cliquer sur celle que vous souhaitez étudier.
Vous pourrez échanger avec la contributrice et les autres mainteneuses du dépôt principal dans l’espace « Activity ». Vous avez les onglets « Overview », « Commits », « Pipelines » et « Changes » qui permettent de suivre ce que la Merge request comporte comme contenu. Les réponses, remarques etc. apparaissent dans leur ordre chronologique par défaut, mais cela peut se filtrer/changer avec les paramètres dans le menu déroulant à droite.
Lorsque le contenu vous semble correct pour une fusion dans la base principale, mais que vous ne souhaitez atrtendre d’autres avis, vous pouvez cliquer sur « Approve ». Cela signalera juste aux autres utilisatrices que vous êtes d’accord pour le merge.
Lorsque vous pensez que la contribution doit être intégrée au projet, vous pouvez cliquer sur « Merge », en laissant les autres options telles que par défaut. Vous pouvez également estimer qu’il faut d’autres validations / « Approvals » avant de faire cette opération.
Si vous estimez que la contribution n’est pas adaptée et doit être refusée, vous pouvez cliquer sur « Close merge request » qui fermera la demande sans intégrer son contenu au dépôt principal.
- **feat** : ajoute une fonctionnalité qui doit être mentionnée dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type _minor_ ou _major_, selon le cas, dans le versionnement).
- **fix** : résoud un bug qui doit être mentionné dans le pied de page avec un hashtag et son numéro de ticket (entraîne un changement de type _bugfix_ dans le versionnement).
- **refactor** : refactorisation du code sans modifier son comportement, ajouter une fonctionnalité ou réparer un bug (entraîne un changement de type _bugfix_ dans le versionnement).
- **removed** : effacement d’une partie jugée inutile, redondante ou obsolète (entraîne un changement de type _minor_ ou _major_, selon le cas, dans le versionnement).
- **security** : gestion d’une vulnérabilité (entraîne un changement de type _minor_ ou _major_, selon le cas dans le versionnement).
- **style** : reprise formelle du code sans en modifier le fonctionnement (typos, espacements, tabulations etc.) (entraîne un changement de type _bugfix_ dans le versionnement).
Le cas échéant, il est possible d’ajouter de nouveaux types selon les besoins (se référer à [la convention Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) ou [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) par exemple). Il faut alors penser à modifier les scripts de génération de changelog en conséquence (ainsi que les conséquences sur les séquences de versionnement).
Indiquée entre parenthèses, en minuscule sans espace, elle permet de préciser éventuellement sur quel partie du code la modification porte.
Elle peut être choisie dans cette liste :
- **core** : concerne le code de base, les systèmes essentiels au fonctionnement du jeu
- **ui** : concerne l’interface utilisateur
- **shading** : concerne les shaders d’affichage
- **ia** : concerne l’intelligence artificielle des créatures en jeu
D’autres portées peuvent être ajoutées à la liste au fur et à mesure des besoins.
##### Rupture de compatibilité
Si le commit entraîne une rupture de compatibilité dans le code, le type doit se voir accoler un point d’exclamation avant les deux points, quel que soit son type (entraîne un changement de type _majeur_ dans le versionnement).Il faut alors également lui ajouter un pied de page avec la mention « BREAKING CHANGE: » suivi de la mention de l’endroit où la rupture s’opère.
##### Le sujet
Laissant une espace après les deux points, il ne comporte pas de majuscule au début ni de point à la fin.
Le sujet doit décrire en peu de mot le changement qu’opère le nouveau code.
Exemples de première ligne correcte :
feat(ui)!: change methods for IG windows, close #18
fix(core): address collision problems for player, close #37
feat: add color wheel for windows background, close #16
##### Corps de description
Facultatif, il permet de décrire de façon détaillée ce qui a motivé les choix opérés et mettre l’emphase sur les améliorations espérées par rapport à l’ancien état.
Il n’est pas utile de versionner le répertoire `.import/` situé à la racine d’un projet car son contenu peut être généré depuis les fichiers originaux et leur fichier de configuration annexe (avec l’extension `.import`, par exemple pour `icone.png` cela donne `icone.png.import`). Il convient donc d’ajouter le répertoire `.import/` dans le `.gitignore` comme c’est proposé dans [la documentation Godot](https://docs.godotengine.org/en/latest/tutorials/assets_pipeline/import_process.html#files-generated).
Les objets à destination du moteur de jeu Godot doivent être exportés au format glTF. Il faut pour cela sélectionner tous les objets à exporter puis aller dans `File > Export > glTF`, avec les options suivantes à vérifier particulièrement :
-`Format > glTF Embeddded`.
-`Copyright : Khaganat`.
- On peut cocher `Remember export settings` pour ne pas avoir à revérifier à chaque export de ces modèles.
Les objets animés avec une armature de déformation sont modélisés et conçus dans Blender, puis exportés vers Godot. Les principes appliqués proviennent des méthodes initiées par [Richard Lico](https://www.animationsherpa.com/), en particulier pour le développement du jeu [Moss](https://www.polyarcgames.com/moss/). Il s’agit de différencier les ressources et les outils, et de ne pas se préoccuper de ces derniers tant qu’ils permettent aux intervenants de travailler efficacement avec leurs outils propres et, surtout, façons personnelles. La documentation ne comporte que des instructions pour travailler sous Blender.
Le mesh de base est sauvegardé dans son propre fichier, et sera inséré avec un `Link` depuis le fichier où se trouve son armature de déformation. Il doit se situer à la racine de la collection `Khanat`, avec un weight painting adapté à son armature de déformation.
L’armature de déformation est conservée dans son propre fichier, sans rien d’autre dans sa collection`Khanat`. Elle peut être ainsi être utilisée par plusieurs meshes en créant un `Link`.
Afin de travailler une animation, il est possible de la récupérer dans le dépôt, où elle est sous format glTF. Une fois le fichier à récupérer identifié, il faut l’importer avec les préférences suivantes :
Une animation peut être éditée depuis n’importe quel fichier local, avec ses propre préférences de travail. Il suffit d’y importer le mesh avec son armature de déformation, puis d’appliquer à ce dernier le rig de contrôle souhaité qui permettra de procéder au travail de création/édition souhaité. Chaque animateur pourra recourir à la méthode qu’il préfère, comme le propose Richard Lico dans une conférence du GDC en 2018 ( [Animating Quill: Creating an Emotional Experience](https://www.youtube.com/watch?v=u3CzLVpuE4k&t=2011s)). Le studio [Dypsloom](https://dypsloom.com/) propose un addon spécialement développé pour ce genre de travail : [Rig On the Fly](https://gitlab.com/dypsloom/rigonthefly).
Il faut faire en sorte que l’animation devienne une ressource qui pourra être appelée dans un `Animation Player`. Travailer ainsi permettra de ne plus avoir à se soucier des scènes héritées, n’importe quel élément de ces dernières pouvant avoir été manipulée dans Godot depuis son importation. Appeler des ressources secondaires permet d’ajouter de nouveaux éléments importés qui se rapportent à d’autres éléments anciennement ajoutés également depuis une source externe.
Une fois les fichiers visibles dans l’arborescence de Godot (fichiers _.glb_) :
1. double-cliquer dessus permettra d’afficher la fenêtre des paramètres d’importations.
2. sélectionner à droite l’action à importer (`bone_turn`dans l’exemple ci-dessous) et paramétrer la partie `Save To File`en cochant `Enabled`et `Keep Custom Tracks`et en indiquant le chemin où la ressource sera enregistrée dans `Path`.
Lorsqu’on a importé un certain nombre de ressources d’animations qui peuvent concerner le même objet (typiquement les actions d’un mesh avec son armature), il est possible de les ajouter à la node `AnimationPlayer`qui l’anime :
1. sélectionner la node `AnimationPlayer`à compléter
2. aller en bas dans l’onglet `Animation`et cliquer sur le menu de cette zone, sélectionner `Manage Animations`
3. Dans la fenêtre popup qui s’ouvre, cliquer sur l’icône pour ouvrir une ressource existante et aller là où se trouve l’action à ajouter.
