Aller au contenu principal

Numerical Storage

Soldes numériques nommés par joueur avec niveaux, intérêts, un menu bancaire et des placeholders.

Gratuitesv0.15Économie et artisanat
NécessiteTypeWriter0.9GUI (GuiAndDialogs)PlaceholderAPIfacultatifVaultfacultatifProfilesfacultatif
TéléchargerCode sourceSupport

Vue d'ensemble​

Numerical Storage vous permet de créer des réserves numériques nommées pour chaque joueur : un compte en banque, une réserve de mana, un portefeuille de jetons, un stock de n'importe quelle ressource. Vous décrivez une réserve une fois dans une définition, et l'extension enregistre un solde et un niveau par joueur.

Une réserve peut avoir des niveaux, chacun avec une capacité maximale. Les joueurs y déposent et y retirent de l'argent via un menu d'inventaire construit avec l'extension GUI. L'argent peut provenir de votre plugin d'économie via Vault, ou de n'importe quel placeholder et commande console de votre choix. Des intérêts peuvent être ajoutés selon un calendrier, et les réserves peuvent être réinitialisées, modifiées ou ouvertes par des commandes.

Les soldes sont enregistrés dans un artefact TypeWriter et écrits de manière asynchrone : un dépôt ne bloque donc jamais le thread du serveur. Les soldes, niveaux et capacités sont exposés sous forme de placeholders PlaceholderAPI pour les scoreboards, les hologrammes et les menus.

Fonctionnalités​

  • Plusieurs réserves — créez autant de définitions que nécessaire, chacune avec son propre nom, préfixe, niveaux et menu.
  • Niveaux et capacité — chaque niveau a un solde maximal ; les joueurs montent de niveau pour l'augmenter.
  • Prérequis de niveau — débloquez un niveau avec des comparaisons de placeholders ou de facts, et prélevez éventuellement un coût.
  • Intérêts — un calendrier cron, un taux global, un taux par niveau et un taux par permission, avec un plafond par cycle.
  • Vault ou commandes — les dépôts et retraits passent par Vault, ou par un placeholder et des commandes console.
  • Transferts — déplacez un solde entre deux réserves de manière atomique.
  • Boutons de menu — montant fixe, pourcentage, tout, montant personnalisé (dialogue), sous-menus, amélioration et fermeture.
  • Persistance sûre — sauvegardes asynchrones, un verrou par artefact et migration automatique des anciens fichiers.
  • Mode profil — soldes par profil facultatifs avec MMOProfiles.
  • Placeholders et commandes — lisez les valeurs n'importe où et modifiez-les depuis la console.

