NL
games/alis / AGENTS.md · commit 9c722cf
# alis — notes for agentsThis 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 isA 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/<game>/` (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/<game>/` (git-ignored; on the playground: private files `data/<game>/...`, preloaded). The big files  listed in `catalog/<game>.json` ("lazy", made by `tools/catalog.php`) are private files `lazy/<game>/...`,  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/<game>/` 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 <data> <data>/src`: `<name>.als` + `<name>.res`, byte-exact round trip checked) and  compiled back by the engine itself: the "<game> - ALIS sources" and "<game> 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/<out>/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-<game>.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/<Group>.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/<game>/), `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/<time>/`  (`App\Alis\Trace`): inputs.jsonl (every update: dt, msec, keys, mouse, pad, audio mixed), hd.log (each HD pass,  each picture: HD land shown or why not), BMPs at each HD on/off change. Replayed headless, deterministic:  `tools/run.php data/robinson 1 0 '' --source --hd --hd3d --replay=var/trace/<time>/inputs.jsonl`.- "Skip intro" (`App\Alis\IntroSkip`, PlayScene's button): Escape pressed again and again during the films and  the rest of the introduction (phase from SysVars::$opened: flags.io … baratine … newprefs/prefs); never on the  flags. `tools/run.php ... --skip-intro`. Shift held while moving = run (the joystick's fire bit with a direction).- `tools/run.php ... --watch=0x184c` prints a byte of the main script's variables when it changes.- **ALIS editor** (`docs/editor.md`): `src/Scene/EditorScene.php` (home screen "<GAME> - ALIS EDITOR"; drawn in an  overlay at the window's resolution, `assets/fonts/mono.ttf` = DejaVu Sans Mono), `src/Editor/` (SourceBuffer:  text / undo / find; Highlighter; SourceStore: originals + the player's versions in storage  `alis-src-<game>-<script>.als`, used by `sys_source_io()` when `SysVars::$sourceGame` is set). F5 / F6 play the  source / HD edition (`back: editor`: F10 returns to the editor). Tests: `tests/EditorTest.php`.- Site pages of the docs: `tools/site/docs.php` turns `docs/language.md` + `docs/editor.md` into `site/langage/`,  `site/editeur/`, `site/en/language/` (re-run it when they change).- Headless runs of `tools/run.php` are NOT deterministic (two identical runs diverge around frame 45000): do not  read a difference there as a bug of the HD pass.- **ALIS 90 form** (`src/Alis/Lang/Human.php`, docs/language.md "Le format 90"): the same scripts in a 90s studio  language (French words, `variables … fin_variables` declarations, `si … alors … sinon … finsi`, `$hex`, `:=`).  A word-for-word translation both ways (`toHuman()` / `toCanonical()`): `tools/lang/human.php <src> [out]` checks  the round trip of every script (109/109 identical). `Human::compile()` compiles either form (sys_source_io(), the  editor's SourceStore); errors give the human file's line. Names the decompiler cannot know: `Human::KNOWN`  (main variables) / `KNOWN_LOCAL` (per script) — add names there as their role is found. The editor shows the 90  form (F2: the next form; option `alis_editor_form`). Word tables for the doc: `tools/lang/human-reference.php`.- **ALIS BASIC** (`src/Alis/Lang/Basic.php`, docs/language.md "ALIS BASIC"): the scripts as Silmarils' developers  most likely wrote them on the Atari ST (the original opcode names are GFA BASIC words: locate, tab, dim, plot,  box, ink...): the machine's words in capitals, `IF … ELSE … ENDIF`, `WHILE … WEND`, `GOSUB`, `SELECT/CASE`,  `ADD x, n`, `&H`, `'`, typed variables (`|` `&` `$` `%`) declared `LOCAL / GLOBAL / FIELD [DIM|ZONE] name AT &H..`,  `V:zone`, `=` a store at the head of a line else a comparison. `ACTOR "x"` marks the file. Word for word both ways,  `tools/lang/basic.php <src> [out]` (109/109). `Lang\Forms`: which form a text is, canonical(), to($form);  `Human::compile()` compiles all three. Editor F2: 90 → BASIC → machine.