放置档案（generators/*.yml）

上一页：机关系统（触发器 × 动作）　·　下一页：自然生成与预加载（生成总控 / 密度 / 再生）相关：遗迹模板 · 程序化生成 · 内置内容清单

放置档案（Profile）是「这座遗迹在哪生成」的可复用规则包：维度 / 世界 / 群系过滤、生成层、平整度、最小间距、落点检测、概率……一份档案就是 plugins/QinhRuins/generators/<名>.yml 里的一个文件。多个模板可以共享同一份档案（generation.profile: surface_overworld），也可在模板里局部覆盖任意字段。插件自带 17 个内置档案，覆盖三维度全部常见地貌。

提示

一句话分工：档案管「选址规则」、模板管「身份与玩法」。 模板用 generation.profile 引用档案继承一整套默认，只写要改的字段即可。

🖼️ [图片占位] 一张「模板 generation.profile → 档案 generators/*.yml → 落点校验链」的示意图　·　建议 assets/profile-flow.png

一、档案 vs 模板覆盖：继承关系（关键）

放置档案和模板的 generation 段用的是同一套字段。加载顺序是：

内置兜底(DEFAULT) → 引用的档案(profile) → 模板 generation 段写的字段
        每一层只覆盖「自己显式写了的键」，没写的沿用上一层

模板写 generation.profile: surface_overworld → 先拿到整份 surface_overworld 档案当底；
模板的 generation 段里再写的任何字段（biomes / y / flatness / min-distance-same…）逐键覆盖档案里的同名项；
没写的键继续用档案的值。

⚙ 逐键覆盖、不是整段替换：模板里只写 biomes: [PLAINS] 不会把档案的 layer / min-distance-others 一起清空——只覆盖 biomes 这一个键，其余照旧。所以「引用档案 + 只写两三行覆盖」是推荐写法。

注意

引用了不存在的 profile：自动回退内置默认档案并在控制台告警；y（生成层）值无法识别 → 回退 surface 并告警。

模板侧 generation 段的完整写法见遗迹模板 §5。本页专讲档案文件本身的全部字段。

二、字段总表

下表是 generators/*.yml 的全部字段（模板 generation 段同样可写）。加粗为最常配。

YAML 键	类型	默认	含义
`enabled`	Bool	`false`	档案是否可用（一般写 `true`）。模板侧的 `generation.enabled` 才是「这座遗迹参不参与自然生成」的真正开关。
`layer`（或 `y`）	String	`surface`	生成层：地表 / 地下 / 天空 / 海面 / 海底 / 固定 Y / 相对地表。见 §四。
`environments`	List	空	维度环境：`NORMAL`(主世界) / `NETHER`(下界) / `THE_END`(末地)；空=不限。
`worlds`	List	空	再按世界名细分（空=该环境下所有世界）。
`biomes`	List	空	限定群系；空=不限。见 §三。
`probability`	段	`1/1000`	`{ numerator, denominator }`，仅生成总控关闭时各自 roll 用。见 §五。
`priority`	Int	`0`	优先级：数字越小越优先；同候选点只有最高优先级那批参与权重抽签。
`spawn-chance`	Double	`1.0`	绝对稀有度：被抽中后再独立掷骰，`<1.0` 才真稀有。
`min-distance-others`	Int	`0`	距任意遗迹最小间距（格）。
`min-distance-same`	Int	`0`	距同类遗迹最小间距（格），防同款扎堆。
`flatness`	段	—	选址平整度检测 `{ radius, max-variance, max-errors }`。见 §六。
`whitelist-ground`	List	空	仅允许落在这些地面方块上。
`blacklist-ground`	List	空	禁止落在这些地面方块上。
`spawn-in-water`	Bool	`true`	`false` = 不许落在水面方块上。
`spawn-in-lava`	Bool	`false`	`true` = 允许落在岩浆面（下界岩浆海主题）。
`spawn-in-void`	Bool	`true`	`false` = 强制落在实心地面（拒绝脚下悬空）。
`heightmap`	String?	无	surface 层的高度图算法。见 §四。
`y-band`	段	—	underground / sky 的随机深度 / 高度区间 `{ min, max }`。
`y-offset`	Int	`0`	垂直微调（最终 Y 再 ±N，海面已自动对齐水线一般留 0）。
`spawn-region`	段	无	坐标盒限制 `{ min-x, min-z, max-x, max-z, exclude }`。见 §七。

说明

layer 和 y 是同一字段的两个名字（layer 优先）。档案文件里习惯写 layer，模板 generation 段里习惯写 y，效果完全一样。

三、维度 / 世界 / 群系过滤

yaml

environments: [NORMAL]     # 维度：NORMAL(主世界)/NETHER(下界)/THE_END(末地)；空=不限
worlds: []                 # 再按世界名细分（空=该环境下所有世界）
biomes:                    # 限定群系（空=不限）
  - PLAINS
  - FOREST

environments 认 NORMAL / OVERWORLD（都等于主世界）、NETHER / THE_NETHER、END / THE_END。想兼容自定义主世界维度可再加 CUSTOM。
worlds 在 environments 基础上再收紧到具体世界名（大小写不敏感）。空=该环境下所有世界都行。
biomes 写原版群系枚举名（如 PLAINS / DESERT / LUSH_CAVES）。命中规则同时认「带命名空间的 key」和「枚举名」，写不写 minecraft: 前缀都行；空=不限群系。

⚙ 群系判定取的是落点那一格的实际群系。海底 / 地下档案落点在水下 / 地下，群系仍按该坐标读取，所以 OCEAN / DRIPSTONE_CAVES 这类要写对应的洞穴 / 海洋群系。

四、生成层与高度（layer / y-band / y-offset / heightmap）

layer（= y）决定结构落在哪一层。取值：

`layer` / `y` 取值	含义
`surface`（`ground` / `top`）	地表。智能跳过树冠 / 树叶落到真地面。
`underground`（`cave` / `buried`）	地下，向下埋。配 `y-band` 定深度区间（默认 8~40）。
`sky`（`floating` / `air`）	天空，向上悬浮。配 `y-band` 定高度区间（默认 30~70）。
`ocean-surface`（`sea-surface` / `water-surface`）	海面，自动对齐水线；该列没水则换点。
`seabed`（`ocean-floor` / `underwater`）	海底（海床实心面）；没水则换点。
固定数字（如 `64`）	固定 Y 坐标。
`+8` / `-5`	相对地表上 8 格 / 下 5 格。
`+[3;12]` / `-[2;6]`	相对地表上随机 3~12 格 / 下随机 2~6 格。

yaml

layer: underground
y-band: { min: 10, max: 35 }   # 地表往下随机埋深 10~35 格
# y-offset: 0                  # 最终 Y 再 ±N 微调
# heightmap: world-surface     # 仅 surface 层：地表算到哪

y-band：只对 underground / sky 生效——underground 是「地表往下随机 [min,max] 格」，sky 是「地表往上随机 [min,max] 格」。
y-offset：在算出的最终 Y 上再加一个固定偏移，做整体微调。
heightmap（仅 surface）：控制「地表」算到哪个高度图——world-surface / motion-blocking / motion-blocking-no-leaves（= no-leaves） / ocean-floor。留空 = 智能跳过树冠 / 树叶 / 雪 / 藤蔓落到真地面（推荐）。

⚙ 下界的「地表」是特殊算法：下界顶天花板是基岩，QR 从 Y≈120 往下扫，找「下方实心(非岩浆) + 当前与上方都是空气」的第一格作落点，自动避开基岩天花板。所以下界档案直接写 layer: surface 就落在地形顶面。

注意

海面 / 海底档案靠水判定落点：那一列若海平面下没有水，会直接放弃该点重选。水下结构请确保原理图自带封闭外壳，否则内部灌水。

五、概率（probability）—— 仅生成总控关闭时

yaml

probability: { numerator: 1, denominator: 700 }   # 1/700：仅 director 关闭时按此各自 roll

生成总控开启时：probability 被忽略，所有遗迹改走「权重竞争抽签 + 全局密度」。各模板的 generation.weight（或留空时由 probability 自动折算的权重）参与抽签。
生成总控关闭时（向后兼容旧逻辑）：回退到「每个模板各自按 probability 独立 roll」——每个候选点按 numerator/denominator 掷骰决定生不生。

说明

内置档案的 denominator 普遍是 500~900（地下洞穴更密、天空 / 海洋更稀），是「平均每这么多候选点出一个」的稀有度基准。开了生成总控后这些值不再直接生效，但留空 director.weights 时会被折算成抽签权重，所以仍有相对稀有度意义。生成总控详见自然生成与预加载。

六、平整度与落点检测

yaml

flatness: { radius: 4, max-variance: 4, max-errors: 0 }
whitelist-ground: [GRASS_BLOCK, DIRT]   # 仅允许落在这些地面方块上
blacklist-ground: [SAND, WATER]         # 禁止落在这些地面方块上
spawn-in-water: true
spawn-in-lava: false
spawn-in-void: true

平整度 flatness：以落点为中心采样一圈地面高度，判断地够不够平。

字段	默认	说明
`radius`	—	检测半径（格）。`0` 或 `max-variance:0` = 不检测（天空 / 海洋 / 地下档案都关）。
`max-variance`	—	允许的最大高差。采样点比最低点高出超过它就算一个「凸起」。
`max-errors`	`0`	允许几个凸起采样点。`0` = 一个都不许（最严，地必须很平）。

⚙ 采样实现：radius<=4 时每格采样、更大时隔 2 格采样；取所有采样高度的最小值作基准，统计「高出 max-variance」的点数，超过 max-errors 就判定不平、放弃该点。地越平越严，凸起越多越容易被拒。

落点方块检测（检查落点正下方那一格 y-1）：

字段	行为
`whitelist-ground`	非空时，地面方块必须在白名单里（如荒漠档案 `[SAND, SANDSTONE, RED_SAND]`）。
`blacklist-ground`	地面方块在黑名单里就拒绝。
`spawn-in-water`	`false` = 正下方是水就拒绝。
`spawn-in-lava`	`false`（默认）= 正下方是岩浆就拒绝；`true` 用于下界岩浆海主题。
`spawn-in-void`	`false` = 正下方是空气（脚下悬空）就拒绝，强制实心落点。

七、坐标盒限制（spawn-region）

把生成限制 / 排除在一个矩形 XZ 盒内（如「出生点保护区不刷遗迹」）。

yaml

spawn-region:
  min-x: -2000
  min-z: -2000
  max-x: 2000
  max-z: 2000
  exclude: true        # true=只在盒外刷（出生点附近不刷）；false=只在盒内刷

字段	说明
`min-x` / `min-z` / `max-x` / `max-z`	矩形 XZ 范围。
`exclude`	`false`（默认）= 只在盒内生成；`true` = 只在盒外生成。

提示

出生点保护：exclude: true + 一个围住出生点的盒，新手区就永远不会冒出遗迹。

八、17 个内置档案清单

插件自带 generators/ 下 17 份档案，按维度 × 地貌划分。模板直接 generation.profile: <名> 引用即可。

主世界（NORMAL）

档案名	层	群系范围	备注
`surface_overworld`	surface	不限群系	通用地表兜底，最常用
`surface_grassland`	surface	平原 / 森林 / 针叶林 / 沼泽 / 丛林 / 草甸等草木带	flatness 较严
`surface_desert`	surface	荒漠	`whitelist-ground: [SAND, SANDSTONE, RED_SAND]`
`surface_snowy`	surface	雪原 / 雪林 / 冰刺 / 冰封山峰 / 林地等冰雪带	—
`surface_barren`	surface	恶地 / 热带草原 / 蘑菇岛 / 石峰等荒原	—
`underground_overworld`	underground	不限群系	通用地宫 / 墓穴，`y-band 10~35`
`underground_lush`	underground	繁茂洞穴	`y-band 6~24`
`underground_dripstone`	underground	滴水石洞穴	`y-band 8~30`
`sky_overworld`	sky	不限群系	悬浮空岛，`y-band 35~75`
`ocean_overworld`	ocean-surface	各类海洋群系	沉船 / 浮台，浮海面
`seabed_overworld`	seabed	各类海洋群系	水下遗迹，需自带封闭外壳

下界（NETHER）

档案名	层	备注
`surface_nether`	surface	坐落地形顶面，已避开基岩天花板
`underground_nether`	underground	埋在地狱岩层里，`y-band 8~24`
`sky_nether`	sky	悬浮熔岩海上方，`y-band 18~38`（顶是基岩，别配太高）

末地（THE_END）

档案名	层	备注
`surface_end`	surface	坐落末地岛屿表面
`underground_end`	underground	埋入末地石岛内部，`y-band 6~18`
`sky_end`	sky	悬浮末地岛上方，`y-band 25~60`

内置档案的完整字段值见内置内容清单。

九、完整注解示例

一份「草木带地表」自定义档案（可直接放进 generators/my_surface.yml）：

yaml

# 放置档案 · 自定义草木带地表
enabled: true
layer: surface                 # 生成层：地表
environments: [NORMAL]         # 仅主世界
worlds: []                     # 不限世界
biomes: [PLAINS, FOREST, TAIGA]  # 限定群系
probability: { numerator: 1, denominator: 600 }  # 仅 director 关闭时各自 roll
min-distance-others: 80        # 距任意遗迹 ≥80 格
min-distance-same: 320         # 距同款遗迹 ≥320 格
flatness: { radius: 5, max-variance: 3, max-errors: 1 }  # 要求较平的地
whitelist-ground: []           # 不限地面方块
blacklist-ground: [WATER, LAVA]
spawn-in-water: false          # 不落水面
spawn-in-void: false           # 不悬空
y-offset: 0
# spawn-region:                # 可选：出生点保护
#   min-x: -1500
#   min-z: -1500
#   max-x: 1500
#   max-z: 1500
#   exclude: true              # 只在这个盒外刷

模板里引用它，只覆盖两行：

yaml

# template.yml 片段
generation:
  profile: my_surface          # 引用上面的档案
  enabled: true
  weight: 20                   # 抽签权重
  biomes: [PLAINS]             # 只覆盖群系：收窄到仅平原（其余字段沿用档案）

🖼️ [图片占位] 同一份档案被三座不同遗迹模板引用、各自只覆盖少量字段的对照图　·　建议 assets/profile-shared.png

十、改完之后

改 generators/*.yml 或模板 generation 段 → /qr reload。
想确认「某模板能不能在我脚下生成、卡在哪一步」→ /qr why <模板>（逐条列出每项检测的通过 / 失败）。
想看生成总控在附近的实际生成命中率 → /qr gentest。
想立刻在半径内批量铺一片看效果 → /qr scatter <半径> <数量>。

详见自然生成与预加载与诊断与排错。

下一步

生成总控、密度、消退再生 → 自然生成与预加载
模板侧 generation 段怎么写 → 遗迹模板 §5
子结构变体 / 调色板拼接 → 程序化生成
全部内置档案字段值 → 内置内容清单

放置档案（generators/*.yml） ​

一、档案 vs 模板覆盖：继承关系（关键） ​

二、字段总表 ​

三、维度 / 世界 / 群系过滤 ​

四、生成层与高度（layer / y-band / y-offset / heightmap） ​

五、概率（probability）—— 仅生成总控关闭时 ​

六、平整度与落点检测 ​

七、坐标盒限制（spawn-region） ​

八、17 个内置档案清单 ​

主世界（NORMAL） ​

下界（NETHER） ​

末地（THE_END） ​

九、完整注解示例 ​

十、改完之后 ​

下一步 ​

放置档案（generators/*.yml）

一、档案 vs 模板覆盖：继承关系（关键）

二、字段总表

三、维度 / 世界 / 群系过滤

四、生成层与高度（layer / y-band / y-offset / heightmap）

五、概率（probability）—— 仅生成总控关闭时

六、平整度与落点检测

七、坐标盒限制（spawn-region）

八、17 个内置档案清单

主世界（NORMAL）

下界（NETHER）

末地（THE_END）

九、完整注解示例

十、改完之后

下一步