版本历史

v3.2 存档加固与测试基建

• core 崩溃安全存档原语(saveFiles):业务无关的"原子文件 + 轮换备份"层 —— 临时写入 → fsync → 读回校验 → 备份轮换 → 原子重命名,配合信封校验(magic + 长度 + SHA-256)抓物理损坏;不含存档头部业务字段。AtomicFileBackend 六原语接口(writeFile/syncFile/renameFile/readFile/deleteFile/exists)由 core 编排但不实现;commitSlot 保证任意时刻中断 path 都指向完整的一代,recoverSlot 按 current → backup1 → backup2 新到旧扫描,返回首个通过校验的一代及每一代的失败原因
• 两个后端实现:新包 adapters-savefile(Tauri 桌面壳)—— createTauriSaveFileBackend() + 配套 Rust 插件 crate overworld-savefile(crates.io 单独发布)提供真正的 fsync(Tauri 官方 plugin-fs 的 JS API 不暴露此能力),resolve_path 拒绝绝对路径与 Windows 根路径;platform 新增 createWebSaveFileBackend()(localStorage 实现,syncFile 为 no-op —— 浏览器没有 fsync 等价物)
• core createSeededRng/RngSource:零依赖确定性 PRNG(mulberry32),任何工厂函数都可接受注入的随机源 —— 生产传 { next: Math.random },测试传固定种子得到字节级可复现结果
• 新包 @overworld-engine/test-kit:应用层集成测试原语 —— createEventRecorder(基于 EventBus.onAny 的确定性事件流录制断言)+ renderHook(react-test-renderer 挂载单个 hook,无 DOM/Canvas/WebGL,验证 hook→action 接线);非渲染/E2E 框架
• 流程修复:CI 新增 changeset 强制检查(PRs 改动 packages/*/src/src-tauri 必须带 changeset,pnpm changeset --empty 可显式豁免);全部 27 包的 CHANGELOG 按 git 发布史回填,npm 已发布版本与 changelog 条目一一对应

v3.1 Steam 桌面适配(新包 adapters-steam)

• createSteamBridge():把 Steamworks 成就、Steam Cloud 存档、Rich Presence 桥接进 Tauri 桌面壳,API 在 Steam 环境之外静默 no-op、优雅降级;bridgeSteamAchievements() 将 core 的 achievement:unlocked 事件转发给 Steam
• 配套 Rust 插件 crate overworld-steam(crates.io 单独发布,封装 steamworks-rs);不支持 Steam Overlay/好友 UI —— Tauri 基于 WebView2 的渲染拿不到 Overlay 所需钩子,但成就/云存档/Rich Presence 都是纯 API 调用,不受影响

v3.0 UI 扩展性重构(破坏性)

• 破坏性:Modal 改为复合组件 { Root, Content, Close } 替代单组件写法(附迁移 diff)
• 破坏性:桶导出 Slot(背包格子组件)更名 InventorySlot —— Slot 这个名字现在属于新的 asChild 原语;类型 SlotProps 同步更名 InventorySlotProps(旧导入仍能解析、但落到新原语的类型上,表现为类型不匹配而非编译报错,需手动切换)
• Button/IconButton 支持 asChild:把 props/ref 渲染到单个子元素而非自身 <button>;背后是新的公共 Slot 原语(可用来构建自己的 asChild 组件),Modal.Close 同样支持
• 新增 packages/ui/README.md(导出/主题/新 API);CI 起用 dependency-cruiser 强制零跨包导入规则

v2.4 导航 HUD 与空间焦点

• 导航 HUD 组件:MinimapFrame/Compass/WaypointIndicator + normalizeAngle/compassOffset/compassTicks/edgeAnchor 纯函数;与 @overworld-engine/minimap 组合但不产生包依赖(宿主把 <MiniMap> 嵌进 <MinimapFrame>,给 Compass/WaypointIndicator 喂朝向与离屏方位角)
• 空间焦点导航(可选子路径 @overworld-engine/ui/focus):FocusProvider/Focusable/useSpatialFocus/useGamepadFocus,基于 @noriginmedia/norigin-spatial-navigation(可选 peer 依赖,核心包保持零依赖);Button/IconButton/Slot 改为 forwardRef;Modal 获得键盘焦点陷阱(Tab 循环、Esc 关闭、关闭后焦点还原)
• v2.4.1 修正:hextech 主题按钮造型统一为斜切标签族(替换掉让透明 ghost 按钮像浮动括号的侧尖切角);ghost 按钮改为淡半透明填充 + 柔金描边,danger 按钮改为红调填充

v2.3 战斗 HUD

• 战斗组件:CastBar/BuffBar/TargetFrame/Nameplate + castProgress/buffSweepPct/formatBuffTime 纯函数
• 稀有度色板扩展到六档(poor / common / uncommon / rare / epic / legendary);注意 --ow-color-rarity-common 由灰(#9aa0b0)改为近白(#f0f0f0) —— 既有 common 品质 Slot 描边的观感会变化

v2.2 无头游戏 UI(新包 ui)

• 新包 @overworld-engine/ui:无头游戏 UI 库 —— HUD 原语(Hud/Panel/GameWindow/Bar/Slot/SlotGrid/Hotbar/Button/Tooltip/Modal);通过鸭子类型接口绑定引擎的组件(DialogueBox/QuestTracker/QuestLogWindow/InventoryWindow/ToastViewport/AlertHost/TutorialOverlay/AchievementPopup),UI 包不 import 引擎包;行为 hooks、中性基础样式表、四套主题皮肤(仙侠 xianxia / 海克斯 hextech / 战术 tactical / 像素 pixel)

v2.1 世界生产化质量收口

收口审计反馈差距:

• scene:GPU 感知质量检测(软渲染 → 低档);动画 NPC 契约(animationMap.idle、默认 idle 播放、onModelReady);移动 NPC 经 animStateRef 切换 idle↔walk↔run;运行时 LOD 设备档封顶 + 就近优先预载;装饰物按组切换 LOD(逐实例 LOD 析构有意不发 —— 与 drei 共享 GLTF 缓存不兼容)
• environment:曝光与独立月球旋钮;昼夜光色逐帧插值(修掉 0.5 硬切换的跳变);transitionDuration 成为可声明的 preset 字段
• loading:跨区域进度聚合;优先级桶区域排序;真正的区域重试(重新拉取失败资产);资产加载失败冒泡到 failZone
• minimap:createHeadingTracker 由连续位置推断朝向;RadarEntity 改为配置形态(结构化,不再 import scene)

v2.0 世界生产化(world-production v2)

• core inputLock:无头、框架无关的输入锁(acquire/release/isLocked/activeLocks/subscribe/releaseAll)+ createInputLock() 隔离实例 + input:lock-changed 总线事件 —— input(键盘层、摇杆)与 scene(Player、交互、FollowCamera 轨道)统一向它查询,一次 inputLock.acquire('dialogue') 即全局挂起游戏输入,无需逐源接线
• scene(major):实例化 Decorations 渲染器;运行时 Lod + lods 配置;FollowCamera 轨道相机;ref 驱动的移动 NPC(SceneShell.npcPositionRefs 驱动 BaseNPC 的视觉/碰撞体/邻近/选中环,BaseNPC.positionRef;独立移动 NPC 用 AgentNPC);isInputBlocked 省略时回退到 inputLock.isLocked()
• input:useKeyboardLayer 接受 { lockInput } 选项(层存活期持有共享 inputLock;导出 parseLayerOpts);<VirtualJoystick respectInputLock>(默认 true)持锁时输出清零(纯函数 resolveJoystickOutput)
• audio:命名总线(master/music/ambience/sfx,setBusVolume/getBusVolume);基于距离的环境音区(setAmbientZones/updateListener + 纯函数 zoneWeight/mixBuses);定位单发 playCue;测试/无头环境用 silentBackend
• environment:<WorldEnvironment preset engine quality> —— 质量感知的天空/雾/地面/光照/星空层,WORLD_ENV_PRESETS(clear-noon/overcast/foggy-dusk/night)+ 纯函数 resolvePreset/resolveLight;传入 engine 时环境光/日光随其时间逐帧插值
• loading:场景级加载状态 useSceneLoadStore(相位 idle → module → geometry → texture → first-frame → ready,SCENE_PHASES/aggregateSceneProgress);区域流式加载(useZoneStreaming/orderZonesByDistance,ZoneManifest/ZoneBounds);<FirstFramePhase /> Canvas 标记;installSceneLoadDebugHandle()(开发构建下 Playwright 友好的 window.__overworldSceneLoad 检查句柄)
• minimap:玩家相对 HUD 雷达选择器 —— selectRadarMarkers(世界实体 → 旋转/距离钳制的标记)与 computeOffscreenIndicator(超程实体的屏幕边缘角),RadarConfig/RadarMarker/RadarEntity 类型

v1.5 规模化授权与实时调试

• 编辑器多场景/关卡管理:命名场景(新建/切换/改名/删除/复制)、exportProject/importProject 多关卡项目;devtools sceneProjectSchema + validateSceneProject;scene pickScene 按名渲染指定关卡。scene-authoring 示例升级为多关卡授权闭环
• 新包 @overworld-engine/inspector:createEventStream 环形缓冲(确定性、可测)+ <EventBusInspector> 实时事件流/计数面板 + <StoreInspector> zustand store 实时快照;dungeon 示例接入(反引号开关),E2E 验证真实事件与 store 字段
• 新包 @overworld-engine/content:defineContentPack/validateContentPack/applyContentPack —— 校验门控后把对话/任务/物品/成就热更新注入引擎;examples/content-packs 演示 v2 包热更新
• core defineMigrations:顺序版本迁移辅助,配合 persistOptions({ version, migrate }) 演进存档结构

v1.4 授权闭环与出包硬化

• 编辑器↔SceneShell 场景往返(授权闭环):scene <SceneFromJson> + 纯映射器(sceneJsonToShellProps/sceneConfigToSceneJson);devtools sceneConfigSchema + validateScene;editor sceneConfigToEditorEntities/loadSceneConfig。新示例 examples/scene-authoring 端到端演示 编辑 → 导出 → 校验 → 从 JSON 出图 → 重新导入(E2E:导出校验 0 错、SceneFromJson 渲染 5 网格、往返实体数一致)
• 跨端云端命名存档槽位:FlushableStorage.flush()(Telegram CloudStorage / Tauri 文件存储,app:paused 前落盘);createSaveSlots 直接跑在 CloudStorage 上,槽位键 overworld:slots:* 同样透明编码为合法 wire key
• 发布签名与商店上架脚手架:build-artifacts.yml 增签名/上传步骤(Apple 公证 / Windows 签名 / Google Play / TestFlight),secrets 缺失时 skip 不 fail(无签名构件照常产出);docs/guides/signing-and-store.md 四端手册

v1.3 原生交互与出包

• 微信小游戏完整交互:R3F 指针桥(createWeappPointerBridge,wx 触摸驱动的 raycast 拾取,点 NPC 网格→onClick)+ vendor XMLHttpRequest-over-wx.request polyfill 使 useGLTF 可加载真实 GLB;wx-shim harness 新增两条真断言
• Telegram CloudStorage 云存档:createTelegramCloudStorage(异步加载→同步 Map 镜像→异步写穿);透明键编码(overworld:quest ⇄ overworld_003Aquest)让冒号命名的框架 store 直接接入 Telegram 的 [A-Za-z0-9_] 键约束
• CI 出包矩阵:ci.yml 新增 examples 编译 job;build-artifacts.yml 产出无签名的 Tauri(macOS/Windows)+ Capacitor(Android debug / iOS 模拟器)构件;修复 pnpm/action-setup 与 packageManager 的冲突
• scene SceneShell 透传 labelMode;createWeappCanvasRoot 内置 extend(THREE)

v1.2 确定性与联机基建

响应首个生产消费方(投资模拟游戏)的需求反馈:

• 确定性注入:achievements/quest/saveSlots/presence 的 clock、toasts 的 clock + scheduler(默认不变;重放全等测试背书)
• @overworld-engine/relay(新包):正式中继服务器(npx/编程 API/挂载既有 http server),与 net 客户端真 socket 互操作测试
• 线路协议规范:信封/peerId/房间/t 多路复用/自建兼容中继检查单,2.0 前只增不改
• 权威多人接入指南(外部确定性内核作为共享 step)
• DOM 组件 data-testid + 官方测试指南(store 驱动断言);configureEditorLabels 文案覆写;持久化互操作指南;npm workspaces 兼容确认

v1.1 多端支持

• 新包 platform:平台检测/能力/桥(web/telegram/tauri/capacitor/weapp),app:paused/resumed/back 事件
• 新包 adapters-weapp:wx 存储/socket/音频适配器、createWeappCanvasRoot(R3F 免 react-dom)、触摸摇杆
• 微信小游戏完整 3D:examples/weapp-game(wx-shim 真浏览器 harness 21 断言,发布包体 1.01MB)
• 端模板:telegram-mini-app / desktop-tauri(macOS 实测出包)/ mobile-capacitor
• audio 后端注入 + pauseOnHide;scene SpriteLabel 跨端标签 + labelMode
• 指南:docs/guides/platforms.md(矩阵/接线/注入对照/上架红线)

v1.0 首个公开发布(2026-07-16)

• npm 正式发布:@overworld-engine/* 1.0.0,18 个包作为同一 fixed 版本组一起上架(标准 ESM + .d.ts,npm/yarn/pnpm 通用)
• 文档站上线:overworldengine.com(Fumadocs,中文全文搜索 + llms.txt),部署于 Ship Dock
• 开源:GitHub luzhenqian/overworld
• API 冻结:承接 v0.8 的 1.0 API 评审与 v0.9 的破坏性收官,进入 1.x 稳定期(2.0 前只增不改)

v0.9 破坏性变更收官

• P1 store 形态统一:dialogue/quest/audio 全部改为 { store, ...方法 }(React 端 useStore(engine.store, sel)),全框架 8 个引擎形态一致
• P2 interact → entity:interact(双发过渡,旧名 2.0 移除)
• P3 audio persist 默认对齐约定(省略 = 关闭)
• P11 NPCWalker 新增 driven/tree,行为树组合不再双步进
• P12 BaseNPC/BaseBuilding 回退几何体与标签高度尊重 scale(默认值下视觉不变)
• P13 模型加载改为标准 Suspense + 错误边界;顺带修复 Player/Portal 无边界导致的潜在整树挂起
• P14 blockCell/createNavGridFromCells 格子级建网格(tile 地图一等公民)

v0.8 泛化验证与发布流水线

• 第二款示例游戏 examples/dungeon:种子化程序地牢、行为树敌人(巡逻→追击→回岗)、钥匙宝箱任务链、HPA* 引路点、心心/击退/通关计时 —— 验证框架泛化性,并带回 6 个 1.0 前待修阻力点
• 1.0 API 冻结评审(docs/api-review-1.0.md):就绪度 B+,15 项提案(store 形态统一、interact 加域名前缀等);低风险修复已落地(audio events 规范别名、persist 文档纠错、core README)
• 发布流水线:changesets(fixed 版本组)+ CI/Release 工作流,18 包 publish --dry-run 全通过
• 性能基准(benchmarks/):24 项基准 + 基线对比 + 8 个计数型回归守护;HPA* 访问格数少 17.9 倍,事件总线 ~250 万 emit/秒

v0.7 输入预测与编辑器进阶

• 输入预测与服务器对账:createPredictedState(预测/序号排队/回滚重放/误预测纠正)+ createInputChannel + examples/authority-server 权威服务器示例(含反作弊 clamp 演示)
• 编辑器多选与对齐:shift 点选、群组拖拽单撤销步、对齐(min/center/max)与均分、Ctrl+A/Delete/Ctrl+D 作用于选区
• 性能预设(scene):三档 DPR/阴影/粒子系数 + ApplyQuality + 设备启发式检测
• 内容热重载约定:import.meta.hot + registerX 增量替换指南(语义对照源码核实),starter 已接线

v0.6 联机进阶与云存档

• 联机进阶:createSnapshotBuffer 延迟插值缓冲、presence interpolation 选项、examples/ws-server 参考中继服务器
• 编辑器实体模板(一键放置预设)与 GLTF 真实模型预览(失败自动回退)
• createRestStorage 云存档 REST 适配器(防抖/flush/错误吞吐)
• profileBus 事件总线性能剖析(计数/耗时/报表)

v0.5 多人同步与层级寻路

• @overworld-engine/net:多人同步接口抽象 —— Transport 接口(内存 / BroadcastChannel / WebSocket)、presence 复制、事件中继、<RemotePlayers> 组件
• 编辑器撤销/重做(transient 突发合并)、复制、吸附可调、网格可视化
• 层级化寻路 HPA*(200×200 基准:访问格数 3,393 vs 普通 A* 35,873)
• 行为树(记忆式 sequence/selector、parallel、blackboard、agent 动作节点)

v0.4 场景编辑器与 NPC 日程

• @overworld-engine/editor:游戏内场景编辑器雏形(放置/拖拽/属性面板/导出 JSON)
• NPC 日程系统(昼夜相位驱动行为切换)与动态避障
• 内容 JSON Schema(draft 2020-12,ajv 可用)

v0.3 寻路 AI 与开发工具

• @overworld-engine/ai:网格 A* 寻路 + 巡逻/游荡/跟随行为 + <NPCWalker>
• @overworld-engine/devtools:内容校验(引用完整性/前置循环/效果条件核对)+ 事件日志
• 资产清单(defineAssetManifest/preloadManifest)、i18n 内容组织约定

v0.2 昼夜天气与小地图

• @overworld-engine/environment(昼夜循环+天气)、@overworld-engine/minimap
• 虚拟摇杆 + Player 外部输入源、存档槽位管理
• persist 配置全框架统一(省略/false=关,true=默认,对象=自定义)

v0.1 框架初始提取

• 初始提取 12 个基础包:core / scene / input / dialogue / quest / inventory / achievements / tutorial / audio / notifications / loading / analytics
• 确立三大解耦机制:类型化事件总线、条件/效果注册表、内容注入