Add-on Getting Started

Add-on Getting Started covers what you need in place before you wire up your own Forge mod against DragonMineZ: the toolchain versions, the mods to avoid, and the parts of DMZ an add-on can safely rely on. Read it before Creating a DMZ Addon.

Who this is for

These pages are for Forge add-on developers who want their own mod jar to react to DMZ: granting bonus TP, listening for form changes, adding new quest objective and reward types, adding buttons to the utility menu and so on. If you just want to tune numbers or add races, forms, quests or wishes, you don't need any of this; see Developer Scope and Prerequisites instead.

DMZ has no Java API to register new races, forms, skills or techniques: new races and forms are added through JSON config files (see Custom Races and Custom Forms).

Required toolchain

Requirement	Version	Where it is declared
Minecraft	`1.20.1`	`gradle.properties`
Forge	`47.4.10` (accepts `[47,)`)	`gradle.properties`, add-on `mods.toml`
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.