# Tools

Every tool and script in GameFrame, with its own help. The same list is in the terminal with `./gameframe tools`, and one tool's help with `./gameframe tool NAME`.

## Discs and disk images

| Tool | Kind | What it does |
|---|---|---|
| [checks](/tools/checks) | library | Checks of a CD's file systems, for discinfo.py: sectors that hold data no file system names, the system area, files that only one directory tree lists, and file dates later than the volume's own date. |
| [discinfo](/tools/discinfo) | program | First look at a CD image (CUE/BIN, raw BIN or ISO): its tracks, its file systems, its dates, and the files on it. |
| [image](/tools/image) | library | Read the tracks and sectors of a CD image: a CUE sheet with its BIN files, a raw BIN without a sheet, or a plain ISO. |
| [volumes](/tools/volumes) | library | Find and read the file systems in a CD data track: ISO 9660 with its Joliet names, the older High Sierra format, an El Torito boot record, and an Apple HFS or HFS+ volume (hybrid Mac and PC discs). |

## Windows PE

| Tool | Kind | What it does |
|---|---|---|
| [peinfo](/tools/peinfo) | program | First look at a Windows executable or DLL: what it is, how it was built, what it uses. |
| [peres](/tools/peres) | program | List and extract the resources inside a Windows executable or DLL: version information, string tables, dialogs, menus, icons, bitmaps, sounds and the game's own data. |
| [readdata](/tools/readdata) | program | Read typed values from a Windows binary at Ghidra addresses (the DAT_ globals in pseudocode). |
| [stackstrings](/tools/stackstrings) | program | Find text that the code builds on the stack a few bytes at a time, which a list of strings in the file does not show. |
| [vtable](/tools/vtable) | program | List the slots of a table of function pointers (a C++ vtable) with the functions they hold. |

## 16-bit DOS

| Tool | Kind | What it does |
|---|---|---|
| [dbx_control](/tools/dbx_control) | program | Drive DOSBox-X's built-in debugger from a script, through its debugger control channel. |
| [dosinfo](/tools/dosinfo) | program | First look at a DOS or Windows 3.x executable (MZ, NE): what it is, how it was built, what it uses. |
| [fileio_trace](/tools/fileio_trace) | program | Turn a DOSBox-X file log into a per-file map of reads: which file, at which offset, how many bytes, in what order. |
| [ne](/tools/ne) | library | Read MZ (DOS) and NE (16-bit protected mode, Windows 3.x) executables: the shared parser behind dosinfo.py and readseg.py. |
| [nedis](/tools/nedis) | program | Disassemble 16-bit code with its relocations applied and its names shown. |
| [omf](/tools/omf) | program | Read Intel/Microsoft OMF object files and libraries (.OBJ, .LIB): the format of the DOS and 16-bit Windows compilers (Borland, Microsoft, Watcom). |
| [readseg](/tools/readseg) | program | Read typed values from a DOS (MZ) or 16-bit NE executable at Ghidra's seg:off addresses. |
| [td_rust](/tools/td_rust) | library | Rust code from Borland Turbo Debugger symbols: record types, the data segment's variables, and the Pascal reader/writer they use. |
| [tdinfo](/tools/tdinfo) | program | Read Borland Turbo Debugger symbols (TDINFO, signature FB52) from a DOS or NE executable. |

## Triage

