自然生成与预加载（生成总控 / 密度 / 再生）
上一页：放置档案（generators/*.yml） · 下一页：程序化生成（调色板 / 子结构变体） 相关：遗迹模板 · config.yml 全配置 · 命令大全
放置档案管「一座遗迹自己能落在哪」，生成总控 管「全世界这么多遗迹，谁、在哪、多久冒一个」。它是把配方变成锚点的调度大脑：所有可生成的遗迹按权重竞争抽签，受全局密度（每区域上限、最小间距）约束，能在已探索的世界里围绕玩家活世界刷新，还能让打通的遗迹随时间消退再生腾出名额。
提示
生成总控开 / 关，是两套世界观：
- 开（推荐）：一堆遗迹抢一个名额，密度统一可控，世界会「活着长」。
- 关（向后兼容）：回退到「每个模板各自按
generation.probability独立 roll」的旧逻辑——各刷各的，没有全局密度，老服 config 无director段时自动走这条路。
🖼️ [图片占位] 「新区块/活世界触发 → 生成总控抽签选模板 → 密度+间距校验 → 落点放置」的调度流水线图 · 建议
assets/director-pipeline.png
一、两层开关：generation 总开关 + director 子开关
generation:
enabled: true # 自然生成总开关（关闭则只能 /qr spawn 手动投放）
grid-bucket-size: 512 # 空间索引分桶尺寸
max-per-tick: 4 # 每次处理的候选区块上限（限流防卡）
max-millis-per-tick: 3 # ★每tick的毫秒预算：超时即让出本tick（比固定条数更抗压）
period-ticks: 5 # 候选处理任务的间隔 tick
director:
enabled: true # 总控接管：权重抽签 + 全局密度（老服无此段=自动回退旧逻辑）
...| 字段 | 默认 | 含义 |
|---|---|---|
generation.enabled | true | 生成总大闸。关掉则整套自然生成都停，只能 /qr spawn / /qr stage 手动投放。它也约束生成总控——总开关关了，生成总控再开也不生成。 |
grid-bucket-size | 512 | 空间索引分桶尺寸（锚点位置的快速查询用），一般不动。 |
max-per-tick | 4 | 候选处理任务每次最多处理几个候选区块（限流）。 |
max-millis-per-tick | 3 | 每 tick 的毫秒预算：处理累计超此耗时即让出本 tick，比固定条数更抗生成尖峰、防冻服。 |
period-ticks | 5 | 候选处理任务的运行间隔（tick）。 |
⚙ 候选不是当场放置，而是进队列分帧落地：触发（新区块 / 活世界）只是把「世界 + 区块 + 模板」塞进候选队列，由后台任务按
max-per-tick/max-millis-per-tick/period-ticks限流处理。队列满（默认上限较大）会丢弃多余候选并每分钟告警一次——此时调大max-per-tick/max-millis-per-tick或调低director.live.chance。
二、生成总控全字段
director:
enabled: true
notify-admins: true
chunk-chance: 80
live:
enabled: true
interval: 10m
chance: 0.25
min-radius: 80
max-radius: 220
density:
region-size: 512
max-per-region: 3
min-spacing: 48
regen-hours: 24
weights: []2.1 顶层
| 字段 | 默认 | 含义 |
|---|---|---|
enabled | true | 开 = 总控接管（权重抽签 + 全局密度）；关 = 回退每模板各自 probability roll。 |
notify-admins | true | 任意遗迹自然生成时，私聊在线管理员（qinhruins.admin）报坐标 + ID。调试找遗迹神器，嫌吵可关。 |
chunk-chance | 80 | 新区块尝试生成的概率分母：每个新加载的区块有 1/N 几率发起一次生成尝试。0 = 探索不主动刷，纯靠下面的 live。想多刷调小（如 40），想少调大。 |
2.2 活世界 live（已探索的世界也会长新遗迹）
chunk-chance 只在「新区块」触发，老地图早探索完就不再有新区块。live 让生成总控定时围绕在线玩家在已加载区块里也尝试生成，于是「老世界也会长出新遗迹」。
| 字段 | 默认 | 含义 |
|---|---|---|
enabled | true | 活世界总开关。 |
interval | 10m | 每隔多久围绕在线玩家尝试一次（这就是「刷新间隔」，调试可改 1m / 30s；最低 20 秒）。 |
chance | 0.25 | 每名玩家每次尝试的概率（越高刷得越勤）。 |
min-radius | 80 | 在玩家这个环带内选址（避开脚下，太近突兀）。 |
max-radius | 220 | 一般略大于视距——玩家走近时新遗迹「正好已经在那」。 |
⚙ 选址只在已加载区块：
live每次为命中概率的玩家算一个[min-radius, max-radius]环带内的随机点，该点所在区块未加载就跳过（不强制加载防卡），加载了才发起候选。所以遗迹倾向于在玩家活动范围边缘出现。
2.3 全局密度 density（世界总体遗迹密度）
| 字段 | 默认 | 含义 |
|---|---|---|
region-size | 512 | 密度统计的方格边长（格）。 |
max-per-region | 3 | 每个 region-size×region-size 方格内最多几座遗迹（0 = 不限）。 |
min-spacing | 48 | 任意两座遗迹的最小间距，贴脸兜底（0 = 不限）。 |
⚙ 密度与间距的判定：放置前生成总控先数落点所在方格里已有几座非回收锚点，达到
max-per-region就拒绝；再查min-spacing范围内有没有别的锚点。档案 / 模板里写了min-distance-others就用它自己的值（可低于全局兜底），没写(0)才用全局min-spacing。min-distance-same是「距同款遗迹」的额外间距，防同款扎堆。
2.4 消退再生 regen-hours
regen-hours: 24 # 打通的遗迹 24h 后、附近无人时快照还原，腾出密度名额- 打通（
CLEARED）的遗迹超过regen-hours小时、且附近（约 64 格内）没有玩家时，生成总控会快照还原地形、把锚点转RECYCLED，腾出密度名额让世界长新遗迹。 0= 永不消退（打通的遗迹永久留在世界里当地标）。- ⚠️ 真正还原方块需要开
cleanup.snapshot-restore（见 §四）。没开快照时regen-hours只会腾出密度名额、回收锚点记录，但不还原方块。
2.5 权重 weights
weights:
[]
# - { template: ancient_tower, weight: 30 } # 数字越大越常见
# - { template: sunken_crypt, weight: 10 }- 留空（
[]）= 自动用各模板的generation.weight/generation.probability折算权重——无需在这里逐个登记，新加的遗迹自动参与抽签。 - 想集中、强制控盘时，在这里显式列模板 + 权重；一旦写了非空
weights，就只有列进来的模板参与抽签（没列的不刷）。
⚙ 抽签流程：候选点上，先取所有「
generation.enabled且世界 / 维度匹配」的模板 → 找出最高优先级（priority最小）那批 → 在这批里按权重轮盘抽一个。留空 weights 时，模板权重 =generation.weight（>0 时用它），否则由probability的numerator/denominator折算成整数权重。
三、生成总控开 vs 关 对照
| 维度 | 生成总控开 | 生成总控关（向后兼容） |
|---|---|---|
| 选谁 | 一堆遗迹按权重竞争抽一个 | 每个模板各自按 probability 独立 roll |
| 触发 | 新区块（chunk-chance）+ 活世界（live） | 新区块各模板各掷各的 |
| 全局密度 | density.region-size/max-per-region/min-spacing 统一约束 | 无全局密度（只有模板自己的 min-distance-*） |
| 活世界 | 老地图也长新遗迹 | 无（探索完就不再刷） |
| 消退再生 | regen-hours 打通后消退腾名额 | 无 |
| 适合 | 绝大多数服（密度可控、世界活着长） | 极简、要完全复刻旧行为、或老服未迁移 config |
四、快照与再生（cleanup）
cleanup:
snapshot-restore: true # 生成结构前快照原地形，移除/消退时还原
max-snapshot-volume: 500000 # 快照体积上限(方块数)：超此值跳过快照（移除不还原但不卡服）。0=不限(危险)| 字段 | 默认 | 含义 |
|---|---|---|
snapshot-restore | true | 生成结构前快照原地形，/qr remove 或 regen-hours 消退时还原方块。关闭省磁盘，但移除 / 消退不还原方块。 |
max-snapshot-volume | 500000 | 快照体积上限（方块数）。超大结构（百万级）同步快照会冻主线程、被看门狗杀服 → 超此值跳过快照（移除不还原但不卡服）。0 = 不限（危险）。 |
🔗
regen-hours与snapshot-restore配合使用：要让打通的遗迹「真消退、地形还原如初」，两者都要开——regen-hours>0（设定消退时机）+snapshot-restore: true（生成时存了快照才有得还原）。只开regen-hours不开快照，消退只腾名额不复原方块。
五、调试命令
| 命令 | 用途 |
|---|---|
/qr why <模板> | 诊断：在你脚下逐条列出该模板每项落点检测（开关 / 世界 / 维度 / 坐标盒 / 高度 / 地面 / 水 / 群系 / 平整度 / 间距 / 密度）的通过 / 失败 + 原因。「配了不生成」第一时间用它。 |
/qr gentest | 在你附近按生成总控的活世界算法发起约 25 次生成尝试，回报「成功 N / 被密度拦 / 没抽到模板 / 放置失败」各几次。看实际命中率。 |
/qr scatter <半径> <数量> | 围绕你批量预生成：半径 100–20000，数量 1–200。在半径内撒点尝试放置，直到铺满目标数量或耗尽尝试。一次性把一片区域填满遗迹看效果（生成期间静默不刷管理员广播）。 |
/qr spawn <模板> | 绕过一切选址检测，直接在你脚下投放一座指定遗迹（手动放置，不受生成总控 / 密度约束）。 |
⚙
/qr gentest与/qr scatter都要求生成总控开启（director.enabled: true），关着会提示总控未启用。/qr why与/qr spawn不受此限。
🖼️ [图片占位]
/qr why ancient_tower输出的逐条检测清单（绿勾 / 红叉）截图 · 建议assets/qr-why.png
六、调参速查
| 我想要 | 改哪里 |
|---|---|
| 遗迹整体更多 | 调小 chunk-chance、调高 live.chance、调高 density.max-per-region |
| 遗迹整体更少 / 更稀 | 调大 chunk-chance、调低 live.chance、调小 max-per-region、调大 min-spacing |
| 老地图也持续长新遗迹 | 开 live.enabled，缩短 live.interval |
| 某座遗迹更常见 / 更稀有 | 调它模板的 generation.weight（或在 weights 里显式给权重 / spawn-chance） |
| 打通的遗迹定期清掉腾位 | regen-hours: 24 + cleanup.snapshot-restore: true |
| 出生点附近不刷 | 档案 / 模板加 spawn-region { exclude: true }（见 放置档案 §7） |
| 完全复刻旧版各刷各的 | director.enabled: false |
七、世界预生成（Chunky）与防卡建议 ⚠️ 必读
QR 的遗迹是跟着区块走的：新区块加载（chunk-chance）或玩家活动（live）才触发生成尝试。所以「先把世界预生成铺开，再让玩家进去探索」体验最好——区块都成型了，遗迹在玩家走到前就已落位，进图不卡顿、/qr scatter 也能一次性把一片区域铺满遗迹。
7.1 用什么插件预生成
推荐 Chunky（免费、轻量、主流、Paper 原生兼容），这是目前最通用的世界预生成插件。常用流程：
/chunky world world # 选要预生成的世界
/chunky center 0 0 # 设中心（一般出生点）
/chunky radius 3000 # 设半径（格）——★这个数字直接决定耗时与卡顿
/chunky start # 开始预生成（后台跑，可 /chunky pause 暂停）也有 WorldBorder 等老牌方案，原理一致。本节的注意事项对它们都适用。
7.2 ⚠️ 预生成会很卡、很慢——这是预生成本身的代价，不是 QR 的问题
🔴 重要认知：预生成阶段的卡顿、TPS 下降、耗时长，来自服务端在疯狂生成原版地形区块（Chunky 在干活），而不是 QinhRuins。 QR 自身的遗迹放置是分帧限流的（
max-millis-per-tick/ 候选队列，见 §一），超时就让出本 tick，不会冻服。请务必让服主和玩家明白这点，别把预生成的卡当成 QR 的锅。
7.3 给服主的防卡清单（按这个来基本不出事）
- 提前发通知：预生成期间服务器会明显卡顿、TPS 掉，提前在群 / 公告里告知玩家，约定一个低人数时段（如凌晨）执行。
- 资源世界要单独说：如果你预生成 / 重置的是资源世界，务必提前通知玩家「资源世界即将关闭 / 重置」，让大家把家当和建材搬走，避免财产损失和投诉。
- 配置不好就把半径调小：服务器配置一般，一次别铺太大。先
radius 1000~2000跑一批看负载，扛得住再加大；不要一上来就radius 10000把服务器顶死。 - 分批次执行：大地图拆成几次跑——这批跑完、TPS 回稳，再跑下一批。Chunky 支持
/chunky pause//chunky continue断点续传，关服重启也能接着跑。 - 预生成时先给 QR 减负：Chunky 会在短时间内加载海量新区块，每个新区块 QR 都会按
chunk-chance发起一次生成尝试，候选队列可能被瞬间塞满（控制台会每分钟告警一次）。两种做法：- 省心做法：预生成期间临时把
generation.enabled设false（或把director.chunk-chance调到很大、live.enabled关掉），等预生成跑完，再开回来并用/qr scatter <半径> <数量>手动、可控地把遗迹一次性撒进已铺好的区域。 - 放任做法：保持默认也行——QR 的
max-millis-per-tick会自我限流、不冻服，只是预生成期间遗迹落位会被限流拖慢、且候选队列满时丢弃多余候选（不影响后续live补刷）。
- 省心做法：预生成期间临时把
- 预生成完别忘了：把临时改的
generation.enabled/chunk-chance/live调回正常值并/qr reload。
7.4 预生成 + QR 的推荐顺序
① 公告通知玩家（尤其资源世界要说"即将关闭/重置"）
② （可选）临时 generation.enabled: false，/qr reload，给 QR 减负
③ Chunky 分批预生成：小半径起步 → 看 TPS → 再加大 / 跑下一批
④ 预生成完成、TPS 回稳
⑤ 调回 QR 生成配置，/qr reload
⑥ /qr scatter <半径> <数量> 把遗迹一次性铺进已生成区域（或交给 chunk-chance/live 慢慢长）
⑦ /qr near / /qr gentest 抽查，开服🖼️ [图片占位] Chunky 预生成进度 + 同期 TPS 曲线，标注「卡顿来自地形生成而非 QR」 · 建议
assets/pregen-chunky.png
下一步
- 一座遗迹自己的落点规则 → 放置档案
- 模板侧
generation.weight/priority/spawn-chance→ 遗迹模板 §5 - 把多个小结构拼成大遗迹 / 子结构变体 → 程序化生成
- 全部 config.yml 字段 → config.yml 全配置