winzik/docs/hot-reload.md
David Nurdin 8ceaad03c7 Apps in apps/ beside games/, config/project.yaml beside config/game.yaml (both read)
Apps, CLI apps, graphic apps and IDE plugins are made in apps/<id>; bin/jumphp, the tools, the
workflows, the IDE and the docs find a project in games/ or apps/. New projects get
config/project.yaml (under project:); the engine, bin/jumphp, the tools and the IDE still read
config/game.yaml (under game:). JUMPHP_APP is read before JUMPHP_GAME.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
2026-11-03 23:30:23 +01:00

43 lines
2.5 KiB
Markdown

# Hot reload (remote games in the browser)
A page that shows a remote game (`docs/remote.md`) in an iframe can push changed files into the running game
without reloading it. The JumPHP playground does it in its online editor and sandbox (⚡ Live).
## The protocol
1. The page saves the files where the game's manifest points (the manifest is asked for again, `no-store`).
2. It sends `{type: 'jumphp:hot'}` to the iframe (`iframe.contentWindow.postMessage(...)`).
3. The engine (`engine/web/jumphp.js`) fetches the manifest, writes the files whose hash changed into `/game`,
deletes the removed ones, and decides (`engine/src/Debug/HotReload.php`):
| What changed | What happens | `result` |
|---|---|---|
| nothing the game reads (`*.md`, `*.txt`, `tests/`, `site/`, `docs/`) | nothing | `assets` or `none` |
| pictures, sounds | reloaded in place (textures, sfx, the music played again) | `assets` |
| `config/lang.yaml`, `config/input.yaml` | translations, keys reloaded | `assets` |
| another data file (a level, a `.json`...) | the playing scene entered again, same parameters | `scene` |
| `*.php`, `project.yaml`, `services.yaml`, `composer.json` (namespaces) | PHP restarted in the same engine | `restart` |
4. It answers `{type: 'jumphp:hot-done', game, result, changed, message?}`; `result: 'error'` when the game
did not start again (`message`: PHP's error first). The next `jumphp:hot` tries again.
An engine older than 0.3.0 does not answer: after a few seconds without `jumphp:hot-done`, reload the iframe.
## The restart
`HotReload::save()` writes the playing scene, its parameters and, for a scene implementing
`JumPHP\Scene\HotReloadable`, its `hotState()` to `/tmp/jumphp-hot.json`; `HotReload::shutdown()` closes the
sound, the network and SDL. Then `phpw_restart()` (`docker/engine-wasm/source/phpw.c`) ends the PHP request and
starts a new one in the same WebAssembly instance: no download, no compilation, the canvas kept. The boot
(`Engine`) finds the saved scene (`HotReload::pending()`), starts it instead of the start scene, then calls
`hotRestore()` with the state. A boot that fails (a syntax error) leaves the engine waiting for the next files.
```php
final class PlayScene extends AbstractScene implements HotReloadable
{
public function hotState(): array { return ['room' => $this->room, 'score' => $this->score]; }
public function hotRestore(array $state): void { ['room' => $this->room, 'score' => $this->score] = $state; }
}
```
Plain values only: they cross from one version of the code to the next (JSON).