Генератор меню

Автор меню

Основы

Генерируемое меню состоит из четырёх частей:

Каталог - источник объектов (игроки в онлайне, кастомные предметы, регионы и т.д.). Можно навесить фильтры, чтобы сузить список.
Матрица - сетка ячеек, по которой раскладываются предметы. Строк в ней столько же, сколько в самом меню.
Шаблоны предметов - то, как выглядят элементы каталога. В шаблонах работают плейсхолдеры каталога вроде %ctg_player_name%.
Пагинация - сгенерированное меню может растянуться на несколько страниц, между ними переключаются навигационными действиями.

Полный список каталогов - в конце страницы. Сейчас соберём простое сгенерированное меню. Для примера возьмём каталог PLAYERS - он отдаёт всех игроков с сервера.

title: "Generated Menu"
size: 4

catalog {
  type: PLAYERS
}

matrix {
  cells: [
    "_________",
    "_xxxxxxx_",
    "_xxxxxxx_",
    "_________"
  ]
  templates {
    "x" {
      skullOwner: "%ctg_player_name%"
      name: "&7Player &e%ctg_player_name%"
    }
  }
}

Это меню на 4 строки. Как только в корне появился catalog, плагин считает меню автогенерируемым.

catalog - настройки каталога. Внутри обязательно type - имя каталога. Остальные параметры зависят от типа.
cells - матрица ячеек в виде списка строк. Каждая строка - строка меню, каждый символ - слот инвентаря. _ (или любой символ, которого нет в templates) - пустой слот, ничего не положим. x - тег, который мы объявили в templates: в такой слот попадает только предмет шаблона x.
templates - привязка предметов к тегам. У каждого шаблона свой тег - любая латинская буква от a до z или спецсимвол. К тегу можно привязать любой предмет. Слот указывать не нужно, плагин сам вычислит его при генерации.

Если игроков на сервере хватает, получится примерно такое меню:

Пример генерируемого меню

Переключение страниц

Объектов в каталоге может быть много, поэтому меню разбивается на страницы. Для переключения есть два действия: pageNext и pagePrev - на следующую и предыдущую страницу.

Кнопки страниц задаются как обычные статические предметы. Пример:

title: "Сгенерированное меню"
size: 4

catalog {
  type: PLAYERS
}

matrix {
  cells: [
    "_________",
    "_xxxxxxx_",
    "_xxxxxxx_",
    "_________"
  ]

  templates {
    "x" {
      skullOwner: "%ctg_player_name%"
      name: "&7Игрок &e%ctg_player_name%"
    }
  }
}

items: [
  {
    slot: 27
    material: ARROW
    name: "&e&l<<"
    click {
      pagePrev: 1
    }
  },
  {
    slot: 35
    material: ARROW
    name: "&e&l>>"
    click {
      pageNext: 1
    }
  }
]

Это статические предметы с действиями переключения страниц. Они показываются на всех страницах, пока не повесишь на них правила. Так можно добавить любые статические кнопки - в них тоже работают плейсхолдеры каталога.

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

Контекстные плейсхолдеры - сердце автогенерируемых меню. Каждый каталог опирается на один из Экстракторов значений. Логика та же, что и в контексте активатора, отличается только префикс: ctg_ вместо activator_.

При генерации для каждого объекта каталога создаётся свой набор плейсхолдеров - и пользоваться ими можно почти везде в меню.

Выглядят они так:

%ctg_<placeholder>%

ctg_ - сокращение от catalog. <placeholder> - конкретный плейсхолдер из экстрактора, который тянет каталог, либо один из общих плейсхолдеров каталога из таблицы ниже.

Плейсхолдер	Тип	Описание
page	Number	Индекс текущей страницы
pages	Number	Общее количество страниц меню
page_next	Number	Индекс следующей страницы
page_prev	Number	Индекс предыдущей страницы
elements	Number	Общее количество объектов каталога

Например, плейсхолдер page из таблицы пишется как %ctg_page%.

Каталоги

Каталог - это динамическая коллекция объектов одного типа. У каждого каталога свой уникальный идентификатор и набор дополнительных параметров - всё это указывается в блоке catalog.

