BG3 Script Extender macOS + Ghidra Development

Project Locations

| Project | Path | |---------|------| | bg3se-macos | /Users/tomdimino/Desktop/Programming/bg3se-macos | | bg3se (Windows ref) | /Users/tomdimino/Desktop/Programming/bg3se |

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)

| Namespace | Status | Notes | |-----------|--------|-------| | Osi.* | 95% | Dynamic metatable, Query/Call/Event | | Ext.Osiris | 95% | RegisterListener, NewCall/Query/Event | | Ext.Stats | 95% | Property read/write | | Ext.Entity | 50% | Get, GetComponent, GetAllEntitiesWithComponent | | Ext.Events | 75% | 7 events | | Ext.Timer | 100% | Complete | | Ext.Debug | 100% | Memory introspection |

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

Key Offsets

| Symbol | Address/Offset | |--------|----------------| | esv::EocServer::m_ptr | 0x10898e8b8 | | EntityWorld | EocServer+0x288 | | RPGStats::m_ptr | base+0x89c5730 | | RPGStats.FixedStrings | +0x348 | | GlobalStringTable | base+0x8aeccd8 |

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