17 KiB
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.docname other folders thandoc/samples/anddoc/(older packages keep their samples insamples/: still read).- JumPHP's own seven (
particles,physics,shorts,effects,collision,dialogue,tiles) have both: trybin/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.
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 itstests/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:
- create the three empty public repositories
davidnurdin/jumphp-particles,jumphp-physics,jumphp-shorts; - 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; - run the workflow once (Actions > extensions-split > Run workflow, or the next
v*tag); - 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 = untilstop()),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;#rrggbbaafades),size([birth, death]),shape(circle/square),area(born in a box). - Deterministic: the same seed (project.yaml
particles: {seed: 7}, orreset(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')(namedEmitters). - 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.