PL
games/alis / src / Alis / Compiled / README.md · commit 9c722cf
# ALIS -> PHP: the compiled scripts`Compiler` turns a script loaded by the VM into a PHP class (`CompiledScript::run()`): each instruction becomes a`case` of its offset in the script, written by a **template**; an instruction without one is run by the VM's ownhandler at its address (`readexec_opcode()`), so the compiled code and the VM are interchangeable at every instruction(same memory `Alis::$mem`, same registers `Alis::$varD7` / `$varD6`, same string accumulators `Alis::$sd7` / `$sd6` /`$oldsd7`, same script stack, same `$s->pc` = absolute address). The generated PHP is made at load time from the game'sdata and is never published.## Templates`Templates/<Group>.php`: `final class <Group>` with `public static function register(): void` filling:- `Templates::$op['cname']` = `fn (array $i, Context $c): ?string` — an instruction (opcode names: `Lang/Grammar.php`  OPCODES). `$i` = the decoded instruction (`Lang/Decoder.php`): `at`, `end`, `op`, `ops` (operands: `['E', item]`  expression, `['S', item]` store target, `['A', item]` add target, `['b'|'w'|'W'|'l', int]`, `['z', bytes]`,  `['j', bits, target, pad]`, `['v', offset, long]`, `['r', bytes]`, and the specials of `Decoder::special()`).  Return PHP statements, or `null` to leave this instruction to the VM.- `Templates::$oper[code]` = `fn (array $item, Context $c): string` — an expression element (opernames, Grammar OPERS:  even codes). `$item` = `['c' => code, 'a' => its operand (already read), 'sub' => sub-items]`.- `Templates::$store[code]`, `Templates::$add[code]` — store targets (STORES) and add targets (ADDS), same shape.Inside the PHP you write, `$s` is the running script (`Alis::$script`, a `ScriptLive`), `$o` its address(`$s->data->data_org`); `Alis` is imported; call the VM's functions with their namespace (`\App\Alis\xread16(...)`,`\App\Alis\s16(...)`, `\App\Alis\put(...)`...). Before your instruction's PHP the compiler already did what the VM doesafter reading an instruction: `Alis::$opcode_pc = $s->pc` (its start) and `$s->pc = $o + end` (after its operands);a jump sets `$s->pc` again (`Context::go($target)`).`Context` gives the VM's evaluation steps, with the same effects in the same order as `fn/alis.php`:`opername($item)` (= `readexec_opername()`: the element then D7 as a signed 16-bit value), `opernameSaveD7($item)`(D6 = D7 first), `opernameSaveD6($item)`, `opernameSwap($item)` (sd7 / sd6 swapped first), `storename($item)`,`addname($item)`, `addnameSwap($item)`; `$c->tmp` for unique temporary variable names (`'$t' . (++$c->tmp)`).A missing element template throws `NoTemplate`: the whole instruction then goes to the VM (correct, just not native).## How to write oneRead the VM's handler (`fn/opcodes*.php`, `fn/opernames.php`, `fn/storenames.php`, `fn/addnames.php`, `fn/escnames.php`)and write its body again with every read of the script stream (`script_read8/16/32()`, `read_off24()`,`readexec_opername*()`, `readexec_storename()`, `readexec_addname*()`, string reads) replaced by the operand alreadydecoded (a PHP literal) or by the Context call for that element, **in the same order** (an element's evaluationchanges D6 / D7 / sd*: the order matters). Keep every other effect exactly (same calls, same globals, same version /platform tests). If a handler is not a thin wrapper, depends on reading the stream in a way the decoder does not give,loops on the stream, or you are not sure: return `null` (the VM runs it). Correct first, native second.## How to checkFrom the repository root: `games/alis/tools/compiled/check.sh <your-tag> [inputs] [edition] [groups]` replays arecorded session with the VM and with the compiled scripts and compares a checksum of the whole VM memory andregisters at each picture (`same N pictures` = identical). Use `groups` = `Flow,Expressions,<YourGroup>` to test onlyyour templates (plus the base ones). Sessions: `var/trace/20261114-183050/inputs.jsonl` (desktop, HD edition, 55 s,Socrate), `var/webtrace/inputs.jsonl` (browser, longer). Editions: `hd` (default), `source`, `original` (the byte codeof the .io files, no sources). Also `bin/jumphp test alis` must pass. How much is native: the "compiled scripts"line (`--compiled-dump` keeps the generated PHP in `games/alis/var/<out>/compiled/`).## Readable PHP, edited PHP`tools/compiled/readable.php <data> <out>` writes every script of the game as a PHP class (`<out>/<name>.php`): each`case` is commented with its instruction as ALIS source (`Lang\Printer::texts()`), the variables named in`<data>/names.json` or `<data>/names/*.json` (`{"<script>": {"0x62": "amazone"}, "main": {"0x1a9e": "..."}}`, `main`= the main script's globals, `_notes` ignored) are constants of the class (`$s->vram_org + self::AMAZONE`,`Alis::$basemain + self::MAIN_...`), and lines that change nothing are taken out (`Compiler::tidy()`).`tools/run.php --compiled-from=<out>` (and `check.sh <tag> <inputs> <edition> from:<out>`) runs the game with thesefiles instead of generating the PHP: a file is used when its class is the one of the loaded script (`S_<name>_<md5 ofits header and program>`), else it is generated again (logged). So the scripts can be rewritten by hand, a system at atime, and `check.sh` says whether the game is still the same (or shows where it changed, when that is the point).These files are made from the game's data: they stay with it (private), never in this repository.Coverage (Robinson's Requiem, 109 scripts): 37267 instructions in PHP, none left to the VM (the "PHP code" edition ofthe game runs them all as PHP; `readexec_opcode()` stays only as the fallback of templates that refuse another platform orversion). The recorded sessions run 17743 of them; the rare ones (Templates/Ops13.php, Ops14.php: shrink, chartmap, vinput,avmov, runfilm, defsc, defmap, setmap, putmap, ...) were written from the handlers without a replay that runs them.