Weapon Attributes

Weapon Attributes is a datapack system that tells the DragonMineZ combat engine how a specific item behaves in combat: attack range, animation, hitbox shape, damage multipliers, conditional attack variants (dual-wielding, sneaking, mounted and so on) and critical stats. Third-party weapon mods hook into this system to get proper DragonMineZ combat behavior.

Loader: WeaponRegistry.loadAttributes(resourceManager), in src/main/java/com/dragonminez/common/combat/logic/weapon/WeaponRegistry.java. It reloads with the vanilla datapack reload (/reload or a restart), not with /dmzreload.

File location and item mapping

data/<namespace>/weapon_attributes/<item_path>.json

The namespace and path become the target item id: data/dragonminez/weapon_attributes/axe.json applies to dragonminez:axe. A third-party mod defines its own weapons under its own namespace, for example data/mymod/weapon_attributes/great_axe.json for mymod:great_axe.

Better Combat datapacks Any bettercombat: namespace found in these JSON files is rewritten to dragonminez: at load time, so weapon attribute datapacks written for the Better Combat mod mostly work as they are.

Top-level schema

A file holds an attributes object:

{
  "attributes": { ... }
}

Or, to inherit another item's attributes and only override specific fields, it names a parent:

{
  "parent": "dragonminez:sword",
  "attributes": {
    "crit_chance": 0.10,
    "crit_damage": 0.15
  }
}

parent chains can go several levels deep (a parent can have its own parent). Cycles are detected: a weapon whose parent chain loops back on itself fails to resolve and is skipped (logged as an error), so double-check your parent references.

Attributes fields

Configured in: Combat ConfigfallbackCompatibility

Field	Type	What it does
`attack_range`	Number	Reach in blocks (the Minecraft default `3.0` if left out).
`pose`	String	GeckoLib animation pose for the main-hand weapon.
`off_hand_pose`	String	GeckoLib animation pose for the off-hand weapon.
`two_handed`	Boolean	If `true`, the off hand can't be used while the weapon is wielded.
`category`	String	Free-form category tag. It is used for two things: matching `DUAL_WIELDING_SAME_CATEGORY` conditions between the main hand and the off hand, and as the target category for the `fallbackCompatibility` regex system in Combat Config.
`crit_chance`	Number	Innate critical chance (`0.0`–`1.0`), applied as an attribute modifier.
`crit_damage`	Number	Innate critical damage multiplier, applied as an attribute modifier.
`attacks`	Array	Required. One or more attack variants (see below).

Attack entries

Each entry of attacks describes one swing variant. DragonMineZ checks the conditions from top to bottom and uses the first attack whose conditions all pass.

Field	Type	What it does
`conditions`	List of condition strings	All of them must be true for this variant to fire. Leave it out for an unconditional attack.
`hitbox`	String	`FORWARD_BOX` (a box extending forward, closest to vanilla), `VERTICAL_PLANE` (a vertical sweeping slash) or `HORIZONTAL_PLANE` (a wide horizontal sweep).
`damage_multiplier`	Number	Multiplier on the weapon's base damage (default `1.0`).
`angle`	Number	Swing arc in degrees.
`upswing`	Number	Cooldown multiplier: `cooldownTicks = (1 / (4 - attackSpeed)) * 20 * upswing`. Lower means a faster follow-up. It also sets the swing's windup (the delay before the hit lands): animation ticks × `upswing` × 0.95, clamped to 3–7 ticks.
`animation`	String	GeckoLib animation name. It is checked against `animations/*.json`; if there is no exact match, DragonMineZ picks the closest name (Levenshtein distance) after stripping known prefixes (`dragonminez:`, `bettercombat:`, `combat.`).
`swing_sound` / `impact_sound`	`{ "id", "volume", "pitch", "randomness"* }`	Sound played on swing or impact. `volume` and `pitch` default to `1.0`, `randomness` to `0.1`.

Attack conditions

This is the complete list of conditions:

Condition	Meaning
`NOT_DUAL_WIELDING`	The off hand is empty (air).
`DUAL_WIELDING_ANY`	Both hands hold something.
`DUAL_WIELDING_SAME`	Both hands hold the exact same item id.
`DUAL_WIELDING_SAME_CATEGORY`	Both hands hold items that share the same `category`.
`NO_OFFHAND_ITEM`	The off hand is empty.
`OFF_HAND_SHIELD`	The off hand holds a shield.
`MAIN_HAND_ONLY`	The attack only applies to the main-hand weapon.
`OFF_HAND_ONLY`	The attack only applies to the off-hand weapon.
`MOUNTED`	The player is riding an entity.
`NOT_MOUNTED`	The player is not riding.
`SNEAKING`	The player is crouching.
`NOT_SNEAKING`	The player is standing.

Full example

A dagger with several attacks and a dual-wield variant:

{
  "attributes": {
    "attack_range": 2,
    "two_handed": false,
    "category": "dagger",
    "attacks": [
      {
        "hitbox": "HORIZONTAL_PLANE",
        "damage_multiplier": 0.8,
        "angle": 150,
        "upswing": 0.5,
        "animation": "combat.one_handed_slash_horizontal_right_1",
        "swing_sound": { "id": "dragonminez:dagger_slash" }
      },
      {
        "hitbox": "HORIZONTAL_PLANE",
        "damage_multiplier": 0.8,
        "angle": 150,
        "upswing": 0.5,
        "animation": "combat.one_handed_slash_horizontal_right_2",
        "swing_sound": { "id": "dragonminez:dagger_slash" }
      },
      {
        "conditions": ["DUAL_WIELDING_SAME_CATEGORY", "MAIN_HAND_ONLY"],
        "hitbox": "FORWARD_BOX",
        "damage_multiplier": 1.4,
        "angle": 150,
        "upswing": 0.5,
        "animation": "combat.dual_handed_stab",
        "swing_sound": { "id": "dragonminez:dagger_slash" }
      }
    ]
  }
}

An inheritance example (brave_sword.json, overriding only the critical stats):

{
  "parent": "dragonminez:sword",
  "attributes": {
    "crit_chance": 0.10,
    "crit_damage": 0.15
  }
}

Shipped attribute files

For third-party weapon mods

If your mod adds weapons and you don't ship a Weapon Attributes entry for them, DragonMineZ falls back to matching the item id of every item with an attack-damage modifier against the fallbackCompatibility list in Combat Config (for example, an item id containing axe is treated like dragonminez:axe). This gives a reasonable default, but a real datapack entry that matches your weapon's actual moveset and animations is always more accurate, and it always takes priority over the fallback guess.

Reload and validate

Add or edit files under data/<namespace>/weapon_attributes/.
Validate the JSON syntax (see How to JSON).
Run the vanilla /reload, or restart. This is a plain datapack reload listener, not part of /dmzreload (see Reloading and Updating Changes).
Test the weapon in game: range, animation, hitbox shape and any conditional variants (dual-wielding, sneaking, mounted).