Placeholders¶

Quick Start: Connect your other plugins.

JManhunt provides built-in PlaceholderAPI identifiers. All placeholders must be used with the prefix %jmanhunt_<placeholder>% (e.g. %jmanhunt_career_kills%, %jmanhunt_live_phase_0%).

Career, current-match, compass, and ranked viewer keys resolve for the viewer PlaceholderAPI passes; match, lobby, live, leaderboard, player-lookup, global, playlist, and the ranked season and leaderboard keys work player-less (they resolve for console and sign lines too). Trailing-id keys take the match id (%jmanhunt_match_winner_7%), the lobby id (%jmanhunt_live_phase_0%), a playlist id (%jmanhunt_playlist_queued_standard-1v1%, lowercase), or a match id plus a uuid or player name (%jmanhunt_match_player_kills_7_Steve%, names match case-insensitively). Leaderboard cells take a rank (%jmanhunt_top_kills_1_name%, ranks start at 1), and player lookups take a uuid or player name (%jmanhunt_player_kills_Steve%). Ranked season keys take a season number (%jmanhunt_ranked_season_1%) and the ranked board takes a rank (%jmanhunt_ranked_top_1%, names at %jmanhunt_ranked_top_1_name%, ranks start at 1). When a lobby runs sub-lobbies, the first sub-lobby with a running game answers the live keys.

Every value reads from memory: unknown match ids resolve empty and warm the history cache in the background, so a second read finds them. Outside a match, current-match numbers resolve -1 and texts resolve empty; scores shown through placeholders never go below 0. Leaderboards refresh when a match ends (career only changes there), so holograms never trigger database reads; kdr boards only rank players with enough matches played (statistics.leaderboards.min-matches, default 3). Keys marked free resolve in both editions; unmarked keys resolve empty in the free edition.

Career¶

The viewer's lifetime totals, kept in the statistics database across restarts. KDR is kills over deaths (2dp); win rate is wins over matches as a bare percent (1dp, no sign so values stay PAPI-safe).

Current Match¶

The viewer's live match. Numbers resolve -1 outside a match, texts resolve empty. match_mvp names the live score leader during the match and the official MVP once the match finalizes; winner and leaders stay empty until the match ends.

Compass¶

The viewer's tracking compass, as of its last render. Distance is the same whole meters the actionbar shows, with no suffix; target fields stay empty unless the needle tracks a live player (TRACKING) or a last-seen location (LAST_SEEN). Outside a match, or before the first render, distance resolves -1, flags resolve false, state resolves NO_TARGET, and the rest resolve empty. Reason ids come from the signal interference options (light-level, underground, underwater, altitude, weather, biome, moved, line-of-sight, line-of-sight-hidden, invisible, low-health, hungry, low-exp-level); a reasonless cache signal reports an empty reason and side. Modifiers read these through <placeholder:compass_distance> and friends.

Match By Id¶

One stored match, addressed by match id. Works player-less. The spectator peak is the highest that roster reached during the match; role counts read through the composition keys instead.

One participant's row, addressed by match id plus uuid or player name:

Lobby And Live¶

Per-lobby aggregates plus the lobby's live match, addressed by lobby id. Works player-less. Live counts fall back to 0 when idle, missing times to -1, and phase to LOBBY.

Playlists¶

Queue headcounts per playlist id, across every lobby. Works player-less. Unknown ids read zero (IDLE for the state word). Appending a lobby id scopes a metric to one lobby's queues (%jmanhunt_playlist_matches_standard-1v1_0%).

Quickmatch¶

The viewer's live queue attempt, backing the looking-for-match sidebar. Both keys read empty without a viewer, outside a queue attempt, and on free.

Tournaments¶

Mode-agnostic tournament keys: the same rows work for Best-of, brackets, and round-robin. See Tournaments. Viewer keys need a viewer; outside a live tournament the score and unit keys read empty.

Ranked¶

