Zum Hauptinhalt springen

Codex

Entdeckungs-Codex mit freischaltbaren Kategorien, Rezeptbüchern und sammelbaren Fragmenten.

Privatv0.0.3Quests & Story
BenötigtTypeWriter0.9BasicGUIQuestoptionalQuest Codexoptional

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

Support

Überblick​

Codex ist ein Entdeckungslog. Du definierst Kategorien (ein Bestiarium, ein Lore-Buch, eine Liste von Orten) und die Items darin, und jedes Item oder jede Kategorie wird durch TypeWriter-Criteria freigeschaltet: einen Fact, einen Quest-Status, eine Berechtigung, alles, was ein Criteria prüfen kann. Gesperrte Einträge bleiben mit ihrer eigenen Lore sichtbar, sodass Spieler sehen, was noch zu entdecken ist. Du kannst auch Rezeptkategorien hinzufügen, die ein Vanilla-Rezept in einer kleinen Werkbank-Ansicht zeigen, wenn der Spieler ein Rezept anklickt.

Die Erweiterung enthält außerdem ein Fragment-System: sammelbare Items, die Spieler aufheben, in Sets gruppiert, mit einer Sequence, die ausgelöst wird, sobald genug Fragmente gesammelt sind. Alles ist ein TypeWriter-Entry, im Web-Panel gebaut, und die Menüs werden von der GUI-Erweiterung dargestellt.

Die Erweiterung läuft auf dem BTC-Build von TypeWriter (BTC Core, Paper/Folia) und ist hier als Referenz dokumentiert.

Funktionen​

  • Entdeckungskategorien — gruppiere Items, mit verschachtelten Unterkategorien über parentCategory.
  • Freischaltung per Criteria — Kategorien und Items werden über Criteria freigeschaltet; gesperrte können ein eigenes Item und eine eigene Lore zeigen.
  • Abschlusszähler — freigeschaltet, gesperrt, gesamt und Prozent stehen in Kategorie-Icons und als Platzhalter zur Verfügung.
  • Rezeptbücher — zeige die Zutaten und das Ergebnis eines Vanilla-Rezepts anhand seines recipeKey.
  • Freischalt-Trigger — löse Trigger aus, wenn eine Kategorie, ein Item oder ein Rezept für einen Spieler zum ersten Mal freigeschaltet wird, gespeichert, damit sie nie zweimal ausgelöst werden.
  • Vier Menü-Layouts — PAGINATED, SCROLLABLE, FRAME oder SIMPLE für jede Kategorie.
  • Globales Codex-Menü — ein GUI-Layout, in dem Kategorie-Icons über Marker platziert werden und das ein gemeinsames Menü-Chassis erbt.
  • Sammelbare Fragmente — hebe ein Item auf, um ein Fragment zu sammeln, mit einem Trigger, wenn eine Gruppe vollständig ist.
  • Öffnen per Befehl und Action — öffne eine Kategorie über einen Befehl, einen Dialog oder einen beliebigen Trigger.

Installation​

  1. Installiere die GUI-Erweiterung (GuiAndDialogs im BTC-Build) und die Basic-Erweiterung von TypeWriter. Codex lädt ohne sie nicht.
  2. Installiere optional die Quest-Erweiterung und die Quest Codex-Erweiterung, wenn du Einträge anhand des Quest-Fortschritts freischalten möchtest.
  3. Lege die Codex-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
  4. Füge ein Codex Unlock-Artifact hinzu, wenn du Freischalt-Trigger verwendest, und ein Fragment Storage-Artifact, wenn du Fragmente verwendest.

Erste Schritte​

So baust du eine Kategorie „Waldkreaturen“ mit zwei Items:

  1. Öffne im TypeWriter-Web-Panel eine Manifest-Seite und füge einen Discovery Codex Category-Entry hinzu.
  2. Setze category auf eine eindeutige Kennung wie forest_creatures, einen title, rows (zum Beispiel 3) und ein icon.
  3. Setze itemSlotRange auf die zu füllenden Slots, zum Beispiel 10-16 (die Nummern beginnen bei 1), und wähle guiLayout.
  4. Füge in items ein Item hinzu: entryId wolf, ein item, das im freigeschalteten Zustand angezeigt wird, ein lockedItem, das davor angezeigt wird, und in criteria den Fact, der „der Spieler hat einen Wolf gesehen“ bedeutet. Füge unlockedLore und lockedLore hinzu.
  5. Füge einem Static- oder Sequence-Seiten-Entry eine Open Discovery Codex-Action hinzu, setze definition auf deine Kategorie und löse sie über einen NPC, ein Item oder eine Dialogoption aus. Du kannst auch /tw codex open forest_creatures verwenden.
  6. Veröffentliche und öffne den Codex. Items, deren Criteria nicht erfüllt sind, bleiben gesperrt.
Items ohne Criteria

