Подстановка шаблона HOCON

HOCON поддерживает подстановку ${name} - ссылку на ранее определённый блок по имени. Если за ней идёт { ... переопределения ... }, переопределение мержится поверх подставленного значения. Именно за счёт этого работают общий _shared/templates.conf и локальные шаблоны в каждом меню.

menu.conf
_shared/templates.conf

# Сниппет: подстановка шаблона HOCON + переопределение
# Документация: https://abstractmenus.github.io/docs/ru/examples/snippets/template-substitution
# Открыть: /ame_snip_template

include required(file("./plugins/AbstractMenus/menus/example/_shared/templates.conf"))

title: "&6Подстановка шаблона"
size: 1
activators { command: "ame_snip_template" }

# Переиспользуемый шаблон предмета, определённый на уровне файла.
prizeTile {
  material: NETHER_STAR
  lore: ["&7Кликните за призом."]
  click {
    actions {
      itemAdd { material: DIAMOND }
      sound: ${successSound}
    }
  }
}

items: [
  # Ссылаемся на шаблон, переопределяем slot + name. Блок click из prizeTile сохраняется.
  ${prizeTile} {
    slot: 2
    name: "&aОбычный приз"
  }
  ${prizeTile} {
    slot: 4
    name: "&6Редкий приз"
  }
  ${prizeTile} {
    slot: 6
    name: "&dЭпический приз"
  }
  ${buttonClose} { slot: 8 }
]

# AbstractMenus example pack - shared templates (RU)
# Reusable HOCON snippets referenced from menus via ${blockName} substitution.
# Docs: https://abstractmenus.github.io/docs/ru/examples

# Sound presets (Paper 1.21+ registry keys)
clickSound:    "ui.button.click"
openSound:     "block.chest.open"
closeSound:    "block.chest.close"
successSound:  "entity.experience_orb.pickup"
failSound:     "block.note_block.bass"
deniedSound:   "block.anvil.land"

# Deny action snippets (use as: denyActions: ${denyNoMoney})
denyNoMoney {
  sound:   ${deniedSound}
  message: "&cУ вас недостаточно денег."
}
denyNoPerm {
  sound:   ${deniedSound}
  message: "&cНет прав."
}
denyCooldown {
  sound:   ${deniedSound}
  message: "&cВы на кулдауне. Попробуйте позже."
}

# Border items (use as: ${borderBlack} { slot: "0-8" })
borderBlack {
  material: BLACK_STAINED_GLASS_PANE
  name: " "
}
borderGray {
  material: GRAY_STAINED_GLASS_PANE
  name: " "
}
borderBlue {
  material: BLUE_STAINED_GLASS_PANE
  name: " "
}

# Navigation buttons (use as: ${buttonClose} { slot: 22 })
buttonClose {
  material: BARRIER
  name: "&cЗакрыть"
  click {
    closeMenu: true
  }
}
buttonBack {
  material: ARROW
  name: "&eНазад"
  lore: ["&7Вернуться в предыдущее меню"]
  click {
    closeMenu: true
  }
}
buttonNext {
  material: ARROW
  name: "&eСледующая страница"
  click {
    pageNext: 1
  }
}
buttonPrev {
  material: ARROW
  name: "&eПредыдущая страница"
  click {
    pagePrev: 1
  }
}

# Rule shortcut snippets (use as: rules: ${rulesAdmin})
rulesAdmin   { permission: "abstractmenus.admin" }
rulesVip     { permission: "abstractmenus.vip" }
rulesDonator { permission: "abstractmenus.donator" }

# Common decorative header (use as: ${commonHeader} { slot: 4 })
commonHeader {
  material: NETHER_STAR
  name: "&6&lМеню примера"
  lore: ["&7Добро пожаловать в пак примеров AbstractMenus"]
}

↓ menu.conf

Бандл включает _shared/templates.conf и INSTALL.txt.

Как использовать

# Описать один раз
prizeTile {
  material: NETHER_STAR
  lore: ["&7Click for a prize."]
  click { actions { itemAdd { material: DIAMOND } } }
}

# Использовать много раз с переопределениями
items: [
  ${prizeTile} { slot: 2, name: "&aCommon Prize" }
  ${prizeTile} { slot: 4, name: "&6Rare Prize" }
  ${prizeTile} { slot: 6, name: "&dEpic Prize" }
]

Каждый экземпляр стартует как копия prizeTile (material, lore, click), затем блок переопределения добавляет slot и name. На выходе три разных предмета с общей структурой, отличающиеся только идентифицирующими полями.

Семантика мержа

${A} { B } делает глубокий мерж объектов - ключи из B перебивают ключи из A, но вложенные объекты мержатся рекурсивно. Если у A есть click.actions.sound: ${clickSound}, а у B есть click.actions.message: "Hi", в результате будет и то и другое: click.actions.{sound: ..., message: "Hi"}.

Для списков переопределение ЗАМЕНЯЕТ исходный список - не добавляет в конец. Чтобы расширить список lore:

${prizeTile} {
  lore: ${prizeTile.lore} [ "&7Extra line" ]
}

Подстановка ${prizeTile.lore} подтягивает исходный массив lore, а [...] добавляет к нему новые записи. Этот паттерн в действии смотрите в примере Daily Kit.

Когда выносить в шаблон

Форма предмета повторяется 3+ раза - выносите в шаблон
Один обработчик клика используется в нескольких предметах - вынесите clickFoo {...} и подставляйте через click: ${clickFoo}
Стоимость или цена общая для отображаемого предмета и проверки правила - опишите один раз на уровне файла, ссылайтесь в обоих местах

Если что-то используется дважды и встроенный код по-прежнему читается понятно, оставьте как есть. Шаблоны окупаются, когда они уменьшают площадь правок при изменении повторяющейся логики.