Un projet JumPHP : création, assistant, serveur, GitHub
Créer le projet
composer create-project jumphp/jumphp mon-jeu
Composer télécharge JumPHP : le moteur, le squelette, les jeux d'exemple, les outils et la CLI bin/jumphp.
Le paquet racine n'a aucune dépendance PHP, donc rien n'est exigé de la machine à part composer lui-même.
Ensuite, tools/post-create.sh :
- relie le dossier au dépôt JumPHP (
git init, remotejumphp, rattachement au commit de cette version). Le projet a ainsi l'historique du framework : tes commits viennent par-dessus, etbin/jumphp updatefusionne plus tard les nouvelles versions (git pull jumphp main) ; - lance l'assistant (
bin/jumphp init) sur le terminal.
Si l'assistant ne peut pas démarrer (composer lancé dans Docker, CI, pas de terminal), la commande s'arrête
avec la suite à taper : cd mon-jeu && bin/jumphp.
Autres façons de faire, qui donnent le même résultat :
# sans PHP sur la machine
docker run --rm -it -v "$PWD":/app -w /app composer create-project jumphp/jumphp mon-jeu
cd mon-jeu && bin/jumphp
# avec git seulement
git clone https://git.jumphp.net/jumphp/jumPhp.git mon-jeu && cd mon-jeu && bin/jumphp
Dans ce dernier cas, origin désigne le dépôt JumPHP. L'étape Git de l'assistant le renomme en jumphp
et crée ton propre origin.
L'assistant (bin/jumphp init)
bin/jumphp lancé sans argument démarre l'assistant tant que le projet n'a pas de jeu (JUMPHP_GAME vide
dans .env). Ensuite, il affiche l'aide. Chaque étape demande avant d'agir. Ctrl+C l'arrête à tout moment,
et bin/jumphp init reprend là où il en était : les étapes déjà faites sont reconnues. Les textes sont en
français quand la langue du système l'est (JUMPHP_LANG=en pour forcer l'anglais).
-
Outils. L'assistant vérifie que git, curl et Docker (avec Compose et Buildx) sont présents, et propose d'installer ceux qui manquent avec le gestionnaire de paquets du système : apt, dnf, pacman, zypper, apk ou Homebrew. Docker s'installe avec le script officiel de Docker sur Debian, Ubuntu et Fedora, et avec Docker Desktop sur macOS. L'utilisateur est ajouté au groupe
docker, et l'assistant continue dans un shell qui a ce groupe. PHP, composer, emscripten et le serveur web tournent dans Docker : il n'y a rien d'autre à installer. -
Ton jeu. Les questions portent sur :
- le nom (titre affiché) ;
- l'identifiant (dossier
games/<id>, adresse web) ; - une phrase de description ;
- la résolution virtuelle : 320×180, 256×224, 320×240 ou 480×270 ;
- la langue par défaut.
L'assistant construit ensuite l'image Docker du runtime (environ 5 min la première fois), puis crée le jeu depuis le squelette (
bin/jumphp new). Il écritJUMPHP_GAME=<id>dans.env. Les jeux d'exemple peuvent être retirés ; pong reste toujours, c'est le jeu de référence d'AGENTS.md. -
Moteur navigateur. Tu choisis entre :
- le télécharger déjà compilé (
bin/jumphp engine:download) : c'est l'archivejumphp-engine.tar.gzde la release GitHub de la version (VERSION), vérifiée avec son sha256 ; - le compiler sur place (
bin/jumphp engine:build, environ 25 min) ; - le faire plus tard.
L'assistant propose ensuite un premier
bin/jumphp test <id>. - le télécharger déjà compilé (
-
Serveur (facultatif, voir plus bas).
-
GitHub. L'assistant fait le premier commit, avec le nom et l'e-mail git demandés s'ils ne sont pas configurés (ils sont enregistrés dans ce projet seulement). Il propose d'installer la CLI
ghet de se connecter (gh auth login), puis crée le dépôt, privé ou public, avecgh repo create --source . --remote origin --push. Si le dépôt est public, il propose aussi de publier le jeu sur GitHub Pages (bin/jumphp pages <id>). Pour faire cette étape seule :bin/jumphp github. -
Claude Code. Tu décris seulement ce que doit faire ton jeu, en quelques lignes. L'assistant écrit et commite
games/<id>/BRIEF.md, un prompt complet qui rappelle :- de lire AGENTS.md ;
- de remplacer le squelette ;
- de prendre les jeux d'exemple comme modèles ;
- de tester et de regarder les captures ;
- la définition de « fini » ;
- de demander avant de publier quoi que ce soit.
Il propose d'installer Claude Code (installateur officiel
claude.ai/install.sh) s'il manque, puis le lance avec ce prompt. Pour le relancer plus tard :claude "$(cat games/<id>/BRIEF.md)". Pour refaire cette étape seule :bin/jumphp init --claude.
bin/jumphp init --yes prend toutes les réponses par défaut, n'installe aucun outil, ne crée pas de dépôt
Git et ne lance pas Claude. C'est utile pour les tests et la CI.
Déployer sur un serveur
Un jeu JumPHP est un site statique, puisque PHP tourne dans le navigateur du joueur. Un petit serveur Linux
avec Docker suffit. La configuration se fait avec bin/jumphp deploy:setup (l'étape 4 de l'assistant), qui
demande :
-
l'accès SSH (
utilisateur@machine). Si la connexion sans mot de passe ne marche pas, l'assistant propose de créer une clé et de l'installer sur le serveur avecssh-copy-id; -
le nom de domaine. Son enregistrement DNS A/AAAA doit pointer vers le serveur pour que Let's Encrypt puisse délivrer le certificat ;
-
le serveur web :
Mode Ce qui tourne sur le serveur Quand le choisir frankenphpFrankenPHP seul, ports 80 et 443, HTTPS automatique (Caddy + Let's Encrypt) un serveur dédié au jeu, le plus simple traefikTraefik (ports 80/443, Let's Encrypt, redirection HTTP → HTTPS) devant FrankenPHP pour héberger d'autres sites ensuite derrière le même Traefik (réseau Docker jumphp-traefik)traefik-externalFrankenPHP seul, branché sur le réseau d'un Traefik déjà installé le serveur a déjà son Traefik, avec un résolveur de certificats qui marche : l'assistant lit sur le serveur son réseau Docker, son point d'entrée HTTPS et son résolveur ( bin/jumphp server:traefik)traefik-passthroughFrankenPHP seul, derrière un Traefik déjà installé qui laisse passer le TLS ; FrankenPHP obtient lui-même son certificat le Traefik du serveur n'a pas de résolveur de certificats qui marche (aucun site ne s'en sert) : l'assistant le détecte et choisit ce mode ; points d'entrée :443 et :80 dans JUMPHP_TRAEFIK_ENTRYPOINT/JUMPHP_TRAEFIK_HTTP_ENTRYPOINT -
l'e-mail Let's Encrypt (modes
frankenphpettraefik) ; -
le dossier sur le serveur (par défaut
/opt/jumphp/<id>).
Tout est enregistré dans .env (JUMPHP_SERVER, JUMPHP_DOMAIN, JUMPHP_SERVER_MODE...). Si Docker
manque sur le serveur, bin/jumphp server:setup l'installe par SSH (script officiel de Docker) et ajoute
l'utilisateur au groupe docker.
bin/jumphp deploy fait alors, dans l'ordre :
- construit la version navigateur du jeu (
JUMPHP_GAME), ou de plusieurs jeux :bin/jumphp deploy jeu1 jeu2, ouJUMPHP_DEPLOY_GAMES="jeu1 jeu2". Avec plusieurs jeux, le site a une page d'accueil et un dossier/jeu1/,/jeu2/par jeu. Un seul jeu qui a son propre site (games/<id>/site/index.html: page d'accueil, images,robots.txt...) : le site est à la racine et le jeu dans/play/;{{DOMAIN}}y est remplacé parJUMPHP_DOMAIN(liens canoniques, sitemap) ; - prépare
.build/server/:site/, lecompose.yamldu mode (docker/server/<mode>/), le Caddyfile et un.env; - l'envoie avec
rsync(seuls les fichiers modifiés partent) ; - lance
docker compose up -dsur le serveur. Les conteneurs ne sont recréés que si la configuration a changé : une simple mise à jour du jeu ne coupe rien ; - attend (2 minutes au plus) que
https://<domaine>/réponde avec un certificat valide ; sinon il affiche l'état et les journaux du conteneur, et ce qu'il faut vérifier (DNS, points d'entrée de Traefik).
Les journaux du serveur web s'affichent avec bin/jumphp server:logs. Les certificats restent dans des
volumes Docker (caddy_data ou letsencrypt) : ils survivent aux déploiements.
Sans JUMPHP_SERVER, bin/jumphp deploy <jeu> garde l'ancien comportement : un rsync de dist/web vers
JUMPHP_DEPLOY_TARGET, pour un hébergement statique existant.
Mettre JumPHP à jour
bin/jumphp update # git pull jumphp main (fusion : tes commits sont gardés)
bin/jumphp setup # images Docker du runtime, si docker/ a changé
bin/jumphp engine:download # moteur navigateur de la nouvelle version (ou engine:build)
Publier une version de JumPHP (mainteneurs)
- Mettre à jour
VERSION, puis commiter. bin/jumphp engine:build, puisbin/jumphp engine:pack. On obtient.build/jumphp-engine.tar.gzet son.sha256.- Taguer et publier :
git tag vX.Y.Z && git push origin vX.Y.Z, puisgh release create vX.Y.Z .build/jumphp-engine.tar.gz .build/jumphp-engine.tar.gz.sha256. - Packagist (
jumphp/jumphp) lit les tags du dépôt Git : la nouvelle version apparaît d'elle-même quand le webhook Git de Packagist est en place.