Cosmetics

Cosmétiques 3D, cosmétiques de modèles d'objets et skins avec menus de garde-robe et stockage par joueur.

Privéesv0.0.2Menus et visuels

NécessiteTypeWriter0.9GUIEntityCraftEnginefacultatifProfilesfacultatif

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

Support

Vue d'ensemble

Cosmetics permet aux joueurs de s'habiller et de personnaliser leur équipement. Il couvre deux types de cosmétiques. Les cosmétiques d'entité sont des modèles 3D (un chapeau, un sac à dos, des ailes, un halo) qui suivent le joueur, avec des particules facultatives. Les cosmétiques d'objet changent le modèle d'un vrai objet que le joueur porte, comme une pièce d'armure ou une épée : la nouvelle apparence se voit aussi lorsque l'objet est tenu, porté ou lâché. Une fonctionnalité distincte de skins applique un habillage à l'objet tenu en main par le joueur.

Les joueurs choisissent leurs cosmétiques dans un menu de garde-robe avec un onglet par catégorie. Un cosmétique est disponible lorsqu'il n'a pas de permission, lorsque le joueur détient sa permission, ou lorsqu'un administrateur ou une autre entrée l'a débloqué. Les cosmétiques équipés et débloqués sont enregistrés par joueur dans des artefacts.

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

Fonctionnalités

• Cosmétiques d'entité — attachez n'importe quelle définition d'entité (un item display, un modèle BetterModel…) à un joueur, relativement au corps ou à la tête, ou fixe.
• Cosmétiques d'objet — remplacez l'item_model et l'apparence portée des objets correspondants, et restaurez-les lorsque le cosmétique est retiré.
• Particules — attachez des effets de particules à un cosmétique.
• Catégories et onglets — regroupez les cosmétiques en catégories, un onglet par catégorie, avec un filtre de possession (tous, possédés, non possédés).
• Un par catégorie — un joueur porte un cosmétique par catégorie à la fois.
• Déblocages — gratuits, par permission, par commande, ou depuis d'autres entrées.
• Skins — habillages pour l'objet tenu, choisis dans un menu dédié, retirés lorsque l'objet est lâché.
• Cosmétiques sur des entités — attachez un cosmétique à un PNJ ou à une autre entité avec des données d'entité.
• Placeholders et facts — affichez des compteurs dans d'autres plugins et testez la possession dans des critères.

Installation

1. Installez l'extension GUI (GuiAndDialogs dans la version BTC), utilisée par les deux menus.
2. Installez l'extension TypeWriter Entity, ou une autre extension qui fournit des définitions d'entités, pour les cosmétiques d'entité. Les cosmétiques d'objet et les skins n'en ont pas besoin.
3. Facultatif : installez CraftEngine si vos cosmétiques d'objet ciblent des objets CraftEngine, et l'extension Profiles si les cosmétiques doivent suivre le profil actif.
4. Placez le JAR de Cosmetics dans plugins/Typewriter/extensions/ et redémarrez le serveur.
5. Fournissez les modèles dans votre resource pack : des clés item_model pour les cosmétiques d'objet et les skins (Minecraft 1.21.4 ou plus récent), et des textures assets/<namespace>/textures/entity/equipment/ pour les apparences d'armure portée.

Premiers pas

Créez un chapeau que les joueurs débloquent avec une permission :

1. Dans le panel web TypeWriter, ouvrez une page manifest et ajoutez une entrée Cosmetic Category. Nommez-la Hats et choisissez une icon.
2. Ajoutez une entrée Cosmetic Definition. Définissez category sur l'ID de l'entrée de catégorie (ou son nom si elle n'a pas d'ID), priority, une menuIcon, et permission (par exemple cosmetics.hat.top_hat).
3. Dans model, référencez une définition d'entité, par exemple un item display tenant votre modèle de chapeau. Définissez rotationMode sur RELATIVE_TO_HEAD et ajustez offset et rotationOffset.
4. Ajoutez un artefact Player Cosmetics pour que les cosmétiques équipés et débloqués soient enregistrés. Laissez artifactId au panel web pour qu'il le génère.
5. Ajoutez une action BTC Cosmetics Menu. Construisez sa disposition dans layoutPool, avec les cinq marqueurs cosmetics_button: décrits dans Menus, et définissez baseMenuId si vous utilisez un châssis de menu partagé.
6. Publiez. Donnez la permission à un joueur de test, ou exécutez /tw cosmetics give <player> <cosmetic entry id>, puis exécutez /tw cosmetics et équipez le chapeau.

Utilisez l'ID d'entrée

La liste des déblocages, la liste des équipés, la commande give et le fact Has Cosmetic identifient tous un cosmétique par son ID d'entrée, et non par le champ cosmeticId. Le champ cosmeticId n'est affiché que sous la forme du jeton {cosmetic_id} dans les menus.

Fonctionnement

