🔌 PlaceholderAPI
EventForge supports PlaceholderAPI placeholders for events, schedules, player stats, regions, voting, scheduled voting and manual event queues.
Use them in plugins such as:
scoreboards
TAB
chat formats
menus
holograms
leaderboards
server info displays
PlaceholderAPI is optional. You only need it if you want to show EventForge data in other plugins.
Requirements
You need:
PlaceholderAPI
EventForge
After installing PlaceholderAPI, restart your server.
Test a placeholder
Use PlaceholderAPI's parse command:
/papi parse me %eventforge_version%
If EventForge is loaded correctly, it should return the EventForge plugin version.
For player-specific placeholders, test as an online player instead of console where possible.
General placeholders
%eventforge_version%
%eventforge_api_version%
%eventforge_loaded_count%
%eventforge_active_count%
%eventforge_active_names%
%eventforge_scheduled_count%
| Placeholder | Description |
|---|---|
%eventforge_version% | EventForge plugin version |
%eventforge_api_version% | EventForge API version |
%eventforge_loaded_count% | Number of loaded events |
%eventforge_active_count% | Number of active events |
%eventforge_active_names% | Active event display names |
%eventforge_scheduled_count% | Number of normal scheduled events |
Next scheduled event
These placeholders show the next normal scheduled event from EventForge's event schedule system.
%eventforge_next_event%
%eventforge_next_event_id%
%eventforge_next_event_display%
%eventforge_next_event_time%
%eventforge_next_scheduled_event%
%eventforge_next_scheduled_time%
| Placeholder | Description |
|---|---|
%eventforge_next_event% | Display name of the next scheduled event |
%eventforge_next_event_id% | ID of the next scheduled event |
%eventforge_next_event_display% | Display name of the next scheduled event |
%eventforge_next_event_time% | Time until the next scheduled event starts |
%eventforge_next_scheduled_event% | ID of the next scheduled event |
%eventforge_next_scheduled_time% | Time until the next scheduled event starts |
Player stat placeholders
These placeholders need a player context.
%eventforge_player_total_score%
%eventforge_player_events_played%
%eventforge_player_wins%
%eventforge_player_best_score%
| Placeholder | Description |
|---|---|
%eventforge_player_total_score% | Player's total EventForge score |
%eventforge_player_events_played% | Number of EventForge events the player has played |
%eventforge_player_wins% | Number of EventForge wins |
%eventforge_player_best_score% | Player's best event score |
Event placeholders
These use the event ID inside the placeholder.
Format:
%eventforge_event_<event>_<value>%
Example:
%eventforge_event_mining_rush_active%
Available values:
active
loaded
on_cooldown
cooldown
display
time_left
elapsed
participants
scheduled
next_start
category
difficulty
author
version
tags
description
can_start
start_reason
region_count
player_score
player_rank
player_participating
Examples:
%eventforge_event_mining_rush_active%
%eventforge_event_mining_rush_loaded%
%eventforge_event_mining_rush_time_left%
%eventforge_event_mining_rush_participants%
%eventforge_event_mining_rush_player_score%
%eventforge_event_mining_rush_player_rank%
%eventforge_event_mining_rush_player_participating%
Event status placeholders
| Placeholder | Description |
|---|---|
%eventforge_event_<event>_active% | Whether the event is active |
%eventforge_event_<event>_loaded% | Whether the event is loaded |
%eventforge_event_<event>_on_cooldown% | Whether the event is on cooldown |
%eventforge_event_<event>_cooldown% | Remaining event cooldown |
%eventforge_event_<event>_can_start% | Whether the event can start |
%eventforge_event_<event>_start_reason% | Reason the event cannot start |
Event time placeholders
| Placeholder | Description |
|---|---|
%eventforge_event_<event>_time_left% | Time left for an active event |
%eventforge_event_<event>_elapsed% | Elapsed time for an active event |
%eventforge_event_<event>_scheduled% | Whether the event is scheduled |
%eventforge_event_<event>_next_start% | Time until the event's next scheduled start |
Event metadata placeholders
| Placeholder | Description |
|---|---|
%eventforge_event_<event>_display% | Event display name |
%eventforge_event_<event>_category% | Event category |
%eventforge_event_<event>_difficulty% | Event difficulty |
%eventforge_event_<event>_author% | Event author |
%eventforge_event_<event>_version% | Event version |
%eventforge_event_<event>_tags% | Event tags |
%eventforge_event_<event>_description% | Event description |
%eventforge_event_<event>_region_count% | Number of configured regions for the event |
Event player placeholders
These placeholders need a player context.
| Placeholder | Description |
|---|---|
%eventforge_event_<event>_player_score% | Player's score in the event |
%eventforge_event_<event>_player_rank% | Player's rank in the event |
%eventforge_event_<event>_player_participating% | Whether the player is participating |
Example:
%eventforge_event_mining_rush_player_score%
For manual queue events, player_participating only returns Yes for players who are actually participating in the active event.
Event variable placeholders
You can read event variables through PlaceholderAPI.
Format:
%eventforge_event_variable_<event>_<variable>%
Example:
%eventforge_event_variable_mining_rush_event_color%
If the variable exists in the event file, the placeholder returns its value.
Region placeholders
EventForge can check whether a player is inside a configured event region.
Format:
%eventforge_player_in_region_<event>_<region>%
Example:
%eventforge_player_in_region_capture_zone_blue_zone%
This returns:
Yes
No
You can also show the number of regions configured for an event:
%eventforge_event_<event>_region_count%
Example:
%eventforge_event_capture_zone_region_count%
Player event stats
These placeholders show a player's stored stats for a specific event.
Format:
%eventforge_player_event_<event>_<value>%
Available values:
played
wins
total_score
best_score
Examples:
%eventforge_player_event_mining_rush_played%
%eventforge_player_event_mining_rush_wins%
%eventforge_player_event_mining_rush_total_score%
%eventforge_player_event_mining_rush_best_score%
Leaderboard placeholders
These placeholders show current active-event leaderboard positions.
%eventforge_top_player_<event>_<position>%
%eventforge_top_score_<event>_<position>%
Examples:
%eventforge_top_player_mining_rush_1%
%eventforge_top_score_mining_rush_1%
%eventforge_top_player_mining_rush_2%
%eventforge_top_score_mining_rush_2%
If the event does not have that leaderboard position, the player placeholder returns blank and the score placeholder returns 0.
Event group count placeholders
These placeholders count events by metadata.
%eventforge_events_category_count_<category>%
%eventforge_events_tag_count_<tag>%
%eventforge_events_difficulty_count_<difficulty>%
Examples:
%eventforge_events_category_count_mining%
%eventforge_events_tag_count_survival%
%eventforge_events_difficulty_count_easy%
Vote placeholders
These placeholders show the current manual event vote.
%eventforge_vote_enabled%
%eventforge_vote_active%
%eventforge_vote_time_left%
%eventforge_vote_total_votes%
%eventforge_vote_options%
%eventforge_vote_option_ids%
%eventforge_vote_winner%
%eventforge_vote_winner_display%
%eventforge_vote_count_<event_id>%
%eventforge_vote_option_<event_id>%
| Placeholder | Description |
|---|---|
%eventforge_vote_enabled% | Whether manual voting is enabled in config.yml |
%eventforge_vote_active% | Whether a vote is currently active |
%eventforge_vote_time_left% | Time left in the active vote |
%eventforge_vote_total_votes% | Total votes cast in the active vote |
%eventforge_vote_options% | Display names of active vote options |
%eventforge_vote_option_ids% | Event IDs of active vote options |
%eventforge_vote_winner% | Current winning event ID |
%eventforge_vote_winner_display% | Current winning event display name |
%eventforge_vote_count_<event_id>% | Vote count for an event option |
%eventforge_vote_option_<event_id>% | Whether the event is an active vote option |
Examples:
%eventforge_vote_active%
%eventforge_vote_time_left%
%eventforge_vote_options%
%eventforge_vote_count_mining_rush%
%eventforge_vote_option_mob_hunt%
Voting is opt-in. Enable it in config.yml before using vote placeholders on live scoreboards or menus.
Scheduled vote placeholders
These placeholders show the scheduled voting system from schedule_config.yml.
%eventforge_scheduled_vote_enabled%
%eventforge_scheduled_vote_count%
%eventforge_next_scheduled_vote%
%eventforge_next_scheduled_vote_time_left%
%eventforge_next_scheduled_vote_options%
%eventforge_next_scheduled_vote_option_ids%
%eventforge_scheduled_vote_time_left_<id>%
%eventforge_scheduled_vote_options_<id>%
%eventforge_scheduled_vote_option_ids_<id>%
| Placeholder | Description |
|---|---|
%eventforge_scheduled_vote_enabled% | Whether scheduled voting is enabled in schedule_config.yml |
%eventforge_scheduled_vote_count% | Number of loaded scheduled votes |
%eventforge_next_scheduled_vote% | ID of the next scheduled vote |
%eventforge_next_scheduled_vote_time_left% | Time until the next scheduled vote starts |
%eventforge_next_scheduled_vote_options% | Option IDs for the next scheduled vote |
%eventforge_next_scheduled_vote_option_ids% | Option IDs for the next scheduled vote |
%eventforge_scheduled_vote_time_left_<id>% | Time until a specific scheduled vote starts |
%eventforge_scheduled_vote_options_<id>% | Option IDs for a specific scheduled vote |
%eventforge_scheduled_vote_option_ids_<id>% | Option IDs for a specific scheduled vote |
Examples:
%eventforge_next_scheduled_vote%
%eventforge_next_scheduled_vote_time_left%
%eventforge_scheduled_vote_time_left_hourly_vote%
%eventforge_scheduled_vote_options_hourly_vote%
%eventforge_scheduled_vote_option_ids_hourly_vote%
Scheduled voting is disabled by default. Enable it in schedule_config.yml and make sure each scheduled vote has at least two valid event options.
Queue placeholders
These placeholders show manual event queue information.
Global/current queue placeholders:
%eventforge_queue_active%
%eventforge_queue_event%
%eventforge_queue_event_display%
%eventforge_queue_time_left%
%eventforge_queue_players%
%eventforge_queue_min_players%
%eventforge_queue_max_players%
%eventforge_queue_joined%
| Placeholder | Description |
|---|---|
%eventforge_queue_active% | Whether any manual event queue is open |
%eventforge_queue_event% | Event ID of the first open queue |
%eventforge_queue_event_display% | Display name of the first open queue |
%eventforge_queue_time_left% | Time left for the first open queue |
%eventforge_queue_players% | Joined player count for the first open queue |
%eventforge_queue_min_players% | Minimum required players for the first open queue |
%eventforge_queue_max_players% | Maximum players for the first open queue, or ∞ if unlimited |
%eventforge_queue_joined% | Whether the parsing player has joined the first open queue |
Event-specific queue placeholders:
%eventforge_queue_<event_id>_active%
%eventforge_queue_<event_id>_time_left%
%eventforge_queue_<event_id>_players%
%eventforge_queue_<event_id>_min_players%
%eventforge_queue_<event_id>_max_players%
%eventforge_queue_<event_id>_joined%
%eventforge_queue_<event_id>_display%
%eventforge_queue_<event_id>_event_display%
Examples:
%eventforge_queue_mining_rush_active%
%eventforge_queue_mining_rush_time_left%
%eventforge_queue_mining_rush_players%
%eventforge_queue_mining_rush_joined%
%eventforge_queue_mining_rush_display%
Queue placeholders are useful for menus, scoreboards and TAB layouts that show players when a manual event queue is open.
Older supported formats
Some older placeholder formats are still supported.
%eventforge_event_active_<event>%
%eventforge_event_loaded_<event>%
%eventforge_event_on_cooldown_<event>%
%eventforge_event_cooldown_<event>%
%eventforge_event_display_<event>%
%eventforge_event_time_left_<event>%
%eventforge_event_elapsed_<event>%
%eventforge_event_participants_<event>%
%eventforge_player_score_<event>%
%eventforge_player_rank_<event>%
%eventforge_player_participating_<event>%
%eventforge_event_scheduled_<event>%
%eventforge_event_next_start_<event>%
%eventforge_event_category_<event>%
%eventforge_event_difficulty_<event>%
%eventforge_event_author_<event>%
%eventforge_event_version_<event>%
%eventforge_event_tags_<event>%
%eventforge_event_description_<event>%
%eventforge_event_can_start_<event>%
%eventforge_event_start_reason_<event>%
%eventforge_event_region_count_<event>%
For new setups, use the newer format:
%eventforge_event_<event>_<value>%
Example:
%eventforge_event_mining_rush_active%
Example scoreboard lines
&bActive Events: &f%eventforge_active_count%
&7Current: &f%eventforge_active_names%
&7Next Event: &f%eventforge_next_event%
&7Starts In: &f%eventforge_next_event_time%
&7Vote: &f%eventforge_vote_active% &8(&f%eventforge_vote_time_left%&8)
&7Queue: &f%eventforge_queue_event_display% &8(&f%eventforge_queue_time_left%&8)
&7Score: &a%eventforge_event_mining_rush_player_score%
&7Rank: &e#%eventforge_event_mining_rush_player_rank%
Example menu checks
Show a vote button only while a vote is active:
%eventforge_vote_active%
Show a queue join button only while a queue is active:
%eventforge_queue_active%
Show whether the player has joined the current queue:
%eventforge_queue_joined%
Show whether a specific event queue is open:
%eventforge_queue_mining_rush_active%
Troubleshooting
Placeholder returns blank​
Check that:
EventForge is installed
PlaceholderAPI is installed
the event ID is correct
the event is loaded
the placeholder spelling is correct
Run:
/eventforge list
to check loaded event IDs.
Player placeholders return 0 or No​
Some placeholders need a player context.
For example:
%eventforge_event_mining_rush_player_score%
%eventforge_queue_joined%
work best in scoreboards, TAB, menus, or plugins that parse placeholders for a specific player.
Event time left returns 0s​
The event probably is not active.
Check:
%eventforge_event_mining_rush_active%
or run:
/eventforge active
Vote placeholders show No or 0​
Voting may be disabled or no vote may be active.
Check:
%eventforge_vote_enabled%
%eventforge_vote_active%
Then start a vote:
/eventforge vote start mining_rush mob_hunt
Scheduled vote placeholders show blank​
Scheduled voting may be disabled, or no scheduled votes may have loaded.
Check:
%eventforge_scheduled_vote_enabled%
%eventforge_scheduled_vote_count%
Then run:
/eventforge validate schedule_config.yml
Queue placeholders show No or 0​
No manual queue may be open.
Check:
%eventforge_queue_active%
Then start a manual-mode event:
/eventforge start mining_rush
If the event is still using AUTOMATIC, it will start instantly instead of opening a queue.
Summary
PlaceholderAPI lets other plugins display EventForge data.
Useful placeholders include:
%eventforge_active_names%
%eventforge_next_event%
%eventforge_next_event_time%
%eventforge_event_<event>_active%
%eventforge_event_<event>_player_score%
%eventforge_event_<event>_player_rank%
%eventforge_vote_active%
%eventforge_vote_time_left%
%eventforge_next_scheduled_vote_time_left%
%eventforge_queue_active%
%eventforge_queue_time_left%
%eventforge_queue_joined%
%eventforge_top_player_<event>_1%
%eventforge_top_score_<event>_1%