刷新规则
刷新规则文件位于 plugins/EmakiMobs/spawn_rules/*.yml，每个文件可包含多条规则，通过 rules: 列表定义。
文件结构
yaml
rules:
- mob_id: <生物 id>
type: <刷新类型>
# 各类型专属字段…当前加载器只接受两种 type
下方"六种刷新类型"一节已陈旧
当前加载器只认 type: natural 与 type: autonomous。写 structure、biome、player_relative、day_interval、custom 不会报错，而是被记录为 Unknown spawn type 并静默跳过整条规则。
下方六型小节中，除 natural 外的五节描述的是旧 schema，字段说明仍可作参考，但 type 值本身已不生效。等价写法见 autonomous — 自主定时刷新。随插件发货的 spawn_rules/overworld.yml 对每条旧类型都标注了迁移方向。
旧 type | 当前等价写法 | 迁移注意 |
|---|---|---|
structure | autonomous + trigger: interval | interval_ticks 提升到规则根节点；active_spawn、require_player_nearby 不是当前字段。 |
biome | autonomous + trigger: interval | biomes、interval_ticks、distance 沿用；conditions.light_max / conditions.require_surface 改为根级 light_level_max / require_surface。 |
player_relative | autonomous + trigger: player_follow | distance、max_global、interval_ticks、count 沿用；require_sky_access 不是当前字段。 |
day_interval | autonomous + trigger: day_interval | interval_days、on_day_start、max_global、count 沿用；distance_from_player 改为 distance。 |
custom | autonomous + trigger: interval | interval_ticks、distance、biomes、max_nearby、count 沿用。 |
autonomous — 自主定时刷新
完全脱离原版刷新事件，由自己的调度器驱动。trigger 决定调度方式，缺 trigger 或 trigger 值未知时整条规则被跳过。
yaml
- mob_id: elite_zombie
type: autonomous
trigger: interval
interval_ticks: 1200
worlds:
- world
biomes:
- plains
distance:
min: 16
max: 64
max_nearby: 4
max_global: 10
count:
min: 1
max: 2四种 trigger
trigger | 调度方式 | 相关字段 |
|---|---|---|
interval | 固定 tick 间隔，逐个扫描所有在线玩家 | interval_ticks |
player_follow | 固定 tick 间隔，每次随机选一名在线玩家 | interval_ticks |
day_interval | 按游戏日计时 | interval_days、on_day_start |
cron | 按系统真实时间的 Cron 触发 | cron |
trigger 值不区分大小写。cron 使用 6 段 Quartz 格式，写法见 CoreLib 表达式 · Cron 表达式；表达式为空或无法解析时只打一条警告，该规则永不触发。
字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
trigger | string | 无（必需） | 调度方式，见上表。 |
interval_ticks | long | 600 | interval / player_follow 的刷新间隔（tick）。 |
interval_days | int | 1 | day_interval 的间隔游戏日数。 |
on_day_start | boolean | false | true = 天亮时触发；false = 计时到达即触发。 |
cron | string | "" | trigger: cron 的 Cron 表达式。 |
worlds | string list | []（不限） | 限定世界名。 |
biomes | string list | []（不限） | 限定生物群系。 |
structures | string list | []（不限） | 限定原版结构，NamespacedKey 格式。 |
y_range | int list [min, max] | [-64, 320] | 有效 Y 范围。 |
light_level_max | int | 15 | 光照等级不超过此值才刷出。 |
time_of_day | string | any | 限定时段：any / day（游戏时间 1000–12999）/ night（13000–999）。未知取值等同 any。 |
require_surface | boolean | false | 是否要求刷新点天光充足（天空光照为 15）。 |
distance | {min, max} | {16, 64} | 距玩家的刷新距离（格）。 |
max_nearby | int | 0 | 64 格内同 id 生物上限；0 = 不限。 |
max_global | int | 0 | 全服（所有世界）同 id 生物上限；0 = 不限。 |
count | {min, max} | {1, 1} | 每次刷出数量范围。 |
condition | section | 无 | 可选条件块。 |
六种刷新类型
natural — 原版事件拦截
拦截 Minecraft 的 CreatureSpawnEvent，在满足条件时以一定概率将原版生物替换为自定义生物。
yaml
- mob_id: elite_zombie
type: natural
biomes: # 限定生物群系列表；留空则不限
- plains
- forest
y_range: [-64, 50] # 仅在此 Y 范围内替换
light_level_max: 7 # 光照等级上限（含）
replacement_chance: 0.08 # 替换概率，0.0–1.0
max_nearby: 3 # 64 格内同 id 生物上限；0 = 不限
count:
min: 1
max: 1| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
worlds | string list | []（不限） | 限定世界名。 |
biomes | string list | []（不限） | 触发替换的生物群系列表。 |
y_range | int list [min, max] | [-64, 320] | 有效 Y 坐标范围。 |
light_level_max | int | 15 | 光照等级不超过此值才触发。 |
replacement_chance | double | 1.0 | 触发替换的概率。 |
max_nearby | int | 0 | 64 格内同 id 生物数量上限；0 = 不限。 |
count | {min, max} | {1, 1} | 每次触发刷出数量范围。 |
condition | section | 无 | 可选条件块。 |
structure — 结构内定时刷新
当玩家进入指定原版结构附近时，按 active_spawn 定时向结构内补充生物。
yaml
- mob_id: bone_lord
type: structure
structures:
- minecraft:stronghold # NamespacedKey 格式
max_nearby: 1
active_spawn:
interval_ticks: 6000 # 每 5 分钟检查一次
require_player_nearby: 64 # 必须有玩家在此范围内
count:
min: 1
max: 1| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
structures | string list | [] | 目标结构 NamespacedKey 列表。 |
max_nearby | int | 0 | 结构附近同 id 生物上限。 |
active_spawn.interval_ticks | int | 1200 | 补充检查间隔（tick）。 |
active_spawn.require_player_nearby | int | 64 | 触发所需玩家距离（格）。 |
biome — 生物群系周期刷新
每隔 interval_ticks tick 为每名在线玩家在附近寻找地表位置，若符合生物群系和条件则刷出。
yaml
- mob_id: jungle_stalker
type: biome
biomes:
- jungle
- bamboo_jungle
interval_ticks: 600
distance:
min: 16
max: 48
conditions:
light_max: 7
require_surface: false
max_nearby: 2
count:
min: 1
max: 2| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
biomes | string list | []（不限） | 目标生物群系列表。 |
interval_ticks | long | 400 | 每名玩家的刷新检查间隔（tick）。 |
distance | {min, max} | {16, 64} | 距玩家的刷新距离范围（格）。 |
conditions.light_max | int | 15 | 刷出位置光照等级上限。 |
conditions.require_surface | boolean | false | 是否要求刷出位置可见天空。 |
max_nearby | int | 0 | 附近同 id 生物上限。 |
player_relative — 跟随玩家定时刷新
每隔 interval_ticks tick 在每名在线玩家附近随机位置刷出生物，适合稀有巡逻兵或伴随型生物。
yaml
- mob_id: elite_zombie
type: player_relative
distance:
min: 24
max: 64
require_sky_access: false
max_global: 10
interval_ticks: 12000
count:
min: 1
max: 1| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
distance | {min, max} | {16, 64} | 距玩家的刷新距离范围（格）。 |
require_sky_access | boolean | false | 是否要求刷出位置可见天空。 |
max_global | int | 0 | 全服同 id 生物总量上限；0 = 不限。 |
interval_ticks | long | 24000 | 每名玩家的刷新间隔（tick）。 |
day_interval — 游戏日计时刷新
每隔 interval_days 个游戏日（约20 分钟/天）在玩家附近刷出一次，适合周期性 Boss 或稀有事件。
yaml
- mob_id: bone_lord
type: day_interval
interval_days: 3
on_day_start: true
distance_from_player:
min: 20
max: 50
max_global: 2
count:
min: 1
max: 1| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
interval_days | int | 1 | 每隔几个游戏日触发一次。 |
on_day_start | boolean | false | true = 天亮时触发；false = 计时到达即触发。 |
distance_from_player | {min, max} | {16, 64} | 距玩家的刷新距离（格）。 |
max_global | int | 0 | 全服同 id 生物总量上限。 |
custom — 自定义定时刷新
最灵活的刷新类型，定时为每名玩家附近随机位置刷出，可叠加生物群系过滤。
yaml
- mob_id: elite_zombie
type: custom
interval_ticks: 1200
distance:
min: 16
max: 64
biomes:
- plains
max_nearby: 4
count:
min: 1
max: 2| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
interval_ticks | long | 600 | 每名玩家的刷新间隔（tick）。 |
distance | {min, max} | {16, 64} | 距玩家的刷新距离（格）。 |
biomes | string list | []（不限） | 可选生物群系过滤。 |
max_nearby | int | 0 | 附近同 id 生物上限。 |