Aller au contenu principal

Codex

Codex de découvertes avec catégories déverrouillables, livres de recettes et fragments à collectionner.

Privéesv0.0.3Quêtes et narration
NécessiteTypeWriter0.9BasicGUIQuestfacultatifQuest Codexfacultatif

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​

Codex est un journal de découvertes. Vous définissez des catégories (un bestiaire, un livre de lore, une liste de lieux) et les objets qu'elles contiennent, et chaque objet ou catégorie se débloque selon des critères TypeWriter : un fact, un statut de quête, une permission, tout ce qu'un critère peut vérifier. Les entrées verrouillées restent visibles avec leur propre lore, pour que les joueurs voient ce qu'il leur reste à découvrir. Vous pouvez aussi ajouter des catégories de recettes, qui affichent une recette d'artisanat vanilla dans une petite vue d'établi lorsque le joueur clique sur une recette.

L'extension contient aussi un système de fragments : des objets à collectionner que les joueurs ramassent, regroupés en ensembles, avec une séquence qui se déclenche une fois assez de fragments réunis. Tout est une entrée TypeWriter, construite dans le panel web, et les menus sont affichés par l'extension GUI.

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

Fonctionnalités​

  • Catégories de découverte — regroupent des objets, avec des sous-catégories imbriquées via parentCategory.
  • Déblocage par critères — les catégories et objets se débloquent selon des critères ; ceux qui sont verrouillés peuvent afficher leur propre objet et lore.
  • Compteurs de complétion — débloqués, verrouillés, total et pourcentage sont disponibles dans les icônes de catégories et sous forme de placeholders.
  • Livres de recettes — affichez les ingrédients et le résultat d'une recette vanilla à partir de son recipeKey.
  • Triggers de déblocage — déclenchez des triggers la première fois qu'une catégorie, un objet ou une recette se débloque pour un joueur, enregistrés pour ne jamais se déclencher deux fois.
  • Quatre dispositions de menu — PAGINATED, SCROLLABLE, FRAME ou SIMPLE pour chaque catégorie.
  • Menu global du codex — une disposition GUI où les icônes de catégories sont placées par des marqueurs, héritant d'un châssis de menu partagé.
  • Fragments à collectionner — ramassez un objet pour collecter un fragment, avec un trigger lorsqu'un groupe est complété.
  • Commande et action d'ouverture — ouvrez une catégorie depuis une commande, un dialogue ou n'importe quel trigger.

Installation​

  1. Installez l'extension GUI (GuiAndDialogs dans la version BTC) et l'extension Basic de TypeWriter. Codex ne se chargera pas sans elles.
  2. Facultatif : installez l'extension Quest et l'extension Quest Codex si vous voulez débloquer des entrées à partir de la progression des quêtes.
  3. Placez le JAR de Codex dans plugins/Typewriter/extensions/ et redémarrez le serveur.
  4. Ajoutez un artefact Codex Unlock si vous utilisez des triggers de déblocage, et un artefact Fragment Storage si vous utilisez des fragments.

Premiers pas​

Construisez une catégorie « Créatures de la forêt » avec deux objets :

  1. Dans le panel web TypeWriter, ouvrez une page manifest et ajoutez une entrée Discovery Codex Category.
  2. Définissez category sur un identifiant unique tel que forest_creatures, un title, rows (par exemple 3) et une icon.
  3. Définissez itemSlotRange sur les emplacements à remplir, par exemple 10-16 (les numéros commencent à 1), et choisissez guiLayout.
  4. Dans items, ajoutez un objet : entryId wolf, un item affiché lorsqu'il est débloqué, un lockedItem affiché avant, et dans criteria le fact qui signifie « le joueur a vu un loup ». Ajoutez unlockedLore et lockedLore.
  5. Ajoutez sur une page static ou sequence une entrée avec une action Open Discovery Codex, définissez definition sur votre catégorie, et déclenchez-la depuis un PNJ, un objet ou une option de dialogue. Vous pouvez aussi utiliser /tw codex open forest_creatures.
  6. Publiez et ouvrez le codex. Les objets dont les critères ne sont pas remplis restent verrouillés.
Objets sans critères

Un objet dont la liste criteria est vide est toujours débloqué. Ajoutez des critères à chaque objet que vous voulez masquer.

Fonctionnement​

