Crate

Caixas de saque com recompensas ponderadas, chaves virtuais, marcos e um minijogo de abertura com escolha de cartas.

Privadasv0.0.2Economia e criação

RequerTypeWriter0.9BasicGUI

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral

O Crate adiciona caixas de loot ao seu servidor. Uma crate tem uma lista de recompensas, cada uma com uma raridade, e os jogadores a abrem gastando uma chave virtual. A recompensa vencedora é sorteada no servidor antes de qualquer animação começar, então nada que o jogador faça durante a abertura pode alterar o resultado. Abrir uma crate conta para os marcos, que podem disparar recompensas extras após um certo número de aberturas.

As recompensas são triggers do TypeWriter, então uma recompensa pode entregar um item, executar um comando, conceder um cosmético ou iniciar uma sequence. A abertura é exibida no mundo diante do jogador: uma prévia das recompensas em item displays flutuantes, ou um minijogo de escolher cartas. Os menus permitem que os jogadores naveguem pelas crates e pelas recompensas que cada uma pode dar.

A extensão roda no build BTC do TypeWriter (BTC Core, Paper/Folia) e é documentada aqui como referência.

Recursos

• Recompensas ponderadas — as raridades têm um peso, e a chance de cada recompensa é exibida nos menus.
• Chaves virtuais — as chaves são contadas por jogador no artifact de dados da crate, e uma é gasta a cada abertura.
• Aberturas seguras — uma chave é reservada primeiro e só é gasta quando a recompensa é revelada; uma desconexão, um timeout ou um reinício a reembolsa.
• Marcos — dispare recompensas extras após um número de aberturas.
• Minijogo de cartas — o jogador vira uma carta de uma grade de cartas viradas para baixo, enquanto a recompensa já foi decidida.
• Prévias no mundo — as recompensas flutuam ao redor do jogador em layouts PAGINATED, FLEX ou SIMPLE, com um NPC e um holograma opcionais.
• Menus — um menu global de crates e um menu de recompensas por crate, com molduras, paginação e botões personalizados.
• Estatísticas — aberturas, chaves, chaves usadas, última abertura e marco, disponíveis como placeholders.

Instalação

1. Instale a extensão Basic do TypeWriter e a extensão GUI (GuiAndDialogs no build BTC). O Crate não carrega sem elas.
2. Coloque o JAR do Crate em plugins/Typewriter/extensions/ e reinicie o servidor.
3. Conceda as permissões da seção Permissões à sua equipe.

Primeiros passos

Crie uma crate com três recompensas e dê uma chave a você mesmo:

1. No painel web do TypeWriter, abra uma page manifest e adicione um artifact Crate Data. Mantenha o artifactId gerado e use um artifact por crate.
2. Adicione uma entry Crate. Defina dataArtifact como o artifact e escreva a noKeyMessage.
3. Em rarities, adicione Common com peso 70 e Rare com peso 30.
4. Em rewards, adicione três recompensas: para cada uma, defina uma rarity, um item exibido na prévia, um name e, em action, um trigger que entrega a recompensa. Mantenha grantItem ativado para entregar o item automaticamente, ou desative-o se a action entregar o item por conta própria.
5. Em rewardSlots, liste os slots de inventário do menu de recompensas (contados a partir de 0), por exemplo 10-12. Uma crate sem slot de recompensa se recusa a abrir.
6. Em icon, defina o x e o y da crate no menu global, um item e um name.
7. Adicione uma ação Open Crate apontando para a crate e dispare-a a partir de um NPC, um bloco ou um item.
8. Publique e depois execute /tw crate give <crate entry id> 5 e abra a crate. Use /tw crate menu para navegar pelas crates.

Cliques em recompensas no menu de recompensas

No menu de recompensas de uma crate, clicar em uma recompensa dispara diretamente a action dessa recompensa, sem gastar chave e sem estatísticas. Não dê aos jogadores acesso ao menu de recompensas se a action de alguma recompensa entregar algo valioso, ou reserve o menu para a equipe.

Entregando chaves

As chaves são adicionadas com /tw crate give <crate> <amount> [targets]. Não há uma ação dedicada para chaves, mas uma ação de comando pode executar esse comando, por exemplo a partir da recompensa de uma quest ou de uma loja.

Como funciona

A chance de uma recompensa é o peso da sua raridade dividido pelo peso total de todas as recompensas. Uma recompensa cuja raridade não está listada em rarities tem peso 1. Quando a recompensa é revelada, a chave é gasta, os contadores de aberturas e de chaves usadas sobem, qualquer marco atingido dispara, e então o item é entregue (se grantItem estiver ativado) e a action da recompensa é executada. Um jogador só pode ter uma abertura por vez.

Menus

