bg3se-macos-ghidra

tdimino's avatarfrom tdimino

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

⭐12stars🔀3forks📁View on GitHub🕐Updated Dec 31, 2025
[Debugging]

When & Why to Use This Skill

This Claude skill is a specialized development assistant for porting and maintaining the Baldur's Gate 3 Script Extender (BG3SE) on macOS. It integrates deep technical knowledge of reverse engineering using Ghidra, ARM64 assembly analysis, and Lua API implementation. By providing specific memory offsets, architectural patterns (ECS, Osiris), and macOS-specific constraints like Hardened Runtime workarounds, it streamlines the complex process of game tool development and low-level debugging.

Use Cases

  • Reverse Engineering: Utilizing Ghidra to discover function addresses, memory offsets, and data structures within the BG3 macOS binary.
  • ARM64 Architecture Porting: Adapting Windows-based BG3SE features to macOS ARM64, including handling specific calling conventions and the x8 register for structs.
  • Lua API Development: Implementing and registering new Lua namespaces (Ext.*, Osi.*) to expand modding capabilities on the macOS platform.
  • System Analysis: Navigating the game's Entity Component System (ECS) and Osiris integration to implement custom game logic and event listeners.
  • Troubleshooting & Hooking: Diagnosing crashes, verifying dylib signing, and implementing hooks within libOsiris.dylib while bypassing macOS security restrictions.
namebg3se-macos-ghidra
description|
version0.22.0
last_updated2025-12-10

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

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