khanat_gamedev_guide/README.md

305 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Guide de développement pour [Khaganat](https://khaganat.net)
Ce manuel est rédigé collaborativement en Markdown à ladresse suivante : <https://git.numenaute.org/khaganat/mmorpg_khanat/khanat_gamedev_guide>
## Sources et inspirations
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 quun [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 dillégal dans le projet par vos actions. En particulier :
- ne réemployez pas le travail dautrui si vous nen avez pas reçu lautorisation explicite
- respectez les licences dusage des éléments que vous souhaitez copier depuis un autre projet, en particulier si lattribution est demandée (comme avec les licences CC BY)
- avant dy apporter des éléments externes, vérifiez-en la compatibilité avec les licences du projet Khaganat
## Terminologie
### Identifiants
Un `Identifiant` est ce quon appelle communément un « nom » : celui dun objet 3D, dun fichier de son, dun répertoire, dune variable ou dun script…
#### Caractères autorisés dans les identifiants
Dans un `Identifiant`, jamais on nutilise 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 :
* ABCDEFGHIJKLMNOPQRSTUVWXYZ
* abcdefghijklmnopqrstuvwxyz
* 1234567890
* _ (avec parcimonie)
Pour résumer, un `Identifiant` doit pouvoir répondre à lexpression régulière `[A-Za-z0-9_]+`)
Ces règles permettent la plus grande compatibilité entre systèmes et pays.
#### Lusage 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
Cest 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 lidé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).
##### lisp-case / kebab-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 nest pas définitive, *kebab-case* semblant le plus fréquent, mais lisp lutilise aussi depuis de très nombreuses années.
#### Variables / Propriétés
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.
## Les types de fichiers
### Godot
- **.escn** : *Exported Scene Data*. Format utilisé pour exporter des scènes depuis Blender vers Godot.
- **.gd** : *Source Code*. Fichiers avec le code source natif de Godot.
- **.gdc** : *Compiled Script*. Fichiers compilés.
- **.gdshader** : *Shader Data*. Shader spécifique à Godot (du GLSL modifié).
- **.godot** : *Project. Fichier descriptif du projet.
- **.import** : *Import Settings Data*. Fichier sidecar aux formats externes, qui contient les paramètres dimport.
- **.material**: *Godot material*. Matériau.
- **.mesh** : *Mesh Data*. Informations sur la géométrie dun objet 3D.
- **.meshlib** : *Mesh Library*. Catalogue de meshes.
- **.oggstr** : *OGG Audio Data*. Fichier audio.
- **.pck** : *Game Package*. Paquet de jeu
- **.profile** : *Feature Profile Data*
- **.res** : *Binary Resource Data*. Ressource binaire.
- **.sample** : *Audio Sample Data*. Fichier audio.
- **.scn** : *Binary Scene Data*. Scène sous forme binaire.
- **.stex** : *Stream Texture Data*.
- **.tpz** : *Export Template Archive*.
- **.tres** : *Text Resource Data*. Fichier descriptif dune ressource.
- **.tscn** : *Text Scene Data*. Scène, élément de base dun projet.
## Convention de nommage
### Noms de fichiers
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).
#### Nommage des éléments internes aux fichiers
##### Blender
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.
###### Collections
Les objets destinés au jeu Khanat doivent être placés dans une collection nommée « khanat », située à la racine de la collection principale.
###### Objets
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.*
#### Godot
Les signaux doivent avoir un nom avec un verbe au passé, car cela indique un état qui vient dêtre connu par lémetteur.
Les fonctions doivent commencer par un verbe, voire un verbe avec un auxiliaire si elles retournent un booléen (« is_green », « has_been_healed »).
Les variables et les classes commencent généralement plutôt par un nom.
###### Export glTF
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.
- `Include > Limit to Selected Objects` coché.
- `Geometry > Apply modifiers` coché.
Les autres options par défaut conviennent.
## Le suivi de version avec Git
### Le dépôt principal
Le dépôt de référence et sa branche principale « main » doivent avoir un historique le plus propre possible. Cest 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 laccès au dépôt principal (rôle de **developper**, **maintainer** voire **owner** du dépôt principal). Cest lors de cette étape de validation avant fusion/merge quun 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).
### Forker sur gitlab / cloner en local
#### Forker : copie distante
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 emrge 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.
### Cloner : copie locale
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 ladresse à cloner, il faut cliquer sur le bouton « Clone » de linterface gitlab sur la page daccueil du dépôt. Vous pourrez choisir soit par _https_, soit par _ssh_. Préférez toujours de passer par _ssh_.
git clone ssh://git@port.numenaute.org:3543/yannk/khanat_gamedev_guide.git
Cela va copier le dépôt dans un sous-répertoire de lendroit où vous avez tapé la commande. Il vous faudra alors vous y déplacer pour travailler.
Une étape essentielle est ensuite dajouter 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 ladresse est indiquée par le même bouton « Clone » sur sa page gitlab.
git remote add upstream ssh://git@port.numenaute.org:3543/khaganat/mmorpg_khanat/khanat_gamedev_guide.git
git fetch upstream
Ces commandes passées lors de la création vous permettront de mettre toute branche de votre dépôt local en tapant :
git pull --rebase upstream main
Loption `rebase` nest pas obligatoire, mais sera nécessaire dans notre flux de travail.
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.
#### Le travail en local
Vous avez par défaut sur votre dépôt local la branch `main`. Vous pouvez le vérifier en tapant la commande :
git branch
et vous obtenez :
* main
Ce qui signifie quil nexiste que la branche `main` et que vous êtes actuellement positionné dessus (présence de lastérique devant)
Il faudra veiller à sa mise à jour régulière en tapant la commande :
git pull --rebase upstream main
### Gestion des branches
Pour implémenter votre code, il va falloir créer une branche dédiée, depuis la branche `main` :
git branch preference-file-creation
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
Loption `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 sarrêtera et vous demandera de régler le conflit (comme lors dun 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 lopération.
En cas de doute, si vous pensez avoir fait une erreur, vous pouvez annuler toute lopération très aisément pour retrouver votre dépôt dans son état précédant le rebase avec la commande :
git rebase --abort
### Le merge request
### Les commits
#### Généralités
Les messages de commit se rédigent en anglais de façon à faciliter la collaboration internationale.
#### Rédaction des commits
La rédaction des commits se base sur les [conventionnal commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) avec des spécificités.
Structure dun message de commit :
<type>(portée, facultative): sujet
<ligne vide> (si élément suivant présent)
Corps de description plus complète (un ou plusieurs paragraphes), facultatif
<ligne vide> (si élément suivant présent)
<pied de page>, facultatif
##### Les _types_
Les types de commits possibles sont les suivants :
- **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 _patch_ dans le versionnement).
- **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 _mineur_ dans le versionnement).
- **ci** : concerne le fonctionnement de la CI du dépôt.
- **docs** : reprise de la documentation du code sans toucher aux fonctionnalités.
- **refactor** : refactorisation du code sans modifier son comportement, ajouter une fonctionnalité ou réparer un bug.
- **style** : reprise formelle du code sans en modifier le fonctionnement (typos, espacements, tabulations etc.)
Le cas échéant, il est possible dajouter de nouveaux types selon les besoins (se référer à [la convention Angular](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) par exemple).
Le type doit être écrit en minuscule, sans espace.
##### La portée
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 linterface utilisateur
- **shading** : concerne les shaders daffichage
- **ia** : concerne lintelligence artificielle des créatures en jeu
Dautres 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 dexclamation 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 lendroit où la rupture sopè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 quopè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 lemphase sur les améliorations espérées par rapport à lancien état.
##### Pied de page
Il peut comporter deux éléments :
- si le commit clôt un ticket, il faut indiquer sur une ligne son numéro de la façon suivante : `« Close #58 »`
- si le commit entraîne une rupture de compatibilité, il doit comporter une ligne avec la mention « BREAKING CHANGES » en majuscules.
### Projets Godot
Il nest pas utile de versionner le répertoire `.import/` situé à la racine dun projet car son contenu peut être généré depuis les fichiers originaux et leur fichier de configuration annexe (avec lextension `.import`, par exemple pour `icone.png` cela donne `icone.png.import`). Il convient donc dajouter le répertoire `.import/` dans le `.gitignore` comme cest proposé dans [la documentation Godot](https://docs.godotengine.org/en/latest/tutorials/assets_pipeline/import_process.html#files-generated).
## License
CC BY SA Khaganat - 2022