JA
games/alis / tools / lang / vmdoc.php · commit 9c722cf
<?php// The technical documentation of the ALIS virtual machine (docs/vm.md, then the site's page through// tools/site/docs.php): one sheet per handler of the original DOS executable of Robinson's Requiem, from the audit// that compared each of them with the port (docs/vm/: audit-entries.json, sheets.json, confirmed.json).//   bin/jumphp php games/alis tools/lang/vmdoc.php$root = dirname(__DIR__, 2);$sheets = json_decode((string) file_get_contents("$root/docs/vm/sheets.json"), true);$entries = json_decode((string) file_get_contents("$root/docs/vm/audit-entries.json"), true);$confirmed = json_decode((string) file_get_contents("$root/docs/vm/confirmed.json"), true);/** opcodes | esc1 | opernames | storenames | addnames */function group_of(string $table): string{    return match (true) {        str_contains($table, 'esc1') => 'esc1',        str_contains($table, 'opername') || str_contains($table, '1884e') => 'opernames',        str_contains($table, '189ae') || str_contains($table, 'store') => 'storenames',        str_contains($table, '18a26') || str_contains($table, 'add') => 'addnames',        default => 'opcodes',    };}function code_of(string $index): string{    if (preg_match('/code (0x[0-9a-f]+)/i', $index, $m)) {        return strtolower($m[1]);    }    if (preg_match('/0x[0-9a-f]+/i', $index, $m)) {        return strtolower($m[0]);    }    return preg_match('/^[0-9a-f]+$/i', trim($index)) ? '0x' . strtolower(trim($index)) : trim($index);}$fixed = [];foreach ($confirmed as $c) {    $fixed[strtolower(explode(' ', $c['name'])[0])] = $c['severity'];}$titles = [    'opcodes' => ['Les instructions', 'Un octet de code par instruction, lu par la boucle de la machine (0x7b73 : `lodsb ; call [eax*4+0x18432]`).'],    'esc1' => ['Les échappements (`cesc1` + un octet)', 'L\'instruction 0x01 lit un second octet et saute dans cette table (0x18832).'],    'opernames' => ['Les éléments d\'expression', 'Les expressions sont des suites d\'éléments de code pair (`jmp [eax*2+0x1884e]`) : valeurs, variables, opérateurs, fonctions.'],    'storenames' => ['Les cibles de rangement', 'Où `cstore` range le résultat d\'une expression (table 0x189ae).'],    'addnames' => ['Les cibles d\'ajout', 'Où `cadd` / `csub` ajoutent ou retirent le résultat d\'une expression (table 0x18a26).'],];$rows = array_fill_keys(array_keys($titles), []);foreach ($sheets as $k => $s) {    $e = $entries[$k] ?? [];    $name = trim(explode(' ', (string) ($e['name'] ?? $s['name']))[0]);    $g = group_of((string) ($e['table'] ?? $s['table']));    $used = (string) ($e['used_by_game'] ?? '');    $usedN = preg_match('/^\s*~?(\d+)/', $used, $m) ? (int) $m[1] : 0;    $state = match (true) {        isset($fixed[strtolower($name)]) => 'corrigé',        ($e['status'] ?? '') === 'platform' => 'plateforme',        default => 'conforme',    };    $rows[$g][] = [code_of((string) ($e['index'] ?? $s['index'])), $name, (string) ($e['original_addr'] ?? ''), $usedN, $s['operands'], $s['effect'],        $state === 'corrigé' ? trim((string) preg_replace('/\s*(À|à) (corriger|aligner|implémenter)[^.]*\.?/u', '', (string) $s['port_note'])) : '', $state];}$counts = array_count_values(array_map(static fn ($r) => $r[7], array_merge(...array_values($rows))));$md = "# La machine virtuelle ALIS : documentation technique\n\n";$md .= "Robinson's Requiem est un ensemble de programmes pour la machine virtuelle ALIS de Silmarils. Cette page décrit chaque "    . "élément de cette machine **tel que l'exécutable DOS d'origine l'exécute** (`START.EXE` du CD, décompilé avec Ghidra), "    . "pour qui veut lire ou écrire des scripts ([le langage](language.md), [l'éditeur](editor.md)).\n\n";$md .= "Chaque traitement de l'original a été comparé à celui du moteur PHP : " . count($sheets) . " éléments, "    . ($counts['conforme'] ?? 0) . " conformes, " . ($counts['plateforme'] ?? 0) . " dont seule la plateforme diffère (carte son, "    . "ports VGA…), " . ($counts['corrigé'] ?? 0) . " corrigés après l'audit (la colonne « état » le dit, la note dit ce qui "    . "différait). « Utilisations » = combien de fois les 109 scripts du jeu s'en servent.\n\n";$md .= "L'exécutable : un extenseur DOS (Doug Huffman) puis un programme 32 bits à plat, écrit en assembleur ; la boucle de "    . "la machine lit un octet de code et appelle son traitement, le pointeur de programme est ESI, les variables du script "    . "courant sont en ES:EBP (adresses négatives : `vb[]`, `vw[]`…). Détails : `docs/vm/original-binary.md` du dépôt.\n\n";foreach ($titles as $g => [$title, $intro]) {    if ($rows[$g] === []) {        continue;    }    usort($rows[$g], static fn ($a, $b) => hexdec(substr($a[0], 2)) <=> hexdec(substr($b[0], 2)));    $md .= "## $title\n\n$intro\n\n| Code | Nom | Opérandes | Effet | Utilisations | État |\n|---|---|---|---|---|---|\n";    foreach ($rows[$g] as [$code, $name, $addr, $used, $ops, $effect, $note, $state]) {        $cell = static fn (string $t) => str_replace(['|', "\n"], ['\\|', ' '], trim($t));        $md .= "| `$code` | `$name` | " . $cell($ops) . ' | ' . $cell($effect) . ($note !== '' ? ' *Avant la correction : ' . $cell($note) . '*' : '')            . " | $used | $state |\n";    }    $md .= "\n";}file_put_contents("$root/docs/vm.md", $md);echo "docs/vm.md: " . count($sheets) . " entries\n";