Плейсхолдеры

Автор меню

Плейсхолдер - это часть текста, заключённая между символами %.

Плейсхолдеры работают в любом параметре предмета, действия, правила и в некоторых активаторах. Тип параметра значения не имеет.

Главное - чтобы возвращаемое значение подходило по типу: если параметр ждёт число, плейсхолдер тоже должен вернуть число, иначе будет ошибка.

Плейсхолдеры бывают встроенные в AM и сторонние (PlaceholderAPI).

Встроенные плейсхолдеры

Плейсхолдер	Тип	Описание
Плейсхолдеры игрока
%player_name%	String	Имя игрока
%player_display_name%	String	Отображаемое имя (с цветами)
%player_level%	Number	Уровень игрока
%player_xp%	Number	Опыт игрока
%player_location%	String	Локация игрока
%player_world%	String	Мир игрока
%player_uuid%	String	UUID игрока
%player_gm%	String	Имя игрового режима из Bukkit
Плейсхолдеры сервера
%server_players%	Number	Количество игроков
%server_players_<world>%	Number	Количество игроков в указанном мире
%server_name%	String	Имя сервера
%server_ip%	String	IP-адрес сервера
%server_port%	Number	Порт сервера
%server_max_players%	String	Максимум слотов игроков
%server_version%	String	Версия сервера
Плейсхолдеры BungeeCord
%bungee_online%	Number	Общее количество игроков во всей сети BungeeCord
%bungee_players_<server>%	Number	Количество игроков на конкретном сервере BungeeCord
Специальные плейсхолдеры
%hanim_:<animation_name>:<unique_id>%	String	Возвращает следующий кадр анимации головы из файла animated_heads.conf
%ctg_page%	Number	Индекс текущей страницы
%ctg_pages%	Number	Общее количество страниц меню
%ctg_page_next%	Number	Индекс следующей страницы
%ctg_page_prev%	Number	Индекс предыдущей страницы
%ctg_elements%	Number	Общее количество объектов в каталоге
%ctg_<extractor placeholder>%	Зависит от экстрактора	Получить значение через экстрактор из контекста каталога
%activator_name%	String	Имя активатора, открывшего меню
%activator_<extractor placeholder>%	Зависит от экстрактора	Получить значение через экстрактор из контекста активатора
%placed_<item_extractor_placeholder>%	Зависит от экстрактора	Информация о последнем размещённом предмете
%placed_slot%	Number	Индекс слота, в который был размещён последний предмет
%taken_<item_extractor_placeholder>%	Зависит от экстрактора	Информация о последнем взятом предмете
%taken_slot%	Number	Индекс слота, из которого был взят последний предмет
%changed_<item_extractor_placeholder>%	Зависит от экстрактора	Информация о финальном предмете после размещения/взятия

Если стоит PlaceholderAPI, часть встроенных плейсхолдеров отключается и подменяется огромным набором из PAPI. Специальные плейсхолдеры работают и с PAPI, и без него.

Примеры использования

Несколько вариантов применения плейсхолдеров в меню.

В командах

command {
  console: "give %player_name% minecraft:diamond_sword"
}

В предметах

itemAdd {
  slot: 0
  material: STONE
  name: "&eКамень %player_name%"
}

Плейсхолдеры для переменных

Отдельной группой идут плейсхолдеры для переменных - они читают значения переменных. Работают и с PlaceholderAPI, и без него.

Экстракторы значений

Осторожно

Экстракторы значений - не самостоятельные плейсхолдеры вроде %player_name%. Они работают только в своём контексте: например, в контексте активатора или внутри генерируемых меню.

AbstractMenus умеет хранить контекст события. Например, при открытии меню через clickBlock плагин запоминает блок, по которому кликнули. Плейсхолдеры активатора достают данные из этого контекста - и достают их именно через экстракторы. Как ими пользоваться - см. Контекст активатора.

На каждый тип данных есть свой экстрактор со своим набором плейсхолдеров. Все экстракторы и доступные в них имена - ниже.

Экстрактор блока

Получает данные из блока Minecraft.

Имя	Описание
block_type	Материал блока
block_data	Data блока (MC 1.12-)
block_world	Мир блока
block_x	Позиция по оси X
block_y	Позиция по оси Y
block_z	Позиция по оси Z
block_power	Сила редстоун-сигнала на блоке
block_temp	Температура биома, в котором стоит блок
block_biome	Имя биома, в котором стоит блок

Экстрактор мира

Получает данные о мире.

Имя	Описание
world_name	Имя мира
world_difficulty	Сложность мира (peaceful, normal и т.д.)
world_max_height	Максимальная высота строительства
world_pvp	Разрешён ли PVP
world_seed	Сид мира
world_time	Относительное игровое время мира. Аналог hours * 1000
world_type	Тип мира (default, flat и т.д.)
world_entities	Количество сущностей (включая игроков) в мире
world_players	Количество игроков в мире

Экстрактор сущности

Достаёт данные сущности. Если знаешь, что сущность живая (моб, животное, игрок и т.д.), доступны и плейсхолдеры для living-сущностей.

Заметка

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

Имя	Описание
Все сущности
entity_type	Тип
entity_id	Числовой id
entity_uuid	Уникальный id
entity_name	Общее имя
entity_custom_name	Кастомное имя (если есть)
entity_world	Мир сущности
entity_loc_x	Позиция по оси X
entity_loc_y	Позиция по оси Y
entity_loc_z	Позиция по оси Z
entity_facing	Направление взгляда (north, east и т.д.)
entity_pose	Поза сущности (MC 1.14+)
entity_ticks_lived	Сколько живёт сущность
Living-сущность
entity_last_damage	Последний полученный урон
entity_no_damage_ticks	Сколько сущность прожила без урона
entity_killer	Имя последнего убийцы (если есть)
entity_eye_height	Высота глаз

Экстрактор предмета

Получает данные из ItemStack.

Имя	Описание
item_type	Материал предмета
item_data	Data предмета (MC 1.12-)
item_amount	Количество в стаке
item_max_stack	Максимальный размер стака
item_display_name	Отформатированное имя
item_localized_name	Локализованное имя
item_model	Custom model data (MC 1.14+)
item_serialized	Весь предмет, сериализованный в base64-строку. Можно использовать со свойством serialized

Экстрактор региона

Получает данные региона WorldGuard.

Имя	Описание
region_id	Имя региона
region_priority	Приоритет региона
region_type	Тип региона (cuboid, poly2d и т.д.)
region_owners	Список владельцев
region_members	Список участников
region_owners_amount	Количество владельцев
region_members_amount	Количество участников

Экстрактор NPC

Получает данные NPC из Citizens.

Имя	Описание
npc_id	Числовой id NPC
npc_name	Общее имя
npc_full_name	Полное имя
npc_entity_<entity placeholder>	Получить значение из сущности NPC через экстрактор сущности

Например, чтобы получить тип сущности NPC, по формату экстрактора сущности плейсхолдер будет такой:

npc_entity_type

Отличие от обычного экстрактора сущности - префикс npc_.

Экстрактор команды

Отдаёт данные распарсенной команды (только в контексте активатора).

Имя	Описание
cmd_name	Базовое имя команды
cmd_args	Количество аргументов
cmd_arg:<argument key>	Значение распарсенного аргумента по ключу
<argument key>:<placeholder>	Получить значение обычным плейсхолдером по игроку, который ввёл команду

Например, ты задал в активаторе аргумент с ключом username. Чтобы достать значение, которое ввёл игрок, бери плейсхолдер:

cmd_arg_username

Подробнее про построение команд и чтение аргументов - в разделе Построение команд.