HOCON template substitution

HOCON supports ${name} substitution - reference a previously-defined block by name. When followed by { ... overrides ... }, the override merges on top of the substituted value. This is what makes the shared _shared/templates.conf and per-menu local templates work.

intermediate

Features: template-substitutionobject-mergeDRY-pattern

Open: /ame_snip_template Copy

menu.conf

# Snippet: HOCON template substitution + override
# Docs: https://abstractmenus.github.io/docs/en/examples/snippets/template-substitution
# Open: /ame_snip_template

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

title: "&6Template Substitution"
size: 1
activators { command: "ame_snip_template" }

# A reusable item template defined at file scope.
prizeTile {
  material: NETHER_STAR
  lore: ["&7Click for a prize."]
  click {
    actions {
      itemAdd { material: DIAMOND }
      sound: ${successSound}
    }
  }
}

items: [
  # Reference the template, override slot + name. The click block from prizeTile is preserved.
  ${prizeTile} {
    slot: 2
    name: "&aCommon Prize"
  }
  ${prizeTile} {
    slot: 4
    name: "&6Rare Prize"
  }
  ${prizeTile} {
    slot: 6
    name: "&dEpic Prize"
  }
  ${buttonClose} { slot: 8 }
]

_shared/templates.conf

# AbstractMenus example pack - shared templates
# Reusable HOCON snippets referenced from menus via ${blockName} substitution.
# Docs: https://abstractmenus.github.io/docs/en/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: "&cYou don't have enough money."
}
denyNoPerm {
  sound:   ${deniedSound}
  message: "&cYou don't have permission."
}
denyCooldown {
  sound:   ${deniedSound}
  message: "&cYou're on cooldown. Try again later."
}

# 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: "&cClose"
  click {
    closeMenu: true
  }
}
buttonBack {
  material: ARROW
  name: "&eBack"
  lore: ["&7Return to previous menu"]
  click {
    closeMenu: true
  }
}
buttonNext {
  material: ARROW
  name: "&eNext page"
  click {
    pageNext: 1
  }
}
buttonPrev {
  material: ARROW
  name: "&ePrevious page"
  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&lExample Menu"
  lore: ["&7Welcome to the AbstractMenus example pack"]
}

↓ menu.conf ↓ Bundle (.zip)

Bundle includes _shared/templates.conf and INSTALL.txt.

Usage

# Define once
prizeTile {
  material: NETHER_STAR
  lore: ["&7Click for a prize."]
  click { actions { itemAdd { material: DIAMOND } } }
}

# Use multiple times with overrides
items: [
  ${prizeTile} { slot: 2, name: "&aCommon Prize" }
  ${prizeTile} { slot: 4, name: "&6Rare Prize" }
  ${prizeTile} { slot: 6, name: "&dEpic Prize" }
]

Each instance starts as a copy of prizeTile (material, lore, click), then the override block adds slot and name. The result is three different items sharing structure but differing in identifying fields.

Merge semantics

${A} { B } does a deep object merge - keys from B override keys from A, but nested objects merge recursively. So if A has click.actions.sound: ${clickSound} and B has click.actions.message: "Hi", the merged result has both: click.actions.{sound: ..., message: "Hi"}.

For lists, the override REPLACES the original list - it doesn’t append. To extend a lore list:

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

The ${prizeTile.lore} substitution gets the original lore array, then [...] appends new entries. See the Daily Kit example for this pattern in action.

When to template

• Item shape repeated 3+ times: extract a template
• A click handler used in multiple items: extract clickFoo {...} and reference via click: ${clickFoo}
• Cost or price data shared between display item and rule check: define once at file scope, reference in both spots

If something is used twice and inlined still reads clearly, leave it inlined. Templates pay off when they reduce edit surface for repeated logic.