thirdeye

How to implement or fix an AESOP runtime function (`CALL` target) in thirdeye. Always read the John Miles AESOP/32 C source under `../eob3_research/runtime/*.C` *first* — it's ground truth for what every runtime function should do; our job is to make `defaultRuntimeCall` in [apps/thirdeye/engine.cpp](../../../apps/thirdeye/engine.cpp) match. Use whenever you're adding, fixing, or chasing down a runtime function: triggers include "runtime function", "runtime CALL", "stubbed", "unimplemented", "C:foo", "implement CALL", "defaultRuntimeCall", "what does post_event/cancel/dispatch_event/create_program/destroy_object/etc. do", "stuck on a CALL", or "the bytecode expects a runtime that does X".

Comparing rendered screenshots — between thirdeye and DOSBox-captured references, between two thirdeye renders for regression, or between a decoder's output and a ground-truth reference. Covers `odiff` / `spaceman-diff` / PIL+NumPy pixel scans, when to reach for each, and the load-bearing trap of comparing a native 320x200 render against an upscaled-and-blurred DOSBox capture. Use whenever you need to answer "does this look right?" with more rigour than eyeballing. Triggers include "image diff", "screenshot compare", "odiff", "spaceman-diff", "alignment off", "doesn't look right", "dosbox screenshot", "regress this frame", "find where it differs", "is this pixel-perfect".

How to diagnose thirdeye at runtime — `THIRDEYE_*` env vars, `--debug` VM trace, Debug-vs-Release build config (always under `build/`), the `[mon-msg]`/`[atk]`/`[xfer]` log formats, and the standard combat-debug incantation. Use whenever something's broken/slow/silent and you need to see what the VM or runtime is doing: triggers include "debug", "trace", "diagnose", "stuck", "slow", "stall", "what's the engine doing", "THIRDEYE_", "no hit lands", "combat doesn't work", "monster doesn't die", "frame dump", "autowalk".

Reference for reading AESOP SOP bytecode in EYE.RES / HACK.RES — daesop disassembler commands, VM stack discipline, how to find message handlers, naming conventions (`M:N` messages, `C:foo` runtime calls, `W:/B:/L:` exported vars). Use whenever you need to disassemble or interpret a SOP handler: triggers include "disassemble", "daesop", "what does M:N do", "M:71", "SOP", "bytecode", "stack discipline", "PUSH overwrites top", "LSWA", "SEND", "MESSAGE_HANDLER_NAME", or any time you're cracking open `.dasm` output.

Reverse-engineering the DOS executables that ship beside EYE.RES (CHGEN.EXE, CHARCOPY.EXE, AESOP.EXE, INTERP.EXE, CINE.EXE, SOUND.EXE). These are 16-bit MS-DOS MZ (or LZEXE-packed) binaries — the AESOP runtime + char-gen + cinema players — and decoding them is the ground truth for things SOP bytecode can't tell us (e.g. CREATE.SAV layout, char-copy semantics). Use whenever you need to crack open a DOS .EXE: triggers include "CHGEN.EXE", "CHARCOPY.EXE", "AESOP.EXE", "INTERP.EXE", "CINE.EXE", "disassemble exe", "DOS binary", "LZEXE", "MZ", "Ghidra", "radare2", "r2", "what does CHGEN write to CREATE.SAV", "where is the chargen logic", "how does CHARCOPY work".