Guild
Visão geral
O Guild permite que os jogadores fundem uma guilda, convidem outros, gerenciem ranks e compartilhem um banco. Tudo funciona com comandos /guild, e você pode adicionar um menu construído no painel web para que os jogadores nunca precisem digitar. Uma guilda tem um líder e qualquer quantidade de oficiais, membros e recrutas.
Todas as guildas são armazenadas em um único Guild Artifact e mantidas na memória para leituras rápidas. Com a ponte do MySQL e o Redis, cada alteração é transmitida aos outros servidores da rede, e o banco da guilda é uma linha separada no banco de dados, de modo que dois servidores nunca podem gastar as mesmas moedas duas vezes.
O menu é um menu do GUI. Você projeta seu layout e suas telas, marca itens como botões de guilda e a extensão adiciona as cabeças dos membros e os banners de convite.
Recursos
- Guildas e cargos — líder, oficial, membro e recruta, com criar, convidar, expulsar, promover, transferir e dissolver.
- Convites — convide por nome, entre com
/guild join, aceite ou recuse pelo menu com uma caixa de busca. - Menu da guilda — uma entry carrega todas as telas, com cabeças de membros, paginação e abas.
- Botões sensíveis ao estado — os botões que não se aplicam ao jogador (criar estando em uma guilda, dissolver sem ser líder) são removidos do layout.
- Banco da guilda — deposite e saque usando o saldo do NumericalStorage do jogador, com linhas atômicas no banco de dados.
- Sincronização entre servidores — criação, participação, cargos, banco e remoção chegam a todos os servidores do grupo.
- Placeholders — nome, cargo, líder, tamanho, contagem de online, banco, nomes dos membros e uma busca por jogador.
- Comandos de admin — liste guildas, inspecione uma, dissolva ou expulse em nome de um líder.
Instalação
- Instale a extensão GUI, que desenha o menu.
- Instale a extensão NumericalStorage se os jogadores forem usar o banco. Ela fornece o saldo que os depósitos e saques usam.
- Opcional, para vários servidores: instale a extensão MySQL, ative o Redis (ou Valkey) e defina o mesmo
redis.group-idem todos os servidores. O banco da guilda também exige a extensão MySQL, veja Banco da guilda. - Coloque o JAR do Guild em
plugins/Typewriter/extensions/e reinicie o servidor. - Crie um Guild Artifact em uma página static e publique.
guild.use é concedida a todos por padrão e guild.admin aos operadores.
Primeiros passos
Construa um menu de guilda que abre com /guild:
- No painel web do TypeWriter, adicione um Guild Artifact em uma página static. Mantenha
artifactIdcomobtc_guild_data. - Adicione uma entry Guild Menu.
/guildabre o primeiro Guild Menu encontrado. - Defina
inventoryTitle,inventoryRowseguiType, construa o layout emlayoutPoole definamainLayoutId. Veja os guias do GUI. - Declare suas telas em
views(por exemplomain,members,join). Coloque os ids das telas que listam membros emmemberListViewIdse o id da tela que lista convites pendentes emjoinListViewIds. - Adicione itens e defina
buttonTypecom botões de guilda:GUILD_MEMBERSeGUILD_BANKabrem telas,GUILD_LEAVEeGUILD_DISBANDsão executados imediatamente ePAGE_NAVpercorre as páginas de uma lista. - Para botões que precisam de um nome digitado (criar, convidar, expulsar, promover, transferir), dê ao item um diálogo
inputcujoonInputCommandsexecuta o comando, por exemploguild create {input}. - Publique e execute
/guild.
Uma tela com o id join é a que GUILD_JOIN e GUILD_PENDING_INVITES abrem. Adicione join a views e a joinListViewIds e dê a ela um item com um diálogo input que execute guild joinsearch {input} para que os jogadores filtrem os convites pelo nome da guilda.
Como funciona
As guildas são carregadas na memória ao iniciar. Após cada alteração, a guilda é salva no artifact em segundo plano e transmitida aos outros servidores, que substituem sua cópia. Os convites pendentes são mantidos apenas na memória e não são salvos.
Menus
O Guild Menu é um menu do GUI com estes comportamentos específicos de guilda.
Painel de conteúdo. Em uma tela listada em memberListViewIds, cada membro é uma cabeça de jogador, com o líder primeiro, mostrando seu cargo e status online. Se você é o líder, o clique esquerdo promove um membro e o clique direito o expulsa. Em uma tela listada em joinListViewIds, cada convite pendente é um banner: o clique esquerdo entra, o clique direito recusa. O painel é posicionado com contentX, contentY, contentColumns e contentRows.
Botões. Estes valores de buttonType funcionam de imediato:
buttonType | Clique |
|---|---|
GUILD_MEMBERS | Abre a tela members (guild open members). |
GUILD_BANK | Abre a tela bank (guild open bank). |
GUILD_ALLIANCES, GUILD_WARS | Abre as telas allies ou wars (veja a observação abaixo). |
GUILD_LEAVE | Sai da guilda. |
GUILD_DISBAND | Dissolve a guilda (somente o líder). |
GUILD_JOIN, GUILD_PENDING_INVITES | Muda para a view join do mesmo menu. |
NAV_BACK, NAV_CLOSE | Voltar, fechar o menu. |
PAGE_NAV | Clique esquerdo avança, clique direito volta; o nome mostra o contador de páginas. Oculto quando uma página basta. |
Estes valores não anexam nenhuma ação. Eles se destinam a itens que você mesmo configura (texto de exibição ou um diálogo input que executa o comando correspondente): 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.
Botões ocultos. Os itens são removidos do layout quando não se aplicam: GUILD_CREATE e GUILD_JOIN quando o jogador já tem uma guilda; GUILD_INVITE a menos que o jogador seja líder ou oficial; GUILD_LEAVE, GUILD_MEMBERS, GUILD_BANK, GUILD_ALLIANCES e GUILD_WARS sem uma guilda; GUILD_DISBAND a menos que o jogador seja o líder.
Comandos de slot. Os itens podem executar 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> e guild transfer <name>. Eles são executados como o jogador que clicou.
As guildas armazenam uma lista de aliados, uma lista de inimigos e um nível, e os placeholders os expõem, mas nenhum comando ou botão desta versão os altera: o nível permanece em 1 e não existe comando de rebaixamento. As telas allies e wars só existem se você as construir.
Os textos padrão do menu (título "Guilde", lore das cabeças) e as respostas de guild admin estão em francês. As mensagens de chat para os jogadores estão em inglês. Sobrescreva os textos do menu no seu layout.
Banco da guilda
O banco trabalha com o saldo da guilda na tabela btc_guild_bank (o nome não segue table-prefix), criada automaticamente no banco de dados MySQL. Cada operação é atômica, então depósitos e saques de servidores diferentes não conseguem deixar o banco no negativo.
/guild deposit <amount>retira moedas do saldo do jogador no NumericalStorage e as adiciona ao banco. Qualquer membro pode depositar./guild withdraw <amount>move moedas do banco para o jogador. Apenas o líder e os oficiais podem sacar.- Se o banco não puder ser alcançado, um depósito é reembolsado e o jogador é informado de que o armazenamento está temporariamente indisponível.
Sem a extensão MySQL ativada, ou sem o NumericalStorage, o banco não pode ser usado.
Comandos
Todos os comandos exigem guild.use. Aliases: /g, /guilde. O comando sem argumentos abre o primeiro Guild Menu e não imprime nada quando não existe nenhum.
| Comando | Descrição |
|---|---|
/guild | Abre o menu da guilda. |
/guild create <name> | Cria uma guilda. O nome deve ter de 3 a 16 letras ou dígitos. |
/guild invite <player> | Convida um jogador (líder ou oficial). |
/guild join <guild> | Entra em uma guilda para a qual você foi convidado. |
/guild leave | Sai da sua guilda. Um líder com membros deve transferir ou dissolver antes. |
/guild kick <player> | Expulsa um membro (o líder, ou um oficial para quem não é oficial). |
/guild promote <player> | Recruta para membro, membro para oficial (somente o líder). |
/guild transfer <player> | Passa a liderança. O antigo líder se torna oficial. |
/guild deposit <amount> | Coloca moedas no banco da guilda. |
/guild withdraw <amount> | Retira moedas do banco (líder ou oficial). |
/guild info | Imprime o líder, a contagem de membros, o nível e o banco da sua guilda. |
/guild disband | Dissolve sua guilda (somente o líder). |
/guild admin list | Lista todas as guildas (exige guild.admin). |
/guild admin info <guild> | Mostra uma guilda. |
/guild admin disband <guild> | Dissolve uma guilda. O líder dela deve estar online. |
/guild admin kick <guild> <player> | Expulsa um membro. O líder da guilda deve estar online. |
Permissões
| Permissão | Padrão | Concede |
|---|---|---|
guild.use | Todos | Todos os comandos /guild. Os cliques nos menus executam as mesmas ações sem verificá-la. |
guild.admin | Operadores | Os comandos /guild admin. |
Placeholders
Tags MiniPlaceholders para texto MiniMessage, como <guild_name>.
| Placeholder | Retorna |
|---|---|
<guild_in_guild> | 1 quando o jogador está em uma guilda, caso contrário 0. |
<guild_name> | Nome da guilda, vazio sem uma guilda. |
<guild_role> | LEADER, OFFICER, MEMBER ou RECRUIT. |
<guild_leader> | Nome do líder. |
<guild_size>, <guild_members> | Número de membros (ambos retornam o mesmo valor). |
<guild_online_count> | Membros online neste servidor. |
<guild_level> | Nível da guilda (atualmente sempre 1), 0 sem uma guilda. |
<guild_bank> | Saldo do banco conforme armazenado neste servidor. |
<guild_allies_count>, <guild_enemies_count> | Número de aliados e inimigos. |
<guild_list> | Nomes dos membros separados por vírgula. |
<guild_member_name:index> | Nome do membro nessa posição, começando em 0. |
<guild_of:name> | Guilda do jogador indicado, vazio quando não há. |
Entries
2 entradas, geradas a partir do código-fonte da extensão.
Ações1
- Guild MenuGuild Menu
Artefatos1
- Guild ArtifactArtifact for storing guild data
Solução de problemas
As guildas sumiram após uma reinicialização. Nenhum Guild Artifact está publicado, então nada é salvo. Adicione-o em uma página static e publique.
/guild create responde "Guild name must be alphanumeric and between 3-16 characters." Os nomes aceitam apenas letras e dígitos, sem espaços nem sublinhado.
/guild não imprime nada. Não há uma entry Guild Menu. Crie e publique uma. Subcomandos como /guild info funcionam sem ela.
Os depósitos falham com "Insufficient funds". O depósito lê o saldo do jogador no NumericalStorage. Instale o NumericalStorage e verifique se o jogador tem moedas suficientes lá.
"Guild bank storage is temporarily unavailable." A tabela do banco não pôde ser alcançada. Ative a extensão MySQL (mysql.enabled: true) e verifique a conexão com o banco de dados nos logs. O depósito é reembolsado.
Uma guilda criada em um servidor não existe no outro. Cada servidor precisa do mesmo redis.group-id, de um redis.server-name único e de mysql.enabled: true para que o artifact seja compartilhado. Sem um group-id, nada é transmitido.
As cabeças dos membros ou os banners de convite não aparecem. A tela ativa não está listada em memberListViewIds nem em joinListViewIds. Quando views está vazio, o menu usa view: defina-o como members ou join.
Extensões relacionadas
- MySQL — mensageria Redis e o banco de dados por trás do banco da guilda.
- GUI — layouts, views e diálogos
inputusados pelo menu da guilda. - NumericalStorage — o saldo do jogador usado pelo banco.
- Friend e Party — os outros sistemas sociais.