Cosmetics

3D-Cosmetics, Item-Modell-Cosmetics und Skins mit Garderobenmenüs und Speicher pro Spieler.

Privatv0.0.2Menüs & Visuelles

BenötigtTypeWriter0.9GUIEntityCraftEngineoptionalProfilesoptional

Für das BornToCraft-Netzwerk entwickelt. Diese Erweiterung ist zu Referenzzwecken dokumentiert und wird nicht verteilt.

Support

Überblick

Mit Cosmetics können Spieler sich einkleiden und ihre Ausrüstung individuell gestalten. Es deckt zwei Arten von Kosmetika ab. Entity-Kosmetika sind 3D-Modelle (ein Hut, ein Rucksack, Flügel, ein Heiligenschein), die dem Spieler folgen, mit optionalen Partikeln. Item-Kosmetika verändern das Modell eines echten Items, das der Spieler trägt, etwa eines Rüstungsteils oder eines Schwerts, sodass das neue Aussehen auch erscheint, wenn das Item gehalten, getragen oder fallen gelassen wird. Eine separate Funktion Skins wendet eine Hülle auf das Item in der Hand des Spielers an.

Spieler wählen Kosmetika in einem Garderoben-Menü mit einem Tab pro Kategorie. Ein Kosmetikum ist verfügbar, wenn es keine Berechtigung hat, wenn der Spieler seine Berechtigung hält oder wenn ein Administrator oder ein anderer Entry es freigeschaltet hat. Angelegte und freigeschaltete Kosmetika werden pro Spieler in Artifacts gespeichert.

Die Erweiterung läuft auf dem BTC-Build von TypeWriter (BTC Core, Paper/Folia) und ist hier als Referenz dokumentiert. Version 0.0.2 ist ein frühes Release.

Funktionen

• Entity-Kosmetika — hänge jede Entity-Definition (ein Item Display, ein BetterModel-Modell …) an einen Spieler, relativ zum Körper oder zum Kopf oder fest.
• Item-Kosmetika — ersetze das item_model und das getragene Aussehen passender Items und stelle sie wieder her, wenn das Kosmetikum entfernt wird.
• Partikel — hänge Partikeleffekte an ein Kosmetikum.
• Kategorien und Tabs — gruppiere Kosmetika in Kategorien, ein Tab pro Kategorie, mit einem Besitzfilter (alle, besessen, nicht besessen).
• Eines pro Kategorie — ein Spieler trägt pro Kategorie jeweils ein Kosmetikum.
• Freischaltungen — kostenlos, per Berechtigung, per Befehl oder aus anderen Entries.
• Skins — Hüllen für das gehaltene Item, in einem eigenen Menü gewählt, entfernt, wenn das Item fallen gelassen wird.
• Kosmetika an Entities — hänge ein Kosmetikum mit Entity-Daten an einen NPC oder eine andere Entity.
• Platzhalter und Facts — zeige Zählungen in anderen Plugins an und teste den Besitz in Criteria.

Installation

1. Installiere die GUI-Erweiterung (GuiAndDialogs im BTC-Build), die von beiden Menüs verwendet wird.
2. Installiere für Entity-Kosmetika die TypeWriter-Erweiterung Entity oder eine andere Erweiterung, die Entity-Definitionen bereitstellt. Item-Kosmetika und Skins benötigen sie nicht.
3. Optional: Installiere CraftEngine, wenn deine Item-Kosmetika auf CraftEngine-Items zielen, und die Profiles-Erweiterung, wenn Kosmetika dem aktiven Profil folgen sollen.
4. Lege die Cosmetics-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
5. Stelle die Modelle in deinem Resource Pack bereit: item_model-Keys für Item-Kosmetika und Skins (Minecraft 1.21.4 oder neuer) und Texturen unter assets/<namespace>/textures/entity/equipment/ für das Aussehen getragener Rüstung.

Erste Schritte

So erstellst du einen Hut, den Spieler mit einer Berechtigung freischalten:

