Quest Codex
Überblick
Quest Codex gibt Spielern ein Questbuch. Ein Hauptmenü listet Kategorien auf (Hauptgeschichte, Nebenquests, Dungeons ...), jede Kategorie öffnet eine Liste ihrer Quests, und ein Klick auf eine aktive Quest verfolgt sie. Die Quests selbst sind diejenigen, die du mit der offiziellen TypeWriter-Erweiterung Quest erstellst: Quest Codex organisiert und zeigt sie nur an.
Du zeichnest jeden Bildschirm selbst. Ein Menü ist ein Layout der Erweiterung GUI, in dem du Marker-Items platzierst: Ein QUEST_SLOT-Marker wird durch die Quests des Spielers ersetzt, ein CATEGORY_SLOT-Marker durch Kategorien, ein SORT_SLOT-Marker durch den Sortier-Button. Alles um die Marker herum (Rahmen, Titel, Buttons, Scrollen, Seiten) ist gewöhnlicher GUI-Inhalt.
Über das Menü hinaus bietet die Erweiterung das Tracking mehrerer Quests, das Wiederverbindungen übersteht, die Wiederherstellung eines unterbrochenen Dialogs oder einer unterbrochenen Cinematic, clientseitige GPS-Waypoints und Locator-Bar-Punkte, benutzerdefinierte Minecraft-Advancements, die von einer Page aus vergeben werden, sowie Quest-Icons auf BlueMap.
Funktionen
- Kategorien — verschachtelte Kategorien mit Reihenfolge, Icon, Sichtbarkeit und Abschluss-Criteria sowie Nachrichten pro Status.
- Quest-Zuordnung — Quests einer Kategorie zuordnen, ihre Reihenfolge festlegen und Icon, Name, Lore und Sichtbarkeit pro Status überschreiben.
- Layout-Pools — du gestaltest jedes Menü mit GUI-Layouts; der Codex befüllt die Marker
QUEST_SLOT,CATEGORY_SLOT,TRACKED_QUEST_SLOTundSORT_SLOT. - Sortier-Button — wechselt zwischen Alle, Nicht begonnen, In Bearbeitung und Abgeschlossen, mit Bezeichnung, Icon und Lore pro Modus.
- Multi-Tracking — mehrere aktive Quests gleichzeitig verfolgen; die letzte ist die primäre Quest des offiziellen HUD-Trackers.
- Menü der verfolgten Quests — ein eigenes Menü mit den Quests, die der Spieler verfolgt.
- Waypoints — reine Paket-Ebenen für Text, Block und Beacon, die auf ein Objective, eine Position oder eine Entity zeigen, plus eine Variante für die Vanilla-Locator-Bar.
- Wiederherstellung von Interaktionen — stellt den aktiven Dialog oder die aktive Cinematic nach einer Trennung wieder her.
- Advancements — Minecraft-Advancement-Tabs im Panel definieren und per Aktion vergeben.
- BlueMap-Icons — ein Quest-Icon mit Popup auf BlueMap platzieren.
Installation
- Installiere TypeWriter auf einem Paper- oder Folia-Server, mit seiner offiziellen Erweiterung Quest, die die Quests definiert, die Quest Codex anzeigt.
- Installiere die Erweiterung GUI (Version 0.18 oder neuer).
- Optional: Installiere PacketEvents (von TypeWriter ohnehin benötigt) für Waypoints und BlueMap für Karten-Icons.
- Lade die Quest-Codex-JAR von den GitHub-Releases herunter (der Button im Übersichtspanel oben), lege sie in
plugins/Typewriter/extensions/ab und starte den Server neu. - Gib deinen Spielern die Berechtigung
typewriter.codex.open, siehe Berechtigungen weiter unten.
Erste Schritte
Baue ein Questlog mit einer Kategorie:
- Füge auf einer statischen Page einen Quest Codex Tracking Data-Entry hinzu. Hier werden verfolgte Quests gespeichert.
- Füge auf einer Manifest-Page einen Quest Codex Global Settings-Entry hinzu. Setze
trackingArtifactauf das Artifact und prüfemaxTrackedQuestsund die Sounds. - Füge einen Quest Category-Entry mit
categorymain_quests, einemtitlewie<gold>Main Storyund einemiconhinzu. - Füge einen Quest Assignment-Entry mit
categorymain_questsund deinen Quests inquestRefshinzu.ordersist optional. - Erstelle zwei Open GUI-Entries, die nur als Container für Layouts dienen. Füge im ersten,
main_gui, einsimple-Layout mit deridmainhinzu, setzemainLayoutIdaufmain,guiTypeaufCUSTOMundsizeaufSIZE_36. Füge ein Item mitbuttonPrefixcodex_button:,buttonTypeCATEGORY_SLOT,x1,y1,count7 unddirectionrighthinzu. Mache im zweiten,quests_gui, dasselbe mit dem MarkerQUEST_SLOTund füge in der untersten Reihe einCLOSE-Item hinzu. - Füge ein Category Menu mit leerer
category,rows4undmenuaufmain_guigesetzt hinzu. Das ist das Hauptmenü. - Füge ein zweites Category Menu mit
categorymain_quests,rows4undmenuaufquests_guigesetzt hinzu. - Veröffentliche und führe dann im Spiel
/tw codexaus. Klicke auf die Kategorie und dann auf eine aktive Quest, um sie zu verfolgen.
Das Inventar wird aus den rows des Category Menu aufgebaut und nicht aus der size des Open GUI. Weichen beide voneinander ab, werden Slots unterhalb der kleineren Höhe verworfen, und die Konsole warnt dich beim Start.
Ein Marker-Slot zeigt eine Quest. Verwende count, direction, gap und repeatY, um einen Marker über ein Raster zu verteilen: count 7, direction right und repeatY 3 ergeben 21 Quest-Slots. Ohne direction bleibt der Marker ein einzelner Slot. Quests füllen die Marker in Leserichtung, und die nächste Seite mit Quests erreichst du über einen PAGE_NEXT-Button.
Funktionsweise
Beim Start lädt die Erweiterung die Kategorien, die Zuordnungen und die Menüs. Wenn ein Spieler ein Menü öffnet, schreibt sie jeden Marker des Layouts in einen indizierten Marker um (QUEST_SLOT#0, QUEST_SLOT#1, ...), bevor das Layout geparst wird, sodass sich Marker innerhalb von scrollable-, paginated- und frame-Layouts wie gewöhnliche Slots verhalten. Beim Rendern wird jeder Marker durch die n-te Quest oder Kategorie ersetzt.
Menüs
Welche Entries ein Menü bilden
Ein Category Menu ist der Entry, den du öffnest. Sein Feld menu verweist auf einen Open GUI-Entry, der nur den Layout-Pool, das Hauptlayout, den Fenstertyp und die Sounds liefert. Löse dieses Open GUI nicht selbst aus.
category des Category Menu | Menü | Marker, den es enthalten muss |
|---|---|---|
| leer | Hauptmenü mit den Wurzelkategorien | CATEGORY_SLOT |
| ein Kategoriename | Quests dieser Kategorie | QUEST_SLOT |
@tracked | Quests, die der Spieler verfolgt | TRACKED_QUEST_SLOT |
Jede definierte Kategorie benötigt ein Category Menu, andernfalls bewirkt das Öffnen nichts, und die Konsole meldet dies beim Start.
Marker und Buttons
Setze buttonPrefix auf codex_button: und buttonType auf einen der folgenden Werte:
buttonType | Aufgabe |
|---|---|
CATEGORY_SLOT | Ein Kategorie-Icon mit Titel, Fortschritt {completed}/{total}, Klickhinweis und Statusnachricht. Ein Klick öffnet die Kategorie. |
QUEST_SLOT | Eine Quest. Das Icon folgt ihrem Status, Name und Lore stammen aus der Quest, der Zuordnung und den Quest-Lore-Entries. Ein Klick auf eine aktive Quest verfolgt sie oder beendet die Verfolgung. |
TRACKED_QUEST_SLOT | Eine verfolgte Quest im Menü @tracked. Ein leerer Slot behält dein eigenes Item und bleibt inaktiv, ist also dein Leerzustand. |
SORT_SLOT | Der Sortier-Button. Konfiguriere jeden Modus in sortDisplay des Category Menu. |
PAGE_NEXT, PAGE_PREV | Zur nächsten oder vorherigen Seite mit Quests oder Kategorien wechseln. |
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHT | Das Menü scrollen. |
BACK | Kehrt zum Hauptmenü zurück, falls es eines gibt, sonst zum Entry mainMenuTrigger, sonst zum vorherigen Menü, sonst wird geschlossen. |
CLOSE | Schließt das Menü. |
SORT | Ein Sortier-Button, der als einfacher Navigations-Slot platziert wird. |
Navigations-Buttons behalten das von dir konfigurierte Item, den Namen und die Lore; der eingebaute Pfeil, die Barriere oder der Trichter wird nur verwendet, wenn der Slot kein Item hat.
Platziere Marker in simple-Layouts, die zu dem durch menu referenzierten Open GUI gehören. Marker in anderen Layouttypen oder in den Layouts eines gemeinsamen Grundgerüsts werden nicht indiziert und bleiben verborgen.
Grundgerüst, Ansichten und Tabs
Um ein Questbuch mit Tabs zu bauen, setze baseMenuId am Category Menu auf eine gemeinsame Open-GUI-Hülle und füge views, defaultViewId und breadcrumbSeparator hinzu, genau wie in Ansichten, Tabs und Vererbung. pushHistoryOnViewSwitch sorgt dafür, dass Zurück zum vorherigen Tab führt. Ein Grundgerüst, dessen Wurzel-Layout eine _extended-Variante hat, erhält automatisch die Zehn-Reihen-Fläche.
Quest-Anzeige
- Ein Quest-Icon ist standardmäßig ein Buch, eine Uhr oder ein Smaragd für nicht begonnen, in Bearbeitung und abgeschlossen. Überschreibe es pro Status im Quest Assignment (
notStartedItem,inProgressItem,completedItem). notStartedName,inProgressNameundcompletedNameersetzen den Quest-Namen, und die passenden Lore-Felder fügen Zeilen hinzu. Verberge eine Quest pro Status mithideWhenNotStarted,hideWhenInProgressundhideWhenCompleted.- Ein Quest Lore-Entry fügt einer Quest pro Status Zeilen hinzu, in einer Kategorie oder in allen.
- Die Quest-Reihenfolge richtet sich zuerst nach
orders, dann nach der Reihenfolge vonquestRefs. Eine Kategorie listet auch die Quests ihrer Unterkategorien auf. - Das Hauptmenü listet nur Kategorien der obersten Ebene (ohne
parent). Eine Unterkategorie wird mit/tw codex <category>oder einem Button geöffnet, dercodex:open <category>ausführt.
Konfiguration
Der Entry Quest Codex Global Settings enthält die Optionen, die nicht an ein Menü gebunden sind. Erstelle nur einen; ohne ihn werden Standardwerte verwendet.
- Sounds —
soundOnOpen,soundOnSwitch,soundOnClick,soundOnTrack,soundOnUntrack. - Tracking —
multiTrackingEnabled,maxTrackedQuests(mindestens 1) undtrackingArtifact. Ohne Artifact werden verfolgte Quests nur im Speicher gehalten, und die Konsole warnt beim Start. Das Artifact ist eine Datei, die ihreartifactIdbehalten muss, sobald Spieler es nutzen. - Wiederherstellung —
recoveryEnabled,recoveryArtifact,recoveryRetentionSeconds(10 bis 86400) undrecoveryRestoreDelayTicks(1 bis 20). Verlässt ein Spieler den Server während eines Dialogs oder einer Cinematic, wird der Snapshot gespeichert und kurz nach dem erneuten Beitritt des Spielers wiederhergestellt. Ohne Artifact ist die Wiederherstellung deaktiviert. - Nachrichten —
nowTrackingMessage,stoppedTrackingMessage,questInactiveMessage,questCompletedMessage,trackingLimitMessage({quest},{max}),categoryProgressMessage({completed},{total}) sowie die Hinweise zu Kategorie- und Quest-Lore. - Navigationsbeschriftungen —
navLabelslegt den Namen jedes eingebauten Buttons fest (next,previous,up,down,left,right,back,close,sort). Er wird nur verwendet, wenn der markierte Slot kein eigenes Item hat: Ein Slot mit einem Item behält seinen eigenen Namen und seine Lore. - Sortier-Button —
sortTextslegt die Beschriftung jedes Sortiermodus fest (allLabel,notStartedLabel,activeLabel,completedLabel) sowie die Lore-Zeilehint. Ein Category Menu, das in seinemsortDisplayfür einen Modus einlabeloderloresetzt, behält sein eigenes. - Menütitel —
mainMenuTitleundtrackedQuestsTitlesind die Titel, die verwendet werden, wenn das passende Category Menu einen leerentitlehat. - Befehlsfehler —
unknownCategoryMessageist der Fehler, den/tw codex <category>für eine nicht existierende Kategorie anzeigt ({category}). - Fallback fürs Hauptmenü —
mainMenuTriggerwird ausgelöst, wenn es kein Haupt-Category-Menu gibt, zum Beispiel ein eigenes Open GUI, dessen Buttonscodex:open <category>ausführen.
Waypoints und Locator Bar
Quest Codex Waypoint ist ein Audience-Entry: Verbinde ihn mit einem Audience-Filter, um zu bestimmen, wer ihn sieht. Sein target ist eine feste Position, ein auffindbares Objective, das verfolgte Objective (Auswahl HIGHEST_PRIORITY, FIRST, CLOSEST, ALL oder ONE_PER_QUEST) oder eine Entity. Seine layers kombinieren eine Text-Ebene (Platzhalter {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} und {eta}), eine Block-Ebene und eine Beacon-Ebene. displayMode ist HUD_LOCKED (Standard), WORLD_DIRECTIONAL, TARGET_ANCHORED oder ADAPTIVE, und jede Ebene kann ihn überschreiben. Alles wird per Paket gesendet; es wird keine Entity in der Welt gespeichert.
Quest Codex Locator Bar zeigt dieselben Ziele als Punkte auf der Vanilla-Locator-Bar an, die Minecraft 1.21.6 oder neuer benötigt, und ergänzt einen 3D-Waypoint.
Advancements und BlueMap
- Advancement Definition beschreibt ein Advancement. Eines ohne
parentwird zu einem Tab. Sie werden beim Start in ein Datapack namensquestcodex_advancementsim Weltordner geschrieben, und der Server lädt seine Daten neu, wenn sich der Inhalt geändert hat, eine neue Definition erfordert also einen Neustart. Das Advancement wird nur durch die Aktion Grant Advancement erworben. - BlueMap Icon platziert beim Start einen Marker mit Bezeichnung und Popup auf den BlueMap-Karten seiner Welt. In
descriptionwird<objectives>durch die Objectives der Quest ersetzt.
Befehle
Alle Befehle sind Unterbefehle von /typewriter, meist als /tw eingegeben, und erfordern typewriter.codex.open.
| Befehl | Beschreibung |
|---|---|
/tw codex | Öffnet das Hauptmenü: das Category Menu mit leerer category, andernfalls der Entry mainMenuTrigger. |
/tw codex tracked | Öffnet das Menü der verfolgten Quests. |
/tw codex <category> | Öffnet eine Kategorie. Die Tab-Vervollständigung listet die definierten Kategorien auf. |
Menü-Buttons können außerdem diese internen Befehle ausführen: codex:open <category>, codex:tracked, codex:quest <quest_id> und codex:nav <action>. Verwende codex:open und codex:tracked in den Buttons deiner eigenen GUI-Menüs.
Berechtigungen
| Berechtigung | Gewährt |
|---|---|
typewriter.codex.open | Jeden /tw codex-Befehl. Die Erweiterung deklariert sie mit einem Standard nur für Operatoren, und sie erscheint in deinem Berechtigungs-Plugin: Vergib sie an die Gruppen, die /tw codex verwenden dürfen. |
Das Öffnen eines Menüs über eine Category-Menu-Aktion oder einen Menü-Button erfordert keine Berechtigung.
Platzhalter
PlaceholderAPI-Platzhalter mit der Expansion typewriter. Sie benötigen einen Spieler.
| Platzhalter | Gibt zurück |
|---|---|
%typewriter_total_quests% | Anzahl der Quests über alle Kategorien. |
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started% | Anzahl der Quests in jedem Status für den Spieler. |
%typewriter_total_progress% | Abgeschlossen im Verhältnis zur Gesamtzahl, zum Beispiel 15/42. |
%typewriter_category_<name>% | Anzahl der Quests in der Kategorie. |
%typewriter_category_<name>_completed%, _in_progress%, _not_started% | Quests der Kategorie in diesem Status. |
%typewriter_category_<name>_progress% | Abgeschlossen im Verhältnis zur Gesamtzahl für die Kategorie. |
%typewriter_codex_tracked_count%, _limit% | Anzahl der verfolgten Quests und das Maximum. |
%typewriter_codex_tracked_multi_enabled%, _has_any% | true oder false. |
%typewriter_codex_tracked_ids%, _names%, _names_lines% | IDs oder Namen der verfolgten Quests, kommagetrennt oder eine pro Zeile. |
%typewriter_codex_tracked_primary_id%, _primary_name% | Die primäre Quest, die der offizielle Tracker anzeigt. |
%typewriter_codex_tracked_has_<quest_id>% | Ob diese Quest verfolgt wird. |
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary% | Details der n-ten verfolgten Quest, ab 1. Leer, wenn es keine gibt. |
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority% | Sichtbare Objectives der n-ten verfolgten Quest. |
<name> ist der Kategoriename, ohne Beachtung der Groß- und Kleinschreibung verglichen. Mehr Details unter Platzhalter, Befehle und Berechtigungen.
Entries
12 Einträge, aus dem Quellcode der Erweiterung generiert.
Aktionen2
- Category MenuCategory Menu Configuration
- Grant AdvancementGrant Advancement
Zielgruppen2
- Quest Codex Locator BarQuest Codex Locator Bar
- Quest Codex WaypointQuest Codex Waypoint
Artefakte2
- Quest Codex Recovery ArtifactQuest Codex Recovery Data
- Quest Codex Tracking ArtifactQuest Codex Tracking Data
Manifeste6
- Advancement DefinitionAdvancement Definition
- Bluemap IconAdds an icon to BlueMap for a specific quest
- Quest AssignmentQuest Assignment to Category
- Quest CategoryQuest Category
- Quest CodexQuest Codex Global Settings
- Quest LoreQuest Additional Lore
Fehlerbehebung
/tw codex bewirkt nichts. Es gibt kein Category Menu mit leerer category und keinen mainMenuTrigger. Die Konsole protokolliert Main menu could not open mit der Ursache. Erstelle für eine Kategorie ein Category Menu, dessen category der category der Quest Category entspricht.
Ein Menü öffnet sich ohne Inhalt. Die Konsole meldet es beim Start: Kein Slot des referenzierten Open GUI trägt den vom Menü benötigten Marker (CATEGORY_SLOT, QUEST_SLOT oder TRACKED_QUEST_SLOT), menu ist leer oder kein Open GUI, der Layout-Pool ist leer, oder mainLayoutId ist nicht darin enthalten. Marker benötigen buttonPrefix codex_button:.
Slots in den unteren Reihen fehlen. Die rows des Category Menu sind kleiner als die size des Open GUI. Setze beide auf dieselbe Anzahl an Reihen.
Quests erscheinen einen Slot auseinander statt mit einem leeren Slot dazwischen. gap ist eine Schrittweite: 1 bedeutet direkt nebeneinander, 2 lässt einen Slot frei. Vor Quest Codex 0.3.0 geschriebene Menüs verwendeten gap als Abstand, verdopple den Wert also. Eine Kollision mit einer Dekoration wird als Slot overlap-Warnung gemeldet.
Mehrere Marker stapeln sich auf einem Feld. Der Marker hat count, aber keine direction, oder die Position liegt außerhalb des Rasters. Setze eine direction.
Eine Quest fehlt in einer Kategorie. Die Quest ist durch eine hideWhen...-Option für ihren aktuellen Status verborgen, der aktuelle Sortiermodus filtert sie heraus, oder die Zuordnung konnte sie nicht auflösen (Quest '...' could not be resolved in der Konsole).
Eine verfolgte Quest verschwindet nach einem Neustart. trackingArtifact ist leer, oder seine artifactId hat sich geändert. Eine Quest, die nicht mehr aktiv ist, wird aus der Liste der verfolgten Quests entfernt.
Waypoints werden nicht angezeigt. Der Waypoint-Entry muss in einer Audience liegen, zu der der Spieler passt, die Quest muss verfolgt werden, und das Objective muss auffindbar sein. Eine Text-Ebene mit {icon} bleibt leer, bis icon gesetzt ist.
Ein neues Advancement ist dem Server unbekannt. Definitionen werden beim Start geschrieben; starte nach dem Hinzufügen neu. Eine Definition, deren Icon kein Item ist, wird mit einer Warnung übersprungen.