95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
<!-- file: docs/architecture/005-ASSET_ARCHITECTURE.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# 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.
|