Saltar al contenido principal

Codex

Códice de descubrimientos con categorías desbloqueables, libros de recetas y fragmentos coleccionables.

Privadasv0.0.3Misiones y narrativa
RequiereTypeWriter0.9BasicGUIQuestopcionalQuest Codexopcional

Creada para la red BornToCraft. Esta extensión está documentada como referencia y no se distribuye.

Soporte

Descripción general​

Codex es un registro de descubrimientos. Defines categorías (un bestiario, un libro de lore, una lista de lugares) y los items que contienen, y cada item o categoría se desbloquea con criterios de TypeWriter: un fact, el estado de una misión, un permiso, cualquier cosa que un criterio pueda comprobar. Las entradas bloqueadas siguen siendo visibles con su propio lore, de modo que los jugadores ven lo que les queda por descubrir. También puedes añadir categorías de recetas, que muestran una receta de crafteo de vanilla en una pequeña vista de mesa de crafteo cuando el jugador hace clic en una receta.

La extensión contiene además un sistema de fragmentos: objetos coleccionables que los jugadores recogen, agrupados en conjuntos, con una secuencia que se activa cuando se reúnen suficientes fragmentos. Todo es una entrada de TypeWriter, construida en el panel web, y los menús los renderiza la extensión GUI.

La extensión funciona en la compilación BTC de TypeWriter (BTC Core, Paper/Folia) y se documenta aquí como referencia.

Características​

  • Categorías de descubrimiento — agrupa items, con subcategorías anidadas mediante parentCategory.
  • Desbloqueo basado en criterios — las categorías y los items se desbloquean a partir de criterios; los bloqueados pueden mostrar su propio item y lore.
  • Contadores de finalización — desbloqueados, bloqueados, total y porcentaje están disponibles en los iconos de categoría y como placeholders.
  • Libros de recetas — muestra los ingredientes y el resultado de una receta de vanilla a partir de su recipeKey.
  • Triggers de desbloqueo — activa triggers la primera vez que una categoría, un item o una receta se desbloquea para un jugador, guardado para que nunca se activen dos veces.
  • Cuatro layouts de menú — PAGINATED, SCROLLABLE, FRAME o SIMPLE para cada categoría.
  • Menú global del códice — un layout de GUI donde los iconos de categoría se colocan mediante marcadores, heredando un chasis de menú compartido.
  • Fragmentos coleccionables — recoge un objeto para obtener un fragmento, con un trigger cuando se completa un grupo.
  • Comando y acción de apertura — abre una categoría desde un comando, un diálogo o cualquier trigger.

Instalación​

  1. Instala la extensión GUI (GuiAndDialogs en la compilación BTC) y la extensión Basic de TypeWriter. Codex no se cargará sin ellas.
  2. Opcionalmente, instala la extensión Quest y la extensión Quest Codex si quieres desbloquear entradas a partir del progreso de misiones.
  3. Coloca el JAR de Codex en plugins/Typewriter/extensions/ y reinicia el servidor.
  4. Añade un artefacto Codex Unlock si usas triggers de desbloqueo, y un artefacto Fragment Storage si usas fragmentos.

Primeros pasos​

Crea una categoría "Criaturas del bosque" con dos items:

  1. En el panel web de TypeWriter, abre una página de manifest y añade una entrada Discovery Codex Category.
  2. Establece category con un identificador único como forest_creatures, un title, rows (por ejemplo 3) y un icon.
  3. Establece itemSlotRange con las ranuras que se rellenarán, por ejemplo 10-16 (los números empiezan en 1), y elige guiLayout.
  4. En items, añade un item: entryId wolf, un item que se muestra cuando está desbloqueado, un lockedItem que se muestra antes y, en criteria, el fact que significa "el jugador ha visto un lobo". Añade unlockedLore y lockedLore.
  5. Añade a una página static o sequence una acción Open Discovery Codex, establece definition con tu categoría y actívala desde un NPC, un objeto o una opción de diálogo. También puedes usar /tw codex open forest_creatures.
  6. Publica y abre el códice. Los items cuyos criterios no se cumplen siguen bloqueados.
