FR
games/alis / docs / porting.md · commit 9c722cf
# ALIS C → PHP porting conventionsThe PHP port of the ALIS virtual machine (https://github.com/maestun/alis, MIT) lives in`games/alis/src/Alis/`. Every translator follows these rules so that files written separately fit together.Source: the C files preprocessed for the desktop SDL2 build (Atari-native, Falcon DSP, m68k, planarand 16-bpp-native branches already removed). Translate **what is there**, function by function, in the sameorder, keeping the C function names, local variable names and the original comments (shortened if huge).Faithfulness first: the VM must behave exactly like the C one. No "improvements".## 1. ScopePhase 1 (done): VM versions < 60 for every platform + the Robinson's Requiem DOS 3D renderer (`rrq3d.php`).Phase 2 (now): EVERYTHING else of the desktop SDL2 build — audio (audio.c, music_v0/1/2, emu2149, emu8950,the mixing of sys.c), films (video/: FLI/FLS/3DO cinepak), VM v6+ (Deus, RRQ 3DO, Time Warriors...: the `*_v6`functions, `version >= 60` branches, deus3d, rrq3d_3do), the 68k 3D back end (rrq3d_68k.c). Only theAtari-native / Falcon-DSP / m68k-assembly builds stay out (they are removed by the preprocessing anyway).Rules when several translators work at the same time on a shared code base:- Write your code in NEW files (`fn/<cfile>_v6.php`, `fn/audio.php`...). In existing files you may only (a) delete  the stub (`unsupported(...)`) of a function you now implement and (b) replace a stubbed call by the real call.  Use small exact Edit replacements, never rewrite or reformat a whole existing file (others edit it too).- Before adding a function, check it is not defined anywhere (`php games/alis/tools/undefined.php` lists  duplicates and missing functions; `grep -rn "function name(" games/alis/src/Alis/fn`).- Test what you can: `bin/jumphp php games/alis tools/run.php ../../.alis-data/robinson 3000 300 "700:m:100:60"`  runs Robinson's Requiem PC (VM v31) headless (see tools/run.php for clicks / keys / trace).## 2. Files and namespaces- One PHP file per C file, **plain namespaced functions** (no classes): `src/Alis/fn/<cfile>.php`  (`opcodes.c` → `fn/opcodes.php`, `audio/music_v1.c` → `fn/music_v1.php`), starting with  `<?php` + `namespace App\Alis;`. All function files share the namespace, so a C call `foo(x)` stays  `foo($x)`. They are loaded by composer `autoload.files` (`fn/_load.php` loads every file of the folder: never edit composer.json).- C function names are kept as is. Collisions (see the symbol index): `cscdark`, `ctexmap` exist in both  escnames.c and opcodes.c → the escnames.c ones become `esc_cscdark`, `esc_ctexmap`;  `update_output` in emuadpcm.c → `adpcm_update_output`.- **File-scope C variables** (static or not, from the symbol index) of `foo.c` become public static  properties of a class `FooVars` in `src/Alis/FooVars.php` (`opcodes.c` → `OpcodesVars`,  `audio/music_v2.c` → `MusicV2Vars`, `sys/sys.c` → `SysVars`), initialised with their C initial value  (constant tables as `const` arrays or static arrays). Exceptions — the VM singletons (already generated):  | C global | PHP |  |---|---|  | `alis.x` (sAlisVM) | `Alis::$x` |  | `image.x` (sImage) | `Img::$x` |  | `audio.x` (sAudio) | `Aud::$x` |  | `screen.x` (sScreen) | `Scr::$x` |  | `host.x` | `Host::$x` |  | `alis.platform.version` | `Alis::$platform->version` |  Nested C structs are PHP objects with public properties (classes generated from the C structs:  `ScriptLive`, `ScriptData`, `ScriptHeader`, `Sprite`, `Platform`, `MouseT`, `sChannel`, `sMV1Audio`...).  Anonymous nested structs (`alis.scrnode[i].node`) are PHP arrays: `Alis::$scrnode[$i]['node']`.- Enumerations and `#define` constants: `const` in `src/Alis/C.php` (class `C`): `C::EPlatformPC`,  `C::EGameIshar_1`, `C::kNameMaxLen`. Add the ones you need to **your own** constants class  `FooConst`-style if not in `C` (e.g. `OpcodesConst::kSomething`), never edit another translator's files.  Function-like macros become functions in your file (or use the ones of runtime.php).## 3. Integers (the browser runs 32-bit PHP!)PHP ints are 64-bit on the desktop and **32-bit in the browser**. Every value keeps its C type throughexplicit normalisation, using the helpers of `fn/runtime.php`:| C | PHP ||---|---|| `(u8)x`, store into u8 | `($x & 0xff)` || `(s8)x` | `s8($x)` || `(u16)x` | `($x & 0xffff)` || `(s16)x` | `s16($x)` || `(s32)x`, s32 arithmetic that may overflow (`a+b`, `a*b`, `a<<n` on 32-bit values) | `s32($x)`, `mul32($a, $b)`, `shl32($a, $n)` || `(u32)x` | same bits as s32: `s32($x)`; unsigned compare `ult($a, $b)` / `ule()`; unsigned shift right `shr32($a, $n)`; unsigned divide/modulo `udiv32()`, `umod32()` || `a / b` (ints) | `intdiv($a, $b)` (C truncates toward 0, so does intdiv) — guard `b == 0` like the C (which would crash): return 0 || `a % b` | `$a % $b` (same sign rule as C) || `x >> n` on a signed value | `$x >> $n` || `x >> n` on u16/u8 | mask first: `($x & 0xffff) >> $n` |- Never write an integer literal ≥ `0x80000000` (it is a float in 32-bit PHP): use `s32()` of a  smaller expression or the constants `U32_MASK` helpers (`and32()`), or negative literals  (`-0x80000000` is fine… on 64-bit only; prefer helpers).- Every C assignment to a typed variable / field normalises: `s16 a = b + c;` → `$a = s16($b + $c);`.  `u8 c = x;` → `$c = $x & 0xff;`. Skip it only when the value is provably in range.- Comparisons on unsigned types: values must be normalised to their unsigned range first (u8/u16 masks;  u32 via `ult()`). Implicit C promotions: `(s8)` byte compared with an int, etc. — reproduce exactly.- Booleans: C `if (x)` on an int → `if ($x)` works; `!x` → `!$x`; a C expression yielding 0/1 that is  stored into an int: `(int)($a < $b)`.## 4. Memory: one address space`Alis::$mem` is ONE binary string: the VM RAM (`alis.mem`, `ram_sz` bytes) **followed by the hostbuffers** that C allocates with malloc (screens `physic`/`logic`, background cache, `bufpack`, ...).So **every C pointer to bytes becomes an int offset into `Alis::$mem`** — `alis.mem + addr` is just`$addr`; `image.logic` is an int; `u8 *p = image.logic + y * w; *p++ = c;` →`$p = Img::$logic + $y * $w; Alis::$mem[$p++] = chr($c);`.Host buffers are allocated with `host_alloc($size)` (runtime.php) which returns the offset of a zeroedblock past the VM RAM (never freed; `host_free()` is a no-op).| C | PHP (runtime.php) ||---|---|| `xread8(o)` / `*(u8*)(alis.mem+o)` / `alis.mem[o]` | `xread8($o)` (u8) or `ord(Alis::$mem[$o])` || `(s8)xread8(o)` | `s8(xread8($o))` || `xread16(o)` (game endianness, returns **s16**) | `xread16($o)` || `xread32(o)` (game endianness, s32) | `xread32($o)` || `xwrite8/16/32(o, v)` | same names || `xadd8/16/32`, `xsub8/16/32` | same names || `read16(ptr)`, `read24`, `read32` (game endianness, unsigned) | `read16($o)`, `read24($o)`, `read32($o)` (u16, u24, s32-bits) || `read16be/le`, `read32be/le`, `swap16(ptr)`, `swap32(ptr)` | same names, taking an offset || `xswap16(v)` / `xswap32(v)` / `xswap16be` / `xswap32be` (values) | same names || `memcpy(alis.mem+d, alis.mem+s, n)` / `memmove` | `mem_move($d, $s, $n)` || `memset(alis.mem+d, v, n)` | `mem_set($d, $v, $n)` || `memcmp` | `mem_cmp($a, $b, $n)` || `strcpy(dst, src)` (both in mem) | `mem_strcpy($dst, $src)` || `strlen(p)` | `mem_strlen($p)` || C string at p → PHP string | `mem_str($p)` || PHP string → C string at p (with NUL) | `mem_putstr($p, $s)` || `script_read8/16/24/32()` (advance `alis.script->pc`) | same names (16 = **s16**? no: u16 like C; cast as C does) || `get_vram(off)` | `get_vram($off)` (offset) || `get_0x24_scan_inter(vram)` ... all `get_0x..`/`set_0x..` inline accessors of alis.h | same names || `get_scr_*`/`set_scr_*` of screen.h | same names |Return types follow C: `xread16` returns s16, `read16` u16, `xread32`/`read32` s32 bits.**Byte order**: `xread*/xwrite*/read*` use the GAME byte order (`Alis::$xle`). A plain C dereference ofa typed pointer into memory (`*(s16 *)(alis.mem + o)`, `*(u32 *)p`, `*alis.acc++`) uses the HOST order,which is little endian in the port: `hread8/hread16/hread32` (signed) and `hwrite8/16/32`.- `alis.acc` (s32 *) is an address in `Alis::$mem`: `alis.varD7 = *alis.acc++;` →  `Alis::$varD7 = hread32(Alis::$acc); Alis::$acc += 4;` and `*(--alis.acc) = v;` →  `Alis::$acc -= 4; hwrite32(Alis::$acc, $v);`.- `alis.ptrent` (s16 *) points into `alis.tablent`: it is an element index (`ptrent++` → `Alis::$ptrent++`,  `*alis.ptrent` → `Alis::$tablent[Alis::$ptrent]`).Pointers to things that are **not bytes**:- `sAlisScriptLive *`, `sAlisScriptData *` → the PHP objects (`ScriptLive`, `ScriptData`), `NULL` → `null`.- `sSprite *` → `Sprite` object. `SPRITE_VAR(x)` → `sprite_var($x)` (returns the Sprite for byte  offset `$x` of the sprite memory, created on first use; `null` when `$x == 0`). Each Sprite keeps its  offset in `->idx`. The 24-bit bitfields: `newad` (u24) and `newf` (s8) are separate properties, same for  `data` (u24) and `flaginvx` (u8). Byte-level access to sprite memory (`*(s16 *)(image.spritemem + i + 4)`):  translate to the field at that offset (see the sSprite layout in image.h).- Pointers to C locals / out-parameters (`u16 *curidx`, `s16 *x`) → PHP references (`&$curidx`).- Pointers into a PHP array (`s16 *p = image.tabfen; p++`) → an int index into that array.- `u32 *` palettes (`image.atpalet` points to `image.tpalet` or `image.mpalet`): store the property  name as a string (`Img::$atpalet = 'tpalet'`) and access with `Img::${Img::$atpalet}[$i]`.- Colours: palette entries are packed `0xRRGGBB` ints (**no alpha byte**, it would overflow 32-bit PHP);  `PAL_WRITE_DISPATCH(...)` becomes a plain write of `($r << 16) | ($g << 8) | $b`.- Function pointers / opcode tables (`sAlisOpcode table[] = { DECL_OPCODE(0x01, cnul, "...") }`) → PHP  arrays of callables `[cnul(...), ...]` built by a function `table_opcodes(): array` (first-class callable  syntax), plus a parallel array of names for debugging. Dispatch: `(Tables::$opcodes[$code])()`.- `FILE *` → PHP stream resource from `sys_fopen()`; use `fread/fwrite/fseek/ftell/fclose` (files are read-only  game data under the data folder; saves go through `sys_*` functions that use JumPHP storage).## 5. Control flow and blocking- `goto` is available in PHP (labels inside the function, not into loops) — keep it when the C uses it.- `switch` with fall-through works the same in PHP. `do { } while (0)` macros → plain blocks.- **Never block**: the VM runs one frame per call from the JumPHP scene. These C functions are  provided by the host layer (sys.php, written separately) and are **non-blocking**:  `sys_delay_loop()`, `sys_delay_frame()`, `sys_sleep_interactive()`, `sys_sleep_until_music_stops()`,  `sys_poll_event()` → just call them.- `io_getkey()` busy-waits in C (`getval`, `getstring` in opcodes.c): translate those two specially —  read keys with `io_inkey()` in a non-blocking way and, when Enter is not yet pressed, call  `vm_yield_retry()` (runtime.php) which rewinds the script to the start of the current opcode and stops  the frame; keep the partial text in `OpcodesVars`. Ask the integrator (leave a `// PORT:` comment) if  unsure.- `setjmp`/`longjmp` (v6 only) → dropped.## 6. Output format- Header of each file: `<?php`, blank, `namespace App\Alis;`, blank, a short comment  `// Port of alis/src/<file>.c (MIT, Olivier Huguenot, Vadim Kindl).`- Type declarations: parameters `int`, return `int`/`void`; no `declare(strict_types=1)`.- Debug prints (`ALIS_DEBUG`, `debug()`, `printf` of logs) → remove (NDEBUG). Keep `alis_error()` calls.- Leave `// PORT: ...` comments for anything you were unsure about, so the integrator can grep them.- PHP 8.2 syntax max. Must pass `php -l`.