| Tool | Kind | What it does |
|---|---|---|
| [binview](/tools/binview) | program | Draw a file as a picture, one pixel per byte (or per block of bytes), to see its structure at a glance: headers, tables of records, text, code, compressed or encrypted parts, padding. |
| [cite_labels](/tools/cite_labels) | program | Make function labels from a reimplementation's citations: every item whose comment says "Original: FUN_xxxx" names that original function. |
| [compare_trees](/tools/compare_trees) | program | Compare two copies of a game file by file: are two releases (a CD, a GOG or Steam copy, a patch) the same program and the same data? |
| [constants](/tools/constants) | program | Name the algorithms in a binary by their constants: random number generators, checksums, hashes, ciphers, compressors and well-known maths tricks. |
| [coverage](/tools/coverage) | program | How much of the original's code does the reimplementation cite? |
| [coverdiff](/tools/coverdiff) | program | Find the code that runs only when you do something in the game: compare the code coverage of two runs, one without the action and one with it. |
| [decomp_query](/tools/decomp_query) | program | Answer questions about a Ghidra export (scripts/ghidra-export.sh) without reading it whole. |
| [deviations](/tools/deviations) | program | Collect every known difference from the original into one ledger. |
| [filetypes](/tools/filetypes) | program | What each file of a game is, from its bytes: the format its first bytes name, its size and its entropy. |
| [fixity](/tools/fixity) | program | Keep a copy of a game unchanged over the years, and prove it: package it as a BagIt bag with a checksum for every file, and check the checksums again whenever you like. |
| [hashnames](/tools/hashnames) | program | Name hashed strings: find which hash function a game uses for its names, and which name each hash constant stands for. |
| [insns](/tools/insns) | program | List every instruction of a kind in a program: every port read or write, every interrupt, every timer read, every division, every far call. |
| [match_functions](/tools/match_functions) | program | Match the functions of two builds of a game, and carry your labels from one to the other: a patch, another release, a demo, a version for another platform with the same compiler. |
| [memscan](/tools/memscan) | program | Find where a running game keeps a value, from memory dumps taken while you watch the value change: the gold, a unit's health, the turn counter, the random seed. |
| [pointerpaths](/tools/pointerpaths) | program | Find a way to the address of a value that moves: a chain of pointers from a fixed address (a global variable of the program) through the game's objects to the value. |
| [sigscan](/tools/sigscan) | program | Byte signatures with wildcards: make them from functions you have named, and find them in another build, a memory dump or a game that uses the same library. |
| [similar](/tools/similar) | program | How alike two files are, when they are not identical: two versions of an executable, a patched data file, a renamed file, or a library the game links against. |
| [tables](/tools/tables) | program | Find the sine and cosine tables in a binary or a data file, and say exactly how each was made: its length, its scale, its number type and how it was rounded. |

## Emulators

| Tool | Kind | What it does |
|---|---|---|
| [call_trace](/tools/call_trace) | library | Record the calls an emulated function makes to chosen functions, in order, with call sites. |
| [dos_emu](/tools/dos_emu) | library | Call functions inside a 16-bit DOS or Windows 3.x program (NE or MZ) under Unicorn. |
| [dos_env](/tools/dos_env) | library | A small DOS, BIOS and PC for tools/emu/dos_emu/, so a whole 16-bit program can run headless. |
| [fragments](/tools/fragments) | program | Capture fragments of a DOS program's main loop, before and after, from one headless run. |
| [pe_emu](/tools/pe_emu) | library | Call functions inside a Windows x64 game's EXE and DLLs under Unicorn, without running the game. |

## Formats

| Tool | Kind | What it does |
|---|---|---|
| [fields](/tools/fields) | program | Find the fields in many messages or records of one kind: which byte offsets are constant, which count up, which hold the length, which pick the kind of message, and which vary. |
| [markers](/tools/markers) | program | Mark the fields of a data file with unique values, then find where the game puts each one in memory. |
| [pcap](/tools/pcap) | program | Read a network capture (.pcap or .pcapng, from Wireshark or tcpdump) and split it into the conversations of a game: who talks to whom, on which ports, and the bytes of each message. |
| [rawimage](/tools/rawimage) | program | Turn raw pixel data into a PNG: a dump of video memory, a screen saved by a DOS game, or a block of a data file that may hold a picture. |
| [reader](/tools/reader) | library | A binary reader (little-endian, with big-endian and variable-length reads) for prototyping decoders of a game's data files. |
| [shaders](/tools/shaders) | program | Find the shaders inside a game's files: compiled Direct3D 9 and 10-12 shaders, SPIR-V, and shader source text in GLSL, HLSL and the OpenGL ARB assembly. |
| [skeleton](/tools/skeleton) | program | Find skeletons and poses in a model or animation file: arrays of parent indices, and runs of unit quaternions. |
| [swfinfo](/tools/swfinfo) | program | First look at a Flash game: an SWF file, or a Flash projector (an .exe with the SWF inside). |
| [timestamps](/tools/timestamps) | program | Decode a number as every common kind of timestamp, or find timestamps inside a file. |
| [validate](/tools/validate) | program | Run a decoder over every file of a type and report which files fail or leave bytes unread. |
| [xorscan](/tools/xorscan) | program | Find the key of a simply obfuscated data file: XOR with one byte or a repeating key, adding a byte, a key that steps by a fixed amount each byte, or each byte XORed with the one before. |

