Numerical Storage

Saldos numéricos nomeados por jogador com níveis, juros, um menu de banco e placeholders.

Gratuitasv0.15Economia e criação

RequerTypeWriter0.9GUI (GuiAndDialogs)PlaceholderAPIopcionalVaultopcionalProfilesopcional

BaixarCódigo-fonteSuporte

Visão geral

O Numerical Storage permite criar reservas numéricas nomeadas para cada jogador: uma conta bancária, uma reserva de mana, uma carteira de tokens, um estoque de qualquer recurso. Você descreve uma reserva uma única vez em uma definição, e a extensão salva um saldo e um nível por jogador.

Uma reserva pode ter níveis, cada um com uma capacidade máxima. Os jogadores depositam e sacam por meio de um menu de inventário construído com a extensão GUI. O dinheiro pode vir do seu plugin de economia por meio do Vault, ou de qualquer placeholder e comando de console que você escolher. Juros podem ser adicionados em um cronograma, e as reservas podem ser redefinidas, editadas ou abertas por comandos.

Os saldos são salvos em um artifact do TypeWriter e gravados de forma assíncrona, então um depósito nunca bloqueia a thread do servidor. Os saldos, níveis e a capacidade são expostos como placeholders do PlaceholderAPI para scoreboards, hologramas e menus.

Recursos

• Várias reservas — crie quantas definições precisar, cada uma com seu próprio nome, prefixo, níveis e menu.
• Níveis e capacidade — cada nível tem um saldo máximo; os jogadores fazem upgrade para aumentá-lo.
• Requisitos de nível — libere um nível com comparações de placeholders ou facts e, opcionalmente, cobre um custo.
• Juros — um cronograma cron, uma taxa global, uma taxa por nível e uma taxa por permissão, com um teto por ciclo.
• Vault ou comandos — depósitos e saques passam pelo Vault, ou por um placeholder mais comandos de console.
• Transferências — mova um saldo entre duas reservas de forma atômica.
• Botões de menu — quantia fixa, porcentagem, tudo, quantia personalizada (diálogo), submenus, upgrade e fechar.
• Persistência segura — gravações assíncronas, um bloqueio por artifact e migração automática de arquivos antigos.
• Modo de perfil — saldos opcionais por perfil com o MMOProfiles.
• Placeholders e comandos — leia valores em qualquer lugar e edite-os pelo console.

Instalação

1. Instale a extensão GUI: o Numerical Storage precisa dela para seus menus. A extensão GUI é publicada com o nome GuiAndDialogs.
2. Instale o PlaceholderAPI se quiser usar os placeholders %typewriter_ns_...%.
3. Opcional: instale o Vault (a extensão é compilada contra o VaultUnlocked) e um plugin de economia, para usar o modo de transação VAULT.
4. Opcional: instale o MMOProfiles para usar profileMode.
5. Coloque o JAR do Numerical Storage em plugins/Typewriter/extensions/ e reinicie o servidor.

A janela de quantia personalizada usa diálogos do Paper, então exige uma versão do Paper que os suporte (Minecraft 1.21.6 ou posterior).

Faça backup antes de atualizar

Desde a versão 0.9, os novos artifacts usam um identificador técnico e a versão 2 do esquema JSON. Na primeira vez que um arquivo antigo é lido, ele é copiado para o novo caminho, salvo em backups/numericalstorage/ e removido. Guarde uma cópia da pasta assets/ do TypeWriter antes de atualizar.

Primeiros passos

Crie um banco pago com a sua economia do Vault:

1. No painel web do TypeWriter, abra uma página de manifest e adicione um artifact Player Numerical Storage. Deixe artifactId vazio: o TypeWriter o gera.
2. Adicione uma Numerical Storage Definition. Defina displayName (por exemplo Bank), prefix e vincule o artifact em artifact.
3. Em levels, adicione o primeiro nível com um limit de 1000 e depois um segundo com 5000. Preencha depositMessage e levelUpMessage se quiser textos personalizados.
4. Em transaction, defina transactionMode como VAULT.
5. Em menu.transactionButtons, adicione um botão do tipo DEPOSIT com amountType FIXED, um amount de 100 e o item a exibir. Adicione um segundo do tipo WITHDRAW.
6. Adicione uma action Open Numerical Storage Menu. Vincule a definition.
7. Em seu layoutPool, adicione um layout simple com o id main e defina mainLayoutId como main. No layout, adicione um item com buttonPrefix definido como numericalstorage_button: e buttonType definido como DEPOSIT_FIXED:100. Faça o mesmo com WITHDRAW_FIXED:100, UPGRADE_LEVEL e NAV_CLOSE.
8. Vincule a action a um diálogo de NPC ou a um evento de comando, publique e abra o banco no jogo. Você também pode executar /typewriter ns open <definition>.

Uma entry de abertura de menu por definição

Após cada transação, o menu é reaberto para mostrar o novo saldo. A extensão procura uma entry Open Numerical Storage Menu vinculada à mesma definição. Sem uma, o menu é simplesmente fechado.