Ein Item mit leerer criteria-Liste ist immer freigeschaltet. Füge jedem Item, das du verbergen möchtest, Criteria hinzu.

So funktioniert es​

Eine Kategorie zeigt entweder ihre Unterkategorien und Rezeptkategorien (wenn andere Kategorien sie als parentCategory nennen) oder ihre eigenen Items. Kategorie-Criteria und Item-Criteria werden jedes Mal ausgewertet, wenn das Menü für den Spieler aufgebaut wird.

Menüs​

Jede Discovery Codex Category ist ein eigenes Inventarmenü mit rows Reihen (1 bis 6). Items kommen in die Slots von itemSlotRange (zum Beispiel 1-25, ab 1 gezählt) oder ab startSlot, reihen- oder spaltenweise gefüllt. Die Buttons haben Standardwerte: vorherige Seite in Slot 0, nächste Seite in Slot 8, Info in Slot 4 und Zurück in Slot 44. Standardmäßig verwenden sie Pfeile und ein Buch und können mit previousButton, nextButton, infoButton und backButton ersetzt werden. Der Zurück-Button erscheint nur, wenn die Kategorie aus einer übergeordneten geöffnet wurde. Ein background-Item füllt jeden freien Slot.

Das Feld guiLayout bestimmt, wie Items angeordnet werden, wenn sie nicht auf eine Seite passen: PAGINATED (Seiten-Buttons), SCROLLABLE (Scroll-Buttons), FRAME (ein Frame pro Reihe) oder SIMPLE (alles auf einem Bildschirm).

Name und Lore eines Kategorie-Icons (iconName, iconLore, lockedIconLore) können {unlocked}, {locked}, {total} und {percent} verwenden, die ersetzt werden, wenn das Icon in einer übergeordneten Kategorie oder im globalen Menü angezeigt wird. Die anderen Lore-Felder (Items, Info- und Navigations-Buttons) werden so angezeigt, wie sie geschrieben sind, auch wenn ihr Hilfetext Platzhalter aufführt.

Ein Blatt-Item, dessen entryId zu einer entryId einer Recipe Category passt, öffnet beim Klick die Rezeptansicht. Die Rezeptansicht zeigt das Crafting-Raster in craftingGridSlots und das Ergebnis in resultSlot; ein Rezept, das auf dem Server nicht registriert ist, zeigt ein Barriere-Item namens „Recipe not found“.

Die Action Codex Global Menu öffnet einen Hub, der aus einem GUI-Layout-Pool gebaut ist. Platziere codex_button:CODEX_CATEGORY-Marker (mit count, gap und direction, um sie zu wiederholen), und jeder Marker wird mit einer Kategorie der obersten Ebene gefüllt, nach order sortiert. Eine Kategorie ohne passenden Marker wird nicht angezeigt, und ein Marker ohne Kategorie bleibt leer. CODEX_BACK geht zurück, und CODEX_INFO, CODEX_PAGE_NEXT und CODEX_PAGE_PREV sind in dieser Version einfache Dekorations-Items.

CODEX_RECIPE-Marker zeigen Rezepte: Der N-te Marker, in der Reihenfolge seines Auftretens im Layout (wie bei CODEX_CATEGORY), zeigt das Icon des N-ten Rezepts. Die Rezepte aller Recipe Categories werden in einer flachen Liste zusammengefasst, wobei die Kategorien nach order sortiert sind und die Rezepte in der Reihenfolge ihrer Liste stehen. Ein Klick auf ein freigeschaltetes Rezept öffnet seine Detailansicht. Gibt es mehr Rezepte als Marker, werden die überzähligen Rezepte nicht angezeigt; gibt es mehr Marker als Rezepte, bleiben die überzähligen Marker leer.

Marker-Abstand

Bei count-Markern ist gap eine Schrittweite, kein Abstand: 1 platziert die Slots nebeneinander und 2 lässt einen leeren Slot dazwischen. Der Codex nutzt die gemeinsame GUI-Formel. Das ist dieselbe Regel, die seit Quest Codex 0.3.0 für Quest-Codex-Marker gilt, ein aus einem älteren Quest-Codex-Menü kopiertes Layout muss also unter Umständen sein gap verdoppeln. Die Layout-Referenz findest du in der GUI-Erweiterung.

Die Kategoriemenüs selbst können sich in einem gemeinsamen Chassis öffnen, wenn baseMenuId gesetzt ist (verwende rows von 3 oder weniger, damit sie in den Inhaltsbereich passen). Die UiCore-Erweiterung kann den Codex ebenfalls anzeigen: Ihr Codex-Bildschirm sortiert Kategorien der obersten Ebene in vier Tabs (Bestiary, Items, Places und Fragments), indem er in Kennung und Name der Kategorie nach Schlüsselwörtern wie fragment, place, region, item oder recipe sucht, und ordnet alles andere dem Bestiary zu.

