winzik/docs/tutoriel.md

249 lines
9.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Tutoriel JumPHP de A à Z
Ce tutoriel va d'une machine vide à un jeu en ligne sur ton propre domaine, en HTTPS. Il faut compter
environ 30 minutes, dont la plupart à attendre Docker. English version: [tutorial.md](tutorial.md).
On y voit dans l'ordre :
- A. créer le projet ;
- B. passer l'assistant ;
- C. faire écrire le jeu par Claude Code ;
- D. jouer et tester ;
- E. le modifier soi-même ;
- F. le mettre dans le navigateur ;
- G. le mettre en ligne sur un serveur ;
- H. l'envoyer sur Git ;
- I. mettre JumPHP à jour.
---
## A. Créer le projet
**Prérequis** : une machine Linux, macOS ou Windows avec WSL2, et un terminal. Le reste (git, Docker...)
est proposé par l'assistant.
```bash
composer create-project jumphp/jumphp mon-jeu
```
Si tu n'as pas composer (ni PHP), deux autres façons donnent le même résultat :
```bash
# avec Docker
docker run --rm -it -v "$PWD":/app -w /app composer create-project jumphp/jumphp mon-jeu
cd mon-jeu && bin/jumphp
# avec git
git clone https://git.jumphp.net/jumphp/jumPhp.git mon-jeu && cd mon-jeu && bin/jumphp
```
Le dossier `mon-jeu` contient tout JumPHP :
| Dossier | Contenu |
|---|---|
| `engine/` | le moteur |
| `skeleton/` | le squelette d'un jeu |
| `games/` | les jeux d'exemple : pong, jumpball en 3D, casse-briques... |
| `bin/jumphp` | la CLI |
| `AGENTS.md` | le guide complet, pour les humains comme pour les IA |
Il est relié au dépôt JumPHP par git, sous le remote `jumphp`.
## B. L'assistant
Avec composer, l'assistant démarre tout seul. Sinon, lance `bin/jumphp`. Il pose ses questions une par une
et demande toujours avant d'agir. Entrée accepte la réponse entre crochets. Ctrl+C l'arrête, et
`bin/jumphp init` le reprend.
1. **Outils.** git, curl et Docker sont vérifiés, et l'assistant propose d'installer ceux qui manquent. Sous
Linux, il ajoute aussi ton utilisateur au groupe `docker`. PHP, composer, emscripten et le serveur web
tournent dans Docker : tu n'as rien d'autre à installer.
2. **Ton jeu.** Il demande :
- le **nom** affiché (par exemple `Space Race`) ;
- l'**identifiant** : le dossier `games/space-race`, qui sert aussi d'adresse web ;
- une phrase de **description** ;
- la **résolution** : 320×180 par défaut. Ce sont les pixels du jeu, agrandis à la taille de la fenêtre ;
- la **langue** par défaut.
L'assistant construit l'image Docker du runtime (environ 5 min la première fois), puis crée le jeu à
partir du squelette, un petit jeu de plateforme.
3. **Moteur navigateur.** Prends « le télécharger » : environ 10 Mo, au lieu de 25 min de compilation.
Accepte ensuite le premier test.
4. **Serveur.** Tu peux le faire maintenant ou plus tard : voir la partie G.
5. **GitHub.** Tu peux le faire maintenant ou plus tard : voir la partie H.
6. **Claude Code.** Écris en quelques lignes ce que doit faire ton jeu, puis une ligne vide. Par exemple :
```
Un shoot'em up vertical : le vaisseau tire sur des vagues d'aliens, un boss tous les 3 niveaux,
des bonus (tir double, bouclier), 3 vies, meilleur score sauvegardé. Jouable au clavier, à la manette
et sur téléphone.
```
L'assistant écrit `games/space-race/BRIEF.md`. C'est ton texte, complété par tout ce que Claude doit savoir :
lire AGENTS.md, tester, regarder les captures, et ne rien publier sans te demander. Il lance ensuite Claude
Code avec ce prompt, après avoir proposé de l'installer s'il manque.
## C. Claude écrit le jeu
Claude lit `AGENTS.md`, remplace le squelette par ton jeu, puis vérifie son travail tout seul :
- `bin/jumphp test space-race` : lint, analyse statique, et 600 images jouées sans écran ;
- `bin/jumphp shot space-race` : des captures PNG qu'il regarde ;
- la version navigateur, avec `bin/jumphp build` puis `bin/jumphp webshot`.
Demande-lui des changements comme à un collègue : « des ennemis plus rapides au niveau 2 »,
« un mode 2 joueurs », « traduis en anglais »... Pour le relancer plus tard :
`claude "$(cat games/space-race/BRIEF.md)"`, ou simplement `claude` dans le dossier.
## D. Jouer et tester
```bash
bin/jumphp run space-race # dans une fenêtre, avec le son
bin/jumphp test space-race # tous les contrôles
bin/jumphp shot space-race 120 # capture après 2 s : games/space-race/var/screenshots/shot.png
```
Les touches de base :
| Touche | Action |
|---|---|
| flèches + Entrée | menus |
| Échap | pause / retour |
| F11 | plein écran |
| F3 | images par seconde |
Une manette branchée marche directement.
## E. Le modifier soi-même
Un jeu, c'est :
| Fichier | Contenu |
|---|---|
| `config/project.yaml` | titre, résolution, première scène, démo jouée par `test` |
| `config/input.yaml` | les actions (`jump`, `fire`...) associées aux touches, à la manette et au tactile |
| `config/lang.yaml` | les traductions |
| `src/Scene/*.php` | les écrans : titre, partie, pause, fin de partie |
| `src/Entity/*.php` | ce qui bouge |
Une scène minimale :
```php
<?php
namespace App\Scene;
use JumPHP\Renderer\Renderer;
use JumPHP\Scene\AbstractScene;
final class PlayScene extends AbstractScene
{
private float $x = 0;
public function enter(array $params = []): void
{
$this->x = 0; // la scène est réutilisée : tout remettre à zéro
}
public function update(float $dt): void // $dt en secondes
{
$this->x += $this->actions()->axis('left', 'right') * 100 * $dt;
}
public function render(Renderer $r): void
{
$r->clear([0, 0, 40]);
$r->fillRect($this->x, 80, 16, 16, '#ffcc00');
$this->font()->draw($r, 'HELLO', $this->width() / 2, 20, 2, [255, 255, 255], 'center');
}
}
```
Trois règles à retenir : ne jamais bloquer une image (pas de `sleep()`), passer par `bin/jumphp` pour tout,
et dessiner uniquement dans `render()`. Tout le reste est dans [AGENTS.md](../AGENTS.md) (en anglais) et dans
les autres pages de `docs/`. Les jeux de `games/` servent de modèles : pong pour les menus, l'IA et le jeu en
ligne, jumpball pour la 3D WebGL.
## F. Dans le navigateur
```bash
bin/jumphp build space-race # -> games/space-race/dist/web : des fichiers statiques
bin/jumphp serve space-race # http://localhost:8080
```
Le même code PHP tourne dans la page : PHP est compilé en WebAssembly, OpenGL y devient WebGL et OpenAL
Web Audio. Sur téléphone, une manette tactile apparaît.
## G. En ligne sur ton serveur
Il te faut :
- un serveur Linux joignable en SSH. Un petit VPS suffit, car le jeu est statique ;
- un nom de domaine dont l'enregistrement DNS **A** (et **AAAA** en IPv6) pointe vers ce serveur, par
exemple `space-race.example.com`.
```bash
bin/jumphp deploy:setup
```
Les questions :
1. **Accès SSH** (`utilisateur@machine`). Si la connexion demande un mot de passe, l'assistant propose de
créer une clé SSH et de l'installer sur le serveur (`ssh-copy-id`).
2. **Domaine** : `space-race.example.com`.
3. **Serveur web** :
- **FrankenPHP seul** : le plus simple. Les ports 80 et 443 doivent être libres sur le serveur, et le
certificat HTTPS est automatique ;
- **Traefik + FrankenPHP** : Traefik gère le HTTPS, et d'autres sites pourront venir derrière le même
Traefik ;
- **derrière un Traefik déjà installé** : l'assistant demande son réseau Docker, son point d'entrée et
son résolveur de certificats.
4. **E-mail Let's Encrypt** : il sert aux avis d'expiration.
5. **Dossier sur le serveur** : `/opt/jumphp/space-race` par défaut.
Si Docker manque sur le serveur, l'assistant l'installe (ou plus tard : `bin/jumphp server:setup`). Puis, et
à chaque nouvelle version du jeu :
```bash
bin/jumphp deploy
```
La commande construit le jeu, envoie seulement ce qui a changé, et lance `docker compose up -d` sur le
serveur. Le jeu est alors sur `https://space-race.example.com/`. La toute première visite peut prendre
quelques secondes, le temps que le certificat soit délivré. Pour voir les journaux du serveur web :
`bin/jumphp server:logs`. Pour mettre plusieurs jeux sur un même domaine (une page d'accueil et un dossier
par jeu) : `bin/jumphp deploy jeu1 jeu2`.
## H. Sur Git
```bash
bin/jumphp github
```
L'assistant fait le premier commit, installe `gh` et te connecte (`gh auth login`), puis crée le dépôt,
privé ou public. Avec un dépôt public, tu peux aussi publier le jeu gratuitement sur GitHub Pages :
`bin/jumphp pages space-race` le met sur `https://<compte>.github.io/<dépôt>/`.
## I. Mettre JumPHP à jour
```bash
bin/jumphp update # fusionne la dernière version de JumPHP (tes commits sont gardés)
bin/jumphp setup # images Docker, si le runtime a changé
bin/jumphp engine:download # moteur navigateur de la nouvelle version
```
---
## En cas de problème
| Symptôme | Solution |
|---|---|
| `docker: permission denied` | Ton utilisateur vient d'entrer dans le groupe `docker` : déconnecte-toi puis reconnecte-toi, ou lance `newgrp docker`, puis `bin/jumphp init`. |
| L'assistant ne démarre pas après composer | `cd mon-jeu && bin/jumphp` |
| Pas de fenêtre avec `bin/jumphp run` | Il faut un écran (X11 ou Wayland). Sans écran, utilise `bin/jumphp test` et `bin/jumphp shot`. |
| Pas de son | Il faut PulseAudio ou PipeWire. Le jeu marche quand même, sans son. |
| `engine:download` échoue | `bin/jumphp engine:build` (environ 25 min, une seule fois) |
| Le site ne répond pas en HTTPS | Vérifie que le DNS pointe vers le serveur et que les ports 80 et 443 sont ouverts, puis lance `bin/jumphp server:logs`. |
| La machine n'est pas reconnue | Installe Docker à la main (https://docs.docker.com/get-docker/), puis relance `bin/jumphp init`. |
Diagnostic de la machine : `bin/jumphp doctor`. Toutes les commandes : `bin/jumphp help`.