Kzeroko KTM2
EN
English

结构空间数据

用锚点 NBT 定义房产区域，并用家具规则计算家园温馨度。

更新于 2026/9/19 9 分钟阅读

结构空间锚点定义房产区域、住户名额与契约价格。家具 JSON 是独立的服务器数据格式，用来决定永久家园中哪些方块可以贡献温馨度。

文件放在哪里

家具规则从 data/<namespace>/home_furniture/*.json 加载，命名空间与相对文件路径组成规则 ID。通过数据包资源选择覆盖同一资源 ID 即可替换规则；不同 ID 仍是独立规则。加载器按选中的 ID 排序，只处理前 256 个资源，无效资源也占用这个数量。

锚点数据存放在 isekaiexpansion:structure_space_block 的方块实体中，也可随该方块保存到结构模板。它使用 NBT，并非另一类家具 JSON。生成模板通过 isekaiexpansion:structure_space_processor 将锚点转换为运行时房产。

最小示例

下面是内置 isekaiexpansion:bookshelves 规则的完整内容：

{
  "block": "minecraft:bookshelf",
  "category": "study",
  "points": 4,
  "limit": 5
}

即使其他规则也使用 study，这个类别仍最多贡献 20 点。

字段

字段类型默认值作用
block字符串必填方块 ID 或 #block_tag，必须符合标识符语法。未注册方块或空标签不会匹配任何方块。
properties对象{}方块状态属性名到字符串值的精确映射，所有条目均须匹配；不存在的属性或值不会匹配。
properties.<name>字符串无单项属性的字符串值；示例中的 part: head 与 lit: true 均为字符串。
category字符串必填符合 [a-z0-9_.-]{1,64}；同类别共用 20 分上限，最多接受 16 个不同类别。
points整数必填每个计分方块贡献 1–100 点。
limit整数必填每条规则在每处家园最多计入 1–64 个方块。

每个方块只使用首先匹配的规则。该规则达到重复数量上限后，不会继续尝试后面的规则。同一房产的区域重叠时，每个位置只计分一次；空气不参与计分。完成评估后，每类上限为 20，家园总上限为 100，炉边眷顾等级按总分整除 20 计算，最高 5 级。

锚点 NBT

下面仅列出锚点自定义数据；结构或方块实体容器还会提供常规标识与位置元数据。

{
  RoomId: "room_1",
  GroupId: "isekaiexpansion:guild_lodging",
  Regions: [
    {Box: [I; 0, 0, 0, 5, 3, 5]},
    {Box: [I; 6, 0, 2, 9, 3, 5]}
  ],
  Capacity: 1,
  AllowRent: 1b,
  AllowBuy: 1b,
  RentPrice: 100L,
  BuyPrice: 10000L,
  ShowBox: 1b
}
字段类型默认值作用
RoomId字符串room_1绑定时须符合 [a-z0-9_./-]{1,64} 的房间标识；原始锚点 NBT 不验证。
GroupId字符串defaultMinecraft 标识符，因此默认解析为 minecraft:default；编辑器与网络长度最多 64。
Regions复合标签列表必填1–16 个含端点的相对区域，受下述几何限制约束。
Regions[].Box整数数组必填恰好 6 个整数，依次为最小 XYZ、最大 XYZ；各轴最小值不得大于最大值。
Capacity整数1住户名额。原始 NBT 缺省或非正值按 1 读取；编辑器与运行时绑定要求 1–64。
AllowRent布尔字节true是否接受租赁申请。
AllowBuy布尔字节false是否接受购买申请。
RentPrice长整数0每开始一个游戏日的铜币价格；编辑器保存与注册要求非负，原始 NBT 读取不截断负值。
BuyPrice长整数0每个永久住户名额的铜币价格，验证规则与租金相同。
ShowBox布尔字节true仅控制制作预览；生成注册忽略此项，运行时房产状态不保存此项。

默认值列描述读入新锚点的情况。向已有对象读取数据时，缺失的房间或分组字段会保留对象当前值。虽然新放置的锚点初始包含相对原点处的单个方块，读取 NBT 时仍必须提供 Regions。

几何约束限制
每处家园的区域数1–16
各轴含端点的外包跨度最多 128 格
区域体积之和最多 262144 个方块；重叠部分仍占制作预算
编辑器与保存数据包的相对坐标各轴 −128 至 +128
运行时注册坐标使用绝对坐标；编辑器相对坐标限制不代表一般几何对象的原点限制

房间显示名称使用 structure.<structure_namespace>.<structure_path_with_slashes_as_dots>.<room_id>，其中结构路径的斜杠转为点，房间 ID 原样追加。缺少翻译时，目录直接显示房间 ID。

完整示例

对于由多个部分组成的方块，可只统计其中一个固定部分：

{
  "block": "#minecraft:beds",
  "properties": {
    "part": "head"
  },
  "category": "rest",
  "points": 10,
  "limit": 2
}

这里的 part 属于 properties.<name> 描述的动态属性名。点燃营火的字符串筛选条件则为 "lit": "true"。重载时不会针对所有选中方块验证属性；没有该属性的方块只会匹配失败。

制作与绑定

  1. 使用具有权限等级 2 的创造模式管理员账号，用 isekaiexpansion:structure_dev_wand 点击方块设置第一个角点，潜行点击设置第二个。
  2. 将魔杖应用到锚点会替换区域；潜行应用则追加区域。此操作只修改制作方块，不更新运行时房产。
  3. 不持魔杖打开锚点，在区域页编辑含端点的相对最小与最大坐标。添加区域会复制当前区域；移除后至少保留一个区域。
  4. 点击预览草稿检查未保存的几何。锚点已保存的 ShowBox 必须启用，渲染器才会显示草稿。关闭编辑器会清除该草稿预览。
  5. 设置标识、名额与价格。启用“在当前世界绑定或更新”后保存，才会同时注册房产。这个开关初始关闭。服务器只接受距离锚点 64 格内的编辑；应查看聊天结果，不能将本地“已发送”提示视为保存成功。

绑定使用所在结构的 ID；没有结构时使用 isekaiexpansion:authored_home。已绑定锚点的房间与分组 ID 不可更改。更新同一标识会保留住户和授权，替换几何并重建索引。名额不能降至现有住户数以下。不同家园不得重叠，同一家园内部的区域可以重叠。

锚点仍关联任何永久住户或有效租客时，解除空置房产绑定会被拒绝。解除绑定会保留制作方块；原本就未绑定的锚点也会返回成功。移除制作方块本身不会删除运行时绑定。

生成注册会围绕锚点对各相对区域应用镜像与旋转，再偏移至世界坐标，将注册任务提交给服务器，并从生成模板输出中移除锚点。此路径仅创建缺失标识；重复生成不会覆盖完全相同标识的现有房产。

校验

家具必填字段缺失、为 null 或无法转换为预期值时，该规则会被拒绝。未知字段被忽略。解析器采用标量转换，并非严格 JSON Schema；制作时仍应按示例使用字符串和整数。空对象、非对象资源、无效标识符，以及越界的分数或数量上限都会记录错误并跳过，不会中止整个目录。

已有 16 个成功加载的不同类别后，引入新类别的规则会被跳过。排序后超出前 256 个 ID 的资源不会解析，实际匹配也使用同样的 ID 顺序。不存在的方块 ID、空标签、不存在的状态属性或不匹配的属性值可以加载，但不计分。规则的命名空间决定规则自身标识，不限制其选择的方块命名空间。

锚点几何解析会拒绝缺失或空的 Regions、长度错误的 Box、反向角点，以及超出预算的几何。不存在旧式 Min/Max 或单一 Bounds 读取路径。锚点读取不会完整验证标识、负价格或名额上限，但编辑器保存和运行时注册会验证。请直接在源数据中填写合法值。

生成处理器会在提交的注册任务内捕获参数错误并记录日志；更早的解析错误不在这个捕获范围内。若缺少可用服务器世界、正在生成的结构 ID 或 NBT，处理器会移除锚点而不注册家园，不能用这条路径代替独立家园绑定。

重载

家具规则随服务器数据重载。成功解析的条目替换旧列表，匹配缓存被清除，版本号更新。数据包完成回调还会使标签匹配失效，这次失效不以重载成功为条件。客户端收到派生的评估快照，不接收全部家具规则。

评估不会加载区块。几何或规则变化、相关方块变化，以及结果过旧都会使评估重新开始。所有区域必须已加载；因缺少区块而跳过的家园，需要后续请求才能重新入队。业主身处永久家园时会周期性请求，打开家园列表也会请求评估。

锚点编辑在保存后生效，运行时绑定还须启用绑定开关。重载家具不会重建房产或替换契约。运行时数据位于各维度持久化目录中的 data/isekaiexpansion/structure/spaces_v2.dat，不导入 v1。修改保存数据前请阅读开发者参考。

相关页面