Placeholder API Integration - Ubivis/UbiDungeon GitHub Wiki

PlaceholderAPI Integration

Overview

AI Dungeon Generator provides full integration with PlaceholderAPI, allowing you to display dungeon information, quest progress, and player statistics in other plugins like scoreboards, holograms, GUIs, and more.

Available Placeholders

General Statistics

  • %aidungeon_total_dungeons% - Total number of generated dungeons across all worlds

Player-Specific Information

  • %aidungeon_player_completed_dungeons% - Number of dungeons the player has completed
  • %aidungeon_player_active_quests% - Number of active quests the player has
  • %aidungeon_player_completed_quests% - Number of completed quests the player has

Nearest Dungeon Information

  • %aidungeon_nearest_dungeon_distance% - Distance to the nearest dungeon
  • %aidungeon_nearest_dungeon_coords% - Coordinates of the nearest dungeon (x,y,z format)
  • %aidungeon_nearest_dungeon_x% - X coordinate of the nearest dungeon
  • %aidungeon_nearest_dungeon_y% - Y coordinate of the nearest dungeon entrance
  • %aidungeon_nearest_dungeon_z% - Z coordinate of the nearest dungeon
  • %aidungeon_nearest_dungeon_world% - World name of the nearest dungeon
  • %aidungeon_nearest_dungeon_biome% - Biome type of the nearest dungeon
  • %aidungeon_nearest_dungeon_theme% - Theme of the nearest dungeon

Quest Information

Access information about a player's quests by index (1-based):

  • %aidungeon_quest_1_name% - Name of the player's first quest
  • %aidungeon_quest_1_description% - Description of the first quest
  • %aidungeon_quest_1_type% - Type of the first quest (KILL, COLLECT, EXPLORE)
  • %aidungeon_quest_1_progress% - Progress of the first quest (e.g., "2/5")
  • %aidungeon_quest_1_percentage% - Completion percentage of the first quest
  • %aidungeon_quest_1_completed% - Whether the quest is completed (Yes/No)
  • %aidungeon_quest_1_dungeon% - Dungeon ID associated with the quest

Dungeon Information

Access information about generated dungeons by index (1-based):

  • %aidungeon_dungeon_1_world% - World name of the first dungeon
  • %aidungeon_dungeon_1_biome% - Biome type of the first dungeon
  • %aidungeon_dungeon_1_x% - X coordinate of the first dungeon
  • %aidungeon_dungeon_1_y% - Y coordinate of the first dungeon entrance
  • %aidungeon_dungeon_1_z% - Z coordinate of the first dungeon
  • %aidungeon_dungeon_1_coords% - Coordinates of the first dungeon (x,y,z format)
  • %aidungeon_dungeon_1_theme% - Theme of the first dungeon
  • %aidungeon_dungeon_1_age% - Age of the dungeon in days
  • %aidungeon_dungeon_1_discoverer% - Name of the player who discovered the dungeon

Usage Examples

Scoreboard Display

Create a scoreboard that shows nearby dungeons and quest progress:

# In your scoreboard plugin configuration
scoreboard:
  title: "&6&lDungeon Explorer"
  lines:
    - "&7&m----------------"
    - "&eNearest Dungeon:"
    - "  &fLocation: &a%aidungeon_nearest_dungeon_coords%"
    - "  &fDistance: &a%aidungeon_nearest_dungeon_distance% blocks"
    - "  &fTheme: &a%aidungeon_nearest_dungeon_theme%"
    - "&eQuests:"
    - "  &f%aidungeon_quest_1_name%: &a%aidungeon_quest_1_progress%"
    - "  &f%aidungeon_quest_2_name%: &a%aidungeon_quest_2_progress%"
    - "&7&m----------------"
    - "&fTotal Dungeons: &a%aidungeon_player_completed_dungeons%/%aidungeon_total_dungeons%"

Holographic Displays

Create floating text above dungeon entrances:

