Primeros pasos con addons

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`	`build.gradle.kts` plugins
Java	`17`	`build.gradle.kts` toolchain
Mappings	Parchment `2023.09.03-1.20.1`	`gradle.properties`
GeckoLib	`4.8.3+`	`gradle.properties`, add-on `mods.toml`
TerraBlender	`3.0.1.10+`	`gradle.properties`, add-on `mods.toml`
Curios API	`5.14.1+1.20.1` or newer	`gradle.properties`, add-on `mods.toml`

Match these exactly (or with compatible version ranges) in your own add-on's build.gradle or build.gradle.kts, gradle.properties and mods.toml, or you will hit classloading and mixin mismatches at runtime. DMZ itself is currently on mod version 2.2-alpha (gradle.properties).

GeckoLib, TerraBlender and Curios are mandatory dependencies of DMZ, so they must be on your development runtime classpath too.

Incompatible mods

DMZ refuses to start (it throws an IllegalStateException while loading) when any of these mods is installed, and declares them incompatible in its mods.toml:

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

Don't depend on them, bundle them or add them to your development run configurations.

Pre-release builds

2.2-alpha is a pre-release build. Alpha and beta builds of DMZ only let whitelisted usernames join a world or server. The default ForgeGradle development username Dev is on the whitelist, so runClient works out of the box: keep that username for local testing.

Package layout

Before writing any hook code, skim the source layout (AI/Context.md in the DMZ repository documents it in detail):

com.dragonminez.client: rendering, GUI and animation; client only.
com.dragonminez.common: config, stats, networking, quests and wishes; the surface most add-ons touch.
com.dragonminez.server: commands, storage, world generation and server events.
com.dragonminez.mixin: mixins; avoid depending on these from an add-on.

Add-ons should hook com.dragonminez.common almost exclusively: it is the shared, most stable layer. The only client-side hooks meant for add-ons are DMZClientEvent and the utility menu slots (see Implementation and Events).

Two integration styles

Hard dependency: your add-on requires DMZ to be present (mandatory=true in mods.toml). This is the simplest option, but your add-on won't load without DMZ.
Soft (optional) dependency: your add-on works on its own and only turns on DMZ-specific behavior when DMZ is detected. DMZ uses this pattern itself for its optional integrations (common/compat/WeaponLevelingCompat.java, common/compat/ApotheosisCompat.java): check ModList.get().isLoaded("dragonminez") once, and keep every class that imports DMZ code behind that check. This is recommended if your add-on has value without DMZ installed. See Optional dependency pattern.

What you can safely rely on

Events: the nested classes of com.dragonminez.common.events.DMZEvent (server and common) and com.dragonminez.client.events.DMZClientEvent (client) are the intended public hook surface. See Implementation and Events for the full list.
Read-only player state: StatsCapability, StatsProvider and StatsData, for reading race, form, stats and resources.
Extension registries: QuestObjectiveRegistry and QuestRewardRegistry (custom quest content types), DMZTextPlaceholders (custom %placeholders% in quest and dialogue text) and UtilityMenuScreen.addMenuSlot (buttons in the client utility menu).
Registries: MainItems, MainBlocks, MainEntities, MainAttributes, MainEffects, MainEnchants (and the other Main* classes) under common/init/ expose RegistryObject and DeferredRegister references you can import directly.

What to avoid relying on

Values reported by the client for anything related to progression. DMZ never trusts them either; read from the server-side capability instead.
Changing StatsData fields directly outside of events or commands. Prefer reacting to or cancelling events over poking values, and prefer DMZ's existing commands when you need to change something DMZ owns.
Registering packets on DMZ's network channel. DMZ's packet ids depend on registration order; use your own channel.
Depending on com.dragonminez.mixin classes or DMZ internals not mentioned above. These can change without notice between versions.

Next step

Once your development environment builds against DMZ and you can see it detected at runtime, move on to Implementation and Events to wire up actual hooks, then to Creating a DMZ Addon for the full Gradle and mods.toml setup.