BG3SE macOS Development

Development assistant for the Baldur's Gate 3 Script Extender macOS port. Helps with building, testing, reverse engineering, and implementing Windows BG3SE parity features.

Project Context

You are working on a macOS port of Norbyte's Script Extender for Baldur's Gate 3. The goal is feature parity with Windows BG3SE for full mod compatibility.

**Tech Stack:**

**Key Directories:**

Core Workflows

1. Build & Deploy

```bash

cd build && cmake .. && cmake --build .

```

**Important:** Build automatically deploys dylib to Steam folder via `scripts/deploy.sh` (CMake POST_BUILD hook). After rebuilding, the game must be restarted to load the new dylib.

2. Testing

**Launch Game:**

```bash

./scripts/launch_bg3.sh

```

**Live Lua Console (immediate command execution):**

```bash

./build/bin/bg3se-console

Or one-liner via socket:

echo 'Ext.Dump(_C())' | nc -U /tmp/bg3se.sock

```

**CRITICAL:** When user says "run the commands" during in-game testing, YOU should execute test commands via `nc -U /tmp/bg3se.sock` immediately. This is faster than asking the user to run them manually.

**Console Access:** You can ALWAYS connect to the BG3SE console when the game is running. Prefer this over log parsing for real-time feedback.

**View Logs:**

```bash

Check system time first (to filter old entries)

date && tail -f "/Users/tomdimino/Library/Application Support/BG3SE/logs/latest.log"

```

Each game launch creates a new session log file. Use `latest.log` symlink or check specific timestamps in `/logs/` directory.

**Automated Tests:**

Use `!test` in console to run regression tests.

3. Semantic Search (Prefer Over grep)

**Use osgrep** for code search across indexed repos. Use the `osgrep-reference` skill for CLI reference.

**Indexed repositories:**

```bash

Search macOS port

cd /Users/tomdimino/Desktop/Programming/bg3se-macos && osgrep "query"

Search Windows reference for parity

cd /Users/tomdimino/Desktop/Programming/bg3se && osgrep "query"

```

4. Reverse Engineering

For RE sessions, adopt the **Meridian** persona (see `agent_docs/meridian-persona.md`):

**GhidraMCP:** When Ghidra is running with BG3 binary loaded and plugin enabled, you have direct access to decompilation via MCP tools. See `plans/unexplored-re-techniques.md` for setup. Use `bg3se-macos-ghidra` skill for Ghidra workflows.

**Use Debug.* helpers** for memory probing during runtime.

Current API Status

**Implemented:**

Key Offsets (Ghidra-verified)

| Offset | Purpose |

|--------|---------|

| `0x348` | RPGSTATS_OFFSET_FIXEDSTRINGS |

| `0x10124f92c` | LEGACY_IsInCombat (EntityWorld capture) |

| `0x10898e8b8` | esv::EocServer::m_ptr |

| `0x10898c968` | ecl::EocClient::m_ptr |

| `0x1089bac80` | SpellPrototypeManager::m_ptr |

| `0x1089bdb30` | StatusPrototypeManager::m_ptr |

| `0x108aeccd8` | PassivePrototypeManager |

| `0x108aecce0` | InterruptPrototypeManager |

| `0x108991528` | BoostPrototypeManager |

| `0x108a8f070` | ResourceManager::m_ptr |

| `0x101f72754` | SpellPrototype::Init |

Coding Conventions

Documentation Updates

When completing features, update:

See `agent_docs/development.md` for full checklist.

Reference Documentation

**Always available:**

**Read on-demand:**

Example Usage

**Build and test new API:**

```bash

Build

cd build && cmake .. && cmake --build .

Launch game

./scripts/launch_bg3.sh

Test via console (in another terminal)

echo '_D(Ext.Stats.Get("TARGET_Player"))' | nc -U /tmp/bg3se.sock

Watch logs

date && tail -f "/Users/tomdimino/Library/Application Support/BG3SE/logs/latest.log"

```

**Search Windows reference for implementation:**

```bash

cd /Users/tomdimino/Desktop/Programming/bg3se && osgrep "GetAllTypes"

```

**Probe memory during RE:**

```lua

Debug.ProbeStruct(address, "ComponentLayout")

Debug.HexDump(address, 256)

```

Important Notes