1. Öffne im TypeWriter-Web-Panel eine Manifest-Seite und füge einen Cosmetic Category-Entry hinzu. Nenne ihn Hats und wähle ein icon.
2. Füge einen Cosmetic Definition-Entry hinzu. Setze category auf die ID des Kategorie-Entrys (oder auf seinen Namen, wenn er keine ID hat), priority, ein menuIcon und permission (zum Beispiel cosmetics.hat.top_hat).
3. Verweise in model auf eine Entity-Definition, zum Beispiel ein Item Display, das dein Hutmodell enthält. Setze rotationMode auf RELATIVE_TO_HEAD und passe offset und rotationOffset an.
4. Füge ein Player Cosmetics-Artifact hinzu, damit angelegte und freigeschaltete Kosmetika gespeichert werden. Lass artifactId vom Web-Panel generieren.
5. Füge eine BTC Cosmetics Menu-Action hinzu. Baue ihr Layout in layoutPool, mit den fünf unter Menüs beschriebenen cosmetics_button:-Markern, und setze baseMenuId, wenn du ein gemeinsames Menü-Chassis verwendest.
6. Veröffentliche. Gib einem Testspieler die Berechtigung oder führe /tw cosmetics give <player> <cosmetic entry id> aus, führe dann /tw cosmetics aus und lege den Hut an.

Verwende die Entry-ID

Die Freischaltliste, die Liste der angelegten Kosmetika, der Befehl give und der Fact Has Cosmetic identifizieren ein Kosmetikum alle über seine Entry-ID, nicht über das Feld cosmeticId. Das Feld cosmeticId wird nur als Token {cosmetic_id} in Menüs angezeigt.

So funktioniert es

Eine Definition ist ein Item-Kosmetikum, wenn sie ein itemModel oder eine equipmentAssetId hat und außerdem applicableCraftEngineIds oder applicableItems auflistet. Jede andere Definition ist ein Entity-Kosmetikum und verwendet model. Item-Kosmetika werden bei jedem Tick der Aktualisierung auf die passenden Items im Inventar des Spielers angewendet, und das ursprüngliche Modell wird am Item behalten, damit es wiederhergestellt werden kann.

Menüs

Das BTC Cosmetics Menu ist ein GUI-Entry mit einer View pro Kategorie, aus deinen Cosmetic-Category-Entries generiert. Eine Kategorie, die von einem Kosmetikum verwendet, aber nie deklariert wird, erscheint trotzdem als Tab. Setze diese Marker mit dem Tag cosmetics_button:<TYPE> in dein Layout:

Marker	Wo	Was er tut
CATEGORY_TAB	Wiederholbar	Ein Tab pro Kategorie. Token: {category_id}, {category_name}, {owned}, {total}.
COSMETIC_SLOT	Wiederholbar	Ein Slot pro Kosmetikum des aktiven Tabs, nach priority sortiert. Ein Klick legt an oder legt ab, wenn es bereits getragen wird. Nicht besessene Kosmetika werden angezeigt, sind aber wirkungslos. Token: {cosmetic_id}, {cosmetic_name}, {category_name}, {state}.
SORT_TOGGLE	Einmal	Wechselt zwischen alle, besessen und nicht besessen. Token: {current_filter}. Der Filter wird zurückgesetzt, wenn der Spieler geht.
CLEAR_CATEGORY	Einmal	Legt das Kosmetikum des aktiven Tabs ab.
PAGE_NAV	Einmal	Linksklick für die nächste Seite, Rechtsklick für die vorherige. Token: {page}, {total_pages}, {page_indicator}. Ausgeblendet, wenn eine Seite genügt.

categoryView ist eine Vorlage, die für jede Kategorie geklont wird (ihr Name akzeptiert {category_name} und {category_id}), und categoryViewIdPrefix (Standard cosmetic_) ist das Präfix der View-IDs. Es gibt keinen Marker für Schließen oder Seitenanzeige: Das Schließen übernimmt das Chassis, und der Zähler wird von PAGE_NAV getragen. Die Standardtexte dieser Buttons sind auf Französisch.

