地形生成

地形子系统为 ReTerraForged 增加确定性区域、预整形地标与体积几何。它负责默认预设的注册表启动流程，以及每个生成器的环境；这些属于内部实现约定。唯一的公开接口是 TerrainAPI：只读查询某个位置属于哪个地标或地形区域。

它做什么

构建使用 ReTerraForged 0.0.6-fabric-1.20.1，模组依赖要求 0.0.6。KtmPreset 通过依赖的编解码器一次性读取随包的 data/isekaiexpansion/terrain/ktm2.json，随后返回副本。该预设的世界属性指定海平面 60、世界高度 1024。预设缺失或无效会中止加载，不会改选后备预设。

TerrainWorldPreset 注册 WorldPresets.DEFAULT：主世界使用包装的群系源，下界和末地生成器使用各自对应的注册表设置。TerrainServerPresetMixin 在专用服务端创建维度时明确选择该默认值。RTF 预设工厂混入将所列工厂方法重定向到 KTM2；默认自定义界面为只读。

玩家可见的系列与命令见地形。本地配置的全部字段与校验范围见地形配置。

运行时模型

注册表与环境归属

TerrainBootstrap.load 使用 Gson 复制服务端本地选项，完成校验后安装线程局部的加载快照，并在 finally 中恢复原快照。它启动 RTF 的预设、噪声、修改器与结构规则注册表，以及原版的地物、雕刻器、群系、维度类型、密度函数、生成器设置和世界预设。

对于已绑定注册表，remainingResources 移除 ID 已被启动流程注册的资源条目，保留无关资源。因此，数据包不能通过提供同名 ID 覆盖这些自有条目。验证阶段检查必需的系列群系、已绑定的预设环境，以及默认主世界群系源。集成缺失会导致失败，不会静默生成原版地形。

TerrainEnvironment 拥有已校验的参数记录、各系列形状、已解析方块配色、群系准入规则，以及按种子弱引用保存的地标集合。RtfPresetSettingsMixin 只允许绑定一次环境。RTF 高度图具有环境时，RtfHeightmapMixin 创建引擎，确保气候已采样，再于气候处理后应用地形。

服务端世界构造器只绑定使用 TerrainBiomeSource 的主世界。它要求存在 RTF 上下文与引擎，先绑定群系源，再在正常生成前接入世界树状态。Cyanide 替换的注册表加载器另有填充与过滤桥接。

准入、密度与装饰

区域网格按确定性的加权排列尝试已启用系列。某系列失败后，可尝试另一个系列，但不会重新抽取区域准入概率。候选点采用分层采样，检查原始群系、地形高度与预留区域。公布区域前先验证完整形状，最高点必须低于 maxY - 32。

风息原野与世界树优先。预整形地标表面混合到原始高度轮廓；普通贴地形状更新 RTF 高度与地形身份，并保护完全生效的内部区域免受侵蚀。空境群岛、穹庭与裂隙巨岩共享 TerrainFamily.elevated() 分类，跳过地面高度修改，上层体积通过最终密度加入，保留原生含水层输入。穹庭地基贴合原始地面，只在规划的承接池与瀑布落点处调整。裂隙巨岩通过最终密度保留谷地与基座形状。LandformColumn.blendDetached 让相连岩体随地面混合，分离岩体则在自身高度变薄，保留中间空隙。

TerrainNoiseConfigMixin 即使在温度函数内部嵌套的位置，也能发现 RTF 单元标记，然后用 LandformDensity 包装最终密度。包装器通过访问器映射原密度与高度，只存在于运行时，调用 getCodecHolder 会抛出异常。LandformColumn 合并实体区间，保留两种贴地表面以下的原始洞穴，并加入浮空体积，而不将其拖向原生地面。

区间缓冲区最多支持 16 个不相交区间，溢出时抛出异常。引擎使用 16 个分条区域锁、共享的 128 项 LRU，以及线程局部区域和柱缓存；风息原野与林地树木规划的共享缓存各限 64 项。区域构造使用原生 64 位坐标映射，相同半径、候选轮次与生境类型可复用准入范围；调查缓存只在规划期间保留。采样原地形时使用线程局部递归保护，并在 finally 恢复；柱查询不请求相邻区块。

在 generateFeatures 的 HEAD，奇境装饰处理自有地表风化、有界水体、晶体、化石、建筑与植被。在 TAIL，执行普通风化、林地树木与世界树栅格化。写入限制在当前区块内，相邻几何通过描述数据采样。世界树跳过方块实体和流体，树叶只替换空气、可替换方块或已有树叶。这是世界生成，不是运行时树木生长。

Arona 兼容桥接仅在其层注入调用期间，为空境群岛、穹庭与裂隙巨岩提供悬浮顶面高度。线程局部作用域在 finally 中恢复，不会全局替换地面或水文高度。穹庭在规划高度附近寻找实际栅格表面，为干燥、外露的台地铺设配置的表层方块与下方三层土壤。