Installation​

  1. Installez l'extension GUI : Numerical Storage en a besoin pour ses menus. L'extension GUI est publiée sous le nom GuiAndDialogs.
  2. Installez PlaceholderAPI si vous voulez utiliser les placeholders %typewriter_ns_...%.
  3. Facultatif : installez Vault (l'extension est construite pour VaultUnlocked) et un plugin d'économie, pour utiliser le mode de transaction VAULT.
  4. Facultatif : installez MMOProfiles pour utiliser profileMode.
  5. Placez le JAR de Numerical Storage dans plugins/Typewriter/extensions/ et redémarrez le serveur.

La fenêtre de montant personnalisé utilise les dialogues de Paper : il faut donc une version de Paper qui les prend en charge (Minecraft 1.21.6 ou plus récent).

Sauvegardez avant de mettre à jour

Depuis la version 0.9, les nouveaux artefacts utilisent un identifiant technique et un schéma JSON version 2. La première fois qu'un ancien fichier est lu, il est copié vers le nouveau chemin, sauvegardé dans backups/numericalstorage/ et supprimé. Conservez une copie du dossier assets/ de TypeWriter avant de mettre à jour.

Premiers pas​

Créez une banque payée avec votre économie Vault :

  1. Dans le panel web TypeWriter, ouvrez une page manifest et ajoutez un artefact Player Numerical Storage. Laissez artifactId vide : TypeWriter le génère.
  2. Ajoutez une Numerical Storage Definition. Définissez displayName (par exemple Bank), prefix et reliez l'artefact dans artifact.
  3. Dans levels, ajoutez le premier niveau avec une limit de 1000, puis un second avec 5000. Renseignez depositMessage et levelUpMessage si vous voulez un texte personnalisé.
  4. Dans transaction, définissez transactionMode sur VAULT.
  5. Dans menu.transactionButtons, ajoutez un bouton de type DEPOSIT avec amountType FIXED, un amount de 100, et l'objet à afficher. Ajoutez-en un second de type WITHDRAW.
  6. Ajoutez une action Open Numerical Storage Menu. Reliez la definition.
  7. Dans son layoutPool, ajoutez une disposition simple avec l'id main et définissez mainLayoutId sur main. Dans la disposition, ajoutez un objet avec buttonPrefix défini sur numericalstorage_button: et buttonType défini sur DEPOSIT_FIXED:100. Faites de même avec WITHDRAW_FIXED:100, UPGRADE_LEVEL et NAV_CLOSE.
  8. Reliez l'action à un dialogue de PNJ ou à un événement de commande, publiez, et ouvrez la banque en jeu. Vous pouvez aussi exécuter /typewriter ns open <definition>.
Une entrée d'ouverture de menu par définition

Après chaque transaction, le menu est rouvert pour afficher le nouveau solde. L'extension cherche une entrée Open Numerical Storage Menu reliée à la même définition. Sans elle, le menu est simplement fermé.

Fonctionnement​

Le menu est une disposition GUI normale. L'action Open Menu l'ouvre avec le titre et le nombre de lignes de la définition (menu.title, menu.rows, de 1 à 6), et votre layoutPool décide de l'emplacement de chaque objet. L'extension transforme un objet en bouton fonctionnel lorsque l'objet a buttonPrefix défini sur numericalstorage_button: et un buttonType parmi cette liste :

buttonTypeCe que fait le bouton
DEPOSIT_FIXEDDépose un montant fixe. Ajoutez le montant après deux-points, par exemple DEPOSIT_FIXED:100.
DEPOSIT_PERCENTDépose un pourcentage du solde source, par exemple DEPOSIT_PERCENT:50.
DEPOSIT_CUSTOMFerme le menu et demande un montant dans un dialogue.
DEPOSIT_ALLDépose le solde source, dans la limite de la capacité restante. Cela nécessite un amountPlaceholder : en mode VAULT, le bouton tente de déposer toute la capacité restante et échoue si le solde de l'économie est inférieur.
DEPOSIT_SUBMENUOuvre un sous-menu de boutons de dépôt. L'identifiant du sous-menu suit les deux-points.
WITHDRAW_FIXED, WITHDRAW_PERCENT, WITHDRAW_CUSTOM, WITHDRAW_ALL, WITHDRAW_SUBMENUComme ci-dessus, pour les retraits. Le pourcentage est pris sur le solde stocké.
TRANSFER_FIXED, TRANSFER_PERCENT, TRANSFER_ALLDéplacent un solde vers une autre définition. Le bouton provient d'une entrée transactionButtons de type TRANSFER avec un transferTarget.
SUB_MENUOuvre le sous-menu dont l'identifiant suit les deux-points, par exemple SUB_MENU:deposit_options.
UPGRADE_LEVELPasse au niveau suivant, ou affiche l'objet de niveau maximal.
NAV_CLOSEFerme le menu.

Lorsque buttonType comporte un montant (DEPOSIT_FIXED:100), l'extension choisit l'entrée de menu.transactionButtons ayant le même type, le même type de montant et le même montant, et utilise son template comme objet. Sans montant, elle utilise la première entrée correspondante. Lorsque rien ne correspond, un simple objet de teinture avec le libellé par défaut est affiché.

Les sous-menus sont définis dans menu.subMenus, sous forme de table associant un identifiant à un titre, un nombre de lignes, des boutons de transaction placés dans slots, un bouton retour et un bouton de fermeture.

Un bouton de transfert a besoin du transferTarget de l'autre définition (son identifiant d'entrée), et le joueur doit avoir de la place dans la réserve cible.

Commandes​

Toutes les commandes sont des sous-commandes de /typewriter (alias /tw). <definition> est une entrée de définition. Le [target] facultatif sélectionne un autre joueur ; sans lui, la commande s'applique à l'émetteur.

CommandePermissionDescription
/typewriter ns open <definition> [target]typewriter.ns.openOuvre le menu de la réserve, via son entrée Open Menu.
/typewriter ns add <definition> <amount> [target]typewriter.ns.addAjoute au solde. La capacité n'est pas vérifiée.
/typewriter ns remove <definition> <amount> [target]typewriter.ns.removeRetire du solde, jusqu'à 0.
/typewriter ns level <definition> <level> [target]typewriter.ns.levelDéfinit le niveau et remet le solde à 0.
/typewriter ns reset <definition> [target]typewriter.ns.resetRemet le niveau à 1 et le solde à 0.

Les commandes /typewriter numstorage tx ..., upgrade et back_main sont utilisées en interne par les boutons de menu. Elles ne font rien pour un joueur sans menu ouvert.

Avec profileMode activé, add, remove, level et reset modifient le solde et le niveau du profil de la cible, comme le fait le menu.

Réponses des commandes​

Les réponses de add, remove, level, reset et open, ainsi que les réponses d'erreur ci-dessous, sont les champs de adminMessages sur la définition. Elles sont en MiniMessage. Chacune peut utiliser <player>, <storage> (l'identifiant de la définition) et <prefix>.

ChampPlaceholder supplémentairePar défaut
resetMessageaucunNumerical 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>.
noMenuMessageaucunLe message affiché quand le stockage n'a pas d'entrée Open Menu.
invalidAmountMessage<amount> (la valeur saisie)Invalid amount '<amount>'. Use a positive number. Affiché par add et remove quand le montant n'est pas un nombre positif.
noArtifactMessageaucunLe message affiché par add, remove, level et reset quand aucun artefact n'est lié à la définition.
noActiveProfileMessageaucun<player> has no active profile. Affiché par add, remove, level et reset, et au joueur qui clique une action de menu, quand profileMode est activé et que le joueur n'a aucun profil MMOProfiles actif. Rien n'est écrit.

