Crate

Caisses de butin avec récompenses pondérées, clés virtuelles, paliers et mini-jeu d'ouverture par tirage de cartes.

Privéesv0.0.2Économie et artisanat

NécessiteTypeWriter0.9BasicGUI

Conçue pour le réseau BornToCraft. Cette extension est documentée à titre de référence et n'est pas distribuée.

Support

Présentation

Crate ajoute des caisses de butin à votre serveur. Une caisse possède une liste de récompenses, chacune avec une rareté, et les joueurs l'ouvrent en dépensant une clé virtuelle. La récompense gagnante est tirée sur le serveur avant le début de toute animation ; rien de ce que fait le joueur pendant l'ouverture ne peut donc modifier le résultat. Les ouvertures comptent pour des paliers, qui peuvent déclencher des récompenses supplémentaires après un certain nombre d'ouvertures.

Les récompenses sont des triggers TypeWriter : une récompense peut donc donner un objet, exécuter une commande, attribuer un cosmétique ou lancer une séquence. L'ouverture est affichée dans le monde devant le joueur : un aperçu des récompenses sur des affichages d'objets flottants, ou un mini-jeu de choix de cartes. Des menus permettent aux joueurs de parcourir les caisses et les récompenses que chacune peut donner.

L'extension fonctionne sur la version BTC de TypeWriter (BTC Core, Paper/Folia) et est documentée ici à titre de référence.

Fonctionnalités

• Récompenses pondérées — les raretés ont un poids, et la probabilité de chaque récompense est affichée dans les menus.
• Clés virtuelles — les clés sont comptées par joueur dans l'artifact de données de la caisse, et une est dépensée à chaque ouverture.
• Ouvertures sécurisées — une clé est d'abord réservée et n'est dépensée que lorsque la récompense est révélée ; une déconnexion, un délai dépassé ou un redémarrage la rembourse.
• Paliers — déclenchez des récompenses supplémentaires après un certain nombre d'ouvertures.
• Mini-jeu de cartes — le joueur retourne l'une des cartes d'une grille posées face cachée, alors que la récompense est déjà décidée.
• Aperçus dans le monde — les récompenses flottent autour du joueur selon les dispositions PAGINATED, FLEX ou SIMPLE, avec un PNJ et un hologramme facultatifs.
• Menus — un menu global des caisses et un menu des récompenses par caisse, avec cadres, pagination et boutons personnalisés.
• Statistiques — ouvertures, clés, clés utilisées, dernière ouverture et palier, disponibles sous forme de placeholders.

Installation

1. Installez l'extension TypeWriter Basic et l'extension GUI (GuiAndDialogs dans la version BTC). Crate ne se charge pas sans elles.
2. Placez le JAR de Crate dans plugins/Typewriter/extensions/ et redémarrez le serveur.
3. Accordez à votre staff les permissions de la section Permissions.

Premiers pas

Créez une caisse avec trois récompenses et donnez-vous une clé :

1. Dans le panneau web de TypeWriter, ouvrez une page manifest et ajoutez un artifact Crate Data. Conservez l'artifactId généré, et utilisez un artifact par caisse.
2. Ajoutez une entrée Crate. Définissez dataArtifact sur l'artifact et rédigez le noKeyMessage.
3. Dans rarities, ajoutez Common avec un poids de 70 et Rare avec un poids de 30.
4. Dans rewards, ajoutez trois récompenses : pour chacune, définissez une rarity, un item affiché dans l'aperçu, un name, et dans action un trigger qui donne la récompense. Laissez grantItem activé pour donner automatiquement l'item, ou désactivez-le si l'action donne elle-même l'objet.
5. Dans rewardSlots, listez les emplacements d'inventaire du menu des récompenses (comptés à partir de 0), par exemple 10-12. Une caisse sans emplacement de récompense refuse de s'ouvrir.
6. Dans icon, définissez le x et le y de la caisse dans le menu global, un item et un name.
7. Ajoutez une action Open Crate pointant vers la caisse, et déclenchez-la depuis un PNJ, un bloc ou un objet.
8. Publiez, puis exécutez /tw crate give <crate entry id> 5 et ouvrez la caisse. Utilisez /tw crate menu pour parcourir les caisses.

Clics sur les récompenses dans le menu des récompenses

Dans le menu des récompenses d'une caisse, cliquer sur une récompense déclenche directement l'action de cette récompense, sans dépenser de clé et sans statistiques. Ne donnez pas aux joueurs l'accès au menu des récompenses si l'action d'une récompense donne quelque chose de valeur, ou réservez ce menu au staff.

Donner des clés

Les clés s'ajoutent avec /tw crate give <crate> <amount> [targets]. Il n'existe pas d'action dédiée aux clés, mais une action de commande peut exécuter cette commande, par exemple depuis la récompense d'une quête ou une boutique.

Fonctionnement

La probabilité d'une récompense est le poids de sa rareté divisé par le poids total de toutes les récompenses. Une récompense dont la rareté ne figure pas dans rarities a un poids de 1. Lorsque la récompense est révélée, la clé est dépensée, les compteurs d'ouvertures et de clés utilisées augmentent, tout palier franchi se déclenche, puis l'objet est donné (si grantItem est activé) et l'action de la récompense s'exécute. Un joueur ne peut avoir qu'une seule ouverture à la fois.

Menus