• Menu global — aberto com /tw crate menu. Mostra um ícone por crate, posicionado no x (0 a 8) e y (0 a 5) do ícone, e clicar em um ícone abre o menu de recompensas daquela crate. Uma entry opcional Crate Main Menu define o tamanho, o título, a moldura, os botões, os itens por página e a coluna reservada para as setas de paginação.
• Menu de recompensas — aberto clicando em um ícone ou com a ação Open Crate Menu. Mostra as recompensas em rewardSlots, com seu nome, lore e linhas opcionais de chance e raridade (chanceLore e rarityLore, usando {chance} e {rarity}). guiLayout é PAGINATED, FLEX (centralizado, quatro colunas) ou SIMPLE. frameItem, itemsPerPage e paginationColumn ajustam a moldura e a paginação, e buttons adiciona botões personalizados com uma ação.

Os botões têm um tipo (INFORMATION, NEXT, PREVIOUS, FILL) e uma posição. Um botão FILL é copiado para todo slot vazio. Os marcadores crate_button: (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) são oferecidos no editor do GUI, mas nesta versão mostram apenas um item provisório.

Configuração

O Crate não tem arquivo de configuração. Tudo é configurado em entries. Os dados do jogador ficam no artifact Crate Data: chaves, aberturas, chaves usadas, horário da última abertura, marco e aberturas pendentes. Ele é gravado de forma assíncrona, e as aberturas pendentes deixadas por uma falha são recuperadas na inicialização (a chave é reembolsada).

Comandos

Todos os comandos são subcomandos do comando do TypeWriter, então começam com /typewriter ou /tw. <crate> é a entry de uma crate e tem autocompletar.

Comando	Descrição	Permissão
/tw crate menu	Abre o menu global de crates.	typewriter.crate.menu
/tw crate open <crate>	Abre a crate, usando uma chave.	typewriter.crate.open
/tw crate give <crate> [targets]	Dá uma chave a você ou aos jogadores selecionados.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Dá várias chaves.	typewriter.crate.give
/tw crate remove <crate> [targets]	Remove uma chave, somente se o jogador tiver uma.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Remove várias chaves, somente se o jogador tiver o suficiente.	typewriter.crate.remove

A permissão base typewriter.crate protege o comando inteiro. A extensão registra um comando interno /cratemenu usado pelos cliques nos menus; ele não se destina a ser digitado.

Permissões

Permissão	Concede
typewriter.crate	Acesso ao comando /tw crate.
typewriter.crate.menu	/tw crate menu.
typewriter.crate.open	/tw crate open.
typewriter.crate.give	/tw crate give.
typewriter.crate.remove	/tw crate remove.

Placeholders

São tags MiniPlaceholders da expansão crate. Substitua id pelo ID da entry da crate. Uma crate desconhecida retorna um valor vazio.

Placeholder	Retorna
<crate_openings:id>	Número de aberturas desta crate pelo jogador.
<crate_keys:id>	Chaves que o jogador possui.
<crate_keys_used:id>	Chaves que o jogador gastou.
<crate_last_open:id>	Horário da última abertura, em milissegundos desde 1º de janeiro de 1970.
<crate_milestone:id>	O maior marco atingido.

Em hologramLines, use os tokens {openings}, {keys}, {last_open} e {milestone} no lugar.

Entries

6 entradas, geradas a partir do código-fonte da extensão.

Ações2

• Open CrateOuvre une caisse
• Open Crate MenuOuvre le menu d'une caisse

Artefatos1

• Crate ArtifactDonnées de caisse

Manifestos3

• CrateDéfinition d’une caisse
• Crate Main MenuApparence du menu principal
• Crate Minigame CardsMini-jeu Caisse : Cartes

Solução de problemas

"This crate is not configured correctly". A crate falhou na validação, e o log do servidor lista os motivos: nenhuma recompensa, um peso de raridade inválido (deve ser maior que zero), nenhum rewardSlots ou slots fora de 0 a 53 ou duplicados, um botão ou icon fora da grade de 9 por 6, ou marcos em zero aberturas ou duplicados. As mesmas verificações são executadas na inicialização e registram um aviso.

O jogador recebe a noKeyMessage. O jogador não tem chave para essa crate, ou a crate não tem dataArtifact. Entregue chaves com /tw crate give e verifique a ligação do artifact.

"You are already opening a crate". Há uma abertura em andamento para esse jogador. Ela termina quando a recompensa é revelada ou o jogador se desconecta.

As estatísticas e as chaves não mudam após uma abertura. Elas só mudam quando a recompensa é revelada. Se o jogador saiu ou o servidor parou antes disso, a chave é reembolsada e os contadores permanecem iguais.

A prévia não mostra nada ou mostra as recompensas erradas. A prévia usa o item de cada recompensa. As recompensas com item vazio são ignoradas, e preview.maxVisibleRewards limita quantas aparecem de uma vez. preview.distance e os deslocamentos *Location movem a exibição.

O minijogo de cartas não inicia. Ligue uma entry Crate Minigame: Cards no campo minigame da crate. Seu columns vai até 10 e rows até 10, e cardCount é limitado a 100.

Uma recompensa é entregue duas vezes. Mantenha grantItem ativado apenas quando a action não entregar também o item.

Extensões relacionadas

• GUI — motor de menus usado pelos menus de crate.