# alis — notes for agents This game is built with JumPHP. **Read `../../AGENTS.md` first** (rules, commands, API), then **`docs/porting.md`** (the C → PHP conventions of this port). ## What it is A PHP port of ALIS, the virtual machine of the Silmarils games (https://github.com/maestun/alis, MIT, Olivier Huguenot & Vadim Kindl). It plays the ORIGINAL data files of the games, which are never in git: `data//` (ignored), private files on the playground. ## Layout - `src/Alis/fn/*.php` — the VM: one file per C file, plain functions with the C names (loaded by `fn/_load.php`). `runtime.php` (C integer semantics, unified memory `Alis::$mem`, script reads), `accessors.php` (generated), `sys.php` + `host.php` (host layer: input snapshot, BMP frame, files/saves through JumPHP storage), `sys_audio.php` + `audio.php` + `music_v0/1/2.php` + `emu2149.php` / `emu8950*.php` (sound). - `src/Alis/*.php` — global state (Alis, Img, Aud, Scr, Host: generated from the C structs), `*Vars` (file-scope C variables), `Machine.php` (the resumable per-frame main loop: no Fibers in the browser). - `src/Scene/TitleScene.php` (game list from data/), `PlayScene.php` (runs the VM, draws the frame + cursor). - `tools/run.php` — headless runner: `bin/jumphp php games/alis tools/run.php ../../.alis-data/robinson 3000 300 "700:m:100:60" [traceCycles]` (BMP frames in var/run/, `opened.txt` = data files read, trace.txt = opcodes). `tools/undefined.php` lists called-but-undefined functions. `tools/port/` = the scripts that preprocess the C and generate the state classes. ## Status - The whole desktop SDL2 build of alis is ported (~49 000 lines of PHP): VM v0..v31 and v6+ (Deus, RRQ 3DO...), 2D rendering of every platform, the RRQ 3D renderer (DOS, 68k, 3DO), Deus 3D, films (FLI/FLC, FLS HAM6 / S512, 3DO cinepak), audio (samples, MV0/MV1/MV2 music, YM2149 PSG, OPL2 emu8950 — bit-exact with the C emulators). - Validated on Robinson's Requiem PC CD (VM v31): films, intro, title, menu, 3D game with walking, sound — on 64-bit and 32-bit PHP (identical frames) and in the browser. v6 / Deus / 3DO / Atari-Amiga 3D are written from the C but untested (no data here). - Sound: `audio_mix()` (fn/sys_audio.php) → `$engine->pcm()` (PcmStream, JumPHP >= 0.5.54; older engines: the mixer runs silently at real-time pace). - Data: `data//` (git-ignored; on the playground: private files `data//...`, preloaded). The big files listed in `catalog/.json` ("lazy", made by `tools/catalog.php`) are private files `lazy//...`, downloaded when the VM opens them (`sys_lazy_file()`: the opcode is retried until the file is there). A developer's full copy in `../../.alis-data//` is used instead on the desktop. - Keys: Pause / F10 back to the game list; F11 / F12 save / load state (as the C SDL build). - Site: `site/` (fr + en), pictures made by `tools/site/shots.sh` from real runs. - **ALIS source language** (`docs/language.md`, `src/Alis/Lang/`): the scripts decompiled into readable source (`tools/lang/decompile.php /src`: `.als` + `.res`, byte-exact round trip checked) and compiled back by the engine itself: the " - ALIS sources" and " HD" editions of the game list (`SysVars::$sourceDir`, `sys_source_io()`). The grammar (`Grammar.php`) is checked against a real run by `tools/lang/check.php` (`tools/run.php` trace, 5th argument). The sources come from the game data: private files. - A second `Machine::boot()` in one process resets every state class first (`Machine::resetState()`): back to the list and another game / edition. - **HD edition** (`edition: hd`, `src/Hd/HdRenderer.php`): (1) the picture scaled by a GPU post shader as sharp pixels (each pixel a square, its border mixed over one screen pixel; xBR smeared the dithered pictures); (2) the texts: `put_char()` marks the elements it puts (`Sprite::$hdChar`), `destofen()` notes the glyph's pixels and puts the frame back as it was (`fn/hd.php`, `SysVars::$hdGlyphs` → `$hdShown` at `sys_render()`, dropped when a `fenetre()` redraw does not draw them again or the pixels under them change), and an overlay draws them after the filter with `assets/fonts/hd.ttf` (Lato Bold, OFL) at the window's resolution; (3) the 3D: `affiland()` runs the land pipeline a second time at twice the resolution (`fn/hd3d.php`, `App\Alis\Hd3d`): the VM state before / after the game's own frame is kept (Img / Rrq3dVars statics, sprites, the scene's and the render context's memory), the scene's screen doubled (viewport at 0,0, centre 0xa/0xc made relative, lens), its buffer / row table / altitude and slope tables replaced by host blocks; the sky is drawn with doubled pixels (`hd3d_sky()`); `hd3d_shown()` keys out the pixels the VM drew over the land. `tools/run.php ... --hd` (glyphs JSON) / `--hd3d` (land BMP) / `--hd3d-debug` (checks that the pass leaves the VM state unchanged) / `--hd3d-scale=1` (the pass at the game's scale must give back the game's own land: compare land-*.bmp with the frames). The pass reuses the game's tables (made once by openland(), with the lens of that moment): the altitude table scaled (rc-0x262 / rc-0x2c8, depths, unchanged), the projection scales 0x76 / 0x7a and their copies scaled. The HD pass draws only the sprites the game's own land drew (`Hd3d::$drawn`, recorded by zoomtofen() between hd3d_begin() and hd3d_low(); landtofi() adds to the set): far objects the game does not show were projected by the pass into the sky (a bush floating, a walker coming closer). `--hd3d-all-sprites` (run.php) draws them all again and writes the HD lands where it matters in var//skip/. spritland() in the HD pass projects again the sprites of state 0 (projected by the game earlier, not moved since: their newx / newy / zoom are the game's): else a partial redraw (landtofi) put them at half size, higher (Socrate twice, the second one up in the air). The land is drawn by affiland() AND by landtofi() (a partial redraw under a sprite that left: Socrate walking away after a talk): both run the pass, else the HD land of before stays over a changed screen (the "flicker"). - HD pass cost: `Hd3d::$budget` (0.75): when the passes take more than that share of the game's time over 2 s (the browser: ~95 ms a pass for the big view), that view size is "slow" (`Hd3d::$slow`, console "ALIS HD 3D: ..."): the game's own land while it moves (the HD land of before stays where the land did not change: hd3d_shown() keys the rest; a new land never blanks it, or a character walking away made HD / game / HD blink), and one deferred pass (`Hd3d::$pending`, `hd3d_deferred()` from sys_render) once the land stayed the same `Hd3d::STILL` s. A land identical to the last HD one reuses it (no pass). `--hd3d-budget=0.01` (run.php) plays a slow computer; `--hd3d-debug` checks every pass (deferred ones too) leaves the VM state as it was. The DOS land renderer's hot functions (doland_dos, barland_dos, tbarland_dos, bartra_dos) have xread16 / xwrite16 / s16 written out (`$__m`): the same pixels (replay's hd.log identical), fewer calls. `--hd3d-compare` (run.php): each HD land halved against the game's land. - Films in the game (Socrate's talk): a 320x200 FLC framed for the game's view (the picture in the 3D window, the rest black) with a whole palette whose unused entries are VGA's defaults. fli_next() copies the frame only where it has a picture (`FilmVars::$box`, grown frame after frame) and gives the palette entries the film does not use their game colours back (`FilmVars::$gamePal` / `$gameDpal`, taken by inifilm()): the interface around stays, in its colours (copying the whole frame blacked it out on both pages and the game never draws all of it again). - Loading online: the files on demand come from the externals, every block cached by the browser for good (`?v=` version, `&r=` one cache entry per range); PlayScene lists the game's folder once (no ~stat per file opened); 6 parts / requests at a time. `App\Alis\Prefetch`: in the background, while the game waits for nothing, the small files (whole game if <= 64 MB, else files <= 1 MB, sources first) read part by part into the browser's HTTP cache (not IndexedDB: in memory), remembered in alis-prefetch-.json (never asked again). - The original VM (docs/vm/): START.EXE decompiled (Ghidra headless, the 32-bit flat image = the second MZ load module from +0x4290, dispatch tables 0x18432 opcodes / 0x18832 esc1 / 0x1884e opernames (code/2) / 0x189ae storenames / 0x18a26 addnames; notes in docs/vm/original-binary.md). 405 handlers audited against the port, 35 differences fixed (2026-11-15). The site's technical page site/vm/ comes from docs/vm.md, made by tools/lang/vmdoc.php from docs/vm/{sheets,audit-entries,confirmed}.json, then tools/site/docs.php. - ALIS -> PHP compiler (src/Alis/Compiled/, README.md there): a loaded script becomes a PHP class (one `case` per instruction offset, Templates/.php per group of opcodes / expression elements / store and add targets); an instruction without a template is run by the VM at its address, so both are interchangeable. Off by default (`Compiler::$on`; tools/run.php --compiled / --compiled-dump / --compiled-only=Groups). 75% of the instructions run as PHP (2026-11-15); tools/compiled/check.sh compares VM vs compiled (checksum of the whole VM memory per picture: identical on both recorded sessions and the three editions). No speed gain: the drawing costs, not the VM. The generated PHP comes from the game's data: made at load time, never committed. - Debugging a real session in the browser: a local build (`bin/jumphp build alis`, served with the lazy files at /alis/play/private/lazy//), `JumPHP.php("\\App\\Alis\\Trace::$force = true;")` before starting the edition; the trace has the draws (pages, windows, interface checksum per page) and the films (Trace::event()). - Debugging a real session: `touch games/alis/var/trace.on`, `bin/jumphp run alis`, play, quit: `var/trace/