jumPhp/games/hello-threads/AGENTS.md
David Nurdin fcb742b249 JumPHP 0.3.0: PHP 8.5; hot reload; the game on Google Play; the jumphp command for the whole system
- PHP 8.5 everywhere (desktop, relay, WebAssembly engine 8.5.12): php-sdl and php_glob patched, opcache JIT off
- hot reload of remote games (docs/hot-reload.md): assets in place, a scene entered again, or PHP restarted in
  the same engine (phpw_restart) in the scene that was playing; JumPHP\Scene\HotReloadable keeps its state
- what PHP writes goes to the page around the game (jumphp:output), phpinfo() as HTML
- bin/jumphp twa: the game as an Android app (Trusted Web Activity, Bubblewrap in Docker; docs/android.md)
- bin/jumphp cli:install: the jumphp command (tools/jumphp-cli), new projects, a question when Packagist has
  a newer JumPHP; offered by the wizard
- Testing\Game closes SDL before PHP ends (an intermittent crash at the end of the tests)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-29 22:17:30 +01:00

31 lines
1.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# hello-threads — notes for agents
This game is built with JumPHP. **Read `../../AGENTS.md` first** (rules, commands, API), especially the
"Threads" section.
## Checklist
```bash
bin/jumphp test hello-threads # lint + phpstan + headless smoke test (must pass)
bin/jumphp shot hello-threads 60 # title screen
JUMPHP_SCENE='App\Scene\FractalScene' bin/jumphp shot hello-threads 120 var/screenshots/play.png
JUMPHP_RUNTIME=default bin/jumphp test hello-threads # the same game without threads (fallback path)
bin/jumphp build hello-threads && bin/jumphp webshot hello-threads 12 '[[1,"Enter"]]' # browser (Web Workers)
```
## This game
- **What it is**: the "hello world" of `JumPHP\Async`. A Mandelbrot picture (192×144, 2500 iterations) is
computed row by row by a pool of worker threads, while the main thread keeps drawing at 60 FPS (the
turning bar proves it never stops). `M` computes the same picture on the main thread instead (4 ms per
frame) to compare the times.
- **Runtime**: `game.yaml runtime: async` → `bin/jumphp` uses the PHP 8.6 ZTS + TrueAsync image
(`docker/desktop-async`). In the browser the pool uses Web Workers (`Tasks::backend() === 'workers'`); on
the default PHP 8.5 runtime it runs the jobs between frames. The panel shows which backend runs.
- **Scenes**: `TitleScene` (menu) → `FractalScene` ; overlay `PauseScene`.
- **Thread code**: `src/Work/Fractal.php`, pure static code (excluded from the container in
`config/services.yaml`). Jobs are `static fn` with plain arguments; results are strings of iteration bytes,
drawn into the `fractal` texture in `FractalScene::flushRows()`.
- **Controls**: Space / Enter next spot, M (Tab) threads ↔ main thread, Escape pause.
- **Smoke test**: `FractalScene` with `demo: true` (goes to the next spot after each picture, alternating
threads and main thread).