PlaceholderAPI

PlaceholderAPI Integration

Alkatraz registers a PlaceholderAPI expansion (alkatraz) that exposes player stats, spell data, research progress, hotbar info, and server-wide leaderboards.

---

Setup

1. Install PlaceholderAPI on your server.
2. Start the server once with both Alkatraz and PlaceholderAPI installed.
3. Alkatraz automatically registers its expansion — no placeholder download command is needed.
4. Use any %alkatraz_...% placeholder in chat plugins, scoreboards, holograms, etc.

Leaderboard Configuration

Leaderboard placeholders are cached and refreshed periodically. Adjust these settings in config.yml:

placeholders:
  leaderboard:
    enabled: true
    refresh_interval_minutes: 5
    max_entries: 10

---

Placeholders

All placeholders follow the format %alkatraz_<category>_<params>%. Player-specific placeholders return an empty string if the player's profile is not loaded.

---

Stats

Placeholder	Description
%alkatraz_stats_circle%	Current Magic Circle level (0–9)
%alkatraz_stats_circle_roman%	Current circle as a Roman numeral (I, II, III, ...)
%alkatraz_stats_mana%	Current mana
%alkatraz_stats_max_mana%	Maximum mana
%alkatraz_stats_mana_percent%	Mana as a percentage (0–100)
%alkatraz_stats_mana_regen%	Mana regeneration rate
%alkatraz_stats_spell_power%	Spell Power attribute
%alkatraz_stats_stat_points%	Available stat points to invest
%alkatraz_stats_reset_tokens%	Remaining reset tokens
%alkatraz_stats_arcane_knowledge%	Arcane Knowledge earned
%alkatraz_stats_research_points%	Available research points
%alkatraz_stats_casting%	true if currently casting
%alkatraz_stats_stealth%	true if in stealth mode
%alkatraz_stats_can_cast%	true if able to cast
%alkatraz_stats_cast_mode%	Current cast mode
%alkatraz_stats_disguise%	Current disguise name
%alkatraz_stats_tutorial_seen%	true if tutorial has been seen
%alkatraz_stats_total_spells%	Total spells in the registry
%alkatraz_stats_total_enabled_spells%	Total enabled spells
%alkatraz_stats_discovered_count%	Number of spells the player has discovered

---

Elements

Replace <element> with one of: fire, water, air, earth, light, dark.

Placeholder	Description
%alkatraz_elements_points_<element>%	Stat points invested in this element
%alkatraz_elements_affinity_<element>%	Elemental affinity
%alkatraz_elements_resistance_<element>%	Elemental resistance
%alkatraz_elements_magic_affinity%	Magic (unaligned) affinity
%alkatraz_elements_magic_resistance%	Magic (unaligned) resistance

Examples:

%alkatraz_elements_affinity_fire%
%alkatraz_elements_resistance_water%
%alkatraz_elements_points_earth%

---

Spells

Replace <spell_id> with the spell's internal ID (e.g. magic_missile, fireball, heal).

Placeholder	Description
%alkatraz_spells_has_<spell_id>%	true if the player has discovered this spell
%alkatraz_spells_name_<spell_id>%	Display name of the spell
%alkatraz_spells_element_<spell_id>%	Element of the spell (FIRE, WATER, etc.)
%alkatraz_spells_circle_<spell_id>%	Required Magic Circle level
%alkatraz_spells_mana_cost_<spell_id>%	Mana cost
%alkatraz_spells_code_<spell_id>%	Cast code (e.g. RRRRR)
%alkatraz_spells_mastery_<spell_id>%	Current mastery level
%alkatraz_spells_mastery_<spell_id>_percent%	Mastery as a percentage
%alkatraz_spells_mastery_<spell_id>_max%	Maximum mastery for the spell
%alkatraz_spells_cooldown_<spell_id>%	Remaining cooldown in seconds (0 if ready)
%alkatraz_spells_cooldown_<spell_id>_ready%	true if off cooldown
%alkatraz_spells_cooldown_time_<spell_id>%	Base cooldown time in seconds