Konfiguration​

Die Erweiterung hat keine Konfigurationsdatei. Der Zustand wird in zwei Artifacts gehalten, die beide einige Sekunden nach einer Änderung und beim Entladen von TypeWriter gespeichert werden:

  • Codex Unlock merkt sich, welche Freischalt-Trigger für jeden Spieler bereits ausgelöst wurden.
  • Fragment Storage merkt sich die Fragmente, die jeder Spieler gesammelt hat, pro Gruppe.

Befehle​

BefehlBeschreibung
/tw codex open <category> [targets]Öffnet die Kategorie mit dieser category-Kennung für dich oder die ausgewählten Spieler. Alias: /tw dcx open.

Der Befehl hat über den Zugriff auf den TypeWriter-Befehl hinaus keine eigene Berechtigungsprüfung. Eine Kategorie, deren Criteria nicht erfüllt sind, antwortet „This codex is locked“, und eine unbekannte Kennung antwortet „Unknown category“.

Die Erweiterung registriert außerdem einen internen Befehl /codexmenu, der von Menüklicks verwendet wird (category, recipecat, recipe). Er funktioniert nur für Spieler und ist nicht dafür gedacht, von Hand eingegeben zu werden.

Platzhalter​

Dies sind MiniPlaceholders-Tags der Expansion discoverycodex, verfügbar in jedem MiniMessage-Text, der Platzhalter unterstützt. Ersetze cat durch die category-Kennung und item durch die entryId des Items. Kennungen dürfen Unterstriche enthalten.

PlatzhalterLiefert
<discoverycodex_category_unlocked:cat>Anzahl der für den Spieler freigeschalteten Items der Kategorie.
<discoverycodex_category_total:cat>Anzahl der Items in der Kategorie.
<discoverycodex_category_locked:cat>Anzahl der für den Spieler gesperrten Items.
<discoverycodex_category_percent:cat>Prozentsatz der freigeschalteten Items, von 0 bis 100.
<discoverycodex_category_name:cat>Den Namen des Kategorie-Entrys.
<discoverycodex_item_unlocked:item>true oder false für dieses Item.

Entries​

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

Aktionen2
Artefakte2
Manifeste6

Fehlerbehebung​

Die Erweiterung lädt nicht. Codex benötigt die Erweiterungen Basic und GUI (GuiAndDialogs). Suche im Startlog von TypeWriter nach der fehlenden Abhängigkeit.

Freischalt-Trigger werden nie ausgelöst. Das Log meldet „No CodexUnlockArtifactEntry configured: skipping unlock triggers“. Füge einer veröffentlichten Seite ein Codex Unlock-Artifact hinzu. Ohne es werden die Trigger absichtlich übersprungen, damit Belohnungen nach jedem Neustart nicht erneut vergeben werden.

Freischalt-Trigger wurden einmal ausgelöst und nie wieder. Das ist beabsichtigt: Jeder Trigger wird pro Spieler einmal ausgelöst, und der Eintrag wird im Artifact gespeichert. Um erneut zu testen, verwende einen neuen Spieler oder entferne seine Daten aus dem Artifact.

Die Items landen in den falschen Slots oder der letzte Slot ist leer. itemSlotRange zählt ab 1 (1-25 bedeutet die Slots 0 bis 24 des Inventars). Slots außerhalb der Menügröße werden ignoriert, und Items über die Slot-Anzahl hinaus kommen auf die nächste Seite.

Ein Rezept zeigt „Recipe not found“. recipeKey muss der Namespaced Key eines auf dem Server registrierten Rezepts sein, etwa minecraft:iron_pickaxe. Rezepte anderer Plugins verwenden ihren eigenen Namespace.

Ein Fragment wird nicht gesammelt. Der Spieler muss das Item aufheben: Es muss zu customItem passen (oder zu displayItem, wenn customItem leer ist), und das Log darf nicht „No FragmentArtifactEntry found“ melden. Füge ein Fragment Storage-Artifact hinzu. Ein bereits gesammeltes Fragment wird nicht erneut verbraucht.

Die Gruppe wird nie abgeschlossen. requiredCount ist standardmäßig 0, was jedes in fragments aufgeführte Fragment bedeutet; eine Zahl über der Listenlänge wird auf die Listenlänge begrenzt. Die groupId der Gruppe muss derselbe Text sein wie die fragmentGroup ihrer Fragmente.

Marker in einem globalen Menü sind einen Slot auseinander. gap ist eine Schrittweite, verwende also gap 2, um zwischen Markern einen leeren Slot zu lassen.

Verwandte Erweiterungen​

  • GUI — Menü-Engine, Layouts und Marker.
  • Quest Codex — Quest-Menüs; Codex ist ein optionaler Begleiter.
  • UiCore — kann den Codex in seiner eigenen Oberfläche darstellen.