🧾 EventObjectiveSession API

EventObjectiveSession gives custom objectives access to the running EventForge event.

Use it to award score, read event state, check participants, and access leaderboard data.

---

What it is used for

Custom objectives use the session to:

award score
read player score
read event ID
read objective display name
read objective weight
check participant count
read elapsed time
read leaderboard entries

---

Awarding score

Use:

session.addScore(player, points);

Example:

session.addScore(player, 5);

EventForge handles:

score updates
leaderboard updates
PlaceholderAPI updates
score change Bukkit events
milestone checks
reward eligibility

---

Reading player score

int score = session.getScore(player);

Example:

player.sendMessage("Your score is " + session.getScore(player));

---

Event ID

String eventId = session.getEventId();

Use this when parsing variables or running EventForge actions.

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

---

Objective display name

String displayName = session.getObjectiveDisplayName();

This is useful for messages or logs.

---

Objective weight

double weight = session.getObjectiveWeight();

Objective weight is used when an event has multiple objectives.

Example:

objectives:
  relics:
    type: RELIC_HUNT
    weight: 2.0

Your objective can show this if needed, but EventForge handles weighted scoring internally.

---

Participant count

int participantCount = session.getParticipantCount();

Use this for messages, debug logs, or objective-specific logic.

---

Elapsed time

long elapsedSeconds = session.getElapsedSeconds();

This can be used for timed objective logic.

Example:

if (session.getElapsedSeconds() > 60) {
    // Objective has been running for more than 1 minute.
}

---

Leaderboard

You can read leaderboard entries from the session.

List<EventLeaderboardEntry> leaderboard = session.getLeaderboard();

Example:

for (EventLeaderboardEntry entry : session.getLeaderboard()) {
    String playerName = entry.getPlayerName();
    int score = entry.getScore();
    int rank = entry.getRank();
}

---

Using with ActionService

Custom objectives can use the session event ID when running actions.

Map<String, String> placeholders = new HashMap<>();
placeholders.put("score_change", "5");

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

---

Using with VariableService

String message = "{var:event_color}{event_display} &7custom objective message.";

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

---

Using with TextEffectService

String styled = EventForgeAPI.getTextEffectService().parse(
        "<gradient:#22d3ed:#ffffff>Objective Complete</gradient>"
);

For animated text, pass a tick value:

int animationTick = (int) Math.floorMod(session.getElapsedSeconds() * 20L, Integer.MAX_VALUE);

String styled = EventForgeAPI.getTextEffectService().parse(
        "<stack:rainbow,wobble>Objective Complete</stack>",
        animationTick
);

---

Null safety

EventObjectiveSession is only provided while an objective is running.

Do not store a session forever.

If you keep references for runtime logic, clear them when the event stops.

---

Cleanup on stop

Use your objective handler's stop method to clear runtime data.

@Override
public void onStop(EventObjectiveSession session, RelicHuntObjectiveData data) {
    discoveredPlayers.remove(session.getEventId());
    cooldowns.remove(session.getEventId());
}

---

Summary

Use EventObjectiveSession as the bridge between your custom objective and the active EventForge event.

Most custom objectives will use it for:

adding score
reading score
reading event ID
running actions
parsing variables
tracking runtime state
cleaning up on stop