# ALIS C → PHP porting conventions The 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, planar and 16-bpp-native branches already removed). Translate **what is there**, function by function, in the same order, 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. Scope Phase 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 the Atari-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/_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/.php` (`opcodes.c` → `fn/opcodes.php`, `audio/music_v1.c` → `fn/music_v1.php`), starting with `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 through explicit 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 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 host buffers** 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 zeroed block 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 of a 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: `.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`.