Quest Codex

Menus de journal de quêtes avec catégories, suivi multiple, points de passage GPS, progrès et icônes BlueMap.

Gratuitesv2.16Quêtes et narration

NécessiteTypeWriter0.9QuestGUI0.18+BlueMapfacultatif

TéléchargerCode sourceSupport

Présentation

Quest Codex donne aux joueurs un livre de quêtes. Un menu principal liste des catégories (Histoire principale, Quêtes secondaires, Donjons...), chaque catégorie ouvre la liste de ses quêtes, et un clic sur une quête active la suit. Les quêtes elles-mêmes sont celles que vous créez avec l'extension Quest officielle de TypeWriter : Quest Codex ne fait que les organiser et les afficher.

Vous dessinez chaque écran vous-même. Un menu est un layout de l'extension GUI dans lequel vous placez des objets marqueurs : un marqueur QUEST_SLOT est remplacé par les quêtes du joueur, un marqueur CATEGORY_SLOT par des catégories, un marqueur SORT_SLOT par le bouton de tri. Tout ce qui entoure les marqueurs (bordures, titres, boutons, défilement, pages) est du contenu GUI ordinaire.

Au-delà du menu, l'extension ajoute un suivi multi-quêtes qui survit aux reconnexions, la récupération d'un dialogue ou d'une cinématique interrompus, des waypoints GPS côté client et des points sur la barre de localisation, des advancements Minecraft personnalisés attribués depuis une page, ainsi que des icônes de quêtes sur BlueMap.

Fonctionnalités

• Catégories — catégories imbriquées avec ordre, icône, visibilité et critères d'achèvement, et messages par statut.
• Assignation des quêtes — placez des quêtes dans une catégorie, définissez leur ordre, et surchargez l'icône, le nom, le lore et la visibilité par statut.
• Pools de layouts — vous concevez chaque menu avec des layouts GUI ; le codex remplit les marqueurs QUEST_SLOT, CATEGORY_SLOT, TRACKED_QUEST_SLOT et SORT_SLOT.
• Bouton de tri — parcourt Toutes, Non commencées, En cours et Terminées, avec un libellé, une icône et un lore par mode.
• Suivi multiple — suivez plusieurs quêtes actives à la fois ; la dernière est la quête principale du suivi officiel sur le HUD.
• Menu des quêtes suivies — un menu dédié aux quêtes que le joueur suit.
• Waypoints — couches de texte, de bloc et de balise uniquement par paquets pointant vers un objectif, une position ou une entité, ainsi qu'une variante pour la barre de localisation vanilla.
• Récupération des interactions — restaure le dialogue ou la cinématique actifs après une déconnexion.
• Advancements — définissez des onglets d'advancements Minecraft dans le panneau et attribuez-les avec une action.
• Icônes BlueMap — placez une icône de quête avec une fenêtre contextuelle sur BlueMap.

Installation

1. Installez TypeWriter sur un serveur Paper ou Folia, avec son extension officielle Quest, qui définit les quêtes affichées par Quest Codex.
2. Installez l'extension GUI (version 0.18 ou ultérieure).
3. Facultatif : installez PacketEvents (déjà requis par TypeWriter) pour les waypoints, et BlueMap pour les icônes de carte.
4. Téléchargez le JAR de Quest Codex depuis les releases GitHub (le bouton du panneau de synthèse ci-dessus), placez-le dans plugins/Typewriter/extensions/ et redémarrez le serveur.
5. Donnez à vos joueurs la permission typewriter.codex.open, voir Permissions ci-dessous.

Premiers pas

Construisez un journal de quêtes avec une catégorie :

1. Sur une page statique, ajoutez une entrée Quest Codex Tracking Data. C'est là que les quêtes suivies sont sauvegardées.
2. Sur une page manifest, ajoutez une entrée Quest Codex Global Settings. Définissez trackingArtifact sur l'artifact, et passez en revue maxTrackedQuests et les sons.
3. Ajoutez une entrée Quest Category avec category main_quests, un title tel que <gold>Main Story et une icon.
4. Ajoutez une entrée Quest Assignment avec category main_quests, et vos quêtes dans questRefs. orders est facultatif.
5. Créez deux entrées Open GUI servant uniquement de conteneurs de layouts. Dans la première, main_gui, ajoutez un layout simple avec l'id main, définissez mainLayoutId sur main, guiType sur CUSTOM et size sur SIZE_36. Ajoutez un objet avec buttonPrefix codex_button:, buttonType CATEGORY_SLOT, x 1, y 1, count 7 et direction right. Dans la seconde, quests_gui, faites de même avec le marqueur QUEST_SLOT, et ajoutez un objet CLOSE sur la dernière ligne.
6. Ajoutez un Category Menu avec un category vide, rows 4 et menu défini sur main_gui. C'est le menu principal.
7. Ajoutez un second Category Menu avec category main_quests, rows 4 et menu défini sur quests_gui.
8. Publiez, puis exécutez /tw codex en jeu. Cliquez sur la catégorie, puis sur une quête active pour la suivre.

