结构模板

结构模板就是原版的 .nbt 结构文件, 存放在 plugins/EmakiStructure/structures/<名称>.nbt. 同一份模板你可以用在三处: 放置 (place), 就地预览 (get), 以及替换原版结构 (replace_rules)

选区与高亮

• 两点框选: 用 /ems select pos1 与 /ems select pos2 记下两个角点, 两点必须在同一个世界
• 框好后屏幕上会显示坐标与尺寸 (X × Y × Z), 并用发光方块 (隐形方块实体) 在游戏里画出线框, 共 12 条棱加顶角标记; 线框只在视距内可见, 你离开这个世界或超时后它会自动消失
• select adjust 用来按方向微调大小; select clear 取消选区与线框
• 框选放着不管太久会自动结束, 时限由 selection.session_timeout 控制 (默认 30m)
• 选区尺寸受 generate.size_limit 限制, 超出会被拒绝 (error.selection.too_large)

导出校验

用 /ems structure export <名称> 导出时, 插件在写文件之前会逐项检查, 任何一项不通过都会拒绝导出并说明原因:

检查项	不通过时的报错键
名称只能用小写字母, 数字, 下划线, 连字符, 且必须以字母或数字开头, 长度不超过 64	error.name.invalid
选区不超过 generate.size_limit 与导出上限	error.export.too_large
选区里至少有 1 个可以导出的方块	error.export.no_blocks
单个文件大小不超过 template.import_max_file_bytes (默认 32 MiB)	error.template.file_too_large
颜色表条目数不超过 template.palette_limit (默认 4096). 颜色表就是模板里出现过的所有不同方块状态的清单	error.template.palette_exceeded
单个方块自带的数据 (例如箱子里的物品) 不超过 template.block_entity_max_bytes (默认 64 KiB)	error.template.block_entity_too_large
从旧版本模板读不出来的方块状态, 按 template.legacy_policy 处理 (reject 拒绝整个文件 / skip 跳过该方块并填成空气)	error.template.legacy_block_rejected, console.template_legacy_skipped

导出成功后, 屏幕上会显示方块数量, 尺寸, 家具条目数 (以及有多少家具因为超出选区被跳过) 和文件路径. 导出是一次性写好的, 不会先写临时文件再改名

放置

执行 /ems structure place <模板> <朝向> 后, 插件按下面的顺序逐步处理:

1. 检查模板与尺寸: 模板不存在就报 error.template.not_found; 尺寸超过 generate.size_limit 就报 error.generate.rejected_by_limit
2. 开回滚日志: 在 journal/ 里建一份改动记录, 建不起来就拒绝这次生成 (error.generate.journal_failed)
3. 检查支撑面: 按 generate.ground_mode 判断脚下能不能放 (见配置详解), 不满足就报 error.generate.ground_unsupported 并放弃
4. 分批写入: 按 generate.max_blocks_per_tick 分到多个游戏刻里慢慢写 (每刻约 1/20 秒), 受排队超时 (generate.queue_timeout) 与服务器卡顿时的自动降速约束; 超时则中止 (error.generate.queue_timeout) 并还原
5. 实体与生物: 模板里的实体按 generate.entity_policy 处理, 然后执行 spawns/ 里配好的生物点位
6. 收尾: 成功后显示位置, 朝向与被覆盖的方块数; 如果有玩家被埋住会给出离开提示 (error.generate.player_trapped)

生成过程中被 reload 或停服打断时, 插件靠回滚日志恢复: 启动时如果发现有没走完的记录, 会先把它还原并暂停生成功能, 还原完再放开 (console.rollback_recovering / console.rollback_recovered). 还原不成功的记录会被改名加上 rollback-partial 标记, 并且不会再自动重试, 你可以用 /ems debug 查看

/ems get <模板> [朝向] 只是在你面前 3 格处临时摆一遍, 用来试看位置和朝向对不对

生物点位附属配置

生物点位附属配置把一组"在哪生成什么生物"的设定绑定到某一个具体的结构模板上. 文件放在 plugins/EmakiStructure/spawns/<模板名>.yml, 其中 <模板名> 必须和 structures/<模板名>.nbt 完全一致, 放置这份模板时插件会按文件名自动读取

• 一对一绑定, 没有通用文件: 放 castle.nbt 只会读 spawns/castle.yml; 没有同名文件就一只生物也不生成, 也不会去套用别的结构的点位, 不存在"全局共用"的点位文件
• 坐标系: pos / region 用的是模板自己的坐标, 原点是你导出时选区的最小角, 各轴取值范围是 [0, sizeX) / [0, sizeY) / [0, sizeZ); 换算方式是 模板坐标 = 世界坐标 − 选区最小角 (导出成功会显示尺寸, 框选时会显示两个角点的坐标)
• 朝向跟随结构: 点位会跟着结构一起旋转 (和方块, 家具摆放用的是同一套朝向换算), 结构朝东南西北或镜像放置后, 生物仍然落在对应位置; facing 字段写的朝向会叠加在结构朝向之上
• 生成时机: 在方块和家具都摆好之后的收尾阶段执行, 每次放置这个结构都会触发 (没有冷却); 生成的生物会记进回滚日志, 生成中断还原时一并移除
• 改动何时生效: 点位文件读取后会缓存, 新建或修改后执行 /ems reload; 如果用 /ems structure export 重新导出同名结构, 点位与家具缓存会自动刷新

配置示例

spawns/castle.yml (对应 structures/castle.nbt):