Une définition est un cosmétique d'objet lorsqu'elle a un itemModel ou un equipmentAssetId, et liste aussi applicableCraftEngineIds ou applicableItems. Toute autre définition est un cosmétique d'entité et utilise model. Les cosmétiques d'objet sont appliqués aux objets correspondants de l'inventaire du joueur à chaque tick du rafraîchissement, et le modèle d'origine est conservé sur l'objet pour pouvoir être restauré.

Menus

Le BTC Cosmetics Menu est une entrée GUI avec une vue par catégorie, générée à partir de vos entrées Cosmetic Category. Une catégorie utilisée par un cosmétique mais jamais déclarée apparaît tout de même comme onglet. Placez ces marqueurs dans votre disposition avec la balise cosmetics_button:<TYPE> :

Marqueur	Où	Ce qu'il fait
CATEGORY_TAB	Répétable	Un onglet par catégorie. Jetons : {category_id}, {category_name}, {owned}, {total}.
COSMETIC_SLOT	Répétable	Un emplacement par cosmétique de l'onglet actif, trié par priority. Un clic équipe, ou déséquipe lorsqu'il est déjà porté. Les cosmétiques non possédés sont affichés mais inertes. Jetons : {cosmetic_id}, {cosmetic_name}, {category_name}, {state}.
SORT_TOGGLE	Une fois	Alterne entre tous, possédés et non possédés. Jeton : {current_filter}. Le filtre se réinitialise lorsque le joueur part.
CLEAR_CATEGORY	Une fois	Déséquipe le cosmétique de l'onglet actif.
PAGE_NAV	Une fois	Clic gauche pour la page suivante, clic droit pour la précédente. Jetons : {page}, {total_pages}, {page_indicator}. Masqué lorsqu'une seule page suffit.

categoryView est un modèle cloné pour chaque catégorie (son nom accepte {category_name} et {category_id}), et categoryViewIdPrefix (cosmetic_ par défaut) préfixe les identifiants de vues. Il n'y a pas de marqueur de fermeture ni d'indicateur de page : la fermeture est gérée par le châssis et le compteur est porté par PAGE_NAV. Les textes par défaut de ces boutons sont en français.

Le menu des skins est distinct : il s'ouvre avec l'action Open Skins Menu ou /tw skins, affiche les skins qui s'appliquent à l'objet de la main principale du joueur, et est disposé par l'entrée Skins Menu Config (skinSlots, modèles pour les skins débloqués, actifs et verrouillés, et les boutons). Un clic gauche sur un skin débloqué l'applique, et les boutons retirent le skin ou l'appliquent à chaque objet compatible de l'inventaire. Un objet avec skin qui est lâché perd son skin.

Configuration

Les cosmétiques et les skins sont stockés via deux artefacts, chargés environ une seconde après le démarrage et enregistrés quelques secondes après chaque changement :

• Player Cosmetics stocke, par joueur, les cosmétiques débloqués et celui équipé de chaque catégorie.
• Player Skins stocke les skins débloqués et le skin sélectionné de chaque type d'objet.

Profils et données stockées

Lorsque l'extension Profiles est installée, les cosmétiques équipés sont stockés sous le profil actif du joueur au lieu de son UUID. Les cosmétiques enregistrés auparavant sous l'UUID ne sont pas supprimés, mais ils ne sont plus retrouvés. Sur un serveur qui contient déjà de vraies données de joueurs, migrez les clés avant d'installer ou de mettre à jour avec Profiles présent. Les déblocages sont toujours stockés par UUID de joueur.

Commandes

Les commandes de Cosmetics sont des sous-commandes de la commande TypeWriter : elles commencent donc par /typewriter ou /tw.

Commande	Description
/tw cosmetics ou /tw cosmetics open	Ouvre le menu des cosmétiques. Nécessite cosmetics.use.
/tw cosmetics give <player> <cosmetic>	Débloque un cosmétique, indiqué par son ID d'entrée. Nécessite cosmetics.admin.
/tw cosmetics remove <player> <cosmetic>	Retire un déblocage. Nécessite cosmetics.admin.
/tw cosmetics reset <player>	Efface les cosmétiques du joueur. Nécessite cosmetics.admin.
/tw skins ou /tw skins open	Ouvre le menu des skins pour l'objet en main. Nécessite skins.use.
/tw skins give <player> <skin>	Débloque un skin par son skinId. Nécessite skins.admin.
/tw skins remove <player> <skin>	Retire le déblocage d'un skin. Nécessite skins.admin.
/tw skins reset <player>	Efface les skins du joueur. Nécessite skins.admin.

Les clics de menu utilisent les commandes internes cosmetics ... et skins ..., gérées par l'extension. Elles ne sont pas destinées à être saisies à la main.

Permissions

