3146 lines
No EOL
116 KiB
Python
3146 lines
No EOL
116 KiB
Python
from __future__ import annotations
|
||
|
||
import argparse
|
||
import ast
|
||
import csv
|
||
import hashlib
|
||
import json
|
||
import re
|
||
from functools import lru_cache
|
||
from dataclasses import dataclass
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
|
||
REPO_ROOT = Path(__file__).resolve().parents[1]
|
||
EXTRACTED_ROOT = REPO_ROOT / "USECODE" / "EUSECODE_extracted"
|
||
CLASS_EVENT_INDEX = EXTRACTED_ROOT / "class_event_index.tsv"
|
||
CLASS_LAYOUT_INDEX = EXTRACTED_ROOT / "class_layout_index.tsv"
|
||
RUNTIME_VM_IR_INDEX = EXTRACTED_ROOT / "runtime_vm_ir.tsv"
|
||
CHUNKS_DIR = EXTRACTED_ROOT / "chunks"
|
||
UNKCOFFS_DIR = REPO_ROOT / "tools" / "unkcoffs"
|
||
DEFAULT_GAME_VARIANT = "regret"
|
||
INTRINSIC_HINT_PATHS = {
|
||
"regret": UNKCOFFS_DIR / "regret_ints.py",
|
||
"remorse": UNKCOFFS_DIR / "remorse_ints.py",
|
||
}
|
||
|
||
|
||
def resolve_extracted_root(extracted_root: Path | str | None = None) -> Path:
|
||
if extracted_root is None:
|
||
return EXTRACTED_ROOT
|
||
return Path(extracted_root)
|
||
|
||
|
||
def extracted_root_paths(extracted_root: Path | str | None = None) -> tuple[Path, Path, Path, Path]:
|
||
root = resolve_extracted_root(extracted_root)
|
||
return (
|
||
root / "class_event_index.tsv",
|
||
root / "class_layout_index.tsv",
|
||
root / "runtime_vm_ir.tsv",
|
||
root / "chunks",
|
||
)
|
||
|
||
|
||
def repo_relative_path(path: Path) -> str:
|
||
try:
|
||
return str(path.relative_to(REPO_ROOT)).replace("\\", "/")
|
||
except ValueError:
|
||
return str(path).replace("\\", "/")
|
||
|
||
|
||
def infer_flex_path(extracted_root: Path | str | None = None) -> str:
|
||
root = resolve_extracted_root(extracted_root)
|
||
parent = root.parent
|
||
if parent == REPO_ROOT:
|
||
return "EUSECODE.FLX"
|
||
return f"{repo_relative_path(parent)}/EUSECODE.FLX"
|
||
|
||
|
||
EVENT_NAME_HINTS = {
|
||
0x00: "look",
|
||
0x01: "use",
|
||
0x02: "anim",
|
||
0x03: "setActivity",
|
||
0x04: "cachein",
|
||
0x05: "hit",
|
||
0x06: "gotHit",
|
||
0x07: "hatch",
|
||
0x08: "schedule",
|
||
0x09: "release",
|
||
0x0A: "equip",
|
||
0x0B: "unequip",
|
||
0x0C: "combine",
|
||
0x0D: "func0D",
|
||
0x0E: "calledFromAnim",
|
||
0x0F: "enterFastArea",
|
||
0x10: "leaveFastArea",
|
||
0x11: "cast",
|
||
0x12: "justMoved",
|
||
0x13: "avatarStoleSomething",
|
||
0x14: "animGetHit",
|
||
0x15: "func15",
|
||
0x16: "func16",
|
||
0x17: "func17",
|
||
0x18: "func18",
|
||
0x19: "func19",
|
||
0x1A: "func1A",
|
||
0x1B: "func1B",
|
||
0x1C: "func1C",
|
||
0x1D: "func1D",
|
||
0x1E: "func1E",
|
||
0x1F: "func1F",
|
||
}
|
||
|
||
|
||
# Intrinsic table extracted from Pentagram ConvertUsecodeCrusader.h
|
||
# Source note: "current discovered intrinsics are for regret1.21 only"
|
||
# This is used as a hint only – ordinal mapping may differ between builds.
|
||
BASE_INTRINSIC_HINTS: dict[int, str] = {
|
||
0x0000: "Intrinsic0000()",
|
||
0x0001: "Item::getFrame(void)",
|
||
0x0002: "Item::setFrame(uint16)",
|
||
0x0003: "Item::getMapNum(void)",
|
||
0x0004: "Item::getStatus(void)",
|
||
0x0005: "Item::orStatus(sint16)",
|
||
0x0006: "Item::callEvent0A(sint16)",
|
||
0x0007: "Intrinsic0007()",
|
||
0x0008: "Item::isNpc(void)",
|
||
0x0009: "Item::getZ(void)",
|
||
0x000A: "Intrinsic000A()",
|
||
0x000B: "Item::getQLo(void)",
|
||
0x000C: "Item::destroy(void)",
|
||
0x000D: "Intrinsic000D()",
|
||
0x000E: "Item::getX(void)",
|
||
0x000F: "Item::getY(void)",
|
||
0x0010: "Intrinsic0010()",
|
||
0x0011: "Item::getType(void)",
|
||
0x0012: "Intrinsic0012()",
|
||
0x0013: "Intrinsic0013()",
|
||
0x0014: "Item::legal_create(uint16,uint16,uint16,uint16,uint16)",
|
||
0x0015: "Item::andStatus(void)",
|
||
0x0016: "Intrinsic0016()",
|
||
0x0017: "Intrinsic00C3()",
|
||
0x0018: "Intrinsic00DA()",
|
||
0x0019: "Intrinsic0019()",
|
||
0x001A: "Item::create(uint16,uint16)",
|
||
0x001B: "Item::pop(uint16,uint16,uint8)",
|
||
0x001C: "Intrinsic00FA()",
|
||
0x001D: "Item::push(void)",
|
||
0x001E: "Intrinsic001E()",
|
||
0x001F: "Item::getQLo(void)",
|
||
0x0020: "Item::setQLo(sint16)",
|
||
0x0021: "Item::getQHi(void)",
|
||
0x0022: "Item::setQHi(sint16)",
|
||
0x0023: "Intrinsic0023()",
|
||
0x0024: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0025: "Item::getCY(void)",
|
||
0x0026: "Item::getCX(void)",
|
||
0x0027: "Intrinsic0027()",
|
||
0x0028: "Item::setNpcNum(sint16)",
|
||
0x0029: "Intrinsic0029()",
|
||
0x002A: "Intrinsic002A()",
|
||
0x002B: "Item::pop(void)",
|
||
0x002C: "Intrinsic002C()",
|
||
0x002D: "Item::isCompletelyOn(uint16)",
|
||
0x002E: "Item::pop(uint16)",
|
||
0x002F: "Intrinsic002F()",
|
||
0x0030: "Intrinsic0030()",
|
||
0x0031: "Item::getFamily(void)",
|
||
0x0032: "Item::destroyContents(void)",
|
||
0x0033: "Intrinsic0033()",
|
||
0x0034: "Item::getDirToItem(uint16)",
|
||
0x0035: "Intrinsic0035()",
|
||
0x0036: "Intrinsic0036()",
|
||
0x0037: "Intrinsic0037()",
|
||
0x0038: "Item::andStatus(void)",
|
||
0x0039: "Kernel::resetRef(uint16,ProcessType)",
|
||
0x003A: "Item::touch(void)",
|
||
0x003B: "Egg::getEggId(void)",
|
||
0x003C: "Intrinsic003C()",
|
||
0x003D: "Intrinsic003D()",
|
||
0x003E: "Item::callEvent11(sint16)",
|
||
0x003F: "Intrinsic003F()",
|
||
0x0040: "Intrinsic0040()",
|
||
0x0041: "Item::isOn(uint16)",
|
||
0x0042: "Item::getQHi(void)",
|
||
0x0043: "Item::isOn(uint16)",
|
||
0x0044: "Item::getQHi(void)",
|
||
0x0045: "Item::isOn(uint16)",
|
||
0x0046: "Item::getQHi(void)",
|
||
0x0047: "Item::isOn(uint16)",
|
||
0x0048: "Item::getQHi(void)",
|
||
0x0049: "Item::isOn(uint16)",
|
||
0x004A: "Item::getQHi(void)",
|
||
0x004B: "Item::isOn(uint16)",
|
||
0x004C: "Item::getQHi(void)",
|
||
0x004D: "Intrinsic004D()",
|
||
0x004E: "Npc::isDead(void)",
|
||
0x004F: "Intrinsic009C()",
|
||
0x0050: "Intrinsic0050()",
|
||
0x0051: "Intrinsic0051()",
|
||
0x0052: "Intrinsic0052()",
|
||
0x0053: "Intrinsic00BD()",
|
||
0x0054: "Intrinsic0054()",
|
||
0x0055: "Intrinsic0055()",
|
||
0x0056: "Intrinsic0056()",
|
||
0x0057: "Intrinsic0057()",
|
||
0x0058: "Item::use(void)",
|
||
0x0059: "Item::setQuantity(sint16)",
|
||
0x005A: "Intrinsic005A()",
|
||
0x005B: "Item::getSurfaceWeight(void)",
|
||
0x005C: "Intrinsic005C()",
|
||
0x005D: "Item::setFrame(uint16)",
|
||
0x005E: "Intrinsic00DA()",
|
||
0x005F: "Intrinsic005F()",
|
||
0x0060: "Intrinsic0060()",
|
||
0x0061: "Intrinsic0061()",
|
||
0x0062: "Intrinsic0062()",
|
||
0x0063: "Item::legal_create(uint16,uint16,WorldPoint&)",
|
||
0x0064: "Item::getPoint(WorldPoint&)",
|
||
0x0065: "Item::legal_move(WorldPoint&,uint16,uint16)",
|
||
0x0066: "Item::fall(void)",
|
||
0x0067: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0068: "Kernel::getNumProcesses(uint16,ProcessType)",
|
||
0x0069: "Item::getCY(void)",
|
||
0x006A: "Intrinsic006A()",
|
||
0x006B: "Intrinsic006B()",
|
||
0x006C: "Intrinsic006C()",
|
||
0x006D: "Intrinsic006D()",
|
||
0x006E: "Intrinsic006E()",
|
||
0x006F: "Item::isInNpc(void)",
|
||
0x0070: "Intrinsic0070()",
|
||
0x0071: "Intrinsic0071()",
|
||
0x0072: "Intrinsic0072()",
|
||
0x0073: "Intrinsic0073()",
|
||
0x0074: "Npc::isDead(void)",
|
||
0x0075: "Item::getNpcNum(void)",
|
||
0x0076: "IntrinsicReturn0",
|
||
0x0077: "Intrinsic0077()",
|
||
0x0078: "Item::callEvent0B(sint16)",
|
||
0x0079: "Item::andStatus(void)",
|
||
0x007A: "Item::move(uint16,uint16,uint8)",
|
||
0x007B: "Intrinsic007B()",
|
||
0x007C: "Intrinsic007C()",
|
||
0x007D: "Intrinsic007D()",
|
||
0x007E: "Intrinsic007E()",
|
||
0x007F: "Intrinsic007F()",
|
||
0x0080: "Intrinsic0080()",
|
||
0x0081: "Intrinsic0081()",
|
||
0x0082: "Intrinsic0082()",
|
||
0x0083: "Intrinsic0083()",
|
||
0x0084: "Intrinsic0084()",
|
||
0x0085: "Intrinsic0085()",
|
||
0x0086: "teleportToEgg(sint16,int,uint8)",
|
||
0x0087: "Intrinsic0087()",
|
||
0x0088: "Intrinsic0088()",
|
||
0x0089: "Intrinsic00BD()",
|
||
0x008A: "Item::getQuality(void)",
|
||
0x008B: "Item::setQuality(sint16)",
|
||
0x008C: "Intrinsic008C()",
|
||
0x008D: "Intrinsic008D()",
|
||
0x008E: "Intrinsic008E()",
|
||
0x008F: "Camera::getX(void)",
|
||
0x0090: "Camera::getY(void)",
|
||
0x0091: "Item::setMapNum(sint16)",
|
||
0x0092: "Item::getNpcNum(void)",
|
||
0x0093: "Item::shoot(WorldPoint&,sint16,sint16)",
|
||
0x0094: "Intrinsic0094()",
|
||
0x0095: "Item::enterFastArea(void)",
|
||
0x0096: "Intrinsic00CA()",
|
||
0x0097: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0098: "Item::getNpcNum(void)",
|
||
0x0099: "Intrinsic0099()",
|
||
0x009A: "teleportToEgg(sint16,uint8)",
|
||
0x009B: "Intrinsic009B()",
|
||
0x009C: "Intrinsic009C()",
|
||
0x009D: "Intrinsic009D()",
|
||
0x009E: "Intrinsic009E()",
|
||
0x009F: "Intrinsic009F()",
|
||
0x00A0: "Item::andStatus(void)",
|
||
0x00A1: "Item::getUnkEggType(void)",
|
||
0x00A2: "Egg::setEggXRange(uint16)",
|
||
0x00A3: "Item::setFrame(uint16)",
|
||
0x00A4: "Item::overlaps(uint16)",
|
||
0x00A5: "Item::isOn(uint16)",
|
||
0x00A6: "Item::getQHi(void)",
|
||
0x00A7: "Intrinsic00DA()",
|
||
0x00A8: "Item::getCY(void)",
|
||
0x00A9: "Intrinsic00A9()",
|
||
0x00AA: "Item::isOn(uint16)",
|
||
0x00AB: "Npc::isDead(void)",
|
||
0x00AC: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00AD: "Intrinsic00AD()",
|
||
0x00AE: "Item::getQHi(void)",
|
||
0x00AF: "Item::andStatus(void)",
|
||
0x00B0: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00B1: "Item::andStatus(void)",
|
||
0x00B2: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00B3: "Item::andStatus(void)",
|
||
0x00B4: "Item::getDirToCoords(uint16,uint16)",
|
||
0x00B5: "Intrinsic00B5()",
|
||
0x00B6: "Intrinsic00B6()",
|
||
0x00B7: "Item::getNpcNum(void)",
|
||
0x00B8: "Item::getCY(void)",
|
||
0x00B9: "Item::isOn(uint16)",
|
||
0x00BA: "Item::getFootpad(sint16&,sint16&,sint16&)",
|
||
0x00BB: "Npc::isDead(void)",
|
||
0x00BC: "Intrinsic00BC()",
|
||
0x00BD: "Intrinsic00BD()",
|
||
0x00BE: "Intrinsic00BE()",
|
||
0x00BF: "Item::andStatus(void)",
|
||
0x00C0: "Intrinsic00C0()",
|
||
0x00C1: "Intrinsic00C1()",
|
||
0x00C2: "IntrinsicReturn0",
|
||
0x00C3: "Intrinsic00C3()",
|
||
0x00C4: "Item::getQHi(void)",
|
||
0x00C5: "Item::setQuality(sint16)",
|
||
0x00C6: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00C7: "Intrinsic00C7()",
|
||
0x00C8: "Intrinsic00C8()",
|
||
0x00C9: "Item::callEvent0A(sint16)",
|
||
0x00CA: "Intrinsic00CA()",
|
||
0x00CB: "Item::isOn(uint16)",
|
||
0x00CC: "Intrinsic00CC()",
|
||
0x00CD: "Intrinsic00CD()",
|
||
0x00CE: "Item::getQHi(void)",
|
||
0x00CF: "Item::isOn(uint16)",
|
||
0x00D0: "Intrinsic00D0()",
|
||
0x00D1: "Intrinsic00D1()",
|
||
0x00D2: "Intrinsic00D2()",
|
||
0x00D3: "Intrinsic00FA()",
|
||
0x00D4: "Camera::getY(void)",
|
||
0x00D5: "Intrinsic00D5()",
|
||
0x00D6: "Intrinsic00D6()",
|
||
0x00D7: "Intrinsic00D7()",
|
||
0x00D8: "Intrinsic00D8()",
|
||
0x00D9: "Intrinsic00D9()",
|
||
0x00DA: "Intrinsic00DA()",
|
||
0x00DB: "Intrinsic00DB()",
|
||
0x00DC: "Item::getQLo(void)",
|
||
0x00DD: "Item::getQHi(void)",
|
||
0x00DE: "Item::getNpcNum(void)",
|
||
0x00DF: "Intrinsic00DF()",
|
||
0x00E0: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00E1: "Intrinsic00FA()",
|
||
0x00E2: "Item::getQLo(void)",
|
||
0x00E3: "Item::getCY(void)",
|
||
0x00E4: "Item::getNpcNum(void)",
|
||
0x00E5: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00E6: "Item::getNpcNum(void)",
|
||
0x00E7: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00E8: "Item::getNpcNum(void)",
|
||
0x00E9: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00EA: "Item::getNpcNum(void)",
|
||
0x00EB: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00EC: "Item::getNpcNum(void)",
|
||
0x00ED: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00EE: "Item::getNpcNum(void)",
|
||
0x00EF: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00F0: "Item::getNpcNum(void)",
|
||
0x00F1: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00F2: "Item::getNpcNum(void)",
|
||
0x00F3: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00F4: "Item::getNpcNum(void)",
|
||
0x00F5: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x00F6: "Item::getNpcNum(void)",
|
||
0x00F7: "Item::andStatus(void)",
|
||
0x00F8: "Intrinsic00FA()",
|
||
0x00F9: "Item::getQLo(void)",
|
||
0x00FA: "Intrinsic00FA()",
|
||
0x00FB: "Intrinsic00FB()",
|
||
0x00FC: "Intrinsic00FC()",
|
||
0x00FD: "Item::getQLo(void)",
|
||
0x00FE: "Intrinsic00FE()",
|
||
0x00FF: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0100: "Item::andStatus(void)",
|
||
0x0101: "Item::isOn(uint16)",
|
||
0x0102: "Npc::isDead(void)",
|
||
0x0103: "Intrinsic00BD()",
|
||
0x0104: "Item::getQHi(void)",
|
||
0x0105: "Intrinsic00DA()",
|
||
0x0106: "Intrinsic00FA()",
|
||
0x0107: "Item::getQLo(void)",
|
||
0x0108: "Item::isOn(uint16)",
|
||
0x0109: "Item::getQHi(void)",
|
||
0x010A: "Item::isOn(uint16)",
|
||
0x010B: "Item::getQHi(void)",
|
||
0x010C: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x010D: "Item::getNpcNum(void)",
|
||
0x010E: "Item::getCY(void)",
|
||
0x010F: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0110: "Item::isOn(uint16)",
|
||
0x0111: "Intrinsic0111()",
|
||
0x0112: "IntrinsicReturn0",
|
||
0x0113: "Npc::isDead(void)",
|
||
0x0114: "Intrinsic0088()",
|
||
0x0115: "Intrinsic00C1()",
|
||
0x0116: "Item::getQHi(void)",
|
||
0x0117: "Intrinsic00BD()",
|
||
0x0118: "Item::andStatus(void)",
|
||
0x0119: "Item::getNpcNum(void)",
|
||
0x011A: "Item::andStatus(void)",
|
||
0x011B: "Item::getNpcNum(void)",
|
||
0x011C: "Intrinsic011C()",
|
||
0x011D: "Item::andStatus(void)",
|
||
0x011E: "Item::getNpcNum(void)",
|
||
0x011F: "Item::AvatarStoleSomehting(uint16)",
|
||
0x0120: "Item::andStatus(void)",
|
||
0x0121: "Item::getNpcNum(void)",
|
||
0x0122: "Item::getQ(void)",
|
||
0x0123: "Item::setQ(uint)",
|
||
0x0124: "Item::andStatus(void)",
|
||
0x0125: "Item::getNpcNum(void)",
|
||
0x0126: "Item::andStatus(void)",
|
||
0x0127: "Item::getNpcNum(void)",
|
||
0x0128: "Item::andStatus(void)",
|
||
0x0129: "Item::getNpcNum(void)",
|
||
0x012A: "Item::andStatus(void)",
|
||
0x012B: "Item::getNpcNum(void)",
|
||
0x012C: "Item::andStatus(void)",
|
||
0x012D: "Item::getNpcNum(void)",
|
||
0x012E: "Intrinsic00C3()",
|
||
0x012F: "Item::andStatus(void)",
|
||
0x0130: "Item::getNpcNum(void)",
|
||
0x0131: "Intrinsic0131()",
|
||
0x0132: "Item::andStatus(void)",
|
||
0x0133: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x0134: "Item::andStatus(void)",
|
||
0x0135: "Camera::getY(void)",
|
||
0x0136: "Camera::getZ(void)",
|
||
0x0137: "Intrinsic0137()",
|
||
0x0138: "Intrinsic009C()",
|
||
0x0139: "Item::getTypeFlagCrusader(sint16)",
|
||
0x013A: "Item::getNpcNum(void)",
|
||
0x013B: "Item::hurl(sint16,sint16,sint16,sint16)",
|
||
0x013C: "Item::getCY(void)",
|
||
0x013D: "Item::getCZ(void)",
|
||
0x013E: "Item::setFrame(uint16)",
|
||
0x013F: "Intrinsic013F()",
|
||
0x0140: "Intrinsic0140()",
|
||
0x0141: "Intrinsic0141()",
|
||
0x0142: "Intrinsic0142()",
|
||
0x0143: "Npc::isDead(void)",
|
||
0x0144: "Intrinsic00FA()",
|
||
0x0145: "Intrinsic0145()",
|
||
0x0146: "Intrinsic0146()",
|
||
0x0147: "Intrinsic0147()",
|
||
0x0148: "Item::getNpcNum(void)",
|
||
0x0149: "Item::getQLo(void)",
|
||
0x014A: "Item::andStatus(void)",
|
||
0x014B: "Intrinsic014B()",
|
||
0x014C: "Intrinsic014C()",
|
||
0x014D: "Intrinsic014D()",
|
||
0x014E: "Intrinsic003C()",
|
||
0x014F: "Egg::getEggXRange(void)",
|
||
0x0150: "Intrinsic009C()",
|
||
0x0151: "Intrinsic0072()",
|
||
0x0152: "Item::setFrame(uint16)",
|
||
0x0153: "Intrinsic00C1()",
|
||
0x0154: "Intrinsic00C3()",
|
||
0x0155: "Intrinsic00C1()",
|
||
0x0156: "Item::isOn(uint16)",
|
||
0x0157: "Intrinsic00C3()",
|
||
0x0158: "Intrinsic00FA()",
|
||
0x0159: "Item::getQHi(void)",
|
||
0x015A: "Item::getQLo(void)",
|
||
0x015B: "Intrinsic00C1()",
|
||
0x015C: "Intrinsic00C3()",
|
||
0x015D: "Intrinsic015D()",
|
||
}
|
||
|
||
|
||
VARIANT_INTRINSIC_CALLSITE_HINTS: dict[str, dict[tuple[int, int], str]] = {
|
||
"regret": {
|
||
(0x001E, 0x10): "Item::I_fireWeapon(Item *, x, y, z, byte, int, byte)",
|
||
},
|
||
"remorse": {},
|
||
}
|
||
|
||
|
||
CLASS_EVENT_NAME_HINTS: dict[tuple[int, int], str] = {
|
||
(0x0A0C, 0x32): "waitNTimerTicks",
|
||
}
|
||
|
||
|
||
LOOP_SELECTOR_FIELD_HINTS = {
|
||
0x3A: "family",
|
||
0x40: "shape",
|
||
}
|
||
|
||
SHAPE_CATALOG_FILENAME = "usecode_shape_catalog.csv"
|
||
SHAPE_CATALOG_FILENAMES = {
|
||
"remorse": "usecode_shape_catalog_remorse.csv",
|
||
"regret": "usecode_shape_catalog_regret.csv",
|
||
}
|
||
SHAPE_CATALOG_FIELDNAMES = ["shape_code", "human_readable_id", "description"]
|
||
NUMERIC_SHAPE_LITERAL_PATTERN = r"(?:0x[0-9A-Fa-f]+|\d+)"
|
||
SHAPE_REFERENCE_PATTERNS = (
|
||
re.compile(rf"(?P<prefix>\bshape=)(?P<value>{NUMERIC_SHAPE_LITERAL_PATTERN})\b"),
|
||
re.compile(
|
||
rf"(?P<prefix>\bItem\.(?:getShape|getType)\([^\)\n]*\)\s*(?:==|!=|<=|>=|<|>)\s*)(?P<value>{NUMERIC_SHAPE_LITERAL_PATTERN})\b"
|
||
),
|
||
re.compile(rf"(?P<prefix>\bItem\.create\(\s*[^,\n]+,\s*)(?P<value>{NUMERIC_SHAPE_LITERAL_PATTERN})\b"),
|
||
re.compile(rf"(?P<prefix>\bItem\.legal_create\(\s*)(?P<value>{NUMERIC_SHAPE_LITERAL_PATTERN})\b"),
|
||
)
|
||
|
||
ShapeCatalog = dict[int, dict[str, str]]
|
||
|
||
|
||
def infer_shape_catalog_variant(extracted_root: Path | str | None = None, game_variant: str | None = None) -> str | None:
|
||
normalized = normalize_game_variant(game_variant)
|
||
if normalized is not None:
|
||
return normalized
|
||
|
||
root = resolve_extracted_root(extracted_root)
|
||
inferred = infer_game_variant_from_path(root)
|
||
if inferred is not None:
|
||
return inferred
|
||
|
||
try:
|
||
relative_root = root.resolve().relative_to(REPO_ROOT.resolve())
|
||
except ValueError:
|
||
relative_root = None
|
||
|
||
if relative_root is not None:
|
||
relative_parts = tuple(part.lower() for part in relative_root.parts)
|
||
if relative_parts[:2] == ("usecode", "eusecode_extracted"):
|
||
return "remorse"
|
||
if relative_parts[:3] == ("usecode", "regret", "regret_usecode_extracted"):
|
||
return "regret"
|
||
return None
|
||
|
||
|
||
def default_shape_catalog_path(
|
||
extracted_root: Path | str | None = None,
|
||
game_variant: str | None = None,
|
||
) -> Path:
|
||
root = resolve_extracted_root(extracted_root)
|
||
variant = infer_shape_catalog_variant(root, game_variant)
|
||
filename = SHAPE_CATALOG_FILENAMES.get(variant, SHAPE_CATALOG_FILENAME)
|
||
return root / filename
|
||
|
||
|
||
def format_shape_code(shape_code: int) -> str:
|
||
return f"0x{shape_code:04X}"
|
||
|
||
|
||
def load_shape_catalog(path: Path | str | None) -> ShapeCatalog:
|
||
if path is None:
|
||
return {}
|
||
|
||
shape_path = Path(path)
|
||
if not shape_path.exists():
|
||
return {}
|
||
|
||
catalog: ShapeCatalog = {}
|
||
with shape_path.open("r", encoding="utf-8", newline="") as handle:
|
||
reader = csv.DictReader(handle)
|
||
for row in reader:
|
||
shape_code = try_parse_int((row.get("shape_code") or "").strip())
|
||
if shape_code is None:
|
||
continue
|
||
catalog[shape_code] = {
|
||
"shape_code": format_shape_code(shape_code),
|
||
"human_readable_id": (row.get("human_readable_id") or "").strip(),
|
||
"description": row.get("description") or "",
|
||
}
|
||
return catalog
|
||
|
||
|
||
def shape_catalog_identifier(shape_code: int, shape_catalog: ShapeCatalog | None = None) -> str | None:
|
||
if not shape_catalog:
|
||
return None
|
||
|
||
row = shape_catalog.get(shape_code)
|
||
if row is None:
|
||
return None
|
||
|
||
human_readable_id = (row.get("human_readable_id") or "").strip()
|
||
if not human_readable_id:
|
||
return None
|
||
return sanitize_identifier(human_readable_id)
|
||
|
||
|
||
def format_shape_reference(
|
||
shape_code: int,
|
||
shape_catalog: ShapeCatalog | None = None,
|
||
frame_expr: str | None = None,
|
||
) -> str:
|
||
base = shape_catalog_identifier(shape_code, shape_catalog) or format_shape_code(shape_code)
|
||
if frame_expr is None or not frame_expr.strip():
|
||
return base
|
||
return f"{base}[{frame_expr}]"
|
||
|
||
|
||
def iter_shape_code_matches(text: str):
|
||
for pattern in SHAPE_REFERENCE_PATTERNS:
|
||
for match in pattern.finditer(text):
|
||
shape_code = try_parse_int(match.group("value"))
|
||
if shape_code is not None:
|
||
yield shape_code
|
||
|
||
|
||
def collect_shape_codes_from_pseudocode(text: str) -> set[int]:
|
||
return set(iter_shape_code_matches(text))
|
||
|
||
|
||
def apply_shape_catalog_to_pseudocode(text: str, shape_catalog: ShapeCatalog | None = None) -> str:
|
||
if not shape_catalog:
|
||
return text
|
||
|
||
def replace_match(match: re.Match[str]) -> str:
|
||
shape_code = try_parse_int(match.group("value"))
|
||
if shape_code is None:
|
||
return match.group(0)
|
||
|
||
shape_id = shape_catalog_identifier(shape_code, shape_catalog)
|
||
if shape_id is None:
|
||
return match.group(0)
|
||
return f"{match.group('prefix')}{shape_id}"
|
||
|
||
rendered = text
|
||
for pattern in SHAPE_REFERENCE_PATTERNS:
|
||
rendered = pattern.sub(replace_match, rendered)
|
||
return rendered
|
||
|
||
|
||
def generic_loop_selector_call(name: str, arguments: list[tuple[str, str]]) -> str:
|
||
rendered_args = ", ".join(f"{label}={expr}" for label, expr in arguments)
|
||
return f"{name}({rendered_args})"
|
||
|
||
|
||
def normalize_game_variant(value: str | None) -> str | None:
|
||
if value is None:
|
||
return None
|
||
normalized = value.strip().lower()
|
||
if not normalized or normalized == "auto":
|
||
return None
|
||
if normalized not in INTRINSIC_HINT_PATHS:
|
||
raise ValueError(f"Unsupported Crusader variant: {value}")
|
||
return normalized
|
||
|
||
|
||
def infer_game_variant_from_path(path: Path | None) -> str | None:
|
||
if path is None:
|
||
return None
|
||
lowered_parts = [part.lower() for part in path.parts]
|
||
if any("regret" in part for part in lowered_parts):
|
||
return "regret"
|
||
if any("remorse" in part for part in lowered_parts):
|
||
return "remorse"
|
||
return None
|
||
|
||
|
||
def resolve_game_variant(game_variant: str | None = None, source_root: Path | None = None) -> str:
|
||
normalized = normalize_game_variant(game_variant)
|
||
if normalized is not None:
|
||
return normalized
|
||
inferred = infer_game_variant_from_path(source_root)
|
||
if inferred is not None:
|
||
return inferred
|
||
return DEFAULT_GAME_VARIANT
|
||
|
||
|
||
def load_intrinsic_hints_from_file(path: Path) -> dict[int, str]:
|
||
if not path.exists():
|
||
return {}
|
||
|
||
try:
|
||
module = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
|
||
except (OSError, SyntaxError):
|
||
return {}
|
||
|
||
for node in module.body:
|
||
if not isinstance(node, ast.Assign):
|
||
continue
|
||
if len(node.targets) != 1 or not isinstance(node.targets[0], ast.Name):
|
||
continue
|
||
if node.targets[0].id != "intrinsics":
|
||
continue
|
||
try:
|
||
values = ast.literal_eval(node.value)
|
||
except (SyntaxError, ValueError):
|
||
return {}
|
||
if not isinstance(values, list):
|
||
return {}
|
||
return {
|
||
index: str(value)
|
||
for index, value in enumerate(values)
|
||
if isinstance(value, str) and value.strip()
|
||
}
|
||
return {}
|
||
|
||
|
||
def normalize_intrinsic_hint(name: str) -> str:
|
||
normalized = name.strip()
|
||
normalized = re.sub(r"^(?:unsigned|signed|void|byte|char|short|long|int\d+|uint\d+|sint\d+)\s+(?=[A-Za-z_])", "", normalized)
|
||
normalized = re.sub(r"(?<![A-Za-z])udioProcess::", "AudioProcess::", normalized)
|
||
normalized = normalized.replace("MusicProcess:I_", "MusicProcess::I_")
|
||
normalized = normalized.replace("Somehting", "Something")
|
||
normalized = normalized.replace("Actor::I_setDead())", "Actor::I_setDead()")
|
||
return normalized
|
||
|
||
|
||
def build_intrinsic_hints(game_variant: str | None = None, source_root: Path | None = None) -> dict[int, str]:
|
||
variant = resolve_game_variant(game_variant, source_root)
|
||
hints = {index: normalize_intrinsic_hint(name) for index, name in BASE_INTRINSIC_HINTS.items()}
|
||
for index, name in load_intrinsic_hints_from_file(INTRINSIC_HINT_PATHS[variant]).items():
|
||
normalized = normalize_intrinsic_hint(name)
|
||
existing = hints.get(index)
|
||
if existing is None or not normalized.startswith("Intrinsic") or existing.startswith("Intrinsic"):
|
||
hints[index] = normalized
|
||
return hints
|
||
|
||
|
||
_INTRINSIC_HINTS_CACHE: dict[str, dict[int, str]] = {}
|
||
|
||
|
||
def get_intrinsic_hints(game_variant: str | None = None, source_root: Path | None = None) -> dict[int, str]:
|
||
variant = resolve_game_variant(game_variant, source_root)
|
||
cached = _INTRINSIC_HINTS_CACHE.get(variant)
|
||
if cached is None:
|
||
cached = build_intrinsic_hints(variant)
|
||
_INTRINSIC_HINTS_CACHE[variant] = cached
|
||
return cached
|
||
|
||
|
||
def get_intrinsic_callsite_hints(game_variant: str | None = None, source_root: Path | None = None) -> dict[tuple[int, int], str]:
|
||
variant = resolve_game_variant(game_variant, source_root)
|
||
return VARIANT_INTRINSIC_CALLSITE_HINTS.get(variant, {})
|
||
|
||
|
||
INTRINSIC_HINTS = get_intrinsic_hints(DEFAULT_GAME_VARIANT)
|
||
|
||
|
||
NO_ARG_MNEMONICS = {
|
||
0x08: "pop_result",
|
||
0x12: "pop_temp",
|
||
0x13: "pop_temp_dword",
|
||
0x14: "add",
|
||
0x15: "add_dword",
|
||
0x16: "concat",
|
||
0x17: "append_list",
|
||
0x1C: "sub",
|
||
0x1D: "sub_dword",
|
||
0x1E: "mul",
|
||
0x1F: "mul_dword",
|
||
0x20: "div",
|
||
0x21: "div_dword",
|
||
0x22: "mod",
|
||
0x23: "mod_dword",
|
||
0x24: "cmp",
|
||
0x25: "cmp_dword",
|
||
0x26: "strcmp",
|
||
0x27: "cmp_huge",
|
||
0x28: "lt",
|
||
0x29: "lt_dword",
|
||
0x2A: "le",
|
||
0x2B: "le_dword",
|
||
0x2C: "gt",
|
||
0x2D: "gt_dword",
|
||
0x2E: "ge",
|
||
0x2F: "ge_dword",
|
||
0x30: "not",
|
||
0x31: "not_dword",
|
||
0x32: "and",
|
||
0x33: "and_dword",
|
||
0x34: "or",
|
||
0x35: "or_dword",
|
||
0x36: "ne",
|
||
0x37: "ne_dword",
|
||
0x39: "bit_and",
|
||
0x3A: "bit_or",
|
||
0x3B: "bit_not",
|
||
0x3C: "lsh",
|
||
0x3D: "rsh",
|
||
0x50: "ret",
|
||
0x53: "suspend",
|
||
0x59: "push_pid",
|
||
0x5D: "push_retval_byte",
|
||
0x5E: "push_retval_word",
|
||
0x5F: "push_retval_dword",
|
||
0x60: "word_to_dword",
|
||
0x61: "dword_to_word",
|
||
0x68: "copy_string",
|
||
0x6A: "ptr_to_string",
|
||
0x6B: "str_to_ptr",
|
||
0x6D: "push_process_result",
|
||
0x73: "loopnext",
|
||
0x77: "set_info",
|
||
0x78: "process_exclude",
|
||
0x7A: "end",
|
||
}
|
||
|
||
|
||
def parse_int(value: str) -> int:
|
||
return int(value, 0)
|
||
|
||
|
||
def try_parse_int(value: str) -> int | None:
|
||
try:
|
||
return parse_int(value)
|
||
except (TypeError, ValueError):
|
||
return None
|
||
|
||
|
||
def signed_byte(value: int) -> int:
|
||
return value - 0x100 if value & 0x80 else value
|
||
|
||
|
||
def bp_repr(value: int) -> str:
|
||
disp = signed_byte(value)
|
||
sign = "+" if disp >= 0 else "-"
|
||
return f"[BP{sign}{abs(disp):02X}h]"
|
||
|
||
|
||
def sp_repr(value: int) -> str:
|
||
disp = signed_byte(value)
|
||
sign = "+" if disp >= 0 else "-"
|
||
return f"[SP{sign}{abs(disp):02X}h]"
|
||
|
||
|
||
@dataclass
|
||
class ParseResult:
|
||
op: dict[str, Any] | None
|
||
next_offset: int
|
||
end_reason: str | None = None
|
||
unknown_tail: bytes | None = None
|
||
|
||
|
||
@dataclass
|
||
class DebugSymbolRecord:
|
||
index: int
|
||
unknown1: int
|
||
type_id: int
|
||
type_char: str
|
||
bp_offset: int
|
||
bp_repr: str
|
||
unknown3: int
|
||
name: str
|
||
|
||
|
||
@dataclass
|
||
class DebugSymbolParseResult:
|
||
debug_symbols: list[DebugSymbolRecord]
|
||
end_offset: int
|
||
has_end_opcode: bool
|
||
trailing_bytes: bytes
|
||
|
||
|
||
@dataclass
|
||
class FieldTagRecord:
|
||
tag_id: int
|
||
bp_offset: int
|
||
value_kind: int
|
||
name: str
|
||
|
||
|
||
@dataclass
|
||
class FieldTagParseResult:
|
||
field_tags: list[FieldTagRecord]
|
||
end_offset: int
|
||
trailing_bytes: bytes
|
||
|
||
|
||
class BodyReader:
|
||
def __init__(self, data: bytes, offset: int = 0) -> None:
|
||
self.data = data
|
||
self.offset = offset
|
||
|
||
def read_u8(self) -> int:
|
||
value = self.data[self.offset]
|
||
self.offset += 1
|
||
return value
|
||
|
||
def read_u16(self) -> int:
|
||
value = int.from_bytes(self.data[self.offset:self.offset + 2], "little")
|
||
self.offset += 2
|
||
return value
|
||
|
||
def read_u32(self) -> int:
|
||
value = int.from_bytes(self.data[self.offset:self.offset + 4], "little")
|
||
self.offset += 4
|
||
return value
|
||
|
||
def read_cstring(self) -> str:
|
||
chars: list[str] = []
|
||
while self.offset < len(self.data):
|
||
byte = self.read_u8()
|
||
if byte == 0:
|
||
break
|
||
chars.append(chr(byte))
|
||
return "".join(chars)
|
||
|
||
def read_fixed_string(self, length: int) -> str:
|
||
raw = self.data[self.offset:self.offset + length]
|
||
self.offset += length
|
||
return raw.decode("latin-1", errors="replace").rstrip("\x00")
|
||
|
||
|
||
def op_record(start: int, absolute_start: int, opcode: int, raw_bytes: bytes, mnemonic: str, operands: dict[str, Any]) -> dict[str, Any]:
|
||
return {
|
||
"offset": start,
|
||
"absolute_body_offset": absolute_start,
|
||
"opcode": opcode,
|
||
"mnemonic": mnemonic,
|
||
"raw_bytes": raw_bytes.hex(),
|
||
"operands": operands,
|
||
}
|
||
|
||
|
||
def parse_one_op(
|
||
body: bytes,
|
||
start: int,
|
||
intrinsic_hints: dict[int, str] | None = None,
|
||
intrinsic_callsite_hints: dict[tuple[int, int], str] | None = None,
|
||
) -> ParseResult:
|
||
reader = BodyReader(body, start)
|
||
opcode = reader.read_u8()
|
||
operands: dict[str, Any] = {}
|
||
mnemonic = NO_ARG_MNEMONICS.get(opcode)
|
||
active_intrinsic_hints = intrinsic_hints or INTRINSIC_HINTS
|
||
active_callsite_hints = intrinsic_callsite_hints or get_intrinsic_callsite_hints(DEFAULT_GAME_VARIANT)
|
||
|
||
if opcode == 0x00:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_local_byte"
|
||
elif opcode == 0x01:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_local_word"
|
||
elif opcode == 0x02:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_local_dword"
|
||
elif opcode == 0x03:
|
||
bp_offset = reader.read_u8()
|
||
size = reader.read_u8()
|
||
operands = {"bp_offset": bp_offset, "target": bp_repr(bp_offset), "size": size}
|
||
mnemonic = "pop_local_blob"
|
||
elif opcode == 0x04:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_member_byte"
|
||
elif opcode == 0x05:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_member_word"
|
||
elif opcode == 0x06:
|
||
operands = {"bp_offset": reader.read_u8(), "target": bp_repr(body[start + 1])}
|
||
mnemonic = "pop_member_dword"
|
||
elif opcode == 0x07:
|
||
bp_offset = reader.read_u8()
|
||
size = reader.read_u8()
|
||
operands = {"bp_offset": bp_offset, "target": bp_repr(bp_offset), "size": size}
|
||
mnemonic = "pop_member_blob"
|
||
elif opcode == 0x09:
|
||
bp_offset = reader.read_u8()
|
||
element_size = reader.read_u8()
|
||
slist_flag = reader.read_u8()
|
||
operands = {
|
||
"bp_offset": bp_offset,
|
||
"target": bp_repr(bp_offset),
|
||
"element_size": element_size,
|
||
"slist_flag": slist_flag,
|
||
}
|
||
mnemonic = "pop_list_element"
|
||
elif opcode == 0x0A:
|
||
value = reader.read_u8()
|
||
operands = {"value_u8": value, "value_signed": signed_byte(value)}
|
||
mnemonic = "push_byte_immediate"
|
||
elif opcode == 0x0B:
|
||
operands = {"value_u16": reader.read_u16()}
|
||
mnemonic = "push_word_immediate"
|
||
elif opcode == 0x0C:
|
||
operands = {"value_u32": reader.read_u32()}
|
||
mnemonic = "push_dword_immediate"
|
||
elif opcode == 0x0D:
|
||
declared_length = reader.read_u16()
|
||
text = reader.read_cstring()
|
||
operands = {"declared_length": declared_length, "string": text}
|
||
mnemonic = "push_string_immediate"
|
||
elif opcode == 0x0E:
|
||
element_size = reader.read_u8()
|
||
count = reader.read_u8()
|
||
operands = {"element_size": element_size, "count": count}
|
||
mnemonic = "create_list"
|
||
elif opcode == 0x0F:
|
||
arg_bytes = reader.read_u8()
|
||
intrinsic_ordinal = reader.read_u16()
|
||
operands = {
|
||
"intrinsic_ordinal": intrinsic_ordinal,
|
||
"arg_bytes": arg_bytes,
|
||
"intrinsic_name_hint": active_callsite_hints.get((intrinsic_ordinal, arg_bytes), active_intrinsic_hints.get(intrinsic_ordinal)),
|
||
}
|
||
mnemonic = "call_intrinsic"
|
||
elif opcode == 0x10:
|
||
operands = {"target_offset": reader.read_u16()}
|
||
mnemonic = "call_near"
|
||
elif opcode == 0x11:
|
||
target_class_id = reader.read_u16()
|
||
target_slot = reader.read_u16()
|
||
operands = {
|
||
"target_class_id": target_class_id,
|
||
"target_event_slot": target_slot,
|
||
"target_event_name_hint": EVENT_NAME_HINTS.get(target_slot),
|
||
}
|
||
mnemonic = "call_class_event"
|
||
elif opcode in {0x18, 0x19, 0x1A, 0x1B}:
|
||
element_size = reader.read_u8()
|
||
operands = {"element_size": element_size}
|
||
mnemonic = {
|
||
0x18: "append_unique_inline",
|
||
0x19: "append_unique_indirect",
|
||
0x1A: "remove_matching_indirect",
|
||
0x1B: "remove_matching_inline",
|
||
}[opcode]
|
||
elif opcode == 0x38:
|
||
element_size = reader.read_u8()
|
||
slist_flag = reader.read_u8()
|
||
operands = {"element_size": element_size, "slist_flag": slist_flag}
|
||
mnemonic = "in_list"
|
||
elif opcode in {0x3E, 0x3F, 0x40, 0x41, 0x43, 0x46, 0x47, 0x48, 0x49, 0x4B, 0x62, 0x63, 0x64, 0x69}:
|
||
bp_offset = reader.read_u8()
|
||
operands = {"bp_offset": bp_offset, "target": bp_repr(bp_offset)}
|
||
mnemonic = {
|
||
0x3E: "push_local_byte",
|
||
0x3F: "push_local_word",
|
||
0x40: "push_local_dword",
|
||
0x41: "push_local_string",
|
||
0x43: "push_local_slist",
|
||
0x46: "push_member_byte",
|
||
0x47: "push_member_word",
|
||
0x48: "push_member_dword",
|
||
0x49: "push_member_huge",
|
||
0x4B: "push_local_addr",
|
||
0x62: "free_local_string",
|
||
0x63: "free_local_slist",
|
||
0x64: "free_local_list",
|
||
0x69: "push_string_ptr",
|
||
}[opcode]
|
||
elif opcode == 0x42:
|
||
bp_offset = reader.read_u8()
|
||
element_size = reader.read_u8()
|
||
operands = {"bp_offset": bp_offset, "target": bp_repr(bp_offset), "element_size": element_size}
|
||
mnemonic = "push_local_list"
|
||
elif opcode == 0x44:
|
||
element_size = reader.read_u8()
|
||
slist_flag = reader.read_u8()
|
||
operands = {"element_size": element_size, "slist_flag": slist_flag}
|
||
mnemonic = "push_list_element"
|
||
elif opcode == 0x45:
|
||
byte0 = reader.read_u8()
|
||
byte1 = reader.read_u8()
|
||
operands = {"value_a": byte0, "value_b": byte1}
|
||
mnemonic = "push_huge"
|
||
elif opcode in {0x4C, 0x4D}:
|
||
size = reader.read_u8()
|
||
operands = {"size": size}
|
||
mnemonic = {0x4C: "push_indirect", 0x4D: "pop_indirect"}[opcode]
|
||
elif opcode in {0x4E, 0x4F}:
|
||
global_id = reader.read_u16()
|
||
size = reader.read_u8()
|
||
operands = {"global_id": global_id, "size": size}
|
||
mnemonic = {0x4E: "push_global", 0x4F: "pop_global"}[opcode]
|
||
elif opcode in {0x51, 0x52}:
|
||
relative = reader.read_u16()
|
||
signed_relative = relative - 0x10000 if relative & 0x8000 else relative
|
||
target = reader.offset + signed_relative
|
||
operands = {"relative_u16": relative, "relative_signed": signed_relative, "target_offset": target}
|
||
mnemonic = {0x51: "jne", 0x52: "jmp"}[opcode]
|
||
elif opcode == 0x54:
|
||
arg0 = reader.read_u8()
|
||
arg1 = reader.read_u8()
|
||
operands = {"arg0": arg0, "arg1": arg1}
|
||
mnemonic = "implies"
|
||
elif opcode == 0x57:
|
||
arg_bytes = reader.read_u8()
|
||
this_size = reader.read_u8()
|
||
target_class_id = reader.read_u16()
|
||
target_slot = reader.read_u16()
|
||
operands = {
|
||
"arg_bytes": arg_bytes,
|
||
"this_size": this_size,
|
||
"target_class_id": target_class_id,
|
||
"target_event_slot": target_slot,
|
||
"target_event_name_hint": EVENT_NAME_HINTS.get(target_slot),
|
||
}
|
||
mnemonic = "spawn"
|
||
elif opcode == 0x58:
|
||
target_class_id = reader.read_u16()
|
||
target_slot = reader.read_u16()
|
||
inline_offset = reader.read_u16()
|
||
this_size = reader.read_u8()
|
||
unknown = reader.read_u8()
|
||
operands = {
|
||
"target_class_id": target_class_id,
|
||
"target_event_slot": target_slot,
|
||
"target_event_name_hint": EVENT_NAME_HINTS.get(target_slot),
|
||
"inline_offset": inline_offset,
|
||
"this_size": this_size,
|
||
"unknown": unknown,
|
||
}
|
||
mnemonic = "spawn_inline"
|
||
elif opcode == 0x5A:
|
||
operands = {"local_bytes": reader.read_u8()}
|
||
mnemonic = "init"
|
||
elif opcode == 0x5B:
|
||
operands = {"line_number": reader.read_u16()}
|
||
mnemonic = "line_number"
|
||
elif opcode == 0x5C:
|
||
relative = reader.read_u16()
|
||
symbol_offset = reader.offset + (relative - 0x10000 if relative & 0x8000 else relative)
|
||
symbol = reader.read_fixed_string(8)
|
||
trailing_zero = reader.read_u8()
|
||
operands = {
|
||
"symbol_offset": symbol_offset,
|
||
"symbol": symbol,
|
||
"trailing_zero": trailing_zero,
|
||
}
|
||
mnemonic = "symbol_info"
|
||
elif opcode in {0x65, 0x66, 0x67, 0x6E, 0x6F, 0x74}:
|
||
value = reader.read_u8()
|
||
operands = {"value_u8": value}
|
||
if opcode in {0x65, 0x66, 0x67}:
|
||
operands["target"] = sp_repr(value)
|
||
mnemonic = {
|
||
0x65: "free_stack_string",
|
||
0x66: "free_stack_list",
|
||
0x67: "free_stack_slist",
|
||
0x6E: "add_sp",
|
||
0x6F: "push_stack_addr",
|
||
0x74: "loopscr",
|
||
}[opcode]
|
||
elif opcode == 0x6C:
|
||
bp_offset = reader.read_u8()
|
||
copy_type = reader.read_u8()
|
||
operands = {"bp_offset": bp_offset, "target": bp_repr(bp_offset), "copy_type": copy_type}
|
||
mnemonic = "param_pid_chg"
|
||
elif opcode == 0x70:
|
||
current_var = reader.read_u8()
|
||
string_bytes = reader.read_u8()
|
||
loop_type = reader.read_u8()
|
||
operands = {"current_var": current_var, "string_bytes": string_bytes, "loop_type": loop_type}
|
||
mnemonic = "loop"
|
||
elif opcode in {0x75, 0x76}:
|
||
bp_offset = reader.read_u8()
|
||
element_size = reader.read_u8()
|
||
branch = reader.read_u16()
|
||
signed_branch = branch - 0x10000 if branch & 0x8000 else branch
|
||
target = reader.offset + signed_branch
|
||
operands = {
|
||
"bp_offset": bp_offset,
|
||
"target_var": bp_repr(bp_offset),
|
||
"element_size": element_size,
|
||
"relative_u16": branch,
|
||
"relative_signed": signed_branch,
|
||
"target_offset": target,
|
||
}
|
||
mnemonic = {0x75: "foreach_list", 0x76: "foreach_slist"}[opcode]
|
||
elif opcode == 0x79:
|
||
operands = {"global_id": reader.read_u16()}
|
||
mnemonic = "global_address"
|
||
elif mnemonic is None:
|
||
return ParseResult(op=None, next_offset=start, end_reason="unknown_opcode", unknown_tail=body[start:])
|
||
|
||
raw = body[start:reader.offset]
|
||
op = op_record(start, start, opcode, raw, mnemonic, operands)
|
||
end_reason = "end_opcode" if opcode == 0x7A else None
|
||
return ParseResult(op=op, next_offset=reader.offset, end_reason=end_reason)
|
||
|
||
|
||
def load_tsv_rows(path: Path) -> list[dict[str, str]]:
|
||
with path.open("r", encoding="utf-8", newline="") as handle:
|
||
return list(csv.DictReader(handle, delimiter="\t"))
|
||
|
||
|
||
@lru_cache(maxsize=None)
|
||
def load_class_name_hints_by_id(extracted_root_key: str) -> dict[int, str]:
|
||
_, class_layout_index, _, _ = extracted_root_paths(Path(extracted_root_key))
|
||
hints: dict[int, str] = {}
|
||
for row in load_tsv_rows(class_layout_index):
|
||
class_id = try_parse_int(row.get("class_id", ""))
|
||
class_name = (row.get("class_name_hint") or "").strip()
|
||
if class_id is None or not class_name:
|
||
continue
|
||
hints[class_id] = class_name
|
||
return hints
|
||
|
||
|
||
def class_name_hints_by_id(extracted_root: Path | str | None = None) -> dict[int, str]:
|
||
root = resolve_extracted_root(extracted_root)
|
||
return load_class_name_hints_by_id(str(root))
|
||
|
||
|
||
def find_chunk_file(entry_index: int, extracted_root: Path | str | None = None) -> Path:
|
||
_, _, _, chunks_dir = extracted_root_paths(extracted_root)
|
||
matches = sorted(chunks_dir.glob(f"chunk_{entry_index:03d}_*.bin"))
|
||
if not matches:
|
||
matches = sorted(chunks_dir.glob(f"chunk_{entry_index}_*.bin"))
|
||
if not matches:
|
||
raise FileNotFoundError(f"No chunk file found for entry_index={entry_index}")
|
||
return matches[0]
|
||
|
||
|
||
def select_rows(class_name: str, slot: int, extracted_root: Path | str | None = None) -> tuple[dict[str, str], dict[str, str]]:
|
||
class_event_index, class_layout_index, _, _ = extracted_root_paths(extracted_root)
|
||
event_rows = load_tsv_rows(class_event_index)
|
||
layout_rows = load_tsv_rows(class_layout_index)
|
||
|
||
event_row = next(
|
||
(
|
||
row for row in event_rows
|
||
if row["class_name_hint"].upper() == class_name.upper()
|
||
and try_parse_int(row.get("slot", "")) == slot
|
||
and try_parse_int(row.get("entry_index", "")) is not None
|
||
),
|
||
None,
|
||
)
|
||
if event_row is None:
|
||
raise KeyError(f"No class_event_index row found for class={class_name} slot=0x{slot:02X}")
|
||
if not event_row["derived_body_start"] or not event_row["derived_body_end"]:
|
||
raise ValueError(f"Selected row has no derived body range for class={class_name} slot=0x{slot:02X}")
|
||
|
||
entry_index = parse_int(event_row["entry_index"])
|
||
layout_row = next(
|
||
(row for row in layout_rows if try_parse_int(row.get("entry_index", "")) == entry_index),
|
||
None,
|
||
)
|
||
if layout_row is None:
|
||
raise KeyError(f"No class_layout_index row found for entry_index={entry_index}")
|
||
return event_row, layout_row
|
||
|
||
|
||
def load_runtime_ir_rows(extracted_root: Path | str | None = None) -> list[dict[str, str]]:
|
||
_, _, runtime_vm_ir_index, _ = extracted_root_paths(extracted_root)
|
||
return load_tsv_rows(runtime_vm_ir_index)
|
||
|
||
|
||
def runtime_stage_hints(ops: list[dict[str, Any]], extracted_root: Path | str | None = None) -> list[dict[str, str]]:
|
||
opcode_values = {op["opcode"] for op in ops}
|
||
hints: list[dict[str, str]] = []
|
||
for row in load_runtime_ir_rows(extracted_root):
|
||
opcode_or_lane = row.get("opcode_or_lane", "")
|
||
if opcode_or_lane.lower().startswith("opcode 0x"):
|
||
opcode_value = try_parse_int(opcode_or_lane.split()[1])
|
||
if opcode_value is None or opcode_value not in opcode_values:
|
||
continue
|
||
elif row.get("stage_address") not in {"000d:177c", "000d:1acb", "000d:2104", "000d:21ed", "000d:22bc"}:
|
||
continue
|
||
hints.append(row)
|
||
return hints
|
||
|
||
|
||
def annotation_hints(event_row: dict[str, str], payload_shape_hint: str, ops: list[dict[str, Any]], extracted_root: Path | str | None = None) -> dict[str, Any]:
|
||
slot = parse_int(event_row["slot"])
|
||
return {
|
||
"runtime_family": "slot-backed-owner-loaded-body",
|
||
"payload_shape_hint": payload_shape_hint,
|
||
"compiled_anchors": [
|
||
{"address": "000d:46ec", "role": "context_create_from_slot"},
|
||
{"address": "000d:0988", "role": "referent_chain_mutator"},
|
||
{"address": "000d:177c", "role": "push_frame_word_literal"},
|
||
{"address": "000d:1acb", "role": "compare_stream_dword_and_push_bool"},
|
||
{"address": "000d:208b", "role": "materialize_or_forward_value"},
|
||
{"address": "000d:21ed", "role": "prepend_inline_payload"},
|
||
{"address": "000d:22bc", "role": "matrix_pushback_stage"},
|
||
{"address": "000d:2104", "role": "finalize_to_outptr"},
|
||
{"address": "000d:ebe3", "role": "opcode_sequence_run"},
|
||
],
|
||
"runtime_stage_hints": runtime_stage_hints(ops, extracted_root),
|
||
"slot_taxonomy": {"slot": slot, "event_name_hint": event_row["event_name_hint"] or EVENT_NAME_HINTS.get(slot)},
|
||
}
|
||
|
||
|
||
def infer_payload_shape(slot: int) -> str | None:
|
||
if slot in {0x10, 0x12}:
|
||
return "none"
|
||
if slot in {0x0A, 0x0B, 0x11, 0x14}:
|
||
return "word"
|
||
if slot == 0x13:
|
||
return "signed_word"
|
||
return None
|
||
|
||
|
||
def parse_debug_symbols(body: bytes, start: int) -> DebugSymbolParseResult | None:
|
||
if start >= len(body):
|
||
return None
|
||
if body[start] == 0x7A:
|
||
return DebugSymbolParseResult(debug_symbols=[], end_offset=start + 1, has_end_opcode=True, trailing_bytes=body[start + 1:])
|
||
|
||
reader = BodyReader(body, start)
|
||
count = reader.read_u8()
|
||
debug_symbols: list[DebugSymbolRecord] = []
|
||
|
||
try:
|
||
for index in range(count):
|
||
unknown1 = reader.read_u8()
|
||
type_id = reader.read_u8()
|
||
bp_offset = reader.read_u8()
|
||
unknown3 = reader.read_u8()
|
||
name = reader.read_cstring()
|
||
type_char = chr(type_id) if 0x20 <= type_id <= 0x7E else "."
|
||
debug_symbols.append(
|
||
DebugSymbolRecord(
|
||
index=index,
|
||
unknown1=unknown1,
|
||
type_id=type_id,
|
||
type_char=type_char,
|
||
bp_offset=bp_offset,
|
||
bp_repr=bp_repr(bp_offset),
|
||
unknown3=unknown3,
|
||
name=name,
|
||
)
|
||
)
|
||
except IndexError:
|
||
return None
|
||
|
||
has_end_opcode = reader.offset < len(body) and body[reader.offset] == 0x7A
|
||
end_offset = reader.offset + (1 if has_end_opcode else 0)
|
||
trailing_bytes = body[end_offset:]
|
||
if not has_end_opcode:
|
||
return None
|
||
return DebugSymbolParseResult(
|
||
debug_symbols=debug_symbols,
|
||
end_offset=end_offset,
|
||
has_end_opcode=has_end_opcode,
|
||
trailing_bytes=trailing_bytes,
|
||
)
|
||
|
||
|
||
def parse_field_tags(body: bytes, start: int) -> FieldTagParseResult | None:
|
||
if start >= len(body):
|
||
return None
|
||
|
||
reader = BodyReader(body, start)
|
||
field_tags: list[FieldTagRecord] = []
|
||
|
||
try:
|
||
while reader.offset < len(body) and body[reader.offset] != 0x7A:
|
||
tag_id = reader.read_u8()
|
||
bp_offset = reader.read_u8()
|
||
value_kind = reader.read_u8()
|
||
name = reader.read_cstring()
|
||
if not name:
|
||
return None
|
||
field_tags.append(FieldTagRecord(tag_id=tag_id, bp_offset=bp_offset, value_kind=value_kind, name=name))
|
||
if reader.offset < len(body) and body[reader.offset] == 0x00:
|
||
reader.offset += 1
|
||
except IndexError:
|
||
return None
|
||
|
||
if not field_tags or reader.offset >= len(body) or body[reader.offset] != 0x7A:
|
||
return None
|
||
end_offset = reader.offset + 1
|
||
return FieldTagParseResult(field_tags=field_tags, end_offset=end_offset, trailing_bytes=body[end_offset:])
|
||
|
||
|
||
def parse_body_ir(
|
||
event_row: dict[str, str],
|
||
layout_row: dict[str, str],
|
||
game_variant: str | None = None,
|
||
extracted_root: Path | str | None = None,
|
||
) -> dict[str, Any]:
|
||
resolved_extracted_root = resolve_extracted_root(extracted_root)
|
||
entry_index = parse_int(event_row["entry_index"])
|
||
chunk_file = find_chunk_file(entry_index, resolved_extracted_root)
|
||
chunk_bytes = chunk_file.read_bytes()
|
||
resolved_game_variant = resolve_game_variant(game_variant, chunk_file)
|
||
intrinsic_hints = get_intrinsic_hints(resolved_game_variant, chunk_file)
|
||
intrinsic_callsite_hints = get_intrinsic_callsite_hints(resolved_game_variant, chunk_file)
|
||
target_class_name_hints = class_name_hints_by_id(resolved_extracted_root)
|
||
|
||
body_start = parse_int(event_row["derived_body_start"])
|
||
body_end = parse_int(event_row["derived_body_end"])
|
||
body = chunk_bytes[body_start:body_end]
|
||
|
||
ops: list[dict[str, Any]] = []
|
||
offset = 0
|
||
end_reason = "body_exhausted"
|
||
unknown_tail = b""
|
||
debug_symbols: list[dict[str, Any]] = []
|
||
debug_symbol_offset: int | None = None
|
||
field_tags: list[dict[str, Any]] = []
|
||
|
||
while offset < len(body):
|
||
result = parse_one_op(body, offset, intrinsic_hints, intrinsic_callsite_hints)
|
||
if result.op is not None:
|
||
operands = result.op["operands"]
|
||
if "target_class_id" in operands:
|
||
class_id = operands["target_class_id"]
|
||
operands["target_class_name_hint"] = target_class_name_hints.get(class_id)
|
||
result.op["absolute_body_offset"] = body_start + result.op["offset"]
|
||
ops.append(result.op)
|
||
if result.end_reason is not None:
|
||
end_reason = result.end_reason
|
||
unknown_tail = result.unknown_tail or b""
|
||
if result.end_reason == "end_opcode":
|
||
unknown_tail = body[result.next_offset:]
|
||
offset = result.next_offset
|
||
break
|
||
offset = result.next_offset
|
||
|
||
if offset >= len(body) and end_reason == "body_exhausted":
|
||
unknown_tail = b""
|
||
|
||
candidate_debug_offsets = sorted(
|
||
{
|
||
operands["symbol_offset"]
|
||
for op in ops
|
||
for operands in [op["operands"]]
|
||
if op["mnemonic"] == "symbol_info"
|
||
and isinstance(operands.get("symbol_offset"), int)
|
||
and 0 <= operands["symbol_offset"] < len(body)
|
||
}
|
||
)
|
||
last_ret_index = next((index for index in range(len(ops) - 1, -1, -1) if ops[index]["mnemonic"] == "ret"), None)
|
||
if end_reason == "unknown_opcode" and last_ret_index is not None:
|
||
ret_end = ops[last_ret_index]["offset"] + (len(ops[last_ret_index]["raw_bytes"]) // 2)
|
||
ret_debug_result = parse_debug_symbols(body, ret_end)
|
||
if ret_debug_result is not None:
|
||
ops = ops[:last_ret_index + 1]
|
||
debug_symbol_offset = ret_end
|
||
debug_symbols = [
|
||
{
|
||
"index": symbol.index,
|
||
"unknown1": symbol.unknown1,
|
||
"type_id": symbol.type_id,
|
||
"type_char": symbol.type_char,
|
||
"bp_offset": symbol.bp_offset,
|
||
"bp_repr": symbol.bp_repr,
|
||
"unknown3": symbol.unknown3,
|
||
"name": symbol.name,
|
||
}
|
||
for symbol in ret_debug_result.debug_symbols
|
||
]
|
||
end_reason = "debug_symbols_then_end"
|
||
unknown_tail = ret_debug_result.trailing_bytes
|
||
offset = ret_debug_result.end_offset
|
||
|
||
if end_reason == "unknown_opcode" and candidate_debug_offsets:
|
||
for candidate_offset in reversed(candidate_debug_offsets):
|
||
if candidate_offset != offset:
|
||
continue
|
||
debug_result = parse_debug_symbols(body, candidate_offset)
|
||
if debug_result is None:
|
||
continue
|
||
debug_symbol_offset = candidate_offset
|
||
debug_symbols = [
|
||
{
|
||
"index": symbol.index,
|
||
"unknown1": symbol.unknown1,
|
||
"type_id": symbol.type_id,
|
||
"type_char": symbol.type_char,
|
||
"bp_offset": symbol.bp_offset,
|
||
"bp_repr": symbol.bp_repr,
|
||
"unknown3": symbol.unknown3,
|
||
"name": symbol.name,
|
||
}
|
||
for symbol in debug_result.debug_symbols
|
||
]
|
||
end_reason = "debug_symbols_then_end"
|
||
unknown_tail = debug_result.trailing_bytes
|
||
offset = debug_result.end_offset
|
||
break
|
||
|
||
if end_reason == "unknown_opcode" and last_ret_index is not None:
|
||
ret_end = ops[last_ret_index]["offset"] + (len(ops[last_ret_index]["raw_bytes"]) // 2)
|
||
field_tag_result = parse_field_tags(body, ret_end)
|
||
if field_tag_result is not None:
|
||
ops = ops[:last_ret_index + 1]
|
||
field_tags = [
|
||
{
|
||
"tag_id": tag.tag_id,
|
||
"bp_offset": tag.bp_offset,
|
||
"bp_repr": bp_repr(tag.bp_offset),
|
||
"value_kind": tag.value_kind,
|
||
"name": tag.name,
|
||
"tag_label": f"{tag.tag_id:02X}:{tag.bp_offset:02X}{tag.value_kind:02X}->{tag.name}",
|
||
}
|
||
for tag in field_tag_result.field_tags
|
||
]
|
||
end_reason = "field_tags_then_end"
|
||
unknown_tail = field_tag_result.trailing_bytes
|
||
offset = field_tag_result.end_offset
|
||
|
||
slot = parse_int(event_row["slot"])
|
||
payload_shape = infer_payload_shape(slot)
|
||
return {
|
||
"schema_version": "crusader-usecode-ir-v1-poc",
|
||
"source": {
|
||
"game_variant": resolved_game_variant,
|
||
"flex_path": infer_flex_path(resolved_extracted_root),
|
||
"extracted_root": repo_relative_path(resolved_extracted_root),
|
||
"chunk_file": repo_relative_path(chunk_file),
|
||
},
|
||
"class": {
|
||
"entry_index": entry_index,
|
||
"object_index": parse_int(layout_row["object_index"]),
|
||
"class_id": parse_int(layout_row["class_id"]),
|
||
"class_name": layout_row["class_name_hint"],
|
||
"raw_code_base_u32": parse_int(layout_row["raw_code_base_u32"]),
|
||
"code_base_minus_one": parse_int(layout_row["code_base_minus_one"]),
|
||
"conservative_event_count": parse_int(layout_row["conservative_event_count"]),
|
||
},
|
||
"event": {
|
||
"slot": slot,
|
||
"event_name_hint": event_row["event_name_hint"] or EVENT_NAME_HINTS.get(slot),
|
||
"raw_event_entry_word": parse_int(event_row["raw_event_entry_word"]),
|
||
"raw_code_offset": parse_int(event_row["raw_code_offset"]),
|
||
"derived_body_start": body_start,
|
||
"derived_body_end": body_end,
|
||
"derived_body_length": parse_int(event_row["derived_body_length"]),
|
||
"repeated_template_status": event_row["repeated_template_status"],
|
||
},
|
||
"body": {
|
||
"end_reason": end_reason,
|
||
"raw_body_sha1": hashlib.sha1(body).hexdigest(),
|
||
"unknown_trailing_bytes": unknown_tail.hex(),
|
||
"decoded_op_count": len(ops),
|
||
"debug_symbol_offset": debug_symbol_offset,
|
||
"debug_symbol_count": len(debug_symbols),
|
||
"field_tag_count": len(field_tags),
|
||
},
|
||
"ops": ops,
|
||
"debug_symbols": debug_symbols,
|
||
"field_tags": field_tags,
|
||
"annotation_hints": annotation_hints(event_row, payload_shape, ops, resolved_extracted_root),
|
||
}
|
||
|
||
|
||
# ---------------------------------------------------------------------------
|
||
# Family diff helpers
|
||
# ---------------------------------------------------------------------------
|
||
|
||
def _common_prefix_len(a: bytes, b: bytes) -> int:
|
||
limit = min(len(a), len(b))
|
||
for i in range(limit):
|
||
if a[i] != b[i]:
|
||
return i
|
||
return limit
|
||
|
||
|
||
def _common_suffix_len(a: bytes, b: bytes, prefix_len: int) -> int:
|
||
la, lb = len(a), len(b)
|
||
limit = min(la - prefix_len, lb - prefix_len)
|
||
for i in range(1, limit + 1):
|
||
if a[la - i] != b[lb - i]:
|
||
return i - 1
|
||
return limit
|
||
|
||
|
||
def compute_family_diff(class_name: str, slot: int, extracted_root: Path | str | None = None) -> dict[str, Any]:
|
||
"""
|
||
Find all event rows that share the same repeated_template_status family tag
|
||
as the named class/slot row, then decode each body and compute pairwise diff
|
||
statistics against the reference body.
|
||
|
||
Returns a dict with:
|
||
reference_entry – entry_index for the named class/slot
|
||
family_tag – repeated_template_status value used for grouping
|
||
sibling_count – number of additional rows in the same family
|
||
members – list of per-member records (entry, class, body stats, diff vs ref)
|
||
"""
|
||
class_event_index, class_layout_index, _, _ = extracted_root_paths(extracted_root)
|
||
event_rows = load_tsv_rows(class_event_index)
|
||
layout_rows = load_tsv_rows(class_layout_index)
|
||
layout_by_entry: dict[int, dict[str, str]] = {}
|
||
for row in layout_rows:
|
||
idx = try_parse_int(row.get("entry_index", ""))
|
||
if idx is not None:
|
||
layout_by_entry[idx] = row
|
||
|
||
# Locate the reference row
|
||
ref_row = next(
|
||
(
|
||
row for row in event_rows
|
||
if row["class_name_hint"].upper() == class_name.upper()
|
||
and try_parse_int(row.get("slot", "")) == slot
|
||
and try_parse_int(row.get("entry_index", "")) is not None
|
||
),
|
||
None,
|
||
)
|
||
if ref_row is None:
|
||
raise KeyError(f"No class_event_index row for class={class_name} slot=0x{slot:02X}")
|
||
|
||
family_tag = ref_row.get("repeated_template_status", "").strip()
|
||
ref_entry = parse_int(ref_row["entry_index"])
|
||
|
||
# Collect family members – same family_tag if non-empty, else same slot
|
||
if family_tag and family_tag not in {"", "unique"}:
|
||
family_rows = [
|
||
row for row in event_rows
|
||
if row.get("repeated_template_status", "").strip() == family_tag
|
||
and try_parse_int(row.get("entry_index", "")) is not None
|
||
]
|
||
else:
|
||
# Fall back: same slot across all classes
|
||
family_rows = [
|
||
row for row in event_rows
|
||
if try_parse_int(row.get("slot", "")) == slot
|
||
and try_parse_int(row.get("entry_index", "")) is not None
|
||
]
|
||
|
||
# Load reference body bytes
|
||
def _load_body(row: dict[str, str]) -> bytes | None:
|
||
body_start_str = row.get("derived_body_start", "")
|
||
body_end_str = row.get("derived_body_end", "")
|
||
if not body_start_str or not body_end_str:
|
||
return None
|
||
try:
|
||
chunk = find_chunk_file(parse_int(row["entry_index"]), extracted_root)
|
||
data = chunk.read_bytes()
|
||
return data[parse_int(body_start_str):parse_int(body_end_str)]
|
||
except (FileNotFoundError, ValueError):
|
||
return None
|
||
|
||
ref_body = _load_body(ref_row)
|
||
if ref_body is None:
|
||
raise ValueError(f"Cannot load reference body for class={class_name} slot=0x{slot:02X}")
|
||
|
||
members: list[dict[str, Any]] = []
|
||
for row in family_rows:
|
||
entry_idx = parse_int(row["entry_index"])
|
||
body = _load_body(row)
|
||
is_ref = entry_idx == ref_entry
|
||
member: dict[str, Any] = {
|
||
"entry_index": entry_idx,
|
||
"class_name": row["class_name_hint"],
|
||
"slot": try_parse_int(row.get("slot", "")),
|
||
"body_length": len(body) if body is not None else None,
|
||
"is_reference": is_ref,
|
||
}
|
||
if body is not None and not is_ref:
|
||
prefix = _common_prefix_len(ref_body, body)
|
||
suffix = _common_suffix_len(ref_body, body, prefix)
|
||
ref_diff_window = ref_body[prefix:len(ref_body) - suffix] if suffix else ref_body[prefix:]
|
||
member_diff_window = body[prefix:len(body) - suffix] if suffix else body[prefix:]
|
||
member["diff_vs_reference"] = {
|
||
"common_prefix_bytes": prefix,
|
||
"common_suffix_bytes": suffix,
|
||
"ref_diff_window_hex": ref_diff_window.hex(),
|
||
"member_diff_window_hex": member_diff_window.hex(),
|
||
"diff_window_length_ref": len(ref_diff_window),
|
||
"diff_window_length_member": len(member_diff_window),
|
||
"identical": ref_body == body,
|
||
}
|
||
elif is_ref:
|
||
member["diff_vs_reference"] = {"identical": True, "note": "reference"}
|
||
members.append(member)
|
||
|
||
members.sort(key=lambda m: (0 if m["is_reference"] else 1, m["entry_index"]))
|
||
|
||
return {
|
||
"reference_entry": ref_entry,
|
||
"reference_class": class_name,
|
||
"slot": slot,
|
||
"family_tag": family_tag or f"slot_0x{slot:02X}_all",
|
||
"member_count": len(members),
|
||
"sibling_count": len(members) - 1,
|
||
"members": members,
|
||
}
|
||
|
||
|
||
def render_family_diff_text(diff: dict[str, Any]) -> str:
|
||
lines = [
|
||
f"Family diff: {diff['family_tag']}",
|
||
f"Reference entry={diff['reference_entry']} class={diff['reference_class']} slot=0x{diff['slot']:02X}",
|
||
f"Members: {diff['member_count']} Siblings: {diff['sibling_count']}",
|
||
"",
|
||
]
|
||
for m in diff["members"]:
|
||
tag = " [REF]" if m["is_reference"] else ""
|
||
body_len = m["body_length"] if m["body_length"] is not None else "?"
|
||
lines.append(f" entry={m['entry_index']} class={m['class_name']} slot=0x{m['slot']:02X} body_len={body_len}{tag}")
|
||
d = m.get("diff_vs_reference")
|
||
if d and not m["is_reference"]:
|
||
if d["identical"]:
|
||
lines.append(" identical to reference")
|
||
else:
|
||
lines.append(f" prefix={d['common_prefix_bytes']} suffix={d['common_suffix_bytes']}")
|
||
lines.append(f" ref_diff_window ({d['diff_window_length_ref']}B): {d['ref_diff_window_hex']}")
|
||
lines.append(f" mem_diff_window ({d['diff_window_length_member']}B): {d['member_diff_window_hex']}")
|
||
return "\n".join(lines) + "\n"
|
||
|
||
|
||
def build_listing_labels(ir: dict[str, Any]) -> dict[int, str]:
|
||
return {
|
||
op["operands"]["target_offset"] + ir["event"]["derived_body_start"]: f"L_{op['operands']['target_offset'] + ir['event']['derived_body_start']:04X}"
|
||
for op in ir["ops"]
|
||
if "target_offset" in op["operands"] and isinstance(op["operands"]["target_offset"], int)
|
||
}
|
||
|
||
|
||
def build_script_blocks(ir: dict[str, Any]) -> tuple[dict[int, str], list[tuple[str, list[dict[str, Any]]]]]:
|
||
ops = ir["ops"]
|
||
if not ops:
|
||
return {}, []
|
||
|
||
branch_mnemonics = {"jne", "jmp", "foreach_list", "foreach_slist"}
|
||
leaders = {ops[0]["absolute_body_offset"]}
|
||
for index, op in enumerate(ops):
|
||
target_offset = op["operands"].get("target_offset")
|
||
if isinstance(target_offset, int):
|
||
leaders.add(ir["event"]["derived_body_start"] + target_offset)
|
||
if op["mnemonic"] in branch_mnemonics and index + 1 < len(ops):
|
||
leaders.add(ops[index + 1]["absolute_body_offset"])
|
||
|
||
ordered_leaders = sorted(leaders)
|
||
label_map = {ordered_leaders[0]: "entry"}
|
||
for absolute_offset in ordered_leaders[1:]:
|
||
label_map[absolute_offset] = f"block_{absolute_offset:04X}"
|
||
|
||
blocks: list[tuple[str, list[dict[str, Any]]]] = []
|
||
current_label = label_map[ops[0]["absolute_body_offset"]]
|
||
current_ops: list[dict[str, Any]] = []
|
||
for op in ops:
|
||
absolute_offset = op["absolute_body_offset"]
|
||
if absolute_offset in label_map and current_ops and label_map[absolute_offset] != current_label:
|
||
blocks.append((current_label, current_ops))
|
||
current_label = label_map[absolute_offset]
|
||
current_ops = []
|
||
current_ops.append(op)
|
||
if current_ops:
|
||
blocks.append((current_label, current_ops))
|
||
return label_map, blocks
|
||
|
||
|
||
def format_script_string(value: str) -> str:
|
||
escaped = value.replace("\\", "\\\\").replace('"', '\\"')
|
||
return f'"{escaped}"'
|
||
|
||
|
||
def format_generic_operands(operands: dict[str, Any], label_map: dict[int, str], body_start: int) -> str:
|
||
parts: list[str] = []
|
||
for key, value in operands.items():
|
||
if value is None or value == "":
|
||
continue
|
||
if key == "target_offset" and isinstance(value, int):
|
||
parts.append(f"target={label_map.get(body_start + value, f'0x{body_start + value:04X}')}")
|
||
continue
|
||
if key == "target_event_name_hint":
|
||
parts.append(f"event={value}")
|
||
continue
|
||
if key == "intrinsic_name_hint":
|
||
parts.append(f"hint={value}")
|
||
continue
|
||
if isinstance(value, int):
|
||
if key.endswith("_signed"):
|
||
parts.append(f"{key}={value}")
|
||
else:
|
||
parts.append(f"{key}=0x{value:X}")
|
||
continue
|
||
parts.append(f"{key}={value}")
|
||
return " ".join(parts)
|
||
|
||
|
||
def format_script_statement(op: dict[str, Any], label_map: dict[int, str], body_start: int) -> str:
|
||
mnemonic = op["mnemonic"]
|
||
operands = op["operands"]
|
||
|
||
if mnemonic == "init":
|
||
return f"init locals 0x{operands['local_bytes']:02X}"
|
||
if mnemonic == "push_byte_immediate":
|
||
return f"push 0x{operands['value_u8']:02X} ; signed {operands['value_signed']}"
|
||
if mnemonic == "push_word_immediate":
|
||
return f"push 0x{operands['value_u16']:04X}"
|
||
if mnemonic == "push_dword_immediate":
|
||
return f"push 0x{operands['value_u32']:08X}"
|
||
if mnemonic == "push_string_immediate":
|
||
return f"push {format_script_string(operands['string'])}"
|
||
if mnemonic.startswith("push_local_") or mnemonic.startswith("push_member_"):
|
||
return f"push {operands['target']}"
|
||
if mnemonic == "push_local_list":
|
||
return f"push {operands['target']}<list:{operands['element_size']}>"
|
||
if mnemonic == "push_list_element":
|
||
return f"push list_element size=0x{operands['element_size']:X} slist=0x{operands['slist_flag']:X}"
|
||
if mnemonic == "push_huge":
|
||
return f"push huge 0x{operands['value_a']:02X}:0x{operands['value_b']:02X}"
|
||
if mnemonic == "push_global":
|
||
return f"push global[0x{operands['global_id']:04X}] size=0x{operands['size']:X}"
|
||
if mnemonic == "push_local_addr":
|
||
return f"push &{operands['target']}"
|
||
if mnemonic == "push_string_ptr":
|
||
return f"push string_ptr {operands['target']}"
|
||
if mnemonic.startswith("pop_local_") or mnemonic.startswith("pop_member_"):
|
||
return f"pop -> {operands['target']}"
|
||
if mnemonic == "pop_local_blob" or mnemonic == "pop_member_blob":
|
||
return f"pop_blob -> {operands['target']} size=0x{operands['size']:X}"
|
||
if mnemonic == "pop_list_element":
|
||
return f"pop_list_element -> {operands['target']} elem_size=0x{operands['element_size']:X} slist=0x{operands['slist_flag']:X}"
|
||
if mnemonic == "pop_global":
|
||
return f"pop -> global[0x{operands['global_id']:04X}] size=0x{operands['size']:X}"
|
||
if mnemonic == "call_intrinsic":
|
||
hint = operands.get("intrinsic_name_hint") or "unknown_intrinsic"
|
||
return f"call intrinsic 0x{operands['intrinsic_ordinal']:04X} {hint} args=0x{operands['arg_bytes']:02X}"
|
||
if mnemonic == "call_near":
|
||
target = label_map.get(body_start + operands["target_offset"], f"0x{body_start + operands['target_offset']:04X}")
|
||
return f"call {target}"
|
||
if mnemonic == "call_class_event":
|
||
return f"call {format_target_event_reference(operands)}"
|
||
if mnemonic in {"append_unique_inline", "append_unique_indirect", "remove_matching_indirect", "remove_matching_inline"}:
|
||
return f"{mnemonic} size=0x{operands['element_size']:X}"
|
||
if mnemonic == "create_list":
|
||
return f"create_list elem_size=0x{operands['element_size']:X} count=0x{operands['count']:X}"
|
||
if mnemonic == "in_list":
|
||
return f"in_list elem_size=0x{operands['element_size']:X} slist=0x{operands['slist_flag']:X}"
|
||
if mnemonic == "jne":
|
||
target = label_map.get(body_start + operands["target_offset"], f"0x{body_start + operands['target_offset']:04X}")
|
||
return f"if pop() != 0 goto {target}"
|
||
if mnemonic == "jmp":
|
||
target = label_map.get(body_start + operands["target_offset"], f"0x{body_start + operands['target_offset']:04X}")
|
||
return f"goto {target}"
|
||
if mnemonic in {"foreach_list", "foreach_slist"}:
|
||
target = label_map.get(body_start + operands["target_offset"], f"0x{body_start + operands['target_offset']:04X}")
|
||
return f"{mnemonic} {operands['target_var']} elem_size=0x{operands['element_size']:X} -> {target}"
|
||
if mnemonic == "spawn":
|
||
return (
|
||
f"spawn {format_target_event_reference(operands)} "
|
||
f"args=0x{operands['arg_bytes']:02X} this_size=0x{operands['this_size']:02X}"
|
||
)
|
||
if mnemonic == "spawn_inline":
|
||
return (
|
||
f"spawn_inline {format_target_event_reference(operands)} "
|
||
f"inline=0x{operands['inline_offset']:04X} this_size=0x{operands['this_size']:02X} unk=0x{operands['unknown']:02X}"
|
||
)
|
||
if mnemonic == "line_number":
|
||
return f"line {operands['line_number']}"
|
||
if mnemonic == "symbol_info":
|
||
return f"symbol_info {operands['symbol']} -> 0x{operands['symbol_offset']:04X}"
|
||
if mnemonic == "global_address":
|
||
return f"push &global[0x{operands['global_id']:04X}]"
|
||
if mnemonic == "ret":
|
||
return "return"
|
||
if mnemonic in NO_ARG_MNEMONICS.values():
|
||
return mnemonic
|
||
|
||
rendered_operands = format_generic_operands(operands, label_map, body_start)
|
||
return f"{mnemonic} {rendered_operands}".rstrip()
|
||
|
||
|
||
def render_script(ir: dict[str, Any]) -> str:
|
||
label_map, blocks = build_script_blocks(ir)
|
||
slot_name = ir["event"]["event_name_hint"] or f"slot_{ir['event']['slot']:02X}"
|
||
lines = [
|
||
(
|
||
f"script {ir['class']['class_name']}.{slot_name} "
|
||
f"(entry={ir['class']['entry_index']}, class_id=0x{ir['class']['class_id']:04X}, slot=0x{ir['event']['slot']:02X})"
|
||
),
|
||
"{",
|
||
f" body_range 0x{ir['event']['derived_body_start']:04X}..0x{ir['event']['derived_body_end']:04X}",
|
||
f" raw_event_word 0x{ir['event']['raw_event_entry_word']:04X}",
|
||
f" raw_code_offset 0x{ir['event']['raw_code_offset']:08X}",
|
||
f" end_reason {ir['body']['end_reason']}",
|
||
]
|
||
|
||
if ir["debug_symbols"]:
|
||
lines.append(" locals")
|
||
lines.append(" {")
|
||
for symbol in ir["debug_symbols"]:
|
||
lines.append(
|
||
f" {symbol['bp_repr']} {symbol['name']} ; type=0x{symbol['type_id']:02X} ('{symbol['type_char']}') unk1=0x{symbol['unknown1']:02X} unk3=0x{symbol['unknown3']:02X}"
|
||
)
|
||
lines.append(" }")
|
||
|
||
lines.append("")
|
||
for label, ops in blocks:
|
||
lines.append(f" {label}:")
|
||
for op in ops:
|
||
statement = format_script_statement(op, label_map, ir["event"]["derived_body_start"])
|
||
lines.append(f" {statement} ; {op['absolute_body_offset']:04X}: {op['raw_bytes']}")
|
||
lines.append("")
|
||
|
||
if ir["field_tags"]:
|
||
lines.append(" field_tags")
|
||
lines.append(" {")
|
||
for tag in ir["field_tags"]:
|
||
lines.append(
|
||
f" {tag['bp_repr']} {tag['name']} ; tag=0x{tag['tag_id']:02X} kind=0x{tag['value_kind']:02X}"
|
||
)
|
||
lines.append(" }")
|
||
|
||
if ir["body"]["unknown_trailing_bytes"]:
|
||
lines.append(f" unknown_trailing_bytes {ir['body']['unknown_trailing_bytes']}")
|
||
|
||
lines.append("}")
|
||
return "\n".join(lines) + "\n"
|
||
|
||
|
||
def sanitize_identifier(name: str) -> str:
|
||
cleaned = [char if char.isalnum() or char == "_" else "_" for char in name.strip()]
|
||
identifier = "".join(cleaned).strip("_") or "var"
|
||
if identifier[0].isdigit():
|
||
identifier = f"v_{identifier}"
|
||
return identifier
|
||
|
||
|
||
def target_event_display_name(operands: dict[str, Any]) -> str:
|
||
class_id = operands["target_class_id"]
|
||
slot = operands["target_event_slot"]
|
||
return CLASS_EVENT_NAME_HINTS.get((class_id, slot)) or operands.get("target_event_name_hint") or f"slot_{slot:02X}"
|
||
|
||
|
||
def format_target_event_reference(operands: dict[str, Any]) -> str:
|
||
class_name_hint = operands.get("target_class_name_hint")
|
||
event_name = sanitize_identifier(target_event_display_name(operands))
|
||
if class_name_hint:
|
||
return f"{sanitize_identifier(class_name_hint)}.{event_name}"
|
||
return f"class_{operands['target_class_id']:04X}_{event_name}"
|
||
|
||
|
||
def build_local_name_map(ir: dict[str, Any]) -> dict[int, str]:
|
||
return {
|
||
symbol["bp_offset"]: sanitize_identifier(symbol["name"])
|
||
for symbol in ir["debug_symbols"]
|
||
}
|
||
|
||
|
||
def format_bp_name(bp_offset: int, local_name_map: dict[int, str]) -> str:
|
||
if bp_offset in local_name_map:
|
||
return local_name_map[bp_offset]
|
||
disp = signed_byte(bp_offset)
|
||
if disp >= 0:
|
||
return f"arg_{disp:02X}"
|
||
return f"local_{abs(disp):02X}"
|
||
|
||
|
||
def intrinsic_display_name(name_hint: str | None, ordinal: int) -> str:
|
||
if not name_hint:
|
||
return f"intrinsic_{ordinal:04X}"
|
||
display = name_hint.replace("::", ".")
|
||
display = re.sub(r"(?<=\.)I_", "", display)
|
||
if display.startswith("I_"):
|
||
display = display[2:]
|
||
paren = display.find("(")
|
||
if paren != -1:
|
||
display = display[:paren]
|
||
return display
|
||
|
||
|
||
def push_expr_from_op(op: dict[str, Any], local_name_map: dict[int, str]) -> tuple[str, int] | None:
|
||
mnemonic = op["mnemonic"]
|
||
operands = op["operands"]
|
||
|
||
if mnemonic == "push_byte_immediate":
|
||
return (str(operands["value_signed"]), 1)
|
||
if mnemonic == "push_word_immediate":
|
||
return (f"0x{operands['value_u16']:04X}", 2)
|
||
if mnemonic == "push_dword_immediate":
|
||
return (f"0x{operands['value_u32']:08X}", 4)
|
||
if mnemonic == "push_string_immediate":
|
||
return (format_script_string(operands["string"]), max(2, operands["declared_length"]))
|
||
if mnemonic in {"push_local_byte", "push_local_word", "push_local_dword", "push_local_string", "push_local_slist", "push_local_addr", "push_string_ptr"}:
|
||
return (format_bp_name(operands["bp_offset"], local_name_map), 4 if mnemonic in {"push_local_dword", "push_local_addr", "push_string_ptr"} else 2)
|
||
if mnemonic in {"push_member_byte", "push_member_word", "push_member_dword", "push_member_huge"}:
|
||
return (f"member.{format_bp_name(operands['bp_offset'], local_name_map)}", 4 if mnemonic in {"push_member_dword", "push_member_huge"} else 2)
|
||
if mnemonic == "push_local_list":
|
||
return (format_bp_name(operands["bp_offset"], local_name_map), max(2, operands["element_size"]))
|
||
if mnemonic == "push_list_element":
|
||
return (f"list_element(size=0x{operands['element_size']:X})", max(1, operands["element_size"]))
|
||
if mnemonic == "push_huge":
|
||
return (f"0x{operands['value_a']:02X}{operands['value_b']:02X}", 4)
|
||
if mnemonic == "push_global":
|
||
return (f"global[0x{operands['global_id']:04X}]", max(1, operands["size"]))
|
||
if mnemonic == "push_pid":
|
||
return ("pid", 2)
|
||
if mnemonic == "push_process_result":
|
||
return ("process_result", 2)
|
||
return None
|
||
|
||
|
||
def pop_stack_bytes(stack: list[tuple[str, int]], byte_count: int) -> list[str]:
|
||
if byte_count <= 0:
|
||
return []
|
||
parts: list[str] = []
|
||
consumed = 0
|
||
while stack and consumed < byte_count:
|
||
expr, width = stack.pop()
|
||
parts.append(expr)
|
||
consumed += max(1, width)
|
||
parts.reverse()
|
||
return parts
|
||
|
||
|
||
def combine_binary(stack: list[tuple[str, int]], operator: str, result_width: int = 2) -> None:
|
||
if len(stack) < 2:
|
||
return
|
||
right_expr, _ = stack.pop()
|
||
left_expr, _ = stack.pop()
|
||
stack.append((f"({left_expr} {operator} {right_expr})", result_width))
|
||
|
||
|
||
def evaluate_loop_setup_op(
|
||
op: dict[str, Any],
|
||
stack: list[tuple[str, int]],
|
||
local_name_map: dict[int, str],
|
||
) -> bool:
|
||
pushed = push_expr_from_op(op, local_name_map)
|
||
if pushed is not None:
|
||
stack.append(pushed)
|
||
return True
|
||
|
||
mnemonic = op["mnemonic"]
|
||
operands = op["operands"]
|
||
if mnemonic == "push_indirect":
|
||
if stack:
|
||
expr, _ = stack.pop()
|
||
stack.append((f"*({expr})", max(1, operands["size"])))
|
||
return True
|
||
if mnemonic in {"add", "add_dword"}:
|
||
combine_binary(stack, "+", 4 if mnemonic.endswith("dword") else 2)
|
||
return True
|
||
if mnemonic in {"sub", "sub_dword"}:
|
||
combine_binary(stack, "-", 4 if mnemonic.endswith("dword") else 2)
|
||
return True
|
||
if mnemonic in {"mul", "mul_dword"}:
|
||
combine_binary(stack, "*", 4 if mnemonic.endswith("dword") else 2)
|
||
return True
|
||
if mnemonic in {"div", "div_dword"}:
|
||
combine_binary(stack, "/", 4 if mnemonic.endswith("dword") else 2)
|
||
return True
|
||
if mnemonic == "line_number":
|
||
return True
|
||
return False
|
||
|
||
|
||
def normalize_loop_origin(expr: str) -> str:
|
||
normalized = expr.strip()
|
||
if normalized.startswith("*(") and normalized.endswith(")"):
|
||
return normalized[2:-1]
|
||
return normalized
|
||
|
||
|
||
def try_decode_loop_selector(
|
||
ops: list[dict[str, Any]],
|
||
start_index: int,
|
||
local_name_map: dict[int, str],
|
||
) -> tuple[str, int] | None:
|
||
selector_tokens: list[int] = []
|
||
selector_stack: list[tuple[str, int]] = []
|
||
index = start_index
|
||
|
||
while index < len(ops):
|
||
op = ops[index]
|
||
mnemonic = op["mnemonic"]
|
||
if mnemonic == "loopscr":
|
||
selector_tokens.append(op["operands"]["value_u8"])
|
||
index += 1
|
||
continue
|
||
if mnemonic == "loop":
|
||
break
|
||
if not evaluate_loop_setup_op(op, selector_stack, local_name_map):
|
||
return None
|
||
index += 1
|
||
|
||
if index >= len(ops) or ops[index]["mnemonic"] != "loop":
|
||
return None
|
||
|
||
loop_operands = ops[index]["operands"]
|
||
if loop_operands.get("string_bytes") != 0x6 or loop_operands.get("loop_type") != 0x2:
|
||
return None
|
||
if len(selector_tokens) != 4 or selector_tokens[0] != 0x24 or selector_tokens[1] != 0x3D or selector_tokens[3] != 0x25:
|
||
if selector_tokens == [0x24, 0x42] and len(selector_stack) >= 4:
|
||
current_var = format_bp_name(loop_operands["current_var"], local_name_map)
|
||
return (
|
||
f"{current_var} in {generic_loop_selector_call('selector_0x42', [
|
||
('arg0', selector_stack[-4][0]),
|
||
('arg1', selector_stack[-3][0]),
|
||
('arg2', selector_stack[-2][0]),
|
||
('origin', normalize_loop_origin(selector_stack[-1][0])),
|
||
])}",
|
||
index + 1,
|
||
)
|
||
return None
|
||
selector_field = LOOP_SELECTOR_FIELD_HINTS.get(selector_tokens[2])
|
||
if selector_field is None or len(selector_stack) < 3:
|
||
return None
|
||
|
||
current_var = format_bp_name(loop_operands["current_var"], local_name_map)
|
||
selector_value = selector_stack[-3][0]
|
||
origin_expr = normalize_loop_origin(selector_stack[-1][0])
|
||
return (
|
||
f"{current_var} in nearby_items({selector_field}={selector_value}, origin={origin_expr})",
|
||
index + 1,
|
||
)
|
||
|
||
|
||
def loop_selector_statement(selector_text: str) -> str:
|
||
return f"/* loop_selector {selector_text} */"
|
||
|
||
|
||
def decompile_pseudocode_blocks(ir: dict[str, Any]) -> list[tuple[str, list[str]]]:
|
||
label_map, blocks = build_script_blocks(ir)
|
||
local_name_map = build_local_name_map(ir)
|
||
skip_mnemonics = {"line_number", "symbol_info", "add_sp", "init"}
|
||
pending_result: str | None
|
||
rendered_blocks: list[tuple[str, list[str]]] = []
|
||
|
||
for label, ops in blocks:
|
||
stack: list[tuple[str, int]] = []
|
||
pending_result = None
|
||
block_lines: list[str] = []
|
||
index = 0
|
||
while index < len(ops):
|
||
op = ops[index]
|
||
mnemonic = op["mnemonic"]
|
||
operands = op["operands"]
|
||
|
||
if mnemonic == "loopscr":
|
||
decoded_loop = try_decode_loop_selector(ops, index, local_name_map)
|
||
if decoded_loop is not None:
|
||
selector_text, next_index = decoded_loop
|
||
block_lines.append(loop_selector_statement(selector_text))
|
||
stack.clear()
|
||
pending_result = None
|
||
index = next_index
|
||
continue
|
||
|
||
pushed = push_expr_from_op(op, local_name_map)
|
||
if pushed is not None:
|
||
stack.append(pushed)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in skip_mnemonics:
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "push_indirect":
|
||
if stack:
|
||
expr, _ = stack.pop()
|
||
stack.append((f"*({expr})", max(1, operands["size"])))
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "set_info":
|
||
args = ", ".join(expr for expr, _ in stack) if stack else ""
|
||
stack.clear()
|
||
block_lines.append(f"set_info({args});")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "process_exclude":
|
||
block_lines.append("process_exclude();")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "call_intrinsic":
|
||
arg_exprs = pop_stack_bytes(stack, operands["arg_bytes"])
|
||
pending_result = f"{intrinsic_display_name(operands.get('intrinsic_name_hint'), operands['intrinsic_ordinal'])}({', '.join(arg_exprs)})"
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "push_retval_byte":
|
||
stack.append((pending_result or "retval", 1))
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "push_retval_word":
|
||
stack.append((pending_result or "retval", 2))
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "push_retval_dword":
|
||
stack.append((pending_result or "retval", 4))
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "call_class_event":
|
||
arg_text = ", ".join(expr for expr, _ in stack)
|
||
stack.clear()
|
||
block_lines.append(f"{format_target_event_reference(operands)}({arg_text});")
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "spawn":
|
||
arg_text = ", ".join(expr for expr, _ in stack)
|
||
stack.clear()
|
||
block_lines.append(f"spawn {format_target_event_reference(operands)}({arg_text});")
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "spawn_inline":
|
||
arg_text = ", ".join(expr for expr, _ in stack)
|
||
stack.clear()
|
||
block_lines.append(
|
||
f"spawn_inline {format_target_event_reference(operands)}({arg_text}) /* inline=0x{operands['inline_offset']:04X} */;"
|
||
)
|
||
pending_result = None
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in {"add", "add_dword"}:
|
||
combine_binary(stack, "+", 4 if mnemonic.endswith("dword") else 2)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in {"sub", "sub_dword"}:
|
||
combine_binary(stack, "-", 4 if mnemonic.endswith("dword") else 2)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in {"mul", "mul_dword"}:
|
||
combine_binary(stack, "*", 4 if mnemonic.endswith("dword") else 2)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in {"div", "div_dword"}:
|
||
combine_binary(stack, "/", 4 if mnemonic.endswith("dword") else 2)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "bit_and":
|
||
combine_binary(stack, "&")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "bit_or":
|
||
combine_binary(stack, "|")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "and":
|
||
combine_binary(stack, "&&")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "or":
|
||
combine_binary(stack, "||")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "cmp":
|
||
combine_binary(stack, "!=")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "ne":
|
||
combine_binary(stack, "!=")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "lt":
|
||
combine_binary(stack, "<")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "le":
|
||
combine_binary(stack, "<=")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "gt":
|
||
combine_binary(stack, ">")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "ge":
|
||
combine_binary(stack, ">=")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "not":
|
||
if stack:
|
||
expr, width = stack.pop()
|
||
stack.append((f"(!{expr})", width))
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "implies":
|
||
expr = stack.pop()[0] if stack else "retval"
|
||
stack.append((f"implies({expr}, 0x{operands['arg0']:X}, 0x{operands['arg1']:X})", 1))
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "pop_temp":
|
||
if stack:
|
||
stack.pop()
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "suspend":
|
||
block_lines.append("suspend;")
|
||
stack.clear()
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "jne":
|
||
target = label_map.get(ir["event"]["derived_body_start"] + operands["target_offset"], f"block_{ir['event']['derived_body_start'] + operands['target_offset']:04X}")
|
||
condition = stack.pop()[0] if stack else "condition"
|
||
block_lines.append(f"if {condition} goto {target};")
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "jmp":
|
||
target = label_map.get(ir["event"]["derived_body_start"] + operands["target_offset"], f"block_{ir['event']['derived_body_start'] + operands['target_offset']:04X}")
|
||
block_lines.append(f"goto {target};")
|
||
stack.clear()
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic in {"foreach_list", "foreach_slist"}:
|
||
target = label_map.get(ir["event"]["derived_body_start"] + operands["target_offset"], f"block_{ir['event']['derived_body_start'] + operands['target_offset']:04X}")
|
||
block_lines.append(
|
||
f"{mnemonic} {format_bp_name(operands['bp_offset'], local_name_map)} -> {target};"
|
||
)
|
||
index += 1
|
||
continue
|
||
|
||
if mnemonic == "ret":
|
||
block_lines.append("return;")
|
||
stack.clear()
|
||
break
|
||
|
||
if mnemonic.startswith("pop_local_") or mnemonic.startswith("pop_member_"):
|
||
if stack:
|
||
expr, _ = stack.pop()
|
||
else:
|
||
expr = "value"
|
||
target_name = format_bp_name(operands["bp_offset"], local_name_map)
|
||
block_lines.append(f"{target_name} = {expr};")
|
||
index += 1
|
||
continue
|
||
|
||
rendered_operands = format_generic_operands(operands, label_map, ir["event"]["derived_body_start"])
|
||
block_lines.append(f"/* {mnemonic} {rendered_operands} */")
|
||
index += 1
|
||
|
||
rendered_blocks.append((label, block_lines))
|
||
|
||
return rendered_blocks
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class TerminalStatement:
|
||
kind: str
|
||
condition: str | None = None
|
||
target: str | None = None
|
||
|
||
|
||
def parse_terminal_statement(statement: str) -> TerminalStatement | None:
|
||
if statement == "return;":
|
||
return TerminalStatement("return")
|
||
|
||
goto_match = re.fullmatch(r"goto ([A-Za-z0-9_]+);", statement)
|
||
if goto_match is not None:
|
||
return TerminalStatement("goto", target=goto_match.group(1))
|
||
|
||
if_match = re.fullmatch(r"if (.+) goto ([A-Za-z0-9_]+);", statement)
|
||
if if_match is not None:
|
||
return TerminalStatement("if", condition=if_match.group(1), target=if_match.group(2))
|
||
|
||
return None
|
||
|
||
|
||
def strip_outer_parens(expr: str) -> str:
|
||
text = expr.strip()
|
||
while text.startswith("(") and text.endswith(")"):
|
||
depth = 0
|
||
balanced = True
|
||
for index, char in enumerate(text):
|
||
if char == "(":
|
||
depth += 1
|
||
elif char == ")":
|
||
depth -= 1
|
||
if depth == 0 and index != len(text) - 1:
|
||
balanced = False
|
||
break
|
||
if depth < 0:
|
||
balanced = False
|
||
break
|
||
if not balanced or depth != 0:
|
||
break
|
||
text = text[1:-1].strip()
|
||
return text
|
||
|
||
|
||
def invert_condition_text(condition: str) -> str:
|
||
expr = strip_outer_parens(condition)
|
||
comparisons = {
|
||
" != ": " == ",
|
||
" == ": " != ",
|
||
" <= ": " > ",
|
||
" >= ": " < ",
|
||
" < ": " >= ",
|
||
" > ": " <= ",
|
||
}
|
||
for source, replacement in comparisons.items():
|
||
if source in expr:
|
||
return expr.replace(source, replacement, 1)
|
||
if expr.startswith("!"):
|
||
return strip_outer_parens(expr[1:])
|
||
if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_:.]*(\(.*\))?", expr):
|
||
return f"!{expr}"
|
||
return f"!({expr})"
|
||
|
||
|
||
def indent_lines(lines: list[str], prefix: str = " ") -> list[str]:
|
||
return [f"{prefix}{line}" if line else "" for line in lines]
|
||
|
||
|
||
def detect_noop_compare_chain(
|
||
blocks: list[tuple[str, list[str]]],
|
||
label_to_index: dict[str, int],
|
||
start_index: int,
|
||
end_index: int,
|
||
) -> int | None:
|
||
cursor = start_index
|
||
common_target: str | None = None
|
||
|
||
while cursor + 1 < end_index:
|
||
_, compare_statements = blocks[cursor]
|
||
_, goto_statements = blocks[cursor + 1]
|
||
if len(compare_statements) != 1 or len(goto_statements) != 1:
|
||
return None
|
||
|
||
compare_terminal = parse_terminal_statement(compare_statements[0])
|
||
goto_terminal = parse_terminal_statement(goto_statements[0])
|
||
if compare_terminal is None or compare_terminal.kind != "if":
|
||
return None
|
||
if goto_terminal is None or goto_terminal.kind != "goto":
|
||
return None
|
||
|
||
if common_target is None:
|
||
common_target = goto_terminal.target
|
||
elif goto_terminal.target != common_target:
|
||
return None
|
||
|
||
if compare_terminal.target == common_target:
|
||
body_index = label_to_index.get(common_target or "")
|
||
if body_index is None or body_index != cursor + 2 or body_index >= end_index:
|
||
return None
|
||
return body_index
|
||
|
||
next_index = label_to_index.get(compare_terminal.target or "")
|
||
if next_index is None or next_index != cursor + 2 or next_index >= end_index:
|
||
return None
|
||
cursor += 2
|
||
|
||
return None
|
||
|
||
|
||
def last_nonempty_block_index(
|
||
blocks: list[tuple[str, list[str]]],
|
||
start_index: int,
|
||
end_index: int,
|
||
) -> int | None:
|
||
for index in range(end_index - 1, start_index - 1, -1):
|
||
if blocks[index][1]:
|
||
return index
|
||
return None
|
||
|
||
|
||
def parse_selector_condition(condition: str) -> tuple[str, str] | None:
|
||
expr = strip_outer_parens(condition)
|
||
match = re.fullmatch(r"(.+?)\s*!=\s*(.+)", expr)
|
||
if match is None:
|
||
return None
|
||
return match.group(1).strip(), match.group(2).strip()
|
||
|
||
|
||
def parse_loop_selector_statement(statement: str) -> str | None:
|
||
match = re.fullmatch(r"/\* loop_selector (.+) \*/", statement)
|
||
if match is None:
|
||
return None
|
||
return match.group(1)
|
||
|
||
|
||
def is_loop_selector_only_block(statements: list[str]) -> bool:
|
||
return len(statements) == 1 and parse_loop_selector_statement(statements[0]) is not None
|
||
|
||
|
||
def render_selector_chain(
|
||
blocks: list[tuple[str, list[str]]],
|
||
label_to_index: dict[str, int],
|
||
start_index: int,
|
||
end_index: int,
|
||
return_labels: set[str],
|
||
active_regions: set[tuple[int, int, tuple[str, ...]]] | None = None,
|
||
render_cache: dict[tuple[int, int, tuple[str, ...]], tuple[list[str], bool] | None] | None = None,
|
||
) -> tuple[list[str], int] | None:
|
||
if not blocks[start_index][1]:
|
||
return None
|
||
base_terminal = parse_terminal_statement(blocks[start_index][1][-1])
|
||
if base_terminal is None or base_terminal.kind != "if":
|
||
return None
|
||
|
||
selector = parse_selector_condition(base_terminal.condition or "")
|
||
if selector is None:
|
||
return None
|
||
selector_expr, _ = selector
|
||
|
||
cursor = start_index
|
||
join_label: str | None = None
|
||
branches: list[tuple[str, list[str]]] = []
|
||
|
||
while cursor < end_index:
|
||
_, statements = blocks[cursor]
|
||
if not statements:
|
||
return None
|
||
terminal = parse_terminal_statement(statements[-1])
|
||
if terminal is None or terminal.kind != "if":
|
||
return None
|
||
|
||
parsed = parse_selector_condition(terminal.condition or "")
|
||
if parsed is None or parsed[0] != selector_expr:
|
||
return None
|
||
|
||
target_label = terminal.target or ""
|
||
target_index = label_to_index.get(target_label)
|
||
if target_index is None or target_index <= cursor + 1 or target_index > end_index:
|
||
return None
|
||
|
||
body_tail_index = last_nonempty_block_index(blocks, cursor + 1, target_index)
|
||
if body_tail_index is None:
|
||
return None
|
||
body_tail_terminal = parse_terminal_statement(blocks[body_tail_index][1][-1])
|
||
if body_tail_terminal is None or body_tail_terminal.kind != "goto":
|
||
return None
|
||
|
||
current_join = body_tail_terminal.target or ""
|
||
current_join_index = label_to_index.get(current_join)
|
||
if current_join_index is None or current_join_index > end_index:
|
||
return None
|
||
if current_join_index < target_index:
|
||
return None
|
||
if current_join_index == target_index and target_label != current_join:
|
||
return None
|
||
if join_label is None:
|
||
join_label = current_join
|
||
elif current_join != join_label:
|
||
return None
|
||
|
||
body_result = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
cursor + 1,
|
||
target_index,
|
||
return_labels,
|
||
{join_label},
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if body_result is None:
|
||
return None
|
||
body_lines, _ = body_result
|
||
branches.append((invert_condition_text(terminal.condition or "condition"), body_lines))
|
||
|
||
if target_label == join_label:
|
||
break
|
||
cursor = target_index
|
||
|
||
if join_label is None:
|
||
return None
|
||
|
||
rendered: list[str] = []
|
||
for index, (condition, body_lines) in enumerate(branches):
|
||
branch_head = "if" if index == 0 else "else if"
|
||
rendered.append(f"{branch_head} ({condition}) {{")
|
||
rendered.extend(indent_lines(body_lines))
|
||
rendered.append("}")
|
||
|
||
return rendered, label_to_index[join_label]
|
||
|
||
|
||
def render_loop_construct(
|
||
blocks: list[tuple[str, list[str]]],
|
||
label_to_index: dict[str, int],
|
||
index: int,
|
||
end_index: int,
|
||
return_labels: set[str],
|
||
active_regions: set[tuple[int, int, tuple[str, ...]]] | None = None,
|
||
render_cache: dict[tuple[int, int, tuple[str, ...]], tuple[list[str], bool] | None] | None = None,
|
||
) -> tuple[list[str], int] | None:
|
||
_, statements = blocks[index]
|
||
if not statements:
|
||
return None
|
||
|
||
terminal = parse_terminal_statement(statements[-1])
|
||
if terminal is None or terminal.kind != "if":
|
||
return None
|
||
|
||
target_label = terminal.target or ""
|
||
target_index = label_to_index.get(target_label)
|
||
if target_index is None or target_index <= index or target_index > end_index:
|
||
return None
|
||
|
||
loop_tail_index = last_nonempty_block_index(blocks, index + 1, target_index)
|
||
if loop_tail_index is None:
|
||
return None
|
||
|
||
loop_tail_terminal = parse_terminal_statement(blocks[loop_tail_index][1][-1])
|
||
if loop_tail_terminal is None or loop_tail_terminal.kind != "goto" or loop_tail_terminal.target != blocks[index][0]:
|
||
return None
|
||
|
||
loop_body = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
index + 1,
|
||
target_index,
|
||
return_labels,
|
||
{blocks[index][0]},
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if loop_body is None:
|
||
return None
|
||
|
||
loop_lines, _ = loop_body
|
||
loop_selector = None
|
||
if index > 0 and is_loop_selector_only_block(blocks[index - 1][1]):
|
||
loop_selector = parse_loop_selector_statement(blocks[index - 1][1][0])
|
||
|
||
rendered: list[str] = []
|
||
if loop_selector is not None:
|
||
rendered.append(f"for {loop_selector} {{")
|
||
else:
|
||
rendered.append(f"while ({invert_condition_text(terminal.condition or 'condition')}) {{")
|
||
rendered.extend(indent_lines(loop_lines))
|
||
rendered.append("}")
|
||
return rendered, target_index
|
||
|
||
|
||
def render_infinite_loop_construct(
|
||
blocks: list[tuple[str, list[str]]],
|
||
label_to_index: dict[str, int],
|
||
index: int,
|
||
end_index: int,
|
||
return_labels: set[str],
|
||
active_regions: set[tuple[int, int, tuple[str, ...]]] | None = None,
|
||
render_cache: dict[tuple[int, int, tuple[str, ...]], tuple[list[str], bool] | None] | None = None,
|
||
) -> tuple[list[str], int] | None:
|
||
if index + 1 >= end_index:
|
||
return None
|
||
|
||
loop_label = blocks[index][0]
|
||
loop_tail_index: int | None = None
|
||
for candidate in range(end_index - 1, index, -1):
|
||
statements = blocks[candidate][1]
|
||
if not statements:
|
||
continue
|
||
terminal = parse_terminal_statement(statements[-1])
|
||
if terminal is not None and terminal.kind == "goto" and terminal.target == loop_label:
|
||
loop_tail_index = candidate
|
||
break
|
||
|
||
if loop_tail_index is None:
|
||
return None
|
||
|
||
loop_body = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
index,
|
||
loop_tail_index + 1,
|
||
return_labels,
|
||
{loop_label},
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if loop_body is None:
|
||
return None
|
||
|
||
loop_lines, _ = loop_body
|
||
rendered = ["while (true) {"]
|
||
rendered.extend(indent_lines(loop_lines))
|
||
rendered.append("}")
|
||
return rendered, loop_tail_index + 1
|
||
|
||
|
||
def render_structured_region(
|
||
blocks: list[tuple[str, list[str]]],
|
||
label_to_index: dict[str, int],
|
||
start_index: int,
|
||
end_index: int,
|
||
return_labels: set[str],
|
||
exit_labels: set[str] | None = None,
|
||
active_regions: set[tuple[int, int, tuple[str, ...]]] | None = None,
|
||
render_cache: dict[tuple[int, int, tuple[str, ...]], tuple[list[str], bool] | None] | None = None,
|
||
) -> tuple[list[str], bool] | None:
|
||
region_key = (start_index, end_index, tuple(sorted(exit_labels or ())))
|
||
if render_cache is not None and region_key in render_cache:
|
||
return render_cache[region_key]
|
||
if active_regions is None:
|
||
active_regions = set()
|
||
elif region_key in active_regions:
|
||
return None
|
||
|
||
active_regions = set(active_regions)
|
||
active_regions.add(region_key)
|
||
allowed_exit_labels = set(exit_labels or ())
|
||
lines: list[str] = []
|
||
index = start_index
|
||
|
||
while index < end_index:
|
||
skipped_index = detect_noop_compare_chain(blocks, label_to_index, index, end_index)
|
||
if skipped_index is not None:
|
||
index = skipped_index
|
||
continue
|
||
|
||
_, statements = blocks[index]
|
||
if not statements:
|
||
index += 1
|
||
continue
|
||
if is_loop_selector_only_block(statements):
|
||
index += 1
|
||
continue
|
||
|
||
terminal = parse_terminal_statement(statements[-1])
|
||
if terminal is None:
|
||
lines.extend(statements)
|
||
index += 1
|
||
continue
|
||
|
||
lines.extend(statements[:-1])
|
||
|
||
if terminal.kind == "return":
|
||
lines.append("return;")
|
||
return lines, False
|
||
|
||
if terminal.kind == "goto":
|
||
target_label = terminal.target or ""
|
||
target_index = label_to_index.get(target_label)
|
||
if target_label in return_labels:
|
||
lines.append("return;")
|
||
return lines, False
|
||
if target_label in allowed_exit_labels:
|
||
return lines, False
|
||
if target_index is None:
|
||
return None
|
||
if target_index == index + 1:
|
||
index += 1
|
||
continue
|
||
if index < target_index < end_index:
|
||
index = target_index
|
||
continue
|
||
return None
|
||
|
||
target_label = terminal.target or ""
|
||
target_index = label_to_index.get(target_label)
|
||
if target_index is None or target_index <= index or target_index > end_index:
|
||
return None
|
||
if target_index == index + 1:
|
||
index += 1
|
||
continue
|
||
|
||
selector_chain = render_selector_chain(
|
||
blocks,
|
||
label_to_index,
|
||
index,
|
||
end_index,
|
||
return_labels,
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if selector_chain is not None:
|
||
selector_lines, selector_join_index = selector_chain
|
||
lines.extend(selector_lines)
|
||
index = selector_join_index
|
||
continue
|
||
|
||
loop_construct = render_loop_construct(
|
||
blocks,
|
||
label_to_index,
|
||
index,
|
||
end_index,
|
||
return_labels,
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if loop_construct is not None:
|
||
loop_lines, loop_join_index = loop_construct
|
||
lines.extend(loop_lines)
|
||
index = loop_join_index
|
||
continue
|
||
|
||
true_tail_index = last_nonempty_block_index(blocks, index + 1, target_index)
|
||
if true_tail_index is not None:
|
||
true_tail_terminal = parse_terminal_statement(blocks[true_tail_index][1][-1])
|
||
if true_tail_terminal is not None and true_tail_terminal.kind == "goto":
|
||
join_label = true_tail_terminal.target or ""
|
||
join_index = label_to_index.get(join_label)
|
||
if join_index is not None and join_index > target_index and join_index <= end_index:
|
||
true_result = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
index + 1,
|
||
target_index,
|
||
return_labels,
|
||
{join_label},
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
false_result = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
target_index,
|
||
join_index,
|
||
return_labels,
|
||
{join_label},
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if true_result is not None and false_result is not None:
|
||
true_lines, _ = true_result
|
||
false_lines, _ = false_result
|
||
lines.append(f"if ({invert_condition_text(terminal.condition or 'condition')}) {{")
|
||
lines.extend(indent_lines(true_lines))
|
||
lines.append("}")
|
||
if false_lines:
|
||
if false_lines[0].startswith("if "):
|
||
lines.append(f"else {false_lines[0]}")
|
||
lines.extend(false_lines[1:])
|
||
else:
|
||
lines.append("else {")
|
||
lines.extend(indent_lines(false_lines))
|
||
lines.append("}")
|
||
index = join_index
|
||
continue
|
||
|
||
inner_result = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
index + 1,
|
||
target_index,
|
||
return_labels,
|
||
None,
|
||
active_regions,
|
||
render_cache,
|
||
)
|
||
if inner_result is None:
|
||
if render_cache is not None:
|
||
render_cache[region_key] = None
|
||
return None
|
||
|
||
inner_lines, inner_falls_through = inner_result
|
||
if inner_lines:
|
||
lines.append(f"if ({invert_condition_text(terminal.condition or 'condition')}) {{")
|
||
lines.extend(indent_lines(inner_lines))
|
||
lines.append("}")
|
||
elif not inner_falls_through:
|
||
lines.append(f"if ({invert_condition_text(terminal.condition or 'condition')}) {{")
|
||
lines.append("}")
|
||
|
||
index = target_index
|
||
|
||
result = (lines, True)
|
||
if render_cache is not None:
|
||
render_cache[region_key] = result
|
||
return result
|
||
|
||
|
||
def render_structured_pseudocode(blocks: list[tuple[str, list[str]]]) -> list[str] | None:
|
||
if not blocks:
|
||
return []
|
||
|
||
label_to_index = {label: index for index, (label, _) in enumerate(blocks)}
|
||
return_labels = {
|
||
label
|
||
for label, statements in blocks
|
||
if len(statements) == 1 and statements[0] == "return;"
|
||
}
|
||
render_cache: dict[tuple[int, int, tuple[str, ...]], tuple[list[str], bool] | None] = {}
|
||
structured = render_structured_region(blocks, label_to_index, 0, len(blocks), return_labels, None, None, render_cache)
|
||
if structured is None:
|
||
return None
|
||
return structured[0]
|
||
|
||
|
||
def render_partially_structured_blocks(blocks: list[tuple[str, list[str]]]) -> list[str]:
|
||
if not blocks:
|
||
return []
|
||
|
||
label_to_index = {label: index for index, (label, _) in enumerate(blocks)}
|
||
return_labels = {
|
||
label
|
||
for label, statements in blocks
|
||
if len(statements) == 1 and statements[0] == "return;"
|
||
}
|
||
|
||
lines: list[str] = []
|
||
index = 0
|
||
while index < len(blocks):
|
||
label, statements = blocks[index]
|
||
if is_loop_selector_only_block(statements):
|
||
loop_selector = parse_loop_selector_statement(statements[0])
|
||
if loop_selector is not None and index + 1 < len(blocks):
|
||
next_label, next_statements = blocks[index + 1]
|
||
next_terminal = parse_terminal_statement(next_statements[-1]) if next_statements else None
|
||
if next_terminal is not None and next_terminal.kind == "if":
|
||
target_index = label_to_index.get(next_terminal.target or "")
|
||
if target_index is not None and target_index > index + 1:
|
||
loop_tail_index = last_nonempty_block_index(blocks, index + 2, target_index)
|
||
if loop_tail_index is not None:
|
||
loop_tail_terminal = parse_terminal_statement(blocks[loop_tail_index][1][-1])
|
||
if loop_tail_terminal is not None and loop_tail_terminal.kind == "goto" and loop_tail_terminal.target == next_label:
|
||
loop_body = render_structured_region(
|
||
blocks,
|
||
label_to_index,
|
||
index + 2,
|
||
target_index,
|
||
return_labels,
|
||
{next_label},
|
||
)
|
||
if loop_body is not None:
|
||
loop_lines, _ = loop_body
|
||
lines.append(f" {label}:")
|
||
lines.append(f" for {loop_selector} {{")
|
||
lines.extend(f" {line}" for line in indent_lines(loop_lines))
|
||
lines.append(" }")
|
||
lines.append("")
|
||
index = target_index
|
||
continue
|
||
|
||
lines.append(f" {label}:")
|
||
lines.append(f" {statements[0]}")
|
||
lines.append("")
|
||
index += 1
|
||
continue
|
||
selector_chain = render_selector_chain(blocks, label_to_index, index, len(blocks), return_labels)
|
||
if selector_chain is not None:
|
||
selector_lines, selector_join_index = selector_chain
|
||
lines.append(f" {label}:")
|
||
for statement in selector_lines:
|
||
lines.append(f" {statement}" if statement else "")
|
||
lines.append("")
|
||
index = selector_join_index
|
||
continue
|
||
|
||
loop_construct = render_loop_construct(
|
||
blocks,
|
||
label_to_index,
|
||
index,
|
||
len(blocks),
|
||
return_labels,
|
||
)
|
||
if loop_construct is not None:
|
||
loop_lines, loop_join_index = loop_construct
|
||
lines.append(f" {label}:")
|
||
for statement in loop_lines:
|
||
lines.append(f" {statement}" if statement else "")
|
||
lines.append("")
|
||
index = loop_join_index
|
||
continue
|
||
|
||
infinite_loop_construct = render_infinite_loop_construct(
|
||
blocks,
|
||
label_to_index,
|
||
index,
|
||
len(blocks),
|
||
return_labels,
|
||
)
|
||
if infinite_loop_construct is not None:
|
||
loop_lines, loop_join_index = infinite_loop_construct
|
||
lines.append(f" {label}:")
|
||
for statement in loop_lines:
|
||
lines.append(f" {statement}" if statement else "")
|
||
lines.append("")
|
||
index = loop_join_index
|
||
continue
|
||
|
||
lines.append(f" {label}:")
|
||
for statement in statements:
|
||
lines.append(f" {statement}")
|
||
lines.append("")
|
||
index += 1
|
||
|
||
return lines
|
||
|
||
|
||
def render_pseudocode(ir: dict[str, Any], shape_catalog: ShapeCatalog | None = None) -> str:
|
||
slot_name = sanitize_identifier(ir["event"]["event_name_hint"] or f"slot_{ir['event']['slot']:02X}")
|
||
lines = [
|
||
(
|
||
f"function {sanitize_identifier(ir['class']['class_name'].lower())}_{slot_name}() "
|
||
f"/* entry={ir['class']['entry_index']} class_id=0x{ir['class']['class_id']:04X} slot=0x{ir['event']['slot']:02X} */"
|
||
),
|
||
"{",
|
||
]
|
||
|
||
if ir["debug_symbols"]:
|
||
lines.append(" var")
|
||
for index, symbol in enumerate(ir["debug_symbols"]):
|
||
separator = "," if index + 1 < len(ir["debug_symbols"]) else ";"
|
||
lines.append(f" {sanitize_identifier(symbol['name'])}{separator} /* {symbol['bp_repr']} type=0x{symbol['type_id']:02X} */")
|
||
lines.append("")
|
||
|
||
rendered_blocks = decompile_pseudocode_blocks(ir)
|
||
structured_lines = render_structured_pseudocode(rendered_blocks)
|
||
if structured_lines is not None:
|
||
for statement in structured_lines:
|
||
lines.append(f" {statement}" if statement else "")
|
||
else:
|
||
lines.extend(render_partially_structured_blocks(rendered_blocks))
|
||
|
||
lines.append("}")
|
||
return apply_shape_catalog_to_pseudocode("\n".join(lines) + "\n", shape_catalog)
|
||
|
||
|
||
def validate_pseudocode_text(text: str) -> list[str]:
|
||
errors: list[str] = []
|
||
label_lines: dict[str, int] = {}
|
||
goto_targets: list[tuple[str, int]] = []
|
||
brace_depth = 0
|
||
|
||
for line_number, raw_line in enumerate(text.splitlines(), start=1):
|
||
stripped = raw_line.strip()
|
||
if not stripped:
|
||
continue
|
||
|
||
if stripped.endswith("{"):
|
||
brace_depth += 1
|
||
if stripped == "}":
|
||
brace_depth -= 1
|
||
if brace_depth < 0:
|
||
errors.append(f"line {line_number}: unexpected closing brace")
|
||
brace_depth = 0
|
||
|
||
label_match = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*):", stripped)
|
||
if label_match is not None:
|
||
label = label_match.group(1)
|
||
previous_line = label_lines.get(label)
|
||
if previous_line is not None:
|
||
errors.append(f"line {line_number}: duplicate label {label} (first at line {previous_line})")
|
||
else:
|
||
label_lines[label] = line_number
|
||
|
||
for match in re.finditer(r"\bgoto ([A-Za-z_][A-Za-z0-9_]*)\s*;", stripped):
|
||
goto_targets.append((match.group(1), line_number))
|
||
|
||
if brace_depth != 0:
|
||
errors.append(f"unbalanced braces: final depth {brace_depth}")
|
||
|
||
for target, line_number in goto_targets:
|
||
if target not in label_lines:
|
||
errors.append(f"line {line_number}: goto target {target} has no label")
|
||
|
||
return errors
|
||
|
||
|
||
def render_text(ir: dict[str, Any]) -> str:
|
||
labels = build_listing_labels(ir)
|
||
|
||
def format_operand(key: str, value: Any) -> str:
|
||
if value is None or value == "":
|
||
return ""
|
||
if key == "intrinsic_name_hint" and value:
|
||
return f"hint={value}"
|
||
if key == "target_event_name_hint" and value:
|
||
return f"event={value}"
|
||
if key == "target_offset" and isinstance(value, int):
|
||
label = labels.get(value + ir["event"]["derived_body_start"])
|
||
return f"->{label or f'0x{value + ir['event']['derived_body_start']:04X}'}"
|
||
if isinstance(value, int):
|
||
if key.endswith("_signed"):
|
||
return f"{key}={value}"
|
||
return f"{key}=0x{value:X}"
|
||
return f"{key}={value}"
|
||
|
||
lines = [
|
||
f"Class {ir['class']['class_name']} entry={ir['class']['entry_index']} class_id=0x{ir['class']['class_id']:X}",
|
||
f"Slot 0x{ir['event']['slot']:02X} hint={ir['event']['event_name_hint']} raw_word=0x{ir['event']['raw_event_entry_word']:04X} raw_code_off=0x{ir['event']['raw_code_offset']:08X}",
|
||
f"Body 0x{ir['event']['derived_body_start']:04X}..0x{ir['event']['derived_body_end']:04X} len={ir['event']['derived_body_length']} end={ir['body']['end_reason']} ops={ir['body']['decoded_op_count']}",
|
||
f"SHA1 {ir['body']['raw_body_sha1']}",
|
||
"",
|
||
]
|
||
for op in ir["ops"]:
|
||
absolute_offset = op["absolute_body_offset"]
|
||
label = labels.get(absolute_offset)
|
||
if label is not None:
|
||
lines.extend(["", f"{label}:"])
|
||
operand_items = [formatted for key, value in op["operands"].items() if (formatted := format_operand(key, value))]
|
||
lines.append(f"{absolute_offset:04X}: {op['opcode']:02X} {op['mnemonic']:<24} {' '.join(operand_items)} raw={op['raw_bytes']}")
|
||
if ir["debug_symbols"]:
|
||
lines.extend(["", f"Debug symbols @ 0x{ir['body']['debug_symbol_offset']:04X}:"])
|
||
for symbol in ir["debug_symbols"]:
|
||
lines.append(
|
||
f" {symbol['index']:02X}: unk1=0x{symbol['unknown1']:02X} type=0x{symbol['type_id']:02X} ('{symbol['type_char']}') {symbol['bp_repr']} unk3=0x{symbol['unknown3']:02X} name={symbol['name']}"
|
||
)
|
||
if ir["field_tags"]:
|
||
lines.extend(["", "Field tags:"])
|
||
for tag in ir["field_tags"]:
|
||
lines.append(
|
||
f" {tag['tag_label']} ({tag['bp_repr']})"
|
||
)
|
||
if ir["body"]["unknown_trailing_bytes"]:
|
||
lines.extend(["", f"unknown_trailing_bytes={ir['body']['unknown_trailing_bytes']}"])
|
||
return "\n".join(lines) + "\n"
|
||
|
||
|
||
def main() -> None:
|
||
parser = argparse.ArgumentParser(description="Proof-of-concept Crusader USECODE parser over extracted owner-loaded artifacts")
|
||
parser.add_argument("--class", dest="class_name", required=True, help="Class name from class_event_index.tsv, for example NPCTRIG")
|
||
parser.add_argument("--slot", required=True, help="Event slot, for example 0x0A")
|
||
parser.add_argument("--extracted-root", default=str(EXTRACTED_ROOT), help="Extracted USECODE root containing class_event_index.tsv and chunks/")
|
||
parser.add_argument("--variant", choices=["auto", "regret", "remorse"], default="auto", help="Crusader intrinsic numbering to apply (default: auto, fallback regret)")
|
||
parser.add_argument(
|
||
"--shape-csv",
|
||
help=(
|
||
"Shape catalog CSV to apply to pseudocode output "
|
||
"(default: Remorse uses <extracted-root>/usecode_shape_catalog_remorse.csv; "
|
||
"Regret uses <extracted-root>/usecode_shape_catalog_regret.csv)"
|
||
),
|
||
)
|
||
parser.add_argument("--output", help="Write IR JSON to this file instead of stdout")
|
||
parser.add_argument("--emit-text", action="store_true", help="Emit a readable text listing beside the JSON")
|
||
parser.add_argument("--text-output", help="Write the text listing to this file")
|
||
parser.add_argument("--emit-script", action="store_true", help="Emit a decompiled script-style view beside the JSON")
|
||
parser.add_argument("--script-output", help="Write the script-style decompilation to this file")
|
||
parser.add_argument("--emit-pseudocode", action="store_true", help="Emit a higher-level pseudocode view beside the JSON")
|
||
parser.add_argument("--pseudocode-output", help="Write the pseudocode view to this file")
|
||
parser.add_argument("--family-diff", action="store_true", help="Emit repeated-body family diff report instead of (or alongside) the IR")
|
||
parser.add_argument("--family-diff-output", help="Write the family diff JSON to this file")
|
||
parser.add_argument("--family-diff-text-output", help="Write the family diff text report to this file")
|
||
args = parser.parse_args()
|
||
|
||
slot = parse_int(args.slot)
|
||
extracted_root = Path(args.extracted_root)
|
||
shape_csv = Path(args.shape_csv) if args.shape_csv else default_shape_catalog_path(extracted_root, args.variant)
|
||
shape_catalog = load_shape_catalog(shape_csv)
|
||
event_row, layout_row = select_rows(args.class_name, slot, extracted_root)
|
||
ir = parse_body_ir(event_row, layout_row, None if args.variant == "auto" else args.variant, extracted_root)
|
||
|
||
rendered_json = json.dumps(ir, indent=2)
|
||
if args.output:
|
||
Path(args.output).write_text(rendered_json + "\n", encoding="utf-8")
|
||
else:
|
||
print(rendered_json)
|
||
|
||
if args.emit_text:
|
||
rendered_text = render_text(ir)
|
||
if args.text_output:
|
||
Path(args.text_output).write_text(rendered_text, encoding="utf-8")
|
||
else:
|
||
print(rendered_text)
|
||
|
||
if args.emit_script:
|
||
rendered_script = render_script(ir)
|
||
if args.script_output:
|
||
Path(args.script_output).write_text(rendered_script, encoding="utf-8")
|
||
else:
|
||
print(rendered_script)
|
||
|
||
if args.emit_pseudocode:
|
||
rendered_pseudocode = render_pseudocode(ir, shape_catalog=shape_catalog)
|
||
if args.pseudocode_output:
|
||
Path(args.pseudocode_output).write_text(rendered_pseudocode, encoding="utf-8")
|
||
else:
|
||
print(rendered_pseudocode)
|
||
|
||
if args.family_diff:
|
||
diff = compute_family_diff(args.class_name, slot, extracted_root)
|
||
diff_json = json.dumps(diff, indent=2)
|
||
if args.family_diff_output:
|
||
Path(args.family_diff_output).write_text(diff_json + "\n", encoding="utf-8")
|
||
else:
|
||
print(diff_json)
|
||
diff_text = render_family_diff_text(diff)
|
||
if args.family_diff_text_output:
|
||
Path(args.family_diff_text_output).write_text(diff_text, encoding="utf-8")
|
||
else:
|
||
print(diff_text)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main() |