binana/README.md

# 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
```

[Read cheat engine script info](CheatEngineScriptsInfo.md)

# 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 }))
```