Pets
Présentation
Pets ajoute des compagnons à collectionner, inspirés d'EcoPets. Chaque familier est défini une seule fois dans le panneau web (une Pet Definition), et chaque joueur en possède des exemplaires. Un familier est distribué sous forme d'objet jeton : un clic droit sur le jeton ajoute le familier au menu de compagnons du joueur. Depuis le menu, le joueur active un familier à la fois, et celui-ci flotte au-dessus de sa tête, marche à côté de lui ou vole autour de lui.
Les familiers gagnent de l'expérience lorsque leur propriétaire tue des mobs ou lorsque votre histoire accorde de l'XP, et montent en niveau selon une formule ou un tableau que vous écrivez. Un familier peut riposter contre les mobs qui frappent son propriétaire, et peut avoir plusieurs skins qui se débloquent via des critères TypeWriter.
Fonctionnalités
- Trois modes d'affichage —
HEADflotte au-dessus du joueur,GROUNDmarche à ses côtés,FLYplane à une hauteur définie. - Menu de compagnons — une GUI avec une grille des familiers possédés, l'activation, le masquage et l'affichage, les détails et les skins.
- Objets jetons — les familiers passent d'un joueur à l'autre sous forme d'objets qui conservent leur niveau, leur XP, leur mode et leur skin.
- XP et niveaux — une formule telle que
{level} * 100ou un tableau explicite, avec un niveau maximum. - XP par kill et XP d'histoire — de l'XP par mob tué, plus une action pour accorder de l'XP depuis n'importe quelle séquence.
- Riposte — contre-attaque facultative contre les mobs qui blessent le propriétaire, avec des dégâts par niveau.
- Skins — plusieurs skins de PNJ par familier, chacun avec des critères, une priorité et une icône de menu.
- Permissions d'emplacements — verrouillez des emplacements du menu derrière des permissions pour vendre des emplacements de compagnons supplémentaires.
- Placeholders — nom, niveau, XP, statut et possession du familier actif, d'un emplacement ou de n'importe quel familier.
- Prise en charge des modèles — les familiers terrestres et volants utilisent n'importe quelle définition d'entité, y compris les modèles ModelEngine.
Installation
- Installez l'extension GUI, qui dessine les menus.
- Facultatif : installez ModelEngine et l'extension TypeWriter qui expose vos modèles comme définitions d'entités, si les familiers doivent utiliser des modèles animés.
- Placez le JAR de Pets dans
plugins/Typewriter/extensions/et redémarrez le serveur. - Créez un artifact Pet Storage pour que les familiers possédés soient sauvegardés, voir Premiers pas.
Premiers pas
Créez un premier familier et donnez-le à un joueur :
- Dans le panneau web de TypeWriter, ouvrez une page statique et ajoutez un artifact Pet Storage. Sans lui, l'extension consigne « No pet_storage entry found » et rien n'est conservé.
- Ajoutez une Pet Definition. Le
namede l'entrée est le nom d'affichage du familier et sonidest l'identifiant du familier. - Choisissez
defaultMode. PourHEAD, collez éventuellement unetextureen base64 pour la tête flottante. PourGROUNDouFLY, définisseznpcsur une entrée de définition d'entité qui sera générée à côté du joueur. - Sous
xp, définissezmaxLevel, ainsi qu'uneformulautilisant{level}(par exemple{level} * 100) ou une listelevels. DéfinissezkillRewardpour l'XP par kill. - Facultatif : cochez
combat.enabledpour la riposte, et personnaliseztoken(l'objet, son nom et son lore, et un effet de brillance). - Ajoutez une action Pets Open Menu, définissez son
storagesur votre artifact Pet Storage, et déclenchez-la depuis un PNJ, un objet ou une commande. - Publiez, puis exécutez
/pets give <pet> 1en tant que joueur. Faites un clic droit sur le jeton, puis ouvrez le menu et cliquez sur le familier pour l'activer.
Pour accorder de l'XP depuis votre histoire, ajoutez une action Pets Add XP avec amount. Elle va au familier actif du joueur. Pour contrôler un familier précis, utilisez Pets State avec pet et action.
Il n'existe pas d'action qui débloque directement un familier. Un familier parvient à un joueur sous forme d'objet jeton, via /pets give ou via le bouton « return to item » du menu. Exécutez la commande depuis une action de commande console dans une quête ou une boutique pour en faire une récompense à débloquer.
Fonctionnement
Un joueur possède au plus un familier par définition. Un seul familier est actif à la fois : en activer un autre désactive le premier. Les familiers sont sauvegardés dans l'artifact Pet Storage en arrière-plan, et le familier actif est restauré lorsque le joueur se connecte.
Modes d'affichage.
HEADaffiche le familier au-dessus de la tête du joueur avecheadOffsetappliqué. Sinpcest défini, cette entité est utilisée. Sinon, un armor stand invisible porte une tête de joueur avectexture.GROUNDfait apparaître lenpc(ou le PNJ du skin sélectionné) à quelques blocs derrière le joueur et le fait suivre.swimModedécide s'il nage dans les liquides :AUTOsuit les capacités de l'entité,ALWAYSetNEVERle forcent.FLYest identique àGROUND, mais le familier plane àflightHeightblocs au-dessus du joueur.
Si un familier GROUND ou FLY n'a pas de PNJ (ou qu'aucun de ses skins ne correspond), il n'est pas affiché et un avertissement est consigné. Une étiquette de nom avec le niveau s'affiche au-dessus de chaque familier actif. Le mode provient de defaultMode lors de la première création du jeton et reste attaché à cette instance de familier.
XP et niveaux. Un familier commence au niveau 1. Chaque entrée de levels donne l'XP totale qu'un familier doit avoir atteinte pour un niveau, par exemple le niveau 2 à 100 XP, le niveau 3 à 250 XP. Les entrées explicites l'emportent sur la formule. La formule est évaluée en remplaçant {level} par le niveau à atteindre, et prend en charge + - * /, les parenthèses et les décimales. Un familier sans exigence pour le niveau suivant ne monte pas en niveau.
Riposte. Avec combat.enabled, un familier actif et visible riposte contre tout mob non joueur qui blesse le propriétaire, après un court délai et avec un cooldown de 1,5 seconde par attaquant. Les dégâts sont le damage de l'entrée de levels la plus élevée au niveau du familier ou en dessous. En l'absence d'entrée, ils valent 1,5 plus 0,5 par niveau au-dessus de 1.
Skins. Chaque entrée de skins pointe vers une définition de PNJ, une priority et des criteria. Le familier utilise le skin choisi par le joueur si ses critères correspondent toujours, sinon le skin de plus haute priorité dont les critères correspondent. Le champ npc de la définition est le skin de repli. Une entrée de skin a besoin d'un npc, sinon elle est ignorée.
Menus
L'action Pets Open Menu ouvre le menu de compagnons intégré, intitulé « Compagnons ». Chaque familier possédé est une icône de tête de joueur affichant le niveau, la progression d'XP et l'état. Un clic gauche active ou désactive le familier, un clic droit ouvre son écran de détails. L'écran de détails affiche les statistiques, permet au joueur d'activer, de choisir un skin (lorsque le familier en a plusieurs), de rendre le familier sous forme d'objet, ou de revenir en arrière. Un bouton dans le coin inférieur gauche affiche ou masque le familier actif.
Les paramètres du menu sont des champs de l'objet menu de l'action :
slots— numéros d'emplacements d'inventaire où les familiers sont affichés. La valeur par défaut est de 21 emplacements sur trois lignes.lockedSlots— paires deslotetpermission. Un emplacement dont le joueur n'a pas la permission affiche un marqueur verrouillé, et aucun familier ne peut y être placé.maxSlots— nombre maximal d'emplacements utilisés (21 par défaut, minimum 1) : seules lesmaxSlotspremières entrées deslotssont disposées et peuvent recevoir un nouveau familier. Il limite la disposition et le nombre de familiers qu'un joueur peut obtenir, pas ceux qu'il possède déjà.rows— hauteur du menu, de 1 à 6.storage— l'artifact Pet Storage à utiliser.
La disposition des emplacements du dernier menu ouvert est sauvegardée avec les données du joueur et décide des emplacements qu'un jeton peut occuper. Un familier que le joueur possède déjà dans un emplacement au-delà de maxSlots (ou hors de la hauteur du menu) n'est pas masqué : il est affiché dans une case libre du menu, jamais sur le bouton afficher/masquer, et ses clics agissent toujours sur son propre emplacement. S'il y a plus de familiers de ce type que de cases libres, les surplus restent possédés et apparaissent dans la page Pets du menu Social partagé, qui liste tous les familiers possédés ; un avertissement est journalisé une fois par joueur.
Utilisation dans votre propre menu. L'extension enregistre le préfixe de bouton pets_button: pour n'importe quel menu GUI. Définissez le buttonPrefix d'un objet sur pets_button: et son buttonType sur l'une des valeurs suivantes :
buttonType | Affiche |
|---|---|
PET_ENTRY | Le familier à cette position dans la liste du joueur. Un clic gauche l'active ou le désactive, un clic droit le sélectionne pour les objets de détails. |
PET_DETAIL_INFO | Niveau, XP et mode du familier sélectionné. |
PET_LEVEL_ENTRY | Un niveau du familier sélectionné avec son exigence d'XP et son état. |
PET_DETAIL_REMOVE | Un bouton qui rend le familier sélectionné sous forme d'objet. |
PET_LIST_NAV, PET_DETAIL_NAV | Flèches de page pour la liste des familiers et la liste des niveaux. |
Les emplacements peuvent aussi exécuter les commandes pet_menu : pet_menu activate <slot>, pet_menu deactivate <slot>, pet_menu toggle_visibility, pet_menu details <slot>, pet_menu skins <slot>, pet_menu select_skin <pet> <skin> et pet_menu remove <slot>.
Si UiCore est installé, il peut lire les compagnons du joueur pour dessiner un HUD ou une page de menu.
Les textes de menu, le lore du jeton et l'étiquette au-dessus d'un familier sont en français par défaut (par exemple « Niveau », « Compagnons »). Modifiez le name, le lore et le noSlotMessage du jeton pour chaque familier. Les autres textes de menu sont fixés dans le code.
Commandes
La permission typewriter.pets est requise pour chaque sous-commande, en plus de la permission indiquée. La plupart des sous-commandes acceptent un sélecteur de joueur facultatif [target] après leurs arguments pour agir sur quelqu'un d'autre ; sans lui, elles agissent sur l'émetteur.
| Commande | Permission | Description |
|---|---|---|
/pets open [target] | typewriter.pets.open | Ouvre le menu de compagnons. |
/pets activate <pet> [target] | typewriter.pets.activate | Active un familier possédé. |
/pets deactivate [target] | typewriter.pets.deactivate | Renvoie le familier actif. |
/pets show [target] | typewriter.pets.show | Réaffiche le familier actif. |
/pets hide [target] | typewriter.pets.hide | Masque le familier actif. |
/pets remove <pet> [target] | typewriter.pets.remove | Supprime un familier du menu du joueur. Aucun objet n'est rendu. |
/pets give <pet> <amount> [target] | typewriter.pets.give | Donne de 1 à 64 objets jetons. |
<pet> est l'identifiant ou le nom d'une entrée Pet Definition. La commande seule /pets ne fait rien dans cette version : utilisez /pets open.
Permissions
Aucune n'est enregistrée avec une valeur par défaut ; seuls les opérateurs les possèdent donc, sauf si vous les accordez avec un plugin de permissions.
| Permission | Autorise |
|---|---|
typewriter.pets | L'arborescence de commandes /pets. |
typewriter.pets.open | /pets open. |
typewriter.pets.activate | /pets activate. |
typewriter.pets.deactivate | /pets deactivate. |
typewriter.pets.show | /pets show. |
typewriter.pets.hide | /pets hide. |
typewriter.pets.remove | /pets remove. |
typewriter.pets.give | /pets give. |
Permissions de lockedSlots | Déverrouillent l'emplacement de menu correspondant. Vous choisissez les noms. |
Placeholders
Pets expose une entrée de placeholder TypeWriter, Pets Placeholder. Créez-la une seule fois. La balise est <typewriter_ENTRY:...>, où ENTRY est le nom ou l'identifiant en minuscules de cette entrée, par exemple <typewriter_pets_placeholder:active:name> lorsque l'entrée se nomme pets_placeholder.
| Chemin d'argument | Renvoie |
|---|---|
active | Nom du familier actif, vide s'il n'y en a pas. |
active:name, active:id | Nom et identifiant du familier actif. |
active:level, active:xp, active:max_level | Niveau, XP et niveau maximum. |
active:next_xp | XP requise pour le niveau suivant, Max au sommet. |
active:damage | Dégâts de riposte au niveau actuel. |
active:status | active ou inactive. |
active:visibility | hidden ou visible. |
active:mode | head, ground ou fly. |
slot:<index>:name, id, level, xp, next_xp, max_level, damage, visibility, mode | Les mêmes champs pour le familier de cet emplacement de menu. |
slot:<index>:status | active, inactive ou empty. |
pet:<id>:name, description, max_level, xp_per_kill, default_mode, combat, texture | Champs d'une Pet Definition. |
pet:<id>:owned | true ou false pour le joueur. |
pet:<id>:level, xp, next_xp, visibility, mode, damage | L'exemplaire du joueur de ce familier, vide s'il n'est pas possédé. |
pet:<id>:status | active, inactive ou unowned. |
Entrées
6 entrées, générées depuis la source de l'extension.
Actions3
- Pets Add XPGrant experience to a pet
- Pets Open MenuOpen the pet selection menu
- Pets StateChange the state of a pet
Placeholders1
- Pets PlaceholderExpose companion placeholders
Artefacts1
- Pet StoragePersist companion data
Manifestes1
- Pet DefinitionConfigure a companion pet
Dépannage
Les familiers sont perdus après un redémarrage. Il n'existe aucun artifact Pet Storage, ou l'action de menu n'a pas de storage. Le journal affiche « No pet_storage entry found. Companion data will not persist until one is created. »
Le jeton indique que le menu est plein. Chaque emplacement du menu est occupé ou verrouillé pour ce joueur. Ajoutez des emplacements dans slots, ou accordez la permission d'un emplacement verrouillé. Le message est le noSlotMessage du jeton.
« Ce familier est déjà présent dans ton menu. » Un joueur ne peut posséder qu'un exemplaire de chaque familier. Il ne peut pas utiliser un second jeton pour la même définition.
Un familier GROUND ou FLY n'apparaît jamais. Le journal indique « Unable to summon ground pet ». Définissez npc sur la définition, ou donnez à au moins un skin un npc dont les critères correspondent au joueur. Vérifiez que l'entrée de définition d'entité existe.
Le familier ne monte pas en niveau. Le familier a besoin d'une exigence pour le niveau suivant, soit une entrée de levels, soit une formula. Une formule qui ne peut pas être évaluée est traitée comme une absence d'exigence. Vérifiez qu'elle n'utilise que des nombres, {level}, + - * / et des parenthèses.
/pets n'affiche rien. Utilisez /pets open. Toutes les sous-commandes nécessitent typewriter.pets plus leur propre permission, et ces permissions ne sont pas accordées par défaut.
Un skin apparaît comme verrouillé (« ??? »). Ses criteria ne correspondent pas encore. Testez les facts ou les quêtes dont il dépend.