8.8 KiB
JumPHP tutorial, from A to Z
From an empty machine to your game online on your own domain, over HTTPS. Allow about 30 minutes, most of it waiting for Docker. Version française : tutoriel.md.
In order, this tutorial covers:
- A. creating the project;
- B. the wizard;
- C. Claude Code writes the game;
- D. playing and testing;
- E. changing it yourself;
- F. in the browser;
- G. online on your own server;
- H. on Git;
- I. updating JumPHP.
A. Create the project
Requirements: a Linux machine, a Mac, or Windows with WSL2, and a terminal. The wizard offers to install the rest (git, Docker...).
composer create-project jumphp/jumphp my-game
If you have no composer (or no PHP), two other ways give the same result:
# with Docker
docker run --rm -it -v "$PWD":/app -w /app composer create-project jumphp/jumphp my-game
cd my-game && bin/jumphp
# with git
git clone https://git.jumphp.net/jumphp/jumPhp.git my-game && cd my-game && bin/jumphp
The my-game folder holds all of JumPHP:
| Folder | What it holds |
|---|---|
engine/ |
the engine |
skeleton/ |
the template of a game |
games/ |
the example games: pong, jumpball in 3D, breakout... |
bin/jumphp |
the CLI |
AGENTS.md |
the complete guide, for humans and AIs alike |
The folder is linked to the JumPHP repository with git, as the remote jumphp.
B. The wizard
With composer, the wizard starts by itself. Otherwise, run bin/jumphp. It asks one question at a time and
always asks before doing anything. Enter takes the answer in brackets, Ctrl+C stops the wizard, and
bin/jumphp init resumes it.
-
Tools. The wizard checks git, curl and Docker, and offers to install whatever is missing. On Linux it also adds you to the
dockergroup. PHP, composer, emscripten and the web server all run in Docker: there is nothing else to install. -
Your game. It asks for:
- the name shown (e.g.
Space Race); - the id: the folder
games/space-race, which is also the web address; - a one-line description;
- the resolution: 320×180 by default. These are the game's pixels, scaled up to the window;
- the default language.
The wizard then builds the runtime's Docker image (about 5 min the first time) and creates the game from the skeleton, a tiny platformer.
- the name shown (e.g.
-
Browser engine. Pick "download it": about 10 MB instead of a 25-minute build. Then accept the first test.
-
Server. Now or later: see part G.
-
GitHub. Now or later: see part H.
-
Claude Code. Describe what your game should do in a few lines, then enter an empty line. For example:
A vertical shoot'em up: the ship shoots waves of aliens, a boss every 3 levels, power-ups (double shot, shield), 3 lives, best score saved. Playable with the keyboard, a gamepad and on phones.
The wizard writes games/space-race/BRIEF.md: your text, plus everything Claude needs to know (read
AGENTS.md, test, look at the screenshots, publish nothing without asking you). It then starts Claude Code
with that prompt, offering to install it first if it is missing.
C. Claude writes the game
Claude reads AGENTS.md, replaces the skeleton with your game, then checks its own work:
bin/jumphp test space-race: lint, static analysis, and 600 frames played headless;bin/jumphp shot space-race: PNG screenshots that it looks at;- the browser build, with
bin/jumphp buildthenbin/jumphp webshot.
Ask for changes the way you would ask a colleague: "faster enemies in level 2", "a 2-player mode",
"translate it to French"... To start it again later: claude "$(cat games/space-race/BRIEF.md)", or just
claude in the folder.
D. Play and test
bin/jumphp run space-race # in a window, with sound
bin/jumphp test space-race # every check
bin/jumphp shot space-race 120 # screenshot after 2 s: games/space-race/var/screenshots/shot.png
The basic keys:
| Key | Action |
|---|---|
| arrows + Enter | menus |
| Escape | pause / back |
| F11 | fullscreen |
| F3 | frames per second |
A plugged-in gamepad just works.
E. Change it yourself
A game is made of:
| File | What it holds |
|---|---|
config/project.yaml |
title, resolution, first scene, the demo that test plays |
config/input.yaml |
the actions (jump, fire...) mapped to keys, gamepad and touch |
config/lang.yaml |
the translations |
src/Scene/*.php |
the screens: title, game, pause, game over |
src/Entity/*.php |
the things that move |
A minimal scene:
<?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; // scenes are reused: reset everything
}
public function update(float $dt): void // $dt in seconds
{
$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');
}
}
Three rules to remember: never block a frame (no sleep()), go through bin/jumphp for everything, and draw
only in render(). The rest is in AGENTS.md. The games in games/ are models: pong for menus,
AI and online play, jumpball for 3D with WebGL.
F. In the browser
bin/jumphp build space-race # -> games/space-race/dist/web: static files
bin/jumphp serve space-race # http://localhost:8080
The same PHP code runs in the page: PHP is compiled to WebAssembly, OpenGL becomes WebGL there and OpenAL becomes Web Audio. Phones get an on-screen gamepad.
G. Online on your own server
You need:
- a Linux server you can reach over SSH. A small VPS is enough, since the game is static;
- a domain name whose DNS A record (and AAAA for IPv6) points to that server, for example
space-race.example.com.
bin/jumphp deploy:setup
The questions:
- SSH access (
user@host). If the connection asks for a password, the wizard offers to create an SSH key and install it on the server (ssh-copy-id). - Domain:
space-race.example.com. - Web server:
- FrankenPHP alone: the simplest. Ports 80 and 443 must be free on the server, and the HTTPS certificate is automatic;
- Traefik + FrankenPHP: Traefik handles HTTPS, and other sites can later go behind the same Traefik;
- behind a Traefik already installed: the wizard asks for its Docker network, entry point and certificate resolver.
- Let's Encrypt e-mail: used for expiry notices.
- Folder on the server:
/opt/jumphp/space-raceby default.
If Docker is missing on the server, the wizard installs it (or later: bin/jumphp server:setup). Then, and
again for every new version of the game:
bin/jumphp deploy
The command builds the game, sends only what changed, and runs docker compose up -d on the server. The
game is then at https://space-race.example.com/. The very first visit can take a few seconds while the
certificate is issued. To see the web server's logs: bin/jumphp server:logs. To put several games on one
domain (a home page plus one folder per game): bin/jumphp deploy game1 game2.
H. On Git
bin/jumphp github
The wizard makes the first commit, installs gh and signs you in (gh auth login), then creates the
repository, private or public. With a public repository you can also publish the game for free on Git
Pages: bin/jumphp pages space-race puts it at https://<account>.github.io/<repo>/.
I. Update JumPHP
bin/jumphp update # merges the newest JumPHP (your commits are kept)
bin/jumphp setup # Docker images, if the runtime changed
bin/jumphp engine:download # the browser engine of the new version
Troubleshooting
| Symptom | Fix |
|---|---|
docker: permission denied |
You just joined the docker group: log out and back in, or run newgrp docker, then bin/jumphp init. |
| The wizard did not start after composer | cd my-game && bin/jumphp |
No window with bin/jumphp run |
It needs a display (X11 or Wayland). Without one, use bin/jumphp test and bin/jumphp shot. |
| No sound | It needs PulseAudio or PipeWire. The game still runs, silently. |
engine:download fails |
bin/jumphp engine:build (about 25 min, once) |
| The site does not answer over HTTPS | Check that the DNS points to the server and that ports 80 and 443 are open, then run bin/jumphp server:logs. |
| Unknown system | Install Docker by hand (https://docs.docker.com/get-docker/), then run bin/jumphp init again. |
Machine diagnosis: bin/jumphp doctor. Every command: bin/jumphp help.