• Menu global — ouvert avec /tw crate menu. Il affiche une icône par caisse, placée au x (0 à 8) et au y (0 à 5) de l'icône, et cliquer sur une icône ouvre le menu des récompenses de cette caisse. Une entrée Crate Main Menu facultative définit la taille, le titre, le cadre, les boutons, le nombre d'objets par page et la colonne réservée aux flèches de pagination.
• Menu des récompenses — ouvert en cliquant sur une icône, ou avec l'action Open Crate Menu. Il affiche les récompenses dans rewardSlots, avec leur nom, leur lore, et des lignes facultatives de probabilité et de rareté (chanceLore et rarityLore, utilisant {chance} et {rarity}). guiLayout vaut PAGINATED, FLEX (centré, quatre colonnes) ou SIMPLE. frameItem, itemsPerPage et paginationColumn ajustent le cadre et la pagination, et buttons ajoute des boutons personnalisés avec une action.

Les boutons ont un type (INFORMATION, NEXT, PREVIOUS, FILL) et une position. Un bouton FILL est copié dans tous les emplacements vides. Les marqueurs crate_button: (CRATE_OPEN, CRATE_PREVIEW, CRATE_GLOBAL_BROWSE, CRATE_REWARD_SLOT, NAV_BACK, NAV_CLOSE) sont proposés dans l'éditeur GUI, mais ils n'affichent qu'un objet de substitution dans cette version.

Configuration

Crate n'a pas de fichier de configuration. Tout se configure dans des entrées. Les données des joueurs se trouvent dans l'artifact Crate Data : clés, ouvertures, clés utilisées, heure de la dernière ouverture, palier et ouvertures en attente. Il est écrit de façon asynchrone, et les ouvertures en attente laissées par un plantage sont récupérées au démarrage (la clé est remboursée).

Commandes

Toutes les commandes sont des sous-commandes de la commande TypeWriter ; elles commencent donc par /typewriter ou /tw. <crate> est l'entrée d'une caisse et est autocomplété.

Commande	Description	Permission
/tw crate menu	Ouvre le menu global des caisses.	typewriter.crate.menu
/tw crate open <crate>	Ouvre la caisse en utilisant une clé.	typewriter.crate.open
/tw crate give <crate> [targets]	Donne une clé à vous-même ou aux joueurs sélectionnés.	typewriter.crate.give
/tw crate give <crate> <amount> [targets]	Donne plusieurs clés.	typewriter.crate.give
/tw crate remove <crate> [targets]	Retire une clé, uniquement si le joueur en possède une.	typewriter.crate.remove
/tw crate remove <crate> <amount> [targets]	Retire plusieurs clés, uniquement si le joueur en possède assez.	typewriter.crate.remove

La permission de base typewriter.crate protège toute la commande. L'extension enregistre une commande interne /cratemenu utilisée par les clics de menu ; elle n'est pas destinée à être saisie.

Permissions

Permission	Autorise
typewriter.crate	L'accès à la commande /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

Ce sont des balises MiniPlaceholders de l'expansion crate. Remplacez id par l'ID d'entrée de la caisse. Une caisse inconnue renvoie une valeur vide.

Placeholder	Renvoie
<crate_openings:id>	Nombre d'ouvertures de cette caisse par le joueur.
<crate_keys:id>	Clés que possède le joueur.
<crate_keys_used:id>	Clés que le joueur a dépensées.
<crate_last_open:id>	Heure de la dernière ouverture, en millisecondes depuis le 1er janvier 1970.
<crate_milestone:id>	Le palier le plus élevé atteint.

Dans hologramLines, utilisez plutôt les jetons {openings}, {keys}, {last_open} et {milestone}.

Entrées

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

Actions2

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

Artefacts1

• Crate ArtifactDonnées de caisse

Manifestes3

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

Dépannage

« This crate is not configured correctly ». La caisse a échoué à la validation, et le journal du serveur en liste les raisons : aucune récompense, un poids de rareté invalide (il doit être supérieur à zéro), aucun rewardSlots ou des emplacements en dehors de 0 à 53 ou en double, un bouton ou une icon en dehors de la grille de 9 par 6, ou des paliers à zéro ouverture ou en double. Les mêmes vérifications s'exécutent au démarrage et écrivent un avertissement.

Le joueur reçoit le noKeyMessage. Le joueur n'a pas de clé pour cette caisse, ou la caisse n'a pas de dataArtifact. Donnez des clés avec /tw crate give et vérifiez le lien vers l'artifact.

« You are already opening a crate ». Une ouverture est en cours pour ce joueur. Elle se termine lorsque la récompense est révélée ou que le joueur se déconnecte.

Les statistiques et les clés ne changent pas après une ouverture. Elles ne changent que lorsque la récompense est révélée. Si le joueur est parti ou si le serveur s'est arrêté avant cela, la clé est remboursée et les compteurs restent inchangés.

L'aperçu n'affiche rien ou affiche les mauvaises récompenses. L'aperçu utilise l'item de chaque récompense. Les récompenses dont l'item est vide sont ignorées, et preview.maxVisibleRewards limite le nombre affiché en même temps. preview.distance et les décalages *Location déplacent l'affichage.

Le mini-jeu de cartes ne démarre pas. Liez une entrée Crate Minigame: Cards dans le champ minigame de la caisse. Ses columns vont jusqu'à 10 et ses rows jusqu'à 10, et cardCount est plafonné à 100.

Une récompense est donnée deux fois. Ne gardez grantItem activé que lorsque l'action ne donne pas aussi l'objet.

Extensions associées

• GUI — moteur de menus utilisé pour les menus des caisses.