Skip to content

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.

15.4 KB
Raw Blame

程序化世界:引擎侧工作计划

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 计时下不降分辨率。

  • 编辑器启动时的 NaN CSS 高度报错(无调用栈)。

  • 地形、植被、水体的烘焙下沉到 C++/wasm 以缩短加载(侵蚀、区域场)。