用途
本技能面向《博德之门3》脚本扩展器(BG3 Script Extender)macOS 移植版(bg3se-macos)的开发工作,核心手段是使用 Ghidra 进行逆向工程。它把项目路径、构建方式、平台约束、模块结构、API 现状、内存偏移和排错方法集中成一份开发参考。
项目位置与快速开始
技能明确了两条项目路径:bg3se-macos 位于 /Users/tomdimino/Desktop/Programming/bg3se-macos,Windows 参考实现 bg3se 位于 /Users/tomdimino/Desktop/Programming/bg3se。
构建:进入 build 目录执行 cmake .. && cmake --build .。
测试:运行 ./scripts/launch_bg3.sh,并用 tail -f ~/Library/Application\ Support/BG3SE/bg3se.log 查看日志。
Ghidra 无头分析:./ghidra/scripts/run_analysis.sh <script.py>。
macOS 关键约束
- 不能挂钩主二进制——Hardened Runtime 会阻止对
__TEXT段的 hook。 - 可以挂钩 libOsiris.dylib——该库有 1,013 个导出符号。
- ARM64 ABI——大于 16 字节的结构体使用 x8 寄存器传递。
- 没有 GetRawComponent——必须手动遍历 ECS。
更详细的 macOS 与 Windows 差异见 references/macos-patterns.md。
模块结构
src 下分为:injector/main.c(核心约 2900 行,含 hooks、Osi.、Lua 状态)、entity/(ECS:guid_lookup、component_lookup、arm64_call)、lua/(扩展 API:stats、debug、osiris、json)、osiris/(Osiris 类型、函数、custom_functions)、stats/(RPGStats、GlobalStringTable)、console/(Socket 服务器、基于文件的控制台)、input/(CGEventTap 键盘捕获)。
API 接口现状(v0.22.0)
Osi.*:95%,动态 metatable,支持 Query/Call/EventExt.Osiris:95%,RegisterListener、NewCall/Query/EventExt.Stats:95%,属性读写Ext.Entity:50%,Get、GetComponent、GetAllEntitiesWithComponentExt.Events:75%,7 个事件Ext.Timer:100%,完整Ext.Debug:100%,内存内省
未实现:Ext.Net、Ext.UI、Ext.Level,以及客户端 Lua 状态。
关键偏移
esv::EocServer::m_ptr:0x10898e8b8- EntityWorld:EocServer+
0x288 RPGStats::m_ptr:base+0x89c5730RPGStats.FixedStrings:+0x348- GlobalStringTable:base+
0x8aeccd8
osgrep 用法
需先切换到项目目录再检索,例如 cd /Users/tomdimino/Desktop/Programming/bg3se-macos 后执行 osgrep "how does entity lookup work" 或 osgrep "Ext.Stats property resolution"。检索 Windows 参考实现时可进入 bg3se 目录执行 osgrep "CustomFunctionManager"。
常见任务
新增 Ext. API:在 src/lua/lua_.c 中实现,在 lua__register() 函数中注册,用 EntityTest mod 测试。
发现偏移:在 Ghidra 中搜索字符串,查找 XREF,追踪 ADRP+LDR 模式,记录到 ghidra/offsets/*.md。
移植 Windows 功能:先用 osgrep 搜索 Windows BG3SE,理解模式后找到 ARM64 等价实现,再适配 macOS 约束。
参考文档
macos-patterns.md(macOS 与 Windows 差异、GUID 字节序、组件遍历)、bg3se-architecture.md(Windows BG3SE 结构)、arm64-patterns.md(x8 寄存器、调用约定)、ghidra-workflows.md(脚本用法、分析模式)、offset-discovery.md(查找游戏地址)。
故障排查
启动崩溃:检查 dylib 签名(codesign -dv),验证 ARM64(file)。
Hooks 未被调用:只挂钩 libOsiris,不要挂钩主二进制。
实体查找返回 NULL:EoCServer 可能尚未初始化,验证偏移 0x288。
osgrep 无结果:从项目目录运行,或使用 -p 标志。