- Externals service: list / search / stat / open the folders the playground's administrator shares with a game (server externals/ folder) - RemoteFile: read(offset, length), readNow(), prefetch(), readAll() with progress; only the 64 KB blocks read are downloaded (HTTP Range), consecutive blocks share a request, `parallel` requests at a time - BlockCache: memory LRU + persistent blocks in var/ (IndexedDB) - HttpTransport (the playground's ~list / ~search / ~stat / Range protocol), LocalTransport (folders of the computer for desktop and tests) - samples (browse, search, read), games/externals-demo (file browser), game and unit tests, doc/index.md, tutorial, docs/externals.md, AGENTS.md Co-Authored-By: Claude Opus 5.5 <[email protected]>
58 lines
3.1 KiB
Markdown
58 lines
3.1 KiB
Markdown
# Externals : de grosses données de jeu, lues par blocs depuis le serveur
|
|
|
|
Certains jeux ont besoin de données qui ne peuvent pas être dans leur dépôt public ni être téléchargées au lancement :
|
|
la version CD d'un jeu (ALIS), des collections de niveaux (dmmotor), des films. Les **externals** sont ces fichiers.
|
|
|
|
## Côté serveur (le playground)
|
|
|
|
- Sur la machine de production, le dossier des externals (variable `EXTERNALS_HOST_DIR` du déploiement) est monté
|
|
**en lecture seule** dans le conteneur du playground (`/app/var/externals`, variable `EXTERNALS_DIR`).
|
|
- On y range les données par jeu, avec des sous-dossiers : `externals/dmmotor/wads/…`, `externals/alis/…`.
|
|
- **Seul l'administrateur** donne l'accès : page Administration → *Externals*, un dossier partagé avec un ou plusieurs
|
|
projets (table `external_grant`). Un projet ne voit que les dossiers qui lui sont partagés (et leurs sous-dossiers).
|
|
- Les fichiers et dossiers dont le nom commence par un point ne sont jamais montrés ; un lien symbolique qui sort du
|
|
dossier est refusé.
|
|
- Détails, protocole et tests : `docs/externals.md` du dépôt jumphp-playground.
|
|
|
|
## Le protocole HTTP
|
|
|
|
Sur l'hôte du jeu, à côté de ses fichiers (`/<slug>/play/`) :
|
|
|
|
| Requête | Réponse |
|
|
|---|---|
|
|
| `GET /<slug>/play/externals/~list?dir=<chemin>&recursive=0\|1` | `{"dir", "entries": [{"path", "type": "file"\|"dir", "size", "mtime"}]}` ; `dir` vide = les dossiers partagés |
|
|
| `GET /<slug>/play/externals/~search?q=<texte ou motif>&dir=<chemin>` | idem, fichiers seulement (500 au plus) |
|
|
| `GET /<slug>/play/externals/~stat?path=<chemin>` | `{"path", "type", "size", "mtime", "etag"}` |
|
|
| `GET /<slug>/play/externals/<chemin>` avec `Range: bytes=a-b` | `206` et ces octets (`Accept-Ranges: bytes`) |
|
|
|
|
Non partagé : 403 ; absent : 404. Les chemins partent de la racine des externals (`dmmotor/wads/x.wad`).
|
|
Comme les fichiers du jeu, un fichier partagé se télécharge avec son adresse : ne partager que ce qui peut l'être.
|
|
|
|
## Côté jeu : l'extension `jumphp/externals`
|
|
|
|
```bash
|
|
bin/jumphp composer <jeu> require jumphp/externals
|
|
```
|
|
|
|
```php
|
|
public function __construct(private \JumPHP\Externals\Externals $externals) {}
|
|
|
|
$this->externals->list('dmmotor/wads', recursive: true)->then(fn (array $entries) => ...);
|
|
$this->externals->search('*.wad')->then(...);
|
|
$this->externals->open('dmmotor/wads/mod.wad')->then(fn ($f) => $f->read(0, 12)->then(fn ($bytes) => ...));
|
|
```
|
|
|
|
Un fichier se lit comme un disque : `read($offset, $longueur)` ne télécharge que les blocs de 64 Ko concernés (requête
|
|
HTTP Range ; les blocs qui se suivent partagent une requête), `readNow()` répond tout de suite quand c'est en cache (sinon
|
|
null, et le bloc est demandé), `readAll()` lit tout avec sa progression. Les blocs restent en cache en mémoire et dans
|
|
le stockage du joueur (IndexedDB) : un fichier lu une fois ne se retélécharge pas.
|
|
|
|
En local (bureau, tests), `project.yaml` fait correspondre des dossiers du jeu aux chemins du serveur :
|
|
|
|
```yaml
|
|
externals:
|
|
local: { "dmmotor/wads": "wads" }
|
|
```
|
|
|
|
Documentation complète, exemples et jeu de démonstration : `extensions/externals/` (`doc/index.md`, `doc/samples/`,
|
|
`games/externals-demo`).
|