Async Structure Generator (Astruct)
Astruct 允许你生成基于锁孔结构的巨型结构,而不会导致服务器卡死。
它在后台线程规划结构、排队放置操作,并且仅在所需区块加载后才构建方块。
在实际操作中,非常大的结构可能需要几秒钟才能“流式加载”——尤其是在传送之后,因为规划过程需要时间。在生存模式中,当 plan_horizon_chunks 设置得足够高时,这通常是无感知的。
为什么要使用 Astruct?
- 远超原版限制 – 安全地规划数千个锁孔部件。
- 后台线程规划 – 繁重的锁孔扩展运行在主线程之外,避免 TPS 飙升。
- 数据包驱动 – 通过 JSON 分发内容;无需编写代码。
工作原理(简版)
- 中心点 – 世界被划分为“单元格”(
spacing)。每个单元格根据结构 ID 获得一个确定性的、基于种子的中心点。
- 邻近扫描 – 随着玩家漫游,Astruct 会提前为玩家前方较远的单元格进行预规划。
- 异步扩展 – 锁孔扩展在后台线程中运行。
- 放置队列 – 完成的计划按它们所需的区块作为键入队。
- 区块安全构建 – 在区块加载(以及定期扫描)时,Astruct 仅放置当前已加载区块的部件。
JSON 定义(数据包)
将 JSON 文件放置在:
data/<namespace>/worldgen/async_structure/<id>.json
示例
{
"id": "example:castle",
"dimension": "minecraft:the_nether",
"start_pool": "castle:start",
"fallback_pool": "castle:caps",
"soft_radius_chunks": 16,
"plan_horizon_chunks": 160,
"budgets": {
"max_steps": 30,
"max_open_connectors": 128
},
"gen_y": { "mode": "surface", "value": 0 },
"spacing": 2048
}
字段参考
-
id
唯一结构 ID(应与文件路径键匹配)。
-
dimension
目标维度键(例如 minecraft:the_nether)。
-
start_pool
开始扩展的模板池。
-
fallback_pool
用于封顶死胡同(末端部件)的池。
-
soft_radius_chunks
扩展期间从中心点出发的最大距离预算(以区块为单位)。
-
plan_horizon_chunks
规划器在玩家周围提前准备多远(以区块为单位)。
-
budgets.max_steps
每次计划中锁孔部件的上限。
-
budgets.max_open_connectors
待处理连接器的安全限制。
-
gen_y
控制最终 Y 坐标的选择方式。
Y 坐标会在最终结构位置解析。
支持的模式:
-
"fixed"
始终使用 value 作为 Y 层级。
-
"min_plus"
min_build_height + value。
-
"world_y"
世界海平面。
-
"surface"
结构 X/Z 位置的地形表面
(可通过 value 添加可选偏移量)。
示例:
"gen_y": { "mode": "surface", "value": 0 }
-
spacing
单元格大小,单位为方块(有效控制密度)。
字段参考
id – 唯一结构 ID(应与文件路径键匹配)。
dimension – 目标维度键(例如 minecraft:the_nether)。
start_pool – 开始扩展的模板池。
fallback_pool – 用于封顶死胡同(末端部件)的池。
soft_radius_chunks – 扩展期间从中心点出发的最大距离预算(以区块为单位)。
plan_horizon_chunks – 规划器在玩家周围提前准备多远(以区块为单位)。
budgets.max_steps – 每次计划中锁孔部件的上限。
budgets.max_open_connectors – 待处理连接器的安全限制。
gen_y.mode – "fixed" | "world_y" | "min_plus"。
gen_y.value – Y 或偏移量(取决于模式)。
spacing – 单元格大小,单位为方块(有效控制密度)。
piece_rules.deny_overlap_tile_entities – 可选的安全标志,用于跳过可能导致 TE 重叠的部件。
命令
Astruct 接入原版的 /locate 根命令:
/locate astruct – 查找此维度中任意 Astruct 结构的最近中心点。
/locate astruct <id> – 查找特定结构 ID 的最近中心点。
配置(服务端)
astruct-common.toml:
debug_logs (布尔值, 默认 false) – 详细诊断日志。
max_placements_per_tick (整数, 默认 10) – 每刻放置部件的上限。
根据你的硬件/整合包进行调整。
性能说明
- 规划成本 随
max_steps 和池复杂度缩放。数千个部件可能在后台线程中花费几秒钟——这是预期的。玩家不会卡顿;放置是受控进行的。
- 放置按区块节奏进行。 只有当部件所在的区块加载时才会放置,当你靠近时会产生平滑的“流式”效果。
兼容性
- 可与原版和模组结构共存。
Astruct 不会替换原版生成;它是在原版之上添加了一个异步规划器/放置器。
故障排除
- 命令中出现 “Unknown structure id”
检查你的数据包路径,并确保 JSON 内部的
id 与文件的命名空间键匹配。
- “我的结构从未生成” / “耗时太久”
启用
debug_logs 查看规划时间。非常高的 max_steps 或复杂的池可能导致耗时较长。降低 max_steps,增加 plan_horizon_chunks,或增加 spacing。
- 日志刷屏
设置
debug_logs = false(默认值)。
路线图
- 单结构放置节流。
- 游戏内规划单元格的可视化。
- 集成到
/locate structure 下。
Async Structure Generator (Astruct)
Astruct lets you generate massive jigsaw-based structures without freezing the server.
It plans structures off-thread, queues placements, and only builds blocks once the required chunks are loaded.
In practice, very large structures may “stream in” over a few seconds—especially after teleporting—since planning can take time. In survival, this is usually unnoticeable when plan_horizon_chunks is set high enough.
Why use Astruct?
- Way beyond vanilla limits – plan thousands of jigsaw pieces safely.
- Off-thread planning – heavy jigsaw expansion runs outside the main thread, avoiding TPS spikes.
- Datapack-driven – ship content via JSON; no code required.
How it works (short version)
- Centers – The world is partitioned into “cells” (
spacing). Each cell gets a deterministic, seed-based center per structure ID.
- Proximity scan – As players roam, Astruct pre-plans cells well ahead of them.
- Async expansion – Jigsaw expansion runs off-thread.
- Placement queue – Finished plans enqueue pieces, keyed by the chunks they need.
- Chunk-safe build – On chunk load (and periodic sweeps), Astruct places only pieces whose chunks are currently loaded.
JSON definition (datapack)
Place JSON files at:
data/<namespace>/worldgen/async_structure/<id>.json
Example
{
"id": "example:castle",
"dimension": "minecraft:the_nether",
"start_pool": "castle:start",
"fallback_pool": "castle:caps",
"soft_radius_chunks": 16,
"plan_horizon_chunks": 160,
"budgets": {
"max_steps": 30,
"max_open_connectors": 128
},
"gen_y": { "mode": "surface", "value": 0 },
"spacing": 2048
}
Field reference
-
id
Unique structure ID (should match the file path key).
-
dimension
Target dimension key (e.g. minecraft:the_nether).
-
start_pool
Template pool to start expansion from.
-
fallback_pool
Pool used to cap dead-ends (end pieces).
-
soft_radius_chunks
Max distance budget (in chunks) from the center during expansion.
-
plan_horizon_chunks
How far ahead (in chunks) the planner prepares around players.
-
budgets.max_steps
Upper bound on jigsaw pieces per plan.
-
budgets.max_open_connectors
Safety limit for outstanding connectors.
-
gen_y
Controls how the final Y coordinate is chosen.
Y is resolved late, at the final structure position.
Supported modes:
-
"fixed"
Always use value as the Y level.
-
"min_plus"
min_build_height + value.
-
"world_y"
World sea level.
-
"surface"
Terrain surface at the structure’s X/Z position
(plus optional offset via value).
Example:
"gen_y": { "mode": "surface", "value": 0 }
-
spacing
Cell size in blocks (effective density control).
Field reference
id – Unique structure ID (should match the file path key).
dimension – Target dimension key (e.g. minecraft:the_nether).
start_pool – Template pool to start expansion from.
fallback_pool – Pool used to cap dead-ends (end pieces).
soft_radius_chunks – Max distance budget (in chunks) from the center during expansion.
plan_horizon_chunks – How far ahead (in chunks) the planner prepares around players.
budgets.max_steps – Upper bound on jigsaw pieces per plan.
budgets.max_open_connectors – Safety limit for outstanding connectors.
gen_y.mode – "fixed" | "world_y" | "min_plus".
gen_y.value – Y or offset (depending on mode).
spacing – Cell size in blocks (effective density control).
piece_rules.deny_overlap_tile_entities – Optional safety flag to skip pieces that would overlap TEs.
Commands
Astruct plugs into the vanilla /locate root:
/locate astruct – Nearest center for any Astruct structure in this dimension.
/locate astruct <id> – Nearest center for a specific structure ID.
Config (server)
astruct-common.toml:
debug_logs (bool, default false) – Verbose diagnostics.
max_placements_per_tick (int, default 10) – Upper bound on pieces placed each tick.
Tune for your hardware/pack.
Performance notes
- Planning cost scales with
max_steps and pool complexity. Thousands of pieces may take seconds off-thread—that’s expected. Players won’t lag; placement is paced.
- Placement is chunk-paced. Pieces place only when their chunks are loaded, producing a smooth “streaming” effect as you approach.
Compatibility
- Works alongside vanilla and modded structures.
Astruct doesn’t replace vanilla generation; it adds an async planner/placer on top.
Troubleshooting
- “Unknown structure id” in commands
Check your datapack path and that
id inside JSON matches the file’s namespaced key.
- “My structure never generates” / “It takes ages”
Enable
debug_logs to see planning times. Very high max_steps or complex pools can take long. Reduce max_steps, increase plan_horizon_chunks, or increase spacing.
- Spammy logs
Set
debug_logs = false (default).
Roadmap
- Per-structure placement throttles.
- In-game visualization for planned cells.
- Integration under
/locate structure.
评论 0
登录后参与评分
还没有评论,来抢沙发吧