# 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 own handler 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's data and is never published. ## Templates `Templates/.php`: `final class ` 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 does after 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 one Read 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 already decoded (a PHP literal) or by the Context call for that element, **in the same order** (an element's evaluation changes 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 check From the repository root: `games/alis/tools/compiled/check.sh [inputs] [edition] [groups]` replays a recorded session with the VM and with the compiled scripts and compares a checksum of the whole VM memory and registers at each picture (`same N pictures` = identical). Use `groups` = `Flow,Expressions,` to test only your 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 code of 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//compiled/`). ## Readable PHP, edited PHP `tools/compiled/readable.php ` writes every script of the game as a PHP class (`/.php`): each `case` is commented with its instruction as ALIS source (`Lang\Printer::texts()`), the variables named in `/names.json` or `/names/*.json` (`{"