⏰ ScheduledVoteService API

ScheduledVoteService is the public read-only API for EventForge's scheduled voting system.

Use it to read scheduled votes loaded from schedule_config.yml, check when the next vote starts and build dashboards, menus, scoreboards or Discord announcements.

Scheduled voting is runtime-managed by EventForge. The public API exposes snapshots only.

---

Getting the service

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

ScheduledVoteService scheduledVoteService = EventForgeAPI.getScheduledVoteService();

---

Check if scheduled voting is enabled

boolean enabled = scheduledVoteService.isScheduledVotingEnabled();

This reads the global scheduled voting setting from schedule_config.yml.

---

Get all scheduled votes

Set<ScheduledVoteInfo> votes = scheduledVoteService.getScheduledVotes();

The returned set contains immutable scheduled vote snapshots.

---

Get a scheduled vote by ID

scheduledVoteService.getScheduledVote("hourly_vote")
        .ifPresent(vote -> {
            String id = vote.getId();
            long seconds = vote.getSecondsUntilNextStart();
        });

IDs are normalized to lowercase.

---

Get the next scheduled vote

scheduledVoteService.getNextScheduledVote().ifPresent(next -> {
    String id = next.getId();
    long seconds = next.getSecondsUntilNextStart();
});

This is useful for scoreboards, menus and Discord status messages.

---

Get upcoming scheduled votes

List<ScheduledVoteInfo> upcoming = scheduledVoteService.getUpcomingScheduledVotes(5);

The list is ordered by soonest start time.

---

Get scheduled vote count

int count = scheduledVoteService.getScheduledVoteCount();

---

Get seconds until a specific vote

Optional<Long> seconds = scheduledVoteService.getSecondsUntilNextVote("hourly_vote");

This returns Optional.empty() if the scheduled vote does not exist.

---

ScheduledVoteInfo methods

Useful methods:

vote.getId();
vote.isEnabled();
vote.getType();
vote.getEverySeconds();
vote.getDurationSeconds();
vote.getNextStartEpochSecond();
vote.getSecondsUntilNextStart();
vote.getOptionIds();
vote.isRandomizeOptions();
vote.getRandomizeAmount();
vote.getAnnounceBeforeSeconds();
vote.isStartWinnerAutomatically();
vote.isRequireNoActiveEvents();
vote.isRequireNoActiveVote();

---

Example dashboard output

ScheduledVoteService service = EventForgeAPI.getScheduledVoteService();

service.getUpcomingScheduledVotes(3).forEach(vote -> {
    getLogger().info(
            vote.getId()
                    + " starts in "
                    + vote.getSecondsUntilNextStart()
                    + "s with options "
                    + vote.getOptionIds()
    );
});

---

Manual queue integration

Scheduled voting uses the same winner start flow as manual voting.

If the winning event uses:

participation:
  mode: MANUAL

then the scheduled vote winner opens a manual queue instead of starting instantly.

Your addon can listen for queue events or read EventQueueService if it needs to react to that queue.

---

Read-only design

ScheduledVoteService is intentionally read-only.

It does not expose:

ScheduledVote
ScheduledVoteConfig
internal runtime tasks
mutable scheduled vote maps

This keeps scheduled voting safe while still giving addons useful information.

For scheduled vote start/skip events, see the Bukkit Events page.