IT

The game as one executable (Linux, Windows)

bin/jumphp export:standalone <game> makes one file that runs the game on a computer with nothing installed: no PHP, no Docker, no SDL. The player downloads it and runs it. About 23 MB (Pong, 3D Jumpball): PHP and its libraries ~20 MB, the rest the game.

bin/jumphp export:standalone pong              # games/pong/dist/standalone/pong-linux-x86_64
bin/jumphp export:standalone pong --windows    # games/pong/dist/standalone/pong-windows-x86_64.exe
bin/jumphp export:standalone pong --linux --windows

What is inside

Part What Where it comes from
PHP StaticPHP's micro: PHP 8.5 as one executable that runs the PHAR appended to it built once per set of extensions (below)
the extensions php-sdl, sdl_image, sdl_mixer, sdl_ttf, PHP-OpenGL (with JumPHP's patch), PHP-OpenAL, gd, zip, openssl, mbstring, bcmath, sockets… JumPHP's StaticPHP registry: docker/standalone/registry
the libraries SDL2, SDL2_image (PNG/JPG/GIF/BMP), SDL2_mixer (WAV, OGG, MP3, FLAC), SDL2_ttf (FreeType inside), OpenAL Soft: static same
the game games/<game> with its vendor/ (the engine), as a PHAR; not var/, dist/, tests/, site/ tools/standalone.sh

On Linux the executable needs glibc 2.17 or newer (any Linux since 2013: built with Zig's toolchain) and loads the display (X11, or XWayland), OpenGL and the sound (PulseAudio/PipeWire, ALSA) from the player's system when the game starts, as every Linux game does. On Windows nothing is needed (Windows 10 or newer).

HTTPS ($engine->http(), online play over wss://): PHP's openssl is inside; its CA certificates are the Linux system's (Debian / Ubuntu / Arch, Fedora / openSUSE), else the game's own cacert.pem (Windows, the others), through SSL_CERT_FILE (tools/standalone-stub.php).

The game's own php.ini settings

project.yaml php_ini: "my.setting=1\nother=2" (one line, \n between settings) adds them to the executable's php.ini section: get_cfg_var('my.setting') reads them. A tool can rewrite that section of a copy of the executable later (jumphp2installer writes a server's address there); to keep every offset in place (Windows), rewrite it at the same size, from room reserved by such a setting.

When the player runs it

The first launch unpacks the game (its PHP, pictures, sounds, fonts: SDL reads real files) into the player's cache, in a folder of its own version; later launches start at once. A new version of the game unpacks beside the old one.

Linux Windows
the game, unpacked ~/.cache/jumphp/<id>-<build> ($XDG_CACHE_HOME) %LOCALAPPDATA%\JumPHP\<id>-<build>
saves and options ~/.local/share/<id> ($XDG_DATA_HOME) %APPDATA%\<id>

<id> is project.yaml's id, <build> a hash of the game's files. JUMPHP_STANDALONE_DIR unpacks elsewhere, JUMPHP_VAR puts the saves elsewhere (tools/standalone-stub.php).

The micro binaries

The micro (PHP + the extensions) is the long part: ~15 minutes to build, the same for every game. It is kept in ~/.jumphp/standalone/micro-<target>-<key>.sfx, <key> being a hash of what makes it (tools/standalone-key.sh: PHP's version, tools/standalone-extensions.txt, docker/standalone with StaticPHP's commit, the registry and its patches). export:standalone looks for it, in order:

  1. in ~/.jumphp/standalone;
  2. on JumPHP's GitHub releases: standalone-<key>/micro-<target>.sfx (JUMPHP_STANDALONE_RELEASES: another address);
  3. Linux: built here, in Docker (docker/standalone: StaticPHP pinned, SPC_TARGET=native-native-gnu.2.17). JUMPHP_STANDALONE_BUILD=1 builds even when a release has it. Its build files stay in ~/.jumphp/standalone/spc (the next build only does what changed).

Windows' micro is built on Windows only (Visual Studio 2022): by the GitHub workflow .github/workflows/standalone.yml (Actions > standalone > Run workflow). It builds both micros and publishes them as the release standalone-<key>; run it after each change of docker/standalone, tools/standalone-extensions.txt or docker/ext/php-opengl.patch. A fork of JumPHP runs it in its own repository and sets JUMPHP_STANDALONE_RELEASES=https://github.com/<you>/<repo>/releases/download.

On Windows the extensions are built with JumPHP's config.w32 (registry/w32); Windows' OpenGL library has only OpenGL 1.1, so PHP-OpenGL's newer functions are asked to the driver on their first call (registry/functions.php, jumphp_wgl).

TrueAsync micro (threads: the JumPHP IDE for Linux and Windows)

A desktop app whose project.yaml says export_runtime: async (or runtime: async) gets, on Linux and Windows, another micro: PHP 8.6 ZTS from TrueAsync's fork (tag php-8.6.0-trueasync-0.11.3) + ext/async v0.11.3 + libuv (static), with the apps' extensions (tools/app-async-extensions.txt, FFI included). Its recipe is docker/standalone-async (the fork's archive and ZTS in craft.yml, ext/async in its registry, loaded after docker/standalone/registry); it is part of the key only for that list, so the other micros keep theirs. bin/jumphp app:export <app> --linux builds it like the others (~2 min once the libraries are built, work folder ~/.jumphp/standalone/spc-app-async) and checks it has uv_loop_init. Its php.ini adds register_argc_argv=0 (PHP 8.6 warns in each new thread without it; $argv stays).

Two fixes in its registry (src/Extension/async.php): StaticPHP builds the packages of an extra registry only while it loads that registry's PHP classes (so the class exists even for one package), and PHP 8.6's poll API is told there is no epoll_pwait2() (Zig's headers declare it, glibc 2.17 has none: the link failed).

Windows (MSVC, same recipe): built by the workflow standalone with extensions=tools/app-async-extensions.txt (or by hand on a Windows machine with Visual Studio 2022: the same craft.yml, both registries), published in the same release standalone-<key> as micro-windows-x86_64.sfx. The registry's src/Extension/async.php makes ext/async's config.w32 find StaticPHP's libuv (uv.h straight in buildroot/include, its sources include libuv/uv.h on Windows) and links the system libraries libuv needs (synchronization.lib for libuv >= 1.53, Iphlpapi, Psapi, Userenv, Dbghelp...). StaticPHP splits SPC_REGISTRIES on :: on Windows the paths are relative to its folder (..\jumphp\docker\standalone\registry\spc.registry.yml:..\jumphp\docker\standalone-async\...), a drive letter would cut them. The workflow runs the micro with a script that starts an Async\ThreadPool before publishing. tools/standalone.sh recognises the async micro by the string Libuv Reactor (a Windows PE has no symbol names: no uv_loop_init).

One TrueAsync difference on Windows: once its scheduler has run (a thread pool's first job), stream_socket_accept($server, 0) always answers false, even with a client waiting. The IDE's servers polled every frame (LocalLink, the page's loopback, MCP, the debugger, Remote) go through JumPHP\Ide\Net\Accept::now(): stream_select() first, then accept with a short timeout.

macOS keeps the PHP 8.5 micro for now (the app falls back to helper processes): the same craft on both Macs (the epoll_pwait2 patch changes nothing there: macOS uses kqueue), then the same thread check; macOS runners exist only on GitHub (or an own Mac runner).

Limits

  • x86_64 only (no ARM, no macOS yet: StaticPHP can, the registry has no macOS build of SDL yet).
  • The executable is not signed: Windows SmartScreen asks "Run anyway" the first time; on Linux, chmod +x after a download.
  • A game that runs other programs, or reads files outside its folder, does it on the player's computer.

Le cache des micros : ne jamais copier un fichier d'une clé à l'autre

~/.jumphp/standalone/micro-<système>-<clé>.sfx : la clé est le hash de tools/standalone-key.sh (version de PHP, liste d'extensions, StaticPHP, docker/standalone, patchs). Jeux et applications graphiques : tools/standalone-extensions.txt (SDL, OpenGL, OpenAL) ; applications de bureau Tauri : tools/app-extensions.txt (FFI, sans SDL) : deux clés, deux fichiers. Copier ou renommer un micro sous une autre clé « pour éviter de reconstruire » donne des exécutables qui plantent chez les joueurs (Call to undefined function SDL_Init()), c'est arrivé le 6 novembre 2026. tools/standalone.sh vérifie maintenant que le micro contient chaque extension de sa liste (symboles SDL_CreateWindow, IMG_Load, Mix_OpenAudio, TTF_OpenFont, glGenBuffers, alcOpenDevice) : un mauvais fichier est retiré du cache et l'export s'arrête. La clé a changé ? Reconstruire : Linux JUMPHP_STANDALONE_BUILD=1 bin/jumphp export:standalone <id> --linux, Windows / macOS par le workflow standalone. Avant de publier un exécutable : le lancer (SDL_VIDEODRIVER=dummy SDL_RENDER_DRIVER=software SDL_AUDIODRIVER=dummy timeout 10 ./fichier).