1:1 source port of the engine and game code; Windows build and system layer; docs. No game files or SDK headers.

This commit is contained in:
CRTkafa 2026-10-22 16:30:40 +08:00
parent c3b032a45a
commit 0ecb47e9cb
3871 changed files with 91080 additions and 1640063 deletions

279
tools/port/emu.py Normal file
View file

@ -0,0 +1,279 @@
"""Run functions of the shipped i386 game binary in an x86 emulator (Unicorn) for differential tests.
The Mach-O segments are mapped at their original addresses. Imported library functions (the __jump_table stubs)
are served by small Python implementations (malloc, string functions, operator new/delete...). An unknown import
stops the run with a clear error so tests never silently use a wrong stand-in.
from emu import Game
g = Game()
s = g.new(4) # emulated memory for a `str`
g.call('__ZN3strC1EPKc', s, g.cstr('Hello')) # str::str(const char*)
g.call('__ZNK3str6lengthEv', s) # -> 5
"""
import os
import re
import struct
import subprocess
from unicorn import Uc, UC_ARCH_X86, UC_MODE_32, UC_HOOK_CODE, UcError
from unicorn.x86_const import UC_X86_REG_EAX, UC_X86_REG_EDX, UC_X86_REG_ESP, UC_X86_REG_EIP, UC_X86_REG_FP0
BINARY = os.path.expanduser("~/Library/Application Support/Steam/steamapps/common/Chocolatier Decadence by Design/"
"chocolatier-decadence-design.app/Contents/MacOS/chocolatier-decadence-design")
STACK_TOP = 0xF0000000
STACK_SIZE = 0x100000
HEAP_BASE = 0x40000000
HEAP_SIZE = 0x4000000
RETURN_SENTINEL = 0xE0000000
class EmuError(Exception):
pass
# Extra import stubs live in tools/port/emu_stubs/*.py as functions named like the import symbol
# (e.g. `def _vsnprintf(g): ...`), so parallel work never edits this file. Each receives the Game and must
# finish with g._ret(value).
EXTRA_STUBS = {}
def _load_extra_stubs():
import glob, importlib.util, os
for path in sorted(glob.glob(os.path.join(os.path.dirname(os.path.abspath(__file__)), 'emu_stubs', '*.py'))):
spec = importlib.util.spec_from_file_location('emu_stub_' + os.path.basename(path)[:-3], path)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
for key, value in vars(mod).items():
# import symbols start with '_' (C) or '__Z' (C++); skip Python dunders only
if key.startswith('_') and callable(value) and not (key.startswith('__') and key.endswith('__')):
EXTRA_STUBS[key] = value
_load_extra_stubs()
class Game:
def __init__(self, binary=BINARY):
self.binary = binary
self.uc = Uc(UC_ARCH_X86, UC_MODE_32)
self.data = open(binary, 'rb').read()
self._map_segments()
self._load_symbols()
self._load_imports()
self.uc.mem_map(STACK_TOP - STACK_SIZE, STACK_SIZE + 0x1000)
self.uc.mem_map(HEAP_BASE, HEAP_SIZE)
self.uc.mem_map(RETURN_SENTINEL & ~0xfff, 0x1000)
self.heap_next = HEAP_BASE
self.blocks = {}
self.uc.hook_add(UC_HOOK_CODE, self._on_stub, begin=self.jump_lo, end=self.jump_hi)
# ---- loading -------------------------------------------------------------------------------------------
def _map_segments(self):
out = subprocess.run(['otool', '-arch', 'i386', '-l', self.binary], capture_output=True, text=True).stdout
self.segments = []
for m in re.finditer(r'cmd LC_SEGMENT\n.*?segname (\S+)\n\s+vmaddr (0x[0-9a-f]+)\n\s+vmsize (0x[0-9a-f]+)\n'
r'\s+fileoff (\d+)\n\s+filesize (\d+)', out, re.S):
name, vmaddr, vmsize, fileoff, filesize = m.group(1), int(m.group(2), 16), int(m.group(3), 16), \
int(m.group(4)), int(m.group(5))
if vmsize == 0 or name == '__PAGEZERO':
continue
self.uc.mem_map(vmaddr, (vmsize + 0xfff) & ~0xfff)
if filesize:
self.uc.mem_write(vmaddr, self.data[fileoff:fileoff + filesize])
self.segments.append((name, vmaddr, vmsize))
js = re.search(r'sectname __jump_table\n\s+segname \S+\n\s+addr (0x[0-9a-f]+)\n\s+size (0x[0-9a-f]+)', out)
self.jump_lo = int(js.group(1), 16)
self.jump_hi = self.jump_lo + int(js.group(2), 16)
def _load_symbols(self):
out = subprocess.run(['nm', '-arch', 'i386', self.binary], capture_output=True, text=True).stdout
self.symbols = {}
for line in out.splitlines():
parts = line.split()
if len(parts) == 3:
self.symbols.setdefault(parts[2], int(parts[0], 16))
def _load_imports(self):
out = subprocess.run(['otool', '-arch', 'i386', '-Iv', self.binary], capture_output=True, text=True).stdout
self.stubs = {}
section = None
for line in out.splitlines():
if line.startswith('Indirect symbols for'):
section = line
continue
m = re.match(r'(0x[0-9a-f]+)\s+\S+\s+(\S+)', line)
if m and section and '__jump_table' in section:
self.stubs[int(m.group(1), 16)] = m.group(2)
# ---- memory helpers ------------------------------------------------------------------------------------
def malloc(self, size):
size = max(16, (size + 15) & ~15)
addr = self.heap_next
self.heap_next += size + 16
if self.heap_next > HEAP_BASE + HEAP_SIZE:
raise EmuError('emulated heap exhausted')
self.uc.mem_write(addr, b'\0' * size)
self.blocks[addr] = size
return addr
def new(self, size):
return self.malloc(size)
def cstr(self, s):
b = s.encode('latin1') if isinstance(s, str) else s
a = self.malloc(len(b) + 1)
self.uc.mem_write(a, b + b'\0')
return a
def read_cstr(self, addr, limit=1 << 20):
out = bytearray()
while len(out) < limit:
chunk = self.uc.mem_read(addr + len(out), 64)
z = chunk.find(b'\0')
if z >= 0:
out += chunk[:z]
return bytes(out)
out += chunk
raise EmuError('unterminated string')
def u32(self, addr):
return struct.unpack('<I', self.uc.mem_read(addr, 4))[0]
def w32(self, addr, value):
self.uc.mem_write(addr, struct.pack('<I', value & 0xffffffff))
# ---- imports -------------------------------------------------------------------------------------------
def _args(self, n):
esp = self.uc.reg_read(UC_X86_REG_ESP)
return [self.u32(esp + 4 + 4 * i) for i in range(n)]
def _ret(self, value=0):
esp = self.uc.reg_read(UC_X86_REG_ESP)
ret = self.u32(esp)
self.uc.reg_write(UC_X86_REG_EAX, value & 0xffffffff)
self.uc.reg_write(UC_X86_REG_ESP, esp + 4)
self.uc.reg_write(UC_X86_REG_EIP, ret)
def _on_stub(self, uc, address, size, user):
name = self.stubs.get(address)
if name is None:
return
impl = getattr(self, 'imp' + name, None)
if impl is None and name in EXTRA_STUBS:
impl = lambda: EXTRA_STUBS[name](self)
if impl is None:
uc.emu_stop()
self.error = EmuError(f'unimplemented import {name} called')
return
impl()
def imp_malloc(self):
(n,) = self._args(1); self._ret(self.malloc(n))
def imp__Znwm(self):
self.imp_malloc()
def imp__Znam(self):
self.imp_malloc()
def imp_free(self):
self._ret(0)
def imp__ZdlPv(self):
self._ret(0)
def imp__ZdaPv(self):
self._ret(0)
def imp_strlen(self):
(s,) = self._args(1); self._ret(len(self.read_cstr(s)))
def imp_strdup(self):
(s,) = self._args(1); self._ret(self.cstr(self.read_cstr(s)))
def imp_strcmp(self):
a, b = self._args(2)
x, y = self.read_cstr(a) + b'\0', self.read_cstr(b) + b'\0'
# Darwin libc returns the difference of the first differing bytes (as unsigned char).
for i in range(min(len(x), len(y))):
if x[i] != y[i]:
self._ret(x[i] - y[i]); return
self._ret(0)
def imp_strcpy(self):
d, s = self._args(2); self.uc.mem_write(d, self.read_cstr(s) + b'\0'); self._ret(d)
def imp_strcat(self):
d, s = self._args(2)
self.uc.mem_write(d + len(self.read_cstr(d)), self.read_cstr(s) + b'\0'); self._ret(d)
def imp_strncpy(self):
d, s, n = self._args(3)
src = self.read_cstr(s)[:n]
self.uc.mem_write(d, src + b'\0' * (n - len(src))); self._ret(d)
def imp_memcpy(self):
d, s, n = self._args(3)
if n:
self.uc.mem_write(d, bytes(self.uc.mem_read(s, n)))
self._ret(d)
def imp_memmove(self):
self.imp_memcpy()
def imp_memset(self):
d, c, n = self._args(3)
if n:
self.uc.mem_write(d, bytes([c & 0xff]) * n)
self._ret(d)
def imp_atoi(self):
(s,) = self._args(1)
m = re.match(rb'\s*([+-]?\d+)', self.read_cstr(s))
v = int(m.group(1)) if m else 0
# Darwin atoi is (int)strtol: saturates at LONG_MIN/LONG_MAX on i386
self._ret(max(-0x80000000, min(0x7fffffff, v)))
def imp___toupper(self):
(c,) = self._args(1)
c = c & 0xffffffff
self._ret(c - 32 if 97 <= c <= 122 else c)
def imp___tolower(self):
(c,) = self._args(1)
self._ret(c + 32 if 65 <= c <= 90 else c)
imp_toupper = imp___toupper
imp_tolower = imp___tolower
# ---- calls ---------------------------------------------------------------------------------------------
def addr(self, name):
if isinstance(name, int):
return name
if name in self.symbols:
return self.symbols[name]
raise EmuError(f'unknown symbol {name}')
def call(self, name, *args, max_insns=50_000_000):
target = self.addr(name)
esp = STACK_TOP - 0x100
for a in reversed(args):
esp -= 4
self.w32(esp, a)
esp -= 4
self.w32(esp, RETURN_SENTINEL)
self.uc.reg_write(UC_X86_REG_ESP, esp)
self.error = None
try:
self.uc.emu_start(target, RETURN_SENTINEL, count=max_insns)
except UcError as e:
raise EmuError(f'{name}: {e} at eip=0x{self.uc.reg_read(UC_X86_REG_EIP):08x}')
if self.error:
raise self.error
if self.uc.reg_read(UC_X86_REG_EIP) != RETURN_SENTINEL:
raise EmuError(f'{name}: did not return (instruction limit)')
return self.uc.reg_read(UC_X86_REG_EAX)
def call_signed(self, name, *args):
v = self.call(name, *args)
return v - (1 << 32) if v & 0x80000000 else v