Guild
Обзор
Guild позволяет игрокам основывать гильдию, приглашать других, управлять рангами и пользоваться общим банком. Всё работает через команды /guild, а вы можете добавить меню, созданное в веб-панели, чтобы игрокам вообще не приходилось вводить команды. В гильдии один лидер и любое число офицеров, участников и рекрутов.
Все гильдии хранятся в одном артефакте Guild Artifact и держатся в памяти для быстрого чтения. С мостом MySQL и Redis каждое изменение рассылается на остальные серверы сети, а банк гильдии — отдельная строка в базе данных, поэтому два сервера никогда не смогут потратить одни и те же монеты дважды.
Меню — это меню GUI. Вы проектируете его макет и экраны, помечаете предметы как кнопки гильдии, а расширение добавляет головы участников и баннеры приглашений.
Возможности
- Гильдии и роли — лидер, офицер, участник и рекрут, с созданием, приглашением, исключением, повышением, передачей и роспуском.
- Приглашения — приглашение по имени, вступление через
/guild join, принятие или отклонение из меню с полем поиска. - Меню гильдии — одна запись содержит все экраны, с головами участников, постраничным просмотром и вкладками.
- Кнопки с учётом состояния — кнопки, не применимые к игроку (создание, когда он в гильдии, роспуск, когда он не лидер), удаляются из макета.
- Банк гильдии — внесение и снятие с использованием баланса игрока в NumericalStorage, с атомарными строками в базе данных.
- Синхронизация между серверами — создание, состав, роли, банк и удаление доходят до каждого сервера группы.
- Плейсхолдеры — название, роль, лидер, размер, число в сети, банк, имена участников и поиск по игроку.
- Административные команды — список гильдий, просмотр одной, роспуск или исключение от имени лидера.
Установка
- Установите расширение GUI, которое отрисовывает меню.
- Установите расширение NumericalStorage, если игроки должны пользоваться банком. Оно предоставляет баланс, который используют внесение и снятие.
- По желанию, для нескольких серверов: установите расширение MySQL, включите Redis (или Valkey) и задайте одинаковый
redis.group-idна каждом сервере. Банк гильдии также требует расширения MySQL, см. Банк гильдии. - Положите JAR-файл Guild в
plugins/Typewriter/extensions/и перезапустите сервер. - Создайте Guild Artifact на странице static и опубликуйте.
guild.use по умолчанию выдаётся всем, а guild.admin — операторам.
Быстрый старт
Создадим меню гильдии, открывающееся командой /guild:
- В веб-панели TypeWriter добавьте Guild Artifact на странице static. Оставьте
artifactIdравнымbtc_guild_data. - Добавьте запись Guild Menu.
/guildоткрывает первое найденное Guild Menu. - Задайте
inventoryTitle,inventoryRowsиguiType, постройте макет вlayoutPoolи задайтеmainLayoutId. См. руководства по GUI. - Объявите свои экраны в
views(напримерmain,members,join). Поместите id экранов со списками участников вmemberListViewIds, а id экрана со списком ожидающих приглашений — вjoinListViewIds. - Добавьте предметы и задайте
buttonTypeкнопок гильдии:GUILD_MEMBERSиGUILD_BANKоткрывают экраны,GUILD_LEAVEиGUILD_DISBANDвыполняются сразу, аPAGE_NAVлистает список. - Для кнопок, которым нужно введённое имя (создание, приглашение, исключение, повышение, передача), задайте предмету диалог
input, чьёonInputCommandsвыполняет команду, напримерguild create {input}. - Опубликуйте и выполните
/guild.
Экран с id join — это то, что открывают GUILD_JOIN и GUILD_PENDING_INVITES. Добавьте join в views и в joinListViewIds и задайте ему предмет с диалогом input, выполняющим guild joinsearch {input}, чтобы игроки могли фильтровать приглашения по названию гильдии.
Как это работает
Гильдии загружаются в память при запуске. После каждого изменения гильдия сохраняется в артефакт в фоне и рассылается на другие серверы, которые заменяют свою копию. Ожидающие приглашения хранятся только в памяти и не сохраняются.
Меню
Guild Menu — это меню GUI со следующими особенностями поведения, относящимися к гильдии.
Панель содержимого. На экране из списка memberListViewIds каждый участник — это голова игрока, лидер первым, с его ролью и статусом в сети. Если вы лидер, левый клик повышает участника, а правый клик исключает его. На экране из списка joinListViewIds каждое ожидающее приглашение — баннер: левый клик вступает, правый клик отклоняет. Панель размещается через contentX, contentY, contentColumns и contentRows.
Кнопки. Эти значения buttonType работают из коробки:
buttonType | Клик |
|---|---|
GUILD_MEMBERS | Открывает экран members (guild open members). |
GUILD_BANK | Открывает экран bank (guild open bank). |
GUILD_ALLIANCES, GUILD_WARS | Открывают экраны allies или wars (см. примечание ниже). |
GUILD_LEAVE | Покидает гильдию. |
GUILD_DISBAND | Распускает гильдию (только лидер). |
GUILD_JOIN, GUILD_PENDING_INVITES | Переключают на представление join того же меню. |
NAV_BACK, NAV_CLOSE | Назад, закрыть меню. |
PAGE_NAV | Левый клик — вперёд, правый клик — назад; в названии показан счётчик страниц. Скрыт, когда достаточно одной страницы. |
Эти значения не привязывают действия. Они предназначены для предметов, которые вы настраиваете сами (отображаемый текст или диалог input, выполняющий соответствующую команду): GUILD_INFO, GUILD_MEMBER_MANAGE, GUILD_INVITE, GUILD_CREATE, GUILD_KICK, GUILD_PROMOTE, GUILD_DEMOTE, GUILD_TRANSFER, GUILD_ALLY_ADD, GUILD_ALLY_REMOVE, GUILD_WAR_DECLARE, GUILD_WAR_END, GUILD_BANK_DEPOSIT, GUILD_BANK_WITHDRAW, GUILD_ACCEPT_INVITE, GUILD_DECLINE_INVITE.
Скрытые кнопки. Предметы удаляются из макета, когда не применимы: GUILD_CREATE и GUILD_JOIN, когда у игрока уже есть гильдия; GUILD_INVITE, если игрок не лидер и не офицер; GUILD_LEAVE, GUILD_MEMBERS, GUILD_BANK, GUILD_ALLIANCES и GUILD_WARS без гильдии; GUILD_DISBAND, если игрок не лидер.
Команды слотов. Предметы могут выполнять guild open [view], guild page next|prev|<number>, guild create <name>, guild invite <name>, guild join <guild>, guild declineinvite <guild>, guild joinsearch <text>, guild leave, guild disband, guild kick <name>, guild promote <name> и guild transfer <name>. Они выполняются от имени кликнувшего игрока.
Гильдии хранят список союзников, список врагов и уровень, и плейсхолдеры их показывают, но ни одна команда или кнопка в этой версии их не меняет: уровень остаётся 1, а команды понижения нет. Экраны allies и wars существуют, только если вы их создадите.
Тексты меню по умолчанию (заголовок «Guilde», описание голов) и ответы guild admin — на французском. Сообщения чата для игроков — на английском. Переопределите текст меню в своём макете.
Банк гильдии
Банк работает с балансом гильдии в таблице btc_guild_bank (её имя не следует table-prefix), создаваемой автоматически в базе данных MySQL. Каждая операция атомарна, поэтому внесение и снятие с разных серверов не могут увести банк в минус.
/guild deposit <amount>забирает монеты с баланса игрока в NumericalStorage и добавляет их в банк. Вносить может любой участник./guild withdraw <amount>переводит монеты из банка игроку. Снимать могут только лидер и офицеры.- Если банк недоступен, внесение возвращается, а игроку сообщается, что хранилище временно недоступно.
Без включённого расширения MySQL или без NumericalStorage банком пользоваться нельзя.
Команды
Для всех команд нужно guild.use. Псевдонимы: /g, /guilde. Голая команда открывает первое Guild Menu и ничего не выводит, если его нет.
| Команда | Описание |
|---|---|
/guild | Открывает меню гильдии. |
/guild create <name> | Создаёт гильдию. Название должно состоять из 3–16 букв или цифр. |
/guild invite <player> | Приглашает игрока (лидер или офицер). |
/guild join <guild> | Вступает в гильдию, в которую вас пригласили. |
/guild leave | Покидает вашу гильдию. Лидер с участниками должен сначала передать лидерство или распустить гильдию. |
/guild kick <player> | Исключает участника (лидер или офицер — неофицеров). |
/guild promote <player> | Рекрут до участника, участник до офицера (только лидер). |
/guild transfer <player> | Передаёт лидерство. Прежний лидер становится офицером. |
/guild deposit <amount> | Кладёт монеты в банк гильдии. |
/guild withdraw <amount> | Забирает монеты из банка (лидер или офицер). |
/guild info | Выводит лидера, число участников, уровень и банк вашей гильдии. |
/guild disband | Распускает вашу гильдию (только лидер). |
/guild admin list | Выводит все гильдии (требуется guild.admin). |
/guild admin info <guild> | Показывает одну гильдию. |
/guild admin disband <guild> | Распускает гильдию. Её лидер должен быть в сети. |
/guild admin kick <guild> <player> | Исключает участника. Лидер гильдии должен быть в сети. |
Права
| Право | По умолчанию | Даёт доступ к |
|---|---|---|
guild.use | Все | Всем командам /guild. Клики в меню выполняют те же действия без проверки этого права. |
guild.admin | Операторы | Командам /guild admin. |
Плейсхолдеры
Теги MiniPlaceholders для текста MiniMessage, например <guild_name>.
| Плейсхолдер | Возвращает |
|---|---|
<guild_in_guild> | 1, когда игрок в гильдии, иначе 0. |
<guild_name> | Название гильдии, пусто без гильдии. |
<guild_role> | LEADER, OFFICER, MEMBER или RECRUIT. |
<guild_leader> | Имя лидера. |
<guild_size>, <guild_members> | Число участников (оба возвращают одно значение). |
<guild_online_count> | Участники в сети на этом сервере. |
<guild_level> | Уровень гильдии (сейчас всегда 1), 0 без гильдии. |
<guild_bank> | Баланс банка, как он хранится на этом сервере. |
<guild_allies_count>, <guild_enemies_count> | Число союзников и врагов. |
<guild_list> | Имена участников через запятую. |
<guild_member_name:index> | Имя участника на этой позиции, начиная с 0. |
<guild_of:name> | Гильдия названного игрока, пусто, если её нет. |
Записи
Записей: 2, сгенерированы из исходного кода расширения.
Действия1
- Guild MenuGuild Menu
Артефакты1
- Guild ArtifactArtifact for storing guild data
Устранение неполадок
Гильдии пропали после перезапуска. Не опубликован ни один Guild Artifact, поэтому ничего не сохраняется. Добавьте его на странице static и опубликуйте.
/guild create отвечает «Guild name must be alphanumeric and between 3-16 characters.» Названия принимают только буквы и цифры, без пробелов и подчёркиваний.
/guild ничего не выводит. Нет записи Guild Menu. Создайте и опубликуйте её. Подкоманды вроде /guild info работают и без неё.
Внесение завершается ошибкой «Insufficient funds». Внесение читает баланс игрока в NumericalStorage. Установите NumericalStorage и проверьте, что у игрока там достаточно монет.
«Guild bank storage is temporarily unavailable.» Таблица банка недоступна. Включите расширение MySQL (mysql.enabled: true) и проверьте подключение к базе данных в логах. Внесение возвращается.
Гильдия, созданная на одном сервере, отсутствует на другом. Каждому серверу нужен одинаковый redis.group-id, уникальный redis.server-name и mysql.enabled: true, чтобы артефакт был общим. Без group-id ничего не рассылается.
Головы участников или баннеры приглашений не появляются. Активный экран не указан в memberListViewIds или joinListViewIds. Если views пуст, меню использует view: задайте его равным members или join.
Связанные расширения
- MySQL — обмен сообщениями через Redis и база данных за банком гильдии.
- GUI — макеты, представления и диалоги
input, используемые меню гильдии. - NumericalStorage — баланс игрока, используемый банком.
- Friend и Party — другие социальные системы.