Primeros pasos con addons

This page is a translated version of the page Add-on Getting Started and the translation is 100% complete.

Primeros pasos con addons explica lo que necesitas tener listo antes de conectar tu propio mod de Forge con DragonMineZ: las versiones de las herramientas, los mods que debes evitar y las partes de DMZ en las que un addon puede confiar sin riesgo. Léela antes de Crear un addon de DMZ.

Para quién es

Estas páginas son para desarrolladores de addons de Forge que quieren que el jar de su mod reaccione a DMZ: dar TP extra, escuchar cambios de forma, añadir nuevos tipos de objetivos y recompensas de misiones, agregar botones al menú de utilidades, etc. Si solo quieres ajustar números o añadir razas, formas, misiones o deseos, no necesitas nada de esto; consulta Alcance y requisitos.

DMZ no tiene una API de Java para registrar razas, formas, habilidades o técnicas nuevas: las razas y formas nuevas se añaden con archivos de configuración JSON (consulta Razas personalizadas y Formas personalizadas).

Herramientas necesarias

Requisito	Versión	Dónde se declara
Minecraft	`1.20.1`	`gradle.properties`
Forge	`47.4.10` (acepta `[47,)`)	`gradle.properties`, `mods.toml` del addon
ForgeGradle	`6.0.30`	Plugins de `build.gradle.kts`
Java	`17`	Toolchain de `build.gradle.kts`
Mappings	Parchment `2023.09.03-1.20.1`	`gradle.properties`
GeckoLib	`4.8.3+`	`gradle.properties`, `mods.toml` del addon
TerraBlender	`3.0.1.10+`	`gradle.properties`, `mods.toml` del addon
Curios API	`5.14.1+1.20.1` o posterior	`gradle.properties`, `mods.toml` del addon

Usa exactamente estas versiones (o rangos de versiones compatibles) en el build.gradle o build.gradle.kts, el gradle.properties y el mods.toml de tu addon; si no, tendrás errores de carga de clases y de mixins incompatibles en tiempo de ejecución. DMZ está actualmente en la versión 2.2-alpha del mod (gradle.properties).

GeckoLib, TerraBlender y Curios son dependencias obligatorias de DMZ, así que también deben estar en el classpath de ejecución de tu entorno de desarrollo.

Mods incompatibles

DMZ se niega a iniciar (lanza una IllegalStateException durante la carga) cuando alguno de estos mods está instalado, y los declara como incompatible en su mods.toml:

Legendary Tooltips (legendarytooltips)
Epic Fight (epicfight)
Better Combat (bettercombat)

No dependas de ellos, no los incluyas ni los añadas a tus configuraciones de ejecución de desarrollo.

Versiones preliminares

2.2-alpha es una versión preliminar. Las versiones alpha y beta de DMZ solo dejan entrar a un mundo o servidor a los nombres de usuario de la lista blanca. El nombre de usuario de desarrollo predeterminado de ForgeGradle, Dev, está en la lista blanca, así que runClient funciona sin configurar nada: conserva ese nombre de usuario para tus pruebas locales.

Estructura de paquetes

Antes de escribir código de hooks, échale un vistazo a la estructura del código fuente (AI/Context.md en el repositorio de DMZ la documenta en detalle):

com.dragonminez.client: renderizado, GUI y animación; solo cliente.
com.dragonminez.common: configuración, estadísticas, red, misiones y deseos; la parte que más tocan los addons.
com.dragonminez.server: comandos, almacenamiento, generación de mundo y eventos de servidor.
com.dragonminez.mixin: mixins; evita depender de ellos desde un addon.

Los addons deberían engancharse casi exclusivamente a com.dragonminez.common: es la capa compartida y la más estable. Los únicos hooks del lado del cliente pensados para addons son DMZClientEvent y las ranuras del menú de utilidades (consulta Implementación y eventos).

Dos formas de integración

Dependencia obligatoria: tu addon necesita que DMZ esté presente (mandatory=true en mods.toml). Es la opción más simple, pero tu addon no cargará sin DMZ.
Dependencia opcional: tu addon funciona por sí solo y únicamente activa el comportamiento específico de DMZ cuando detecta DMZ. DMZ usa este patrón para sus propias integraciones opcionales (common/compat/WeaponLevelingCompat.java, common/compat/ApotheosisCompat.java): comprueba ModList.get().isLoaded("dragonminez") una sola vez y deja toda clase que importe código de DMZ detrás de esa comprobación. Se recomienda si tu addon aporta algo sin DMZ instalado. Consulta Patrón de dependencia opcional.

En qué puedes confiar

Eventos: las clases anidadas de com.dragonminez.common.events.DMZEvent (servidor y común) y com.dragonminez.client.events.DMZClientEvent (cliente) son la superficie pública de hooks prevista. Consulta Implementación y eventos para ver la lista completa.
Estado del jugador de solo lectura: StatsCapability, StatsProvider y StatsData, para leer la raza, la forma, las estadísticas y los recursos.
Registros de extensión: QuestObjectiveRegistry y QuestRewardRegistry (tipos de contenido de misión personalizados), DMZTextPlaceholders (%placeholders% personalizados en textos de misiones y diálogos) y UtilityMenuScreen.addMenuSlot (botones en el menú de utilidades del cliente).
Registros: MainItems, MainBlocks, MainEntities, MainAttributes, MainEffects, MainEnchants (y las demás clases Main*) en common/init/ exponen referencias RegistryObject y DeferredRegister que puedes importar directamente.

En qué no conviene confiar

Los valores que envía el cliente para cualquier cosa relacionada con el progreso. DMZ tampoco confía en ellos; lee la capability del lado del servidor.
Cambiar campos de StatsData directamente fuera de eventos o comandos. Es preferible reaccionar a los eventos o cancelarlos antes que tocar valores, y usar los comandos existentes de DMZ cuando necesites cambiar algo que pertenece a DMZ.
Registrar paquetes en el canal de red de DMZ. Los ids de paquete de DMZ dependen del orden de registro; usa tu propio canal.
Depender de las clases de com.dragonminez.mixin o de partes internas de DMZ no mencionadas arriba. Pueden cambiar sin aviso entre versiones.

Siguiente paso

Cuando tu entorno de desarrollo compile contra DMZ y veas que lo detecta en tiempo de ejecución, pasa a Implementación y eventos para conectar los hooks reales y luego a Crear un addon de DMZ para la configuración completa de Gradle y mods.toml.