Astruct

Astruct

异步结构生成器:使用离线程规划来构建远超原版限制的拼图结构,以减少服务器卡顿。

优化

异步结构生成器 (Astruct)

Astruct 让你能够生成超大的拼图式结构,而不会导致服务器卡顿。 它在线程外规划结构、将放置任务加入队列,并且只在所需区块加载完成后才放置方块。

实际上,非常大的结构可能会在几秒钟内“逐步流入”——尤其是在传送之后——因为规划需要时间。在生存模式中,只要 plan_horizon_chunks 设置得足够高,这通常不会被察觉。


为什么使用 Astruct?

  • 远超原版限制 – 安全地规划数千个拼图块。
  • 线程外规划 – 繁重的拼图扩展在主线程之外运行,避免 TPS 峰值。
  • 数据包驱动 – 通过 JSON 发布内容;无需编写代码。

工作原理(简述)

  1. 中心点 – 世界被划分为“单元格”(spacing)。每个单元格会按结构 ID 获得一个确定性的、基于种子的中心点。
  2. 邻近扫描 – 当玩家四处移动时,Astruct 会提前规划远在玩家前方的单元格。
  3. 异步扩展 – 拼图扩展在线程外运行。
  4. 放置队列 – 规划完成后,拼图块按所需区块加入队列。
  5. 区块安全建造 – 在区块加载时(以及周期性扫描时),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) – 每 tick 放置拼图块的数量上限。 根据你的硬件/整合包进行调整。

性能说明

  • 规划成本随 max_steps 和模板池复杂度增长。数千个拼图块在线程外可能需要几秒钟——这是预期行为。玩家不会卡顿;放置是分流的。
  • 放置按区块节奏进行。 拼图块仅在其区块加载时放置,随着你接近会产生平滑的“流式”效果。

兼容性

  • 与原版和模组结构共存。 Astruct 不会替换原版生成;它在其之上添加了一个异步规划器/放置器。

故障排除

  • 命令中出现“Unknown structure id” 检查你的数据包路径,以及 JSON 中的 id 是否与文件的命名空间键匹配。
  • “我的结构从不生成”/“它要花很久” 启用 debug_logs 以查看规划时间。非常高的 max_steps 或复杂的模板池可能需要很长时间。降低 max_steps、增加 plan_horizon_chunks 或增加 spacing。
  • 日志刷屏 设置 debug_logs = false(默认)。

路线图

  • 按结构放置节流。
  • 已规划单元格的游戏内可视化。
  • 集成到 /locate structure 下。