TR

Engine extensions

An engine extension is a Composer package that adds a subsystem to JumPHP: particles, a physics engine, a level format with its loader... A game requires it like any package; the engine finds it by itself.

The contract

composer.json of the extension:

{
    "name": "jumphp/particles",
    "type": "jumphp-extension",
    "require": { "jumphp/engine": "*" },
    "autoload": { "psr-4": { "JumPHP\\Particles\\": "src/" } },
    "extra": {
        "jumphp": {
            "name": "Particles",
            "services": ["JumPHP\\Particles\\ParticleSystem"],
            "loaders": { ".particles.json": "JumPHP\\Particles\\EmitterLoader" },
            "config": {
                "particles": { "default": { "max": 4000, "seed": 1 }, "doc": "max particles alive, random seed" }
            }
        }
    }
}
Key What the engine does
type: jumphp-extension at boot, JumPHP\Extension\Extensions reads the game's vendor/composer/installed.json and keeps the packages of this type
services each class is autowired and public in the game's container (before the game's own config/services.yaml, which can override them): a scene asks for one in its constructor
services_file a Symfony services file of the package (path inside it), for anything services cannot say
boot a class implementing JumPHP\Extension\Extension, made by the container: boot(Engine $engine) runs once SDL, options and language are ready, before the first scene
loaders {"<end of a file name>": "Class"}, classes implementing JumPHP\Extension\AssetLoader: $this->engine->extensions()->load('assets/fx/torch.particles.json') picks the loader by the file's end
config project.yaml keys of the extension with their default: $engine->config->get('particles') gives the game's values over the defaults (arrays merged key by key)

$this->engine->extensions(): all(), has('jumphp/particles'), load($file).

Rules: pure PHP, as in a game (AGENTS.md §2): the browser build packs the game's vendor/ and compiles the container with the extensions' services, so an extension works in the browser without anything more. Not on jumphp.net yet: its shared engine does not load a game's own Composer packages.

Samples and documentation

What an extension brings into a game besides its code (bin/jumphp extension:add <game> <vendor/package> does it, extension:remove undoes it):

