A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
docs: the procedural world plan records what the engine owes, where each part stands and how it is accepted
yhh087cb457a37c
diff --git a/docs/WORLD_GENERATION_PLAN.md b/docs/WORLD_GENERATION_PLAN.mdnew file mode 100644index 000000000..4b4e6b9b3--- /dev/null+++ b/docs/WORLD_GENERATION_PLAN.md@@ -0,0 +1,84 @@+# 程序化世界:引擎侧工作计划++2026-10-24 建立。来源:星邻(star-neighbors)项目的《群落与随机世界的空间组织》(`docs/13-biome-and-world-layout.md`)与地形/水域交接(`docs/12-procedural-terrain-handoff.md`),以及本仓库同日的地形、水体、性能工作。本文记录 Estella 需要提供的通用能力、当前状态与验收;游戏规则(家园、资源经济、路线)与美术配方不在引擎内实现。++审查基线说明:交接文档的源码结论对应 `95afb8273`。之后本仓库已改动水体(区域烘焙、优先级)、地形(CDLOD 四叉树、分页高度图、无限地形)与植被(避水、按距离稀疏),各项“当前状态”以本文为准。++## 三方职责++| 归属 | 能力 |+| --- | --- |+| Estella | 连续场采样、群落权重与过渡、排除/保留区、组合生成、优先级与相交查询、确定性身份、分块生命周期与预算、调试显示、渲染/碰撞/查询一致 |+| 游戏(星邻) | 家园规模、起始资源、路线连通、探索节奏、安全落点、可建造条件、资源状态与存档、具体生成算法(`generateChunk`) |+| 美术 | 群落色板与材质、物种、密度变化、树群/岩组/岸带组合配方、留白与遮挡标准、示例场景与评审 |++生成次序(引擎提供支撑,游戏编排):宏观地貌与环境场 → 活动空间与连接(保留区)→ 群落内部结构 → 大物件与组合 → 局部装饰 → 验收与持久差异。++## 优先四项++### T-01 同一份、带版本的地表数据++- 需要:程序化区块数据入口,接收 `generateChunk(seed, algoVersion, cx, cz)` 或同职责的 provider;输入含星球/区块身份、生成器版本、世界坐标原点、采样间距、高度与群落权重;渲染、碰撞、放置、服务端共用同一数据。不替换已保存星球的旧算法。+- 失败处理:高度数据缺失或加载失败时,持久星球报告失败并保持旧数据或等待,不得悄悄回退为噪声。+- 当前状态:地形已改为“数据源”(`TerrainSource`)驱动:`FieldSource`(区域高度场)、`NoiseSource`(世界坐标、按种子、无限)。尚缺:外部 provider 接口、生成器版本、区块身份、区域噪声仍按局部 0..1 归一化、缺图时仍回退噪声。+- 验收:同版本/种子/坐标在客户端与服务端结果相同;不同加载顺序一致;共享边高度与法线一致;缺失数据不改变旧星球。++### T-02 碰撞、贴地查询与可视表面一致++- 需要:地形碰撞(先桥接静态 `MeshCollider3D`,再评估专用高度场碰撞);碰撞精度有自己稳定的规则,不随摄像机 LOD 变化;高度/法线查询、射线、碰撞与三角面在约定精度内吻合。+- 已知差异:`sampleHeight` 双线性插值,渲染为两片三角形(3×3 合成例中对角线中点 0.5 对 1.0)。新 CDLOD 渲染按页样本插值并在细节级之间形变,同样需要与查询统一定义。+- 当前状态:未开始。+- 验收:机器人离地高度稳定;建筑四角支撑不悬空;LOD 切换、跨块、重载不掉落;掉落物、障碍、设备有真实碰撞。++### T-03 程序化区块的驻留与统一预算++- 需要:由 WorldStreamer 调度程序化地形、碰撞、植被、交互实体的准备与发布;距离/视野优先级、取消过期任务、全局帧预算、卸载释放、可查询的 ready/pending/failure;一个地块只有一个生命周期所有者。+- 当前状态:地形渲染已改为按需页(四叉树选择 + 图集 LRU 淘汰,常驻有上限),分帧作业与进度(`Bakes`)已有;植被仍遍历整个区域且按格子合并网格(非 GPU 实例化);尚未接入 WorldStreamer,尚无统一预算与取消。+- 验收:连续走过大量区块内存和实体有上限;折返不重复;快速传送不把旧请求结果发布到新星球;卸载同时移除渲染、碰撞、资产引用;远景与正交俯视 LOD 在目标设备实测。++### T-04 群落、建造排除区与持久变化++- 需要(参照 Epic PCG Biome 的分层、过渡、排除区、组合生成):+ - 环境场输入:高度/法线/坡度、湿度、水深/离岸距离、岩性,可程序生成并允许手工局部覆盖。+ - 群落定义:连续权重、相邻关系、过渡宽度、地表材质映射、物件/组合白名单。+ - 区域与保留区:形状、优先级、类型、边缘衰减(家园、道路、落点、建筑、资源交互、视线)。+ - 组合配方:锚点、成员、相对位置与可变范围、数量、占地、附着方式、允许坡度、可选成员;树冠与树干范围分开。+ - 分层布置:大物件先占位,小物件读取占用与父子关系,冲突按优先级确定性仲裁。+ - 输出:稳定 placement ID(不用数组下标)、规则/配方版本、所属区域、变换、资产、装饰或交互身份。+ - 跨块:组合按锚点所在块唯一归属,邻块读取足够边界,结果与加载顺序无关。+ - 持久:保存采集、移除、建造、有限整地的差异,重载时先叠加差异再分布可见物;装饰可合并绘制,可交互对象独立身份。+ - 调试:群落图、保留区、组边界、拒绝原因与统计。+- 当前状态:植被只有高度/坡度/水深筛选与随机种子;未开始。+- 验收:林地建房后草木不穿地板;采集后卸载重进不重生;同种子不同加载顺序结果相同;安全落点、早期资源、入口可达。++## 水域补充++### T-05 程序化水域与一致查询++| 优先级 | 能力 | 当前状态 | 验收 |+| --- | --- | --- | --- |+| P0 引擎 | 海洋范围掩码/连通性:只有与开阔海在海面高度下连通的低地属于海 | 未做:区域内海洋按“地面低于海面”判定,封闭干盆地会被填水 | 隔绝的低于海面的干盆地不显示海水、不判为水下 |+| P0 引擎 | 多水体命中规则:范围、垂向有效区间/底部、优先级、归属 | 部分:区域烘焙已让湖/河优先于海,查询读同一场且与注册顺序无关;尚缺垂向有效区间(陆地落在湖轮廓内的判定)与水体身份 | 上方湖泊不被下方海洋抢先;顺序无关;陆地不被当作水域 |+| P0 游戏+引擎接口 | 海域连通、盆地/出口、水系连接、独立水位、河床、稳定 waterBodyId | 未做(引擎侧需提供数据接口) | 跨块水位/岸线连续;高湖、低湖与干盆地共存;流向有效 |+| P1 引擎+美术 | 河湖接缝、入海口、急流/瀑布,按类型配置外观 | 部分:区域场已消除河湖接缝;拍岸浪、岸边柔化已有;河口水流纹理仍有问题 | 交界无重复透明面/突变 |++### 后续(不阻塞首块可玩地表)++| 优先级 | 项目 |+| --- | --- |+| P1 | 地形分层法线/粗糙度(每层 normal/ORM);当前地形着色器仅四张颜色图与统一粗糙度 |+| P1 | 高度图显式格式字段(取代按 G 通道猜 R8/RG16),数据图无色彩转换/预乘/有损压缩 |+| P1 | 河床与岸线生成配合(生成器形成岸线后提供湖泊边界/河流样条) |+| P2 | 球面与极远坐标(平面 XZ 的局限、原点精度) |+| P2 | 洞穴/体积挖掘(高度场不支持) |++## 引擎自身待办(同日会话记录)++- 植被改为真正的 GPU 实例化(与 T-03/T-04 的放置输出一起设计)。+- 雨天/阴天时 CPU 渲染提交阻塞约 45 ms(GPU 计时或同步读回导致),需定位。+- 编辑器三维视图套用后处理(天空/雾)后画面上下翻转;改动已撤回,需修呈现路径。+- 河口水流纹理拉伸。+- 无限地形:地貌参数(导数衰减侵蚀下呈台地状)与远处一条直线接缝需排查。+- 动态分辨率在 GPU 计时下不降分辨率。+- 编辑器启动时的 `NaN` CSS 高度报错(无调用栈)。+- 地形、植被、水体的烘焙下沉到 C++/wasm 以缩短加载(侵蚀、区域场)。diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 07d7523af..7622882c1 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2760,4 +2760,6 @@ export const NOTED = {{"internal":"Documentation of features with their own notes."},"build(render): the embedded mesh shader carries the vertex-hook colour":{"internal":"The generated embed of a shader change that has its own note."},+ "docs: the procedural world plan records what the engine owes, where each part stands and how it is accepted":+ {"internal":"A planning document; nothing a creator can use yet."},};