khanat_gamedev_guide/README.md

Guide de développement pour Khaganat

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 UE4 Style Guide » disponible sur GitHub.

Godot propose quelques conseils sur la façon de travailler pour son propre projet dans une section Les meilleures pratiques ainsi qu’un Guide de style et un Bonnes pratiques pour les contributeurs au moteur 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/.

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.

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.

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.

Le suivi de version avec Git

Projets Godot

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.

License

CC BY SA Khaganat - 2022