- signUp / signIn / recover / signOut / me / devices / revokeDevice / hello / changePassword / deleteAccount ; jeton dans var/ (jumphp-account.json), oublié sur un 401 (onSignedOut). - Clé-valeur : get / value / set (If-Match) / setText / delete / search (préfixe, motif, curseur, valeurs) / getMany ; un conflit 412 échoue avec AppAccountError::isConflict() et data['current']. - Objets : put / getObject (?version, SHA-256 vérifié) / versions / objects / deleteObject ; store() sérialise un objet PHP, load() le relit avec allowed_classes obligatoire (une classe hors liste, même au fond, est refusée), AppAccount::unserialize(). - Jamais bloquant (Tasks par $engine->http()), bureau, navigateur et Android ; AppAccount::for($engine) (platform_url, JUMPHP_PLATFORM_URL). - Tests engine/tests/Platform/AppAccountTest.php (faux serveur), docs/platform-account.md, AGENTS.md §1 et §9. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JkYTqrBXzYFUXiSrqYBdP3
1422 lines
124 KiB
Markdown
1422 lines
124 KiB
Markdown
# AGENTS.md — how to build games with JumPHP
|
||
|
||
You are working in **JumPHP**, a framework to write **retro 2D games in PHP**. The same PHP code runs:
|
||
|
||
- on the **desktop** (native PHP 8.5 + SDL2 / OpenGL / OpenAL extensions, in Docker, in a real window with sound),
|
||
- in the **browser** (the same PHP 8.5 + extensions compiled to WebAssembly: OpenGL = WebGL, OpenAL = Web Audio;
|
||
the game is a static web page).
|
||
|
||
Everything (PHP, composer, emscripten, web server, relay server, tests) runs **in Docker** through one
|
||
command: `bin/jumphp`. Never install PHP, extensions, emscripten or node on the host; never run `php` or
|
||
`composer` directly — always `bin/jumphp ...`.
|
||
|
||
Read this whole file once before writing code. It is the contract: if you follow it, your game works on
|
||
both targets.
|
||
|
||
---
|
||
|
||
## 1. Map of the repository
|
||
|
||
```
|
||
bin/jumphp the CLI (bash). `bin/jumphp help`
|
||
AGENTS.md this file
|
||
README.md, docs/ human documentation (French)
|
||
engine/ the framework: composer package jumphp/engine, namespace JumPHP\ (engine/src)
|
||
src/Kernel/ Application (boot), Engine (the frame), GameConfig, Platform
|
||
src/Loop/ GameLoop (ReactPHP), FixedStep
|
||
src/Renderer/ Sdl (textures), Renderer (drawing), Window, BitmapFont, TtfFont, TextDrawer, CrtFilter
|
||
src/Input/ InputManager, ActionMap, Keyboard, Mouse, Touch, Gamepad
|
||
src/Scene/ Scene, AbstractScene, SceneManager, Camera
|
||
src/Entity/ Entity, GameObject, EntityManager, traits Sprite and Gravity
|
||
src/Physics/ CollisionSystem (tiles), Aabb (boxes), TileCollision trait, CollisionResult
|
||
src/Tile/ TileMap, TileSet, CollisionMask, TileMapRenderer, TiledJsonLoader, ArrayLoader, BinaryLoader
|
||
src/Audio/ SoundManager, Synth (generated sounds), Audio3d (positional sound: OpenAL)
|
||
src/Ui/ Menu, MenuScene, TextInput, Hud
|
||
src/Net/ NetSession, LobbyScene, MessageCodec, SnapshotBuffer, Tcp / TcpConnection (§9), Ssh / SshConnection / SshConnector (§9), BridgeRoute / RuntimeLink (the JumPHP runtime, §9)
|
||
src/Save/ Storage, Options
|
||
src/Async/ Tasks, Pool, Task, TaskFailed, WebWorkers, Worker (threads / Web Workers / between frames)
|
||
src/Cryo/ SandboxLoop (Cryo\Sandbox futures settled by the game loop, docs/cryo.md)
|
||
src/Bridge/ JsBridge (game <-> web page, synchronous with the frames)
|
||
src/Device/ Lifecycle (hide/show/blur/close...), Device (phone features), Pwa (installable, offline)
|
||
src/Gl/ OpenGl (raw PHP-OpenGL in SDL's context), WebGl (3D layer + post-processing), Mat4
|
||
src/Http/ Http (async requests: fetch / curl / sockets), HttpResponse, HttpError
|
||
src/Platform/ AppAccount (the user's jumphp.net account: sign-in, key/value store, versioned objects; §9), AppAccountError
|
||
src/Util/ Color, Math, Time, Lang, Vector
|
||
src/Tauri/ desktop apps (§16): App, Window, AppMain, TauriRuntime (FFI), FakeRuntime, NativeCommands
|
||
src/Native/ Dialog, FilePicker, Notification, Shell: the system's features, a provider per target (§16)
|
||
src/Testing/ GameTestCase (games), AppTestCase (desktop apps, no window)
|
||
src/Gui/ graphic apps without HTML (§17): Form (a scene + forms/*.form.yaml), Container (row, column, grid), widgets
|
||
bootstrap/wasm.php browser entry point
|
||
web/ the web page template (index.html, jumphp.js, jumphp-worker.js, jumphp-files.js (remote games), touch.js,
|
||
jumphp-device.js, jumphp-http.js, jumphp-pwa.js, jumphp-gamepad.js, jumphp-runtime.js, sw.js)
|
||
stubs/sdl.stub.php signatures of every SDL function / constant / class (read it to know the raw API)
|
||
stubs/async.stub.php the TrueAsync API used by JumPHP\Async
|
||
stubs/opengl.stub.php, openal.stub.php every gl* / openal_* function and constant (tools/gl-stubs.php)
|
||
tests/ engine unit tests
|
||
skeleton/ template of a game, copied by `bin/jumphp new`
|
||
skeleton-app/ template of a desktop app (Tauri), copied by `bin/jumphp app:new` (§16)
|
||
skeleton-gui/ template of a graphic app (forms, JumPHP\Gui), copied by `bin/jumphp gui:new` (§17)
|
||
skeleton-cli/ template of a CLI app (terminal: Symfony Console + symfony/tui), copied by `bin/jumphp cli:new` (§18)
|
||
skeleton-chrome/ template of a Chrome extension (Manifest V3: popup, options, service worker, content script, en + fr, tests),
|
||
copied by `bin/jumphp chrome:new`; tools/chrome.sh + tools/chrome/ check / run / test / pack it (docs/chrome-extension.md)
|
||
skeleton-plugin/ template of a plugin of the JumPHP IDE (PHP), copied by `bin/jumphp plugin:new` (§19)
|
||
skeleton-extension/ template of an engine extension + its example game, copied by `bin/jumphp extension:new` (§20)
|
||
extensions/<id>/ engine extensions (Composer type jumphp-extension; extensions/particles: particles), §20
|
||
tauri/ the desktop apps' native runtime (Rust + Tauri 2, a C library PHP loads with FFI; §16)
|
||
ide/ JumPHP IDE: package jumphp/ide, PHP core (JumPHP\Ide\) + HTML interface, shared by games/ide
|
||
(the desktop app) and jumphp.net/ide (docs/ide.md)
|
||
games/<id>/ the games (games/pong = the reference game: read it)
|
||
apps/<id>/ the other projects: apps, CLI apps, IDE plugins (made by app:new / gui:new / cli:new /
|
||
plugin:new; older projects keep them in games/, every command finds both)
|
||
docker/ engine-wasm (WebAssembly build), ssh-wasm (OpenSSH's ssh client as WebAssembly: bin/jumphp ssh:build, docs/ssh-wasm.md), desktop (runtime), desktop-async (PHP 8.6 ZTS + TrueAsync),
|
||
relay (network server), web (FrankenPHP), ext (php-opengl.patch, jumphp-xvfb: shared by them),
|
||
server (bin/jumphp deploy: FrankenPHP alone / Traefik + FrankenPHP / existing Traefik)
|
||
tools/ build scripts used by bin/jumphp; init.sh (the wizard), post-create.sh (composer create-project)
|
||
embed/ (jumphp-embed.php: a playground app on a partner's site, docs/embed.md; wordpress/ its plugin)
|
||
build/engine/ the compiled WebAssembly engine (bin/jumphp engine:build), shared by all games
|
||
```
|
||
|
||
A game folder:
|
||
|
||
```
|
||
games/<id>/
|
||
app.php desktop entry point (do not change)
|
||
composer.json namespace App\ -> src/, requires jumphp/engine (path ../../engine)
|
||
config/project.yaml id, title, resolution, first scene, smoke test... (older projects: config/game.yaml under game:, still read)
|
||
config/services.yaml dependency injection (every class of src/ is autowired, except src/Entity)
|
||
config/input.yaml actions -> keys / pad / touch
|
||
config/lang.yaml translations
|
||
src/Scene/*.php the screens (TitleScene, PlayScene, ...)
|
||
src/Entity/*.php the things that move (created with `new`)
|
||
assets/ sprites/, tiles/, maps/, sfx/, music/, fonts/, icon.png, thumbnail.png
|
||
var/ player files (saves, options) — never commit, never read at build time
|
||
site/ (optional) the game's web site, deployed at the root with the game in /play/
|
||
dist/web/ browser build output (bin/jumphp build)
|
||
AGENTS.md notes about this game
|
||
BRIEF.md (projects made by bin/jumphp init) what the game should be: the prompt the user wrote
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Golden rules (read twice)
|
||
|
||
1. **Docker only**: `bin/jumphp ...` for everything (see §3).
|
||
2. **Never block the frame.** No `sleep()`, `usleep()`, `while (true)`, `readline()`, `fgets(STDIN)`,
|
||
blocking sockets, long loops. The browser calls the engine once per frame; a blocking call freezes the tab.
|
||
Time-based things: count `$dt` in `update()`, or `GameLoop::addTimer($seconds, fn () => ...)`.
|
||
3. **32-bit integers in the browser** (`PHP_INT_SIZE === 4`, max 2147483647):
|
||
- no `(int)(microtime(true) * 1000)`, no `hrtime(true)` as int, no `time() * 1000`: use `JumPHP\Util\Time::now()` (float seconds) or `$this->engine->time()`.
|
||
- no colour integers like `0xFF000000`: use `[r, g, b, a]` arrays, `'#rrggbb'` strings or `Color`.
|
||
- no `pack('q'/'J'/'P')`: use `C c v s V g` (see MessageCodec).
|
||
- big counters (score > 2 billion) are floats.
|
||
4. **Network only through `JumPHP\Net`** (`$this->engine->net()`, multiplayer; `$this->engine->tcp()`, TCP, §9) and **`JumPHP\Http`**
|
||
(`$this->engine->http()`, web APIs). No `socket_*`, `fsockopen`, `stream_socket_client`, curl or
|
||
`file_get_contents('http...')`: they do not exist in the browser (and they block the frame).
|
||
5. **Files**: read game files with paths relative to the game root through `$this->engine->config->path('assets/...')`
|
||
(or relative paths given to Sdl / SoundManager / loaders, which resolve them). Write only into `var/`
|
||
through `$this->engine->storage` / `$this->engine->options` (persisted in IndexedDB in the browser: one database per game, named after its id, so the games of one site never read each other's files).
|
||
`sys_get_temp_dir()` is fine for temporary files.
|
||
6. **SDL limits** (the binding): no `SDL_SetTextureBlendMode`, `SDL_SetRenderDrawBlendMode`,
|
||
`SDL_SetTextureColorMod`, `SDL_SetTextureAlphaMod`, `SDL_GameController*`. Translucency: give a colour with
|
||
alpha to `Renderer::fillRect()` (handled), or use PNGs with alpha. Tinting: pre-coloured images (or
|
||
`createTextureFromPixels` with another palette). Textures ≤ 4064 px wide (Sdl slices wider images itself).
|
||
7. **Draw only in `render()`, change state only in `update()`.** Coordinates are virtual pixels
|
||
(`project.yaml` width × height); the engine scales to the window.
|
||
8. **Scenes are reused** (one instance per class, from the container): reset ALL state in `enter()`.
|
||
9. **No `declare(strict_types=1)`** required, PHP 8.2 syntax max (the desktop runs 8.5, the browser 8.5).
|
||
Code, identifiers and comments in English. Follow the style of `games/pong`.
|
||
10. **Forbidden words**: `bin/jumphp lint` fails if the repository contains certain brand names
|
||
(`tools/check-forbidden-words.sh`). Do not name games, classes or files after existing commercial games.
|
||
11. **Always verify** before saying you are done (§10): `bin/jumphp test <game>` must pass, and look at a
|
||
screenshot (`bin/jumphp shot <game>`).
|
||
|
||
12. **Keep a history of what you do** (the JumPHP IDE does it by itself for its Claude / OpenCode window; do it yourself when you
|
||
are launched any other way, e.g. Claude Code in a terminal), **at the root of the project, in `IA/HISTORY/`**, so that any AI can walk
|
||
through the whole folder and know what happened:
|
||
- `IA/HISTORY/INDEX.md`: one line per turn, oldest first (turn number, date, assistant, model, number of actions, result, request, folder);
|
||
the turn numbers only grow (`IA/HISTORY/.seq` holds the last one: 0001, 0002...);
|
||
- per turn, in `IA/HISTORY/<CLAUDE|OPEN CODE>/<model>/<dd-mm-YYYY HH-MM-SS>/` (no `:`, Windows refuses it):
|
||
`<turn>-<request>.md` (every message, the user's and yours, **with its date and time**) and a **separate file**
|
||
`<turn>-<request>.actions.md` with **every command / tool you ran, numbered in order** (`0007-001`, `0007-002`...), each with its
|
||
start and end time, the command itself, its **result** (the end of it when it is long) and whether it worked.
|
||
`IA/` is **never sent to git**: make sure `/IA/` is in the project's `.gitignore`, and tell the user once that this history lives on
|
||
their computer only and is lost if the folder or the computer is.
|
||
|
||
13. **Never move, delete or re-create a published tag** (`v*` of JumPHP and of the extension repositories `jumphp-<id>`): Packagist
|
||
freezes a stable version's commit; a tag that points elsewhere later makes it refuse the update and mail the maintainer
|
||
(happened 2026-11-07 after the move to git.jumphp.net: `v0.5.6` of shorts / physics / particles, several `jumphp` tags).
|
||
No `git tag -f`, no `git push --force` of a tag, no delete + re-tag, no history rewrite under a tag. A mistake in a release =
|
||
a **new version** (`v0.5.N+1`). Before bumping, `git ls-remote --tags` and compare with
|
||
`https://packagist.org/packages/jumphp/<id>.json`. If a tag was moved anyway, restore it to the reference Packagist shows.
|
||
|
||
---
|
||
|
||
## 3. Commands
|
||
|
||
| Command | What it does |
|
||
|---|---|
|
||
| `bin/jumphp setup [async]` | builds the Docker images (desktop runtime, relay; `async`: also the PHP 8.6 ZTS + TrueAsync runtime, ~15 min). Done automatically when missing. |
|
||
| `bin/jumphp init` | interactive project wizard for humans (tools, game, engine, server, GitHub, Claude Code); `bin/jumphp` alone runs it while `.env` has no `JUMPHP_GAME`. Agents: do not run it (it asks questions) |
|
||
| `bin/jumphp engine:download` | downloads the prebuilt WebAssembly engine of this version (release of git.jumphp.net) into `build/engine/` |
|
||
| `bin/jumphp engine:build` | builds the WebAssembly engine into `build/engine/` (~25 min the first time, cached). Needed once for browser builds (or `engine:download`). |
|
||
| `bin/jumphp new <id> ["Title"]` | creates `games/<id>` from `skeleton/` (id: `a-z0-9-`) |
|
||
| `bin/jumphp install <id>` | composer install of the game |
|
||
| `bin/jumphp composer <id> require vendor/pkg` | composer (pure-PHP packages only: no extension exists in the browser) |
|
||
| `bin/jumphp run <id>` | plays on the desktop (window + sound). Needs a display; not usable by an agent without a screen. Without `<id>`: the folder of `games/` or `apps/` it is typed in, else `JUMPHP_APP` (or the older `JUMPHP_GAME`, .env), else the only project |
|
||
| `bin/jumphp test <id>` | `php -l`, phpstan (level 5, if `phpstan.neon` and `bin/jumphp test engine` ran once), phpunit (`tests/` if any, game tests included), **headless smoke test** (600 frames, any PHP warning = failure) |
|
||
| `bin/jumphp shot <id> [frames] [out.png]` | **headless screenshot**: runs N frames (default 120) and saves a PNG in `games/<id>/var/screenshots/` — open it to SEE the game |
|
||
| `bin/jumphp build <id>` | browser build → `games/<id>/dist/web/` (static files) |
|
||
| `bin/jumphp build:remote <id>` | the game as a **remote game** (`dist/remote/`: shared engine + files one by one + manifest, what a games site serves, docs/remote.md); `JUMPHP_WEB=remote bin/jumphp serve/webshot <id>` tries it |
|
||
| `bin/jumphp runtime:build` / `runtime:download [version]` | the shared engine of remote games → `build/runtime/` (+ the release asset `.build/jumphp-runtime.tar.gz`) |
|
||
| `bin/jumphp serve <id> [port]` | serves the browser build on http://localhost:8080 |
|
||
| `bin/jumphp webshot <id> [seconds] [keys]` | headless Chrome: loads the browser build, presses keys, screenshot `dist/webshot.png`, fails on JS / PHP errors |
|
||
| `bin/jumphp relay up\|down\|logs` | multiplayer relay server on `ws://localhost:8090/ws` |
|
||
| `bin/jumphp export:desktop <id>` | a Docker image that runs the game |
|
||
| `bin/jumphp export:standalone <id> [--linux] [--windows]` | the game as one executable for players (dist/standalone/; docs/standalone.md) |
|
||
| `bin/jumphp installer <id> --github \| --url https://site/folder/ \| --standalone [--windows] [--linux] [--macos] [--version X]` | an **installer** per system (jumphp2installer: shortcuts, uninstaller, always installs the newest version): `--github` = a release `v<version>` of the project's repository (gh, public repo), `--url` = `dist/installer/` to upload at that address, `--standalone` = the game inside each installer (`dist/installer/`: no site, no network, installs that version, never updates). Builds Windows / Linux first (`--no-build`: the existing ones); macOS: an existing build. jumphp.net: the IDE (Run > Create an Installer…). Publishing: only when asked |
|
||
| `bin/jumphp gui:new <id> ["Title"] [--mobile]` | a **graphic app** (forms made in the IDE's visual editor, `JumPHP\Gui`, no HTML; §17); then run / test / shot / build / export as a game |
|
||
| `bin/jumphp cli:new <id> ["Title"]` | a **CLI app** (commands + full-screen text screens in the terminal, §18); then run / test / shot (the screen as text) / export:standalone as a game |
|
||
| `bin/jumphp plugin:new <id> ["Title"]` / `plugin:pack <id>` | a **plugin of the JumPHP IDE** in PHP (§19); `test` on its folder; `pack` = `dist/<id>-<version>.zip` |
|
||
| `bin/jumphp extension:new <id> ["Title"]` | an **engine extension** (§20): the package `extensions/<id>` + its example game `games/<id>-demo` (install / test / shot / build it) |
|
||
| `bin/jumphp video <id> <film.mp4> [name] [fps]` | a film as frames + sound for the `video` widget (`assets/videos/<name>/`) |
|
||
| `bin/jumphp app:new / app:run / app:test / app:shot / app:export <id>` | **desktop apps** (HTML pages + PHP, Tauri; §16, docs/tauri.md). `run` / `test` / `shot` on an app's folder hand over to them; `app:export --windows --macos`; `app:release` (updates); `build` = the app in the browser |
|
||
| `bin/jumphp tauri:setup` / `tauri:build` / `tauri:download` | the Tauri image / the runtime library `build/tauri/linux-x86_64/libjumphp_tauri.so`, built or downloaded (done automatically when needed) |
|
||
| `bin/jumphp apple <id>` (`ios <id>`, `macos <id>`) | the game as native Apple apps, built and tried on GitHub's Macs: .dmg (Mac), .ipa (iPhone / iPad), the simulator's app, screenshots (§14, "Apple apps") |
|
||
| `bin/jumphp deploy [id...]` | to the project's server (`.env` `JUMPHP_SERVER`, set by `deploy:setup`): builds, rsync, `docker compose up` (FrankenPHP, or Traefik + FrankenPHP), a game with its own web site (`games/<id>/site/index.html`) gets it at the root and the game in `/play/` (`{{DOMAIN}}` replaced in its pages), then checks that `https://<domain>/` answers (shows the server logs if not). Behind a Traefik already on the server: `bin/jumphp server:traefik` prints its entry points and resolver (`JUMPHP_SERVER_MODE` `traefik-external`, or `traefik-passthrough` when it has no working resolver). Without a server: rsync `dist/web` to `$JUMPHP_DEPLOY_TARGET/<id>/`. Publishing: only when asked |
|
||
| `bin/jumphp runner:install` / `runner:scripts [dir]` | your own CI runner (docs/ci-runner.md): Docker runner for Linux/macOS/VPS; `tools/runner/install-windows-runner.ps1` (native Windows runner), `install-wsl-linux-runner.ps1` (Linux runner in WSL2), `windows-vm/` (headless Windows VM on Linux); one user/org scope only, tokens from the environment, ask the user first |
|
||
| `bin/jumphp update` | merges the newest JumPHP (git remote `jumphp`) into the project |
|
||
| `bin/jumphp cli:install` / `cli:uninstall` | the `jumphp` command for the whole system (`~/.local/bin/jumphp`, `tools/jumphp-cli`): `jumphp <command>` from any folder of a project, `jumphp new <folder>`, and once a day a question when Packagist has a newer JumPHP (`bin/jumphp update` on a yes) |
|
||
| `bin/jumphp twa <id> --url <page>` | the game as an Android app for Google Play (§14, "Android app") |
|
||
| `bin/jumphp pages [id...]` | builds the games (default: all) + a home page from their `game.json`, force-pushes them as the `gh-pages` branch of the git remote (GitHub Pages: `https://<owner>.github.io/<repo>/`). Publishing: only when asked |
|
||
| `bin/jumphp debug` | the IDE's debugger as an MCP server for Claude Code in a terminal (`claude mcp add jumphp-debug -- bin/jumphp debug`): breakpoints / exceptions, then run the program yourself with `JUMPHP_XDEBUG=9003`, then `debug_wait`, `debug_step`, `debug_eval`, `debug_set_value`... |
|
||
| `bin/jumphp notify:login <app>` / `notify <app> --all\|--user U\|--group G "Title" "Text" [--url /play/] [--dry-run]` / `notify:stats` / `notify:history` / `notify:mcp` | push notifications of an application (extension `jumphp/notification`, docs/notifications.md): the owner's token `jnt_…` asked without echo and kept in `~/.jumphp/notify/tokens.json` (0600, never in a repository; `JUMPHP_NOTIFY_TOKEN` wins); `notify:mcp` = MCP server for Claude (`claude mcp add jumphp-notify -- bin/jumphp notify:mcp`; a send to everyone needs `confirm: true`). Sending: only when the user asks |
|
||
| `bin/jumphp ssh:build` | OpenSSH's `ssh` client compiled to WebAssembly (Docker, a few minutes) -> `build/ssh/ssh.js` + `ssh.wasm`, packed in the runtime of remote games and in the web builds (`runtime:build` does it when missing) |
|
||
| `bin/jumphp web:new <kind> <folder>` / `web:serve [folder]` / `web:stop` | **web sites, not games** (Symfony, WordPress, PrestaShop, Sylius, Laravel, PHP) on any folder: FrankenPHP + MariaDB + live reload + SCSS / npm watch in Docker (docs/web.md) |
|
||
| `bin/jumphp chrome:new <folder> ["Name"]` / `chrome:check` / `chrome:run` / `chrome:test` / `chrome:pack` / `chrome:bump` `[folder]` | **Chrome extensions** (Manifest V3) on any folder, in Docker (Puppeteer's image): a new one from `skeleton-chrome/`, the manifest checked (MV3 rules, files, icons, permissions, translations; JSON report), loaded in a headless Chrome (its id, console errors, screenshots of the page / popup / options in `var/screenshots/`: open them), its tests (`tests/*.test.cjs`, node:test + Puppeteer), the Chrome Web Store zip in `dist/`, the version (docs/chrome-extension.md). Publishing: the user's |
|
||
| `bin/jumphp test engine` | engine unit tests + phpstan |
|
||
| `bin/jumphp lint` | php -l everywhere + forbidden words |
|
||
| `bin/jumphp php <dir> <args>` | php in the runtime image (from a repo-relative dir) |
|
||
|
||
**A new project** (you ran `composer create-project jumphp/jumphp <folder>` or cloned one for the user): ask the
|
||
user once whether to install the `jumphp` command for the whole system (`bin/jumphp cli:install`: then
|
||
`jumphp test <id>` works from any folder, `jumphp new` makes other projects, and they are told when a new
|
||
JumPHP is out, updating only if they say yes). Install it only on a yes; it changes their `~/.local/bin` (and,
|
||
if they agree in the terminal, their shell profile).
|
||
|
||
**JumPHP's address is `https://git.jumphp.net/jumphp/jumPhp`** (Forgejo; the old GitHub account is gone). Never use, add or
|
||
write `github.com/davidnurdin/...` (no `github` remote, no link, no clone URL): in this repository `origin` is
|
||
`https://git.jumphp.net/jumphp/jumPhp.git`, the extensions are `https://git.jumphp.net/jumphp/jumphp-<id>.git`, releases are at
|
||
`https://git.jumphp.net/jumphp/jumPhp/releases/download/<tag>/<file>` (not GitHub's `/releases/latest/download/`). `gh` is
|
||
`tools/bin/gh` (it talks to the forge). Details: docs/migration-forge.md.
|
||
|
||
**Which Git host builds what** (a project's `origin` is github.com or a forge such as git.jumphp.net; `gh` talks to both):
|
||
`android`, `installer --github`, `standalone` and the other workflows run on the Actions runners of the project's host (a forge:
|
||
its Forgejo runners, docs/ci-runner.md; none is shared, register your own). `apple` / `ios` / `macos` need a **macOS runner**:
|
||
only GitHub has them, so on a forge `bin/jumphp apple` stops with an explanation (own Mac runner: `JUMPHP_MAC_RUNNER=1`). `pages`
|
||
makes the `gh-pages` branch: GitHub Pages serves it; a forge does not, publish on the JumPHP playground (§14) instead.
|
||
|
||
**The project's own repository**: a project is the user's git repository, remote `origin` on their Git host (the IDE's New
|
||
Project creates it through jumphp.net for every kind; `bin/jumphp init` with `gh`). The remote `jumphp` is JumPHP itself:
|
||
it only gives updates (`bin/jumphp update`) and cannot be pushed to. Never push, make a release or publish to JumPHP's
|
||
repository from a project: `bin/jumphp installer --github`, `android`, `apple`, `pages` refuse it. A project without
|
||
`origin`: ask the user (name, public / private) before `gh repo create <name> --source . --remote origin --push`.
|
||
|
||
Headless runs (`test`, `shot`) use a **fresh temporary `var/`** (options and saves start from the defaults,
|
||
the player's files are never touched; `JUMPHP_VAR=<dir>` forces a folder). They are driven by environment variables:
|
||
|
||
| Variable | Effect |
|
||
|---|---|
|
||
| `JUMPHP_SCENE='App\Scene\PlayScene'` | first scene (instead of `start_scene`) |
|
||
| `JUMPHP_SCENE_PARAMS='{"mode":"cpu"}'` | its `enter()` params (JSON) |
|
||
| `JUMPHP_INPUT='[[10,"confirm"],[30,"left","hold"],[90,"left","release"]]'` | scripted actions: `[frame, action]` = one press, `"hold"` / `"release"` |
|
||
| `JUMPHP_MAX_FRAMES=600` | how many frames (60 frames = 1 s of game time, fixed step) |
|
||
| `JUMPHP_SHOT_EVERY=30` | `shot`: also save one PNG every N frames (`shot-00030.png`...; older ones are deleted first) |
|
||
| `JUMPHP_REALTIME=1` | headless frames in real time (network tests between two processes) |
|
||
| `JUMPHP_WEBSHOT_ARGS="--disable-3d-apis"` | `webshot`: extra Chrome arguments (space separated); this one tests the CPU fallback of a browser without WebGL |
|
||
| `JUMPHP_GL=0` / `1` | headless OpenGL off / on (default: on when the game's code calls `gl()` / `opengl()`: real window on Xvfb, Mesa) |
|
||
| `JUMPHP_DEBUG=1` | FPS / scene overlay (F3 toggles it too) |
|
||
| `JUMPHP_XDEBUG=<port>` | step debugging: PHP runs with Xdebug (desktop image + Xdebug, built once) and connects to a debugger listening on that port of this computer (the JumPHP IDE's Debug sets it); composer, phpstan and `php -l` run without it |
|
||
| `JUMPHP_DEBUGGER=xdebug\|php-debugger` | the engine for `JUMPHP_XDEBUG` (default `xdebug`): `php-debugger` = [PHP Debugger](https://php-debugger.dev) (DBGp like Xdebug, near-zero overhead, PHP 8.2-8.5: the async runtime keeps Xdebug; image `docker/desktop-phpdebugger`, built once). The IDE: Debug with… (right click on the Debug button) picks it per run; `bin/jumphp debug` then starts PHP Debugger's own MCP server (`dbgp mcp`, `dbgp` installed: `claude mcp add dbgp -- dbgp mcp`) |
|
||
|
||
**Which project, what kind, what starts** (the same for a game, a desktop app, a graphic app, a CLI app, a plugin):
|
||
- which project: its folder name, `games/<id>` or `apps/<id>`, given to the commands; without it: the folder of `games/` / `apps/`
|
||
the command is typed in, else `JUMPHP_APP` (`JUMPHP_GAME` is read too, `.env`), else the only project;
|
||
- what kind: `config/project.yaml` (older projects: `config/game.yaml`) `kind:` (`gui`, `cli`, `plugin`; a game by default), or
|
||
`ui: webview` / `ui: hybrid` (desktop apps);
|
||
- what starts: a game: `start_scene:`; a desktop app: `main: App\Main` (its `boot()`); a CLI app: `app.php` calls `App\Main::boot()`.
|
||
The PHP entry is always `app.php` on the desktop, `engine/bootstrap/wasm.php` in the browser (it reads the same project.yaml),
|
||
`tools/standalone-stub.php` in the one-file executables (it loads `app.php`);
|
||
- the names that say "project": `JumPHP\Kernel\ProjectConfig` and `JumPHP\Testing\ProjectTestCase` are `GameConfig` and `GameTestCase`
|
||
under another name (both work forever).
|
||
|
||
Three key-name formats, do not mix them:
|
||
|
||
| Where | Format | Examples |
|
||
|---|---|---|
|
||
| `config/input.yaml` | SDL key names, `padN:`, `touch:`, `mouse:` | `Left`, `Space`, `Return`, `Left Shift`, `pad0:a`, `pad0:start` |
|
||
| `JUMPHP_INPUT` (headless) | **action names** from input.yaml | `confirm`, `left`, `fire` |
|
||
| `bin/jumphp webshot` keys | browser `KeyboardEvent.key` names | `Enter`, `ArrowLeft`, ` ` (space), `Escape`, `a` |
|
||
|
||
Tip: for tests and shots, add test-only `enter()` params to your scenes (e.g. `{"level":3,"lives":1}`) and
|
||
pass them with `JUMPHP_SCENE_PARAMS`, rather than scripting long input sequences.
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
bin/jumphp shot mygame 60 # the title screen after 1 s
|
||
JUMPHP_INPUT='[[5,"confirm"]]' bin/jumphp shot mygame 180 var/screenshots/play.png # press confirm, 3 s later
|
||
JUMPHP_SCENE='App\Scene\PlayScene' bin/jumphp shot mygame 300
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Create a game, step by step
|
||
|
||
```bash
|
||
bin/jumphp new breakout "BREAKOUT"
|
||
bin/jumphp install breakout
|
||
bin/jumphp test breakout # the skeleton passes as is
|
||
bin/jumphp shot breakout 60 # look at games/breakout/var/screenshots/shot.png
|
||
```
|
||
|
||
The skeleton is a tiny platformer (title menu, options, a level with slopes, a player, coins, a pause menu).
|
||
Replace its scenes and entities with your game:
|
||
|
||
1. **`config/project.yaml`** (all keys under `project:`; every one is optional):
|
||
|
||
| Key | Default | |
|
||
|---|---|---|
|
||
| `id`, `title`, `version`, `description` | | identity (page title, `game.json` for the portal) |
|
||
| `descriptions` | {} | the description per language, `{fr: '…', en: '…', es: '…'}`: the playground shows the visitor's. Its languages: `fr en es de it pt nl pl ru uk tr ja zh ko` (fill them all, at least fr and en) |
|
||
| `width`, `height` | 320, 180 | virtual resolution (classic: 320×180, 256×224, 256×192, 320×240) |
|
||
| `scale` | 3 | desktop window = width × scale |
|
||
| `integer_scale` | false | scale by whole factors only (sharper, bigger black borders) |
|
||
| `hd` | 1 | `auto` (or 2..4): the 2D is drawn at the window's resolution, its coordinates unchanged: sharp TTF text (rendered at the real size), round circles, positions at fractions of a pixel; 1 = retro pixels |
|
||
| `fullscreen`, `vsync`, `max_fps` | false, true, 120 | desktop window |
|
||
| `background` | [0,0,0] | letterbox colour |
|
||
| `start_scene`, `start_params` | | first scene class and its `enter()` params |
|
||
| `lang` | en | default language (`config/lang.yaml`) |
|
||
| `net_url` | ws://localhost:8090/ws | relay server |
|
||
| `net_mode` | auto | browser TCP / SSH / UDP / ICMP: `auto` (the user's own network through the JumPHP runtime when it is `ready`, else the server's bridge), `server` (always the server's), `local` (the runtime, or the error "the JumPHP runtime is not available"); env / page `JUMPHP_NET_MODE`; needs the `jumphp/runtime` extension for anything but the server (§9) |
|
||
| `smoke` | | `{scene: ..., params: {...}}` run 600 frames by `bin/jumphp test`: make it a self-playing demo |
|
||
| `online` | false | the game has online play (shown by the portal) |
|
||
| `touch` | | phone pad keys: `{a: Space, b: Escape, start: Return}`; optional `pad: stick` (floating joystick, 8 directions) or `pad: none` (no pad, no buttons: games played by tapping, the touches are mouse clicks), `select: P` (4th button), `labels: {a: JUMP, ..., rotate: TEXT}`; phones go fullscreen + landscape at the first tap (`fullscreen: false` to disable) |
|
||
| `controls` | | one line of help text shown by the web page / portal |
|
||
| `runtime` | default | `async`: desktop runs on PHP 8.6 ZTS + TrueAsync (real threads, §9 Threads) |
|
||
| `pause_scene` | | pushed when the tab is hidden / the window loses the focus (not over menus) |
|
||
| `pause_on_blur`, `mute_when_hidden` | true, true | |
|
||
| `hidden_frames` | true | browser: a hidden tab gets no `requestAnimationFrame`; the page still runs one frame a second (a Web Worker's clock), so the network, pings and timers go on. `false`: nothing runs while hidden |
|
||
| `pwa` | false | `true` or `{name, short_name, display, orientation, theme_color, background_color}`: installable, plays offline (§9) |
|
||
| `debug_key`, `fullscreen_key` | F3, F11 | |
|
||
| `double_click_fullscreen` | false | browser: `true` = a double click on the game goes fullscreen (never in apps). Default off: the FULLSCREEN button / playground bar / F11 do it, and double clicks stay free for lists and columns |
|
||
2. **`config/input.yaml`**: your actions (`jump`, `fire`, `p1_up`...). The engine already defines
|
||
`up down left right confirm back pause`.
|
||
3. **Scenes** in `src/Scene/` (§5): a `TitleScene extends MenuScene`, a `PlayScene extends AbstractScene`,
|
||
overlays (`PauseScene`, `GameOverScene`) with `isOverlay(): true`.
|
||
4. **Entities** in `src/Entity/` (§6), created with `new` by the scenes.
|
||
5. **Assets** (optional): PNG sprite sheets in `assets/sprites/`, tilesets in `assets/tiles/`, Tiled maps
|
||
(`.tmj`) in `assets/maps/`, sounds (`.wav`, `.ogg`) in `assets/sfx/` and `assets/music/`, TTF fonts in
|
||
`assets/fonts/`, `assets/icon.png` (page icon), `assets/thumbnail.png` (games portal). **No asset is
|
||
required**: draw with rectangles, `createTextureFromPixels()` (pixel art in code), GD, the built-in
|
||
`BitmapFont`, and `Synth` sounds.
|
||
6. Replace the skeleton leftovers: `description` in project.yaml, `README.md`, `AGENTS.md`, unused `lang.yaml`
|
||
entries, `src/Entity/Coin.php`...
|
||
7. **Game tests as you go** (§10 "Game tests"): each mechanic you write gets a test that plays it, run at once
|
||
with `bin/jumphp test <id>` (the user watches them play); `bin/jumphp shot <id>`; iterate.
|
||
8. Browser: `bin/jumphp engine:build` (once per machine), `bin/jumphp build <id>`, `bin/jumphp webshot <id>`.
|
||
|
||
---
|
||
|
||
## 5. Scenes
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Scene;
|
||
|
||
use JumPHP\Renderer\Renderer;
|
||
use JumPHP\Scene\AbstractScene;
|
||
|
||
final class PlayScene extends AbstractScene
|
||
{
|
||
private float $x = 0;
|
||
|
||
// constructor: services only (autowired), e.g. TileMapRenderer, CollisionSystem, EntityManager
|
||
public function enter(array $params = []): void
|
||
{
|
||
$this->x = 0; // reset everything: the instance is reused
|
||
}
|
||
|
||
public function update(float $dt): void // $dt in seconds (variable; ~0.016)
|
||
{
|
||
if ($this->actions()->isPressed('pause')) {
|
||
$this->scenes()->push(PauseScene::class);
|
||
return;
|
||
}
|
||
$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');
|
||
}
|
||
}
|
||
```
|
||
|
||
`AbstractScene` helpers: `$this->engine`, `actions()`, `scenes()`, `sound()`, `sdl()`, `font()`,
|
||
`width()`, `height()`. Lifecycle: `enter($params)`, `exit()`, `pause()` (something pushed over it),
|
||
`resume($result)` (it was popped), `update($dt)`, `render($r)`, `isOverlay()`.
|
||
|
||
SceneManager (`$this->scenes()`):
|
||
|
||
| Call | Effect |
|
||
|---|---|
|
||
| `switchTo(Class::class, $params = [], $fade = true)` | replaces the whole stack (black fade) |
|
||
| `push(Class::class, $params = [], $fade = false)` | over the current one (paused) |
|
||
| `pop($result = null)` | back to the one below (`resume($result)`) |
|
||
| `current()` | the scene on top |
|
||
|
||
Only the top scene is updated. Overlays (`isOverlay() === true`) are drawn over the scene below.
|
||
|
||
**Escape is bound to both `pause` and `back`.** In a pause menu (a `MenuScene` overlay), `back()` already
|
||
fires on Escape; to also resume with the other pause keys (P, Start) without popping twice:
|
||
|
||
```php
|
||
public function update(float $dt): void
|
||
{
|
||
if ($this->actions()->isPressed('pause') && !$this->actions()->isPressed('back')) {
|
||
$this->scenes()->pop();
|
||
return;
|
||
}
|
||
parent::update($dt);
|
||
}
|
||
```
|
||
|
||
**Menus**: extend `JumPHP\Ui\MenuScene`, set `$title`, return rows from `items()`:
|
||
|
||
```php
|
||
final class TitleScene extends MenuScene
|
||
{
|
||
protected string $title = 'MY GAME';
|
||
|
||
protected function items(): array
|
||
{
|
||
return [
|
||
// [label, value, onPress, onSide]
|
||
['PLAY', null, fn () => $this->scenes()->switchTo(PlayScene::class, ['level' => 1])],
|
||
['VOLUME', fn () => round($this->sound()->getSfxVolume() * 100) . '%', null,
|
||
fn (int $dir) => $this->sound()->setSfxVolume($this->sound()->getSfxVolume() + $dir / 10)],
|
||
['QUIT', null, fn () => $this->engine->quit()],
|
||
];
|
||
}
|
||
|
||
protected function back(): void { } // Escape; sub-menus: $this->scenes()->pop();
|
||
}
|
||
```
|
||
|
||
Labels and the `$title` are translated with `config/lang.yaml`. Call `$this->refresh()` after changing a value shown in a
|
||
label. Override `renderBackground(Renderer $r)` for a custom background; `$titleScale`, `$menuTop`,
|
||
`$background`, `$titleColor` customise it. Menu sounds: define sfx named `menu_move` and `menu_confirm`.
|
||
Hide `QUIT` in the browser: `if (Platform::isDesktop())`.
|
||
|
||
**Hot reload** (the playground's online editor and sandbox, ⚡ Live): a file saved goes into the running game
|
||
without reloading the page (`engine/src/Debug/HotReload.php`). Pictures, sounds, `lang.yaml`, `input.yaml`:
|
||
replaced in place. Another data file: the current scene is entered again with its parameters. PHP code,
|
||
`project.yaml`, `services.yaml`, `composer.json`: PHP restarts in the same WebAssembly engine and boots straight
|
||
into the scene that was playing. Its fields are then fresh; a scene whose state is worth keeping while one
|
||
tunes the game (the room, the score, the player's position) implements `JumPHP\Scene\HotReloadable`:
|
||
|
||
```php
|
||
final class PlayScene extends AbstractScene implements HotReloadable
|
||
{
|
||
public function hotState(): array { return ['room' => $this->room, 'score' => $this->score, 'lives' => $this->lives]; }
|
||
public function hotRestore(array $state): void { ['room' => $this->room, 'score' => $this->score, 'lives' => $this->lives] = $state; } // after enter()
|
||
}
|
||
```
|
||
|
||
Plain values only (they cross from one version of the code to the next). Do it for the main play scene of a
|
||
game; it changes nothing outside hot reload. `docs/hot-reload.md` has the details.
|
||
|
||
---
|
||
|
||
## 6. Entities, sprites, animation
|
||
|
||
`JumPHP\Entity\Entity` has **protected** fields `x`, `y` (top-left, float), `vx`, `vy`, `ax`, `ay`, `friction`,
|
||
`width`, `height`, `facing` ('left'/'right'), `state` (string): use them as `$this->x` inside the entity
|
||
class, and through accessors from outside. **Public** fields: `active`, `visible`, `dead`, `alwaysActive`.
|
||
Accessors: `setX()/setY()/setXY()`, `setSpeedX()/setSpeedY()`, `getSpeedX()/getSpeedY()`, `getSpeed()` (length),
|
||
`setAcceleration()`, `setFriction()`, `setFacing()/getFacing()`, `setState()/getState()`,
|
||
`setSize()`, `getWidth()/getHeight()`.
|
||
Methods: `getX()/getY()` (rounded ints), `getFloatX()/getFloatY()`, `setVelocity()`,
|
||
`getVelocity()` (`[vx, vy]`), `getBoundingBox()` (`['x','y','width','height']`), `centerX()`, `centerY()`,
|
||
`intersects($rect)`, `kill()`, `update($dt)` (integrates velocity, picks the animation `<state><Facing>`),
|
||
`render(Renderer $r, $camX, $camY)` (default: magenta box). It is an event emitter (`on()`, `emit()`).
|
||
|
||
`GameObject extends Entity`: `type`, `name`, `properties` (from the map editor), `property($name)`,
|
||
constructor `($x, $y, $width, $height, $type, $name, $properties)` — what `EntityManager::spawn()` calls.
|
||
|
||
Traits (compose them; the class's own `update()` calls the aliased ones):
|
||
|
||
```php
|
||
final class Hero extends Entity
|
||
{
|
||
use Sprite, Gravity, TileCollision {
|
||
Sprite::update as updateSprite;
|
||
Gravity::update as updateGravity;
|
||
}
|
||
|
||
protected array $animations = [
|
||
'idleRight' => ['coords' => [['x' => 0, 'y' => 0, 'w' => 16, 'h' => 16]]],
|
||
'walkRight' => ['coords' => [['x' => 16, 'y' => 0, 'w' => 16, 'h' => 16], ['x' => 32, 'y' => 0, 'w' => 16, 'h' => 16]], 'duration' => 0.1],
|
||
'idleLeft' => 'reverseIdleRight', // same frames, flipped
|
||
'walkLeft' => 'reverseWalkRight',
|
||
'dieRight' => ['coords' => [...], 'loop' => false], // isAnimationDone() at the end
|
||
];
|
||
|
||
public function __construct(Sdl $sdl, float $x, float $y)
|
||
{
|
||
$this->x = $x; $this->y = $y; $this->width = 12; $this->height = 16;
|
||
$this->gravity = 900; $this->maxFallSpeed = 500;
|
||
$sdl->hasTexture('hero') || $sdl->loadTexture('hero', 'assets/sprites/hero.png');
|
||
$this->initSprite($sdl, 'hero', 'idleRight');
|
||
}
|
||
|
||
public function update(float $dt): void
|
||
{
|
||
$this->updateGravity($dt); // vy += gravity
|
||
$this->state = abs($this->vx) > 5 ? 'walk' : 'idle';
|
||
$this->pickAnimation(); // "<state><Facing>"
|
||
$this->updateSprite($dt); // next frame
|
||
// the scene then calls $collisions->move($hero, $map, $dt) to move against the tiles
|
||
}
|
||
|
||
public function render(Renderer $r, float $camX = 0, float $camY = 0): void
|
||
{
|
||
$this->drawAt($r, $this->x - $camX, $this->y - $camY);
|
||
}
|
||
}
|
||
```
|
||
|
||
- `Sprite`: `initSprite($sdl, $textureName, $firstAnimation)`, `setAnimation()`, `hasAnimation()`,
|
||
`getAnimation()`, `isAnimationDone()`, `drawAt($r, $x, $y, $forceFlip = false, $scale = 1)`.
|
||
Animation keys: `coords` (frames in the sheet), `duration` (s per frame, default 0.1), `loop` (default true),
|
||
`offset` ([dx, dy] drawing offset), `flags.flip`.
|
||
- `Gravity`: `$gravity` (px/s², default 900), `$maxFallSpeed`, `setGravity()`, `enableGravity(false)`.
|
||
- `TileCollision`: `$onGround`, `$onCeiling`, `$onWallLeft`, `$onWallRight`, `$groundGid` (filled by CollisionSystem).
|
||
|
||
`EntityManager` (inject it in the scene constructor; one per scene):
|
||
`register('coin', Coin::class)` or `register('enemy', fn (array $o) => new Enemy(...))`,
|
||
`spawnFromMap($map)`, `add($e)`, `remove($e)`, `clear()`, `update($dt, $camera)` (entities far from the
|
||
camera wait), `render($r, $camera)`, `all()`, `ofClass(Enemy::class)`, `overlapping($rect, $except)`,
|
||
`count()`. Dead entities (`kill()`) are removed automatically.
|
||
|
||
---
|
||
|
||
## 7. Drawing, textures, text
|
||
|
||
`Renderer $r` (in `render()`), view coordinates:
|
||
|
||
| Call | |
|
||
|---|---|
|
||
| `clear($color)` | fills the view |
|
||
| `fillRect($x, $y, $w, $h, $color)` | colour with alpha < 255 = translucent (works without blend modes) |
|
||
| `drawRect($x, $y, $w, $h, $color, $thickness = 1)` | outline |
|
||
| `drawLine($x1, $y1, $x2, $y2, $color)`, `drawPoint($x, $y, $color)` | |
|
||
| `fillCircle($cx, $cy, $radius, $color)` | |
|
||
| `copy($texture, $src = [x,y,w,h] or null, $x, $y, $w = null, $h = null, $flipH = false, $flipV = false, $angle = 0)` | draws a texture |
|
||
| `getWidth()`, `getHeight()` | view size |
|
||
| `setTarget($texture)` / `setTarget($r->getViewTexture())` | draw into a texture (caches) |
|
||
| `getRenderer()` | the raw SDL renderer for `\SDL_*` calls |
|
||
|
||
Colours everywhere: `[r, g, b]`, `[r, g, b, a]`, `'#rgb'`, `'#rrggbb'`, `'#rrggbbaa'` or `new Color(...)`.
|
||
|
||
Textures (`$this->sdl()`, class `Sdl`): textures have names.
|
||
|
||
| Call | |
|
||
|---|---|
|
||
| `loadTexture('hero', 'assets/sprites/hero.png', $transparentRgb = null)` | now; PNG alpha kept; `[255,0,255]` = colour key |
|
||
| `registerTexture('lvl2', 'assets/tiles/lvl2.png', 'level2')` + `loadGroup('level2')` / `releaseGroupsExcept('level2')` | lazy, per level |
|
||
| `getTexture('hero')` | `['texture' => resource, 'width' => int, 'height' => int, 'x' => 0]` |
|
||
| `hasTexture('hero')` | |
|
||
| `createTextureFromPixels('heart', ['.#.#.', '#####', '.###.', '..#..'], ['#' => '#e33'], $scale = 1)` | pixel art in code, `.`/space = transparent |
|
||
| `createTextureFromGd('name', $gdImage)` | draw with GD (imagefilledpolygon...) then use as texture |
|
||
| `createTexture('name', $w, $h)` | empty render target |
|
||
| `setTextureVariant('-night')` | `getTexture('tiles')` returns `tiles-night` when it exists |
|
||
|
||
The `createTexture*()` / `loadTexture()` calls return a **list of slices** (wide images are cut): the resource is
|
||
`getTexture('name')['texture']` (or `[0]['texture']` of what they return), not `['texture']` of the return value.
|
||
|
||
Text: `$this->font()` is the built-in **BitmapFont** (5×7 pixels, upper case, no file):
|
||
`draw($r, $text, $x, $y, $scale = 1, $color = white, $align = 'left'|'center'|'right', $shadowColor = null)`,
|
||
`width($text, $scale)`, `height($scale)`, `lineHeight($scale)`. `\n` makes new lines.
|
||
A TTF font: `$font = new TtfFont($this->sdl(), 'assets/fonts/x.ttf', 8)` (same interface `TextDrawer`);
|
||
`$this->engine->setFont($font)` makes it the default one. `new TtfFont($sdl, $file, $size, smooth: true, style: TtfFont::BOLD,
|
||
thicken: 0.3, outline: 0.5)`: anti-aliased, bold, its strokes thickened (view pixels: a thin variable font's default
|
||
instance made bolder), and draw()'s shadow colour drawn as an outline around the letters. Smooth text wants `hd: auto`.
|
||
|
||
Helpers: `Hud::panel($r, $x, $y, $w, $h)`, `Hud::bar($r, $x, $y, $w, $h, $ratio)`,
|
||
`Hud::message($r, $font, "TEXT", $cx, $cy)`, `Hud::blink($time)`, `CrtFilter::apply($r)` (scanlines).
|
||
|
||
**Camera** (`JumPHP\Scene\Camera`): `new Camera($this->width(), $this->height())`, `setBounds(0, 0, $mapW, $mapH)`,
|
||
`follow($entity, $deadZoneW = 0.2, $deadZoneH = 0.3, $smoothing = 0)`, `update($dt)`, `getX()`, `getY()`
|
||
(whole pixels, subtract them when drawing), `centerOn()`, `lock()`, `shake($strength, $seconds)`,
|
||
`setOffset()`, `isVisible($rect, $margin)`, `worldToScreen()`.
|
||
|
||
---
|
||
|
||
## 8. Tiles and collisions
|
||
|
||
**Maps** (`JumPHP\Tile\TileMap`): layers of global tile ids (0 = empty), tilesets, objects, properties.
|
||
|
||
- From **Tiled** (recommended for real levels, https://www.mapeditor.org): save as JSON `.tmj`, tilesets
|
||
embedded or `.tsj`, one image per tileset, "Infinite" off.
|
||
`$map = TiledJsonLoader::load($this->engine->config->path('assets/maps/level1.tmj'));`
|
||
- collision layer: the layer named `collision` (or with the bool property `collision`), else the first one;
|
||
- per-tile collision: tile property `collision` = `full` | `none` | `oneway` | `slope:FROM,TO` (heights in
|
||
px at the left / right edge, e.g. `slope:0,16`) | `heights:h0,h1,...` | `oneway-slope:...`, or shapes drawn
|
||
in Tiled's collision editor (rectangles / polygons). Without anything a tile of the collision layer is solid;
|
||
- layer property `foreground` (bool) = drawn over the entities; layer `visible` off = not drawn;
|
||
- objects (object layers): `$map->objects` = `['type','name','x','y','width','height','properties','layer','gid']`,
|
||
`$map->object('start')`, `$map->objectsOfType('coin')`; tile properties: `$map->tileProperty($gid, 'hazard')`;
|
||
- animated tiles (Tiled animation editor), flipped tiles, image layers with parallax: supported.
|
||
- From **rows in code** (prototypes, tests, generated levels):
|
||
```php
|
||
$map = ArrayLoader::fromRows([
|
||
'..........',
|
||
'..P...C...',
|
||
'####==####',
|
||
], legend: ['#' => 1, '=' => 2], objects: ['P' => 'start', 'C' => 'coin'], tileWidth: 16, tileset: 'assets/tiles/tiles.png');
|
||
$map->tilesets[0]->masks[1] = CollisionMask::oneWay(); // gid 2 = local id 1
|
||
```
|
||
Without `tileset`, solid tiles are drawn as flat blocks.
|
||
- From **raw bytes** (`BinaryLoader::load($file, $w, $h, $tileW, $tileH, $image, $columns, $solidityFile, $shapes)`):
|
||
one byte per tile, for levels ripped from old games.
|
||
|
||
Masks (`CollisionMask`): `full()`, `none()`, `oneWay()`, `slope($w, $h, $fromHeight, $toHeight)`,
|
||
`heights([...], $h)`, `fromRows(['#...', ...])`, `parse('slope:0,16', $w, $h)`.
|
||
|
||
Drawing: inject `TileMapRenderer $tiles` in the scene; in `render()`:
|
||
```php
|
||
$this->tiles->renderBackground($r, $map, $camera->getX(), $camera->getY(), $this->time);
|
||
$this->entities->render($r, $camera);
|
||
$this->tiles->renderForeground($r, $map, $camera->getX(), $camera->getY(), $this->time);
|
||
```
|
||
|
||
Collisions with tiles: inject `CollisionSystem $collisions` (one per scene). Each frame, set the velocity
|
||
then `$result = $this->collisions->move($entity, $map, $dt);` — it moves pixel by pixel, stops at walls,
|
||
lands on floors / one-way platforms, climbs slopes and steps up to `$maxStepUp` px (4), sticks to the ground
|
||
going down (`$snapDown`), and fills `TileCollision` flags. `CollisionResult`: `onGround`, `hitCeiling`,
|
||
`hitLeft`, `hitRight`, `hitWall()`, `groundGid`, `platform`.
|
||
Options: `$collisions->solidEdges` (map sides are walls), `touchLayers = ['items']`,
|
||
`setPlatformProvider(fn () => [['x'=>..,'y'=>..,'width'=>..,'height'=>..,'vx'=>..,'vy'=>..,'oneWay'=>true]])` (moving platforms carry the entity).
|
||
Events: `$collisions->on('touch', fn (Entity $e, string $layer, int $tx, int $ty, int $gid, array $props) => ...)`
|
||
for tiles that have properties (collect: `$map->setTile($layer, $tx, $ty, 0)`), `on('fell', fn (Entity $e) => ...)`.
|
||
Remove old listeners in `enter()`: `$this->collisions->removeAllListeners();`.
|
||
`isSolidAt($map, $px, $py)`, `groundBelow($map, $x, $y)` for AI (edge detection).
|
||
|
||
Entity vs entity: `Aabb::intersects($a, $b)`, `Aabb::overlap($a, $b)` (push-out vector), `Aabb::sweep(...)`,
|
||
`$entity->intersects($rect)`, `$entities->overlapping($rect)`.
|
||
|
||
Steady physics: `FixedStep` — `$this->step = new FixedStep(120); $this->step->run($dt, fn (float $h) => $this->simulate($h));`
|
||
(fast objects: use 120 Hz so they do not tunnel).
|
||
|
||
---
|
||
|
||
## 9. Input, sound, saves, language, network
|
||
|
||
**Input** (`$this->actions()`, `ActionMap`): `isPressed('jump')` (this frame), `isHeld()`, `isReleased()`,
|
||
`axis('left', 'right')` (-1/0/1), `label('confirm')` (key name for texts), `hold($action, $bool)` /
|
||
`press($action)` (bots, demos). Raw: `$this->engine->input->getKeyboard()->isKeyHeld(\SDLK_x)`,
|
||
`getMouse()->x/y/isHeld(1)` (view coordinates), `getTouch()->active/x/y` (0..1 of the screen),
|
||
`getGamepad()`. config/input.yaml binding names: SDL key names (`Left`, `Space`, `Return`, `Escape`,
|
||
`Left Shift`, `A`..`Z`, `0`..`9`, `F1`..`F12`, `Keypad 8`), gamepad names (below), `touch:tap`,
|
||
`touch:left`, `mouse:1`. Global keys: F3 debug overlay, F11 fullscreen (desktop).
|
||
|
||
**Gamepads** (`$this->engine->input->getGamepad()`): the same names on every pad and target (W3C "standard"
|
||
layout, Xbox names): `pad0:a b x y lb rb lt rt select start home ls rs up down left right`, stick directions
|
||
`pad0:ls_left`... `pad0:rs_down` (`pad0:left` = d-pad OR left stick), raw `pad0:button3`. Defaults:
|
||
confirm = `pad0:a`, back = `pad0:b`, pause = `pad0:start`. Analog: `axis(0, 'lx')` (-1..1, dead zone
|
||
applied; `lx ly rx ry`, triggers `lt rt` 0..1), `isButtonHeld(0, 'a')`, `count()`, `name(0)`, `isConnected(1)`,
|
||
`rumble(0, $strong, $weak, $seconds)` (browser), events `connect` / `disconnect`. Browser: Gamepad API.
|
||
Desktop: SDL joystick events with an Xbox / PlayStation table (no hat events in the binding: a d-pad seen as
|
||
a hat is invisible there, the left stick works).
|
||
In the browser, phones get an on-screen pad (arrows + A/B/START buttons; set their keys in
|
||
`project.yaml touch: {a: Space, b: Escape, start: Return}`).
|
||
|
||
**Sound** (`$this->sound()`, `SoundManager`): `loadSfx('jump', 'assets/sfx/jump.wav')`,
|
||
`synth('jump', Synth::sweep(300, 900, 0.15))` (generated: `Synth::tone($hz, $s, 'square'|'triangle'|'sine'|'saw')`,
|
||
`sweep($from, $to, $s)`, `noise($s)`, `sequence([[hz, s], ...])`), `playSfx('jump', $loops = 0)`, `stopSfx()`,
|
||
`hasSfx()`, `loadMusic('level', 'assets/music/level.ogg', 'assets/music/level-intro.ogg')`,
|
||
`playMusic('level')`, `stopMusic()`, `setSfxVolume(0..1)`, `setMusicVolume(0..1)`, `setMuted()`.
|
||
Without an audio device everything is silent, never an error. Formats: wav, ogg, mp3. Load each sound once
|
||
(`if (!$this->sound()->hasSfx('x'))`).
|
||
|
||
**Saves**: `$this->engine->storage->writeJson('save.json', $data)`, `readJson('save.json', $default)`,
|
||
`exists()`, `delete()`; settings: `$this->engine->options->get('difficulty', 'normal')`, `->set(...)`
|
||
(saved at once). Engine option keys: `sfx_volume`, `music_volume`, `fullscreen`, `lang`.
|
||
|
||
**Language**: `config/lang.yaml` (`fr: {'PLAY': 'JOUER'}`), `Lang::t('PLAY')`, `Lang::t('{n} COINS', ['n' => 3])`,
|
||
`$this->engine->lang->setLang('fr')`, `available()`. Menus translate their labels.
|
||
|
||
**Timers**: `$this->engine->gameLoop->addTimer(1.5, fn () => ...)`, `addPeriodicTimer()`, `GameLoop::nextTick()`.
|
||
Prefer counting `$dt` in the scene (timers keep running when the scene changes: check
|
||
`$this->scenes()->current() === $this` in the callback).
|
||
|
||
**Network** (online multiplayer, same code desktop and browser):
|
||
1. `bin/jumphp relay up` (server on `ws://localhost:8090/ws`; `project.yaml net_url`, or `?net=wss://host/ws` in the page URL, or env `JUMPHP_NET_URL`).
|
||
2. Lobby: `$this->scenes()->switchTo(LobbyScene::class, ['next' => PlayScene::class, 'nextParams' => ['mode' => 'online'], 'back' => TitleScene::class, 'players' => 2])`.
|
||
It creates / joins (4-letter code) / quick-matches a room, then switches to `next` with
|
||
`['online' => true, 'net' => NetSession, 'host' => bool, 'peer' => int] + nextParams`.
|
||
`'auto' => 'quick'|'host'|'ABCD'` skips its menu; `?room=ABCD` in the page URL joins directly.
|
||
3. In the game scene (`NetSession $net = $params['net']`):
|
||
```php
|
||
$net->removeAllListeners();
|
||
$net->on('message', fn (int $from, int $type, string $payload) => ...);
|
||
$net->on('peerLeave', fn (int $peer) => ...);
|
||
$net->send(MSG_STATE, pack('gg', $x, $y), reliable: false); // frequent state: unreliable
|
||
$net->sendJson(MSG_EVENT, ['goal' => 1]); // rare events: reliable JSON
|
||
```
|
||
The engine polls the session every frame. `isHost()`, `peerId()`, `peers()`, `playerCount()`, `roomCode()`,
|
||
`lastPing()` (after `ping()`), `close()`. Decode: `MessageCodec::unpack('gx/gy', $payload)`, `MessageCodec::unjson($payload)`.
|
||
4. Design: the **host is the authority** (simulates, scores) and sends snapshots ~20/s; others send their
|
||
input/state ~30/s; draw remote things through `SnapshotBuffer` (`push($this->engine->time(), $state)`,
|
||
`sample($this->engine->time())`, 100-120 ms behind). One type byte per message. 64 KB max, 16 players max.
|
||
See `games/pong/src/Scene/PlayScene.php` and `src/Net/PongProtocol.php`.
|
||
5. Test online headless: two processes with `JUMPHP_REALTIME=1`, `JUMPHP_SCENE='JumPHP\Net\LobbyScene'`,
|
||
`JUMPHP_SCENE_PARAMS='{"next":"App\\Scene\\PlayScene","nextParams":{"mode":"online"},"auto":"quick"}'`,
|
||
`JUMPHP_NET_URL=ws://127.0.0.1:8090/ws` and `--network host` (see docs/reseau.md).
|
||
6. Private rooms without a code (a cloud account, a pairing): `$net->enter($longId, $maxPeers)` joins or creates the room
|
||
`$longId` (32-64 chars `[A-Za-z0-9_-]`, `NetSession::newRoomId()`; needs `docker/relay/room-id.patch`, error `room-id` otherwise);
|
||
binary payloads up to `NetSession::MAX_PAYLOAD` (65535). Desktop LAN file sharing: `JumPHP\Net\HttpServer` (non-blocking
|
||
HTTP/1.1, `poll()` each frame, `HttpResponse::file()` streamed with Range / HEAD, client filter `isPrivateAddress()`; not in the
|
||
browser). docs/reseau.md.
|
||
|
||
**TCP** (`$this->engine->tcp()`, `JumPHP\Net\Tcp`; a SQL client, a Redis tool...): `$c = $engine->tcp()->connect($host, $port)`, events
|
||
`open`, `data` (string), `close` (?string reason), `error` (string); `$c->write($bytes)`, `$c->close()`. Never blocks. Desktop: a plain socket.
|
||
**Browser**: no socket exists, so it goes through the playground's **TCP bridge** (WebSocket -> TCP), only for an application the
|
||
**administrator approved** for this exact commit: the owner asks in the studio (project page, "Accès TCP"), the administrator
|
||
(`davidnurdin`) approves or refuses from his notifications; a modified application must be approved again. The page gets a 2-minute
|
||
ticket (`POST /api/tcp/ticket`, project.yaml `tcp_ticket_url`, default: the page's own origin in the browser, https://jumphp.net/api/tcp/ticket elsewhere; env JUMPHP_TCP_URL wins) signed with the app's Ed25519 key
|
||
(kept encrypted on the owner's account) and the platform's signature of the approval (slug | commit | public key); the bridge
|
||
(`docker/tcpbridge` of the playground) checks both, allows ANY port 1-65535 (tcp and udp; the port is `connect($host, $port)`, in the ticket's `port`) except the bridge's deny list (`TCP_DENY_PORTS`, default 25,465,587 = outgoing mail; a `tcp` ticket may not name 22: SSH is the `ssh` right), never a private or
|
||
reserved address; a refused port says so in the `error` event ("port 25 is denied by the platform"). Without approval the `error` event says why. Code that must work on both: use `Tcp`, never `stream_socket_client`
|
||
(rule 4). The administrator sees every connection live (Administration: open connections, bandwidth, who asked, log) and can cut or block an application or an address; quotas (`TCP_QUOTA_MB_PER_HOUR`) block an abuser and raise an alert (docs/tcp.md). Example: `apps/jumphpsql` (`MysqlConnection` takes `['tcp' => $engine->tcp()]` in its config). Tests: `engine/tests/Net/TcpTest.php`.
|
||
|
||
**Using the user's own network: JumPHP runtime** (docs/runtime.md, docs/runtime.en.md; protocol: docs/runtime-protocol.md). In the browser the bridge above only sees what the
|
||
server sees. The **JumPHP runtime** is a small program on the user's computer (tray icon, `ws://127.0.0.1:47820/v1`) that lets the application connect from the user's IP and
|
||
network (LAN, VPN, IP-filtered server) **with their consent** (a native window of the runtime; the administrator's ticket is still required: two doors). project.yaml `net_mode`
|
||
(or `JUMPHP_NET_MODE`, page `?net_mode=`): `auto` (default: the runtime when `ready`, else the server), `server`, `local` (the runtime, or an error with the state). `Tcp`, `Ssh`, `Udp`, `Icmp`
|
||
keep asking the ticket from the server, then open the server's `bridge` or the runtime's address (`JumPHP\Net\BridgeRoute`); the core only knows the `JumPHP\Net\RuntimeLink` interface
|
||
(`$engine->runtime()`, default `NoRuntime` = `unsupported`), the engine itself (since 0.5.27; `engine/src/Runtime/`, samples and docs in `extensions/runtime`, demo `games/runtime-demo`) puts its `RuntimeClient` there in the browser (state
|
||
`unknown | checking | missing | running | ready | refused | unsupported`, `check()`, `pair($app, $title)`, event `change`) and brings the Gui widgets `JumPHP\Runtime\RuntimeBanner` (**the one line an application adds**: `{class: JumPHP\Runtime\RuntimeBanner, id: runtimeBanner}`: the whole notice, what to do on Android (one button opens the runtime app or the install guide, `docs/runtime-android`), on a computer (the guide), when it runs (ask the permission), "Not now" remembered; an iPhone is told the server is used) and `JumPHP\Runtime\RuntimeBadge`
|
||
(`{class: JumPHP\Runtime\RuntimeBadge}`: green active, orange allow this app (click = `pair`), red install (click = the `RuntimeGuide` dialog), grey server bridge) and `RuntimeGuide`. Only active when
|
||
`Platform::isWasm()`. Tests: `new ManualRuntime(RuntimeLink::READY)` through `$engine->setRuntime()`. **AI agents**: use it for a browser *application* that must reach the user's network, add the badge next
|
||
to the connection fields, keep `net_mode: auto`, keep the connection code unchanged; never bypass the consent (no hand-made WebSocket to the runtime, no edit of its `grants.json`), never ask the user to disable
|
||
a security (firewall, Local Network Access, mixed content, origin allow-list), never default a published app to `net_mode: local`.
|
||
|
||
The runtime client **always looks** (8 s while missing / blocked, 20 s otherwise, at once after a failed connection, when the tab or the network comes back) and when the runtime is ready the badge shows a **Local | Server switch**: the user can go back to the server's proxy for new connections (`RuntimeClient::setUseServer()`, option `net_use_server`).
|
||
|
||
**UDP and ICMP** (`$this->engine->udp()`, `$this->engine->icmp()`; docs/tcp.md): `$c = $engine->udp()->open($host, $port)` has the events of `Tcp` but every `data` is ONE datagram and every
|
||
`write()` sends one (DNS, NTP, game servers); `$engine->icmp()->ping($host, $count, $ttl)` is a Task of replies (`['seq', 'ok', 'ms', 'ttl', 'from']`, or `'error' => 'ttl', 'hop'` for a traceroute with growing TTLs). Desktop: a plain
|
||
UDP socket, the system's `ping`. Browser: the TCP bridge, with the **udp** / **icmp** rights (separate, approved by the administrator per commit, like tcp and ssh); udp: any public address, 300 datagrams a
|
||
second; icmp: the bridge host's `ping`, one at a time, 5 a second, 200 a connection. **No Fibers in the browser** (PHP's Fiber needs `getcontext`: "The engine crashed: -1"): use generators for a coroutine
|
||
(`apps/jumphpsql` `MysqlConnection`).
|
||
|
||
**SSH** (`$this->engine->ssh()`, `JumPHP\Net\Ssh`; docs/ssh-wasm.md): `$c = $engine->ssh()->connect($host, $port, ['sshHost' => ..., 'sshUser' => ..., 'sshKey' => $keyText, 'sshPassphrase' => ..., 'knownHosts' => ...])`
|
||
pipes a stream to `$host:$port` through an SSH server (`ssh -W`), with the events of `Tcp` (`open`, `data`, `close`, `error`, plus `knownHosts`); `$engine->ssh()->via($options)` has
|
||
`Tcp`'s `connect($host, $port, $timeout)` for code that takes either. Desktop: the system's `ssh`. **Browser**: the real OpenSSH client compiled to WebAssembly
|
||
(`ssh.wasm`, `docker/ssh-wasm`) in a Web Worker, **piped between two wasm** (the application's PHP and ssh.wasm talk through the page's JsBridge: stdin / stdout are the stream), its network the
|
||
TCP bridge in raw mode. It needs the **SSH right** of the application (separate from TCP, same approval flow: owner asks, administrator approves per commit) and a key the application
|
||
has: ask for the file with `FilePicker::open()` (works in the browser: the file lands in `/tmp/jumphp-picked/`, call it from a click) and keep it in the **key ring** (`$engine->sshKeyring()`: add / remove / all / names, kept in var/ssh_keyring.json: an agent's role, the browser has no ssh-agent; pass `'sshKeys' => $ring->all()`, ssh tries every key). One SSH session carries ONE stream (`ssh -W`): several connections = several sessions (ControlMaster and `-L` need unix sockets and listening sockets, which a browser does not have). Pasted keys are fine too (`Endpoint::browserSsh()` of jumphpsql).
|
||
|
||
**Threads** (`JumPHP\Async`, `$this->engine->tasks()`): heavy work (level generation, path finding, AI,
|
||
procedural pictures) off the main thread, so the frame never waits.
|
||
|
||
- One API, three backends (`Tasks::backend()`):
|
||
- `'threads'`: desktop with the **async runtime** (`runtime: async` in `project.yaml`: `bin/jumphp` runs the
|
||
game on PHP 8.6 ZTS + [TrueAsync](https://true-async.github.io), `docker/desktop-async`);
|
||
- `'workers'`: **the browser**: a pool of Web Workers, each running its own PHP engine with the game's
|
||
files (`engine/web/jumphp-worker.js`; cores - 1, at most 4; `?workers=N` in the page URL, 0 = none);
|
||
- `'frames'`: default desktop runtime (PHP 8.5): jobs run on the main thread between frames,
|
||
`$tasks->budget` ms per frame (4 by default, at least one job). Also the fallback when no Web Worker
|
||
can start.
|
||
`Tasks::threaded()` is true for the first two. A game must be correct with all three.
|
||
- API:
|
||
```php
|
||
$task = $this->engine->tasks()->thread(static fn () => Maze::generate(64, 48, $seed)); // one job, one thread
|
||
$pool = $this->engine->tasks()->pool(); // one worker per core (Tasks::workers()); in enter()
|
||
$job = $pool->submit(static fn (int $y) => Fractal::row($y, 192), $y) // never blocks
|
||
->then(fn (string $row) => $this->rows[$y] = $row, fn (\Throwable $e) => ...); // main thread
|
||
$task->isDone(); $task->isOk(); $task->result(); $task->error();
|
||
$pool->close(); // in exit()
|
||
```
|
||
The engine polls the tasks at the start of each frame (before the scenes update): `then()` callbacks run
|
||
there, on the main thread, so they may touch the scene.
|
||
- **What crosses to a thread is a copy**, in a fresh PHP world that only has the game's autoloader
|
||
(`vendor/autoload.php`): no engine, no SDL, no scene, no container. In the browser the closure travels as
|
||
its source code + captured values (laravel/serializable-closure): its scope class (the class it is written
|
||
in, for `self::`) must be autoloadable, which scenes are. Use **`static fn`**: a closure written
|
||
in a method carries `$this` (the scene and its SDL resources) even if it does not use it, and is refused
|
||
with a `LogicException` in both modes. Pass plain values (int, float, string, arrays, simple objects); return
|
||
plain values. No references (`&$x`), no resources (files, textures, sounds), no objects with dynamic
|
||
properties. Put thread code in plain static classes (e.g. `src/Work/`, excluded from the container in
|
||
`config/services.yaml`).
|
||
- An exception in a thread comes back as `JumPHP\Async\TaskFailed` (`->class`, message, file, line of the
|
||
original): `$task->error()`, or `result()` rethrows it.
|
||
- Results only arrive between frames (TrueAsync reports finished threads while the desktop loop sleeps;
|
||
headless runs wait 1 ms per frame while tasks are pending; the page hands Web Worker results over once per
|
||
frame): never busy-loop on `isDone()`. A Web Worker needs ~0.5-1 s to boot its engine: create the pool early
|
||
(in `enter()`), it starts the workers at once.
|
||
- Rows of an older request can arrive after a new one started: tag jobs (a generation counter) and ignore
|
||
stale results. Example: `games/hello-threads` (fractal by a thread pool, 60 FPS kept).
|
||
- Raw TrueAsync (`Async\spawn`, coroutines, channels, `Async\ThreadChannel`) is available in the async runtime
|
||
too, but only `JumPHP\Async` also works in the browser. Browser jobs can not share memory with the game
|
||
(each worker is a separate PHP): no global state survives between jobs on purpose.
|
||
|
||
**Sandboxes** (`Cryo\Sandbox\Sandbox`, ext-cryo, `docs/cryo.md`): untrusted or fragile PHP code (player scripts,
|
||
mods, puzzles) in another PHP instance (browser: a Web Worker with its own engine; desktop: a child process),
|
||
with `timeout`, `memory_limit`, `disable_functions`: a crash, a fatal error or an endless loop there never touches
|
||
the game. **Asynchronous only in the browser**: `$sb = JumPHP\Cryo\SandboxLoop::spawn([...])` in `enter()`, then
|
||
`$sb->callAsync('fn', $args)` / `evalAsync()` / `getAsync()` / `setAsync()` return a `Cryo\Sandbox\Future`: read its
|
||
flags each frame (`status()`: pending, ready, failed, cancelled; `value()`, `error()`), or `->then(fn ($v) => ...,
|
||
fn (\Throwable $e) => ...)`; `SandboxLoop::wait([$a, $b], $timeout)` gives a `Task`. The synchronous calls
|
||
(`call()`, `eval()`, `await()` of a pending future) throw in the browser. Example: `games/cryo-sandbox-demo`.
|
||
|
||
**HTTP** (`$this->engine->http()`, never blocks): `get($url, $headers)`, `post($url, $body)` (array = JSON),
|
||
`request($method, $url, $body, $headers, $timeout)` return a `Task`:
|
||
`->then(fn (HttpResponse $r) => ..., fn (\Throwable $e) => ...)`. Any status settles it (`$r->status`, `ok()`,
|
||
`json()`, `header('content-type')`, `body`); `HttpError` = no answer (network, timeout, CORS). Browser:
|
||
`fetch()` (the server must allow CORS); desktop: curl_multi, or non-blocking sockets (async runtime).
|
||
|
||
**User accounts and their data on jumphp.net** (`JumPHP\Platform\AppAccount`, docs/platform-account.md; server side:
|
||
https://jumphp.net/docs/comptes-applications and /docs/donnees-applications). Any application published on jumphp.net gets, for free,
|
||
accounts for its users (pseudo + password, no e-mail, a recovery code shown once) and per-account storage, on desktop, browser and
|
||
Android. **Use it instead of writing a server or calling these URLs by hand** whenever an app must sign users in or keep their data
|
||
across devices. `$account = AppAccount::for($this->engine)` (slug = project.yaml `id`; `platform_url` / `JUMPHP_PLATFORM_URL` for
|
||
another server); every call is a `Task` (never blocks), failures are `AppAccountError` (`errorCode`, `status`, `data`):
|
||
- sign-in: `signUp($login, $password, $deviceName)` -> `{login, recovery}`, `signIn()`, `recover($login, $code, $newPassword)`,
|
||
`signOut()`, `signedIn()`, `me()`, `devices()`, `revokeDevice($id)`, `hello()` (presence, every 60 s), `changePassword()`,
|
||
`deleteAccount($password)`, `onSignedOut` (token revoked elsewhere). The device token lives in `var/jumphp-account.json`.
|
||
- key/value (keys `[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}`, JSON values or text, 64 KB): `get($key)` (null when absent), `value($key,
|
||
$default)`, `set($key, $value, $ifMatch)`, `setText()`, `delete()`, `search(prefix:, match: 'score:*', limit:, cursor:, values:)` ->
|
||
`{items, next}`, `getMany([...])` -> `{items, missing}`. Two devices: pass the version read as `$ifMatch`; a conflict fails with
|
||
`$e->isConflict()` and `$e->data['current']` (merge, write again).
|
||
- objects (opaque bytes, 2 MB, the last `keep` versions kept, 1..50, default 10): `store($name, $phpValue, keep:)` (serialize) and
|
||
`load($name, [Allowed::class, ...], $version)` (unserialize with **only** those classes; a class outside the list fails with
|
||
`unserialize`: **never call `unserialize()` on network bytes without `allowed_classes`**), `put($name, $bytes, $format)`,
|
||
`getObject($name, $version)`, `versions($name)`, `objects()`, `deleteObject()`. Store plain models (no closures, resources, textures).
|
||
- tests: `new AppAccount($fakeRequest, $url, new Storage($tmp))` with a closure that settles `HttpResponse`s
|
||
(`engine/tests/Platform/AppAccountTest.php`). Never put a token in the repository; never log it.
|
||
The owner sees the accounts with the playground's MCP tools `app_accounts_stats`, `list_app_accounts`, `get_app_account_data`,
|
||
`delete_app_account` (owner only, never passwords or tokens).
|
||
|
||
**Page / window life** (`$this->engine->lifecycle()`, same events on both targets): `hide` / `show` (tab
|
||
hidden, app in background / window minimized), `blur` / `focus`, `online` / `offline`, `resize` (w, h),
|
||
`orientation` ('landscape'|'portrait'), `fullscreen` (bool), `close` (page closing / game quitting: save NOW).
|
||
`hide` and `close` run at once in the browser, between frames, and var/ is written to IndexedDB right after.
|
||
While hidden the browser runs **one frame a second** (project.yaml `hidden_frames`, on by default since 0.5.63: a hidden tab gets no
|
||
`requestAnimationFrame`, so the page calls `jumphp_frame()` itself on a Web Worker's clock): network, pings, timers go on, `$dt` stays
|
||
capped at 0.1 s. A phone freezes the whole tab after a while: nothing runs then (push notifications, docs/notifications.md).
|
||
Connected applications (chat, online game): read **docs/browser-troubleshooting.en.md** (timeouts, resume after a cut,
|
||
notifications, the server's `stream_select`, time zone).
|
||
Getters `isVisible()`, `hasFocus()`, `isOnline()`, `orientation()`, `size()`. project.yaml `pause_scene` pushes
|
||
your pause menu automatically; the sound is muted while hidden.
|
||
|
||
**Phone features** (`$this->engine->device()`; what a device lacks does nothing): `vibrate(40)` / `vibrate([30,
|
||
20, 30])`, `keepAwake()` (Wake Lock; desktop: no screen saver), `lockOrientation('landscape')`,
|
||
`setFullscreen(true)` (at the next tap if the browser wants a gesture), `copy($text)` (clipboard),
|
||
`share($text, $url)`, `enableMotion()` then `tilt()` ([x, y] -1..1) / `motion()` (m/s²), `battery()`,
|
||
`isMobile()`, `isStandalone()`.
|
||
|
||
**OpenGL / WebGL** — the PHP-OpenGL extension ([Ponup/php-opengl](https://github.com/Ponup/php-opengl) +
|
||
`docker/ext/php-opengl.patch`) runs in SDL's own GL context: OpenGL on the desktop (GPU driver or Mesa), WebGL 1 in
|
||
the browser (the same `gl*` calls compiled by emscripten). Write **GLSL ES 1.00** (`attribute` / `varying` /
|
||
`gl_FragColor`, `precision mediump float;` in fragment shaders; `#version 100` is added): both targets accept it.
|
||
`isAvailable()` is false without a GL context (headless runs with the SDL dummy driver): draw a 2D fallback
|
||
(`Mat4::project()` does software 3D). Keep trigonometry arguments small in mediump (`sin(3.14159 * fract(x))`, not
|
||
`sin(x * 500.0)`: NaN on some GPUs).
|
||
|
||
- High level, `$this->engine->gl()` (`WebGl`): a 3D layer under / over the 2D and post-processing of the whole
|
||
picture. `setLayer('below'|'above', 'view'|'native', $keyColour)` (`setSupersample(2)`: the layer drawn at 2x, smoothed: anti-aliased) (below: the 3D shows where the 2D is the key
|
||
colour, e.g. clear with `[255, 0, 255]` and draw the HUD; there only opaque or black-translucent 2D reads well over the
|
||
3D). `setLayer('below', 'view', null)`: composed by the 2D's alpha instead: clear the 2D with `$r->clear([0, 0, 0, 0], true)` (`clear()` is opaque unless asked), then smooth
|
||
text and translucent panels of any colour lie over the 3D as they are (with `hd: auto` the view is the window's
|
||
resolution), resources once in `enter()`: `program($vsGlsl, $fsGlsl)`,
|
||
`buffer($floats)`, `updateBuffer()`, `indexBuffer($ints)`, `texture('assets/x.png')`, `textureFromRgba($w, $h, $bytes)`;
|
||
each frame in `render()`: `clear($colour)`, `draw($program, ['attributes' => ['a_pos' => [$buffer, 3, $stride,
|
||
$offset]], 'uniforms' => ['u_mvp' => Mat4::...], 'textures' => ['u_tex' => $id], 'cull' => 'back'])`.
|
||
`setPostShader('void main() { gl_FragColor = texture2D(u_frame, v_uv); }')` (inputs: `u_frame`, `v_uv`, `u_time`,
|
||
`u_resolution`, `u_viewport`, `u_view`), `setUniform()`, `disable()` in `exit()`.
|
||
- Low level, `$this->engine->opengl()` (`OpenGl`): raw `gl*` calls between `begin($clearColour)` and `end()` in
|
||
`render()` (a 3D target of the view size with depth; `end()` puts it into the 2D being drawn, alpha blended:
|
||
draw the HUD after it). SDL's GL state is saved / restored around it: **never call gl* outside begin() / end()**
|
||
(or the resource helpers `program()`, `buffer()`, `texture()`, `renderTarget()`, which do it themselves).
|
||
`setSupersample(2)`: smoother edges. All functions and constants: `engine/stubs/opengl.stub.php`
|
||
(+ the patch: framebuffers, `glGetIntegerv`, uniforms 2f/4f/fv/Matrix3fv, `glBufferSubData`, binary strings
|
||
for buffers / pixels: `pack('g*', ...)`).
|
||
- Colours 0..255 in the PHP API, 0..1 in GLSL. Compile errors: `on('error')` + stderr / console `[opengl]`.
|
||
- See `games/hello-webgl` (layer + post shaders, and `RawGlScene`: raw gl* + Audio3d) and `games/jumpball` (a
|
||
whole 3D game: the track in chunk buffers rebuilt with `updateBuffer()`, lit meshes, a shader sky).
|
||
- Headless: `bin/jumphp test` / `shot` run games that call `gl()` / `opengl()` on Xvfb (Mesa llvmpipe): the shots
|
||
show the real 3D. `JUMPHP_GL=0` forces the no-GL path (the fallback), `JUMPHP_GL=1` forces GL.
|
||
|
||
**Positional sound** (`$this->engine->audio3d()`, `Audio3d`: [Ponup/php-openal](https://github.com/Ponup/php-openal);
|
||
desktop OpenAL Soft, browser Web Audio): `load('engine', 'assets/sfx/engine.wav')` or `synth('beep', Synth::tone(...))`
|
||
(mono or stereo WAV, mixed to mono: only mono is placed in space), each frame `listener($position, $forward, $up)`,
|
||
`$voice = play('beep', [$x, $y, $z], $gain, $pitch, loop: true)`, `move($voice, $position, $velocity)`, `setGain()`,
|
||
`setPitch()`, `isPlaying()`, `stop()`, `setDistance($reference, $rolloff, $max)`. Volume / mute follow SoundManager.
|
||
Music and plain sound effects stay in SoundManager. Raw `openal_*` functions: `engine/stubs/openal.stub.php`.
|
||
|
||
**Streamed sound** (`$this->engine->pcm()`, `PcmStream`): raw PCM made by the game (an emulated sound chip, a tracker,
|
||
a synthesizer), played back to back without gaps: signed 16-bit little-endian, mono or interleaved stereo, any rate.
|
||
Each frame keep a little ahead: `while ($pcm->buffered() < 0.1) $pcm->push($emu->render(1024), 22050, 2);`;
|
||
`clear()` drops what is queued. Browser: the page schedules the blocks on the Web Audio clock (`jumphp-pcm.js`);
|
||
desktop: SDL_mixer chunks one after the other (frame precision). Volume / mute = SoundManager's music volume.
|
||
Without a device `buffered()` is large and `push()` does nothing.
|
||
|
||
**PWA** (`$this->engine->pwa()`, project.yaml `pwa: true`): the build adds manifest, icons (from
|
||
`assets/icon.png`, else the title's initial) and a service worker caching the whole build: installable, plays
|
||
offline (https or localhost). `canInstall()` / `install()` (Task: true when accepted; put it in a menu),
|
||
`isInstalled()`, `isOfflineReady()`, `updateReady()` / `applyUpdate()` (reloads into the newer build), events
|
||
`installable`, `installed`, `offline`, `update`. The page itself shows a small bar while the network is gone ("offline, the app runs
|
||
with cached data", also when the worker had to answer from its cache) and a "new version, reload" bar when a newer build waits
|
||
(14 languages, `engine/web/jumphp-pwa.js`): the game needs no UI of its own for that.
|
||
|
||
**Install entry in the playground** (a game framed by a portal page, `pwa()->hasPortal()`): the frame cannot be installed, its page can. `pwa()->canInstall()` / `install()` use the page's own prompt (postMessage `jumphp:install-query` / `jumphp:install` / `jumphp:install-menu`, answer `jumphp:install-info`), `pwa()->downloads()` lists the native installs (Windows / Linux / macOS / Android) of the project's releases, `pwa()->showInstallMenu()` opens the page's Install menu. On the playground every published game / application is an app of its own, installed from its page on the games' origin (manifest id and scope `/<slug>/play/`, apart from the installed jumphp.net site), and plays offline once opened (its worker keeps the page, the shared engine and the game's files); `installed` in `jumphp:install-info` says it is already installed. Put an "Install" entry in the settings menu of every game / app: `if ($pwa->canInstall()) ... install()`, else `if ($pwa->hasPortal()) ... showInstallMenu()`.
|
||
|
||
**Web page** (`$this->engine->bridge->send('open', ['url' => ...])`, `send('quit')`, `send('share', [...])`;
|
||
custom types reach `window.JumPHP.onBridge(msg)` and the parent frame as `postMessage({type: 'jumphp:bridge'})`).
|
||
Page -> game: `window.JumPHP.send('hello', {...})` in the page, `$this->engine->bridge->on('hello', fn (array $d) => ...)`
|
||
in PHP (delivered at the start of the next frame). `window.JumPHP.php('echo 1;')` runs PHP between frames
|
||
(debugging, browser tests).
|
||
`Platform::isWasm()`, `isDesktop()`, `isMobile()`. `$this->engine->quit()`: desktop closes, browser goes to
|
||
`?back=` or shows "thanks for playing".
|
||
|
||
---
|
||
|
||
## 10. Definition of done (always)
|
||
|
||
1. `bin/jumphp test <id>` passes (it runs your `smoke` scene 600 frames; make that a self-playing demo), with game
|
||
tests (below) for the main mechanics.
|
||
2. `bin/jumphp shot <id> 60` (title) and `JUMPHP_INPUT='[[5,"confirm"]]' bin/jumphp shot <id> 240 var/screenshots/play.png`
|
||
(in game): **open the PNGs and check** that what you see is what you intended.
|
||
3. Menus reachable, `pause` / `back` work, the game can be won / lost and restarted.
|
||
4. `bin/jumphp lint` passes.
|
||
5. If the browser engine exists (`build/engine/php-web.wasm`): `bin/jumphp build <id>` then
|
||
`bin/jumphp webshot <id> 6 '[[1,"Enter"]]'` passes and its screenshot looks right.
|
||
6. Update `games/<id>/AGENTS.md` (what the game is, its scenes, its controls, anything non-obvious).
|
||
|
||
### Game tests: tests that play the game
|
||
|
||
Besides plain unit tests (`games/<id>/tests/*Test.php`, PHPUnit 11), write a few **game tests**: a test that plays
|
||
the game, frame by frame, and checks what happened. Extend `JumPHP\Testing\GameTestCase`; `$this->game` drives it:
|
||
|
||
```php
|
||
<?php
|
||
namespace Tests;
|
||
|
||
use App\Entity\Paddle;
|
||
use App\Scene\PlayScene;
|
||
use JumPHP\Testing\GameTestCase;
|
||
|
||
final class PaddleTest extends GameTestCase
|
||
{
|
||
public function testThePaddleGoesFromTheTopToTheBottom(): void
|
||
{
|
||
$this->game->start(PlayScene::class, ['mode' => 'local']); // the scene, no fade, one frame
|
||
$paddle = $this->game->peek('left'); // a field of the scene, private or not
|
||
$this->game->hold('p1_up', 60); // an action held 60 frames (1 s), then let go
|
||
self::assertEqualsWithDelta(PlayScene::TOP, $paddle->getBoundingBox()['y'], 1);
|
||
$this->game->hold('p1_down', 90);
|
||
self::assertEqualsWithDelta(PlayScene::BOTTOM - Paddle::HEIGHT, $paddle->getBoundingBox()['y'], 1);
|
||
}
|
||
}
|
||
```
|
||
|
||
`start($scene, $params)`, `press($action, $frames = 1)`, `hold($action, $frames)`, `run($frames)`, `wait($seconds)`,
|
||
`scene()`, `peek($field, $object = null)`, `shot($name)` (a PNG of the frame). One game per PHP process: each test
|
||
starts the scene it needs. Test what the player sees happen: a move, a jump that lands, a pickup that scores, an
|
||
enemy that dies, a level that ends. Name tests as sentences (`testTheBallBouncesOnThePaddle`): they are shown as
|
||
such. Watched live: `bin/jumphp test` with `JUMPHP_LIVE=1` (the Claude Code pane `jumphp-live` sets it) writes the
|
||
frames as they run and each test's last frame (`var/live/tests/`); `JUMPHP_REALTIME=1` runs them at the game's speed.
|
||
They need SDL: `bin/jumphp test` runs them, and so does the playground's sandbox (MCP `run_tests`, without a
|
||
window): there each game test is **filmed** (`JUMPHP_FILM`: a frame every 4) and the owner replays it in the
|
||
studio, test by test. Write them **while you develop**, not at the end: a mechanic is done when its game test
|
||
passes and its frames show it.
|
||
|
||
## 11. Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---|---|
|
||
| `Unknown texture 'x'` | `loadTexture` / `createTexture*` before use (in `enter()` or the constructor), check the path |
|
||
| Black screen in a shot | the scene draws nothing or outside the view; `JUMPHP_DEBUG=1`; check `render()` uses view coordinates minus the camera |
|
||
| `Scene class ... not found` | namespace `App\Scene\...` must match `src/Scene/...php`; `bin/jumphp composer <id> dump-autoload` |
|
||
| A scene keeps old state | reset it in `enter()` |
|
||
| Entity sinks / jitters on the ground | move it only with `CollisionSystem::move()` (not also `Entity::update()` velocity integration); keep `width/height` = the collision box |
|
||
| Fast object goes through walls | `FixedStep(120)` or smaller speed |
|
||
| Smoke test fails on a warning | fix the warning: undefined index / property, division by zero... |
|
||
| Works on desktop, not in the browser | §2: a blocking call, a 64-bit integer, a socket, a missing file (only the game folder is packaged; `var/` is not) |
|
||
| Browser: "The game did not start" | open the console (webshot prints it): PHP boot error with file and line |
|
||
| `bin/jumphp install` fails fetching `php-wasm-network` | the first install clones it from git.jumphp.net (network needed once); later installs use the composer cache |
|
||
| Composer package needs an extension | not possible in the browser: pure PHP only |
|
||
| OpenGL / WebGL: nothing in 3D, stderr / console `[opengl] ...` | a shader error (also `$gl->on('error')`): GLSL ES 1.00, `precision mediump float;` in the fragment shader; draw every frame in `render()`; `setLayer()` and the key colour cleared in the 2D |
|
||
| Raw gl* calls break the 2D (wrong textures, black screen) | gl* only between `opengl()->begin()` and `end()` (or inside `program()` / `buffer()`...): SDL's GL state is saved / restored there |
|
||
| A post shader is black in parts on some GPUs | mediump: big arguments to sin / cos lose all precision; `sin(3.14159 * fract(x))` |
|
||
| `HttpError ... network error or CORS` in the browser only | the server must send `Access-Control-Allow-Origin` (fetch from a web page) |
|
||
| PWA not installable / not offline | project.yaml `pwa`, https (or localhost), rebuild; the first visit fills the cache (`isOfflineReady()`) |
|
||
| `Class "App\..." not found` inside a thread | the thread only has the autoloader: use `JumPHP\Async` (it loads `vendor/autoload.php` there), not raw `Async\spawn_thread` without a bootloader |
|
||
| `LogicException ... must be a static closure` | write `static fn () => ...` (or a static method) for work sent to `thread()` / `submit()` |
|
||
| `ThreadTransferException`, `Cannot transfer a resource between threads` | a reference, a resource or an object with dynamic properties was sent to a thread (as an argument or a captured `use` variable): plain values only |
|
||
| A connected app is dropped by its server a few minutes after the tab is hidden | engine < 0.5.63: a hidden tab ran no PHP (no `requestAnimationFrame`). Update (hidden tabs run a frame a second), and make the server count the transport's 15 s ping as presence. docs/browser-troubleshooting.en.md §1-2 |
|
||
| Messages lost / "connected" but nothing arrives after a phone slept | the socket died without knowing it: resume token + numbered messages, reconnect when the tab comes back after a long absence. docs/browser-troubleshooting.en.md §3 |
|
||
| A PHP socket server dies with `stream_select(): supplied resource is not a valid stream resource` | a session closed outside the read loop was still in the `select` lists: remove closed sessions before building them. docs/browser-troubleshooting.en.md §4 |
|
||
| `date()` is an hour or two off in the browser | PHP in the browser runs in UTC: `date_default_timezone_set()` |
|
||
| `Notification::show()` returns false in the browser | ask first: `Notification::requestPermission()` from a click; Android Chrome shows none from a page (push through the JumPHP runtime) |
|
||
| The game freezes while threads work | a busy loop on `isDone()`, or raw `Async\ThreadPool::submit()` with a full queue: use `JumPHP\Async\Pool` (never blocks) |
|
||
|
||
## 12. Remaking a game from its original disc (Amstrad CPC)
|
||
|
||
When the user wants an existing **Amstrad CPC** game remade "with the same assets, music, sprites" from a
|
||
`.dsk` file: use **[dsk2jumphp](https://git.jumphp.net/jumphp/dsk2jumphp)**. It already has everything — a
|
||
headless CPC 6128 emulator that runs the game and logs it (screenshots, memory dumps, watched writes, AY sound
|
||
log, keys, pokes, ROM or boot-sector boot), DSK / dump / Z80 / sound tools, the method step by step, and a
|
||
whole game done this way. **Do not write an emulator, a disassembler or a DSK reader yourself.**
|
||
|
||
```bash
|
||
git clone https://git.jumphp.net/jumphp/dsk2jumphp.git <somewhere outside the project> && make -C <it> test
|
||
mkdir -p .claude/skills && ln -s <it>/.claude/skills/dsk2jumphp .claude/skills/dsk2jumphp # the skill
|
||
```
|
||
|
||
Then read its `AGENTS.md` and `docs/method.md`. In short:
|
||
- run the game in its emulator and look at the screenshots; find variables by diffing dumps and watching
|
||
writes; read code only around the PCs the logs give; steer the game with keys and pokes;
|
||
- extract with its tools: palette, tiles and sprites (PNG, pen 0 transparent, mode 0 pixels 2 wide), font,
|
||
maps rebuilt from write logs (JSON), music and effects from the AY log (Ogg);
|
||
- keep the extraction reproducible in the game: `games/<id>/tools/extract/` (scripts + README of the
|
||
addresses + a script that rebuilds `assets/` from the .dsk path); **never commit the .dsk, CPC ROMs or dumps**;
|
||
ROMs only when the game needs the firmware, from the user's machine (ask), never downloaded;
|
||
- write the game in readable PHP with the original's screen size, rules and timings (50 Hz frames), and check
|
||
it side by side with the emulator (`cpc -s` vs `bin/jumphp shot`).
|
||
|
||
Example: the Rainbow Islands remake, https://git.jumphp.net/jumphp/rainbow-island (its `tools/extract/`), and
|
||
`examples/rainbow-islands/` in dsk2jumphp.
|
||
|
||
## 13. A web site for the game (`site/`)
|
||
|
||
A game can have its own home page: `games/<id>/site/` (static files). `bin/jumphp deploy` puts it at the root
|
||
of the domain with the game in `/play/`; the JumPHP playground (§14) shows it as the game's page. Make one when
|
||
the user asks for a site / home page / landing page, and always for a game published on the playground.
|
||
Example: the Rainbow Islands remake (https://git.jumphp.net/jumphp/rainbow-island, `games/rainbow-island/site/`
|
||
and `tools/site/`).
|
||
|
||
- **Themed with the game's own graphics**: real screenshots (`bin/jumphp shot`, several levels / moments,
|
||
`JUMPHP_SCENE_PARAMS` test params), sprites and tiles cut from the game's assets, the game's colours. Make the
|
||
pictures with a script kept in the game (`tools/site/shots.sh` + a Python/PHP image script): it can be re-run
|
||
when the game changes. Pixel art scaled by whole factors, nearest neighbour; `image-rendering: pixelated`.
|
||
- **Files**: `site/index.html` (one page is enough; CSS inline), `site/images/` (PNG/JPG/WebP, no SVG),
|
||
`site/robots.txt`, `site/sitemap.xml`; a favicon (`images/favicon.png`); `og.png` 1200 × 630 for sharing.
|
||
No external scripts, fonts or trackers; it must work offline from its folder.
|
||
- **Link to the game**: `href="play/"` (relative: it works on your domain and on the playground), big and near
|
||
the top, again further down. The game's page title, controls (keyboard, gamepad, phone), what the game is.
|
||
- **SEO**: `<html lang>`, `<title>` (game + genre + "play online free"), `<meta name="description">`, canonical,
|
||
Open Graph + Twitter card, `<h1>`, one `<h2>` per section, `alt` on every image, JSON-LD
|
||
`VideoGame` (name, description, genre, gamePlatform, image, screenshot, `isAccessibleForFree`,
|
||
`potentialAction` PlayAction → `play/`), FAQ as `FAQPage` if there is one. Absolute URLs are written
|
||
`https://{{DOMAIN}}/...`: replaced by the real address when deployed (`https://<domain>/` on your server,
|
||
`https://<playground>/<game>/` on the playground).
|
||
- **Phones**: works at 390 px wide, no sideways scrolling, 16 px side margins.
|
||
- Language: the user's language (or the game's `lang`). Credit the original authors for a remake.
|
||
- **Other languages** (the playground speaks `fr en es de it pt nl pl ru uk tr ja zh ko` and shows a game's site in the
|
||
visitor's language when it has it): `site/index.html` is the page in the main language (its `<html lang>`), each
|
||
translation is `site/<code>/index.html` (same page, translated: title, description, Open Graph, `alt`, JSON-LD
|
||
texts). Inside `site/<code>/`, relative paths go one folder up: `../images/…`, the game `../play/` (with `?back=` if the
|
||
main page has one: `../play/?back=../<code>/`). Every page (the main one included) lists all the languages:
|
||
`<link rel="alternate" hreflang="<code>" href="https://{{DOMAIN}}/<code>/">`, the main one at `https://{{DOMAIN}}/`, plus
|
||
`hreflang="x-default"` = the main one; canonical and `og:url` = the page itself, `og:locale` its language; a small menu
|
||
of the languages (links `../<code>/`, `../` for the main one, each in its own language). `sitemap.xml`: one `<url>` per
|
||
language with the `xhtml:link` alternates.
|
||
- **A first version**: `bin/jumphp site:new <id>` writes one from the game itself (shots of its smoke scene, og.png,
|
||
favicon, SEO, robots.txt, sitemap.xml; never over an existing `site/`): a start to improve, not the end.
|
||
- **Check it**: `bin/jumphp build:site <id>` then `bin/jumphp siteshot <id>`: it fails on a broken image, a
|
||
JavaScript error, a missing title / description / `play/` link or sideways scrolling, and writes
|
||
`var/screenshots/site-desktop.png` and `site-phone.png`: **open them** and look.
|
||
|
||
## 14. Publishing on the JumPHP playground
|
||
|
||
The **JumPHP playground** (https://jumphp.net) is a web site of JumPHP games: a directory by category, each game at
|
||
`https://<playground>/<game>`, played in the browser with a shared engine (remote mode, docs/remote.md), its
|
||
sources browsable, an online editor. Its source: https://git.jumphp.net/jumphp/jumphp-playground. A project
|
||
there is a **public Git repository of the user** holding a JumPHP project with **one game** in
|
||
`games/<id>/`; the playground publishes it after each push to the default branch.
|
||
|
||
The user signs in with Git on the playground, makes an MCP token (`/studio/mcp`) and adds the server to
|
||
Claude Code (the page shows the command, `claude mcp add --transport http --scope user jumphp https://<playground>/mcp
|
||
--header "Authorization: Bearer jph_..."`). Its tools: `whoami`, `list_categories`, `list_projects`,
|
||
`create_project`, `get_project`, `update_project`, `sync_project`, `import_project`, `list_private_files`,
|
||
`upload_private_files`, `remove_private_files`, `list_games`, `list_game_files`, `read_game_file`, `run_tests`,
|
||
`get_test_run` (the game's PHPUnit tests, game tests filmed), notes and todos, feedback, and the accounts of an application's users
|
||
(`app_accounts_stats`, `list_app_accounts`, `get_app_account_data`, `delete_app_account`: the owner only, §9 "User accounts"). The server's
|
||
instructions say the same as this section.
|
||
|
||
To make a game for the user on the playground:
|
||
1. `create_project` (title, description, category, `kind`, brief = the user's request); `get_project` until its
|
||
status is no longer `creating`. `kind`: `original` (a new game), `cpc` (the remake of an Amstrad CPC game
|
||
from its `.dsk`: made with dsk2jumphp, §12; ask the user for the path of their disc), `port` (a port of a game
|
||
whose source code exists). It made the repository from this version of JumPHP with the skeleton game and
|
||
`BRIEF.md`.
|
||
2. `git clone` it (`clone_url`), make the game as this file says (§4-§10), in `games/<id>/` only, with a game
|
||
test for each mechanic as you write it (§10).
|
||
3. Its home page `games/<id>/site/` (§13) and `games/<id>/assets/thumbnail.png` (the directory's picture,
|
||
16:9; else the site's `og:image`, else `assets/icon.png`).
|
||
4. Check it like the playground runs it: `bin/jumphp build:remote <id>` then
|
||
`JUMPHP_WEB=remote bin/jumphp webshot <id> 6 '[[1,"Enter"]]'`.
|
||
5. Commit, `git push`, `sync_project`: it publishes at once and returns errors / warnings. Fix and push until
|
||
the status is `ready`. `run_tests` then `get_test_run`: the tests pass there too (the user replays the
|
||
filmed game tests in the studio). Then `update_project listed=true` and give the user the game's URL.
|
||
|
||
What the playground publishes and how:
|
||
- only `games/<id>/` (the `vendor/` of the game is not used: the engine and its packages come from the shared
|
||
engine; Composer packages of a game are not supported there). An application without the engine (a CLI app:
|
||
`kind: cli`, Symfony Console + symfony/tui) gets its own packages: the playground installs its composer.json's
|
||
`require` (Packagist only, no scripts nor plugins) for its tests and its page;
|
||
- the engine version is the repository's `VERSION` (it must be one the playground serves: keep JumPHP up to
|
||
date with `bin/jumphp update`);
|
||
- a commit with a PHP syntax error (`php -l`) is not published; no PHP runs on the server (it runs in the
|
||
player's browser);
|
||
- the site is served as the game's page (framed, on a separate origin); `{{DOMAIN}}` there = `<playground>/<game>`;
|
||
- limits: 4000 files, 120 MB in all, 20 MB per file; no symbolic links;
|
||
- files that may not be public (the data of an original game): keep them out of git and give them to the
|
||
playground as **private files**: the game loads them, no repository, source page or fork holds them.
|
||
`upload_private_files` gives a signed URL (2 hours) and the `curl` commands: `-F path=assets/data/X.BIN
|
||
-F file=@X.BIN` (one file), or `-F folder=assets/data -F archive=@data.zip` (a folder; its paths kept), 20 MB
|
||
per request; 64 MB and 2000 files per game. `list_private_files`, `remove_private_files`. No push or sync
|
||
needed. (The user can also do it in Studio → the project → "Fichiers privés".);
|
||
- a game without a picture of its own is photographed by the playground (its screen, in a browser);
|
||
- the game's page `/<game>/play`: a game WITHOUT a web site of its own goes fullscreen at the first click (`?fullscreen=1` in the frame's address; the engine page does it, a game with a site keeps its own page and play button), an APPLICATION (project.yaml `kind: gui | cli | app`, `view: window`, or `ui: webview`) starts at once, with no "click / tap to play" screen (the page gets `kind` / `view` from game.json);
|
||
- every published game / application has an **Install** menu: the PWA (the browser's prompt, or how to do it: Chrome / Edge, iPhone, Firefox), the native installs it offers (the IDE's executables and installer, the files of the repository's newest GitHub release: `.exe` `.msi` `.dmg` `.AppImage` `.deb` `.apk`...), Google Play when `android_package` is set, and the GitHub releases;
|
||
- never put the MCP token or any secret in the repository;
|
||
- the **administrator** (the Git account `User::ADMIN_GITHUB_ID`) has an Administration page on the playground (docs/admin.md): TCP / SSH approvals, the TCP bridge live (connections, bandwidth, who asks, log newest first, alerts, cut / block), every project (status, directory, stage, delete) and every account (ban, unban, delete).
|
||
|
||
### Outside the playground: a partner's site, a custom domain
|
||
|
||
- **On a partner's site, without iframe nor CORS** (docs/embed.md, docs/embed.en.md): project.yaml `embed: {blocks: [login], params: [nickname]}`;
|
||
a block is `site/blocks/<name>.html` (`{{BASE}}` = the application's address on the partner's site, `{{SITE}}` its domain). The owner
|
||
declares the partner site in the studio (domain, base path; it gives an identifier `es_…` and a secret `jes_…`); the partner's server
|
||
runs `tools/embed/jumphp-embed.php` (signed requests to `/api/embed/<slug>/…`, the app served under `/chat/`, blocks with
|
||
`->block('login')`; WordPress: `tools/embed/wordpress/`, shortcode `[jumphp_block app="…" block="login"]`). The declared params and
|
||
`site` (the partner's domain, trusted) reach the first scene's `enter()` / `loaded()` over `start_params` (`JUMPHP_START_PARAMS`,
|
||
`Engine::startParams()`); TCP tickets go through the partner's relay (`tcp_ticket_url`). Never put the secret in a repository.
|
||
- **A custom domain** (docs/domains.md): the owner adds it in the studio, makes `CNAME apps.jumphp.net` (DNS only) and
|
||
`TXT _jumphp.<domain>` = the token, checks it there; the administrator may have to approve it. The domain then serves `site/` at `/`
|
||
and the project at `/play/`, like `bin/jumphp deploy`.
|
||
|
||
### One executable (Linux, Windows)
|
||
|
||
When the user wants to give the game to players with nothing installed ("an executable", "a .exe", "a binary"):
|
||
`bin/jumphp export:standalone <id>` (Linux; `--windows` for Windows, `--linux --windows` for both) makes
|
||
`games/<id>/dist/standalone/<id>-linux-x86_64` / `<id>-windows-x86_64.exe`: StaticPHP's micro (PHP 8.5 with
|
||
SDL, OpenGL, OpenAL built in) + the game as a PHAR, unpacked into the player's cache on the first launch; saves go
|
||
to the player's data folder (docs/standalone.md). The micro is downloaded from JumPHP's releases or built once
|
||
in Docker (Linux, ~15 min: run it in the background); Windows' only comes from the releases (the GitHub workflow
|
||
`standalone`): if it is missing, say so, do not try to build it.
|
||
|
||
**The micro cache is keyed by CONTENT, never touch it by hand** (`~/.jumphp/standalone/micro-<target>-<key>.sfx`; the key = `bash tools/standalone-key.sh |
|
||
sha256sum | cut -c1-16`: PHP version, the extension list of the project kind, StaticPHP's commit, `docker/standalone` and the patches). Games and graphic apps (`kind: gui`)
|
||
use `tools/standalone-extensions.txt` (SDL, OpenGL, OpenAL), desktop apps (`ui: webview`) `tools/app-extensions.txt` (FFI, NO SDL): two different keys, two different files.
|
||
**Never copy, rename, symlink or "reuse" a micro under another key** to save a rebuild, even when you changed only comments or Dockerfile addresses: on 2026-11-06 the apps' micro
|
||
was copied under the games' key and every executable of jumphpsql crashed on the players' computers with `Call to undefined function SDL_Init()` (published installers
|
||
included). If the key changed, the micro must be rebuilt: Linux `JUMPHP_STANDALONE_BUILD=1 bin/jumphp export:standalone <id> --linux` (~15 min, background), Windows /
|
||
macOS by the workflow `standalone` (docs/standalone.md). `tools/standalone.sh` now checks that the micro holds every extension of its list (symbols `SDL_CreateWindow`, `IMG_Load`,
|
||
`Mix_OpenAudio`, `TTF_OpenFont`, `glGenBuffers`, `alcOpenDevice`), removes a wrong file from the cache and stops: if you see that message, do not work around it, rebuild.
|
||
**Before publishing any executable or installer, run it** (Linux: `SDL_VIDEODRIVER=dummy SDL_RENDER_DRIVER=software SDL_AUDIODRIVER=dummy timeout 10 ./<file>` must run until the
|
||
timeout, not die with a PHP error) and never upload a binary you did not start. Check the Linux one runs: `SDL_VIDEODRIVER=dummy
|
||
SDL_RENDER_DRIVER=software SDL_AUDIODRIVER=dummy timeout 5 <file>` exits by the timeout, not with an error. dist/ is not in git.
|
||
|
||
### Android app (Google Play)
|
||
|
||
When the user wants the game on the Play Store (or "on Android", "an app"): `bin/jumphp twa <id> --url <the
|
||
game's page online, https>` makes a Trusted Web Activity with Google's Bubblewrap, in Docker (docs/android.md).
|
||
It asks the app's package the first time (suggest `io.github.<github user>.<id with _>`; it never changes) and,
|
||
the first time on this computer, **the user must accept the Android SDK license themselves**: tell them to run
|
||
the command in their terminal (`! bin/jumphp twa <id> --url ...` in Claude Code); never accept it for them.
|
||
Then:
|
||
- out: `games/<id>/dist/android/<id>-<version>.aab` (Google Play), `.apk` (a phone), `assetlinks.json`, and the
|
||
SHA-256 fingerprint of the upload key (printed). `games/<id>/android/twa-manifest.json` goes into git; the key
|
||
and its password (`~/.jumphp/android/keys/`) never do: tell the user to back them up;
|
||
- the site must vouch for the app, or it opens with an address bar: on the playground, `update_project` with
|
||
`android_package` and `android_fingerprints`; on one's own server, `dist/android/assetlinks.json` served at
|
||
`https://<domain>/.well-known/assetlinks.json` (`bin/jumphp deploy` serves `site/.well-known/` if you copy it there);
|
||
- the name under the icon: project.yaml `pwa: {short_name: ...}` (12 characters show whole on most phones);
|
||
- the Play Console is the user's (their developer account): list the steps (create the app with the same
|
||
package, internal testing with the .aab, then **add Google Play's app signing fingerprint** with
|
||
`update_project` too, store listing with `bin/jumphp shot` screenshots);
|
||
- a new version of the app (name, icon): `bin/jumphp twa <id>` again (versionCode + 1). The game itself updates
|
||
with the site, no new app needed.
|
||
|
||
**Publishing on Google Play** (web app or native app `bin/jumphp android`): follow `docs/google-play.md`, step by
|
||
step. Its rules, every time:
|
||
- back up the upload key (`~/.jumphp/android/keys/<package>.keystore` + `.env`) before the first upload: lost, the
|
||
updates are refused; keys, passwords, `dist/`, `var/` never in git or in notes;
|
||
- the web app's assetlinks needs **both** SHA-256 fingerprints (the upload key's, printed by the build, and Google
|
||
Play's app signing key's, Play Console > Setup > App signing) or the Play version opens with an address bar;
|
||
- try the `.apk` on a real phone with `adb` and look at a screenshot (`adb exec-out screencap -p`) before any upload;
|
||
a web app that opens then closes = two Chrome on the phone (clone / dual space), see the guide;
|
||
- the privacy policy address must answer (open it): a page of the game's site (`site/privacy.html`) or the
|
||
repository's `PRIVACY.md`; Store settings needs a category and the contact e-mail the user gives;
|
||
- the target audience, the content rating answers, accepting terms and **sending to production** are the user's:
|
||
show them what you will answer / send and wait for their yes, for that step; never say the game is for children
|
||
unless they want it;
|
||
- never remove a phone's user / clone space or uninstall an app without asking (data is lost);
|
||
- each build is versionCode + 1: commit `android/twa-manifest.json` / `android/app.json` at once.
|
||
|
||
### Apple apps (macOS, iPhone / iPad)
|
||
|
||
When the user wants the game on a Mac, an iPhone or an iPad as an app ("an app for iOS", "on the App Store", "a Mac
|
||
app"): `bin/jumphp apple <id>` (or `ios <id>` / `macos <id>`; docs/apple.md). Xcode is needed, so GitHub builds them
|
||
on one of its Macs: the command writes `games/<id>/apple/app.json` (in git: bundle identifier asked the first time,
|
||
build + 1, version), puts `.github/workflows/apple.yml` in the project, pushes after the user's yes, runs it and
|
||
downloads `games/<id>/dist/apple/`: `<id>-<v>-macos.dmg` / `.zip` (Apple silicon + Intel), `<id>-<v>-ios.ipa`,
|
||
`<id>-<v>-ios-simulator.zip`, and `check/macos.png` (the Mac app ran the game headless) / `check/ios.png` (the app in an
|
||
iPhone simulator): **open the two screenshots** and check the game is there. First build ~40 min (run it in the
|
||
background), then ~10.
|
||
- without an Apple developer account (99 $ a year) the apps are signed ad hoc: a Mac opens it after right click > Open;
|
||
an iPhone installs nothing unsigned (the simulator's app and the web version in the meantime). Signing, notarization
|
||
and TestFlight come with the account (docs/apple.md): never ask for or store Apple credentials yourself;
|
||
- in the app: `JUMPHP_IOS` (Platform::isPhoneApp(), touch controls, the game's orientation) or `JUMPHP_MACOS`; SDL on
|
||
OpenGL ES 2 (iOS) / OpenGL (macOS: the engine turns GLSL ES 1.00 into GLSL 1.20 itself).
|
||
|
||
## 15. Reference
|
||
|
||
- `games/hello-world/` — the smallest game: a menu (play, sound on / off, quit), a text moved by the arrows, a
|
||
Synth sound. The start of the playground's tutorials.
|
||
- `games/pong/` — complete game: menus, options, AI, local 2 players, online, pause, game over.
|
||
- `games/hello-threads/` — threads (`runtime: async`): a thread pool computes a fractal, the frame never waits.
|
||
- `games/hello-webgl/` — WebGL / OpenGL: 3D cubes under a 2D HUD, post-processing shaders, raw gl* + OpenAL (`RawGlScene`),
|
||
gamepad sticks / rumble, automatic pause (lifecycle), PWA (installable, offline).
|
||
- `games/jumpball/` — a 3D runner on OpenGL / WebGL: procedural track (seeded), ball physics at a fixed step, a bot
|
||
(title screen demo + smoke test), chunked vertex buffers, filled software 3D without GL, best score saved.
|
||
- `skeleton/` — platformer: tiles, slopes, one-way platforms, camera, coins, sprite from pixel strings.
|
||
- `apps/hello-tcp/` and `apps/hello-ssh/` — the tutorials of docs/tuto-tcp.md and docs/tuto-ssh.md: a TCP connection (PING to a Redis), the same through an SSH server (key chooser, key ring), with tests that play the window.
|
||
- `games/hello-hybrid/` — a hybrid game (§16): SDL balls + an HTML control panel, native file chooser / dialog, tray
|
||
menu, global shortcut.
|
||
- `games/ide/` + `ide/` — the JumPHP IDE (docs/ide.md): a big desktop app, its core tested with PHPUnit
|
||
(`bin/jumphp php ide vendor/bin/phpunit`), its interface checked with `games/ide/tools/shot.sh`.
|
||
- `games/hello-gui/` — a graphic app (§17): a form made in the visual editor (responsive grid of two panels), its code
|
||
behind, saved contacts, game tests.
|
||
- `games/hello-plugin/` — a plugin of the JumPHP IDE (§19): a tool window, an action, problems, completion, its tests.
|
||
- `extensions/particles/` + `games/particles-demo/` — the particle engine, an engine extension (§20), and its showcase.
|
||
- `games/hello-cli/` — a CLI app (§18): a task list, commands and a full-screen screen, tested on a virtual terminal.
|
||
- `games/hello-desktop/` — a desktop app (Tauri, §16): a notepad, HTML page + PHP (files, native dialogs, PHP clock,
|
||
drag and drop, quit confirmation), tested with `AppTestCase`.
|
||
- `engine/stubs/sdl.stub.php` — every raw SDL / SDL_image / SDL_mixer / SDL_ttf function and constant.
|
||
- `engine/tests/` — usage examples of CollisionSystem, TiledJsonLoader, SceneManager, Menu, Net.
|
||
- `docs/browser-troubleshooting.md` (French) / `.en.md` — connected applications in the browser: hidden tabs, server timeouts, resume after a cut, notifications, the PHP server's loop, time zone; a checklist.
|
||
- `docs/` (French) — architecture, build, browser pitfalls, tiles, network, porting an existing game, remaking a CPC game (`docs/cpc.md`).
|
||
- [dsk2jumphp](https://git.jumphp.net/jumphp/dsk2jumphp) — remake an Amstrad CPC game from its disc (§12).
|
||
|
||
## 16. Desktop apps (Tauri): HTML pages, PHP behind them
|
||
|
||
Besides games, JumPHP makes **desktop applications**: native windows whose content is HTML / CSS / JS (the system's
|
||
WebView), whose logic is PHP. Linux, Windows, macOS, and the same app in the browser / on phones (`bin/jumphp build
|
||
<app>`: PHP in WebAssembly, the native side done in HTML). Full guide: `docs/tauri.md`
|
||
(French: `docs/tauri.fr.md`). Example: `games/hello-desktop`. Nothing of this touches games.
|
||
|
||
When the user wants "an app", "a desktop application", "a tool with a window", "an HTML interface" (not a game):
|
||
|
||
```bash
|
||
bin/jumphp app:new notes "Notes" # apps/notes from skeleton-app/ (config/project.yaml: ui: webview, main: App\Main)
|
||
bin/jumphp install notes
|
||
bin/jumphp app:test notes # php -l + phpstan + phpunit (AppTestCase) + the app for real on Xvfb: must pass
|
||
bin/jumphp app:shot notes # var/screenshots/app.png: OPEN IT and look
|
||
bin/jumphp app:export notes # dist/standalone/notes-linux-x86_64 (the user's computer needs WebKitGTK 4.1)
|
||
bin/jumphp app:export notes --windows --macos # + notes-windows-x86_64.exe, notes-macos.zip (an .app, both Macs)
|
||
bin/jumphp build notes # dist/web/: the same app in a web page (webshot to check it)
|
||
```
|
||
|
||
- **PHP is the program**: `app.php` = `exit(JumPHP\Tauri\App::boot(__DIR__)->run());`. PHP starts the Tauri runtime
|
||
from its main thread (FFI, `libjumphp_tauri.so`), which calls PHP back at every frame (like the browser engine):
|
||
never block (rule 2 holds), answers come later as `Task`s.
|
||
- **`src/Main.php`** implements `JumPHP\Tauri\AppMain::boot(App $app)`: `$app->command('name', fn (mixed $payload) =>
|
||
value | Task)` (what pages call), `$app->send('event', $payload)` / `$app->window()->send(...)` (PHP -> pages),
|
||
`$app->on('page:event', fn ($payload, $window) => ...)`, `$app->window()->on('close-requested', fn (NativeEvent $e)
|
||
=> $e->preventDefault())`, timers with `$app->gameLoop->addPeriodicTimer()`, `$app->storage` / `options` / `http()` /
|
||
`tasks()` as in games.
|
||
- **Pages** in `ui/` (project.yaml `app.pages`): plain HTML / CSS / JS. `window.jumphp` is injected:
|
||
`await jumphp.invoke('name', payload)`, `jumphp.send('event', payload)`, `jumphp.on('event', fn)`, and the built-in
|
||
`jumphp.invoke('native.open' | 'native.save' | 'native.message' | 'native.confirm' | 'native.notify' | 'native.openUrl', {...})`.
|
||
- **Native features from PHP** (any target, `JumPHP\Native`): `Dialog::message()`, `Dialog::confirm()`,
|
||
`FilePicker::open() / folder() / save()` (Tasks; in the browser only `open()`: the chosen file is written into the engine's memory, `/tmp/jumphp-picked/<name>`, call it from a click), `Notification::show()`, `Shell::openUrl() / openPath() / reveal()`;
|
||
`Native::supports($feature)` first (SDL games: message only; browser: openUrl, copy, open, notify; headless: none).
|
||
Browser notifications (0.5.63): `Notification::requestPermission()` from a click, `Notification::permission()` (`default` / `granted` / `denied` /
|
||
`unsupported`), then `show()` works even while the tab is hidden; a frame of another origin (the playground) goes through its parent page;
|
||
Android Chrome shows none from a page: use push through the JumPHP runtime (`jumphp/notification`).
|
||
- **Tests**: `tests/*Test.php` extending `JumPHP\Testing\AppTestCase` play the app without a window: `invoke()`,
|
||
`pageSend()`, `requestClose()`, `answerDialog()`, `frames()`, `wait()`, `sent('window.set_title')`, `lastSent()`.
|
||
Write one per feature as you go, like game tests.
|
||
- Also for apps (and hybrid games): `Clipboard::copy()` / `paste()`, `$app->tray($id, ['menu' => [...]])->on('menu', ...)`,
|
||
`$app->globalShortcut('CmdOrCtrl+Shift+K', fn () => ...)`. `JUMPHP_TAURI_TRACE=1` prints every native command / event.
|
||
- **Starting with the computer** (an exported app): `$app->autostart()->set(true)` / `isEnabled()` / `startedAtLogin()`;
|
||
project.yaml `app: {autostart: {default: true, hidden: true}}` (on at the first start; window hidden at login: a tray app).
|
||
- **Menus**: `$app->window()->setMenu([['text' => 'File', 'items' => [['id' => 'open', 'text' => 'Open...',
|
||
'accelerator' => 'CmdOrCtrl+O'], '-', ['role' => 'quit']]], ...])` (check items: `'checked' => true`; roles: quit
|
||
copy cut paste undo redo select_all...), `$app->window()->on('menu', fn (string $item, ?bool $checked) => ...)`,
|
||
`setMenuItem()`; `$app->setMenu()` for the whole app. Test: `$this->menu('open')` in an AppTestCase.
|
||
- **Updates** of an exported app: `bin/jumphp app:release <app> --url <base> [--linux] [--windows] [--macos]` (signed
|
||
update.json; the key stays in `~/.jumphp/keys`, `config/update.pub` is committed), project.yaml
|
||
`app: {update: {url: <base>/update.json}}`, `$app->updater()->check()->then(fn (?Update $u) => $u?->install()
|
||
->then(fn () => $app->updater()->relaunch()))`. Bump project.yaml `version` for each release.
|
||
- **Hybrid games** (`ui: hybrid` in a game's project.yaml, `main: App\Desktop` optional, `app.window` optional): an SDL
|
||
game that also gets all this and HTML windows beside its own (`games/hello-hybrid`). Headless / browser / phones:
|
||
a plain game, so scenes must check `Native::supports()` and use `App::current()?->send(...)`. `app: {embed: true}`:
|
||
the game drawn **inside** the Tauri window (one window, `JumPHP\Tauri\EmbeddedGame`; not for OpenGL games).
|
||
- **Services** (a program in the background, started at boot / login, restarted on failure): project.yaml `service:
|
||
{name, args: [serve], restart: on-failure, user: true}`, `JumPHP\Service\Daemon::loop()` in the program,
|
||
`bin/jumphp service:install / status / logs / uninstall <id>` on the exported executable (systemd, launchd, WinSW;
|
||
docs/services.md).
|
||
- Platforms: Linux (Docker commands), Windows and macOS (the workflow `tauri` builds and tries the library there,
|
||
`app-export` opens the exported .app on two Macs). `tauri:download` fetches the library of these sources. In the
|
||
browser: windows become frames, menus a bar, dialogs HTML, save = download, no tray / global shortcuts. Phones:
|
||
`bin/jumphp android <app>` / `bin/jumphp ios <app>` = that browser build in the phone's WebView (iOS not tried yet).
|
||
- Don'ts: no SDL / `Engine` in an app (it has no SDL window); no blocking calls; never write outside `var/` (the
|
||
user's data folder once exported) except files the user chose in a dialog.
|
||
|
||
|
||
## 17. Graphic apps (JumPHP\Gui): forms, no HTML
|
||
|
||
When the user wants "an app" made of windows with buttons, lists, fields... drawn by PHP itself (no HTML, the same on
|
||
desktop, web and phones), or a "mobile app" of that kind: `bin/jumphp gui:new <id> "Title"` (`--mobile` for phones).
|
||
Full guide: `docs/gui.md`. Example: `games/hello-gui`.
|
||
|
||
- A window = `forms/<Name>.form.yaml` (its widgets: what the IDE's visual editor writes) + `src/Form/<Name>.php`
|
||
(`final class <Name> extends JumPHP\Gui\Form`, a scene: `loaded($params)`, event methods named in the form file
|
||
`events: {click: onSaveClick}`, `tick($dt)`). Widgets by id: `$this->save`; keep one `@property Button $save` line
|
||
per widget id in the class docblock (the visual editor does it; do it when you edit the YAML by hand).
|
||
- project.yaml: `kind: gui`, `view: window` (the view follows the window, pixel for pixel; sizes in forms are dp),
|
||
`touch: false`, `start_scene: App\Form\MainForm`.
|
||
- Layout like a web page without HTML: `column` / `row` / `grid` (12 columns, `span: {xs: 12, md: 6}` per screen
|
||
width: xs < 600 dp, sm < 900, md < 1200, lg) / `stack` / `panel`; `gap`, `padding`, `items`, `justify`; children
|
||
`width` / `height` (dp, `auto`, `fill`), `grow`, `align`, `hide: [xs]`; a `spacer` takes the free room.
|
||
- Widgets: label, button, textbox, checkbox, radio, combobox, listbox, slider, progressbar, image, video (`src: assets/videos/intro.mp4`:
|
||
bin/jumphp cuts the film into pictures by itself), spacer, separator. Mouse wheel, dead keys, input methods: handled. Their events: docs/gui.md.
|
||
- Tests (GameTestCase): `$form = $this->game->scene(); $form->click($form->widget('add')); $form->type("Ada\n");`.
|
||
Check with `bin/jumphp shot <id>` (and a phone width: `--mobile` apps are 390 dp wide).
|
||
- **Languages**: every text of a widget (label, button, checkbox, tooltip, placeholder, group title) is translated by the engine with `Lang` when the text is a key of `config/lang.yaml` (`fr: {'Save': 'Enregistrer'}`; the language is the page's `?lang=`, the browser's, or project.yaml `lang`). Texts with a variable: `Lang::t('{name} saved', ['name' => $x])`. The engine's own texts (runtime banner, badge, guide) are in `engine/src/Util/engine-lang.yaml` in the 14 languages of JumPHP (`fr en es de it pt nl pl ru uk tr ja zh ko`); the game's file wins. A new application must give its `lang.yaml` in those 14 languages.
|
||
- Don'ts: no game-style `actions()` for the forms (they read the mouse, touch and keys themselves); no HTML;
|
||
colours as '#rrggbb'; never block (rule 2).
|
||
|
||
|
||
## 18. CLI apps: applications in the terminal
|
||
|
||
When the user wants a command-line tool, "a CLI", "a TUI", a program "in the terminal": `bin/jumphp cli:new <id>
|
||
"Title"` (`skeleton-cli/`, `config/project.yaml kind: cli`). Full guide: `docs/cli.md`. Example: `games/hello-cli`.
|
||
|
||
- Commands: Symfony Console, one class per command in `src/Command/` (`#[AsCommand]`), registered in `src/Main.php`.
|
||
- Full-screen screens: symfony/tui in `src/Ui/` (`Tui`, widgets, `onInput` / `onSelect` / `onSubmit`, `run()` /
|
||
`stop()`); with no terminal (a pipe), fall back to plain output.
|
||
- `bin/jumphp run <id> [command...]` (in this terminal), `test` (php -l, phpstan, phpunit, `php app.php list`),
|
||
`shot <id> [seconds]` (the real program in a pseudo-terminal, `JUMPHP_KEYS='[[1,"a"],[1.5,"\r"]]'`: **read** the
|
||
screen text it prints / writes in `var/screenshots/screen.txt`), `export:standalone <id> --linux --windows --macos`
|
||
(one executable each, a console program on Windows).
|
||
- Tests as you go: `ApplicationTester` for commands, a `VirtualTerminal` for screens (`simulateInput()`, `tick()`,
|
||
`ScreenBuffer::getScreen()`).
|
||
- Don'ts: no SDL / engine scenes, no `sleep()` inside a screen (`scheduleInterval()`), data only in `Main::boot()`'s
|
||
folder. In the browser (the playground's Play, `docs/cli.md`) its commands are typed in a web terminal, one
|
||
`app.php` run each, interactive like a real terminal: questions wait for the typed line, full-screen screens get raw
|
||
keys through `src/Ui/WebTerminal.php` + `WebLoop.php` (a Revolt loop without fibers: the browser's PHP has none) when
|
||
`JUMPHP_WEB_TERMINAL=1`; `stream_isatty()` is false there, so check `WebTerminal::available()` too, and keep the
|
||
plain output for pipes. A widget removed from the `Tui` (`remove()`) loses its listeners:
|
||
build a new one to show it again. A screen needs a terminal both ways (`stream_isatty(STDIN)` and `STDOUT`): on a
|
||
pipe, print something plain instead.
|
||
|
||
|
||
## 19. Plugins of the JumPHP IDE (PHP)
|
||
|
||
When the user wants to extend the JumPHP IDE (a tool window, an action, completion, checks of their files, a run
|
||
configuration): `bin/jumphp plugin:new <id> "Title"` (`skeleton-plugin/`, `config/project.yaml kind: plugin`). Full
|
||
guide: `docs/ide-plugins.md`. Example: `games/hello-plugin`.
|
||
|
||
- `composer.json` `extra.jumphp-ide` (id, name, version, class) + `autoload` psr-4 in a namespace of its own
|
||
(`JumphpPlugins\<Id>\`); no package of its own at run time.
|
||
- The class implements `JumPHP\Ide\Plugin\Plugin::activate(Api $ide)`: `action()`, `toolWindow()` (`Ui::` nodes,
|
||
callbacks in PHP), `runConfiguration()`, `completion()`, `diagnostics()`, `mcpTool()` (a tool for Claude on the
|
||
IDE's MCP server: `mcp__jumphp-ide__plugin_<id>_<name>`), `on('file.saved')`, `every()`, `notify()`, `openFile()`,
|
||
`workspace()`, `setting()`.
|
||
- Share it: Tools > Plugins… > "Publish on jumphp.net" (https://jumphp.net/ide-plugins), or `bin/jumphp plugin:pack`.
|
||
- Tests as you go: `tests/*Test.php` extend `JumPHP\Ide\Testing\PluginTestCase` (`project()`, `action()`,
|
||
`toolText()`, `click()`, `submit()`, `complete()`, `problems()`, `save()`, `mcp()`). `bin/jumphp test <id>` must pass.
|
||
- Don'ts: never block (the IDE's frame), no network waits, nothing written outside the project / its settings.
|
||
|
||
|
||
## 20. Engine extensions (Composer packages that add to the engine)
|
||
|
||
A subsystem a game can require (particles, physics, a tile editor's format...): a Composer package of **type
|
||
`jumphp-extension`**. The engine finds it in the game's `vendor/composer/installed.json` at boot: nothing to wire.
|
||
Full guide: `docs/extensions.md`. Example: `extensions/particles` (+ `games/particles-demo`).
|
||
Also `extensions/physics` + `extensions/shorts` (+ `games/shorts-demo`): vertical videos for TikTok / Shorts, each bounce a
|
||
note, `bin/jumphp video:make <game> [--seed N] [--count N] [--seconds S]` -> MP4 1080x1920 (`docs/video-maker.md`).
|
||
|
||
- `composer.json` `extra.jumphp`: `services` (classes autowired, public: scenes ask for them in their constructor),
|
||
`services_file` (a Symfony services file of the package), `boot` (a class implementing `JumPHP\Extension\Extension`:
|
||
`boot(Engine $engine)` before the first scene), `loaders` (`{".particles.json": "Class"}` implementing
|
||
`JumPHP\Extension\AssetLoader`: `$this->engine->extensions()->load('assets/fx/x.particles.json')`), `config` (project.yaml
|
||
keys with their `default`, merged under the game's own values).
|
||
- `bin/jumphp extension:new <id> "Title"`: `extensions/<id>` (namespace `JumphpExtensions\<Id>\`) + `games/<id>-demo`
|
||
requiring it through a path repository; its game tests are the extension's tests (`bin/jumphp test <id>-demo`).
|
||
- Pure PHP (the browser build packs vendor/ and compiles the container with it): rules of §2 apply. Not on jumphp.net
|
||
yet (its shared engine ignores a game's own packages).
|
||
- **When the user asks for an extension** (IDE: New Project > Engine extension, or `bin/jumphp extension:new <id> "Title"`; it is made on the
|
||
computer, nothing online), do not stop at the code. A finished extension has, in `extensions/<id>/`:
|
||
1. the code in `src/` + its tests (unit tests and game tests, in `games/<id>-demo/tests/`);
|
||
2. **`doc/index.md`**: what it brings, short usage code, the project.yaml keys, the list of samples (the IDE shows it, `extension:add` copies it);
|
||
3. **`doc/samples/*.php`: one sample for each thing it does**, each a scene (`final class <Thing>Sample extends AbstractScene`, namespace
|
||
`App\Extensions\<Pascal of the id>`, `public const LABEL = 'one line on what it shows'`, a comment saying what to press and how to run it, the engine's
|
||
actions or the mouse only, a text on the screen), concrete, about 60 lines, runnable alone: `extension:add` copies them into the user's game
|
||
(`src/Extensions/<Name>/`), the IDE has a ▶ Play for each, and in the extension's own project a ▶ on the sample's `class` line runs it through
|
||
`games/<id>-demo` (it autoloads `doc/samples/` itself);
|
||
4. `games/<id>-demo/tests/SamplesTest.php` (already in the skeleton) starts every sample 90 frames: `bin/jumphp test <id>-demo` must pass;
|
||
5. `README.md`, and `composer.json` `extra.jumphp` filled (`summary`, `features`, `engine`, screenshots made with `bin/jumphp shot`);
|
||
6. `doc/tutorial.md`: the step-by-step tutorial (one `## Step` per action, code to type, what appears); `bin/jumphp extension:doc <id>`
|
||
lists what its jumphp.net page still lacks (summary / features / screenshots, doc, tutorial, samples, example game) and writes a
|
||
starter tutorial. The page has the buttons Example game (opens in the browser once `games/<id>-demo` is published as the playground
|
||
project `<id>-demo`), Tutorial (`doc/tutorial.md`, else built from the samples) and Documentation (`doc/index.md`);
|
||
7. `bin/jumphp lint` and a look at a `bin/jumphp shot <id>-demo`.
|
||
Publishing is the user's click: the IDE's Publish (Publish extension) puts the package in its own Git repository `<login>/jumphp-<id>`, tagged, and
|
||
submits it on Packagist (docs/extensions.md "Make and publish your own"): never make repositories or tags yourself, never write a token in a file.
|
||
- Externals (`jumphp/externals`, `extensions/externals` + `games/externals-demo`): big game data the playground's administrator shares
|
||
from the server's `externals/` folder (Administration → Externals): `list()`, `search()`, `stat()`, `open()` -> `RemoteFile`
|
||
read like a disk by 64 KB blocks (HTTP Range), cached in memory and in var/ (IndexedDB); `local` folders stand in for the server on
|
||
desktop and in tests. project.yaml `externals: {url, local, block, memory_mb, persist, parallel}` (docs/externals.md).
|
||
- Runtime (in the engine core since 0.5.27, samples in `extensions/runtime`): the client of the JumPHP runtime (the user's own network from the browser), `RuntimeBadge` and `RuntimeGuide`; project.yaml `net_mode`, `jumphp_runtime` (§9, docs/runtime.md). Namespace `JumPHP\Runtime\`.
|
||
- WebRTC (`jumphp/webrtc`, `extensions/webrtc` + `games/webrtc-demo`): peer-to-peer data channels from PHP (browser: the page's RTCPeerConnection through
|
||
`engine/web/jumphp-webrtc.js`; desktop Linux: a GStreamer webrtcbin sidecar, native or Docker), `Signaling::overNet()` over the relay, and the
|
||
desktop's screen as H.264 + remote input (the IDE's Screen on a phone, `docs/ide-screen.md`). Its TODO: `extensions/webrtc/doc/index.md`.
|
||
- Notifications (`jumphp/notification`, `extensions/notification` + `games/notification-demo`, contract docs/notifications.md): push notifications on the phone through the JumPHP runtime for Android, with the person's consent. Service `Notifications` (`supported()`, `reason()`, `subscribe($user, $groups)` / `status()` / `unsubscribe()` Tasks, events), Gui widget `{class: JumphpExtensions\Notification\NotifyToggle, id: notify, user: ...}`, `Sender` (the owner's token `jnt_…`: scripts / servers only, never in a game), `bin/jumphp notify*` and `notify:mcp`; tests with `PhoneSimulator` / `FakeTransport`. The engine side is `JumPHP\Runtime\RuntimeMessages` (`supports('notify')`, `request()`).
|
||
- Particles (`jumphp/particles`): `ParticleSystem` (one per scene: `add(new Emitter([...]))`, `burst()`, `update($dt)`,
|
||
`render($r, $camX, $camY)`, `reset($seed)`), `Emitter` settings `rate life speed angle spread gravity drag colors size
|
||
shape area duration`, project.yaml `particles: {max, seed}`, `.particles.json` files of named emitters.
|
||
|
||
|
||
## 21. Everything at hand (read before writing something that may already exist)
|
||
|
||
**docs/ai-capabilities.md** is the inventory, generated from the sources (`bin/jumphp php . tools/ai-capabilities.php >
|
||
docs/ai-capabilities.md`, run it again after adding tools, extensions or engine classes): every MCP tool (the IDE's
|
||
`jumphp-ide`, `jumphp-debug`, `jumphp-notify`, the playground's `jumphp`), every engine extension with its services and
|
||
example game, every class of `engine/src` with what it is for, every `bin/jumphp` command. Look there first.
|
||
|
||
Tools worth knowing when you work on performance and memory (the IDE's Cryo window, its tools for you):
|
||
- **profile_run / profile_summary / profile_compare**: where CPU time and memory go (Xdebug's profiler).
|
||
- **ab_start / ab_changes / ab_run / ab_stop**: is a change faster or lighter? A copy of the code before (A), your change
|
||
(B), the same headless run profiled for both, compared for the whole run and for each changed function
|
||
(`JUMPHP_AB_OVERLAY`, engine/src/Debug/AbOverlay.php). Prove an optimisation with it instead of guessing.
|
||
- **cryo_inspect / cryo_diff / cryo_why / cryo_live**: memory leaks: snapshots (`.cryo`), what grew between two, why an
|
||
object is still alive (its path from a root), the live memory of a run (`JUMPHP_CRYO_METRICS`).
|
||
- **cryo_freeze**: a save point of the whole running program (`JumPHP\Cryo\ProcessFreeze`: every object, the level, the
|
||
player; resumed with `JUMPHP_CRYO_THAW`), the scene alone when the code changed since. Test a late part of a game
|
||
without playing up to it.
|
||
- **cryo_patch / cryo_patch_constant / cryo_patch_revert**: hot patch the running game (a method as it is in its file now, a constant)
|
||
with no restart and nothing lost; journal + revert (`JumPHP\Cryo\HotPatch`, docs/cryo.md).
|
||
- **cryo_console**: PHP run inside the running game between two frames (`$engine`, `$scene`): read or change the live state.
|
||
- **cryo_sandbox**: try PHP in an isolated sandbox of the desktop runtime.
|
||
- **debug_***: breakpoints, steps, variables, expressions in the running program (Xdebug or PHP Debugger).
|