PlaceholderAPI на Minecraft сервере: настройка, expansions и примеры

PlaceholderAPI (часто сокращают до PAPI) - это плагин-мост, через который остальные плагины обмениваются динамическими данными. Без него половина современного контента в TAB, scoreboard и чате просто не работает. Разберём, как поставить, какие expansions подключить и где это реально используется.

Что такое PlaceholderAPI и зачем он нужен

PAPI сам по себе ничего не делает. Это API-плагин, который предоставляет другим плагинам единый формат подстановки данных в строки. Любой плагин, который хочет показать имя игрока, его баланс, группу LuckPerms или текущий TPS, просто пишет в конфиге %player_name% или %vault_eco_balance%, а PAPI на лету подменяет это на реальное значение.

Главный плюс - один формат на всё. Раньше для TAB-плагина нужны были одни плейсхолдеры, для scoreboard другие, для чата третьи. С PAPI это один универсальный синтаксис, и любой плагин, который умеет с ним работать, читает данные из любого источника.

На практике PAPI стоит на 90% серверов от small SMP до крупных миниигровых сетей. Если запускаешь сервер с любым TAB, scoreboard, custom-чатом или голограммами - почти наверняка он понадобится.

Установка PlaceholderAPI

Скачать стабильную версию можно на Spigot. Кладёшь .jar в plugins/, рестартишь сервер. Всё.

После старта PAPI создаст папку plugins/PlaceholderAPI/ с подпапкой expansions/. Туда складываются дополнения, которые добавляют конкретные плейсхолдеры. Сам PAPI без них почти бесполезен, поэтому следующий шаг важнее установки.

Совместимость по версиям: Paper и Spigot 1.16.5 - 1.21.x. Для Folia есть отдельный форк PAPI 2.11+, обычная версия на Folia не запустится из-за разницы в планировщике.

Принцип работы: provider и consumer

PAPI работает по простой схеме. Есть провайдеры (expansions) - плагины или модули, которые отдают данные. И есть пользователи (consumers) - плагины, которые эти данные подставляют в свои сообщения.

Например, ты пишешь в конфиге TAB-плагина строку:

header: '&aOnline: %server_online%/%server_max_players%'

TAB-плагин видит %server_online%, спрашивает PAPI, PAPI находит нужный expansion (в данном случае Server) и возвращает текущее число игроков. Сам TAB-плагин про устройство сервера ничего не знает, и это правильно.

Полезные команды

После установки PAPI добавляет несколько команд для отладки и управления:

/papi list
/papi info <expansion>
/papi parse <player> <text>
/papi parse me %player_name% has $%vault_eco_balance%
/papi reload
/papi ecloud download <expansion>

/papi parse me <text> - самый полезный инструмент для дебага. Если в TAB или чате плейсхолдер выводится буквально (%player_name% вместо имени), запусти эту команду. Если PAPI его распознаёт - значит проблема в том плагине, который тебя не подключил. Если возвращает текст как есть - expansion не установлен или неправильно называется.

Установка expansions через ecloud

Раньше expansions качали вручную с сайта. Сейчас всё проще - есть встроенный ecloud:

/papi ecloud download Player
/papi ecloud download Vault
/papi ecloud download Statistic
/papi ecloud download Server
/papi ecloud download Math
/papi reload

После каждого скачивания нужно делать /papi reload или просто рестартить сервер. До перезагрузки expansion лежит в папке, но не активен.

Базовый набор для большинства серверов: Player, Server, Vault (если есть экономика), LuckPerms (если используешь как permissions plugin), Statistic (для разной игровой статистики).

Топ полезных expansions

Player - самый базовый, ставится почти всегда. Даёт %player_name%, %player_displayname%, %player_uuid%, %player_health%, %player_food_level%, %player_world%, %player_ping%, координаты, gamemode и десятки других полей.

Server - данные о сервере. %server_online%, %server_max_players%, %server_unique_joins%, %server_tps_1%, %server_uptime%, %server_ram_used%. TPS-плейсхолдеры особенно полезны для админских скоринбордов.

Vault - экономика и группы через Vault API. %vault_eco_balance%, %vault_eco_balance_formatted% (с разделителями тысяч), %vault_prefix%, %vault_suffix%, %vault_group%. Работает с любой экономикой, которая хукается в Vault: EssentialsX, CMI, TheNewEconomy.