Das Skins-Menü ist getrennt: Es öffnet sich mit der Action Open Skins Menu oder /tw skins, zeigt die Skins, die für das Item in der Haupthand des Spielers gelten, und wird über den Entry Skins Menu Config gestaltet (skinSlots, Vorlagen für freigeschaltete, aktive und gesperrte Skins sowie die Buttons). Ein Linksklick auf einen freigeschalteten Skin wendet ihn an, und die Buttons entfernen den Skin oder wenden ihn auf jedes kompatible Item im Inventar an. Ein Item mit Skin, das fallen gelassen wird, verliert seinen Skin.

Konfiguration

Kosmetika und Skins werden über zwei Artifacts gespeichert, etwa eine Sekunde nach dem Start geladen und einige Sekunden nach jeder Änderung gespeichert:

• Player Cosmetics speichert pro Spieler die freigeschalteten Kosmetika und das angelegte jeder Kategorie.
• Player Skins speichert die freigeschalteten Skins und den gewählten Skin jedes Item-Typs.

Profile und gespeicherte Daten

Ist die Profiles-Erweiterung installiert, werden angelegte Kosmetika unter dem aktiven Profil des Spielers statt unter seiner UUID gespeichert. Früher unter der UUID gespeicherte Kosmetika werden nicht gelöscht, aber nicht mehr gefunden. Migriere auf einem Server, der bereits echte Spielerdaten enthält, die Keys, bevor du mit vorhandenem Profiles installierst oder aktualisierst. Freischaltungen werden immer pro Spieler-UUID gespeichert.

Befehle

Cosmetics-Befehle sind Unterbefehle des TypeWriter-Befehls, beginnen also mit /typewriter oder /tw.

Befehl	Beschreibung
/tw cosmetics oder /tw cosmetics open	Öffnet das Cosmetics-Menü. Erfordert cosmetics.use.
/tw cosmetics give <player> <cosmetic>	Schaltet ein Kosmetikum frei, angegeben über seine Entry-ID. Erfordert cosmetics.admin.
/tw cosmetics remove <player> <cosmetic>	Entfernt eine Freischaltung. Erfordert cosmetics.admin.
/tw cosmetics reset <player>	Löscht die Kosmetika des Spielers. Erfordert cosmetics.admin.
/tw skins oder /tw skins open	Öffnet das Skins-Menü für das Item in der Hand. Erfordert skins.use.
/tw skins give <player> <skin>	Schaltet einen Skin über seine skinId frei. Erfordert skins.admin.
/tw skins remove <player> <skin>	Entfernt eine Skin-Freischaltung. Erfordert skins.admin.
/tw skins reset <player>	Löscht die Skins des Spielers. Erfordert skins.admin.

Menüklicks verwenden die internen Befehle cosmetics ... und skins ..., die von der Erweiterung verarbeitet werden. Sie sind nicht dafür gedacht, von Hand eingegeben zu werden.

Berechtigungen

Berechtigung	Erlaubt
cosmetics.use	/tw cosmetics und /tw cosmetics open.
cosmetics.admin	give, remove und reset für Kosmetika.
skins.use	/tw skins und /tw skins open.
skins.admin	give, remove und reset für Skins.
permission eines Kosmetikums	Eine Berechtigung deiner Wahl, die ein Kosmetikum freischaltet.
permission eines Skins	Eine Berechtigung deiner Wahl, die einen Skin freischaltet.

Platzhalter

Dies sind MiniPlaceholders-Tags der Expansion cosmetics. Ersetze cat durch eine Kategorie-ID oder einen Namen und id durch eine Kosmetikum-Entry-ID.