in the package in the game what for
doc/ (doc/index.md, else its README.md) extensions/<name>/doc/ its documentation, opened by the IDE
doc/samples/*.php src/Extensions/<Name>/ scenes of the game that play and build with it, also in the browser
extensions/<name>/extension.json what the IDE reads: the documentation and the samples
  • A sample is a scene in the namespace App\Extensions\<Name> (<Name> = the package name in StudlyCase: jumphp/particles -> Particles); public const LABEL = '...' is what the IDE shows. A sample the game already has (maybe edited) is not overwritten.
  • Play one: JUMPHP_SCENE='App\Extensions\Particles\FireSample' bin/jumphp run <game>; in the IDE the documentation opens after the install (Tools > Engine Extensions…) with a Play button for each sample, and from the External Libraries (the extension has its package name and a Docs button there).
  • extra.jumphp.samples / extra.jumphp.doc name other folders than doc/samples/ and doc/ (older packages keep their samples in samples/: still read).
  • JumPHP's own seven (particles, physics, shorts, effects, collision, dialogue, tiles) have both: try bin/jumphp extension:add <game> jumphp/particles.

A clean project

A new project (composer create-project, the IDE's New Project, jumphp.net's) does not keep JumPHP's own development files: its extensions (they are on Packagist: extension:add), its examples of games/ and apps/, its notes (TODO*.md), its tooling for its own releases. tools/project-clean.list says what, tools/project-clean.sh does it, bin/jumphp tidy does it again in an older project (--examples also takes JumPHP's example games out; your own games and apps are never touched). What was removed is listed in .jumphp/excluded: bin/jumphp update does not bring it back, and a merge that touches those files raises no conflict.

The list classes every entry of JumPHP's repository (keep, rm, new, example; rm ide/ui unless=plugin: the IDE's interface stays only in IDE plugin projects): bin/jumphp lint runs tools/tests/project-clean.test.sh, which fails as soon as a file, a template or an extension is added to JumPHP without saying whether a project keeps it, and checks on a copy that a new project keeps exactly the keep entries. The IDE's New Project reads the template's own list (JumPHP\Ide\Project\ProjectClean, no bash needed); jumphp.net's new projects and forks use the newest list of JumPHP's main (a fork of a game keeps that game, --keep).

Its page on jumphp.net

https://jumphp.net/extensions lists every Packagist package of type jumphp-extension; each has a page (/extensions/<vendor>/<package>): its README, how to add it, and what its composer.json extra.jumphp says about it (the page reads them, nothing to upload):

key what the page shows
summary one line under the title (else the Composer description)
engine "Works with JumPHP ^0.5" (see below)
features a list of what it brings (12 lines of 160 characters at most)
screenshots pictures: https addresses or paths in the repository (docs/shot.png; png, jpg, gif, webp; 8 at most)
example a code example (4000 characters at most)
docs the address of its documentation
demo its example game
services, config read as they are: the services it adds, the project.yaml keys it reads

Install in my IDE: the page's button asks the JumPHP IDE running on the visitor's computer (it listens on 127.0.0.1, ports 47321-47325, only for pages of jumphp.net). The IDE asks its user to confirm, and for an extension which game of the project gets it (bin/jumphp extension:add); for an IDE plugin it installs it. Nothing is installed without the yes. In the IDE: Tools > Engine Extensions… searches the same list. JUMPHP_IDE_LINK=0 turns the listener off.

Which JumPHP it works with

extra.jumphp.engine is a version constraint on JumPHP ("^0.5", ">=0.5 <0.7", "0.5.*", "^0.5 || ^0.9"). At boot the engine compares it with the project's VERSION: a game on a JumPHP the extension does not accept stops with acme/stars works with JumPHP ^0.6, this game runs JumPHP 0.5.7: update JumPHP (bin/jumphp update) or the extension. Without the key, or when the version is unknown (some builds without a VERSION file), nothing is checked. Declare it in every extension you publish, and widen it after trying the newer JumPHP.

Making one

In the JumPHP IDE: New Project > Engine extension (your own Git repository, the package and its example game, README with the publishing steps). On the command line:

bin/jumphp extension:new star-field "Star Field"
bin/jumphp install star-field-demo
bin/jumphp test star-field-demo        # the example game's tests: the extension's tests
bin/jumphp shot star-field-demo
  • extensions/star-field/: the package (JumphpExtensions\StarField\), a service (Flash), its boot class, a config key, README.md, AGENTS.md: replace them with your subsystem.
  • games/star-field-demo/: a game requiring it through a path repository (../../extensions/star-field): it shows the extension and its tests/ play it (GameTestCase). Develop both together.
  • Publish: see below.

Publishing an extension

Packagist serves a package from a repository with its composer.json at the root, its versions being the git tags.

Your own extension: a public GitHub repository holding extensions/<id>/'s content at its root (rename name first: <your-vendor>/<package>, keep "type": "jumphp-extension"), a tag (git tag v1.0.0 && git push --tags), then https://packagist.org/packages/submit with the repository's address (signed in with Git, Packagist installs its hook: each new tag is a new version). Games then bin/jumphp extension:add <game> <your-vendor>/<package>, and https://jumphp.net/extensions lists it (it reads Packagist's jumphp-extension packages). Do not require jumphp/engine: it is not on Packagist, and every JumPHP project already has it (../../engine).

JumPHP's own (jumphp/particles, jumphp/webrtc, jumphp/physics, jumphp/shorts, jumphp/effects, jumphp/collision, jumphp/dialogue, jumphp/tiles): developed here in extensions/<id>, split to one read-only repository each, davidnurdin/jumphp-<id>, by .github/workflows/extensions-split.yml on each release tag v* (the split gets the same tag) — the same as tools/extensions-publish.sh --push. Without --push the script is a dry run: the splits go to .build/extensions-split/<id>.git, to look at or to require through a vcs repository.

Once, to set it up:

  1. create the three empty public repositories davidnurdin/jumphp-particles, jumphp-physics, jumphp-shorts;
  2. a fine-grained token (Git > Settings > Developer settings) with Contents: read and write on these three, saved as the JumPHP repository's secret EXTENSIONS_SPLIT_TOKEN;
  3. run the workflow once (Actions > extensions-split > Run workflow, or the next v* tag);
  4. submit each repository on https://packagist.org/packages/submit.

The effects extension

extensions/effects (jumphp/effects), shown by games/effects-demo: screen transitions (Transition: fade, four wipes, an iris on a point, blinds, a dissolve; cover() a scene change reveal()), a flash, a vignette and easing curves (Ease). Everything is drawn with translucent rectangles, pure PHP, 32-bit safe. Its doc/index.md has the code; bin/jumphp extension:add <game> jumphp/effects brings two samples (FlashSample, TransitionSample) into your game. Its repository is davidnurdin/jumphp-effects (the release split writes it, Packagist reads it).

The dialogue extension

extensions/dialogue (jumphp/dialogue), shown by games/dialogue-demo: branching dialogues in .dialogue.json files (nodes, choices, if conditions read by a safe parser, set and action, {variables} in the text, branch routers), variables, a quest log (objectives with counts, quest.<id> readable by conditions) and a text box (DialogueBox: letter by letter, a cursor for the choices). A file is checked when loaded and its errors say the dialogue, the node and the choice. Everything can be saved and restored. doc/index.md has the file format and the code, and bin/jumphp extension:add <game> jumphp/dialogue brings DialogueSample into your game.

The collision extension

extensions/collision (jumphp/collision), shown by games/collision-demo: circles, boxes and convex polygons; Collision::test($a, $b) gives the normal and the depth (the minimum translation: $hit->pushOutOfFirst()), Collision::raycast() the first shape a ray meets, a SpatialHash broad phase and a CollisionWorld service (add, update, collisions(), at(), overlapping(), raycast()). Pure PHP on floats. Its doc/index.md has the code, and bin/jumphp extension:add <game> jumphp/collision brings CollisionSample into the game.

The particles extension

extensions/particles (jumphp/particles), shown by games/particles-demo:

public function __construct(private ParticleSystem $particles) {}       // each scene gets its own

public function enter(array $params = []): void
{
    $this->particles->reset();                        // empty, the configured seed again
    $this->fire = $this->particles->add(new Emitter([
        'x' => 160, 'y' => 150, 'rate' => 80, 'life' => [0.6, 1.2], 'speed' => [30, 70],
        'angle' => -90, 'spread' => 20, 'gravity' => -40, 'drag' => 0,
        'colors' => ['#fff6a0', '#ff9a1f', '#c0301000'], 'size' => [5, 1], 'shape' => 'circle', 'area' => [6, 2],
    ]));
}

public function update(float $dt): void
{
    $this->fire->moveTo($this->hero->centerX(), $this->hero->getY());
    if ($hit) {
        $this->particles->burst($this->sparks->moveTo($x, $y), 40);
    }
    $this->particles->update($dt);
}

public function render(Renderer $r): void
{
    $this->particles->render($r, $camera->getX(), $camera->getY());
}
  • Emitter settings: rate (a second; 0 = bursts only), duration (null = until stop()), life, speed (ranges [min, max]), angle / spread (degrees, 0 = right, -90 = up), gravity (px/s², negative rises), drag (0..1 a second), colors (over the life; #rrggbbaa fades), size ([birth, death]), shape (circle / square), area (born in a box).
  • Deterministic: the same seed (project.yaml particles: {seed: 7}, or reset(7)) and the same frames give the same particles, on the desktop and in the browser (its generator works on floats, not 64-bit integers).
  • particles: {max: 3000} caps the particles alive in a system. Colours go through a 16-step ramp per emitter, so translucent particles stay cheap (few cached textures).
  • Files: assets/fx/show.particles.json = {"torch": {...settings...}, "snow": {...}}, read with $this->engine->extensions()->load('assets/fx/show.particles.json') (named Emitters).
  • Inspect: count(), countOf($emitter), particles() (positions, speeds, ages), emitters().

The tiles extension

jumphp/tiles (extensions/tiles, example games/tiles-demo): procedural levels on a Grid (0 floor, 1 wall). Caves::generate() (cellular automaton, one open area), Rooms (non-overlapping rooms joined by corridors), AutoTile (picture of a wall from its neighbours, 16-tile mask), Path::find() (A*), Maps::toMap() / toGrid() (a TileMap for TileMapRenderer / CollisionSystem, and back), Level (start, exit, items; toTiledJson() = a .tmj for the IDE's level editor), Rng (seeded, float arithmetic: identical in the browser's 32-bit PHP). Its doc and the TilesSample come with extension:add.

Make and publish your own, from the IDE

New Project > Engine extension makes it on your computer (the package extensions/<id> with its doc/ (and doc/samples/) and the example game games/<id>-demo; nothing online). Publish (header button / Alt+J area) asks for a version, then puts the package in its own public repository <your login>/jumphp-<id> (Composer wants composer.json at the root: the project's repository is not the package's), the composer name becoming <your login>/<id>, tagged v<version>. Submit that repository on packagist.org once (the IDE opens the page; Packagist then follows the tags by itself when you sign in there with Git); jumphp.net's directory refreshes within hours, and the studio's "My extensions" page lists what is yours.

Samples you can run: doc/samples/

Each extension keeps its samples in doc/samples/*.php: one scene per thing it does, each with a LABEL and a comment that says what to press. They are scenes of the game that adopts the extension (extension:add copies them into src/Extensions/<Name>/, the IDE's Engine Extensions window has a ▶ Play for each), and they run from the extension's own project too: the example game (games/<id>-demo) autoloads extensions/<id>/doc/samples/ as App\Extensions\<Name>\ (composer.json and config/services.yaml, written by extension:new), so in the IDE a ▶ on the class line of a sample (or of any scene) runs that scene only (JUMPHP_SCENE), not the whole project. Every demo game has a SamplesTest that starts each sample for 90 frames.

Extension Samples
particles FireSample: a fire that follows the cursor, sparks on click
physics BouncingBallsSample: balls on pegs in a box (games/physics-demo)
shorts MelodySample: a tune, one note a click, with a caption
effects FlashSample, TransitionSample, EasingSample (every easing curve, under a vignette)
collision CollisionSample (a circle, a hexagon, a ray), WorldSample (sixty circles, the spatial hash)
dialogue DialogueSample (a shopkeeper), QuestSample (a quest log)
tiles TilesSample: a cave or a dungeon, start, exit, items, the shortest path

Never move a published tag

Packagist freezes the commit of every stable version. If a v* tag of an extension repository (or of JumPHP) later points to another commit (re-tag, force-push, a repository re-split with another history), Packagist refuses the update and e-mails the maintainer. tools/extensions-publish.sh never moves a tag; neither should you. A fix goes out as a new version. If it happened, force the tag back to the reference shown on https://packagist.org/packages/<vendor>/<package>.

The page on jumphp.net: documentation, tutorial, example game

The extension's page shows three buttons: Example game (opens in the browser when games/<id>-demo is published on the playground as the project <id>-demo, app:project:import or the MCP import_project, unlisted), Tutorial (doc/tutorial.md, one ## Step per action; without it the page builds one from the samples) and Documentation (doc/index.md). Fill them in the IDE (Publish extension > Edit its page…: summary, features, screenshots, documentation, tutorial) or by hand; bin/jumphp extension:doc <id> lists what is still missing.