全部奇境系列共享 ExoticOptions.Family、不可变 Parameters 快照与 ExoticField 采样契约。具名构造器让部分 Gson 对象保留对应默认值，专用形状参数扩展共同系列结构，不保留旧配置别名。FormationField 把不可变解析片段索引到 48 格桶中，将旋转、倾斜的石拱、岩鳍、巨岩和交织根系裁剪为柱区间。冠状台地边界使用缓存朝向与笛卡尔谐波，避免逐柱计算旋转三角函数。

地下柱同时记录地板与顶板。密度替换限定于洞室及其混合外壳，保留原始 RTF 地表高度。整个洞室的覆岩都按当地地面约束。水池准入同时检查洞顶与原始 RTF 覆岩下的完整池岸，不合适的候选通过有界重试重新选址。ExoticVolumeDecoration 在雕刻器执行后修复有界顶板密封层和紧邻液体的池底、池岸，排除自有空腔内的含水层液体，再绘制规划的液体区间。桥梁或根系横跨水池上方时，下方水体仍会保留。

洞室描述由相互重叠、随机旋转的穹顶、独立起伏的地板与顶板、侧壁支撑、悬挂岩体和高架通路组成。ExoticHydrology 缓存水池朝向、弯曲轴线、不对称岸湾、侵蚀细节与深度变化；空境群岛湖泊、水都蓄水池和冻原冰湖也使用同一池形算法。洞窟与火山的不同液面保持独立，溢流路径不得切穿其他高度的水池。液体采样复用 LandformColumn，保留彼此分离的上下层水体。穹庭在规划时求解台地真实边缘，生成完整落水柱与下方承接池，不等待流体刻更新。火山以不对称收尖山体、小型缺口火山口和侵蚀山坡为中心，外围保持广阔荒原；主峰整体适配受保护场地，可选岩鳍与逐级下降的熔岩池也须完整准入。巨石谷使用多种倾斜板状石拱，裂隙巨岩保留占主导的悬浮上部岩体。

群系选择与保存编解码器

TerrainBiomeSource 注册名为 isekaiexpansion:terrain。它先查询委托源，再于原版洞穴保留检查之前判断奇境归属。自有奇境体积替换 Minecraft 群系，包括 lush_caves、dripstone_caves 与 deep_dark；该分支保留非原版群系。洞窟归属在完整准入范围内包含地板与顶板外各 24 格缓冲，且洞室净高须超过 24 格。空境群岛仍使用自身高度带。奇境归属之外，普通贴地替换继续保留显式原版洞穴群系。预整形林地归属先于后续通用的非原版排除检查，而风息原野明确保留非原版群系。

其他路径中，缺少引擎或没有符合条件的归属时，返回委托源群系。不能笼统承诺所有分支都会保留所有第三方群系，检查顺序本身就是约定。

保存的群系源字段

世界树预留生命周期

WorldTreeState 直接使用主世界持久状态键 isekaiexpansion_world_tree，生成 data/isekaiexpansion_world_tree.dat，位于共享版本化辅助目录之外。状态保存单个预留记录，不保存已生成区块位图或整套材料配色。

尚无预留记录时，LandmarkFrontier 检查现有 r.<x>.<z>.mca 文件名。若存在文件，则在其边界之外选择原点，计入搜索半径、群系半径与 2048 格边距。它不会检查区域文件内每个区块是否实际被占用。区域坐标无效或找不到受支持的边界外位置时，会产生 I/O 失败并中止安全预留。

规划器在有界、种子稳定的候选点与局部细化中搜索，对地理条件评分；偏好生境不可用时，不会直接放弃唯一世界树。选定预整形区域后，先记录并显式保存持久状态管理器，再允许出生区域生成。重载恢复保存的坐标、几何与地基策略，材料则来自当前环境。

读取器将校验失败记入 invalid 状态，不在解码器内部抛出；绑定阶段再抛出异常，防止持久状态管理器静默替换损坏记录。恢复还会拒绝不再适合维度高度的树，或绑定前已采样出的冲突地点。

世界树载荷

客户端气氛

ExoticAtmosphere 是读取活动配置的客户端缓存。它在相机 Y 高度，以 24 格间隔采样 3 × 3 网格，根据配色群系前缀进行加权插值。世界变化时重置混合与时间线状态，非主世界视角将权重归零。它不会修改服务端时间或天气。

StormTimeline 按配置秒数安排局部闪光，雷声在闪光后 28 刻（1.4 秒）响起。世界时间倒退或晶棱混合不再活动时，重置计划。客户端暂停时跳过时间线更新。只要 Iris 启用了光影包，后备天空就会被抑制，包括不支持的光影包；没有光影包时，浓雾或浸没视角仍会跳过绘制。

约定

项目的可选 Iris 集成编译目标为 1.7.6+1.20.1。这只固定集成目标，不代表任意现行光影包版本都符合配方。

公开查询

api.terrain.TerrainAPI 让其他代码知道 KTM2 地形在哪里，而不必接触地形引擎。两个方法都读取生成器自己的规划，不请求也不生成区块。请在服务端线程调用。

TerrainRegion 是一个 record。family 是系列的群系 ID，例如 isekaiexpansion:great_plains；center 是区域中心，位于地面高度；radius 是其所属地形的水平范围，单位为方块；layer 为 SURFACE、ELEVATED 或 UNDERGROUND。