# In your hologram plugin configuration
holograms:
  dungeon_marker:
    location: "%aidungeon_dungeon_1_world%,%aidungeon_dungeon_1_x%,%aidungeon_dungeon_1_y%+3,%aidungeon_dungeon_1_z%"
    lines:
      - "&6✧ &l%aidungeon_dungeon_1_theme% Dungeon &6✧"
      - "&eDiscover the secrets within!"
      - "&7Discovered by: &f%aidungeon_dungeon_1_discoverer%"

GUI Menus

Create clickable dungeon teleport menus:

# In your GUI plugin configuration
menus:
  dungeons:
    title: "Dungeon Teleporter"
    size: 27
    items:
      dungeon1:
        slot: 10
        material: COMPASS
        name: "&6%aidungeon_dungeon_1_theme% Dungeon"
        lore:
          - "&7Location: &f%aidungeon_dungeon_1_coords%"
          - "&7Biome: &f%aidungeon_dungeon_1_biome%"
          - "&7Age: &f%aidungeon_dungeon_1_age% days"
          - "&eClick to teleport!"
        command: "tp %player% %aidungeon_dungeon_1_coords%"

Custom Signs

Create informational signs about dungeons:

[Dungeon]
Nearest: %aidungeon_nearest_dungeon_theme%
Distance: %aidungeon_nearest_dungeon_distance%
/aidungeon info

NPC Integration

If you're using Citizens or another NPC plugin, you can create quest-giving NPCs that reference dungeon information:

# Example NPC dialogue configuration
npcs:
  dungeon_master:
    greeting: "Greetings, adventurer! There are %aidungeon_total_dungeons% dungeons awaiting discovery."
    dialogue:
      - "The nearest dungeon is a %aidungeon_nearest_dungeon_theme% dungeon, located %aidungeon_nearest_dungeon_distance% blocks away."
      - "You have completed %aidungeon_player_completed_dungeons% dungeons so far. Well done!"
    quests:
      - condition: "%aidungeon_nearest_dungeon_theme% == PYRAMID"
        text: "I have heard rumors of ancient artifacts in the nearby pyramid dungeon. Find them for me!"

Waypoint Systems

Many waypoint plugins support PlaceholderAPI, allowing you to automatically create waypoints to dungeons:

# Example waypoint configuration
auto_waypoints:
  dungeons:
    - name: "Dungeon: %aidungeon_nearest_dungeon_theme%"
      world: "%aidungeon_nearest_dungeon_world%"
      x: "%aidungeon_nearest_dungeon_x%"
      y: "%aidungeon_nearest_dungeon_y%"
      z: "%aidungeon_nearest_dungeon_z%"
      color: BLUE
      visible_distance: 200

Custom Commands

Use placeholders in custom command plugins:

# Custom command configuration
commands:
  dungeon:
    aliases: [dung, dg]
    permission: aidungeon.player
    execute:
      - "tell: &6Nearest dungeon is a &e%aidungeon_nearest_dungeon_theme% Dungeon"
      - "tell: &6Located at: &e%aidungeon_nearest_dungeon_coords%"
      - "tell: &6Distance: &e%aidungeon_nearest_dungeon_distance% blocks"

Installation

  1. Make sure PlaceholderAPI is installed on your server
  2. The AI Dungeon Generator plugin will automatically register its placeholders

Troubleshooting

If placeholders aren't working:

  1. Ensure PlaceholderAPI is properly installed
  2. Run /papi reload to reload all expansions
  3. Check if AI Dungeon Generator is listed in /papi list
  4. Verify that you're using the correct placeholder format
  5. Check console for any error messages

Developer API

If you're a developer wanting to use these placeholders in your own plugin:

// Get parsed placeholders
String parsedPlaceholder = PlaceholderAPI.setPlaceholders(player, "%aidungeon_nearest_dungeon_coords%");

// Check for conditions
if (PlaceholderAPI.setPlaceholders(player, "%aidungeon_player_completed_dungeons%").equals("5")) {
    // Player has completed 5 dungeons
    giveReward(player);
}