feat: add integration workflow guide for Blender export process
This commit is contained in:
@ -60,6 +60,12 @@ export default defineConfig({
|
|||||||
{ label: 'Import d\'objects depuis la librairie d\'asset', slug: 'blender/tutoriels/asset-library' },
|
{ label: 'Import d\'objects depuis la librairie d\'asset', slug: 'blender/tutoriels/asset-library' },
|
||||||
],
|
],
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
label: 'Intégration',
|
||||||
|
items: [
|
||||||
|
{ label: 'Workflow d\'Export', slug: 'blender/integration/export-workflow' },
|
||||||
|
],
|
||||||
|
},
|
||||||
{
|
{
|
||||||
label: 'Référence',
|
label: 'Référence',
|
||||||
items: [
|
items: [
|
||||||
|
|||||||
165
src/content/docs/blender/integration/export-workflow.mdx
Normal file
165
src/content/docs/blender/integration/export-workflow.mdx
Normal file
@ -0,0 +1,165 @@
|
|||||||
|
---
|
||||||
|
title: Workflow d'export de scène
|
||||||
|
description: Guide complet pour exporter une scène Blender vers le format GSFramework — GLTF composite, marks NML et props NML+GLTF.
|
||||||
|
---
|
||||||
|
|
||||||
|
import { Aside, Steps, Badge } from '@astrojs/starlight/components';
|
||||||
|
|
||||||
|
Ce guide décrit les trois étapes d'un export complet d'une scène : la géométrie statique via l'export composite, les marks de jeu en NML, et les props dynamiques en NML + GLTF.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Vue d'ensemble
|
||||||
|
|
||||||
|
Un export complet produit trois artefacts distincts :
|
||||||
|
|
||||||
|
| Artefact | Opérateur | Destination |
|
||||||
|
|---|---|---|
|
||||||
|
| Subscènes GLTF + manifeste | **Export Composite Scene** | Dossier de sortie choisi |
|
||||||
|
| Marks | **Export Marks NML** | `app/scenes/marks/<nom_de_scene>.nml` |
|
||||||
|
| Props géométrie | **Export Props NML + GLTF** | `app/scenes/trees/<nom_de_scene>/` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Étape 1 — Export Composite Scene
|
||||||
|
|
||||||
|
L'export principal se lance depuis **File → Export → Composite Scene (.gltf + .scene.json)** ou depuis le panel latéral *NMS Export → Composite Scene Export*.
|
||||||
|
|
||||||
|
Il décompose la scène en **subscènes** (une par collection linkée) et génère un fichier manifeste `.scene.json` qui décrit l'assemblage.
|
||||||
|
|
||||||
|
### Options disponibles
|
||||||
|
|
||||||
|
#### Scene Name
|
||||||
|
Nom logique de la scène. Il est utilisé comme préfixe pour tous les fichiers générés (manifeste, subscènes, NML…). Si laissé vide, le nom du fichier `.blend` courant est utilisé.
|
||||||
|
|
||||||
|
<Aside type="tip">
|
||||||
|
Notez bien ce nom : vous l'utiliserez pour nommer les fichiers NML aux étapes suivantes.
|
||||||
|
</Aside>
|
||||||
|
|
||||||
|
#### Apply Modifiers
|
||||||
|
Si activé (défaut), les modifiers Blender (Subdivision, Mirror, etc.) sont appliqués avant l'export. Les objets du fichier Blender source ne sont pas modifiés.
|
||||||
|
|
||||||
|
#### Deduplicate Textures
|
||||||
|
Fusionne les textures identiques (comparaison par hash XXH3) dans un dossier `textures/` partagé plutôt que de les dupliquer dans chaque subscène. Recommandé pour les scènes avec de nombreuses collections réutilisant les mêmes matériaux.
|
||||||
|
|
||||||
|
<Aside type="caution">
|
||||||
|
Cette option est marquée *expérimentale*. Sur des scènes très larges, le post-traitement peut prendre plusieurs minutes.
|
||||||
|
</Aside>
|
||||||
|
|
||||||
|
#### Convert Textures to DDS (BC7)
|
||||||
|
*Disponible uniquement si Deduplicate Textures est activé.*
|
||||||
|
|
||||||
|
Convertit et redimensionne les textures vers le format **DDS BC7_UNORM** à l'aide de `texconv.exe`. Le chemin vers `texconv.exe` doit être configuré dans les préférences de l'addon.
|
||||||
|
|
||||||
|
#### DDS Max Resolution
|
||||||
|
*Disponible uniquement si la conversion DDS est activée.*
|
||||||
|
|
||||||
|
Résolution maximale (largeur et hauteur) des textures converties. Les textures plus grandes seront réduites à cette taille. Valeur par défaut : **1024 px** ; plage : 64 – 8192.
|
||||||
|
|
||||||
|
#### Single Subscene Mode
|
||||||
|
Exporte l'intégralité de la scène comme **une seule subscène** sans décomposition par collection. Utile pour les scènes qui ne contiennent pas de collections linkées, ou lorsque vous souhaitez conserver toute la hiérarchie et toutes les données dans un unique fichier GLTF.
|
||||||
|
|
||||||
|
<Aside>
|
||||||
|
En mode Single Subscene, l'option *Skip Unchanged Subscenes* est désactivée.
|
||||||
|
</Aside>
|
||||||
|
|
||||||
|
#### Skip Unchanged Subscenes
|
||||||
|
En mode standard (pas Single Subscene), compare le hash XXH3 du fichier `.blend` source de chaque collection avec celui enregistré dans le manifeste précédent. Les subscènes non modifiées sont ignorées, ce qui accélère les exports incrémentaux.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Étape 2 — Export Marks NML
|
||||||
|
|
||||||
|
Les marks sont des points de placement (spawn points, triggers, zones d'intérêt…) associés aux blocs de la scène. Ils sont exportés séparément de la géométrie.
|
||||||
|
|
||||||
|
### Lancer l'export
|
||||||
|
|
||||||
|
Dans le panel *NMS Export → Dynamic Objects (NML)*, cliquez sur **Export Marks NML**.
|
||||||
|
Ou via **File → Export → Export Marks NML**.
|
||||||
|
|
||||||
|
### Destination et nommage
|
||||||
|
|
||||||
|
<Steps>
|
||||||
|
1. Dans le file browser, naviguez vers `app/scenes/marks/`.
|
||||||
|
2. Nommez le fichier en reprenant **exactement** le nom de scène utilisé à l'étape 1.
|
||||||
|
|
||||||
|
```
|
||||||
|
app/scenes/marks/<nom_de_scene>.nml
|
||||||
|
```
|
||||||
|
|
||||||
|
*Exemple :* si la scène s'appelle `city_01`, le fichier sera `app/scenes/marks/city_01.nml`.
|
||||||
|
3. Cliquez **Export Marks NML**.
|
||||||
|
</Steps>
|
||||||
|
|
||||||
|
### Contenu généré
|
||||||
|
|
||||||
|
Le fichier NML produit contient un bloc `BlocksExtraction` avec, pour chaque bloc de la scène, la liste de ses marks (`<Marks=…>`). Les coordonnées sont converties automatiquement de l'espace Blender (Z-up) vers l'espace NMS (Y-up).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Étape 3 — Export Props NML + GLTF
|
||||||
|
|
||||||
|
Les props sont des objets géométriques dynamiques (mobilier, éléments de décor, véhicules…) qui ne font pas partie de la géométrie statique. Ils sont exportés sous la forme d'un fichier NML de références + un fichier GLTF contenant la bibliothèque de géométries uniques.
|
||||||
|
|
||||||
|
### Lancer l'export
|
||||||
|
|
||||||
|
Dans le panel *NMS Export → Dynamic Objects (NML)*, cliquez sur **Export Props NML + GLTF**.
|
||||||
|
Ou via **File → Export → Export Props NML + GLTF**.
|
||||||
|
|
||||||
|
### Destination et nommage
|
||||||
|
|
||||||
|
<Steps>
|
||||||
|
1. Créez (si nécessaire) le dossier `app/scenes/trees/<nom_de_scene>/`.
|
||||||
|
2. Dans le file browser, naviguez dans ce sous-dossier et nommez le fichier NML :
|
||||||
|
|
||||||
|
```
|
||||||
|
app/scenes/trees/<nom_de_scene>/<nom_de_scene>.nml
|
||||||
|
```
|
||||||
|
|
||||||
|
Le fichier GLTF est généré automatiquement au même emplacement avec le même nom de base :
|
||||||
|
|
||||||
|
```
|
||||||
|
app/scenes/trees/<nom_de_scene>/<nom_de_scene>.gltf
|
||||||
|
```
|
||||||
|
|
||||||
|
*Exemple :* pour la scène `city_01` :
|
||||||
|
```
|
||||||
|
app/scenes/trees/city_01/city_01.nml
|
||||||
|
app/scenes/trees/city_01/city_01.gltf
|
||||||
|
```
|
||||||
|
3. Cliquez **Export Props NML + GLTF**.
|
||||||
|
</Steps>
|
||||||
|
|
||||||
|
### Contenu généré
|
||||||
|
|
||||||
|
- **NML** : un bloc `BlocksExtraction` avec les entrées `<Trees=…>` — chaque prop référence son index de géométrie dans le GLTF et sa transformation dans l'espace NMS.
|
||||||
|
- **GLTF** : bibliothèque des géométries uniques (dédupliquées par nom de mesh). Seules les géométries effectivement référencées sont incluses.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Récapitulatif des chemins de sortie
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
└── scenes/
|
||||||
|
├── marks/
|
||||||
|
│ └── <nom_de_scene>.nml ← Étape 2
|
||||||
|
└── trees/
|
||||||
|
└── <nom_de_scene>/
|
||||||
|
├── <nom_de_scene>.nml ← Étape 3
|
||||||
|
└── <nom_de_scene>.gltf ← Étape 3
|
||||||
|
```
|
||||||
|
|
||||||
|
Le dossier de sortie de l'export composite (Étape 1) est libre — choisissez-le selon votre pipeline.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Objets exclus de l'export GLTF
|
||||||
|
|
||||||
|
Certains objets Blender sont automatiquement **exclus** de l'export GLTF composite car ils sont gérés par les étapes 2 et 3 :
|
||||||
|
|
||||||
|
- Objets portant la custom property `nml_source`
|
||||||
|
- Objets portant `nms_mark` ou `nms_marks_container`
|
||||||
|
- Objets dont le nom commence par `tree`, `prop`, `building`, `character` ou `wall`
|
||||||
|
|
||||||
|
Ces objets apparaissent dans le compteur *NML dynamic objects* de la section *Scene Analysis* du panel.
|
||||||
Reference in New Issue
Block a user