Skip to main content

⏰ ScheduleService

ScheduleService lets addons read EventForge schedule information.

Use it for:

scoreboards
custom GUIs
Discord bots
admin dashboards
NPC menus
PlaceholderAPI-style integrations
event browser menus

Getting the service

ScheduleService scheduleService = EventForgeAPI.getScheduleService();

Always check the API is available first:

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

Scheduled event count

int count = scheduleService.getScheduledEventCount();

Example:

getLogger().info("Scheduled events: " + scheduleService.getScheduledEventCount());

Scheduled event IDs

Set<String> ids = scheduleService.getScheduledEventIds();

Example:

for (String eventId : scheduleService.getScheduledEventIds()) {
    getLogger().info("Scheduled: " + eventId);
}

Scheduled events

Set<ScheduledEventInfo> scheduledEvents = scheduleService.getScheduledEvents();

Example:

for (ScheduledEventInfo schedule : scheduleService.getScheduledEvents()) {
    String eventId = schedule.getEventId();
    long seconds = schedule.getSecondsUntilNextStart();

    getLogger().info(eventId + " starts in " + seconds + " seconds.");
}

Get a specific schedule

Optional<ScheduledEventInfo> schedule = scheduleService.getScheduledEvent("mining_rush");

Example:

scheduleService.getScheduledEvent("mining_rush").ifPresent(schedule -> {
    long seconds = schedule.getSecondsUntilNextStart();
    getLogger().info("Mining Rush starts in " + seconds + " seconds.");
});

Check if an event is scheduled

boolean scheduled = scheduleService.isScheduled("mining_rush");

Next scheduled event

Optional<ScheduledEventInfo> next = scheduleService.getNextScheduledEvent();

Example:

scheduleService.getNextScheduledEvent().ifPresent(next -> {
    String eventId = next.getEventId();
    long seconds = next.getSecondsUntilNextStart();

    Bukkit.broadcastMessage("Next event: " + eventId + " in " + seconds + " seconds.");
});

Upcoming events

v1.0.1 added getUpcomingEvents(int limit).

List<ScheduledEventInfo> upcoming = scheduleService.getUpcomingEvents(5);

This returns upcoming scheduled events ordered by next start time.

Example:

List<ScheduledEventInfo> upcoming = scheduleService.getUpcomingEvents(3);

for (ScheduledEventInfo schedule : upcoming) {
    getLogger().info(schedule.getEventId()
            + " starts in "
            + schedule.getSecondsUntilNextStart()
            + " seconds.");
}

Use this for:

upcoming event menus
Discord /events commands
scoreboard rotations
NPC event boards
web dashboards

Next start time

Get the next start epoch second:

long epochSecond = scheduleService
        .getNextStartEpochSecond("mining_rush")
        .orElse(0L);

Get seconds until next start:

long seconds = scheduleService
        .getSecondsUntilNextStart("mining_rush")
        .orElse(0L);

ScheduledEventInfo

ScheduledEventInfo contains public schedule information.

Common methods include:

getEventId();
getScheduleType();
getEverySeconds();
getNextStartEpochSecond();
getSecondsUntilNextStart();

Example:

scheduleService.getScheduledEvent("mining_rush").ifPresent(schedule -> {
    String eventId = schedule.getEventId();
    String type = schedule.getScheduleType();
    long every = schedule.getEverySeconds();
    long nextStart = schedule.getNextStartEpochSecond();
    long secondsUntil = schedule.getSecondsUntilNextStart();
});

Example: simple upcoming event command

public void sendUpcoming(CommandSender sender) {
    List<ScheduledEventInfo> upcoming = EventForgeAPI
            .getScheduleService()
            .getUpcomingEvents(5);

    if (upcoming.isEmpty()) {
        sender.sendMessage("No upcoming events.");
        return;
    }

    sender.sendMessage("Upcoming events:");

    for (ScheduledEventInfo schedule : upcoming) {
        sender.sendMessage("- "
                + schedule.getEventId()
                + " in "
                + schedule.getSecondsUntilNextStart()
                + " seconds");
    }
}

Example: next event scoreboard line

String nextLine = EventForgeAPI.getScheduleService()
        .getNextScheduledEvent()
        .map(schedule -> schedule.getEventId()
                + " in "
                + schedule.getSecondsUntilNextStart()
                + "s")
        .orElse("No events scheduled");

Cooldowns and schedules

Schedules respect event cooldowns.

This means a scheduled event may not start if it is currently on cooldown.

To check cooldown state, use EventService:

EventService eventService = EventForgeAPI.getEventService();

boolean onCooldown = eventService.isEventOnCooldown("relic_hunt");

long remaining = eventService
        .getEventCooldownRemainingSeconds("relic_hunt")
        .orElse(0L);

Common mistakes

Assuming scheduled means startable​

An event can be scheduled but still unable to start because of:

cooldown
minimum players
world conditions
time conditions
weather conditions
already active

Use EventService#getStartCheckResult(eventId) when you need to show whether it can actually start.

Showing only one upcoming event​

For richer menus, use:

getUpcomingEvents(5);

instead of only:

getNextScheduledEvent();

Ignoring empty optionals​

Many schedule methods return Optional.

Always handle the empty case:

long seconds = scheduleService
        .getSecondsUntilNextStart("mining_rush")
        .orElse(0L);