Items sin criterios

Un item con una lista criteria vacía siempre está desbloqueado. Añade criterios a cada item que quieras ocultar.

Cómo funciona​

Una categoría muestra sus subcategorías y categorías de recetas (cuando otras categorías la nombran como parentCategory) o sus propios items. Los criterios de categoría y de item se evalúan cada vez que se construye el menú para el jugador.

Menús​

Cada Discovery Codex Category es su propio menú de inventario con rows filas (de 1 a 6). Los items van en las ranuras de itemSlotRange (por ejemplo 1-25, contadas desde 1), o desde startSlot rellenando por filas o por columnas. Los botones tienen valores por defecto: página anterior en la ranura 0, página siguiente en la ranura 8, información en la ranura 4 y volver en la ranura 44. Usan flechas y un libro por defecto y se pueden sustituir con previousButton, nextButton, infoButton y backButton. El botón de volver solo aparece cuando la categoría se abrió desde un padre. Un item background rellena todas las ranuras libres.

El campo guiLayout elige cómo se organizan los items cuando no caben en una página: PAGINATED (botones de página), SCROLLABLE (botones de desplazamiento), FRAME (un marco por fila) o SIMPLE (todo en una pantalla).

El nombre y el lore de un icono de categoría (iconName, iconLore, lockedIconLore) pueden usar {unlocked}, {locked}, {total} y {percent}, que se sustituyen cuando el icono se muestra en una categoría padre o en el menú global. Los demás campos de lore (items, información y botones de navegación) se muestran tal como están escritos, aunque su texto de ayuda liste placeholders.

Un item hoja cuyo entryId coincide con un entryId de una Recipe Category abre la vista de la receta al hacer clic. La vista de la receta muestra la cuadrícula de crafteo en craftingGridSlots y el resultado en resultSlot; una receta que no está registrada en el servidor muestra un item de barrera llamado "Recipe not found".

La acción Codex Global Menu abre un centro construido a partir de un conjunto de layouts de GUI. Coloca marcadores codex_button:CODEX_CATEGORY (con count, gap y direction para repetirlos) y cada marcador se rellena con una categoría de nivel superior, ordenadas por order. Una categoría sin un marcador correspondiente no se muestra, y un marcador sin categoría queda vacío. CODEX_BACK vuelve atrás, y CODEX_INFO, CODEX_PAGE_NEXT y CODEX_PAGE_PREV son items puramente decorativos en esta versión.

Los marcadores CODEX_RECIPE muestran recetas: el N-ésimo marcador, en el orden de aparición en el layout (como con CODEX_CATEGORY), muestra el icono de la N-ésima receta. Las recetas de todas las Recipe Categories se ponen en una lista plana, con las categorías ordenadas por order y las recetas en el orden de su lista. Hacer clic en una receta desbloqueada abre su vista de detalle. Si hay más recetas que marcadores, las recetas sobrantes no se muestran; si hay más marcadores que recetas, los marcadores sobrantes quedan vacíos.

Espaciado de marcadores

En los marcadores count, gap es un paso, no un espaciado: 1 coloca las ranuras una al lado de otra y 2 deja una ranura vacía entre ellas. Codex usa la fórmula compartida de GUI. Es la misma regla que se aplica a los marcadores de Quest Codex desde Quest Codex 0.3.0, así que un layout copiado de un menú antiguo de Quest Codex puede necesitar que se duplique su gap. Consulta la extensión GUI para la referencia de layouts.

Los propios menús de categoría pueden abrirse dentro de un chasis compartido cuando se establece baseMenuId (usa rows de 3 o menos para que quepan en el área de contenido). La extensión UiCore también puede mostrar el códice: su pantalla Codex ordena las categorías de nivel superior en cuatro pestañas (Bestiario, Objetos, Lugares y Fragmentos) buscando palabras clave como fragment, place, region, item o recipe en el identificador y el nombre de la categoría, y pone todo lo demás en el Bestiario.