Плейсхолдеры каталог отдаёт через один из Экстракторов значений. Чтобы узнать набор плейсхолдеров конкретного каталога, смотри его экстрактор и добавляй префикс ctg_. Их можно использовать в шаблонах генерации. Ниже - каталоги, которые AbstractMenus даёт из коробки.

Players

Тип: PLAYERS

Тип экстрактора: extractor-entity

Отдаёт всех игроков в онлайне. Каталог опирается на extractor-entity, а все объекты тут - игроки, поэтому к любому обычному плейсхолдеру можно приклеить префикс ctg_. Пример:

catalog {
  type: PLAYERS
}

matrix {
  cells: [
    "_________",
    "_xxxxxxx_",
    "_xxxxxxx_",
    "_________",
  ]
  templates {
    "x" {
      skullOwner: "%ctg_player_name%"
      name: "Уровень игрока: %ctg_player_level%"
    }
  }
}

После ctg_ пишется любой плейсхолдер без % - он раскроется в контексте игрока из каталога.

В примере мы взяли player_name - он есть и в PlaceholderAPI, и среди встроенных плейсхолдеров.

Worlds

Тип: WORLDS

Тип экстрактора: extractor-world

Возвращает все миры сервера.

Entities

Тип: ENTITIES

Тип экстрактора: extractor-entity

Отдаёт все сущности из мира игрока (или из указанного мира). Список можно сузить фильтрами.

world - опционально. Имя мира. Если задан, сущности берутся из этого мира, а не из мира зрителя. Поддерживает плейсхолдеры.
allowedTypes - опционально. Список строк. Если задан, в результат попадают только сущности указанных типов. Полный список типов - здесь.

Пример:

catalog {
  type: ENTITIES
  world: "world_nether"
  allowedTypes: [ ZOMBIE, SKELETON ]
}

Серверы BungeeCord

Тип: BUNGEE_SERVERS

Тип экстрактора: Собственный экстрактор. См. плейсхолдеры ниже

Отдаёт все серверы BungeeCord. Работает только когда в конфиге плагина выставлено bungeecord: true. У каталога свой экстрактор с такими плейсхолдерами:

Плейсхолдер	Тип	Описание
server_name	String	Имя сервера
server_online	Number	Количество игроков на сервере

Iterator

Тип: ITERATOR

Тип экстрактора: Собственный экстрактор. См. плейсхолдеры ниже

Отдаёт список чисел от A до B. Удобно, когда нужно ровно N предметов из шаблона.

Три параметра:

start - Number. Стартовое значение (включительно).
end - Number. Конечное значение (включительно).
desc - [опционально]. Boolean. Если true, числа пойдут в обратном порядке. То есть start: 1, end: 10 даст 10, 9, 8, ..., 1.

В этих параметрах работают обычные плейсхолдеры (не каталоговые). Например, можно подставить значение переменной.

У каталога свой экстрактор с такими плейсхолдерами:

Плейсхолдер	Тип	Описание
index	Number	Текущее число

Slice

Тип: slice

Тип экстрактора: Собственный экстрактор. См. плейсхолдеры ниже

Режет строку на части по разделителю. Удобно, когда плейсхолдер возвращает список через запятую, а нужно по одному элементу меню на каждую часть.

catalog {
  type: slice
  value: "%my_csv_placeholder%"
  separator: ","
  trim: true
}

value - строка для разбиения. Плейсхолдеры раскрываются для каждого зрителя.
separator - разделитель, уходит в String.split (Java regex).
trim - опционально. Если true, у каждой части обрезаются пробелы по краям. По умолчанию true.

Пустые части каталог отбрасывает: "a,,b" с разделителем , даст два элемента (a, b), а не три.

У каталога свой экстрактор с такими плейсхолдерами:

Плейсхолдер	Тип	Описание
slice_element	String	Текущий элемент

Это весь список встроенных каталогов. Сама система рассчитана на то, чтобы её расширяли своими каталогами под конкретные задачи. Существующие будем дорабатывать, новые - добавлять.