DOCUMENTATION · 总览
文档总览与阅读路线
核心文档已内置在站内,读完即可上手。更专深的参考(权限全表、ABI、事件契约等)提供仓库完整版。
按目的选择入口
| 我想…… | 看这份 |
|---|---|
| 第一次接触项目,看懂它是什么 | 架构总览 → 跑 npm run dev |
| 写一个剧情(JSON) | 剧情格式 · 参考 public/stories/demo.json |
| 我是编剧,不想碰 JSON | 文本剧本语法(编辑器内同源) |
| 用 TypeScript / JavaScript 写插件 | JS 插件开发 → 仓库 PERMISSIONS.md |
| 用 Rust 写 WASM 插件 | WASM 插件开发 → 仓库 ABI.md |
| 做世界模拟器 / 让剧情被动听世界 | 剧情格式(observe)→ 架构总览(WorldLoop) |
| 把引擎当库嵌进自己的前端 | 仓库 FRONTEND.md;快速路径见主站代码示例 |
| 部署上线 / 被 iframe 嵌入 | 仓库 CROSS_ORIGIN.md —— COOP/COEP 的代价是静默的,先读 |
| 排查「插件加载失败」「剧情不更新」 | FAQ |
动手区 & 站内文档(十四篇)
PLAY
在线工作台 ◉
点开就玩:三种结局,结局徽章记录你的通关;还能导入剧情 JSON、挂载 JS 插件、在线编辑即改即玩。零门槛,驱动它的就是引擎本体。
PLAYGROUND
在线试玩 ▶
贴一段剧情 JSON,右边立刻跑——真引擎 Runtime 驱动,内置节点全部可用,不装环境。
NODE_GRAPH
交互节点图 ▣
把示例剧情画成一张可拖拽、可缩放的节点图:分支、条件、三种结局,点节点看 JSON。
STORY_FORMAT
剧情格式
顶层字段、11 种内置节点、条件表达式 DSL、四个状态命名空间、派生状态。写剧情的人从这里开始。
SCRIPT_TEXT
文本剧本语法
给编剧的写法:场、对白、选择、条件分支、结局 —— 编辑器文本模式的完整语法,写坏了不丢内容。
PLUGIN_JS
JS 插件开发
manifest 字段、JsPlugin 接口、ctx 全部能力速查、生命周期时机,以及「状态读写别整块搬」的真坑。
PLUGIN_WASM
WASM 插件开发
Rust(wasm32 · 裸 C ABI):必须导出的函数、宿主 imports、UTF-8 JSON 跨边界、谁分配谁释放。
ARCHITECTURE
架构总览
四层结构、依赖方向、插件生命周期、错误隔离三道防线、权限模型与关键设计取舍。
FAQ
常见问题
插件加载失败、WASM 实例化失败、剧情不更新、调试、打包发布、错误码速查 —— 按现象排查。
EVENTS
事件总线
引擎生命周期、节点流转、状态变更广播与插件自定义事件 —— 一张事件时刻表。
ABI
WASM ABI 参考
C ABI 契约：内存布局、导出函数表、宿主函数与错误码，写给写 Rust 插件的人。
PERMISSIONS
权限模型
21 项细粒度权限：按能力授予，插件越权当场拦截 —— 安全边界一览。
CROSS_ORIGIN
跨域与嵌入
iframe 嵌入、postMessage 桥、CORS 与安全策略：把剧情引擎放进任何页面。
FRONTEND
前端集成
初始化、生命周期、与 React / Vue / 原生页面的配合方式。
BUILD
构建指南
Vite 双形态产物、Rust→WASM 编译链与发布流程，从源码到 dist。
TESTING
测试体系
439 个用例怎么组织：单元、集成与剧情回归，测试也是游戏玩家。
CHANGELOG
更新日志
每个版本的能力、修复与破坏性变更，升级前先看这里。
仓库完整文档
以下偏参考手册性质,提供仓库完整版(与代码的一致性由 23 个文档检查器用例兜底):
PERMISSIONS.md 权限全表 ABI.md WASM 接口 EVENTS.md 事件契约 FRONTEND.md 前端集成 CROSS_ORIGIN.md 部署 TESTING.md 测试 BUILD.md 构建 CHANGELOG.md 版本
推荐阅读顺序(第一次接触):主站 README → 架构总览 → 跑
npm run dev 观察页面 → 按上面路线深入。
元规则:src/ 下每个 .ts 都必须在文档里被提到,文档不会烂在实现后面。