开发环境

环境要求

Node.js 24 或更新版本（仓库的 .nvmrc 指定了 24）。
package.json 中 packageManager 字段指定版本的 pnpm。
浏览器回归测试需要 Playwright 的 Chromium。
Unity 探针需要本地的 Unity Editor，普通构建和测试不需要。

准备

pnpm install --frozen-lockfile

仓库结构

路径	内容
`packages/natsume/`	运行库本体：`src/` 是源码，`tests/` 是单元测试和浏览器回归测试，`schemas/` 是 NOIR、NOMS 和 NOAP 的模式文件
`packages/playground/`	预览页，用于打开本地 `.noap` 文件，也是接入代码的参考
`tools/unity-probe/`	用本地 Unity Editor 测量行为的探针，以及测量记录
`tools/benchmarks/`	性能基准脚本
`docs/`	本文档站

reference/ 和 data/ 是本地目录，不进入版本库，用来存放参考资料、样本包和测量产物。

常用命令

pnpm dev             # 启动预览页
pnpm build           # 构建运行库和预览页
pnpm typecheck       # 类型检查
pnpm test            # 单元测试
pnpm test:browser    # 浏览器回归测试
pnpm lint            # ESLint
pnpm format:check    # Prettier 检查
pnpm format          # Prettier 格式化

pnpm docs:dev        # 本地预览文档站
pnpm docs:build      # 构建文档站
pnpm docs:preview    # 预览构建结果

浏览器回归测试需要先安装 Chromium：

pnpm exec playwright install chromium
pnpm test:browser

预览页

pnpm dev

打开终端显示的地址，选择 .noap 文件即可预览，文件在浏览器本地读取。

包需要脚本动画字段时，先用"Bridge 声明"导入一个 JSON，再选择 .noap：

json

[
  {
    "identity": {
      "assembly": "Assembly-CSharp",
      "namespace": "MyGame",
      "className": "MaterialSettings"
    },
    "animatedFields": { "mode": "int" }
  }
]

预览页只记录字段的变化，不执行原游戏的逻辑。更换声明需要刷新页面。预览使用静止的 Rigidbody、无雾和关闭软粒子的环境。

缺少项目的排序层信息时，用"排序层"导入一个 ID 到排序值的 JSON，例如 {"-123456": 2}。预览页不会猜测未知层的顺序。

生成的绑定

NOIR 和 NOMS 的 TypeScript 绑定由 FlatBuffers 编译器生成，放在 packages/natsume/src/format/generated/，已经提交到仓库，普通构建不需要安装 flatc。

只有修改模式文件时才需要重新生成：

NATSUME_FLATC=/path/to/flatc pnpm generate

生成脚本会先核对 schemas/provenance.json 里记录的模式哈希，再检查 flatc 的版本是否与记录一致。两者不符会直接报错。

提交约定

提交信息遵循 Conventional Commits，例如 feat(runtime): ...、fix(particles): ...。每个提交只包含一项逻辑上相关的改动。

提交前的检查

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm test:browser
pnpm build && pnpm --filter @untitled-story/natsume check:declarations

最后一条构建运行库，并用严格的库检查对生成的类型声明做类型检查，防止声明引用了已被移除的内部类型。

较慢的原生对照用例在并行运行时可能超过默认的超时，可以单独运行，或用 --timeout 加大超时。

发布

发布由推送版本标签触发（.github/workflows/release.yaml）：

修改 packages/natsume/package.json 里的 version，提交。
创建与版本一致的标签 v<version>，例如 v1.0.0-alpha.2，并推送。

工作流先核对标签与 version 一致，然后依次执行类型检查、单元测试、构建和声明检查，通过后发布到 npm，并创建 GitHub Release。

版本号带 -alpha、-beta 或 -rc 后缀时，npm 的 dist-tag 是 prerelease，GitHub Release 标记为预发布。其他版本使用 latest，并且 prerelease 也会指向这个版本，这样安装 @prerelease 总能得到最新的一个，而不会停在比正式版更旧的预发布版本上。这一步使用 npm dist-tag，在 npm 的 Trusted Publisher 配置里需要勾选 Allow npm dist-tag。所以安装预发布版本需要显式指定：

npm install @untitled-story/natsume@prerelease pixi.js

文档站由 docs.yaml 在 main 分支有推送时构建并部署到 GitHub Pages，地址是 https://natsume.untitled-story.org/。仓库的 Settings → Pages 里，Source 需要选择 GitHub Actions。站点使用自定义域名，部署在域名根路径，所以不需要设置基础路径。

日常的拉取请求和 main 分支由 ci.yaml 检查：类型、lint、格式、单元测试、构建、声明和文档构建，以及浏览器回归测试。依赖本地 Unity 测量数据的对照用例在 CI 里会被跳过。

开发环境 ​

环境要求 ​

准备 ​

仓库结构 ​

常用命令 ​

预览页 ​

生成的绑定 ​

提交约定 ​

提交前的检查 ​

发布 ​