Quest Codex

Menús de registro de misiones con categorías, seguimiento múltiple, puntos de ruta GPS, logros e iconos de BlueMap.

Gratuitasv2.16Misiones y narrativa

RequiereTypeWriter0.9QuestGUI0.18+BlueMapopcional

DescargarCódigo fuenteSoporte

Descripción general

Quest Codex da a los jugadores un libro de misiones. Un menú principal enumera las categorías (Historia principal, Misiones secundarias, Mazmorras...), cada categoría abre una lista de sus misiones y, al hacer clic en una misión activa, se empieza a seguirla. Las misiones son las que creas con la extensión oficial Quest de TypeWriter: Quest Codex solo las organiza y las muestra.

Tú diseñas cada pantalla. Un menú es un layout de la extensión GUI en el que colocas objetos marcador: un marcador QUEST_SLOT se sustituye por las misiones del jugador, un marcador CATEGORY_SLOT por las categorías y un marcador SORT_SLOT por el botón de ordenación. Todo lo que rodea a los marcadores (bordes, títulos, botones, desplazamiento, páginas) es contenido normal de GUI.

Además del menú, la extensión añade seguimiento de varias misiones que sobrevive a las reconexiones, recuperación de un diálogo o una cinemática interrumpidos, waypoints GPS y puntos de la barra de localización en el cliente, logros personalizados de Minecraft concedidos desde una página e iconos de misiones en BlueMap.

Características

• Categorías: categorías anidadas con orden, icono, visibilidad y criterios de finalización, y mensajes por estado.
• Asignación de misiones: coloca misiones en una categoría, define su orden y sobrescribe el icono, el nombre, el lore y la visibilidad por estado.
• Conjuntos de layouts: diseñas cada menú con layouts de GUI; el codex rellena los marcadores QUEST_SLOT, CATEGORY_SLOT, TRACKED_QUEST_SLOT y SORT_SLOT.
• Botón de ordenación: alterna entre Todas, Sin empezar, En curso y Completadas, con una etiqueta, un icono y un lore por modo.
• Seguimiento múltiple: sigue varias misiones activas a la vez; la última es la misión principal del rastreador HUD oficial.
• Menú de misiones seguidas: un menú dedicado a las misiones que sigue el jugador.
• Waypoints: capas de texto, bloque y baliza solo por paquetes que apuntan a un objetivo, una posición o una entidad, además de una variante de barra de localización vanilla.
• Recuperación de interacciones: restaura el diálogo o la cinemática activos tras una desconexión.
• Logros (advancements): define pestañas de logros de Minecraft en el panel y concédelos con una acción.
• Iconos de BlueMap: coloca un icono de misión con una ventana emergente en BlueMap.

Instalación

1. Instala TypeWriter en un servidor Paper o Folia, con su extensión oficial Quest, que define las misiones que muestra Quest Codex.
2. Instala la extensión GUI (versión 0.18 o posterior).
3. Opcional: instala PacketEvents (que TypeWriter ya requiere) para los waypoints y BlueMap para los iconos del mapa.
4. Descarga el JAR de Quest Codex desde las releases de GitHub (el botón del panel de resumen de arriba), colócalo en plugins/Typewriter/extensions/ y reinicia el servidor.
5. Da a tus jugadores el permiso typewriter.codex.open; consulta Permisos más abajo.

Primeros pasos

Construye un diario de misiones con una categoría:

1. En una página estática, añade una entrada Quest Codex Tracking Data. Aquí se guardan las misiones seguidas.
2. En una página de manifiesto, añade una entrada Quest Codex Global Settings. Establece trackingArtifact en el artefacto y revisa maxTrackedQuests y los sonidos.
3. Añade una entrada Quest Category con category main_quests, un title como <gold>Main Story y un icon.
4. Añade una entrada Quest Assignment con category main_quests y tus misiones en questRefs. orders es opcional.
5. Crea dos entradas Open GUI que se usarán solo como contenedores de layouts. En la primera, main_gui, añade un layout simple con el id main, establece mainLayoutId en main, guiType en CUSTOM y size en SIZE_36. Añade un objeto con buttonPrefix codex_button:, buttonType CATEGORY_SLOT, x 1, y 1, count 7 y direction right. En la segunda, quests_gui, haz lo mismo con el marcador QUEST_SLOT y añade un objeto CLOSE en la fila inferior.
6. Añade un Category Menu con category vacío, rows 4 y menu establecido en main_gui. Este es el menú principal.
7. Añade un segundo Category Menu con category main_quests, rows 4 y menu establecido en quests_gui.
8. Publica y ejecuta /tw codex en el juego. Haz clic en la categoría y luego en una misión activa para seguirla.