LuckPerms - если ты на LuckPerms (а ты скорее всего на нём). %luckperms_primary_group_name%, %luckperms_prefix%, %luckperms_suffix%, %luckperms_meta_<key>%. Удобнее чем Vault для prefix/suffix, потому что не теряет цвета.

Statistic - игровая статистика из Bukkit API. %statistic_play_one_minute% (общее время игры), %statistic_mob_kills%, %statistic_deaths%, %statistic_blocks_broken%. Аккуратнее с этим: некоторые поля делают тяжёлые вызовы, не пихай 20 штук в TAB на каждого игрока.

Math - математика прямо в плейсхолдерах. %math_0_{%player_health%}/2% вернёт половину здоровья. Полезно для расчётов в скоринбордах без написания скриптов.

Кастомные плейсхолдеры через JavaScript

Для нестандартных случаев есть JavaScript expansion. Он позволяет написать свой плейсхолдер на JS без компиляции отдельного плагина.

Пример: хочешь плейсхолдер %js_kdr% который считает k/d игрока. Создаёшь файл plugins/PlaceholderAPI/javascript_placeholders.yml:

kdr:
  description: 'Kill / death ratio'
  script_file: 'kdr.js'

И сам скрипт plugins/PlaceholderAPI/javascripts/kdr.js:

function kdr(player, args) {
    var kills = parseInt(PlaceholderAPI.setPlaceholders(player, "%statistic_player_kills%"));
    var deaths = parseInt(PlaceholderAPI.setPlaceholders(player, "%statistic_deaths%"));
    if (deaths === 0) return kills.toFixed(2);
    return (kills / deaths).toFixed(2);
}

После /papi reload плейсхолдер %javascript_kdr% начинает работать везде. JS-движок Nashorn в Java 11+ удалили, поэтому для современных версий ставь GraalVM JS или используй PlaceholderAPI ScriptExpansion fork.

Где использовать PAPI на сервере

TAB / Tablist (TAB plugin) - самый частый кейс. Header, footer, имена игроков в списке, scoreboard через тот же плагин - всё через PAPI.

Scoreboard плагины - FeatherBoard, AnimatedScoreboard, тот же TAB. Динамические скоринборды с балансом, рангом и временем игры строятся целиком на PAPI.

Чат-плагины - DeluxeChat, EssentialsXChat, VentureChat. Формат сообщения и hover/click ивенты пишутся с плейсхолдерами.

Голограммы - HolographicDisplays, DecentHolograms. Лидерборды топ-игроков, баланс над банком, текущий онлайн.

ItemsAdder, Oraxen, MMOItems - формат отображаемого имени и лора предметов часто использует PAPI для динамических полей.

Скрипты Skript - встроенная поддержка плейсхолдеров через parsed placeholder.

Практический пример: формат TAB и чата

Конфиг TAB-плагина с плейсхолдерами:

header:
  - '&8&m-----&r &aMineGuard &8&m-----'
  - '&7Online: &a%server_online%&7/&a%server_max_players%'
  - '&7TPS: &a%server_tps_1%'
footer:
  - '&7Balance: &6$%vault_eco_balance_formatted%'
  - '&7Group: &b%luckperms_primary_group_name%'
  - '&7Ping: &e%player_ping%ms'

Конфиг DeluxeChat для чата:

formats:
  default:
    priority: 100
    format: '%luckperms_prefix%%player_name%%luckperms_suffix% &8» &f{message}'
  vip:
    priority: 50
    permission: 'group.vip'
    format: '&6[VIP] %player_name% &8» &e{message}'

В EssentialsXChat плейсхолдеры включаются в essentials/config.yml:

chat:
  format: '{DISPLAYNAME} &8» &f{MESSAGE}'
  group-formats:
    vip: '&6[VIP] {DISPLAYNAME} &8» &e{MESSAGE}'

EssentialsXChat поддерживает PAPI начиная с EssentialsX 2.19+. До этого нужен был EssentialsXChat-PlaceholderAPI hook отдельным плагином.

Производительность и кеширование

PAPI сам по себе быстрый. Проблемы начинаются с тяжёлыми expansions, которые лезут в БД на каждый запрос плейсхолдера. Например, %statistic_play_one_minute% для всех 100 игроков в TAB каждые 2 секунды это 50 SQL-запросов в секунду, и если статистика хранится в БД, это уже заметная нагрузка.

Что делать:

• Не пихай больше 5-10 плейсхолдеров на игрока в одну строку TAB. Отдельная статистика на каждого игрока умножается на онлайн.
• Увеличивай интервал обновления в TAB-плагине. По умолчанию там обычно 1 секунда, для большинства плейсхолдеров 5-10 секунд хватает с запасом.
• Используй relational placeholders только когда реально нужно. Они дороже обычных потому что вычисляются для пары игроков, а не одного.
• Профилируй через timings. /timings paste покажет, какие плагины съедают время, и среди них может быть конкретный expansion.

Когда плейсхолдер не работает

Стандартные ситуации, когда %player_name% отображается буквально:

1. PAPI не установлен или не загрузился - проверь /plugins, должен быть зелёный.
2. Expansion не скачан - /papi list покажет активные. Если нужного нет - /papi ecloud download <name>.
3. Плагин не использует PAPI - не каждый плагин умеет в плейсхолдеры. Например, чистый Bukkit MOTD из server.properties их не парсит, нужно ставить отдельный MOTD-плагин с поддержкой PAPI.
4. Опечатка в имени - %player_health% работает, %player_hp% нет. /papi list покажет точные имена.
5. PlaceholderAPI hook у плагина нужно включить вручную - в некоторых конфигах это опция типа placeholderapi: true, по умолчанию выключена.

Команда /papi parse me <текст> - твой главный инструмент. Если она резолвит плейсхолдер, а у плагина нет - значит плагин не подключил PAPI hook.

FAQ

Что лучше PlaceholderAPI или MVdWPlaceholderAPI

PAPI сейчас стандарт индустрии. MVdWPlaceholderAPI был популярен на 1.8 и 1.12, но автор давно перестал его поддерживать. Большинство современных плагинов умеет с обоими через bridge-плагин MVdWPlaceholderAPI Hook, но если ставишь сервер с нуля - бери PAPI и не оглядывайся.

Как самому написать expansion

Создаёшь Java-плагин или standalone-jar в папке expansions/. Класс наследуется от PlaceholderExpansion, переопределяешь onPlaceholderRequest(Player p, String identifier) и возвращаешь нужное значение. В getIdentifier() указываешь префикс (например myplugin для %myplugin_xxx%). Документация на GitHub PAPI с примерами.

Можно ли использовать PAPI в названии предмета

Только если плагин, который рендерит предмет, поддерживает плейсхолдеры. Чистый Bukkit ItemStack их не парсит. ItemsAdder, Oraxen, MMOItems и DeluxeMenus умеют. Для самописных GUI обычно используют DeluxeMenus как фронтенд.

Почему %vault_eco_balance% возвращает 0

Три причины. Первая: Vault не установлен или не нашёл провайдера экономики (нужен EssentialsX, CMI или другой плагин с Vault hook). Вторая: у игрока нет аккаунта в экономике (Essentials создаёт аккаунт при первом заходе после установки). Третья: используешь форматированный плейсхолдер %vault_eco_balance_formatted%, а число просто маленькое и округляется до 0.

Сильно ли грузит сервер большое количество плейсхолдеров в TAB

Зависит от того, какие именно. Player и Server плейсхолдеры дешёвые - читают из памяти. Statistic, LuckPerms-meta и кастомные SQL-плейсхолдеры дороже. На практике 5-10 плейсхолдеров на игрока в TAB с интервалом 5 секунд не дают заметной нагрузки даже на 200 онлайн. Проблемы начинаются при 50+ плейсхолдерах с обновлением каждую секунду.

Что такое relational placeholders

Это плейсхолдеры вида %rel_<expansion>_<id>%, которые вычисляются для пары игроков (viewer и target). Используются в основном в TAB для разной подсветки имён в зависимости от того, кто на кого смотрит (например, противник в команде красный, союзник зелёный). Дороже обычных плейсхолдеров потому что считаются N×M раз вместо N.

Что дальше

Поставь базовый набор - Player, Server, Vault, LuckPerms - и запусти /papi list чтобы увидеть что доступно. Дальше прицепляй TAB-плагин и строй scoreboard. Когда захочется чего-то нестандартного, JavaScript expansion закрывает большинство кейсов без написания отдельного плагина.

Если активно используешь PAPI на крупном сервере, обязательно прогоняй /timings paste раз в неделю и смотри, не вылез ли какой-нибудь expansion в топ по нагрузке. Чаще всего это Statistic или самописные expansions с тяжёлыми запросами.