108 lines
3.4 KiB
Markdown
108 lines
3.4 KiB
Markdown
<!-- file: docs/architecture/005-ASSET_ARCHITECTURE.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# Architecture des assets
|
|
|
|
## Séparation physique
|
|
|
|
Les assets ne résident jamais dans les crates Rust. La racine `assets/` contient :
|
|
|
|
```text
|
|
assets/
|
|
├── common/
|
|
├── game-reflex-poc/
|
|
├── game-snake-poc/
|
|
└── <future-game>/
|
|
```
|
|
|
|
`assets/common/` ne contient que les ressources dont la mutualisation est réelle : fonts, UI générique, sons communs, icônes, particules ou shaders selon les besoins.
|
|
|
|
Chaque jeu possède son propre répertoire pour textures, audio, données, niveaux et autres ressources spécifiques.
|
|
|
|
## Espace logique
|
|
|
|
Le runtime doit éviter les collisions silencieuses. Une résolution logique peut distinguer :
|
|
|
|
```text
|
|
common://ui/button.png
|
|
game://textures/player.png
|
|
```
|
|
|
|
ou préserver des préfixes équivalents dans le package final.
|
|
|
|
## Packaging
|
|
|
|
Chaque plateforme assemble les deux sources sans créer de copie source durable dans la crate :
|
|
|
|
```text
|
|
assets/common/
|
|
+
|
|
assets/<game>/
|
|
=
|
|
package runtime du jeu
|
|
```
|
|
|
|
Desktop, Android et Web peuvent utiliser des mécanismes de packaging différents tout en conservant les mêmes noms logiques.
|
|
|
|
## Évolution
|
|
|
|
Un AssetManager commun pourra ultérieurement prendre en charge cache, loaders, textures, audio, fonts, données, erreurs, hot-reload de développement et éventuellement bundles. Ces capacités ne doivent être ajoutées qu'au rythme des besoins réels des jeux.
|
|
|
|
## Contrat V1 concret
|
|
|
|
À partir de `0.1.0-0-pre.9`, les URI logiques canoniques sont :
|
|
|
|
```text
|
|
common://<relative-path>
|
|
game://<relative-path>
|
|
```
|
|
|
|
`game-assets-lib` valide ces URI et les résout à partir de deux racines physiques explicites. Il interdit les chemins absolus, les traversées `..` et les séparateurs Windows injectés dans une URI logique.
|
|
|
|
Le layout runtime généré est identique sur toutes les plateformes :
|
|
|
|
```text
|
|
common/<relative-path>
|
|
game/<relative-path>
|
|
```
|
|
|
|
## Desktop
|
|
|
|
Le script `scripts/stage_game_assets.py` compose un package généré hors des sources.
|
|
|
|
Par défaut :
|
|
|
|
```text
|
|
../builds/sasedev-games/assets/<game>/
|
|
├── common/
|
|
└── game/
|
|
```
|
|
|
|
Le développement peut aussi résoudre directement les deux racines source sans staging.
|
|
|
|
## Android
|
|
|
|
Chaque variante Gradle enregistre une tâche `stage<Variant>SasedevAssets` et l'attache à `variant.sources.assets` avec `addGeneratedSourceDirectory`.
|
|
|
|
Le contenu final de l'APK conserve les namespaces :
|
|
|
|
```text
|
|
assets/common/...
|
|
assets/game/...
|
|
```
|
|
|
|
Les répertoires `build/generated/` restent des artefacts jetables.
|
|
|
|
## Web navigateur direct
|
|
|
|
Le POC Snake Web valide le même espace logique sans copier les sources dans `Web/`. Vite package explicitement les assets nécessaires depuis `assets/` vers :
|
|
|
|
```text
|
|
dist/common/data/runtime.json
|
|
dist/game/data/game.json
|
|
```
|
|
|
|
Le serveur Vite de développement expose les mêmes URL runtime. Le frontend charge donc `common://data/runtime.json` et `game://data/game.json` sous leurs chemins de distribution `./common/data/runtime.json` et `./game/data/game.json`, puis valide leur schéma avant de démarrer la session.
|
|
|
|
Cette première intégration ne transforme pas encore `game-assets-lib` en loader navigateur : la librairie Rust reste responsable de la validation/résolution de chemins physiques pour les hosts qui disposent d'un filesystem, tandis que Vite possède le packaging Web. Une abstraction commune ne sera extraite que si plusieurs hosts en ont réellement besoin.
|