Mantén iguales rows y size

El inventario se construye a partir de rows del Category Menu y no del size de la entrada Open GUI. Si difieren, se descartan las ranuras por debajo de la altura menor y la consola te avisa al arrancar.

Marcadores

Una ranura marcador muestra una misión. Usa count, direction, gap y repeatY para extender un marcador sobre una cuadrícula: count 7, direction right y repeatY 3 dan 21 ranuras de misión. Sin direction, el marcador sigue siendo una sola ranura. Las misiones rellenan los marcadores en orden de lectura y se llega a la siguiente página de misiones con un botón PAGE_NEXT.

Cómo funciona

Al arrancar, la extensión carga las categorías, las asignaciones y los menús. Cuando un jugador abre un menú, reescribe cada marcador del layout como un marcador indexado (QUEST_SLOT#0, QUEST_SLOT#1, ...) antes de analizar el layout, de modo que los marcadores se comportan como ranuras normales dentro de los layouts scrollable, paginated y frame. Al renderizar, cada marcador se sustituye por la n-ésima misión o categoría.

Menús

Qué entradas forman un menú

Un Category Menu es la entrada que abres. Su campo menu apunta a una entrada Open GUI que solo aporta el conjunto de layouts, el layout principal, el tipo de ventana y los sonidos. No actives esa entrada Open GUI por tu cuenta.

category del Category Menu	Menú	Marcador que debe contener
vacío	Menú principal que enumera las categorías raíz	CATEGORY_SLOT
el nombre de una categoría	Misiones de esa categoría	QUEST_SLOT
@tracked	Misiones que sigue el jugador	TRACKED_QUEST_SLOT

Cada categoría definida necesita un Category Menu; de lo contrario, abrirla no hace nada y la consola lo indica al arrancar.

Marcadores y botones

Establece buttonPrefix en codex_button: y buttonType en uno de estos valores:

buttonType	Función
CATEGORY_SLOT	El icono de una categoría, con su título, el progreso {completed}/{total}, la indicación de clic y el mensaje de estado. Al hacer clic se abre la categoría.
QUEST_SLOT	Una misión. El icono sigue su estado; el nombre y el lore proceden de la misión, la asignación y las entradas Quest Lore. Al hacer clic en una misión activa se empieza o se deja de seguirla.
TRACKED_QUEST_SLOT	Una misión seguida en el menú @tracked. Una ranura vacía conserva tu propio objeto y permanece inerte, por lo que es tu estado vacío.
SORT_SLOT	El botón de ordenación. Configura cada modo en sortDisplay del Category Menu.
PAGE_NEXT, PAGE_PREV	Pasan a la página siguiente o anterior de misiones o categorías.
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHT	Desplazan el menú.
BACK	Vuelve al menú principal si existe; si no, a la entrada mainMenuTrigger; si no, al menú anterior; si no, cierra.
CLOSE	Cierra el menú.
SORT	Un botón de ordenación colocado como una ranura de navegación normal.

Los botones de navegación conservan el objeto, el nombre y el lore que configures; la flecha, la barrera o la tolva integradas solo se usan cuando la ranura no tiene objeto.

Coloca los marcadores en layouts simple que pertenezcan a la entrada Open GUI referenciada por menu. Los marcadores en otros tipos de layout, o en los layouts de un chasis compartido, no se indexan y permanecen ocultos.

Chasis, vistas y pestañas

Para construir un libro de misiones con pestañas, establece baseMenuId en el Category Menu con una entrada Open GUI base compartida y añade views, defaultViewId y breadcrumbSeparator, exactamente como en Vistas, pestañas y herencia. pushHistoryOnViewSwitch hace que Volver regrese a la pestaña anterior. Un chasis cuyo layout raíz tenga una variante _extended obtiene automáticamente el lienzo de diez filas.

Visualización de las misiones

• El icono de una misión es por defecto un libro, un reloj o una esmeralda para sin empezar, en curso y completada. Sobrescríbelo por estado en la Quest Assignment (notStartedItem, inProgressItem, completedItem).
• notStartedName, inProgressName y completedName sustituyen el nombre de la misión, y los campos de lore correspondientes añaden líneas. Oculta una misión por estado con hideWhenNotStarted, hideWhenInProgress y hideWhenCompleted.
• Una entrada Quest Lore añade líneas por estado a una misión, en una categoría o en todas.
• El orden de las misiones sigue primero orders y después el orden de questRefs. Una categoría también enumera las misiones de sus subcategorías.
• El menú principal solo enumera las categorías de nivel superior (las que no tienen parent). Una subcategoría se abre con /tw codex <category> o con un botón que ejecute codex:open <category>.

Configuración

La entrada Quest Codex Global Settings contiene las opciones que no están ligadas a un menú. Crea solo una; sin ella se usan los valores por defecto.

• Sonidos: soundOnOpen, soundOnSwitch, soundOnClick, soundOnTrack, soundOnUntrack.
• Seguimiento: multiTrackingEnabled, maxTrackedQuests (al menos 1) y trackingArtifact. Sin un artefacto, las misiones seguidas se conservan solo en memoria y la consola avisa al arrancar. El artefacto es un archivo que debe conservar su artifactId una vez que los jugadores lo usan.
• Recuperación: recoveryEnabled, recoveryArtifact, recoveryRetentionSeconds (10 a 86400) y recoveryRestoreDelayTicks (1 a 20). Cuando un jugador se va durante un diálogo o una cinemática, la instantánea se almacena y se restaura poco después de que el jugador vuelva a entrar. Sin un artefacto, la recuperación está desactivada.
• Mensajes: nowTrackingMessage, stoppedTrackingMessage, questInactiveMessage, questCompletedMessage, trackingLimitMessage ({quest}, {max}), categoryProgressMessage ({completed}, {total}) y las indicaciones sobre el lore de categorías y misiones.
• Etiquetas de navegación — navLabels define el nombre de cada botón integrado (next, previous, up, down, left, right, back, close, sort). Solo se usa cuando el slot etiquetado no tiene un objeto propio: un slot que lleva un objeto conserva su propio nombre y lore.
• Botón de orden — sortTexts define la etiqueta de cada modo de orden (allLabel, notStartedLabel, activeLabel, completedLabel) y la línea de lore hint. Un Category Menu que define un label o un lore en su sortDisplay para un modo conserva el suyo.
• Títulos de menú — mainMenuTitle y trackedQuestsTitle son los títulos que se usan cuando el Category Menu correspondiente tiene un title vacío.
• Error de comando — unknownCategoryMessage es el error que muestra /tw codex <category> para una categoría que no existe ({category}).
• Alternativa del menú principal: mainMenuTrigger se activa cuando no hay un Category Menu principal, por ejemplo una entrada Open GUI propia cuyos botones ejecutan codex:open <category>.

Waypoints y barra de localización

Quest Codex Waypoint es una entrada de audiencia: conéctala a un filtro de audiencia para elegir quién la ve. Su target es una posición fija, un objetivo localizable, el objetivo seguido (selección HIGHEST_PRIORITY, FIRST, CLOSEST, ALL o ONE_PER_QUEST) o una entidad. Sus layers combinan una capa de texto (placeholders {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} y {eta}), una capa de bloque y una capa de baliza. displayMode es HUD_LOCKED (por defecto), WORLD_DIRECTIONAL, TARGET_ANCHORED o ADAPTIVE, y cada capa puede sobrescribirlo. Todo se envía mediante paquetes; no se guarda ninguna entidad en el mundo.

Quest Codex Locator Bar muestra los mismos destinos como puntos en la barra de localización vanilla, que requiere Minecraft 1.21.6 o posterior, y se combina con un waypoint 3D.

Logros y BlueMap

• Advancement Definition describe un logro. Uno sin parent se convierte en una pestaña. Se escriben al arrancar en un datapack llamado questcodex_advancements en la carpeta del mundo, y el servidor recarga sus datos cuando el contenido ha cambiado, por lo que una definición nueva requiere un reinicio. El logro solo se obtiene con la acción Grant Advancement.
• BlueMap Icon coloca al arrancar un marcador con una etiqueta y una ventana emergente en los mapas de BlueMap de su mundo. En description, <objectives> se sustituye por los objetivos de la misión.

Comandos

Todos los comandos son subcomandos de /typewriter, que normalmente se escribe como /tw, y requieren typewriter.codex.open.

Comando	Descripción
/tw codex	Abre el menú principal: el Category Menu con category vacío o, si no existe, la entrada mainMenuTrigger.
/tw codex tracked	Abre el menú de misiones seguidas.
/tw codex <category>	Abre una categoría. El autocompletado con tabulador enumera las categorías definidas.

Los botones de los menús también pueden ejecutar estos comandos internos: codex:open <category>, codex:tracked, codex:quest <quest_id> y codex:nav <action>. Usa codex:open y codex:tracked en los botones de tus propios menús de GUI.

Permisos

Permiso	Concede
typewriter.codex.open	Todos los comandos /tw codex. La extensión lo declara con un valor por defecto solo para operadores y aparece en tu plugin de permisos: concédelo a los grupos que puedan usar /tw codex.

Abrir un menú desde una acción Category Menu o desde un botón de menú no necesita ningún permiso.

Placeholders

Placeholders de PlaceholderAPI, con la expansión typewriter. Necesitan un jugador.

Placeholder	Devuelve
%typewriter_total_quests%	Número de misiones en todas las categorías.
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started%	Número de misiones en cada estado para el jugador.
%typewriter_total_progress%	Completadas sobre el total, por ejemplo 15/42.
%typewriter_category_<name>%	Número de misiones de la categoría.
%typewriter_category_<name>_completed%, _in_progress%, _not_started%	Misiones de la categoría en ese estado.
%typewriter_category_<name>_progress%	Completadas sobre el total de la categoría.
%typewriter_codex_tracked_count%, _limit%	Número de misiones seguidas y el máximo.
%typewriter_codex_tracked_multi_enabled%, _has_any%	true o false.
%typewriter_codex_tracked_ids%, _names%, _names_lines%	Ids o nombres de las misiones seguidas, separados por comas o uno por línea.
%typewriter_codex_tracked_primary_id%, _primary_name%	La misión principal que muestra el rastreador oficial.
%typewriter_codex_tracked_has_<quest_id>%	Si esa misión se está siguiendo.
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary%	Detalles de la n-ésima misión seguida, empezando en 1. Vacío cuando no existe.
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority%	Objetivos visibles de la n-ésima misión seguida.

<name> es el nombre de la categoría, comparado sin distinguir mayúsculas de minúsculas. Más detalles en Placeholders, Comandos y Permisos.

Entradas

12 entradas, generadas a partir del código fuente de la extensión.

Acciones2

• Category MenuCategory Menu Configuration
• Grant AdvancementGrant Advancement

Audiencias2

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

Artefactos2

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

Manifiestos6

• 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

Resolución de problemas

/tw codex no hace nada. No hay ningún Category Menu con category vacío ni mainMenuTrigger. La consola registra Main menu could not open con la causa. Para una categoría, crea un Category Menu cuyo category sea igual al category de la Quest Category.

Un menú se abre vacío. La consola lo indica al arrancar: ninguna ranura de la entrada Open GUI referenciada lleva el marcador que necesita el menú (CATEGORY_SLOT, QUEST_SLOT o TRACKED_QUEST_SLOT), menu está vacío o no es una entrada Open GUI, el conjunto de layouts está vacío, o mainLayoutId no está en él. Los marcadores necesitan buttonPrefix codex_button:.

Faltan ranuras en las filas inferiores. El rows del Category Menu es menor que el size de la entrada Open GUI. Establece ambos en el mismo número de filas.

Las misiones aparecen separadas por una ranura en lugar de dejar una ranura vacía entre ellas. gap es un paso: 1 es adyacente y 2 deja una ranura vacía. Los menús escritos antes de Quest Codex 0.3.0 usaban gap como una separación, así que duplica el valor. Una colisión con una decoración se informa como una advertencia Slot overlap.

Varios marcadores se apilan en una celda. El marcador tiene count pero no direction, o la posición queda fuera de la cuadrícula. Establece una direction.

Falta una misión en una categoría. La misión está oculta por una opción hideWhen... para su estado actual, el modo de ordenación actual la filtra, o la asignación no pudo resolverla (Quest '...' could not be resolved en la consola).

Una misión seguida desaparece tras un reinicio. trackingArtifact está vacío o su artifactId ha cambiado. Una misión que ya no está activa se elimina de la lista de seguidas.

Los waypoints no se muestran. La entrada de waypoint debe estar dentro de una audiencia que el jugador cumpla, la misión debe estar seguida y el objetivo debe ser localizable. Una capa de texto con {icon} permanece vacía hasta que se establece icon.

El servidor no conoce un logro nuevo. Las definiciones se escriben al arrancar; reinicia tras añadir una. Una definición cuyo icono no es un objeto se omite con una advertencia.

Extensiones relacionadas

• GUI: layouts, marcadores, vistas y el chasis open_gui que usan todos los menús de Quest Codex.
• Shops: usa el mismo mecanismo de marcadores para los menús de tienda.