Une catégorie affiche soit ses sous-catégories et catégories de recettes (lorsque d'autres catégories la nomment comme parentCategory), soit ses propres objets. Les critères de catégorie et d'objet sont évalués chaque fois que le menu est construit pour le joueur.

Chaque Discovery Codex Category est son propre menu d'inventaire avec rows lignes (de 1 à 6). Les objets vont dans les emplacements de itemSlotRange (par exemple 1-25, comptés à partir de 1), ou à partir de startSlot en remplissant par ligne ou par colonne. Les boutons ont des valeurs par défaut : page précédente à l'emplacement 0, page suivante à l'emplacement 8, infos à l'emplacement 4 et retour à l'emplacement 44. Ils utilisent par défaut des flèches et un livre et peuvent être remplacés avec previousButton, nextButton, infoButton et backButton. Le bouton retour n'apparaît que lorsque la catégorie a été ouverte depuis un parent. Un objet background remplit chaque emplacement libre.

Le champ guiLayout choisit la façon dont les objets sont organisés lorsqu'ils ne tiennent pas sur une seule page : PAGINATED (boutons de page), SCROLLABLE (boutons de défilement), FRAME (un cadre par ligne) ou SIMPLE (tout sur un seul écran).

Le nom et le lore d'une icône de catégorie (iconName, iconLore, lockedIconLore) peuvent utiliser {unlocked}, {locked}, {total} et {percent}, remplacés lorsque l'icône est affichée dans une catégorie parente ou dans le menu global. Les autres champs de lore (objets, boutons d'infos et de navigation) sont affichés tels qu'écrits, même si leur texte d'aide liste des placeholders.

Un objet feuille dont l'entryId correspond à un entryId d'une Recipe Category ouvre la vue de recette lorsqu'on clique dessus. La vue de recette affiche la grille d'artisanat dans craftingGridSlots et le résultat dans resultSlot ; une recette qui n'est pas enregistrée sur le serveur affiche une barrière nommée « Recipe not found ».

L'action Codex Global Menu ouvre un hub construit à partir d'un pool de dispositions GUI. Placez des marqueurs codex_button:CODEX_CATEGORY (avec count, gap et direction pour les répéter) et chaque marqueur est rempli avec une catégorie de premier niveau, triée par order. Une catégorie sans marqueur correspondant n'est pas affichée, et un marqueur sans catégorie reste vide. CODEX_BACK revient en arrière, et CODEX_INFO, CODEX_PAGE_NEXT et CODEX_PAGE_PREV sont de simples objets décoratifs dans cette version.

Les marqueurs CODEX_RECIPE affichent des recettes : le N-ième marqueur, dans l'ordre d'apparition dans la disposition (comme pour CODEX_CATEGORY), affiche l'icône de la N-ième recette. Les recettes de toutes les Recipe Categories sont mises à plat dans une seule liste, les catégories étant triées par order et les recettes dans l'ordre de leur liste. Cliquer sur une recette débloquée ouvre sa vue détaillée. S'il y a plus de recettes que de marqueurs, les recettes en trop ne sont pas affichées ; s'il y a plus de marqueurs que de recettes, les marqueurs en trop restent vides.

Espacement des marqueurs

Dans les marqueurs count, gap est un pas, et non un espacement : 1 place les emplacements côte à côte et 2 laisse un emplacement vide entre eux. Codex utilise la formule GUI partagée. C'est la même règle que celle qui s'applique aux marqueurs de Quest Codex depuis Quest Codex 0.3.0 : une disposition copiée d'un ancien menu Quest Codex peut donc nécessiter de doubler son gap. Voir l'extension GUI pour la référence des dispositions.

Les menus de catégories eux-mêmes peuvent s'ouvrir dans un châssis partagé lorsque baseMenuId est défini (utilisez rows de 3 ou moins pour qu'ils tiennent dans la zone de contenu). L'extension UiCore peut aussi afficher le codex : son écran Codex répartit les catégories de premier niveau en quatre onglets (Bestiaire, Objets, Lieux et Fragments) en cherchant des mots-clés tels que fragment, place, region, item ou recipe dans l'identifiant et le nom de la catégorie, et place tout le reste dans le Bestiaire.

Configuration​

L'extension n'a pas de fichier de configuration. L'état est conservé dans deux artefacts, tous deux enregistrés quelques secondes après un changement et lorsque TypeWriter se décharge :

  • Codex Unlock mémorise quels triggers de déblocage se sont déjà déclenchés pour chaque joueur.
  • Fragment Storage mémorise les fragments que chaque joueur a collectés, par groupe.

Commandes​

CommandeDescription
/tw codex open <category> [targets]Ouvre la catégorie ayant cet identifiant category pour vous ou pour les joueurs sélectionnés. Alias : /tw dcx open.

La commande n'a pas de vérification de permission propre au-delà de l'accès à la commande TypeWriter. Une catégorie dont les critères ne sont pas remplis répond « This codex is locked » et un identifiant inconnu répond « Unknown category ».

L'extension enregistre aussi une commande interne /codexmenu utilisée par les clics de menu (category, recipecat, recipe). Elle ne fonctionne que pour les joueurs et n'est pas destinée à être saisie à la main.

Placeholders​

Ce sont des balises MiniPlaceholders de l'extension discoverycodex, disponibles dans tout texte MiniMessage qui prend en charge les placeholders. Remplacez cat par l'identifiant category et item par l'entryId de l'objet. Les identifiants peuvent contenir des tirets bas.

PlaceholderRenvoie
<discoverycodex_category_unlocked:cat>Nombre d'objets débloqués dans la catégorie pour le joueur.
<discoverycodex_category_total:cat>Nombre d'objets dans la catégorie.
<discoverycodex_category_locked:cat>Nombre d'objets verrouillés pour le joueur.
<discoverycodex_category_percent:cat>Pourcentage d'objets débloqués, de 0 à 100.
<discoverycodex_category_name:cat>Le nom de l'entrée de catégorie.
<discoverycodex_item_unlocked:item>true ou false pour cet objet.

Entrées​

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

Actions2
Artefacts2
Manifestes6

Dépannage​

L'extension ne se charge pas. Codex nécessite les extensions Basic et GUI (GuiAndDialogs). Consultez le journal de démarrage de TypeWriter pour repérer la dépendance manquante.

Les triggers de déblocage ne se déclenchent jamais. Le journal indique « No CodexUnlockArtifactEntry configured: skipping unlock triggers ». Ajoutez un artefact Codex Unlock à une page publiée. Sans lui, les triggers sont volontairement ignorés, afin que les récompenses ne soient pas redonnées à chaque redémarrage.

Les triggers de déblocage se sont déclenchés une fois et plus jamais. C'est voulu : chaque trigger ne se déclenche qu'une fois par joueur, et l'enregistrement est stocké dans l'artefact. Pour tester à nouveau, utilisez un nouveau joueur ou supprimez ses données de l'artefact.

Les objets atterrissent dans les mauvais emplacements ou le dernier emplacement est vide. itemSlotRange compte à partir de 1 (1-25 signifie les emplacements 0 à 24 de l'inventaire). Les emplacements en dehors de la taille du menu sont ignorés, et les objets au-delà du nombre d'emplacements passent à la page suivante.

Une recette affiche « Recipe not found ». recipeKey doit être la clé avec namespace d'une recette enregistrée sur le serveur, comme minecraft:iron_pickaxe. Les recettes ajoutées par d'autres plugins utilisent leur propre namespace.

Un fragment n'est pas collecté. Le joueur doit ramasser l'objet : il doit correspondre à customItem (ou à displayItem lorsque customItem est vide), et le journal ne doit pas indiquer « No FragmentArtifactEntry found ». Ajoutez un artefact Fragment Storage. Un fragment déjà collecté n'est pas consommé à nouveau.

Le groupe ne se complète jamais. requiredCount vaut 0 par défaut, ce qui signifie tous les fragments listés dans fragments ; un nombre supérieur à la longueur de la liste est plafonné à cette longueur. Le groupId du groupe doit être le même texte que le fragmentGroup de ses fragments.

Les marqueurs d'un menu global sont espacés d'un emplacement. gap est un pas : utilisez donc gap 2 pour laisser un emplacement vide entre les marqueurs.

Extensions associées​

  • GUI — moteur de menus, dispositions et marqueurs.
  • Quest Codex — menus de quêtes ; Codex en est un complément facultatif.
  • UiCore — peut afficher le codex dans sa propre interface.