| name | bg3se-macos-ghidra |
| description | Develop the BG3 Script Extender macOS port using Ghidra for reverse engineering. Use this skill when: (1) Working on bg3se-macos port development or debugging (2) Using Ghidra to discover offsets, function addresses, or data structures in BG3 (3) Implementing new Lua APIs (Ext.*, Osi.*) for macOS Script Extender (4) Porting Windows BG3SE features to macOS ARM64 (5) Understanding ECS architecture, Osiris integration, or stats system (6) Analyzing ARM64 assembly or calling conventions for game hooks (7) Writing or modifying Ghidra Python scripts for BG3 analysis |
| version | 0.22.0 |
| last_updated | Wed Dec 10 2025 00:00:00 GMT+0000 (Coordinated Universal Time) |
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)
- Cannot hook main binary - Hardened Runtime blocks
__TEXThooks - CAN hook libOsiris.dylib - 1,013 exported symbols
- ARM64 ABI - x8 register for structs >16 bytes
- 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:*
- Implement in
src/lua/lua_*.c - Register in
lua_*_register()function - Test with EntityTest mod
Discover offset:
- Search strings in Ghidra
- Find XREFs, trace ADRP+LDR pattern
- Document in
ghidra/offsets/*.md
Port Windows feature:
- Search Windows BG3SE:
osgrep "feature" -p /path/to/bg3se - Understand pattern, find ARM64 equivalents
- 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