132 lines
6.4 KiB
Markdown
132 lines
6.4 KiB
Markdown
# Guide de développement pour [Khaganat](https://khaganat.net)
|
||
|
||
Ce manuel est rédigé collaborativement en Markdown à l’adresse 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 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 :
|
||
|
||
* ABCDEFGHIJKLMNOPQRSTUVWXYZ
|
||
* abcdefghijklmnopqrstuvwxyz
|
||
* 1234567890
|
||
* _ (avec parcimonie)
|
||
|
||
Pour résumer, un `Identifiant` doit pouvoir répondre à l’expression régulière `[A-Za-z0-9_]+`)
|
||
|
||
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).
|
||
|
||
##### 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 n’est pas définitive, *kebab-case* semblant le plus fréquent, mais lisp l’utilise 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 d’import.
|
||
- **.material**: *Godot material*. Matériau.
|
||
- **.mesh** : *Mesh Data*. Informations sur la géométrie d’un 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 d’une ressource.
|
||
- **.tscn** : *Text Scene Data*. Scène, élément de base d’un 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.*
|
||
|
||
## License
|
||
|
||
CC BY SA Khaganat - 2022
|