## Verify

| Tool | Kind | What it does |
|---|---|---|
| [bitcompare](/tools/bitcompare) | program | Compare two raw dumps value by value, bit for bit: ground truth against a port's output. |
| [ramdiff](/tools/ramdiff) | program | Compare the game's memory frame by frame, from the original and from the port, and report the first frame and the first addresses that differ. |
| [seqdiff](/tools/seqdiff) | program | Compare two traces line by line and show the first place they differ. |

## Ghidra scripts

| Tool | Kind | What it does |
|---|---|---|
| [AddMemoryBlocks](/tools/AddMemoryBlocks) | ghidra | Build a program's memory from raw pieces: a booter game's load map, an unpacked memory dump, a console's ROM banks, or overlays loaded at run time. |
| [ApplyLabels](/tools/ApplyLabels) | ghidra | Apply a labels file (labels/names.tsv style: address<TAB>label[<TAB>evidence]) to the program. |
| [ExportAddressBatch](/tools/ExportAddressBatch) | ghidra | Decompile selected code addresses in an already analyzed Ghidra project. |
| [ExportAddressRefs](/tools/ExportAddressRefs) | ghidra | Export direct references and their containing functions for selected Ghidra addresses. |
| [ExportAll](/tools/ExportAll) | ghidra | Export everything an agent needs to read a binary as text, after Ghidra's auto-analysis. |
| [ExportCallArgs](/tools/ExportCallArgs) | ghidra | List every call to chosen functions with the arguments the decompiler can resolve at each call: constants, strings and global addresses. |
| [ExportNamedFunctions](/tools/ExportNamedFunctions) | ghidra | Decompile functions whose Ghidra names contain any supplied search term. |
| [ExportVtableSlots](/tools/ExportVtableSlots) | ghidra | Print executable targets from selected 64-bit MSVC vtables in a Ghidra project. |

## Scripts

| Tool | Kind | What it does |
|---|---|---|
| [dosbox-run](/tools/dosbox-run) | script | Run a DOS program under DOSBox-X from the command line: the whole original game, for ground truth that a single emulated function cannot give (frames, demos, file access, timing). |
| [env](/tools/env) | script | Source this file to use GameFrame from a shell or an agent session. |
| [extract-installer](/tools/extract-installer) | script | Get a game's files out of the installer or package it came in, without running it. |
| [ghidra-export](/tools/ghidra-export) | script | Analyse one or more binaries with Ghidra (no window) and export them as text an agent can search: decomp.c, functions.tsv, strings.txt, imports.txt, exports.txt per binary. |
| [ghidra-run](/tools/ghidra-run) | script | Run one of the tools/ghidra scripts on a binary in an existing, analysed Ghidra project, without analysing it again (about a minute of start-up, so batch addresses in one run). |
| [lib](/tools/lib) | library | Shared settings for the scripts: where Ghidra, Java and the Python environment are. |
| [new-project](/tools/new-project) | script | Start a reverse-engineering project for one game, with GameFrame's toolkit and playbook. |
| [setup](/tools/setup) | script | Check, and optionally install, everything GameFrame uses. |