⚡ ActionService

ActionService lets addons execute EventForge actions through the same action system used by event configs without needing to duplicate action parsing or action execution.

---

Accessing ActionService

ActionService actionService = EventForgeAPI.getActionService();

Make sure the API is available first:

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

---

What it is used for

Use ActionService when your addon has its own system that needs to run EventForge actions.

Common uses:

custom objectives
custom region systems
custom minigames
custom reward moments
custom addon milestones
custom interaction logic

For example, a custom objective may load an actions: section from config and run those actions when a player completes something.

---

Supported action types

ActionService can execute normal EventForge action types.

MESSAGE
BROADCAST
TITLE
ACTIONBAR
ANIMATED_TITLE
ANIMATED_ACTIONBAR
SOUND
COMMAND
EFFECT
PARTICLE
FIREWORK
WEBHOOK

It can also execute custom action types registered through ActionRegistry.

---

Basic usage

EventForgeAPI.getActionService().executeAll(
        eventId,
        player,
        actions,
        placeholders
);

Arguments:

Argument	Description
eventId	Event ID the actions belong to
player	Player context, if available
actions	List of EventAction objects
placeholders	Extra placeholders for the action run

---

Example

Map<String, String> placeholders = new HashMap<>();
placeholders.put("relic", "ancient_relic");
placeholders.put("relic_display", "Ancient Relic");
placeholders.put("score_change", "10");

EventForgeAPI.getActionService().executeAll(
        "relic_hunt",
        player,
        actions,
        placeholders
);

This lets the configured actions use placeholders such as:

{relic}
{relic_display}
{score_change}

---

Loading actions from a custom objective

Custom objective handlers can load actions through the objective load context.

List<EventAction> actions = context.loadActions("rewards.actions");

Then later run them:

EventForgeAPI.getActionService().executeAll(
        session.getEventId(),
        player,
        actions,
        placeholders
);

This keeps custom objectives consistent with normal EventForge action config.

---

Player context

Some actions need a player.

Examples:

MESSAGE
TITLE
ACTIONBAR
ANIMATED_TITLE
ANIMATED_ACTIONBAR
SOUND
EFFECT
PARTICLE
FIREWORK

If your action moment is player-specific, pass the player.

EventForgeAPI.getActionService().executeAll(
        eventId,
        player,
        actions,
        placeholders
);

If the action moment is not player-specific, pass null.

EventForgeAPI.getActionService().executeAll(
        eventId,
        null,
        actions,
        placeholders
);

Actions that require a player may do nothing if no player is available.

---

Placeholders

ActionService uses normal EventForge placeholder parsing and your extra placeholder map.

Example placeholders:

Map<String, String> placeholders = new HashMap<>();
placeholders.put("zone", "blue_zone");
placeholders.put("zone_display", "Blue Zone");
placeholders.put("score_change", "5");

Config example:

actions:
  - type: MESSAGE
    message: "&aYou captured &f{zone_display}&a! &7(+{score_change})"

---

Text effects

Actions executed through ActionService can use EventForge text effects.

actions:
  - type: MESSAGE
    message: "<pulse:#22d3ed:#ffffff>Zone captured:</pulse> &f{zone_display}"

This uses the same text effect system as normal EventForge event files.

---

Null safety

ActionService is designed to safely ignore empty action lists.

Still, your addon should avoid passing bad data where possible.

Good checks:

if (actions == null || actions.isEmpty()) {
    return;
}

Also make sure your event ID is not blank:

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

---

When not to use ActionService

Do not use ActionService for very simple hardcoded addon behaviour.

For example, this does not need ActionService:

player.sendMessage("Hello!");

Use ActionService when the behaviour should be configurable by server owners.

---

Related API

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

---

Summary

Use ActionService when your addon wants to run EventForge-style actions from its own config or custom objective.

It keeps addon behaviour consistent with normal EventForge event files and avoids duplicating EventForge action logic.