Examples:

%alkatraz_spells_has_fireball%
%alkatraz_spells_name_heal%
%alkatraz_spells_mastery_magic_missile_percent%
%alkatraz_spells_cooldown_fireball_ready%

---

Research

Replace <research_id> with the research node's internal ID.

Placeholder	Description
%alkatraz_research_completed_count%	Total completed research nodes
%alkatraz_research_has_<research_id>%	true if this research is completed
%alkatraz_research_state_<research_id>%	State of the research (e.g. COMPLETED, LOCKED, AVAILABLE)

Examples:

%alkatraz_research_completed_count%
%alkatraz_research_has_arcane_basics%
%alkatraz_research_state_advanced_enchanting%

---

Hotbar

Placeholder	Description
%alkatraz_hotbar_slot_<slot>%	Spell ID assigned to hotbar slot (1–9)
%alkatraz_hotbar_count%	Number of spells assigned to hotbar

Examples:

%alkatraz_hotbar_slot_1%
%alkatraz_hotbar_count%

---

Leaderboard

The leaderboard is ranked by Arcane Knowledge and is periodically refreshed based on your config.

Placeholder	Description
%alkatraz_leaderboard_total_players%	Total players on the leaderboard
%alkatraz_leaderboard_rank%	The viewing player's rank (1-indexed)
%alkatraz_leaderboard_top_<position>_name%	Username at the given position
%alkatraz_leaderboard_top_<position>_uuid%	UUID at the given position
%alkatraz_leaderboard_top_<position>_ak%	Arcane Knowledge at the given position
%alkatraz_leaderboard_top_<position>_circle%	Circle level at the given position

<position> is 1-indexed (1 = top player).

Examples:

%alkatraz_leaderboard_rank%
%alkatraz_leaderboard_top_1_name%
%alkatraz_leaderboard_top_3_ak%

---

Usage Examples

Server Scoreboard

§6§lArcane Leaderboard
§e#1 §f%alkatraz_leaderboard_top_1_name% §7- §e%alkatraz_leaderboard_top_1_ak% AK
§e#2 §f%alkatraz_leaderboard_top_2_name% §7- §e%alkatraz_leaderboard_top_2_ak% AK
§e#3 §f%alkatraz_leaderboard_top_3_name% §7- §e%alkatraz_leaderboard_top_3_ak% AK

Player HUD (Holographic Displays, TAB, etc.)

§bMana: §f%alkatraz_stats_mana%/%alkatraz_stats_max_mana%
§6Circle: §f%alkatraz_stats_circle_roman%
§aRank: #%alkatraz_leaderboard_rank%

Spell Status Display

§6Fireball
§7Element: §c%alkatraz_spells_element_fireball%
§7Mana Cost: §b%alkatraz_spells_mana_cost_fireball%
§7Mastery: §e%alkatraz_spells_mastery_fireball_percent%%%
§7Cooldown: %alkatraz_spells_cooldown_fireball_ready%

Chat Announcements

§e%player% has reached Circle %alkatraz_stats_circle_roman%!
§eTotal spells discovered: %alkatraz_stats_discovered_count%

---

Notes

• Leaderboard caching: The leaderboard cache refreshes at the interval defined in config.yml (default: 5 minutes). During this window, the data is stale. Set a shorter interval if your server has fewer players.
• Offline players: The leaderboard reads player data files directly and can rank offline players, but only online players can use player-specific placeholders (stats, spells, hotbar).
• Empty returns: If a placeholder returns an empty string, verify the player is online, the spell/research ID is correct, and the profile is loaded.
• Spell IDs: Use internal spell IDs (lowercase with underscores), not display names. Run /spells to see your spells, or check Spells for a full list.
• Research states: Possible values for %alkatraz_research_state_<id>% correspond to the ResearchState enum (e.g. COMPLETED, LOCKED, AVAILABLE).