docs: Sphinx manuel joueur/admin/dev + build HTML
Manuel complet DauphinCraft v0.1.0 : 14 pages RST (joueur, admin, dev, annexes), conf.py rtd-theme, Makefile/make.bat, build HTML propre. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Floppyrj45
81
docs/dev/architecture.rst
Normal file
81
docs/dev/architecture.rst
Normal file
@@ -0,0 +1,81 @@
|
||||
Architecture technique
|
||||
=======================
|
||||
|
||||
Moteur et langage
|
||||
-----------------
|
||||
|
||||
+------------------+-----------------------------------------------+
|
||||
| Composant | Valeur |
|
||||
+==================+===============================================+
|
||||
| Moteur | Godot Engine 4.6.2 (Forward+) |
|
||||
+------------------+-----------------------------------------------+
|
||||
| Langage | GDScript (typage strict) |
|
||||
+------------------+-----------------------------------------------+
|
||||
| Rendu | Vulkan (Forward+) / Compatibility (fallback) |
|
||||
+------------------+-----------------------------------------------+
|
||||
| Réseau | ENet UDP, autorité serveur |
|
||||
+------------------+-----------------------------------------------+
|
||||
|
||||
Architecture réseau
|
||||
-------------------
|
||||
|
||||
DauphinCraft utilise un modèle **autorité serveur** :
|
||||
|
||||
- Le serveur est la source de vérité pour les positions, les blocs et les inventaires.
|
||||
- Les clients envoient leurs intentions (déplacement, action) et reçoivent l'état du monde.
|
||||
- La synchronisation est assurée par ``PlayerSyncComponent`` et ``WorldSyncComponent``.
|
||||
- Le protocole de transport est **ENet (UDP)** via la couche haut niveau Godot (``MultiplayerAPI``).
|
||||
- Port par défaut : **UDP 7777**.
|
||||
|
||||
Structure du projet
|
||||
-------------------
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
DauphinCraft/
|
||||
├── project.godot # Fichier de projet Godot
|
||||
├── icon.svg # Icône du jeu
|
||||
├── export_presets.cfg # Présets d'export (Windows, Linux serveur)
|
||||
├── assets/ # Ressources visuelles (textures, modèles)
|
||||
├── audio/ # Fichiers audio
|
||||
│ ├── music/ # Musiques de fond
|
||||
│ └── sfx/ # Effets sonores
|
||||
├── builds/ # Sorties d'export
|
||||
├── scenes/ # Scènes Godot (.tscn)
|
||||
│ ├── Main.tscn
|
||||
│ ├── MainMenu.tscn
|
||||
│ ├── LobbyMenu.tscn
|
||||
│ ├── World.tscn
|
||||
│ ├── Dolphin.tscn
|
||||
│ ├── InventoryUI.tscn
|
||||
│ ├── PauseMenu.tscn
|
||||
│ └── mobs/
|
||||
├── scripts/ # Scripts GDScript (.gd)
|
||||
│ ├── Main.gd
|
||||
│ ├── PauseMenu.gd
|
||||
│ ├── world/ # Gestion du monde voxel
|
||||
│ ├── dolphin/ # Contrôleur joueur + HUD
|
||||
│ ├── ambience/ # Environnement visuel et audio
|
||||
│ ├── inventory/ # Inventaire et crafting
|
||||
│ ├── mobs/ # Intelligence artificielle des mobs
|
||||
│ └── net/ # Réseau multijoueur
|
||||
├── shaders/ # Shaders GLSL/Godot
|
||||
└── docs/ # Documentation Sphinx (ce manuel)
|
||||
|
||||
Flux de démarrage
|
||||
-----------------
|
||||
|
||||
1. ``Main.tscn`` est la scène principale. Elle instancie ``MainMenu.tscn``.
|
||||
2. Le joueur choisit Solo / Héberger / Rejoindre dans ``LobbyMenu.tscn``.
|
||||
3. ``NetworkManager`` initialise ENet (serveur ou client).
|
||||
4. ``World.tscn`` est chargée : ``ChunkManager`` génère les premiers chunks.
|
||||
5. ``Dolphin.tscn`` est instanciée pour chaque joueur connecté.
|
||||
6. La boucle de jeu tourne : physique, synchronisation réseau, rendu.
|
||||
|
||||
Présets d'export
|
||||
----------------
|
||||
|
||||
Deux présets sont configurés dans ``export_presets.cfg`` :
|
||||
|
||||
- **Windows (64 bits)** : exécutable joueur pour Windows.
|
||||
- **Linux Server (64 bits)** : exécutable headless pour serveur dédié Linux.
|
||||
110
docs/dev/contribuer.rst
Normal file
110
docs/dev/contribuer.rst
Normal file
@@ -0,0 +1,110 @@
|
||||
Contribuer au projet
|
||||
====================
|
||||
|
||||
Outils nécessaires
|
||||
------------------
|
||||
|
||||
- **Godot Engine 4.6.2** : téléchargez depuis https://godotengine.org/download
|
||||
- **Git** : version 2.x ou supérieure
|
||||
- Accès au dépôt Gitea de DauphinCraft
|
||||
|
||||
Cloner le dépôt
|
||||
---------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone http://<gitea-host>/dauphincraft/dauphincraft.git
|
||||
cd dauphincraft
|
||||
|
||||
.. note::
|
||||
|
||||
Remplacez ``<gitea-host>`` par l'adresse du serveur Gitea communautaire.
|
||||
|
||||
Ouvrir le projet dans Godot
|
||||
-----------------------------
|
||||
|
||||
1. Lancez Godot Engine 4.6.2.
|
||||
2. Dans le gestionnaire de projets, cliquez sur **Import**.
|
||||
3. Naviguez jusqu'au dossier cloné et sélectionnez ``project.godot``.
|
||||
4. Cliquez sur **Import & Edit**.
|
||||
|
||||
Le projet s'ouvre directement dans l'éditeur. Appuyez sur **F5** pour lancer le jeu en mode éditeur.
|
||||
|
||||
Build et export
|
||||
---------------
|
||||
|
||||
Les présets d'export sont configurés dans ``export_presets.cfg``.
|
||||
|
||||
**Exporter pour Windows :**
|
||||
|
||||
1. Menu **Projet → Exporter**.
|
||||
2. Sélectionnez le préset **Windows Desktop**.
|
||||
3. Cliquez sur **Exporter le projet** et choisissez un dossier de sortie.
|
||||
|
||||
**Exporter le serveur Linux :**
|
||||
|
||||
1. Menu **Projet → Exporter**.
|
||||
2. Sélectionnez le préset **Linux Server**.
|
||||
3. Cliquez sur **Exporter le projet**.
|
||||
|
||||
.. note::
|
||||
|
||||
Pour exporter vers Linux, vous devez avoir installé le template d'export Linux dans Godot
|
||||
(**Éditeur → Gérer les modèles d'exportation**).
|
||||
|
||||
Style de code
|
||||
-------------
|
||||
|
||||
- **Typage strict** : déclarez toujours les types explicitement (``var x: int = 0``).
|
||||
- **Pas de TODO** laissé dans le code soumis — ouvrez une issue à la place.
|
||||
- **Nommage** : ``snake_case`` pour les variables et fonctions, ``PascalCase`` pour les classes.
|
||||
- **Commentaires** : en français, concis.
|
||||
- **Signals** : préfixez les signaux avec le nom du composant (``dolphin_died``, ``chunk_loaded``).
|
||||
|
||||
Exemple de code conforme :
|
||||
|
||||
.. code-block:: gdscript
|
||||
|
||||
class_name DolphinController
|
||||
extends CharacterBody3D
|
||||
|
||||
@export var speed: float = 5.0
|
||||
var _oxygen: float = 1.0
|
||||
|
||||
func take_damage(amount: int) -> void:
|
||||
# Réduit les PV et déclenche le signal si mort
|
||||
health -= amount
|
||||
if health <= 0:
|
||||
emit_signal("dolphin_died")
|
||||
|
||||
Soumettre une contribution
|
||||
---------------------------
|
||||
|
||||
1. Créez une branche depuis ``main`` :
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git checkout -b feat/ma-fonctionnalite
|
||||
|
||||
2. Faites vos modifications et committez :
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git add .
|
||||
git commit -m "feat: description courte"
|
||||
|
||||
3. Poussez votre branche :
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git push origin feat/ma-fonctionnalite
|
||||
|
||||
4. Ouvrez une **Pull Request** sur le Gitea de DauphinCraft.
|
||||
|
||||
5. Un mainteneur relit et fusionne après validation.
|
||||
|
||||
Discussion et support
|
||||
----------------------
|
||||
|
||||
Rejoignez le serveur Discord communautaire et consultez le canal **#dauphincraft-dev**
|
||||
pour poser vos questions, proposer des idées ou signaler des bugs.
|
||||
129
docs/dev/modules.rst
Normal file
129
docs/dev/modules.rst
Normal file
@@ -0,0 +1,129 @@
|
||||
Modules du jeu
|
||||
==============
|
||||
|
||||
Le code source est organisé en six modules dans ``scripts/``.
|
||||
|
||||
Module Monde (``world/``)
|
||||
--------------------------
|
||||
|
||||
Responsable de la génération et de la gestion du monde voxel sous-marin.
|
||||
|
||||
**BlockDatabase.gd**
|
||||
Registre central de tous les types de blocs (id, nom, texture, propriétés physiques).
|
||||
API publique : ``get_block(id: int) -> BlockData``, ``get_id_by_name(name: String) -> int``.
|
||||
|
||||
**Chunk.gd**
|
||||
Représente un chunk 16×16×16 blocs. Gère son maillage 3D et son état de chargement.
|
||||
API publique : ``set_block(x, y, z, id)``, ``get_block(x, y, z) -> int``, ``rebuild_mesh()``.
|
||||
|
||||
**ChunkManager.gd**
|
||||
Orchestre le chargement/déchargement des chunks autour du joueur (rayon configurable).
|
||||
API publique : ``get_chunk(cx, cy, cz) -> Chunk``, ``request_chunk(pos: Vector3i)``.
|
||||
|
||||
**WorldGenerator.gd**
|
||||
Génère le contenu des chunks de façon procédurale (bruit de Perlin, biomes, structures).
|
||||
API publique : ``generate_chunk(cx, cy, cz) -> Array`` (tableau de 4096 block ids).
|
||||
|
||||
Module Dauphin (``dolphin/``)
|
||||
------------------------------
|
||||
|
||||
Contrôle du personnage joueur et interface utilisateur associée.
|
||||
|
||||
**DolphinController.gd**
|
||||
Gère les entrées clavier/souris, applique la physique de nage, envoie les actions au serveur.
|
||||
API publique : ``apply_input(input: Dictionary)``, ``take_damage(amount: int)``.
|
||||
|
||||
**HUD.gd**
|
||||
Affiche les jauges (oxygène, vie, faim), la hotbar et les notifications.
|
||||
API publique : ``update_oxygen(value: float)``, ``update_health(value: float)``,
|
||||
``update_hunger(value: float)``.
|
||||
|
||||
**EcholocationPulse.gd**
|
||||
Crée et anime l'impulsion sphérique d'écholocation. Détecte les mobs et blocs dans le rayon.
|
||||
API publique : ``emit_pulse(origin: Vector3, radius: float)``.
|
||||
|
||||
Module Ambiance (``ambience/``)
|
||||
--------------------------------
|
||||
|
||||
Environnement visuel et sonore sous-marin.
|
||||
|
||||
**UnderwaterEnvironment.gd**
|
||||
Configure le fog volumétrique, la lumière directionnelle atténuée et les effets de post-process
|
||||
selon la profondeur du joueur. API publique : ``set_depth(depth: float)``.
|
||||
|
||||
**AudioManager.gd**
|
||||
Singleton audio. Gère les pistes de musique et les effets sonores avec transitions douces.
|
||||
API publique : ``play_sfx(name: String)``, ``play_music(name: String)``, ``stop_music()``.
|
||||
|
||||
**PlanktonParticles.gd**
|
||||
Système de particules generant le plancton lumineux ambiant.
|
||||
API publique : ``set_density(density: float)``.
|
||||
|
||||
**MainMenu.gd**
|
||||
Logique du menu principal (navigation, transitions de scène).
|
||||
|
||||
Module Inventaire (``inventory/``)
|
||||
-----------------------------------
|
||||
|
||||
Gestion des ressources, recettes et interface d'inventaire.
|
||||
|
||||
**Inventory.gd**
|
||||
Stockage des items du joueur (tableau de slots). Synchronisé avec le serveur en multijoueur.
|
||||
API publique : ``add_item(id: int, qty: int) -> bool``, ``remove_item(id: int, qty: int) -> bool``,
|
||||
``has_item(id: int, qty: int) -> bool``.
|
||||
|
||||
**ItemDatabase.gd**
|
||||
Registre de tous les items (id, nom, icône, stack max).
|
||||
API publique : ``get_item(id: int) -> ItemData``.
|
||||
|
||||
**CraftingRecipes.gd**
|
||||
Définit les 5 recettes de craft et expose la logique de fabrication.
|
||||
API publique : ``get_available_recipes(inventory: Inventory) -> Array``,
|
||||
``craft(recipe_id: int, inventory: Inventory) -> bool``.
|
||||
|
||||
**InventoryUI.gd**
|
||||
Interface graphique de l'inventaire et du panneau de crafting.
|
||||
API publique : ``open()``, ``close()``, ``refresh()``.
|
||||
|
||||
Module Mobs (``mobs/``)
|
||||
------------------------
|
||||
|
||||
Intelligence artificielle des créatures marines.
|
||||
|
||||
**FishSchool.gd**
|
||||
Comportement de banc de poissons (alignment, cohesion, separation — boids simplifié).
|
||||
Fuit le joueur à proximité. API publique : ``set_school_size(n: int)``.
|
||||
|
||||
**Jellyfish.gd**
|
||||
Déplacement oscillant aléatoire. Inflige des dégâts de contact au joueur.
|
||||
API publique : ``get_damage() -> int``.
|
||||
|
||||
**Shark.gd**
|
||||
IA hostile : détection du joueur, poursuite, attaque, réaction à l'écholocation (fuite).
|
||||
API publique : ``stun(duration: float)``.
|
||||
|
||||
**MobSpawner.gd**
|
||||
Gère l'apparition des mobs selon le biome et la profondeur, avec limite de population.
|
||||
API publique : ``spawn_in_chunk(chunk_pos: Vector3i)``.
|
||||
|
||||
Module Réseau (``net/``)
|
||||
-------------------------
|
||||
|
||||
Infrastructure multijoueur ENet.
|
||||
|
||||
**NetworkManager.gd**
|
||||
Singleton réseau. Initialise ENet, gère les connexions/déconnexions joueurs, expose les RPCs.
|
||||
API publique : ``host_game(port: int)``, ``join_game(ip: String, port: int)``,
|
||||
``disconnect()``.
|
||||
|
||||
**PlayerSyncComponent.gd**
|
||||
Attaché à chaque ``Dolphin``. Synchronise position, rotation et état sur le réseau.
|
||||
API publique : ``sync_state(state: Dictionary)``.
|
||||
|
||||
**WorldSyncComponent.gd**
|
||||
Synchronise les modifications de blocs entre serveur et clients.
|
||||
API publique : ``broadcast_block_change(pos: Vector3i, block_id: int)``.
|
||||
|
||||
**ChatManager.gd**
|
||||
Gère l'envoi et la réception des messages de chat en multijoueur.
|
||||
API publique : ``send_message(text: String)``, ``on_message_received(sender: String, text: String)``.
|
||||
Reference in New Issue
Block a user