Permission	Autorise
cosmetics.use	/tw cosmetics et /tw cosmetics open.
cosmetics.admin	give, remove et reset pour les cosmétiques.
skins.use	/tw skins et /tw skins open.
skins.admin	give, remove et reset pour les skins.
permission d'un cosmétique	Une permission de votre choix qui débloque un cosmétique.
permission d'un skin	Une permission de votre choix qui débloque un skin.

Placeholders

Ce sont des balises MiniPlaceholders de l'extension cosmetics. Remplacez cat par un ID ou un nom de catégorie et id par un ID d'entrée de cosmétique.

Placeholder	Renvoie
<cosmetics_total_unlocked>	Nombre de cosmétiques que le joueur a débloqués.
<cosmetics_total_available>	Nombre de définitions de cosmétiques sur le serveur.
<cosmetics_category_unlocked:cat>	Cosmétiques débloqués dans la catégorie.
<cosmetics_category_total:cat>	Cosmétiques dans la catégorie.
<cosmetics_is_unlocked:id>	true ou false.
<cosmetics_is_active:id>	true lorsque ce cosmétique est équipé.
<cosmetics_active:cat>	L'ID du cosmétique équipé dans la catégorie, vide s'il n'y en a pas.

<cosmetics_category_unlocked:cat> ne compte que les cosmétiques débloqués par commande ou par d'autres entrées, pas ceux qui sont disponibles par permission.

Entrées

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

Actions2

• BTC Cosmetics MenuBTC Cosmetics Menu
• Open Skins Menu ActionOpens the skins menu

Faits2

• Has Cosmetic FactChecks if a player has a specific cosmetic unlocked.
• Has Skin FactVérifie si un joueur possède un skin spécifique.

Données d'entité1

• Cosmetic Entity DataAttach cosmetics to an entity definition

Artefacts2

• Player Cosmetics ArtifactStores player unlocked cosmetics
• Player Skins ArtifactStores player selected skins

Manifestes4

• Cosmetic CategoryDéfinition d'une catégorie de cosmétiques (ex: Chapeaux, Capes)
• Cosmetic DefinitionDefine a 3D Cosmetic
• Skin DefinitionDéfinition d'une catégorie de skins (wraps) pour les items
• Skins Menu ConfigConfiguration du menu des skins

Dépannage

Le menu indique « Aucun menu de cosmétiques n'est configuré ». Aucune entrée BTC Cosmetics Menu n'est publiée. /tw cosmetics ouvre la première qu'il trouve.

Un onglet de catégorie est vide ou un cosmétique est absent. category sur le cosmétique doit correspondre à l'ID de l'entrée de catégorie (ou à son nom lorsqu'elle n'a pas d'ID), sans tenir compte de la casse. Un nom qui ne correspond à aucune entrée de catégorie crée tout de même un onglet à part.

Le modèle n'apparaît jamais. Les cosmétiques d'entité nécessitent que model référence une définition d'entité. Une définition qui a itemModel mais pas applicableItems ni applicableCraftEngineIds n'est pas un cosmétique d'objet et se rabat sur le chemin des entités. Pour les cosmétiques d'objet, la clé itemModel doit être une clé avec namespace valide (namespace:path) ; une clé invalide est journalisée une fois sous la forme « Invalid itemModel ».

Le modèle de l'objet change dans l'inventaire mais pas sur le corps. itemModel ne change que l'apparence de l'objet en main et dans l'inventaire. Pour l'armure, définissez aussi equipmentAssetId sur l'asset d'équipement du matériau (par exemple armors:enderite), sans le nom de la pièce. Il n'est appliqué que lorsque l'objet porté a déjà un composant equippable.

Un objet CraftEngine ne reçoit pas le cosmétique. Utilisez applicableCraftEngineIds avec l'identifiant CraftEngine (par exemple armors:enderite_helmet). Un objet CraftEngine est reconnu par son identifiant, et non par son matériau : applicableItems ne lui correspondra donc pas.

Les cosmétiques équipés ou les déblocages sont perdus. Ajoutez les artefacts à une page publiée. Le journal signale un artefact manquant ou « has no generated artifact id », et rien n'est enregistré sans eux. Si l'extension Profiles a été installée récemment, voir l'avertissement plus haut.

Les autres joueurs ne voient pas mon cosmétique. Les cosmétiques d'entité sont de fausses entités. Si le journal affiche « Viewer method ... unavailable ... owner-only fallback active », l'extension Entity utilisée n'autorise pas de spectateurs supplémentaires et seul le propriétaire voit le cosmétique.

/tw skins indique qu'il n'y a pas de skin pour cet objet. L'objet tenu doit correspondre à un objet de applicableItems d'une Skin Definition qui liste au moins un skin, et une entrée de menu des skins doit être publiée. Les textes des messages proviennent de l'entrée Skins Menu Config.

Extensions associées

• GUI — dispositions et châssis de menus.
• Profiles — les cosmétiques peuvent suivre le profil actif.
• BetterModel — modèles 3D utilisables comme cosmétiques d'entité.