Configuración​

La extensión no tiene archivo de configuración. El estado se guarda en dos artefactos, ambos guardados unos segundos después de un cambio y cuando TypeWriter se descarga:

  • Codex Unlock recuerda qué triggers de desbloqueo ya se han activado para cada jugador.
  • Fragment Storage recuerda los fragmentos que ha recogido cada jugador, por grupo.

Comandos​

ComandoDescripción
/tw codex open <category> [targets]Abre la categoría con ese identificador category para ti o para los jugadores seleccionados. Alias: /tw dcx open.

El comando no tiene comprobación de permisos propia más allá del acceso al comando de TypeWriter. Una categoría cuyos criterios no se cumplen responde "This codex is locked" y un identificador desconocido responde "Unknown category".

La extensión registra también un comando interno /codexmenu usado por los clics del menú (category, recipecat, recipe). Solo funciona para jugadores y no está pensado para escribirse a mano.

Placeholders​

Son etiquetas de MiniPlaceholders de la expansión discoverycodex, disponibles en cualquier texto MiniMessage que admita placeholders. Sustituye cat por el identificador category e item por el entryId del item. Los identificadores pueden contener guiones bajos.

PlaceholderDevuelve
<discoverycodex_category_unlocked:cat>Número de items desbloqueados de la categoría para el jugador.
<discoverycodex_category_total:cat>Número de items de la categoría.
<discoverycodex_category_locked:cat>Número de items bloqueados para el jugador.
<discoverycodex_category_percent:cat>Porcentaje de items desbloqueados, de 0 a 100.
<discoverycodex_category_name:cat>El nombre de la entrada de categoría.
<discoverycodex_item_unlocked:item>true o false para ese item.

Entradas​

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

Acciones2
Artefactos2
Manifiestos6

Solución de problemas​

La extensión no se carga. Codex requiere las extensiones Basic y GUI (GuiAndDialogs). Revisa el registro de inicio de TypeWriter para ver la dependencia que falta.

Los triggers de desbloqueo nunca se activan. El registro dice "No CodexUnlockArtifactEntry configured: skipping unlock triggers". Añade un artefacto Codex Unlock a una página publicada. Sin él, los triggers se omiten a propósito, para que las recompensas no se vuelvan a dar tras cada reinicio.

Los triggers de desbloqueo se activaron una vez y nunca más. Es lo previsto: cada trigger se activa una vez por jugador, y el registro se guarda en el artefacto. Para probar de nuevo, usa un jugador nuevo o elimina sus datos del artefacto.

Los items caen en ranuras equivocadas o la última ranura está vacía. itemSlotRange cuenta desde 1 (1-25 significa las ranuras 0 a 24 del inventario). Las ranuras fuera del tamaño del menú se ignoran, y los items que exceden el número de ranuras pasan a la página siguiente.

Una receta muestra "Recipe not found". recipeKey debe ser la clave con namespace de una receta registrada en el servidor, como minecraft:iron_pickaxe. Las recetas añadidas por otros plugins usan su propio namespace.

Un fragmento no se recoge. El jugador debe recoger el objeto: debe coincidir con customItem (o displayItem cuando customItem está vacío), y el registro no debe decir "No FragmentArtifactEntry found". Añade un artefacto Fragment Storage. Un fragmento ya recogido no se consume de nuevo.

El grupo nunca se completa. requiredCount es 0 por defecto, lo que significa todos los fragmentos listados en fragments; un número superior a la longitud de la lista se limita a la longitud de la lista. El groupId del grupo debe ser el mismo texto que el fragmentGroup de sus fragmentos.

Los marcadores de un menú global están separados por una ranura. gap es un paso, así que usa gap 2 para dejar una ranura vacía entre marcadores.

Extensiones relacionadas​

  • GUI — motor de menús, layouts y marcadores.
  • Quest Codex — menús de misiones; Codex es un complemento opcional.
  • UiCore — puede renderizar el códice en su propia interfaz.