🧩 VariableService

VariableService lets addons parse EventForge variables and placeholders through the public API.

This was added in EventForge v1.0.2 so addons do not need to duplicate EventForge variable parsing.

---

Accessing VariableService

VariableService variableService = EventForgeAPI.getVariableService();

Check that the API is available first:

if (!EventForgeAPI.isAvailable()) {
    return;
}

---

What it parses

VariableService can parse EventForge event variables such as:

{var:event_color}
{var:arena_name}
{var:reward_name}

It can also parse normal EventForge placeholders when an event or player context is available.

---

Basic usage

String parsed = EventForgeAPI.getVariableService().parse(
        "mining_rush",
        "{var:event_color}{event_display}"
);

If mining_rush has this config:

variables:
  event_color: "&b"

Then the text will be parsed using that event's variables.

---

Player-aware parsing

Use the player-aware method when the text needs player placeholders.

String parsed = EventForgeAPI.getVariableService().parse(
        "mining_rush",
        player,
        "Hello {player}, your score is {score}."
);

This is useful for:

player messages
score feedback
custom objectives
custom actions
addon menus

---

Example addon message

public void sendEventMessage(Player player, String eventId) {
    String message = "{var:event_color}{event_display} &7is active!";

    String parsed = EventForgeAPI.getVariableService().parse(
            eventId,
            player,
            message
    );

    player.sendMessage(parsed);
}

---

Using with TextEffectService

You can parse variables first, then parse text effects.

String text = "<gradient:#22d3ed:#ffffff>{event_display}</gradient>";

String parsedVariables = EventForgeAPI.getVariableService().parse(
        eventId,
        player,
        text
);

String finalText = EventForgeAPI.getTextEffectService().parse(parsedVariables);

player.sendMessage(finalText);

This is useful when your addon supports both variables and text effects.

---

Using with ActionService

If your addon executes EventForge actions, ActionService already handles normal parsing for those actions.

Use VariableService directly when your addon is sending its own messages outside of the action system.

---

Missing variables

If a variable is missing, EventForge handles it safely.

Still, your addon should avoid relying on variables that may not exist unless the server owner has configured them.

Example:

String text = "{var:missing_key}Hello";
String parsed = EventForgeAPI.getVariableService().parse(eventId, text);

---

Null safety

Your addon should still check basic values before parsing.

if (eventId == null || eventId.isBlank()) {
    return;
}

if (text == null || text.isBlank()) {
    return;
}

---

Common uses

Use VariableService for:

custom objective messages
custom action messages
addon command output
addon GUI text
addon score feedback
external integration messages

---

Related API

EventForgeAPI.getVariableService();
EventForgeAPI.getTextEffectService();
EventForgeAPI.getActionService();

---

Summary

Use VariableService when your addon needs to parse EventForge variables from an event file.

It keeps addon messages consistent with normal EventForge event configs.