Como funciona

Menus

O menu é um layout normal do GUI. A action Open Menu o abre com o título e o número de linhas da definição (menu.title, menu.rows, de 1 a 6), e o seu layoutPool decide onde cada item fica. A extensão transforma um item em um botão funcional quando o item tem buttonPrefix definido como numericalstorage_button: e um buttonType desta lista:

buttonType	O que o botão faz
DEPOSIT_FIXED	Deposita uma quantia fixa. Adicione a quantia depois de dois-pontos, por exemplo DEPOSIT_FIXED:100.
DEPOSIT_PERCENT	Deposita uma porcentagem do saldo de origem, por exemplo DEPOSIT_PERCENT:50.
DEPOSIT_CUSTOM	Fecha o menu e pede uma quantia em um diálogo.
DEPOSIT_ALL	Deposita o saldo de origem, até a capacidade restante. Isso exige um amountPlaceholder: no modo VAULT, o botão tenta depositar toda a capacidade restante e falha se o saldo da economia for menor.
DEPOSIT_SUBMENU	Abre um submenu de botões de depósito. O id do submenu vem depois dos dois-pontos.
WITHDRAW_FIXED, WITHDRAW_PERCENT, WITHDRAW_CUSTOM, WITHDRAW_ALL, WITHDRAW_SUBMENU	O mesmo que acima, para saques. A porcentagem é calculada sobre o saldo armazenado.
TRANSFER_FIXED, TRANSFER_PERCENT, TRANSFER_ALL	Move saldo para outra definição. O botão vem de uma entrada de transactionButtons do tipo TRANSFER com um transferTarget.
SUB_MENU	Abre o submenu cujo id vem depois dos dois-pontos, por exemplo SUB_MENU:deposit_options.
UPGRADE_LEVEL	Faz upgrade para o próximo nível, ou mostra o item de nível máximo.
NAV_CLOSE	Fecha o menu.

Quando buttonType tem uma quantia (DEPOSIT_FIXED:100), a extensão escolhe a entrada de menu.transactionButtons com o mesmo tipo, tipo de quantia e quantia, e usa seu template como item. Sem uma quantia, usa a primeira entrada correspondente. Quando nada corresponde, é exibido um item de corante simples com o rótulo padrão.

Os submenus são definidos em menu.subMenus, como um mapa de um id para um título, um número de linhas, botões de transação posicionados em slots, um botão de voltar e um botão de fechar.

Um botão de transferência precisa do transferTarget da outra definição (o id da entry), e o jogador deve ter espaço na reserva de destino.

Comandos

Todos os comandos são subcomandos de /typewriter (alias /tw). <definition> é uma entry de definição. O [target] opcional seleciona outro jogador; sem ele, o comando se aplica a quem o executa.

Comando	Permissão	Descrição
/typewriter ns open <definition> [target]	typewriter.ns.open	Abre o menu da reserva, por meio de sua entry Open Menu.
/typewriter ns add <definition> <amount> [target]	typewriter.ns.add	Adiciona ao saldo. A capacidade não é verificada.
/typewriter ns remove <definition> <amount> [target]	typewriter.ns.remove	Remove do saldo, até 0.
/typewriter ns level <definition> <level> [target]	typewriter.ns.level	Define o nível e redefine o saldo para 0.
/typewriter ns reset <definition> [target]	typewriter.ns.reset	Redefine o nível para 1 e o saldo para 0.

Os comandos /typewriter numstorage tx ..., upgrade e back_main são usados internamente pelos botões do menu. Eles não fazem nada para um jogador sem um menu aberto.

Com profileMode ativado, add, remove, level e reset alteram o saldo e o nível do perfil do alvo, como faz o menu.

Respostas dos comandos

As respostas de add, remove, level, reset e open, e as respostas de erro abaixo, são os campos de adminMessages na definição. São MiniMessage. Cada uma pode usar <player>, <storage> (o id da definição) e <prefix>.

Campo	Placeholder extra	Padrão
resetMessage	nenhum	Numerical storage reset for <player>.
levelSetMessage	<level>	Set numerical storage level to <level> for <player>.
addMessage	<amount>	Added <amount> to <player>.
removeMessage	<amount>	Removed <amount> from <player>.
noMenuMessage	nenhum	A mensagem exibida quando o armazenamento não tem uma entrada Open Menu.
invalidAmountMessage	<amount> (o valor digitado)	Invalid amount '<amount>'. Use a positive number. Exibida por add e remove quando o valor não é um número positivo.
noArtifactMessage	nenhum	A mensagem exibida por add, remove, level e reset quando nenhum artifact está vinculado à definição.
noActiveProfileMessage	nenhum	<player> has no active profile. Mostrada por add, remove, level e reset, e ao jogador que clica em uma ação de menu, quando profileMode está ativado e o jogador não tem nenhum perfil do MMOProfiles ativo. Nada é gravado.

