SuperAPI AI 工具集

bg3se-macos-ghidra

编程与开发

查看项目

更新于 10-16 16:29

技能介绍

用途

本技能面向《博德之门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 关键约束

  1. 不能挂钩主二进制——Hardened Runtime 会阻止对 __TEXT 段的 hook。
  2. 可以挂钩 libOsiris.dylib——该库有 1,013 个导出符号。
  3. ARM64 ABI——大于 16 字节的结构体使用 x8 寄存器传递。
  4. 没有 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/Event
  • Ext.Osiris:95%,RegisterListener、NewCall/Query/Event
  • Ext.Stats:95%,属性读写
  • Ext.Entity:50%,Get、GetComponent、GetAllEntitiesWithComponent
  • Ext.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+0x89c5730
  • RPGStats.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 标志。