Gardez rows et size identiques

L'inventaire est construit à partir de rows du Category Menu et non de size de l'Open GUI. S'ils diffèrent, les emplacements situés sous la plus petite hauteur sont supprimés et la console vous avertit au démarrage.

Marqueurs

Un emplacement de marqueur affiche une quête. Utilisez count, direction, gap et repeatY pour étendre un marqueur sur une grille : count 7, direction right et repeatY 3 donnent 21 emplacements de quêtes. Sans direction, le marqueur reste un seul emplacement. Les quêtes remplissent les marqueurs dans l'ordre de lecture, et la page suivante de quêtes s'atteint avec un bouton PAGE_NEXT.

Fonctionnement

Au démarrage, l'extension charge les catégories, les assignations et les menus. Lorsqu'un joueur ouvre un menu, elle réécrit chaque marqueur du layout en marqueur indexé (QUEST_SLOT#0, QUEST_SLOT#1, ...) avant l'analyse du layout, de sorte que les marqueurs se comportent comme des emplacements ordinaires dans les layouts scrollable, paginated et frame. Au rendu, chaque marqueur est remplacé par la n-ième quête ou catégorie.

Menus

Quelles entrées forment un menu

Un Category Menu est l'entrée que vous ouvrez. Son champ menu pointe vers une entrée Open GUI qui ne fournit que le pool de layouts, le layout principal, le type de fenêtre et les sons. Ne déclenchez pas vous-même cet Open GUI.

category du Category Menu	Menu	Marqueur qu'il doit contenir
vide	Menu principal listant les catégories racines	CATEGORY_SLOT
un nom de catégorie	Quêtes de cette catégorie	QUEST_SLOT
@tracked	Quêtes que le joueur suit	TRACKED_QUEST_SLOT

Chaque catégorie définie a besoin d'un Category Menu, sinon l'ouvrir ne fait rien et la console l'indique au démarrage.

Marqueurs et boutons

Définissez buttonPrefix sur codex_button: et buttonType sur l'une des valeurs suivantes :

buttonType	Rôle
CATEGORY_SLOT	L'icône d'une catégorie, avec son titre, sa progression {completed}/{total}, l'indication de clic et le message de statut. Un clic ouvre la catégorie.
QUEST_SLOT	Une quête. L'icône suit son statut, le nom et le lore proviennent de la quête, de l'assignation et des entrées Quest Lore. Cliquer sur une quête active la suit ou arrête son suivi.
TRACKED_QUEST_SLOT	Une quête suivie dans le menu @tracked. Un emplacement vide conserve votre propre objet et reste inerte : c'est donc votre état vide.
SORT_SLOT	Le bouton de tri. Configurez chaque mode dans sortDisplay du Category Menu.
PAGE_NEXT, PAGE_PREV	Passent à la page suivante ou précédente des quêtes ou des catégories.
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHT	Font défiler le menu.
BACK	Retourne au menu principal s'il y en a un, sinon à l'entrée mainMenuTrigger, sinon au menu précédent, sinon ferme.
CLOSE	Ferme le menu.
SORT	Un bouton de tri placé comme simple emplacement de navigation.

Les boutons de navigation conservent l'objet, le nom et le lore que vous configurez ; la flèche, la barrière ou l'entonnoir intégré n'est utilisé que lorsque l'emplacement n'a pas d'objet.

Placez les marqueurs dans des layouts simple appartenant à l'Open GUI référencé par menu. Les marqueurs placés dans d'autres types de layouts, ou dans les layouts d'un châssis partagé, ne sont pas indexés et restent masqués.

Châssis, vues et onglets

Pour construire un livre de quêtes avec des onglets, définissez baseMenuId sur le Category Menu avec un Open GUI de base partagé, et ajoutez views, defaultViewId et breadcrumbSeparator, exactement comme dans Vues, onglets et héritage. pushHistoryOnViewSwitch fait que Retour ramène à l'onglet précédent. Un châssis dont le layout racine possède une variante _extended obtient automatiquement le canevas de dix lignes.

Affichage des quêtes

• L'icône d'une quête est par défaut un livre, une horloge ou une émeraude pour non commencée, en cours et terminée. Surchargez-la par statut dans le Quest Assignment (notStartedItem, inProgressItem, completedItem).
• notStartedName, inProgressName et completedName remplacent le nom de la quête, et les champs de lore correspondants ajoutent des lignes. Masquez une quête par statut avec hideWhenNotStarted, hideWhenInProgress et hideWhenCompleted.
• Une entrée Quest Lore ajoute des lignes par statut à une quête, dans une catégorie ou dans toutes.
• L'ordre des quêtes suit d'abord orders, puis l'ordre de questRefs. Une catégorie liste aussi les quêtes de ses sous-catégories.
• Le menu principal ne liste que les catégories de premier niveau (celles sans parent). Une sous-catégorie s'ouvre avec /tw codex <category> ou avec un bouton exécutant codex:open <category>.

Configuration

L'entrée Quest Codex Global Settings contient les options qui ne sont pas liées à un menu. N'en créez qu'une ; sans elle, les valeurs par défaut sont utilisées.

• Sons — soundOnOpen, soundOnSwitch, soundOnClick, soundOnTrack, soundOnUntrack.
• Suivi — multiTrackingEnabled, maxTrackedQuests (au moins 1) et trackingArtifact. Sans artifact, les quêtes suivies ne sont conservées qu'en mémoire et la console avertit au démarrage. L'artifact est un fichier qui doit conserver son artifactId dès que des joueurs l'utilisent.
• Récupération — recoveryEnabled, recoveryArtifact, recoveryRetentionSeconds (10 à 86400) et recoveryRestoreDelayTicks (1 à 20). Lorsqu'un joueur quitte pendant un dialogue ou une cinématique, l'instantané est stocké et restauré peu après son retour. Sans artifact, la récupération est désactivée.
• Messages — nowTrackingMessage, stoppedTrackingMessage, questInactiveMessage, questCompletedMessage, trackingLimitMessage ({quest}, {max}), categoryProgressMessage ({completed}, {total}), et les indications sur le lore des catégories et des quêtes.
• Libellés de navigation — navLabels définit le nom de chaque bouton intégré (next, previous, up, down, left, right, back, close, sort). Il n'est utilisé que si l'emplacement étiqueté n'a pas d'objet propre : un emplacement qui porte un objet garde son propre nom et son propre lore.
• Bouton de tri — sortTexts définit le libellé de chaque mode de tri (allLabel, notStartedLabel, activeLabel, completedLabel) et la ligne de lore hint. Un Category Menu qui définit un label ou un lore dans son sortDisplay pour un mode garde le sien.
• Titres de menu — mainMenuTitle et trackedQuestsTitle sont les titres utilisés quand le Category Menu correspondant a un title vide.
• Erreur de commande — unknownCategoryMessage est l'erreur que /tw codex <category> affiche pour une catégorie qui n'existe pas ({category}).
• Repli du menu principal — mainMenuTrigger est déclenché lorsqu'il n'y a pas de Category Menu principal, par exemple un Open GUI de votre cru dont les boutons exécutent codex:open <category>.

Waypoints et barre de localisation

Quest Codex Waypoint est une entrée d'audience : connectez-la à un filtre d'audience pour choisir qui la voit. Son target est une position fixe, un objectif localisable, l'objectif suivi (sélection HIGHEST_PRIORITY, FIRST, CLOSEST, ALL ou ONE_PER_QUEST) ou une entité. Ses layers combinent une couche de texte (placeholders {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} et {eta}), une couche de bloc et une couche de balise. displayMode vaut HUD_LOCKED (par défaut), WORLD_DIRECTIONAL, TARGET_ANCHORED ou ADAPTIVE, et chaque couche peut le surcharger. Tout est envoyé par paquets ; aucune entité n'est enregistrée dans le monde.

Quest Codex Locator Bar affiche les mêmes cibles sous forme de points sur la barre de localisation vanilla, qui nécessite Minecraft 1.21.6 ou ultérieur, et se combine avec un waypoint 3D.

Advancements et BlueMap

• Advancement Definition décrit un advancement. Celui qui n'a pas de parent devient un onglet. Ils sont écrits au démarrage dans un datapack appelé questcodex_advancements dans le dossier du monde, et le serveur recharge ses données lorsque le contenu a changé ; une nouvelle définition nécessite donc un redémarrage. L'advancement n'est obtenu que par l'action Grant Advancement.
• BlueMap Icon place au démarrage un marqueur avec un libellé et une fenêtre contextuelle sur les cartes BlueMap de son monde. Dans description, <objectives> est remplacé par les objectifs de la quête.

Commandes

Toutes les commandes sont des sous-commandes de /typewriter, généralement saisi /tw, et nécessitent typewriter.codex.open.

Commande	Description
/tw codex	Ouvre le menu principal : le Category Menu avec un category vide, sinon l'entrée mainMenuTrigger.
/tw codex tracked	Ouvre le menu des quêtes suivies.
/tw codex <category>	Ouvre une catégorie. L'autocomplétion liste les catégories définies.

Les boutons de menu peuvent aussi exécuter ces commandes internes : codex:open <category>, codex:tracked, codex:quest <quest_id> et codex:nav <action>. Utilisez codex:open et codex:tracked dans les boutons de vos propres menus GUI.

Permissions

Permission	Autorise
typewriter.codex.open	Toutes les commandes /tw codex. L'extension la déclare avec un défaut réservé aux opérateurs et elle apparaît dans votre plugin de permissions : accordez-la aux groupes qui peuvent utiliser /tw codex.

Ouvrir un menu depuis une action de Category Menu ou un bouton de menu ne nécessite aucune permission.

Placeholders

Placeholders PlaceholderAPI, avec l'expansion typewriter. Ils nécessitent un joueur.

Placeholder	Renvoie
%typewriter_total_quests%	Nombre de quêtes dans toutes les catégories.
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started%	Nombre de quêtes dans chaque statut pour le joueur.
%typewriter_total_progress%	Terminées sur le total, par exemple 15/42.
%typewriter_category_<name>%	Nombre de quêtes de la catégorie.
%typewriter_category_<name>_completed%, _in_progress%, _not_started%	Quêtes de la catégorie dans ce statut.
%typewriter_category_<name>_progress%	Terminées sur le total pour la catégorie.
%typewriter_codex_tracked_count%, _limit%	Nombre de quêtes suivies, et le maximum.
%typewriter_codex_tracked_multi_enabled%, _has_any%	true ou false.
%typewriter_codex_tracked_ids%, _names%, _names_lines%	Identifiants ou noms des quêtes suivies, séparés par des virgules ou un par ligne.
%typewriter_codex_tracked_primary_id%, _primary_name%	La quête principale affichée par le suivi officiel.
%typewriter_codex_tracked_has_<quest_id>%	Indique si cette quête est suivie.
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary%	Détails de la n-ième quête suivie, à partir de 1. Vide s'il n'y en a pas.
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority%	Objectifs visibles de la n-ième quête suivie.

<name> est le nom de la catégorie, comparé sans tenir compte de la casse. Plus de détails sur Placeholders, Commandes et Permissions.

Entrées

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

Actions2

• Category MenuCategory Menu Configuration
• Grant AdvancementGrant Advancement

Audiences2

• Quest Codex Locator BarQuest Codex Locator Bar
• Quest Codex WaypointQuest Codex Waypoint

Artefacts2

• Quest Codex Recovery ArtifactQuest Codex Recovery Data
• Quest Codex Tracking ArtifactQuest Codex Tracking Data

Manifestes6

• 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

Dépannage

/tw codex ne fait rien. Il n'y a aucun Category Menu avec un category vide et aucun mainMenuTrigger. La console consigne Main menu could not open avec la cause. Pour une catégorie, créez un Category Menu dont le category est égal au category de la Quest Category.

Un menu s'ouvre sans rien dedans. La console le signale au démarrage : aucun emplacement de l'Open GUI référencé ne porte le marqueur dont le menu a besoin (CATEGORY_SLOT, QUEST_SLOT ou TRACKED_QUEST_SLOT), menu est vide ou n'est pas un Open GUI, le pool de layouts est vide, ou mainLayoutId n'en fait pas partie. Les marqueurs nécessitent buttonPrefix codex_button:.

Les emplacements des lignes du bas sont absents. rows du Category Menu est inférieur à size de l'Open GUI. Définissez les deux avec le même nombre de lignes.

Les quêtes apparaissent côte à côte au lieu d'être séparées par un emplacement vide. gap est un pas : 1 signifie adjacent et 2 laisse un emplacement vide. Les menus écrits avant Quest Codex 0.3.0 utilisaient gap comme un espacement ; doublez donc la valeur. Une collision avec une décoration est signalée par un avertissement Slot overlap.

Plusieurs marqueurs s'empilent sur une même case. Le marqueur a un count mais pas de direction, ou la position tombe en dehors de la grille. Définissez une direction.

Une quête est absente d'une catégorie. La quête est masquée par une option hideWhen... pour son statut actuel, le mode de tri actuel la filtre, ou l'assignation n'a pas pu la résoudre (Quest '...' could not be resolved dans la console).

Une quête suivie disparaît après un redémarrage. trackingArtifact est vide, ou son artifactId a changé. Une quête qui n'est plus active est retirée de la liste des quêtes suivies.

Les waypoints ne s'affichent pas. L'entrée de waypoint doit se trouver dans une audience à laquelle le joueur appartient, la quête doit être suivie, et l'objectif doit être localisable. Une couche de texte avec {icon} reste vide tant que icon n'est pas défini.

Un nouvel advancement est inconnu du serveur. Les définitions sont écrites au démarrage ; redémarrez après en avoir ajouté une. Une définition dont l'icône n'est pas un objet est ignorée avec un avertissement.

Extensions associées

• GUI — layouts, marqueurs, vues et le châssis open_gui utilisés par chaque menu de Quest Codex.
• Shops — utilise le même mécanisme de marqueurs pour les menus de boutique.