Os padrões começam com o prefixo do Typewriter. Três textos não pertencem a nenhuma definição, então são snippets em snippets.yml: numericalstorage.command.player_only (os comandos dos botões do menu executados por um não jogador) e os textos de placeholders numericalstorage.placeholder.interest_disabled (Disabled), numericalstorage.placeholder.interest_error (Error) e numericalstorage.placeholder.capacity_unlimited (o sinal de infinito). As unidades de tempo de interest_cooldown são os snippets numericalstorage.duration.days, hours, minutes, seconds (cada um um modelo com {value}, {value}j por padrão) e numericalstorage.duration.separator.

Permissões

Permissão	Concede
typewriter.ns.open	/typewriter ns open.
typewriter.ns.add	/typewriter ns add.
typewriter.ns.remove	/typewriter ns remove.
typewriter.ns.level	/typewriter ns level.
typewriter.ns.reset	/typewriter ns reset.
Permissões em interestRates	Dão a um jogador uma taxa de juros específica. Usa-se a primeira permissão da lista que o jogador possui.

Placeholders

Substitua <id> pelo id da entry da definição. Eles precisam do PlaceholderAPI e são lidos de um cache, então são seguros para uso em scoreboards. Com profileMode ativado, balance, level, capacity e interest seguem o perfil com o qual o jogador está jogando, como faz o menu.

Placeholder	Retorna
%typewriter_ns_balance_<id>%	O saldo atual.
%typewriter_ns_level_<id>%	O nível atual, começando em 1.
%typewriter_ns_capacity_<id>%	A capacidade do nível atual, ou o sinal de infinito quando nenhum nível está definido.
%typewriter_ns_interest_<id>%	A taxa de juros que se aplica ao jogador, em porcentagem.
%typewriter_ns_interest_cooldown_<id>%	O tempo até o próximo ciclo de juros agendado, ou Disabled.
%typewriter_ns_name_<id>%	O displayName da definição.
%typewriter_ns_prefix_<id>%	O prefix da definição.

Entries

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

Ações2

• Numericalstorage MenuOpens a Numerical Storage menu
• Numericalstorage Open MenuOpens a Numerical Storage menu (triggerable)

Artefatos1

• Player Numericalstorage ArtifactStores the numericalstorage amount per player

Manifestos1

• Numericalstorage DefinitionDefines a configurable numerical storage

Solução de problemas

O menu abre vazio ou os botões não fazem nada. Verifique se cada item tem buttonPrefix definido exatamente como numericalstorage_button: e um buttonType válido. Se o prefixo estiver errado, o item continua sendo um item normal, sem ação. Verifique também se mainLayoutId corresponde ao id de um layout em layoutPool.

O menu fecha após cada depósito. O menu é reaberto por meio de uma entry Open Numerical Storage Menu vinculada à mesma definição. Adicione uma, mesmo que você abra o menu com outra entry.

"Cannot add ... Would exceed limit". A reserva está na capacidade do nível do jogador (levels[].limit). Faça upgrade do nível ou aumente o limite. Sem nenhum nível definido, não há limite.

Um depósito no modo INTERNAL falha. O saldo de origem do jogador é lido com amountPlaceholder e deve retornar um número simples. O addCommand é executado pelo console antes do depósito e precisa ter sucesso. Use {player} e {amount} no comando.

"Economy system is not available." transactionMode é VAULT, mas o Vault ou um provedor de economia está ausente. Instale ambos e reinicie.

Os juros não são pagos. Os juros são aplicados quando um jogador entra, pelos ciclos do cron que passaram desde o último pagamento (no máximo 100 ciclos). interestEnabled deve estar ativado e interestCron preenchido. A primeira entrada apenas registra o horário inicial. Um saldo na capacidade de seu nível não rende nada.

O upgrade pede a capacidade como custo. Quando o próximo nível não tem criteria, o custo de um upgrade é o limit do nível atual, retirado do saldo armazenado. Adicione criteria ao próximo nível para definir outro requisito.

Os placeholders mostram o saldo de outro perfil. Com profileMode ativado, os placeholders e o botão de melhoria leem o saldo e o nível do perfil selecionado pelo jogador. Sem o MMOProfiles, leem o saldo do próprio jogador. Com o MMOProfiles e sem perfil ativo (tela de seleção, após /mmoprofiles quit), mostram 0, pois o UUID do jogador é o id do seu perfil Main e o saldo dele não deve ser exibido nem creditado. As gravações são recusadas com noActiveProfileMessage, e os juros de um perfil são acertados quando ele é selecionado.

Um placeholder aparece vazio logo após uma reinicialização. O armazenamento é carregado em segundo plano ao entrar: a primeira leitura pode vir antes do fim do carregamento; a seguinte mostra o valor guardado.

O placeholder está vazio. O id no placeholder deve ser o id da entry da definição, não o seu nome. Execute /papi parse me %typewriter_ns_balance_<id>% para testar.

Extensões relacionadas

• GUI — o motor de menus usado para os layouts e botões.
• MMOProfiles — opcional, usado por profileMode.