遥空庭院运行机制
每个世界一次的庭院准备、建筑高度扩展、标记抵达平面与常驻传送目的地。
遥空庭院在玩家进入前于主世界准备完成。启动服务属于内部实现,不是公开 API。玩法和管理员选项分别见世界出生点与世界出生点配置。
它做什么
现有半随机地面搜索先选区域,庭院再检查整个占地下方已生成的列,并抬升以避开障碍。所有地形和群系均可选,单轮有限搜索最多进行 4 次生成占地勘察;保留地形、普通光照、强制净空和边界检查。庭院内容缺失或无效时,本次服务器会话停用开场并恢复普通出生处理。超平坦与调试世界跳过准备。
OverworldHeight在地形注册表引导阶段扩展主世界维度类型,此时世界与区块尚未构造。它使用与放置阶段相同的加载器读取当前描述文件及有大小限制的清单头,在预设原始地形范围上方预留庭院完整高度、配置净空及用于严格上限检查的17格空间。结果向上对齐16格区段,并受Minecraft合法高度限制。配置的最低上限、预设中更大的高度、最低Y及其余维度属性均保留。原始地形上限为Y1024时,内置庭院与默认净空会得到1488的建筑上限,不包含该Y层。地形噪声高度和海平面不变;每次加载都从原始预设重新计算,扩展不会累加。
运行时模型
WorldSpawnSetupMixin包装MinecraftServer.setupSpawn,原版只在将新世界标记为已初始化之前调用该方法。流程先选择普通地面出生点,加载保存的世界边界,再尝试准备庭院。SkyGardenStartupMixin在MinecraftServer.prepareStartRegion开始时恢复已有预留,或为旧世界尝试可跳过的准备。缺少庭院状态本身不代表新世界。服务端读取描述文件,验证所有原生分片,保存原点及资源摘要,再依次写入地形、建筑、抵达标记和章节开发层。显式空气清除前层方块,未列出的格子保留前层内容。分片按需解码;世界写入保留普通光照语义。全部层完成后,最后一遍处理邻接形状并安排流体刻。
放置结束后消耗标记,区块刷盘后才保存就绪状态。重开时验证已记录抵达点,使用原庭院而不重新粘贴;中断的准备重试原预留。原型摘要变化或高度不足会拒绝该庭院,清除运行时可用状态并恢复保存的普通出生点及标记,不迁移旧格式。世界不记录永久跳过,因此下次启动可重试。新世界可降低偏好海拔,不降低强制净空。准备在加载时同步执行,完整整合包首次耗时仍须测量。
isekaiexpansion_sky_garden保存原点、摘要、边界、抵达参数与就绪状态;isekaiexpansion_world_spawn保存当前标记平面。庭院状态使用版本 2,包含保存的普通出生点和标记;世界出生状态仍为版本 1。庭院精确三维边界用于保护区域、装饰保护及气候;独立的生成规则把敌对生物自然生成禁区沿水平占地向下延伸至世界底部,不会把建筑保护或庭院气候扩展到下方地形。重连玩家保留退出位置,个人重生点仍有优先权。
转移名录采用版本1,目的地类型为none、sky_garden、anchor或companion。新名录默认选中庭院;可用状态和坐标同步给所属玩家,选择与落点仍由服务端决定。庭院不占锚点名额,也不能被遗忘。没有已准备庭院时,首次共鸣的锚点成为目的地。旧原型名录格式会被拒绝。
约定
可选 Voxy 预热
spawn.skyGarden.preloadVoxyLod 默认 true。加入预热时,已就绪庭院附近的兼容 Voxy 客户端会按保存的完整边界请求一次远景,每次连接只尝试一次。服务端遍历边界相交的区块列与垂直区段,发送非空区段调色板以及复制的方块光、天空光,不接受客户端指定坐标。客户端将快照交给 Voxy,不安装原版客户端区块。此传输不依赖 Voxy World Gen。
可选桥接通过反射绑定 Voxy 公开成员,已对照 Minecraft 1.20.1 的本地 0.2.14-alpha 源码检查。未安装 Voxy、渲染器不可用或绑定不兼容时,会结束该加载活动并继续正常加入,不增加强制模组依赖。
| 限制 | 数值 | 行为 |
|---|---|---|
| 庭院边界 | 2048 个区块列/64 个垂直区段 | 超过范围则跳过预取。 |
| 待处理区块票据 | 每次传输 4 个/全局 16 个 | 异步加载 FULL 区块,复制完成或取消后释放。 |
| 服务端复制预算 | 全局每刻 3 ms | 轮转处理传输,每次最多扫描 256 个区段。 |
| 数据包 | 32 个区段/262144 字节 | 同时只发送一页,客户端确认后再发下一页。 |
| 客户端摄取 | 每刻 16 个区段/2 ms | Voxy 排队任务超过 256 个时暂停。 |
| 超时 | 客户端 115 秒/服务端 2400 刻(120 秒) | 配置的预热时限或跳过操作可能更早终止。 |
切换世界、离开庭院、断线、跳过或关闭预热都会释放待处理工作。正常完成会等待 Voxy 摄取队列清空并保持 750 ms 安静。超时或跳过后远景可能尚不完整,Voxy 常规摄取仍继续工作。预取不会覆盖玩家设置的 Voxy 视距,也不维护另一份地形缓存。
运行 gradlew.bat -I tools/gems/verify.gradle checkLaunchContent 验证区段调色板与光照往返。在游戏中使用空 Voxy 缓存,对比未安装 Voxy、未安装 Voxy World Gen、关闭开关、远程客户端和多人同时加入;在开场前查看完整庭院,并确认跳过与断线会释放票据。
自然生成禁区
SkyGardenSpawnPolicy是内部位置判定,使用缓存边界且不分配临时对象。庭院内部继续禁止所有非受控自然生成;下方只禁止属于SpawnGroup.MONSTER的实体类型,范围延伸至世界最低Y,包括洞穴。水平边缘包含在内,范围外及庭院上方不受此规则影响。下方野生动物、环境生物和水生生物仍可正常生成。
边界在放置前及重开已保存预留时安装,服务端停止时清除。AtelierSpawnHelperMixin在创建生物前拒绝普通候选,也覆盖数据包的自然生成候选池。服务端世界与区块生成区域的最终接纳检查复用LandmarkSpawnPolicy.Source记录的初始化来源;非受控来源为NATURAL、CHUNK_GENERATION、STRUCTURE、PATROL、REINFORCEMENT和JOCKEY。命令、刷怪蛋、刷怪笼、设计好的事件及已有实体保留原行为。查询不加载区块、不查群系、不扫描实体,也不读取持久状态。
局部气候
庭院已保存的三维范围使用固定气候覆盖。api.world中的SkyGardenClimateAPI委托internal.climate实现;边界安装后,只读的contains与biome查询可用于服务端和客户端世界视图。范围外的biome返回null,继续普通查询。查询只读取世界持有的不可变快照,不加载区块,也不读取持久状态。注册群系为isekaiexpansion:remote_sky_garden,不加入地形群系源,也不改写区块中保存的群系调色板。
| 规则 | 数值 | 范围 |
|---|---|---|
| 温度 | 0.8 | Minecraft群系温度,包括带位置的查询;不随海拔降低。 |
| 降水 | 无 | 保存范围内不产生雨、降雪、自然结冰、积雪或依赖降雨判断的自然雷击落点。 |
| 草地与树叶 | 固定颜色 | 庭院群系不采用季节温度或染色变化。 |
| 已有普通冰与雪层 | 随机刻融化 | 仅minecraft:ice与minecraft:snow;浮冰、蓝冰及Conquest装饰保持原行为。需要区块处于加载并运行状态,随机刻速度不能为零。 |
首次放置前和每次已就绪世界启动时都会安装边界。玩家连接后,服务端发送是否存在庭院及六个整数边界;客户端切换维度后重新应用,断开连接时丢弃。客户端坐标不决定服务端保护。气候使用庭院状态版本 2 中的边界,不提供迁移读取器。
SkyGardenClimateClientAPI.sheltered只供客户端/渲染线程查询摄像机位置。摄像机位于范围内时,客户端雨强、雷暴强度和闪电闪光返回零,并阻止新播放的天气分类声音;服务端天气与时间照常运行。从外侧观察时,与庭院边界相交的降水列也使用无雨群系,垂直采样余量为10格。原版雨滴飞溅使用同一群系覆盖。绕过这些查询的光影包或第三方天气系统需要单独适配,并在游戏内检查。
Sodium 0.5.13使用独立的群系切片,工作线程渲染不经过原版群系查询,因此配有可选适配。适配读取同一世界快照,不为每个采样点分配方块坐标对象。现有mixin插件仅在安装Sodium时启用该适配。
有序结构包描述
资源路径为 data/isekaiexpansion/spawn/remote_sky_garden.json。资源优先级选择完整描述,不跨包合并层。内置层依次为 remote_sky_garden / terrain-v4-fit1、remote_sky_garden_architecture / architecture-v11、remote_sky_garden_arrival / spawn-v1、remote_sky_garden_story / chapter-v1,命名空间均为 isekaiexpansion。共 281 个原生分片、6017392 个列出格子,包含清除空气、标记及章节开发方块;个人推进由开场章节负责。
| 字段 | 类型 | 默认值 | 契约 |
|---|---|---|---|
schema | integer | 必填 | 必须为1。 |
layers | array of objects | 必填 | 1–8个有序原生结构包引用。 |
layers[].id | identifier string | 必填 | 已存在的内置清单ID。 |
layers[].revision | string | 必填 | 已存在的不可变结构包版本。 |
spawnMarker | integer array | 必填 | 公共局部坐标系中的3个整数,必须位于合并边界内。 |
描述或层中的未知键、小数坐标、缺失资源、错误哈希、未知状态及无效分片都会使准备失败。指定坐标必须有且仅有一个世界出生点标记。原生结构包格式和限制见Atelier结构。
世界出生点标记
isekaiexpansion:world_spawn_point是管理员创作方块,脚底平面位于其上方一格。内置标记替换已标注的局部金块(0, -1, 183);叠加世界原点之前,脚底Y为0。
| 字段 | 类型 | 默认值 | 契约 |
|---|---|---|---|
Radius | NBT int | 10 | 水平圆形半径,0–64格。 |
Yaw | NBT float | 180 | 有限角度值;配置命令接受-180–180。旋转和镜像会同步变换。 |
FinalState | NBT compound | 金块 | 消耗标记后恢复的原生方块状态。必须无流体、非空气且不带方块实体。 |
FinalState.Name | NBT string | 提供FinalState时必填 | 已注册的方块ID。 |
FinalState.Properties | NBT compound of strings | 省略 | 精确有效的状态属性,遵循原生状态验证。 |
省略标记字段时使用默认值;字段存在但类型错误则失败。应用时还要求中心地板完整安全、身体空间畅通;不安全时恢复标记,世界出生点不变。抵达只在保存的平面上抽取安全格,优先选择无人占据的位置;没有安全位置则失败。该流程不查高度图,不读取地面抵达设置或spawnRadius游戏规则。
开发方块没有自动刻逻辑。庭院准备和手动Atelier后处理会消耗它;普通模板放置需要显式应用。放置日志改为版本3,记录出生点前后快照。撤销时仅当当前出生点仍与该任务结果一致,才恢复旧出生点,因此不会覆盖管理员后续调整。结构包、草稿和自然地标仍为版本2,不保留旧日志读取器。
扩展方式
创造模式管理员用/ise dev world_spawn block获取标记,用/ise dev world_spawn configure <pos> <radius> <yaw>设置平面,再用/ise dev world_spawn apply <pos>消耗标记。命令要求权限等级2。如果恢复地板不应是金块,通过带类型的方块实体NBT指定FinalState。标记应嵌在可通行地板内,而非屋顶。
Studio用不同实体图标区分开发方块。庭院查看器的标记和半径叠层读取伴生导出工具生成的部署元数据,属于创作辅助显示,不是额外打包的建筑。安装注册了新方块的版本后,需要刷新实时方块目录。
验证
运行gradlew.bat compileJava、SpawnAnchorTest、TravelHubTest与SkyGardenClimateTest,以及gradlew.bat -I tools/atelier/verify.gradle checkSkyGarden。运行SkyGardenSiteTest、SkyGardenSpawnPolicyTest与OverworldHeightTest验证不受地形类型限制的选址、旧世界回退、自动高度、生成来源及边界;传入atelierMinecraftIntermediary运行checkSkyGardenStartup,检查当前清单边界、Minecraft维度编解码及重映射后的启动与生成接纳注入。原生检查验证全部分片哈希、边界、数量、带类型标记的旋转,以及317个有地板且身体空间畅通的露台格子;它不实例化Conquest运行时碰撞形状。
使用全新原型世界验收:确认庭院在进入前完成,首次抵达面向圣所,多人抵达能安全分散,个人重生点与重连位置保留,名录显示庭院,重开世界不会生成第二座岛。测量启动耗时,并检查普通光照与所选光影包。Conquest实际放置、流体行为及光影外观仍需要这一步游戏内验收。
气候验收时,在周围寒冷地形中强制雨天与雷暴。分别检查庭院内、每个边界外侧及下方海域的水、雪层、草叶染色、雨幕、飞溅、声音与闪光。切换维度、重连和重启后重复,并让两名客户端玩家分处边界两侧。checkSkyGardenClimateMixins使用atelierMinecraftIntermediary提供的Minecraft intermediary JAR及atelierSodiumRuntime提供的Sodium运行JAR检查重映射后的注入目标。checkSkyGardenClimateData用Minecraft的编解码器读取内置群系。这些检查不能代替视觉验收。