归属与生成保持一致。世界树或风息原野地标在混合权重超过 0.5 的位置拥有归属，返回自身的系列、半径和 SURFACE；其中的林地也报告为该地标。地形区域在占地权重超过 0.5 且规划拥有该处群系的位置拥有归属，半径报告为规划半径的 80%。奇境系列还要求该高度正好是其奇境群系，所以洞窟顶上、浮岛下方的地面都不算在区域内。IsekaiTweaks 的地图集就是这样记录已发现的区域。

扩展方式

新增系列时，同步修改枚举与形状、设置快照、准入权重、几何、群系和配色注册、地表、装饰及本地化。TerrainBiomeSource 序列化有序系列列表，因此插入或重排枚举成员会改变校验约定。新几何需要数值与区块顺序检查，不能只凭截图判断。

光影覆盖与配方

ExoticShaderSourceMixin 在 Iris 发现 include 与选项之前覆盖源码读取。ExoticShaderBridge 检查本地开关与 JVM 属性 isekaiexpansion.exoticShaders；值为不区分大小写的 false 时关闭准备。它不改变光影包选择，也不写入光影包文件。

补丁器检测 lib/ROBOBO_sky.glsl 与 lib/scene_controller.glsl，再根据场景控制器标记区分 Eclipse 与 Bliss。重命名压缩包不影响结构检测。每个输入限制为 4 MiB，并统一 CRLF。诊断包含按文件名与源码文本计算的 SHA-256 前 16 位十六进制指纹。

所有修改在临时源码映射中完成。状态为 PATCHED、ALREADY_PATCHED、UNSUPPORTED 或 UNRELATED。系列标记不明确、锚点缺失或重复、文件不可读，以及已捕获的部分解析错误，都会返回空覆盖。发现已有标记时，只有 settings 包含辅助文件且辅助文件存在才保留原补丁；这是结构检查，不是对旧补丁的完整语义审计。

随包文件为 assets/isekaiexpansion/shaderpatch/exotic-patches.json 与 exotic_environment.glsl。它们是内部构建资源，不是公开数据包加载器。未知操作类型会被拒绝；没有通用未知键检查，损坏的内部配方应在开发阶段发现，不能假设所有异常都会自动恢复。

光影配方字段

光影 uniform

Uniform 每帧更新。辅助代码规范化群系总权重，加入局部天空与反射效果，并提供云雾贡献。配方中的精确 GLSL 锚点属于兼容约定，已知光影包名称本身不足以证明兼容。

验证

运行 tools/terrain/check-exotic-volumes.ps1 -Export 检查几何、洞窟原生覆岩与配置极值，再用 tools/terrain/render-exotic-volumes.py 绘制采样顶板剖视图。checkExoticTerrain 验证 RTF 选址、深暗之域排除、穹庭草土表层、池底与桥下水体。checkTerrainLocate 测量多个种子的冷缓存搜索，并用独立生成引擎确认系列一致；checkTerrainCoverage 检查发现距离。先用 checkSkyHydrology 检查空境群岛，再分别加 -PhydrologyFamily=GARDEN_OF_THE_FIRMAMENT 与 -PhydrologyFamily=RIFTBORNE_MONOLITH 检查穹庭和裂隙巨岩的原生高度与含水层。裂隙巨岩检查还要求基座与悬浮岩体之间保持空气；check-math.ps1 验证分离体积在原生地面抬升时的混合行为。checkExoticShaders 通过 shaderRoots 接受实际 Eclipse/Bliss 路径，checkExoticGpu 渲染地表天空与洞窟薄雾。这些离线检查不能代替游戏内 Iris/Arona 视觉验收。

• 创建默认单人和专用服务端世界，不打开自定义界面，检查自有注册条目、RTF 环境与主世界群系源。
• 测试非法配置、配色名、材料类型与组合几何限制，包括已关闭但设置仍无效的系列。
• 对同一种子比较正负坐标网格与不同生成顺序；检查完整石环、剑脊间距、谷地开挖，以及不改写地面水文的浮岛体积。
• 以相反顺序生成相邻区块，检查水幕、藤蔓、桥梁、树根与树冠接缝，确认不请求相邻区块。
• 修改配置后恢复世界树；测试缺失或无效 NBT、不兼容建造高度、过早采样，以及在现有区域文件之外新增预留。
• 按已记录的分支顺序测试洞穴群系、非原版群系、预整形林地与浮岛高度过渡。
• 比较描述搜索与实际群系，检查取消、世界边界、关闭系列及无匹配结果。
• 重载受支持的目录和 ZIP 光影包及其重命名副本；测试已有或残缺标记、重复锚点、超大输入、关闭覆盖，以及启用但不受支持的光影包。
• 检查天空与反射一致性、群系边缘混合、暂停或时间倒退、雷声延迟及断线或世界切换。这些是验收步骤，不表示本次已运行游戏或视觉检查。

相关页面

• 地形与地标——玩家可见系列与命令。
• 地形配置——全部设置与配色字段。
• 持久状态——共享存储约定与世界树例外。
• 寻路 API——异步定位请求。