What an AI has at hand in a JumPHP project
AGENTS.md is the contract (how to make a game, the rules). This page is the inventory: every tool an AI can call, every engine extension, every class of the engine and every command, so nothing that exists is written again. Read the part you need; the sources and docs/ say the details.
1. MCP servers and their tools
| Server | How it is connected | What for |
|---|---|---|
jumphp-ide |
automatically, for the Claude / OpenCode of the JumPHP IDE | drive the IDE: files, runs, debugger, profiler, Cryo, A/B tests, terminal |
jumphp-debug |
claude mcp add jumphp-debug -- bin/jumphp debug |
the step debugger from a terminal's Claude Code |
jumphp-ide-debug |
claude mcp add jumphp-ide-debug -- jumphp-ide --debug-mcp (or -- bin/jumphp ide:debug) |
live debug of the user's running JumPHP IDE: its state, stuck / slow commands, frames, log, replay a command (docs/ide.md "Live debug") |
jumphp-notify |
claude mcp add jumphp-notify -- bin/jumphp notify:mcp |
push notifications of an application (the owner's token) |
jumphp |
claude mcp add --transport http --scope user jumphp https://jumphp.net/mcp --header "Authorization: Bearer jph_…" |
the playground: projects, publishing, tests, private files, notes, todos |
| plugins | IDE plugins add tools (mcp__jumphp-ide__plugin_<id>_<name>) |
see docs/ide-plugins.md |
jumphp-ide (the IDE)
get_state: What the user sees in the IDE: the open files, the active one with its cursor and selected text, the tool windows shown, the run configurations (their ids forrun), the number of problems.open_file: Opens a file in the IDE's editor (for the user to see), optionally at a line or a range of lines, selected.highlight: Points the user at lines of a file: opens it there and marks the lines with your message beside them (until the next highlight or the user clears it).clear_highlights: Removes the marks of highlight.show_diff: Shows the user the changes of a file against the last commit (a diff tab), or the Commit window with every changed file when no path is given.show_tool: Shows a tool window of the IDE.find_in_files: Shows a search in the IDE's Find window (the user sees the matches) and returns how many there are.search_engine: Searches the project's text files with the IDE's search engine (an index kept up to date: answers at once, ranked best first, BM25 with a bonus for file names and declarations).recent_changes: The project's files changed most recently on disk, newest first, whoever changed them (the IDE, you, a terminal, git): time, size, git status, and whether the IDE saved it or it changed outside the IDE (when its local history knows).run: Runs a run configuration of the project in the IDE's Run window (the user sees its output, test results as a tree, screenshots) and waits for its end: exit code, tests passed / failed, the end of the output, the screenshot it made.debug_breakpoints: Sets the breakpoints of a file (all of them: lines not given are removed), shown in the IDE's gutter, given at once to the programs being debugged; a line can have a condition (a PHP expression: it stops only when true).debug_run: Runs a run configuration with the debugger (Xdebug, like the IDE's Debug: config is an id of get_state or "bin/jumphp test pong", "bin/jumphp shot pong"...) and waits until a breakpoint stops it (then: where, the stack, the local variables), it ends, ortimeoutseconds pass (default 120).debug_state: Where the debugged program is stopped: file, line, the stack, the variables of a frame (0: where it stopped; 1: its caller...).debug_step: Moves the stopped program: step_over (the next line), step_into (into the call), step_out (back to the caller), run (to the next breakpoint), stop (ends the program).debug_eval: Evaluates a PHP expression where the program is stopped ($this->score * 2, count($enemies), $map->tileAt(3, 4)...): its value (and its children, for arrays and objects).debug_run_to: Runs the stopped program to a line (Run to Cursor) and waits until it stops there, at a breakpoint met first, or ends.debug_set_value: Gives a variable of the stopped program a new value: name as in debug_variables ($sum, $this->lives, $list[3]), value a PHP expression evaluated there (9, "Ada", [1, 2], null).debug_exceptions: Exceptions that stop the program where they are thrown, caught or not ("*": every exception; class names: Error, TypeError, App\GameOver; []: none).debug_variables: The variables of a frame of the stopped program, or the children of one of them (name: its full name as given, e.g.profile_run: Runs a run configuration under Xdebug's profiler (shown in the IDE's Profiler window) and waits for its end: config is an id of get_state or a command line like "bin/jumphp shot pong" (a headless game run:shotortest, withframes, is best;runopens a window and waits for the player).profile_summary: The hot spots of a profile made by profile_run (the newest when no id): where CPU time and memory go, as Markdown (own time, with calls, calls, memory, file:line, callers, costliest lines, the frame split of a game) or JSON.profile_compare: Compares two profiles (a = before, b = after an optimisation): total time, memory and the functions that got slower, faster, heavier or lighter, with their deltas.cryo_inspect: Reads an ext-cryo file of the project (shown in the IDE's Cryo window): a snapshot .cryo (what retains memory per class, allocation sites, biggest retainers, duplicates, objects kept by cycles, leak heuristics), a freeze file .cryf (header, can it be thawed here) or a series .cryom (memory samples).cryo_why: Why an object is still alive in a snapshot (.cryo): the shortest paths from a root (global, static property, stack frame) to it, and what holds it.cryo_freeze: Freezes the program running with "Run with memory metrics" into a save point (var/cryo/savepoints/.cryf): the whole program (every object, timers, level, player: resumed exactly), and its scene alone as a fallback when the code changed since; the answer says process: true / false and why; the user can then resume there from the Cryo window (or bin/jumphp run with JUMPHP_CRYO_THAW=).cryo_patch: Hot patch: replaces a method (or function) of the program running with "Run with memory metrics" by its code as it is now in the file, while it runs (Cryo\Engine: no restart, nothing lost: level, player, connections).cryo_patch_constant: Hot patch: sets a constant ("NAME" or "Class::NAME") of the running program to a value (JSON), e.g.cryo_patch_revert: Undoes the hot patch #change of the running program, or every one without change.cryo_console: Runs PHP inside the program running with "Run with memory metrics", between two frames ($engine, $scene = the scene on top; variables kept from one call to the next); returns what it printed and the value of an expression.ab_start: Starts an A/B test of a game or app (the IDE's Cryo window, A/B tab): copies its PHP code as it is now (version A).ab_changes: The files and functions (Class::method) changed since ab_start, with their lines.ab_run: Profiles the version A (the code at ab_start: the changed files are loaded from its copy) and the version B (the code now) on the same headless run (bin/jumphp shot , scene = a scene class or empty for its smoke scene) and compares them: CPU ms and memory of the whole run and of each section (the changed functions, or the ones given).ab_stop: Ends the A/B test: its copy A is deleted, the code stays as it is now.cryo_diff: Compares two snapshots (.cryo) of the project: a = before, b = after; objects and bytes per class, and the allocation sites that keep growing (with the line that stores them: hooked_by).cryo_sandbox: Runs PHP code in an isolated Cryo\Sandbox of the desktop runtime (JumPHP's PHP with its extensions): returns its value (var_export), its output, its time and memory, or the error (fatal, timeout, memory limit) without harming anything.cryo_live: The memory metrics of the program running now with "Run with memory metrics" (the Cryo window; env JUMPHP_CRYO_METRICS): memory, peak, live objects, GC; snapshot=true writes its object graph into var/cryo/ and returns the path (then cryo_inspect / cryo_diff it).composer_search: Searches Packagist (packagist.org) for Composer packages: name, description, downloads, stars.composer_package: A Composer package on Packagist: description, license, home page, repository, its versions (newest first) with what each requires, and the constraint composer require would write.composer_outdated: The outdated packages of a composer.json of the project (composer outdated, in Docker through bin/jumphp; shown in the IDE's Composer window): installed version, latest, and whether the update stays within the constraint.composer_require: Adds (or changes the version of) a Composer package in a composer.json of the project: composer require [:] [--dev], run where the user sees it (the Run window; Docker through bin/jumphp, the IDE's copy of JumPHP for a web site).composer_remove: Removes a Composer package from a composer.json of the project (composer remove, in the Run window).symfony_commands: The commands of the project's Symfony console (bin/console) or Laravel artisan, as the IDE's Console window lists them (run in the site's PHP container when bin/jumphp web:serve runs it): name and description of each (filter: a part of the name or description); with command, its whole definition (arguments, options, help).symfony_run: Runs a command of the project's Symfony console (bin/console) or Laravel artisan, without questions (--no-interaction), in the site's PHP container (with its database when the site runs), and returns its exit code and output.docker_ps: The Docker containers of this computer (the IDE's Docker window): id, name, image, state, status, published ports, Compose project and service, and their CPU / memory when running (stats=true).docker_logs: The last lines of a Docker container's logs (id or name from docker_ps; tail: how many lines, default 200).docker_hub_search: Searches Docker Hub's public images (name, description, stars, pulls, official); with name instead of query, the repository's page (description, newest tags with size and date).docker_pull: Pulls a Docker image (e.g. nginx:1.27, user/name:tag) where the user sees it (the Docker window shows the progress) and waits for the end; returns the end of docker's output.board_list: The project's Board (the IDE's Board window: jumphp.net's board for a project linked to it, else .jumphp/board.json): its columns in order (the last one is "done") with their cards: id, title, body, labels, priority, due date, assignee, checklist, linked issue / pull request.board_add_card: Adds a card (a task) to a column of the Board (default: the first one) and returns its id.board_move_card: Moves a card to a column (name or id) at a position (0 = top; default: the end).board_update_card: Changes fields of a card (only the ones given): title, body, labels, priority, due, assignee, checklist.notes_list: The project's notes (the Board window's Notes tab): id, title, Markdown body, last change.note_save: Writes a note of the project (Markdown): a new one without id, else replaces the title and body of the note id.cpc_run: Runs the project's Amstrad CPC disc (.jumphp/ide.json dsk, ordsk= a .dsk path on this computer: it is remembered) headless in dsk2jumphp's emulator (Docker, built once) and shows the result in the IDE's Amstrad CPC window.cpc_dump: Reads a dump of a cpc_run: memory as hex (addr, len) with the registers, mode and banks; disassembly from..to (*= executed in that run); find_text (a text in any charset); compare_with another dump of the run (diff_from / diff_to values, diff_range) to find lives, level, score.cpc_extract_gfx: Extracts graphics from a dump of a cpc_run into var/cpc/extract/ (PNG): kind gfx (n sprites of w bytes x h lines at addr; mode, zigzag, scale), tiles (count tiles at addr; w, h, perRow), screen, or palette (the 16 pens).cpc_extract_sound: The sound of a cpc_run (its AY register log): without from, the frame ranges where something plays; with from / to, renders them to OGG (or WAV with ogg=false) in var/cpc/extract/, loop=true also estimates a music loop's length.svn_status: The project's Subversion working copy (when it is one): URL, branch, revision, and every changed file (code M modified, A added, D deleted, ? unversioned, ! missing, C conflict), as the IDE's Commit window shows it.svn_diff: A unified diff of the SVN working copy against BASE (one path, or everything), or what a revision changed (revision = its number).svn_commit: Commits to Subversion (svn commit) with a message: the given paths, or every change.svn_update: svn update of the working copy (to HEAD): returns the revision and the files left in conflict (the Commit window lets the user resolve them).svn_log: The Subversion history (of a path, or of the working copy): revision, author, date, message and changed paths, newest first.play: Plays the file's game, as the IDE's Play does: a scene file starts the game in that scene, a test file runs only its tests.diagnostics: The problems the IDE finds in a PHP file (syntax errors, unknown classes, methods, functions), or in the open files when no path is given.ask_user: Asks the user a question in the IDE and waits for the answer (up to 10 minutes).permission: Asks the user in the IDE whether Claude may use a tool (Claude Code calls it by itself when a tool needs a permission: do not call it).terminal_list: The tabs of the IDE's Terminal tool window: id, label, whether the shell is still running, the screen size.terminal_send: Types text into a Terminal tab as the user would (the tab is shown).terminal_read: What a Terminal tab shows now: the lastlineslines of its screen and scrollback as text (default 40).notify: Shows the user a short notification in the IDE.
jumphp-debug (bin/jumphp debug)
debug_breakpoints: Sets the breakpoints of a file (all of them: lines not given are removed); a line can have a condition (a PHP expression: it stops only when true).debug_exceptions: Exceptions that stop the program where they are thrown, caught or not ("*": every exception; class names: Error, TypeError, App\GameOver; []: none).debug_wait: Waits until the program run with JUMPHP_XDEBUG= (bin/jumphp test pong, shot pong, php games/x/tool.php...debug_state: Where the program is stopped: file, line, exception, the stack, the variables of a frame (0: where it stopped; 1: its caller...).debug_step: Moves the stopped program: step_over, step_into, step_out, run (to the next breakpoint), stop (ends it).debug_run_to: Runs the stopped program to a line and waits until it stops there, at a breakpoint met first, or ends.debug_eval: Evaluates a PHP expression where the program is stopped ($this->score * 2, count($enemies)...): its value and children.debug_variables: The variables of a frame, or the children of one of them (name: its full name, e.g.debug_set_value: Gives a variable of the stopped program a new value: a PHP expression evaluated there (9, "Ada", [1, 2], null).
jumphp-ide-debug (jumphp-ide --debug-mcp, bin/jumphp ide:debug)
debug_status: Whether live debug is on in the running JumPHP IDE (and until when, whether eval is allowed).debug_enable: Turns live debug on in the running IDE (it shows a red badge; off by itself afterminutes, default 60, at most 240).debug_disable: Turns live debug off.ide_state: The IDE's state: version, PHP, open project, indexing (indexed, librariesIndexed, progress), busy, frame rate, commands in flight and their age, slow commands, slow frames, the page's last report (what backend.invoke still waits for).ide_invokes: The commands of the interface (backend.invoke -> PHP): pending ones with their age, the last ones with duration (ms), error and a short payload; newest first.ide_frames: The IDE's frame loop: average and max frame time, and the slow frames (>= 50 ms) with the time of each part (Claude, Debugger, indexing, plugins...).ide_log: The IDE's log (what the Logs window shows: programs it ran, errors, interface errors), newest last.ide_run: Runs a command of the IDE as the interface would (backend.invoke(command, payload)) and returns its result and duration: replay what the editor sent to reproduce a bug (php.complete {path, text, line, column}, index.status...).ide_memory: The IDE's memory. In deep debug mode (ext-cryo): live object counts per class, snapshot: a name to snapshot the whole heap, diff: [a, b] what grew between two snapshots (leaks).ide_patch: Hot patch of the running IDE (deep debug mode, ext-cryo; needs "Allow eval"): action method {class, method, code: "function (...) {...}"}, function {function, code}, constant {constant, value}, revert {change?}, journal.ide_deep_restart: Asks the user (a dialog in the IDE, never automatic) to restart the IDE in deep debug mode: from JumPHP's sources in Docker (PHP 8.5 with ext-cryo, optional PHP Debugger on port 9003), same project, live debug on.ide_eval: Runs PHP code inside the IDE process ($main: the desktop app, $ide: the open project's JumPHP\Ide\Ide or null, $debug: LiveDebug); returns its return value and output.
jumphp-notify (bin/jumphp notify:mcp)
notify_send: Sends a push notification to the subscribers of the application.notify_dry_run: How many subscribers a notification would reach; nothing is sent.notify_stats: Per day: sent, delivered, opened, dismissed, refused, failed; active subscribers, unsubscriptions.notify_history: The notifications sent, newest first.notify_subscribers: The subscribers (subscription, user, groups, created, last_seen).notify_groups: The groups of the application and how many subscribers are in each.notify_set_groups: Puts a user in these groups (replaces their groups, server side).
jumphp (the playground, https://jumphp.net/mcp)
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, get_notes, save_note, delete_note, list_todos, add_todos, update_todos, list_feedback, moderate_feedback, list_crash_reports, get_crash_report, delete_crash_report, notify_send, notify_stats, notify_history (AGENTS.md section 14).
2. Engine extensions (Composer packages, bin/jumphp extension:add <game> jumphp/<id>)
- jumphp/collision (
extensions/collision): Shapes (circle, box, convex polygon), the separating axis test with the minimum translation, rays and a spatial hash broad phase. Services:JumPHP\Collision\CollisionWorld. Example game:games/collision-demo.- Circle, Box, convex Polygon (regular(), rotated())
- Collision::test() gives the normal and the depth: how to push apart
- Collision::raycast(): the first shape a ray meets, with its normal
- SpatialHash broad phase and a CollisionWorld service: collisions(), at(), overlapping(), raycast()
- Pure PHP on floats: the same in the browser
- jumphp/dialogue (
extensions/dialogue): Branching dialogues with conditions and variables, a quest log and a typewriter text box, written as JSON files and checked when loaded. Services:JumPHP\Dialogue\Variables,JumPHP\Dialogue\QuestLog,JumPHP\Dialogue\DialogueRunner,JumPHP\Dialogue\DialogueBox. Example game:games/dialogue-demo.- .dialogue.json files: nodes, choices, conditions (gold >= 5 && !helped), set / action, {variables} in the text
- Variables and a QuestLog (objectives with counts, started / progress / done / failed events) that dialogues can read and drive
- DialogueRunner: start, line(), advance(), choose(); actions go to your code
- DialogueBox: the text letter by letter, choices with a cursor, sized to the view
- Errors say where (the dialogue, the node, the choice); save and restore of the whole state; pure PHP, 32-bit safe
- jumphp/effects (
extensions/effects): Fades, wipes, an iris and a dissolve to change scene, a flash, a vignette and easing curves: all drawn with translucent rectangles. Services:JumPHP\Effects\Flash,JumPHP\Effects\Transition. Example game:games/effects-demo.- Transitions: fade, wipe (4 sides), iris on a point, blinds, dissolve; cover, change the scene under it, reveal
- Flash: light the screen in a colour, it fades
- Vignette: darker edges
- Ease: 10 curves (quad, cubic, back, bounce, elastic) and lerp
- Pure PHP, 32-bit safe: the same in the browser
- jumphp/externals (
extensions/externals): Big game data streamed from the playground: browse, search, read files by blocks, cached Services:JumPHP\Externals\Externals. Example game:games/externals-demo.- list / search / stat the folders the administrator shares with the game
- open a file and read any part of it: only its 64 KB blocks are downloaded (HTTP Range)
- memory cache + persistent cache (IndexedDB in the browser): read once, not downloaded again
- readAll() with progress for a whole file
- local folders instead of the server on desktop and in tests
- jumphp/notification (
extensions/notification): Push notifications on your players' phones (JumPHP runtime for Android), with their consent, sent from a script or Claude Services:JumphpExtensions\Notification\Notifications. Example game:games/notification-demo.- Notifications service: supported(), reason(), subscribe(user, groups), status(), unsubscribe() as Tasks, events
- NotifyToggle: one Gui line "Receive notifications" that subscribes, unsubscribes and guides the install
- Sender: send to everyone, users or groups, dry run, stats, history, subscribers, groups (engine Http or curl)
- bin/jumphp notify, notify:stats, notify:history and an MCP server for Claude (notify:mcp)
- Three doors: the administrator's approval, the owner's token, the person's own consent in the runtime
- PhoneSimulator and FakeTransport for your tests; texts in 14 languages
- jumphp/particles (
extensions/particles): Particle engine for JumPHP games: emitters (rate, bursts, lifetime, speed and angle spread, gravity, colour and size over life), seeded Services:JumPHP\Particles\ParticleSystem. Example game:games/particles-demo. - jumphp/physics (
extensions/physics): A small 2D physics engine for JumPHP: balls, rings and arcs (rotating, opening, growing, shrinking, with gaps), pegs, walls; gravity, restitution, collision events; fixed step, seeded, 32-bit safe Services:JumPHP\Physics2d\World. Example game:games/physics-demo. - jumphp/runtime (
extensions/runtime): Let an application running in the browser connect from the user's own computer and network (VPN, LAN, a server open to their address), with their consent: client, status badge and install guide. (the code is part of the engine since 0.5.27: this package carries the docs and the samples) Example game:games/runtime-demo.- RuntimeClient ($engine->runtime()): state unknown | checking | missing | running | ready | refused | unsupported, check(), pair(), a change event
- net_mode in project.yaml: auto (the runtime when ready, else the server) | server | local
- RuntimeBadge: a Gui widget, green / orange / red / grey, a click asks for the authorisation or opens the guide
- RuntimeGuide: a dialog with the steps (download for your system, install, start, allow) that turns green by itself
- Only active in the browser; on the desktop the application already has its network
- jumphp/shorts (
extensions/shorts): Vertical videos (TikTok, Shorts, Reels) made from a JumPHP scene: melodies played by collisions, the sound mixed offline, bin/jumphp video:make renders the frames and the MP4 Services:JumPHP\Shorts\Recorder. Example game:games/shorts-demo. - jumphp/tiles (
extensions/tiles): Caves, dungeon rooms, auto-tiling, A* path finding and a TileMap converter. Example game:games/tiles-demo. - jumphp/webrtc (
extensions/webrtc): Peer-to-peer WebRTC from PHP: data channels between players (no server in the middle), and a computer's screen streamed to a browser with mouse and keyboard. Services:JumPHP\WebRtc\WebRtc. Example game:games/webrtc-demo.- One PHP API on both targets: the browser's RTCPeerConnection, a native GStreamer peer on the desktop
- Data channels: reliable or not, ordered or not, text and binary
- Signaling over the relay you already have (NetSession) or any channel of your own
- Screen streaming (Linux X11): H.264 with the GPU's encoder (VA-API, NVENC) or x264 zero-latency
- Remote input: absolute / relative mouse, buttons, wheel, keys, Unicode text (XTest)
- LAN first (ICE host candidates), STUN for the internet
3. The engine, class by class (engine/src, namespace JumPHP\)
Async
Pool: A fixed set of worker threads sharing a job queue (Tasks::pool()).Task: The result of some work running in the background (a thread, a pool worker, or the fallback queue).TaskFailed: An exception thrown by work that ran in another thread.Tasks: Background work for games, three backends behind one API (backend()):WebWorkers: Browser backend of Tasks / Pool:Worker: Runs inside a Web Worker (engine/web/jumphp-worker.js):
Audio
Audio3d: Positional sound ($this->engine->audio3d()):AudioLog: What a game played and when, for a film of it (bin/jumphp video:replay):PcmStream: Streamed sound ($this->engine->pcm()):SoundManager: Sound effects and music through SDL_mixer.Synth: Retro sound effects generated in PHP:
Bridge
JsBridge: The link between the game and the web page (browser only), both ways, synchronous with the frames:
Cryo
HotPatch: Hot patches of the running program with ext-cryo's Cryo\Engine (the JumPHP IDE's Cryo window, "Hot patch" tab; Claude's cryo_patch_* tools):LiveMetrics: JUMPHP_CRYO_METRICS= (the JumPHP IDE's Cryo window, "Run with memory metrics"):ProcessFreeze: The whole program frozen with ext-cryo (cryo_freeze:SandboxLoop: Cryo\Sandbox\Sandbox in a JumPHP game or app, the ReactPHP way:Savepoint: Development save points (the JumPHP IDE's Cryo window, "Freeze" / "Resume here"):
Debug
AbOverlay: A/B tests of the JumPHP IDE (Cryo window, A/B tab):FpsCounter: Frames per second over the last second, and the time of the slowest frame.HotReload: Hot reload, in the browser (the playground's sandbox and online editor):LiveFrame: A frame for a viewer (the Claude Code pane jumphp-live):
Device
Device: Phone / tablet features ($this->engine->device()).Lifecycle: The life of the page / window, the same events on both targets:Pwa: The game as an installable, offline app (PWA) — $this->engine->pwa().
Entity
Entity: Something that moves in the world:EntityManager: The entities of a scene:GameObject: An object of a level:Gravity(trait): Falling: adds gravity to vy, up to a terminal speed.Sprite(trait): Animated sprite from a sprite sheet.
Extension
AssetLoader(interface): Reads a file format of an extension (composer.json extra.jumphp.loaders:Constraint: Version constraints of extra.jumphp.engine (what JumPHP an extension works with), the Composer syntax that matters:EngineVersion: The JumPHP version a game runs on:Extension(interface): The boot class of an extension (composer.json extra.jumphp.boot):Extensions: The engine extensions of a game:
Gl
Mat4: 4x4 matrices as 16 floats in column-major order (what GLSL uniforms expect), for WebGl::draw() and for software 3D (transform() + Renderer::drawLine:OpenGl: OpenGL from PHP ($this->engine->opengl()):WebGl: A 3D layer and post-processing shaders ($this->engine->gl()), on desktop and in the browser:
Gui
Button: A button.style: default | primary | danger | flat;image:CheckBox: A box to tick:text,checked.ComboBox: A drop-down list:items,selected(index, -1:Container: A box of widgets laid out like a web page, without HTML:EstimatedFont: Text sizes without any font (no SDL:Form: A window of a graphic PHP app (no HTML):FormLoader: Form files to widgets.HasContextMenu(trait): A small menu opened by a right click, drawn over the form (Overlay):Image: A picture:src= a file of the app (assets/images/logo.png) or any file on the disk (one the user chose:Label: A text.size(dp, default the theme's),bold,color,textAlign(left | center | right),wrap(long texts go to the next line, default true),style:ListBox: A list of lines to choose from:Overlay(interface): A widget that opens something over the form (a combo box's list, a text field's context menu):Picture: Pictures of the widgets (Image, Button's image, Video's frames):Pointer: What the user did this frame, for the widgets:ProgressBar: How far something went:Radio: One choice among several:ScaledFont: Another font drawn bigger or smaller (the pixel font at a GUI text size).Separator: A thin line between two groups:Slider: A value chosen by sliding:Spacer: Empty room between two widgets:TextBox: A text field:text,placeholder,password(shown as dots),maxLength(0:Theme: How a form looks: its colours (light or dark), its sizes and its fonts.Video: A video:src= a film put in assets/videos/ (assets/videos/intro.mp4:Widget: A piece of a form: a button, a text box, a list, a container...
Http
Http: Asynchronous HTTP ($this->engine->http()):HttpError: The request got no answer at all:HttpResponse: An HTTP answer (any status:
Input
ActionMap: Named actions instead of raw keys:Gamepad: Gamepads, with the same button names everywhere (the "standard" layout of the W3C Gamepad API, Xbox names):InputManager: Drains the SDL event queue once per frame and feeds keyboard (keys, typed text), mouse (buttons, wheel), touch and gamepads.InputRecorder: A played session as scripted input:Keyboard: Keyboard state by SDL key code (\SDLK_UP, \SDLK_SPACE, \SDLK_a ...):Mouse: Mouse in view pixels (InputManager converts from window pixels through the letterbox).PhysicalKeys: The physical keys (where a key is on the keyboard, whatever the layout):Touch: Touch screen gestures from SDL finger events (coordinates 0..1 of the screen):TouchControls: On-screen controls drawn by the engine itself (the native Android app:
Kernel
Application: Boots a game. The game's app.php (desktop) and the page (browser) both go through here:Engine: The running game: owns the services and runs one frame per tick():GameConfig: config/project.yaml of the project (theproject:key; older projects:Platform: Where the game runs. PHP_OS says "Linux" in the browser too:
Loop
FixedStep: Fixed-rate updates from a variable frame time:GameLoop: The ReactPHP event loop, shared by the engine and the game (timers, deferred calls).
Native
Autostart: An exported app that starts with the computer, when the user logs in (docs/tauri.md "Starting with the computer"):BaseProvider: Every feature unsupported (a failed Task, or false):BrowserProvider: The browser build: links open in a new tab, text to the clipboard, and the system's file chooser (an :Clipboard: The system's clipboard (text).Dialog: The system's message boxes.FilePicker: The system's file choosers.Native: The system's own features from PHP, the same calls on every target (Dialog, FilePicker, Notification, Shell).Notification: A notification of the system (desktop apps).NullProvider: No native feature (headless runs, a server...).Provider(interface): Who does the native features on a target:SdlProvider: Games on the desktop (SDL):Shell: Opens things with the system's programs:TauriProvider: Desktop apps (JumPHP\Tauri\App):UnsupportedFeature: A native feature this target does not have (the Task of the call fails with it; Native::supports() says it first).
Net
BridgeRoute: Which bridge a browser connection uses, by the network mode (JUMPHP_NET_MODE / project.yamlnet_mode):Icmp: Pings (ICMP echo), never blocking:LobbyScene: Ready-made online lobby:MessageCodec: Game messages = one type byte + a payload.NetSession: Online play through php-wasm-network:NoRuntime: The default RuntimeLink, when thejumphp/runtimeextension is not installed:RuntimeLink(interface): The engine's view of the JumPHP runtime (the small program that lets an application running in the browser connect from the user's own computer and network:SnapshotBuffer: Smooth remote objects:Ssh: SSH for applications (a SQL client through a bastion...):SshConnection: One connection through an SSH server (ssh -W host:port, see Ssh).SshConnector: What Tcp is for a plain connection, for one through an SSH server (Ssh::via()).SshKeyring: The SSH keys an application keeps for its user, an agent's role in the browser (which has no ssh-agent):Tcp: TCP connections for applications (a SQL client, a Redis tool...), never blocking the frame.TcpConnection: One TCP connection, or one UDP "connection" (a socket to one address:Udp: UDP for applications (DNS, NTP, game servers...), never blocking:
Physics
Aabb: Axis-aligned boxes: ['x' => left, 'y' => top, 'width' => w, 'height' => h] (Entity::getBoundingBox()).CollisionResult: What CollisionSystem::move() found during one move.CollisionSystem: Moves entities through a tile map, pixel by pixel, against the collision masks of the collision layer:TileCollision(trait): Collision flags on an entity, filled by CollisionSystem::move():
Renderer
BitmapFont: Built-in 5x7 pixel font:Captions: Timed captions over a scene or a whole game (a question, a reaction, a "wait for it", a call to action):CrtFilter: Old TV look: dark scanlines every other line of the view, drawn over the frame.Renderer: Draws the game at its virtual resolution (game.yaml width x height) into a render-target texture, then scales it to the window with letterboxing and nearest-neighbour filtering:Sdl: SDL facade: window, renderer and textures by name.TextDrawer(interface): Something that draws text:TtfFont: Text with a TrueType font of the game (assets/fonts/*.ttf), rendered once per (text, colour) and cached as a texture (LRU):Window: The SDL window. In the browser it is the page's :
Runtime
ManualRuntime: A RuntimeLink whose state you set by hand:RuntimeBadge: The status light of the JumPHP runtime, for a Gui form (docs/runtime.md).RuntimeBanner: The whole "use your own network" notice of an application, in one line of a form (docs/runtime.md):RuntimeClient: The JumPHP runtime as the application sees it ($engine->runtime()):RuntimeGuide: The guide dialog that walks the user through installing the JumPHP runtime.RuntimeMessages(interface): A runtime that can carry other messages than the network ones (docs/notifications.md:
Save
Options: Player settings, saved in var/options.json as soon as they change.Storage: Files of the player in var/ of the game:
Scene
AbstractScene: Base class of the game's scenes.Camera: Which part of the world is on screen.HotReloadable(interface): A scene that keeps its state when the game is hot reloaded (the sandbox / online editor of the playground:Scene(interface): A screen of the game:SceneManager: A stack of scenes. The top one is updated; it and the overlays under it are drawn.
Service
Daemon: A program that runs in the background as a service (bin/jumphp service:install, docs/services.md):
Tauri
App: A desktop app: native windows whose pages are HTML / CSS / JS (Tauri), driven by PHP.AppCli(interface): A desktop app that also works from the command line (no window):AppMain(interface): The main class of a desktop app (game.yaml `main:BrowserRuntime: A desktop app in a web page (bin/jumphp build :EmbeddedGame: A hybrid game in ONE window (game.yaml `ui:FakeRuntime: A runtime without a window, for tests (AppTestCase) and headless checks:Hybrid: A game (SDL) that also drives Tauri (game.yaml `ui:Invocation: A call from a page: jumphp.invoke(name, payload).LinuxWebView: Linux: the system's WebView of desktop apps (WebKitGTK 4.1), installed when it is missing.Menu: The menus of a desktop app (App::setMenu(), Window::setMenu()), written as PHP arrays:NativeCommands: The native features a page can ask for without PHP code of its own (game.yaml app.native_commands:NativeEvent: An event of the native side that has a default action (a window asked to close:NativeRuntime(interface): What runs the native window of a desktop app.Overlay: Code updates for an exported desktop app (the JumPHP IDE):TauriRuntime: The Tauri runtime, a C library (tauri/, built bybin/jumphp tauri:build) loaded with PHP's FFI.Tray: An icon in the system's tray, made by App::tray().Update: A newer version of the app, found by Updater::check() (its signature checked).Updater: Updates of an exported desktop app (bin/jumphp app:export / app:release, docs/tauri.md "Updates").Window: A native window of a desktop app, with its page (a WebView).
Testing
AppTestCase: A PHPUnit test of a desktop app (JumPHP\Tauri\App) without a window:Game: A game driven by a test, frame by frame, without a window (GameTestCase):GameTestCase: A PHPUnit test that plays the game (Game):
Tile
ArrayLoader: Maps written in PHP code, one string per row:BinaryLoader: Maps stored as raw bytes (one byte per tile, row-major), the format of many old games and of tools that rip their levels.CollisionMask: The solid pixels of one tile.TileMap: A tile map: layers of global tile ids (0 = empty), the tilesets they come from, the objects placed in the editor and the map properties.TileMapRenderer: Draws a TileMap: image layers (parallax backgrounds), then tile layers.TileSet: A sheet of tiles: one image cut in a grid.TiledJsonLoader: Loads a map made with the Tiled editor (https://www.mapeditor.org), saved as JSON (.tmj / .json).
Ui
Hud: Small drawing helpers for heads-up displays and dialogs.Menu: A vertical menu. Each item is a row [label, value, onPress, onSide]:MenuScene: A ready-made menu screen:TextInput: Text entry that works with a keyboard AND with a pad / touch screen:
Util
Color: An RGBA colour. SDL calls take the four components separately; Color::of() accepts the usual shapes:Lang: Translations. Source strings are the keys; config/lang.yaml gives the other languages:MathTime: Clock helpers that are safe in the browser build, where PHP_INT_SIZE is 4:Vector(trait): Position of an entity.
4. bin/jumphp commands
JumPHP - retro 2D games in PHP (SDL), desktop + browser. Everything runs in Docker.
Setup
init interactive wizard: tools, your game, engine, server, GitHub, then Claude Code
(also what `bin/jumphp` alone runs in a project without a game yet)
setup [async] build the Docker images (desktop runtime, relay server; async: PHP 8.6 ZTS + TrueAsync)
engine:download [version] download the prebuilt WebAssembly engine of this version (release of git.jumphp.net)
engine:build build the WebAssembly engine (PHP + SDL -> build/engine, ~25 min once, cached)
runner:install [--forge URL] --scope org/NAME|user/NAME [--name N] [--labels L] a CI runner in Docker (git.jumphp.net), docs/ci-runner.md
runner:remove [--name N] stop and delete that runner
runner:scripts [DIR] the runner install scripts (Windows .ps1, WSL, Windows VM for Linux): print their folder, or copy it to DIR
engine:pack build/engine -> .build/jumphp-engine.tar.gz (+ .sha256), the release asset
Chrome extensions (Manifest V3, any folder; the IDE's Chrome extension projects; tools/chrome.sh, docs/chrome-extension.md)
chrome:new <folder> ["Name"] a new extension: popup, options, service worker, content script, en + fr, icons, tests
chrome:check [folder] [--json] manifest, MV3 rules, files, icons, permissions, translations (var/chrome-check.json)
chrome:run [folder] [url] headless Chrome with it loaded: id, console errors, var/screenshots/{page,options,popup}.png
chrome:test [folder] its tests (tests/*.test.cjs: node:test + Puppeteer)
chrome:pack [folder] dist/<name>-<version>.zip for the Chrome Web Store
chrome:bump [folder] [patch|minor|major|x.y.z] the version in manifest.json
chrome:icons [folder] [#bg] [#mark] / chrome:lint [folder] icons drawn again / ESLint
Web sites (any folder, no JumPHP in it needed; the IDE's web projects; tools/web.sh)
web:new <kind> <folder> [--db=mariadb|postgres|sqlite|none] [--docker=dunglas] [--php=8.x]
a new site made in Docker: symfony, wordpress, prestashop, sylius, laravel or php
(--docker=dunglas: Symfony inside https://github.com/dunglas/symfony-docker)
web:serve [folder] FrankenPHP (+ its database) + live reload + assets (npm watch / SCSS); prints its address
web:db <folder> <db> the site's database: mariadb, postgres, sqlite or none
web:dockerize <folder> an existing Symfony site moved to symfony-docker's Dockerfile and compose.yaml
web:stop [folder] stops it (the database stays)
web:up [folder] starts it in the background (its compose.override.yaml merged), no watch
web:config [folder] the merged compose configuration (checks compose.override.yaml)
web:info [folder] its kind and addresses
web:live [folder] [status|notify <file>...] live reload: the browser tabs connected; tells it a file was saved (what the IDE does)
web:composer <folder> ... / web:console <folder> ... composer / bin/console (artisan) in its PHP container
web:php <folder> [8.x|auto] the site's PHP version, shown or chosen (.jumphp/web.json); the same for serve, composer
and console (default: the newest PHP composer.json / composer.lock allow); rebuilds what it must
web:docker <folder> [jumphp|dunglas|compose [service] [file]] the site's Docker setup, shown or changed: the JumPHP stack,
symfony-docker, or its own compose file (the service that runs PHP)
runtime:build the shared engine of remote games (a games site) -> build/runtime
+ .build/jumphp-runtime.tar.gz (+ .sha256), the release asset (docs/remote.md)
runtime:download [version] download it from the release instead
ssh:build OpenSSH's ssh client as WebAssembly (docker/ssh-wasm) -> build/ssh/ssh.js + ssh.wasm, packed in the runtime (docs/ssh-wasm.md)
tidy [--examples] [--yes] remove JumPHP's own development files from this project (tools/project-clean.list)
update merge the newest JumPHP (git remote "jumphp") into the project
forge:migrate [--dry-run] moves this project's JumPHP addresses from GitHub to git.jumphp.net (composer, locks, scripts, docs, remotes)
cli:install the `jumphp` command for the whole system (~/.local/bin): `jumphp test pong` from
any folder of the project, `jumphp new <folder>`; asks to update when Packagist has
a newer JumPHP (once a day; JUMPHP_NO_UPDATE_CHECK=1: never)
cli:uninstall remove it
doctor check docker, display, sound
Games (<game> = a folder of games/, e.g. pong)
new <game> [title] create games/<game> from skeleton/
gui:new <app> [title] [--mobile] a graphic PHP app (forms of the IDE's visual editor, JumPHP\Gui: no HTML)
from skeleton-gui/; --mobile: a phone app (portrait). run / test / shot / build / export as games
video <app> <file.mp4> [name] [fps] a film as frames for the Video widget: assets/videos/<name>/ (+ audio.ogg)
install <game> composer install (engine linked from engine/)
composer <game> <args> any composer command in the game
run [game] [args...] play on desktop (window + sound); no id: the folder of games/ or apps/ you are in,
else JUMPHP_APP (.env), else the only project
test <game> [tests/X.php] lint + phpstan (if configured) + phpunit (if tests/) + headless smoke test; a test file: only its tests
test <game> --phpunit … only PHPUnit with these arguments (the IDE's Tests window: --filter, --teamcity, --log-junit, coverage)
shot <game> [frames] [out.png] headless screenshot after N frames (default 120) -> var/screenshots/
build <game> browser build -> games/<game>/dist/web (static files)
build:remote <game> the game as a remote game (shared engine, files one by one) -> dist/remote
site:new <game> [--force] a first web site for the game in games/<game>/site/ (from project.yaml + screenshots of its demo)
build:site <game> the game's web site (site/) + the game in play/ -> dist/site (what deploy sends)
siteshot <game> headless Chrome on dist/site: desktop + phone screenshots, broken images, JS errors
serve <game> [port] serve the browser build on http://localhost:<port> (default 8080)
webshot <game> [seconds] [keys] headless Chrome: load the browser build, play keys, screenshot, fail on errors
keys: JSON [[second, "ArrowDown"], [2, "Enter"]] -> dist/webshot.png
(serve / webshot: JUMPHP_WEB=remote uses dist/remote, JUMPHP_WEB=site dist/site)
export:desktop <game> a Docker image that runs the game (jumphp/game-<game>)
android <game> [--local] [--package ID] [--version-name X]
the game as a native Android app (no browser: PHP, SDL, OpenGL ES, OpenAL inside), signed:
built by GitHub Actions in your repository and published as a release (.apk + .aab for
Google Play); --local: built here in Docker. docs/android-native.md
apple <game> [--macos] [--ios] [--bundle-id ID] [--version X] [--local]
the game as native Apple apps (no browser: PHP, SDL, OpenGL, OpenAL inside): built by
GitHub Actions on a Mac in your repository, published as a release: .dmg / .zip (a Mac,
Apple silicon + Intel), .ipa (iPhone / iPad), the simulator's app, screenshots of both
running there. ios <game> / macos <game>: one of them. --local: on this Mac. docs/apple.md
export:standalone <game> [--linux] [--windows]
the game as one executable, nothing to install (PHP, SDL, OpenGL, OpenAL inside):
dist/standalone/<game>-linux-x86_64 and/or <game>-windows-x86_64.exe (docs/standalone.md)
installer <game> --github | --url https://site/folder/ | --standalone [--windows] [--linux] [--macos] [--version X] [--no-build]
an installer per system (jumphp2installer: shortcuts, uninstaller, always the newest version):
--github: a release v<version> of the project's repository (gh); --url: a folder to put at
that address, dist/installer/; --standalone: the game inside each installer (no site, no
network, no update). Builds Windows / Linux first (apps too); macOS: an existing
build (bin/jumphp macos <game>, app:export --macos). On jumphp.net: the IDE's jumphp.net window
twa <game> [--url URL] [--package ID] [--name NAME] [--same-version]
the game as an Android app for Google Play (Trusted Web Activity, Bubblewrap):
dist/android/<game>-<v>.aab (Play) + .apk (a phone) + assetlinks.json (docs/android.md).
URL: the game's page online (https), e.g. https://jumphp.net/<slug>
deploy [game...] to your server (JUMPHP_SERVER in .env, see deploy:setup): browser builds + FrankenPHP
(alone or behind Traefik), docker compose up there. Default game: JUMPHP_GAME.
Without JUMPHP_SERVER: rsync dist/web to $JUMPHP_DEPLOY_TARGET/<game>/
deploy:setup ask the server, domain, web server (FrankenPHP / Traefik + FrankenPHP / existing Traefik)
server:setup install Docker on the server (ssh)
server:logs the server's web logs
server:traefik [user@host] looks for a Traefik on the server: network, entry points, certificate resolver in use
github put the project on GitHub (gh), optionally GitHub Pages
pages [game...] build the games (default: all) + a home page, publish them on the gh-pages
branch of the git remote (GitHub Pages; the branch is replaced each time)
CLI apps (in the terminal: commands + full-screen text screens, symfony/tui; docs/cli.md)
cli:new <app> [title] create apps/<app> from skeleton-cli/ (config/project.yaml: kind: cli)
plugin:new <id> [title] a plugin of the JumPHP IDE, in PHP: apps/<id> from skeleton-plugin/ (docs/ide-plugins.md)
plugin:pack <id> the plugin as apps/<id>/dist/<id>-<version>.zip (to install in the IDE, to publish on jumphp.net)
extension:new <id> [title] an engine extension (Composer type jumphp-extension): extensions/<id> + its example
game games/<id>-demo (docs/extensions.md)
extension:doc <id> what its jumphp.net page shows (docs, tutorial, samples, example) and what is missing
extension:remove <game> <pkg> take it out again, with its samples and documentation
extension:add <game> <pkg> add an engine extension to a game (Packagist, or one of extensions/ here), then
show what it adds
video:replay <game> [--input J|file] [--scene C] [--seconds S] a film (MP4, with its sound) of any game, from scripted or recorded input
video:make <game> [--seed N] [--count N] [--seconds S] [--template T]
vertical videos (TikTok, Shorts: 1080x1920, 60 FPS, H.264 + AAC) of project.yaml video: scene,
each bounce a note (jumphp/shorts): dist/video/*.mp4 + a cover (docs/video-maker.md)
service:install <id> [--system] [--exe <file>]
the exported executable (export:standalone) as a service of this computer, from
project.yaml `service:` (systemd / launchd / WinSW; docs/services.md); also
service:uninstall, service:status, service:logs [-f], service:start, service:stop, service:print
debug the IDE's debugger for Claude Code in a terminal (MCP on stdin / stdout):
claude mcp add jumphp-debug -- bin/jumphp debug; then JUMPHP_XDEBUG=9003 bin/jumphp test <game>
ide:debug live debug of the running JumPHP IDE for Claude Code (MCP on stdin / stdout, docs/ide.md):
claude mcp add jumphp-ide-debug -- bin/jumphp ide:debug (installed IDE: jumphp-ide --debug-mcp)
ide:deep <project> [--debugger] the IDE from these sources in Docker (ext-cryo, PHP 8.5) on <project>, live debug on
(deep debug: memory snapshots, hot patches; --debugger: PHP Debugger on port 9003)
notify:login <app> push notifications (docs/notifications.md): keep the app's token jnt_… (asked, not echoed) in
~/.jumphp/notify/tokens.json (0600); JUMPHP_NOTIFY_TOKEN / JUMPHP_NOTIFY_URL win
notify <app> --all|--user U|--group G "Title" "Text" [--url /play/] [--tag T] [--ttl S] [--dry-run]
notify:stats <app> / notify:history <app> / notify:logout <app>
notify:mcp the same for Claude Code (MCP on stdin / stdout): claude mcp add jumphp-notify -- bin/jumphp notify:mcp
then run <app> [command...] / test <app> / shot <app> (the screen as text: JUMPHP_KEYS)
/ export:standalone <app> [--linux] [--windows] [--macos] (one executable, console kept)
Desktop apps (Tauri: native windows with HTML / CSS / JS pages, driven by PHP; native only, docs/tauri.md)
app:new <app> [title] create apps/<app> from skeleton-app/ (config/project.yaml: ui: webview)
app:run <app> open the app on your screen
app:test <app> php -l + phpstan + phpunit (AppTestCase, no window) + the app on a virtual screen
app:shot <app> [frames] [out.png] the app's window after N frames (default 120) -> var/screenshots/app.png
app:export <app> [--linux] [--windows] [--macos] the app as one executable: dist/standalone/<app>-linux-x86_64
(--windows: .exe; --macos: <app>-macos.zip, an .app for Apple silicon + Intel)
ide [--build] [--install] the JumPHP IDE on this computer (natively, no Docker: this checkout's IDE sources in
its executable, built once); --build: build it again; --install: menu launcher
claude:connect the web IDE (jumphp.net/ide) uses this computer's Claude Code: the JumPHP IDE with
"Claude for jumphp.net" on (authorized once in the browser)
app:release <app> --url <base> [--notes "..."] [--linux] [--windows] [--macos]
exported + a signed update.json for the apps' updates (docs/tauri.md "Updates")
(needs WebKitGTK 4.1) / <app>-windows-x86_64.exe (WebView2)
tauri:setup build the Tauri image (desktop runtime + FFI + Rust + WebKitGTK)
tauri:build build the Tauri runtime library tauri/ -> build/tauri/linux-x86_64/libjumphp_tauri.so
tauri:download [platform...|--all] the runtime library of these sources from JumPHP's releases on git.jumphp.net (workflow
tauri): linux-x86_64 (default), windows-x86_64, macos-universal
Engine
test engine engine unit tests + phpstan
lint php -l + forbidden words check of the whole repository
php <dir> <args> php in the desktop image, from <dir> (repo-relative)
Network
relay up|down|logs the multiplayer relay server (ws://localhost:8090/ws)
Environment (headless runs): JUMPHP_SCENE, JUMPHP_SCENE_PARAMS, JUMPHP_INPUT, JUMPHP_MAX_FRAMES, JUMPHP_SHOT_EVERY