Platzhalter	Liefert
<cosmetics_total_unlocked>	Anzahl der vom Spieler freigeschalteten Kosmetika.
<cosmetics_total_available>	Anzahl der Kosmetika-Definitionen auf dem Server.
<cosmetics_category_unlocked:cat>	Freigeschaltete Kosmetika in der Kategorie.
<cosmetics_category_total:cat>	Kosmetika in der Kategorie.
<cosmetics_is_unlocked:id>	true oder false.
<cosmetics_is_active:id>	true, wenn dieses Kosmetikum angelegt ist.
<cosmetics_active:cat>	Die ID des in der Kategorie angelegten Kosmetikums, leer, wenn keines.

<cosmetics_category_unlocked:cat> zählt nur Kosmetika, die per Befehl oder durch andere Entries freigeschaltet wurden, nicht solche, die über eine Berechtigung verfügbar sind.

Entries

11 Einträge, aus dem Quellcode der Erweiterung generiert.

Aktionen2

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

Fakten2

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

Entitätsdaten1

• Cosmetic Entity DataAttach cosmetics to an entity definition

Artefakte2

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

Manifeste4

• 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

Fehlerbehebung

Das Menü meldet „Aucun menu de cosmétiques n'est configuré“. Es ist kein BTC Cosmetics Menu-Entry veröffentlicht. /tw cosmetics öffnet den ersten, den es findet.

Ein Kategorie-Tab ist leer oder ein Kosmetikum fehlt. category beim Kosmetikum muss zur ID des Kategorie-Entrys passen (oder zum Namen, wenn er keine ID hat), ohne Beachtung der Groß- und Kleinschreibung. Ein Name, der zu keinem Kategorie-Entry passt, erzeugt trotzdem einen eigenen Tab.

Das Modell erscheint nie. Entity-Kosmetika benötigen ein model, das auf eine Entity-Definition verweist. Eine Definition mit itemModel, aber ohne applicableItems oder applicableCraftEngineIds ist kein Item-Kosmetikum und fällt auf den Entity-Pfad zurück. Bei Item-Kosmetika muss der Key itemModel ein gültiger Namespaced Key sein (namespace:path); ein ungültiger Key wird einmalig als „Invalid itemModel“ protokolliert.

Das Item-Modell ändert sich im Inventar, aber nicht am Körper. itemModel ändert nur, wie das Item in der Hand und im Inventar aussieht. Setze bei Rüstung außerdem equipmentAssetId auf das Equipment-Asset des Materials (zum Beispiel armors:enderite), ohne den Namen des Teils. Es wird nur angewendet, wenn das getragene Item bereits eine Equippable-Komponente trägt.

Ein CraftEngine-Item erhält das Kosmetikum nicht. Verwende applicableCraftEngineIds mit der CraftEngine-ID (zum Beispiel armors:enderite_helmet). Ein CraftEngine-Item wird über seine ID erkannt, nicht über sein Material, daher passt applicableItems nicht darauf.

Angelegte Kosmetika oder Freischaltungen gehen verloren. Füge die Artifacts einer veröffentlichten Seite hinzu. Das Log meldet ein fehlendes Artifact oder „has no generated artifact id“, und ohne sie wird nichts gespeichert. Wurde die Profiles-Erweiterung kürzlich installiert, siehe die Warnung oben.

Andere Spieler sehen mein Kosmetikum nicht. Entity-Kosmetika sind Fake-Entities. Zeigt das Log „Viewer method ... unavailable ... owner-only fallback active“, erlaubt die verwendete Entity-Erweiterung keine zusätzlichen Betrachter, und nur der Besitzer sieht das Kosmetikum.

/tw skins meldet, es gebe keinen Skin für dieses Item. Das gehaltene Item muss zu einem Item in applicableItems einer Skin Definition passen, die mindestens einen Skin auflistet, und ein Skins-Menü-Entry muss veröffentlicht sein. Die Nachrichtentexte stammen aus dem Entry Skins Menu Config.

Verwandte Erweiterungen

• GUI — Menü-Layouts und Chassis.
• Profiles — Kosmetika können dem aktiven Profil folgen.
• BetterModel — 3D-Modelle, die als Entity-Kosmetika nutzbar sind.