Season elo, ranks, counts, the season leaderboard, and leave penalties. Viewer keys need a viewer; the season number and the board work player-less. Missing rows read --- (counts read 0); the rank name shows Unranked during placement.

Leaderboards¶

Best-first career boards, addressed by rank. Works player-less, so holograms and scoreboards read them directly. Every board ships a total plus hunter and runner splits (win streak ranks the best streak; streaks are role-agnostic, so the splits rank the same best). Boards refresh when a match ends; kdr boards only rank players with enough matches played (statistics.leaderboards.min-matches).

Timed periods¶

Append _monthly or _weekly to any leaderboard cell above (except the win streak boards), to any numeric career_* viewer key with a per-match fold behind it, or to any career_rank_* viewer rank to read the current calendar period instead of alltime. Weeks start Sunday at server-local midnight; months start on the first. Only finished matches fold (cancelled games never count), a match lands in the period it ended in, and periods before this build hold no data. Role, cosmetics, XP, pointers, streaks, and role-split deaths stay alltime. Timed boards rank everyone with no minimum-matches filter, and timed keys keep their bare key's edition. Examples: %jmanhunt_top_kills_1_value_monthly%, %jmanhunt_top_playtime_1_value_weekly%, %jmanhunt_career_kills_monthly%, %jmanhunt_career_rank_playtime_weekly%.

Player Lookup¶

Career totals for one player, addressed by uuid or player name (names match case-insensitively). Works player-less; offline players resolve from their last folded totals.

One player's live match, addressed by uuid or player name. Works player-less. Composition puts the followed player's team first; splits and the live id read -1 outside a match.

General¶

Utilities unrelated to the engine. Date and time follow the parsing language: each language carries its own date format and timezone (see the general lang section), falling back to the server timezone and then to UTC.

Global¶

Server-wide lifetime aggregates. Works player-less.

Migrating From The Old Keys¶

The previous scheme (total_*, game_*, sessions_*) was removed with no backward compatibility: old keys resolve unknown now. Career keys moved under career_* (%jmanhunt_total_kills% is %jmanhunt_career_kills%), live lobby keys moved under live_* (%jmanhunt_game_phase_0% is %jmanhunt_live_phase_0%), and the old per-session keys moved under match_* (%jmanhunt_game_kills_this_session% is %jmanhunt_match_kills%). Note the KDR fix: the old ratio divided kills by sessions, the new one divides by deaths.

Configuration¶

Each placeholder can be individually enabled or disabled and formatted in placeholders.yml:

placeholders:
  career_kills:
    enabled: true
    format: "{value}"
  lobby_score_<id>:
    enabled: true
    format: "{value}"

Trailing-id families share one entry per pattern (lobby_score_<id> covers every lobby). The {value} placeholder is replaced with the built-in value. Formatting uses MiniMessage (classic & codes convert automatically).

Nested Placeholders¶

Formats may nest placeholders inside other placeholders with brace spans: {match_composition_{career_last_match_id}} reads the composition of the viewer's last match. Spans resolve innermost outward through the engine first (with or without the jmanhunt_ prefix), then through PlaceholderAPI for outside-plugin tokens when it is hooked up, repeating until nothing is left to parse. A token whose value is another placeholder keeps resolving: if custom_plugin_placeholder returns {player_match_id_Steve}, then {match_composition_{custom_plugin_placeholder}} lands on Steve's match composition in three passes.

Resolution caps at 15 passes (an engine-internal limit against self-returning placeholders looping forever). Text still unresolved after the final pass stays as is and logs a warning. The free edition runs one pass only: nested input stays literal and logs an upsell for the advanced parser.

Percent spans (%token%) resolve strictly through PlaceholderAPI, never through the engine, alternating with brace spans inside the same pass loop. This is how values from other plugins parse: a LuckPerms prefix returning %jmanhunt_ranked_rank% resolves like any PlaceholderAPI text. Percent spans PlaceholderAPI cannot resolve stay literal and silent, matching PlaceholderAPI semantics.