🧩 Event Variables

Event variables let you define reusable values inside an event file.

They are useful for colours, arena names, reward names, NPC names, webhook text, and repeated phrases.

tip

Use variables when you want cleaner event files and easier editing later.

---

Basic example

Add a variables: section near the top of your event file:

variables:
  event_color: "&b"
  arena_name: "Spawn Mine"
  reward_name: "Emerald Reward"

Use variables with:

{var:key}

Example:

display-name: "{var:event_color}Mining Rush"

messages:
  start:
    - "{var:event_color}&lMining Rush has started!"
    - "&7Mine blocks in &f{var:arena_name}&7."

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "give {player} emerald 1"
      - "say {player} earned {var:reward_name}!"

---

Where variables can be used

Variables can be used in most EventForge text.

Common places:

display names
messages
titles
actionbars
bossbars
sidebars
reward commands
trigger actions
milestone actions
dialogues
webhooks
addon actions that use EventForge parsing

Example:

bossbar:
  enabled: true
  text: "{var:event_color}{event_display} &8| &f{time_left} &8| &eScore: {score}"

---

Variable keys

Variable keys are normalised by EventForge.

This means:

arena-name
arena_name

are treated as the same key.

For consistency, use lowercase keys with underscores.

Good:

variables:
  event_color: "&b"
  arena_name: "Spawn Mine"
  reward_name: "Emerald Reward"

Avoid mixing styles:

variables:
  EventColor: "&b"
  arena-name: "Spawn Mine"
  Reward Name: "Emerald Reward"

---

Simple values

Variables should be simple values.

Good:

variables:
  event_color: "&b"
  arena_name: "Spawn Mine"
  reward_item: "Emerald"

Avoid using large YAML sections inside variables.

Variables are designed for reusable text values, not full config blocks.

---

Variables with text effects

Variables can be used inside text effects.

variables:
  event_name: "Mining Rush"

triggers:
  event-start:
    actions:
      - type: BROADCAST
        message: "<gradient:#22d3ed:#ffffff>{var:event_name}</gradient> &7has started!"

You can also store colour codes in variables:

variables:
  event_color: "&b"

messages:
  start:
    - "{var:event_color}&l{event_display} &7has started!"

---

Variables with placeholders

Variables can be used alongside normal placeholders.

variables:
  arena_name: "Spawn Mine"

triggers:
  event-start:
    actions:
      - type: BROADCAST
        message: "&7{event_display} started at &f{var:arena_name}&7!"

Common placeholders used near variables:

{event_display}
{player}
{time_left}
{score}
{rank}
{score_change}
{new_score}
{milestone_display}

---

Variables in rewards

Variables can be used in reward commands.

variables:
  reward_message: "Thanks for playing!"

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "give {player} emerald 1"
      - "msg {player} {var:reward_message}"

info

Commands are run by console, so make sure the final command is valid for your server.

---

Variables in milestones

Milestone actions can use variables too.

variables:
  milestone_color: "&e"

milestones:
  enabled: true
  thresholds:
    50:
      display-name: "{var:milestone_color}50 Points"
      once-per-player: true
      actions:
        - type: MESSAGE
          message: "{var:milestone_color}You reached &f{milestone_display}&e!"

---

Variables in dialogues

Dialogues can use variables for repeated names, colours, or locations.

variables:
  npc_name: "Guide"
  event_color: "&b"

dialogues:
  intro:
    display-name: "Intro"
    lines:
      - "{var:event_color}{var:npc_name}: &fWelcome to {event_display}."
      - "&7Score points before the timer ends."

---

Missing variables

If a variable does not exist, EventForge leaves the text safely handled instead of crashing the event.

Example:

{var:missing_key}

If you see a missing variable in-game, check the event file and make sure the key exists under:

variables:

---

API access

Addon developers can parse variables through the public API:

EventForgeAPI.getVariableService().parse(eventId, text);
EventForgeAPI.getVariableService().parse(eventId, player, text);

This lets addons use the same variable system as normal event configs.

---

Summary

Variables keep event files easier to manage.

Use them for:

colours
arena names
reward names
NPC names
repeated messages
theme text

Then reuse them with:

{var:key}