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.
程序化世界:引擎侧工作计划
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;输入含星球/区块身份、生成器版本、世界坐标原点、采样间距、高度与群落权重;渲染、碰撞、放置、服务端共用同一数据。不替换已保存星球的旧算法。 - 失败处理:高度数据缺失或加载失败时,持久星球报告失败并保持旧数据或等待,不得悄悄回退为噪声。
- 当前状态:已完成(e4937e148)。
TerrainProvider(sdk/src/terrain/provider.ts)按区域采样(世界、种子、版本、世界坐标起点、间距、样本数),可异步;registerTerrainProvider注册游戏自己的生成器,引擎噪声为estella:noise版本 1;Terrain.provider/world/generatorVersion;未注册、版本不存在、高度图读不到 →Terrains.status为 failed 并给出原因,不回退噪声。测试sdk/tests/terrain-provider.test.ts。后续已补:无高度图的区域改为在世界坐标向其生成器取样(区域即生成器地面的窗口,相邻同尺寸区域无缝,可用游戏自定义生成器);以生成器取样的地形在实体移动后重建、世界地面不变。 - 验收:同版本/种子/坐标在客户端与服务端结果相同;不同加载顺序一致;共享边高度与法线一致;缺失数据不改变旧星球。
T-02 碰撞、贴地查询与可视表面一致
- 需要:地形碰撞(先桥接静态
MeshCollider3D,再评估专用高度场碰撞);碰撞精度有自己稳定的规则,不随摄像机 LOD 变化;高度/法线查询、射线、碰撞与三角面在约定精度内吻合。 - 已知差异:
sampleHeight双线性插值,渲染为两片三角形(3×3 合成例中对角线中点 0.5 对 1.0)。新 CDLOD 渲染按页样本插值并在细节级之间形变,同样需要与查询统一定义。 - 当前状态:已完成第一步。统一定义见
sdk/src/terrain/surface.ts:cellSize格点、节点高度取数据源、每格沿 (1,0)–(0,1) 对角线切分,与最细一级渲染补丁同一三角面(差异仅 GPU 16 位高度编码);heightAt/normalAt(三角面法线)读它;碰撞按 32 格分块,在每个运动刚体与角色周围collisionDistance内构建,经通用的CollisionGeometry资源(sdk/src/runtime/collisionGeometry.ts)交给 3D 物理,每块一个静态网格刚体;重建期间旧块保留到新块覆盖;Terrains.collisionReadyAt供游戏等待。测试sdk/tests/terrain-surface.test.ts(含真实 Jolt:射线跨块缝与heightAt吻合到 1e-3、落球静止在地面上)。后续已定:不用 Jolt HeightFieldShape(按块 8 位量化样本、对角线方向固定,会破坏"查询 = 碰撞 = 所画三角面";网格分块每块约 37KB,内存不是瓶颈);远处无运动物体时用Terrains.raycast对同一组三角面精确求交(测试中与 Jolt 射线逐点一致);分块驻留已归 T-03 的ProceduralChunks。 - 验收:机器人离地高度稳定;建筑四角支撑不悬空;LOD 切换、跨块、重载不掉落;掉落物、障碍、设备有真实碰撞。
T-03 程序化区块的驻留与统一预算
- 需要:由 WorldStreamer 调度程序化地形、碰撞、植被、交互实体的准备与发布;距离/视野优先级、取消过期任务、全局帧预算、卸载释放、可查询的 ready/pending/failure;一个地块只有一个生命周期所有者。
- 当前状态:已完成主体。
ProceduralChunks(sdk/src/residency/chunks.ts)是程序化区块的唯一生命周期所有者,与 WorldStreamer 共用WorldStreamingSource(无源时退回视点);各"层"登记切分、范围、加载/卸载半径、代次与 make/publish/release。每帧跨层按距离排序,源所在区块立即生成,其余在统一帧预算(Bakes.budgetMs与Bakes.hasTime,与烘焙作业、地形页共享,被挤占时作业让出一半)内生成;异步结果按代次丢弃并中止AbortSignal(快速传送不发布旧结果);代次变化时旧版本保留到新版本替换;超出卸载半径即释放其发布的一切;status/stateAt可查询 ready/stale/pending/making/failed 与原因,进度并入状态栏。已迁入:地形碰撞块(跟随运动刚体与角色)、植被格(跟随视点,到drawDistance)。测试sdk/tests/procedural-chunks.test.ts。植被 GPU 实例化评估结论:暂不采用。渲染器的实例记录是每帧重写上传的瞬时纹理,5 万片草叶约 6MB/帧;按格合并的静态网格每帧零上传、GPU 顶点量相同,内存已由驻留限制;真正的实例化需要持久实例缓冲(UE HISM 式),作为渲染器功能另立。仍欠:地形页仍由四叉树 + 图集 LRU 自管(已共用帧预算并限制异步并发);远景与正交俯视 LOD 需在目标设备实测;交互实体待 T-04 作为层接入。 - 验收:连续走过大量区块内存和实体有上限;折返不重复;快速传送不把旧请求结果发布到新星球;卸载同时移除渲染、碰撞、资产引用;远景与正交俯视 LOD 在目标设备实测。
T-04 群落、建造排除区与持久变化
- 需要(参照 Epic PCG Biome 的分层、过渡、排除区、组合生成):
- 环境场输入:高度/法线/坡度、湿度、水深/离岸距离、岩性,可程序生成并允许手工局部覆盖。
- 群落定义:连续权重、相邻关系、过渡宽度、地表材质映射、物件/组合白名单。
- 区域与保留区:形状、优先级、类型、边缘衰减(家园、道路、落点、建筑、资源交互、视线)。
- 组合配方:锚点、成员、相对位置与可变范围、数量、占地、附着方式、允许坡度、可选成员;树冠与树干范围分开。
- 分层布置:大物件先占位,小物件读取占用与父子关系,冲突按优先级确定性仲裁。
- 输出:稳定 placement ID(不用数组下标)、规则/配方版本、所属区域、变换、资产、装饰或交互身份。
- 跨块:组合按锚点所在块唯一归属,邻块读取足够边界,结果与加载顺序无关。
- 持久:保存采集、移除、建造、有限整地的差异,重载时先叠加差异再分布可见物;装饰可合并绘制,可交互对象独立身份。
- 调试:群落图、保留区、组边界、拒绝原因与统计。
- 当前状态:第一版已完成,模块
esengine/worldgen(sdk/src/worldgen/),示例examples/worldgen,文档world/generation。- 环境场(
fields.ts):地形 height/up/slope、水深 waterDepth、带种子噪声 moisture/temperature/rock,游戏自定义场,区域局部覆盖。 - 群落(
rules.ts、plan.ts):软区间条件相乘的连续权重、transition噪声扰动边界、按权重抽样混合、地表四层绘制映射(Terrains.setPaint),区域可强制群落。 - 区域(
zones.ts、WorldZone组件):圆/旋转矩形、类型、优先级、边缘衰减(边缘按权重确定性稀疏)、按标签排除;运行时zones().set增删只重建触及的区块;编辑器视口画轮廓。 - 配方与分层:锚点+成员(环距、角度、数量、缩放、占地与树冠分开、直立/贴地、坡度、水深、概率);层按顺序先大后小,抖动网格候选 + 随机优先级邻域仲裁(与加载顺序无关),后层避开前层占地;组合归锚点所在区块。
- 身份与持久(
diffs.ts):ID = 层@版本:网格/配方@版本/成员.序号;remove/change/toJSON/load,叠加于发布前,只重建对应区块;后加层或配方不改变已有 ID 与位置(有测试)。 - 发布:T-03 区块层;装饰按区块按种类合并网格;可交互物为独立实体带
PlacedObject{id, kind},objectOf(id);生成实体带RuntimeOnly不进存档;服务端只生成可交互实体。 - 调试:
explain(x,z)(场、群落权重、区域、各层候选与拒绝原因)、stats、biomeWeights、placementsIn。 - 测试:
sdk/tests/worldgen-plan.test.ts、worldgen-plugin.test.ts。 - 后续已补:装饰远景版本(成员
far卡片 + 层lodDistance,LODGroup 切换);贴地装饰合并时随法线倾斜。 - 后续已补:有限整地——地形修改器(
Terrains.setModifier,世界空间函数,所有读取方一致,仅重做触及的页与碰撞块),区域flatten压平(地面未知时挂起重试)。 - 后续已补:陆地离岸距离——
Waters.shoreAt与环境场shoreDistance(陆上为到水边距离,水中为负)。 - 后续已补:规则即资源——
.esworld文件(加载时校验、引用的网格材质随场景打包、修改后世界自动重建)与编辑器里的世界规则编辑器(群落/配方/布置层表单,实时显示引擎是否接受)。 - 后续已补:可达性查询——
Terrains.findPath(按需读取地面的坡度受限 A*,可传blocked排除水域/禁区,路径拉直,maxCells有界并区分 unreachable/exhausted/noGround);示例 R 键演示回家路径(约 600 单位、300 格、8ms)。导航网格目前只从静态碰撞体烘焙、不含地形,无限地形的分块运行时导航网格另立。
- 环境场(
- 验收:林地建房后草木不穿地板;采集后卸载重进不重生;同种子不同加载顺序结果相同;安全落点、早期资源、入口可达。
水域补充
T-05 程序化水域与一致查询
| 优先级 | 能力 | 当前状态 | 验收 |
|---|---|---|---|
| P0 引擎 | 海洋范围掩码/连通性:只有与开阔海在海面高度下连通的低地属于海 | 已完成:烘焙先取整片网格地面,从区域边缘泛洪,未连通的低于海面洼地为陆地(zone.ts openSea);测试 water-bodies.test.ts |
隔绝的低于海面的干盆地不显示海水、不判为水下 |
| P0 引擎 | 多水体命中规则:范围、垂向有效区间/底部、优先级、归属 | 已完成:湖/河只在水面高于地面处成立(轮廓内高出水面的陆地为陆地);湖/河优先于海;与顺序无关(测试逐格比对);WaterBody.bodyId 稳定身份,Waters.sample().bodyId、Waters.bodyAt(x,z) |
上方湖泊不被下方海洋抢先;顺序无关;陆地不被当作水域 |
| P0 游戏+引擎接口 | 海域连通、盆地/出口、水系连接、独立水位、河床、稳定 waterBodyId | 引擎接口已提供:findBasins(优先级泛洪:盆地溢出水位/最深点/出口、填洼高度、排水树与汇流量、海域)、drainPath;稳定 bodyId。由游戏据此生成湖泊与河流;河床刻蚀已补:WaterBody.bedDepth(沿河道站点的分段地形修改器,U 形河床+同坡度河岸接回地面,只在河道变化时重设) |
跨块水位/岸线连续;高湖、低湖与干盆地共存;流向有效 |
| P1 引擎+美术 | 河湖接缝、入海口、急流/瀑布,按类型配置外观 | 部分:区域场已消除河湖接缝;拍岸浪、岸边柔化已有;河口水流纹理仍有问题 | 交界无重复透明面/突变 |
后续(不阻塞首块可玩地表)
| 优先级 | 项目 |
|---|---|
| P1 | 地形分层法线/粗糙度(每层 normal/ORM);当前地形着色器仅四张颜色图与统一粗糙度。已完成:纹理数组(渲染底层)、.esterrainlayer 地形层资源与编辑器、Terrain layers/splatmap2(最多 8 层)、Terrain Layers 着色器(按遮罩高度交界、近处去重复、坡面三向投影、法线与遮蔽/粗糙度参与光照);terrain-water 示例改用 4 个程序生成的地形层 |
| P1 | 高度图显式格式字段(取代按 G 通道猜 R8/RG16),数据图无色彩转换/预乘/有损压缩。已完成:Terrain.heightmapFormat(Grey:按文件位深,16 位 PNG 全精度读取;RedGreen16),PNG 数据读取支持 16 位通道;高度图按原始字节读取(无色彩转换/预乘),被压缩时地形失败并说明原因 |
| P1 | 河床与岸线生成配合(生成器形成岸线后提供湖泊边界/河流样条) |
| P2 | 球面与极远坐标(平面 XZ 的局限、原点精度) |
| P2 | 洞穴/体积挖掘(高度场不支持) |
引擎自身待办(同日会话记录)
俯视时地形上的暗方块:已修复。原因是被相机 LOD 剔除的草仍在阴影通道里按最高精度投影;现在阴影投射跟随相机的 LOD 决定。另修地形形变在阴影通道与正交相机下用错视点。植被改为真正的 GPU 实例化(与 T-03/T-04 的放置输出一起设计)。
雨天/阴天时 CPU 渲染提交阻塞约 45 ms(GPU 计时或同步读回导致),需定位。
编辑器三维视图套用后处理(天空/雾)后画面上下翻转;改动已撤回,需修呈现路径。
河口水流纹理拉伸。
岸边锯齿:已修复。三处叠加:岸线距离在岸边用垂直水深(改为按坡度换算的水平距离);岸线距离 8 位线性编码在 ±3500 量程上每档约 27 单位(改为带符号平方根编码,岸边每档约 0.2 单位);冲浪薄膜与泡沫用按纹素截断的烘焙水深判断干湿(有深度缓冲时改用逐像素水柱,水深通道也改为平方根编码)。河流入海/入湖后原在 1.5 纹素内硬切、两条侧边伸进开阔水面,冲浪遇水流即停而被截成直线;现于对方岸线内半个河宽渐隐让位、水流随之减弱,浪沿岸连续并绕入河口。湖口剩下的横边是示例地形的水下陡坎(湖盆边缘深于河床),属地形不属水体。无限地形:地貌参数(导数衰减侵蚀下呈台地状)与远处一条直线接缝需排查。
动态分辨率在 GPU 计时下不降分辨率。
编辑器启动时的
NaNCSS 高度报错(无调用栈)。地形、植被、水体的烘焙下沉到 C++/wasm 以缩短加载(侵蚀、区域场)。