Les valeurs par défaut commencent par le préfixe Typewriter. Trois textes n'appartiennent à aucune définition : ce sont donc des snippets dans snippets.yml : numericalstorage.command.player_only (les commandes des boutons du menu lancées par un non-joueur), et les textes de placeholders numericalstorage.placeholder.interest_disabled (Disabled), numericalstorage.placeholder.interest_error (Error) et numericalstorage.placeholder.capacity_unlimited (le signe infini). Les unités de temps de interest_cooldown sont les snippets numericalstorage.duration.days, hours, minutes, seconds (chacun un modèle avec {value}, {value}j par défaut) et numericalstorage.duration.separator.

Permissions​

PermissionAutorise
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.
Permissions dans interestRatesDonnent à un joueur un taux d'intérêt spécifique. La première permission de la liste que possède le joueur est utilisée.

Placeholders​

Remplacez <id> par l'identifiant d'entrée de la définition. Ils nécessitent PlaceholderAPI et sont lus depuis un cache : ils sont donc sûrs à utiliser dans des scoreboards. Avec profileMode activé, balance, level, capacity et interest suivent le profil avec lequel le joueur joue, comme le fait le menu.

PlaceholderRenvoie
%typewriter_ns_balance_<id>%Le solde actuel.
%typewriter_ns_level_<id>%Le niveau actuel, à partir de 1.
%typewriter_ns_capacity_<id>%La capacité du niveau actuel, ou le signe infini lorsqu'aucun niveau n'est défini.
%typewriter_ns_interest_<id>%Le taux d'intérêt qui s'applique au joueur, en pourcentage.
%typewriter_ns_interest_cooldown_<id>%Le temps avant le prochain cycle d'intérêts planifié, ou Disabled.
%typewriter_ns_name_<id>%Le displayName de la définition.
%typewriter_ns_prefix_<id>%Le prefix de la définition.

Entrées​

4 entrées, générées depuis la source de l'extension.

Actions2
Artefacts1
Manifestes1

Dépannage​

Le menu s'ouvre vide ou les boutons ne font rien. Vérifiez que chaque objet a buttonPrefix défini exactement sur numericalstorage_button: et un buttonType valide. Si le préfixe est erroné, l'objet reste un objet normal sans action. Vérifiez aussi que mainLayoutId correspond à l'id d'une disposition de layoutPool.

Le menu se ferme après chaque dépôt. Le menu est rouvert via une entrée Open Numerical Storage Menu reliée à la même définition. Ajoutez-en une, même si vous ouvrez le menu avec une autre entrée.

« Cannot add ... Would exceed limit ». La réserve est à la capacité du niveau du joueur (levels[].limit). Montez de niveau ou relevez la limite. Sans niveau défini, il n'y a pas de limite.

Un dépôt en mode INTERNAL échoue. Le solde source du joueur est lu avec amountPlaceholder et doit renvoyer un nombre simple. La commande addCommand s'exécute depuis la console avant le dépôt et doit réussir. Utilisez {player} et {amount} dans la commande.

« Economy system is not available. » transactionMode vaut VAULT mais Vault ou un fournisseur d'économie est absent. Installez les deux, puis redémarrez.

Les intérêts ne sont pas versés. Les intérêts sont appliqués lorsqu'un joueur se connecte, pour les cycles cron écoulés depuis son dernier versement (100 cycles au maximum). interestEnabled doit être activé et interestCron renseigné. La première connexion n'enregistre que l'heure de départ. Un solde à la capacité de son niveau ne rapporte rien.

L'amélioration demande la capacité comme coût. Lorsque le niveau suivant n'a pas de criteria, le coût d'une amélioration est la limit du niveau actuel, prélevée sur le solde stocké. Ajoutez des criteria au niveau suivant pour définir une autre exigence.

Les placeholders affichent le solde d'un autre profil. Avec profileMode activé, les placeholders et le bouton d'amélioration lisent le solde et le niveau du profil sélectionné par le joueur. Sans MMOProfiles, ils lisent le solde du joueur. Avec MMOProfiles et aucun profil actif (écran de sélection, après /mmoprofiles quit), ils affichent 0, car l'UUID du joueur est l'identifiant de son profil Main et son solde ne doit être ni affiché ni crédité. Les écritures sont refusées avec noActiveProfileMessage, et l'intérêt d'un profil est réglé à sa sélection.

Un placeholder est vide juste après un redémarrage. Le stockage est chargé en arrière-plan à la connexion : la première lecture peut précéder la fin du chargement ; la lecture suivante affiche la valeur enregistrée.

Le placeholder est vide. L'identifiant dans le placeholder doit être l'identifiant d'entrée de la définition, et non son nom. Exécutez /papi parse me %typewriter_ns_balance_<id>% pour tester.

Extensions associées​

  • GUI — le moteur de menus utilisé pour les dispositions et les boutons.
  • MMOProfiles — facultatif, utilisé par profileMode.