文档目前只有中文。

0002. 核心作为进程内静态库，手写 C ABI，JSON 跨边界

状态：接受日期：2026-10-08

背景

界面与核心语言不同，需要一个边界。目标是单个可执行文件、无额外进程、不引入社区维护的绑定生成器。

决定

核心编译为静态库链接进原生应用。对外只暴露手写的 C 头文件，函数不超过二十个，业务方法统一经 grain_call(method, params_json) 调用，复杂数据以 JSON 字符串传递，事件用 C 回调推送。Swift 直接导入头文件，C# 用 P/Invoke。

备选与放弃理由

• 独立进程 + 本地套接字：性能开销可忽略，但多一个进程、多一个文件，与"单文件"目标相悖。
• UniFFI 等绑定生成器：省手写工夫，但 C# 侧由社区个人维护，不符合依赖门槛。
• 全部 #[repr(C)] 扁平结构体：略快，但接口膨胀严重，每加一个字段都要改头文件。

后果

• 失去崩溃隔离，用 C 边界 catch_unwind 补偿，release 用 panic = "unwind"。
• 游戏进程必须以分离方式拉起，标准输出直接写文件，不走管道。
• 命令行工具是独立二进制，链接同一核心库。