mirror of
https://github.com/thunderbrewhq/binana.git
synced 2026-02-04 08:49:08 +00:00
217 lines
No EOL
6.9 KiB
Markdown
217 lines
No EOL
6.9 KiB
Markdown
# binana
|
||
|
||
This repository hosts some work related to studying the original game binaries.
|
||
|
||
You can use the information here to get a headstart when working on the [Whoa project](https://github.com/whoahq/whoa).
|
||
|
||
- [Dependencies (optional)](#dependencies-optional)
|
||
- [Header files](#header-files)
|
||
- [Symbol files](#symbol-files)
|
||
- [Debugging files](#debugging-files)
|
||
- [Ghidra](#ghidra)
|
||
* [Importing C headers](#importing-c-headers)
|
||
* [Importing symbols](#importing-symbols)
|
||
- [IDA](#ida)
|
||
* [Importing C headers](#importing-c-headers-1)
|
||
* [Importing symbols](#importing-symbols-1)
|
||
- [x64dbg](#x64dbg)
|
||
* [Importing database](#importing-database)
|
||
* [Importing types](#importing-types)
|
||
- [How to Inspect Object Fields in Cheat Engine](#how-to-inspect-object-fields-in-cheat-engine)
|
||
- [How to generate a C struct](#how-to-generate-a-c-struct)
|
||
* [Generating dependent structs](#generating-dependent-structs)
|
||
* [Options for `toCStruct` and `toCStructWithDeps`](#options-for-tocstruct-and-tocstructwithdeps)
|
||
* [Examples](#examples)
|
||
|
||
# Dependencies (optional)
|
||
|
||
This project can be utilized immediately using files we have already generated. However, if you wish to make modifications to the C header and symbol files, **it may be necessary to refresh the generated files that are based on them**.
|
||
|
||
You'll need:
|
||
|
||
- Go >= 1.22
|
||
- git
|
||
- Make
|
||
- Bash shell
|
||
|
||
You can regenerate everything to include your changes with:
|
||
|
||
```bash
|
||
make dependencies
|
||
make
|
||
```
|
||
|
||
# Header files
|
||
|
||
To make looking at the binary easier, C header files to match the original executable's memory layout are provided. They aim to be lightweight and self-contained, so that many tools can make use of them.
|
||
|
||
# Symbol files
|
||
|
||
Symbol files are text files that map addresses to functions and variables/data labels.
|
||
|
||
The format is based on the one used in the stock Ghidra script `ImportSymbolsScript.py`:
|
||
|
||
```
|
||
DataLabel 00DDAA77AA l
|
||
FunctionName 00CC00DDEE f
|
||
```
|
||
|
||
To improve the call stack view in x64dbg, you should append an `end` field to every function, with the address where this function ends and another begins (i.e. after the last instruction of the function):
|
||
|
||
```csv
|
||
FunctionName 00CC00DDEE f end=00CC00DDFF
|
||
```
|
||
|
||
In this repo, `script/compile-symbols` is used to concatenate our organized symbol files into one big file (`<game version>/symbol/main.sym`).
|
||
|
||
To refresh the gigantic `main.sym` file after changing one of the source symbol files:
|
||
|
||
```bash
|
||
script/compile-symbols <game version>
|
||
```
|
||
|
||
Or just
|
||
```
|
||
make
|
||
```
|
||
|
||
# Debugging files
|
||
|
||
The best way to know what a particular routine does is to use a debugger.
|
||
|
||
With our [x64dbg](https://x64dbg.com/) files, you can easily navigate to various functions, read the call stack, play with variables, and explore data structures.
|
||
|
||
These files are autogenerated from the C header and symbol files, using our `binana` tool written in Go. You can install it like so:
|
||
|
||
```bash
|
||
make dependencies
|
||
```
|
||
|
||
To regenerate:
|
||
|
||
```bash
|
||
make
|
||
```
|
||
|
||
# Ghidra
|
||
|
||
## Importing C headers
|
||
|
||
To import the main header file into your Ghidra project,
|
||
|
||
1. go to `File` 🡒 `Parse C Source...`.
|
||
2. Select `clib.prf` as your parse configuration, and clear all source files and input paths.
|
||
3. Add the header `profile/<game version>/include/main.h` to the `Source files to parse` combo box.
|
||
4. Add the path to `profile/<game version>/include` to the `Include paths` combo box.
|
||
5. Add `-DGHIDRA` to a new line in `Parse Options`.
|
||
6. press `Parse to Program`.
|
||
|
||
If all goes well, Data Type Manager will now contain the data structures from the headers.
|
||
|
||
## Importing symbols
|
||
|
||
To import the symbol file into your Ghidra project,
|
||
|
||
1. go to `Window` 🡒 `Script Manager`
|
||
2. In the table view, lookup `ImportSymbolsScript.py`
|
||
3. Run the script
|
||
4. Enter the path to `profile/<game version>/symbol/main.sym`
|
||
|
||
# IDA
|
||
|
||
## Importing C headers
|
||
|
||
To import the main header file into your IDA database,
|
||
|
||
1. Go to `Options` 🡒 `Compiler`
|
||
2. Add `IDA` to the semicolon-separated `Predefined macros` list.
|
||
3. Go to `File` 🡒 `Load file` 🡒 `Parse C Header file`
|
||
4. Enter the path to `profile/<game version>/include/main.h`
|
||
|
||
## Importing symbols
|
||
|
||
To use the IDC script,
|
||
|
||
1. Go to `File` 🡒 `Script file...`
|
||
2. Navigate to `profile/<game version>/ida/import_all.idc`
|
||
3. Wait for everything to be reanalyzed
|
||
|
||
# x64dbg
|
||
|
||
For ease of debugging, we provide x64dbg databases (generated by the Go tool from symbol maps), as well as x64dbg type information (generated by the same Go tool from the C headers).
|
||
|
||
## Importing database
|
||
|
||
To load the database information into x64dbg:
|
||
|
||
1. Open x96dbg.exe or x32dbg.exe directly
|
||
2. Load your game binary
|
||
3. Go to `File` 🡒 `Database` 🡒 `Import database`
|
||
4. Navigate to `profile/<game version>/x64dbg/game.dd32`.
|
||
|
||
## Importing types
|
||
|
||
To load the type information JSON file:
|
||
|
||
1. Open the binary in x32dbg.exe
|
||
2. in the console, type: `LoadTypes <full path to local binana repository>\profile\<game version>\x32dbg\types.json`
|
||
|
||
# How to Inspect Object Fields in Cheat Engine
|
||
|
||
**How to Build the Loading Scripts**
|
||
|
||
```bash
|
||
make ce-lua
|
||
```
|
||
|
||
**For Units**
|
||
* Select a target unit (it must be of type Unit).
|
||
* Execute the script: [Load_CGUnit.lua](https://github.com/thunderbrewhq/binana/blob/master/profile/3.3.5a-windows-386/cheatengine/Load_CGUnit.lua)
|
||
*(Menu: Table -> Show Cheat Table Lua Script)*
|
||
|
||
**For Player (your character)**
|
||
* Execute the script: [Load_CGPlayer.lua](https://github.com/thunderbrewhq/binana/blob/master/profile/3.3.5a-windows-386/cheatengine/Load_CGPlayer.lua)
|
||
|
||
**For Corpses**
|
||
* Execute the script: [Load_CGCorpse.lua](https://github.com/thunderbrewhq/binana/blob/master/profile/3.3.5a-windows-386/cheatengine/Load_CGCorpse.lua)
|
||
* Then hover your mouse cursor over the corpse.
|
||
|
||
**For Items** (items in the main 16-slot backpack)
|
||
* Execute the script: [Load_CGItem.lua](https://github.com/thunderbrewhq/binana/blob/master/profile/3.3.5a-windows-386/cheatengine/Load_CGItem.lua)
|
||
|
||
**For Containers** (only for equipped bags)
|
||
* Execute the script: [Load_CGContainer.lua](https://github.com/thunderbrewhq/binana/blob/master/profile/3.3.5a-windows-386/cheatengine/Load_CGContainer.lua)
|
||
|
||
# How to generate a C struct
|
||
|
||
To generate a C struct, open the file you’re interested in, remove the Cheat Engine loading code, and add this line at the end of the file (using `CGCorpse` as an example):
|
||
|
||
```lua
|
||
print(CGCorpse:toCStruct())
|
||
```
|
||
|
||
Then run:
|
||
|
||
```bash
|
||
lua Load_CGCorpse.lua
|
||
```
|
||
|
||
## Generating dependent structs
|
||
|
||
If you also need dependent (referenced) structs, use:
|
||
|
||
```lua
|
||
print(CGCorpse:toCStructWithDeps())
|
||
```
|
||
|
||
## Options for `toCStruct` and `toCStructWithDeps`
|
||
|
||
- `collapsePadding` — if `false`, `unk_` fields will be grouped into arrays (default: `true`)
|
||
- `flattenInheritance` — if `true`, embedded fields and parent fields will be inlined into the struct (default: `false`)
|
||
|
||
## Examples
|
||
|
||
```lua
|
||
print(CGCorpse:toCStructWithDeps({ flattenInheritance = true }))
|
||
print(CGCorpse:toCStructWithDeps({ collapsePadding = false, flattenInheritance = true }))
|
||
``` |