version: 1                     # 固定写 1, 当前不做校验
enabled: true                  # false 时整份文件不生效
spawns:
  - type: "minecraft:skeleton" # 必须带来源前缀
    pos: [4, 1, 4]             # 固定点位 (模板坐标)
    count: 2                   # 1-16
    chance: 1.0                # 0.0-1.0, 整条只随机一次
    facing: "north"            # north/south/east/west, 可省略
    level: 5                   # 可省略, 只有 mythicmobs: 类型会用到
  - type: "minecraft:zombie"
    pos: [6, 1, 6]             # 只有 pos 条目才能用 radius
    radius: 3                  # 0-64, 在以 pos 为球心的球体内随机取点, 球体必须完全落在模板内
    count: 3
  - type: "emakimobs:elite_zombie"
    region:                    # 在区域内随机取点, min ≤ max 且必须在模板尺寸内
      min: [0, 1, 0]
      max: [15, 1, 15]
    count: 4                   # region 条目里写 radius 会被忽略

参数说明

字段	类型	必填	取值范围	说明
version	int	否	写 1	保留字段, 当前不做校验
enabled	boolean	否	true / false	文件级开关, 默认 true; 填 false 时整份文件都不生效
spawns[].type	string	是	以 minecraft: / mythicmobs: / emakimobs: 开头	生物类型. 后两种需要装了对应插件, 没装时这条生成失败并提示
spawns[].pos	list<int>	与 region 二选一	各轴都要落在模板尺寸内	固定点位, 用模板坐标; 与 region 只能填一个
spawns[].region	map	与 pos 二选一	min / max 各 3 个整数, min ≤ max 且在尺寸内	在区域内随机取点; 与 pos 只能填一个
spawns[].radius	int	否	0–64	只有 pos 条目有效: 在以 pos 为球心的球体内随机取点, 球体必须完全落在模板内; region 条目里写这个字段会被忽略
spawns[].count	int	是	1–16	这条要生成几只生物
spawns[].chance	double	否	0.0–1.0, 默认 1.0	按整条随机一次: 没中则这一条的 count 只全部都不生成, 不会只生成一部分
spawns[].facing	string	否	north / south / east / west	生物的朝向, 会叠加在结构朝向之上; 不填就沿用结构朝向
spawns[].level	int	否	整数	生物等级, 只有 mythicmobs: 类型会用到

生成限制与联动

项	说明
spawn.enabled: false	主配置里的总开关. 关掉后 spawns/ 全部不读, 也不提示 (模板里自带的实体不受影响)
spawn.max_per_generation (默认 32)	一次放置最多生成多少只点位生物, 超过会拒绝整份文件并提示 (error.spawn.rejected)
spawn.batch_per_tick (默认 8)	每 tick 最多生成多少批, 超出的排到下一个 tick
generate.entity_policy: none	会连点位一起关掉: 点位和模板实体共用这个策略, 所以即使 spawn.enabled: true 也不会生成
generate.entity_policy: passive	原版敌对生物生成后立刻移除; 第三方生物 (mythicmobs: / emakimobs:) 是否也这样处理, 由 spawn.respect_entity_policy 决定 (false 放行以保功能完整, true 判断不出来就跳过)
与回滚的联动	点位生物会记进回滚日志, 生成中断还原时一并移除

常见问题与报错

现象	原因与处理	对应报错键
放置后没有生物, 控制台也没有提示	没有同名的 spawns/<模板名>.yml, 或者 spawn.enabled: false, 或者 generate.entity_policy: none	—
改了点位文件却不生效	读取结果有缓存, 执行 /ems reload 即可 (或重新导出同名结构)	—
提示点位超出范围	pos 超出了模板尺寸; 对照导出时显示的尺寸与选区最小角	error.spawn.pos_out_of_bounds
整份文件被拒绝	合计生成数量超过 spawn.max_per_generation, 或文件名不合法	error.spawn.total_exceeded / error.name.invalid
某一条被跳过	会逐条提示原因 (缺 type, 前缀不合法, pos 与 region 同时写了或都没写, count / chance / facing / radius 超范围, 区域顺序写反或超出范围)	console.spawn_entry_issue 及 error.spawn.*
某一条生成失败	依赖的插件没装, 或这次生成被世界规则拒绝	console.spawn_entry_failed

WARNING

重新导出同名结构会改变模板大小, 旧的点位文件不会跟着平移; 模板尺寸变了之后, 请自己把 spawns/<模板名>.yml 里的坐标一起改过来

家具附属配置

furniture/<模板名>.yml 是在导出结构时自动生成的: 插件会识别 ItemsAdder / Oraxen / Nexo / CraftEngine 这四种家具插件放下的家具; 落在选区外的会被跳过, 并计入导出时显示的"越界跳过"

version: 1
enabled: true
furniture:
  - id: "itemsadder:myplugin:chair"   # 前缀只能是 itemsadder/oraxen/nexo/craftengine
    pos: [3, 1, 5]                    # 必须在模板尺寸内
    yaw: 90.0                         # 0.0-360.0
    facing: "east"                    # 由 yaw 算出来的, 导出时自动写入

放置时四种家具插件会按朝向把家具摆回原位 (在方块摆好之后, 生物生成之前); 如果对应家具插件没装, 那条会被跳过并提示 (console.furniture_source_absent). 还原时插件先尝试用家具插件自己的方式移除, 失败则直接删掉实体. 总开关 furniture.enabled: false 一关, 整块功能都不生效