BG3 Script Extender macOS + Ghidra Development

BG3 Script Extender macOS + Ghidra Development

Project Locations

Quick Start

# Build
cd /​Users/​tomdimino/​Desktop/​Programming/​bg3se-macos/​build
cmake .. && cmake --build .

# Test
./​scripts/​launch_bg3.sh
tail -f ~/​Library/​Application\ Support/​BG3SE/​bg3se.log

# Ghidra (headless, optimized)
./​ghidra/​scripts/​run_analysis.sh <script.py>

Key Constraints (macOS)

1. Cannot hook main binary - Hardened Runtime blocks __TEXT hooks
2. CAN hook libOsiris.dylib - 1,013 exported symbols
3. ARM64 ABI - x8 register for structs >16 bytes
4. No GetRawComponent - Must traverse ECS manually

See macos-patterns.md for detailed differences.

Module Structure

src/
├── injector/​main.c   # Core (~2900 lines): hooks, Osi.*, Lua state
├── entity/           # ECS: guid_lookup, component_lookup, arm64_call
├── lua/              # Ext.* APIs: stats, debug, osiris, json
├── osiris/           # Osiris types, functions, custom_functions
├── stats/            # RPGStats, GlobalStringTable
├── console/          # Socket server, file-based console
└── input/            # CGEventTap keyboard capture

API Surface (v0.22.0)

Not implemented: Ext.Net, Ext.UI, Ext.Level, Client Lua State

Key Offsets

osgrep Usage

# IMPORTANT: cd into project first
cd /​Users/​tomdimino/​Desktop/​Programming/​bg3se-macos
osgrep "how does entity lookup work"
osgrep "Ext.Stats property resolution"

# Windows reference
cd /​Users/​tomdimino/​Desktop/​Programming/​bg3se
osgrep "CustomFunctionManager"

Common Tasks

Add new Ext. API:*

1. Implement in src/​lua/​lua_*.c
2. Register in lua_*_register() function
3. Test with EntityTest mod

Discover offset:

1. Search strings in Ghidra
2. Find XREFs, trace ADRP+LDR pattern
3. Document in ghidra/​offsets/​*.md

Port Windows feature:

1. Search Windows BG3SE: osgrep "feature" -p /​path/​to/​bg3se
2. Understand pattern, find ARM64 equivalents
3. Adapt for macOS constraints

Reference Documentation

• macos-patterns.md - macOS vs Windows, GUID byte order, component traversal
• bg3se-architecture.md - Windows BG3SE structure
• arm64-patterns.md - x8 register, calling conventions
• ghidra-workflows.md - Script usage, analysis patterns
• offset-discovery.md - Finding game addresses

Troubleshooting

Crashes on launch: Check dylib signing (codesign -dv), verify ARM64 (file)

Hooks not called: Only hook libOsiris, not main binary

Entity lookup NULL: EoCServer may not be initialized; verify offset 0x288

osgrep no results: Run from project directory or use -p flag