How do I install the Bg3se Macos Ghidra skill?

Run npx skillmds add majiayu000/bg3se-macos-ghidra in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Bg3se Macos Ghidra safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Bg3se Macos Ghidra?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Bg3se Macos Ghidra free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Bg3se Macos Ghidra?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Bg3se Macos Ghidra by majiayu000 — Agent Skill

Name: Bg3se Macos Ghidra
Rating: 4.2 (5 reviews)
Author: majiayu000

Bg3se Macos Ghidra

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

majiayu000 2fbb8fd 2 files · 5.0 KB Updated Sep 9, 2026 567 repo stars

File contents

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 __TEXT hooks
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

---name: bg3se-macos-ghidradescription: 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--- # 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 ```bash # 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](references/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 ```bash # 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](references/macos-patterns.md)** - macOS vs Windows, GUID byte order, component traversal - **[bg3se-architecture.md](references/bg3se-architecture.md)** - Windows BG3SE structure - **[arm64-patterns.md](references/arm64-patterns.md)** - x8 register, calling conventions - **[ghidra-workflows.md](references/ghidra-workflows.md)** - Script usage, analysis patterns - **[offset-discovery.md](references/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

Frequently asked questions