khanat_gamedev_guide/README.md

138 lines
7 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.*
## Le suivi de version avec Git
### 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