Astruct

Async Structure Generator (Astruct)

Astruct позволяет генерировать огромные структуры на основе jigsaw без зависания сервера. Он планирует структуры вне основного потока, ставит размещения в очередь и строит блоки только после загрузки нужных чанков.

На практике очень большие структуры могут «подгружаться» в течение нескольких секунд — особенно после телепортации — так как планирование может занять время. В выживании это обычно незаметно, если plan_horizon_chunks установлен достаточно высоко.

Зачем использовать Astruct?

• Гораздо дальше ванильных лимитов – безопасно планируйте тысячи jigsaw-элементов.
• Планирование вне потока – тяжёлое расширение jigsaw выполняется вне основного потока, избегая скачков TPS.
• Управляется датапаком – поставляйте контент через JSON; код не требуется.

Как это работает (кратко)

1. Центры – Мир разбивается на «ячейки» (spacing). Каждая ячейка получает детерминированный центр на основе сида для каждого ID структуры.
2. Сканирование близости – Пока игроки перемещаются, Astruct заранее планирует ячейки далеко впереди них.
3. Асинхронное расширение – Расширение jigsaw выполняется вне потока.
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
  Верхняя граница количества jigsaw-элементов на план.

• 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 – Верхняя граница количества jigsaw-элементов на план.
• 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.

Конфиг (сервер)

astruct-common.toml:

• debug_logs (bool, по умолчанию false) – Подробная диагностика.
• max_placements_per_tick (int, по умолчанию 10) – Верхний предел количества частей, размещаемых за тик. Настройте под своё железо/сборку.

Заметки о производительности

• Стоимость планирования зависит от max_steps и сложности пула. Тысячи частей могут занять несколько секунд вне основного потока — это ожидаемо. У игроков лагов не будет; размещение идёт размеренно.
• Размещение привязано к чанкам. Части размещаются только когда их чанки загружены, создавая плавный эффект «подгрузки» по мере приближения.

Совместимость

• Работает вместе с ванильными и модовыми структурами. Astruct не заменяет ванильную генерацию; он добавляет асинхронный планировщик/разместитель поверх неё.

Решение проблем

• «Unknown structure id» в командах Проверьте путь к датапаку и что id внутри JSON совпадает с namespaced-ключом файла.
• «Моя структура никогда не генерируется» / «Это занимает вечность» Включите debug_logs, чтобы увидеть время планирования. Очень высокий max_steps или сложные пулы могут занимать долго. Уменьшите max_steps, увеличьте plan_horizon_chunks или увеличьте spacing.
• Спам в логах Установите debug_logs = false (по умолчанию).

Планы

• Ограничения размещения для каждой структуры.
• Визуализация запланированных ячеек в игре.
• Интеграция в /locate structure.