FuzzyBot: Updating to match new version of source page

2026-10-13T05:22:41Z

Updating to match new version of source page

New page

'''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: <code>WeaponRegistry.loadAttributes(resourceManager)</code>, in <code>src/main/java/com/dragonminez/common/combat/logic/weapon/WeaponRegistry.java</code>. It reloads with the vanilla datapack reload (<code>/reload</code> or a restart), '''not''' with <code>/dmzreload</code>.

== File location and item mapping ==

<syntaxhighlight lang="text">
data/<namespace>/weapon_attributes/<item_path>.json
</syntaxhighlight>

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

{{Note|title=Better Combat datapacks|text=Any <code>bettercombat:</code> namespace found in these JSON files is rewritten to <code>dragonminez:</code> 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 <code>attributes</code> object:

<syntaxhighlight lang="text">
{
"attributes": { ... }
}
</syntaxhighlight>

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

<syntaxhighlight lang="json">
{
"parent": "dragonminez:sword",
"attributes": {
"crit_chance": 0.10,
"crit_damage": 0.15
}
}
</syntaxhighlight>

<code>parent</code> 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 <code>parent</code> references.

== Attributes fields ==
{{Config|Combat Config|fallbackCompatibility}}

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

== Attack entries ==
Each entry of <code>attacks</code> describes one swing variant. DragonMineZ checks the <code>conditions</code> from top to bottom and uses the first attack whose conditions all pass.

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

=== Attack conditions ===
This is the complete list of conditions:

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

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

<syntaxhighlight lang="json">
{
"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" }
}
]
}
}
</syntaxhighlight>

An inheritance example (<code>brave_sword.json</code>, overriding only the critical stats):

<syntaxhighlight lang="json">
{
"parent": "dragonminez:sword",
"attributes": {
"crit_chance": 0.10,
"crit_damage": 0.15
}
}
</syntaxhighlight>

== Shipped attribute files ==
{{See also|Special Weapons}}
DragonMineZ ships these entries under <code>data/dragonminez/weapon_attributes/</code>, so you can use them as a <code>parent</code> or as a <code>weaponCombo</code> or fallback target:
* '''Base movesets:''' <code>anchor</code>, <code>axe</code>, <code>battlestaff</code>, <code>claw</code>, <code>claymore</code>, <code>cutlass</code>, <code>dagger</code>, <code>double_axe</code>, <code>fist</code>, <code>giant</code>, <code>glaive</code>, <code>halberd</code>, <code>hammer</code>, <code>katana</code>, <code>lance</code>, <code>mace</code>, <code>pickaxe</code>, <code>rapier</code>, <code>scythe</code>, <code>sickle</code>, <code>soul_knife</code>, <code>spear</code>, <code>staff</code>, <code>sword</code>, <code>trident</code>, <code>twin_blade</code>, <code>wand</code>.
* '''Signature weapons:''' <code>brave_sword</code> ([[Special:MyLanguage/Brave Sword|Brave Sword]], parent <code>sword</code>), <code>yajirobe_katana</code> ([[Special:MyLanguage/Yajirobe's Katana|Yajirobe's Katana]], parent <code>katana</code>), <code>z_sword</code> ([[Special:MyLanguage/Z Sword|Z Sword]], parent <code>claymore</code>) and <code>power_pole</code> ([[Special:MyLanguage/Power Pole|Power Pole]], parent <code>staff</code>, with its own three-hit combo).

DragonMineZ items without an entry of their own (for example the [[Special:MyLanguage/Dimension Sword|Dimension Sword]] and the Tamagami weapons: [[Special:MyLanguage/Tamagami Sword|Tamagami Sword]], [[Special:MyLanguage/Tamagami Trident|Tamagami Trident]] and [[Special:MyLanguage/Tamagami Hammer|Tamagami Hammer]]) get their moveset from the <code>fallbackCompatibility</code> regexes in [[Special:MyLanguage/Combat Config|Combat Config]], just like third-party weapons.

== 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 <code>fallbackCompatibility</code> list in [[Special:MyLanguage/Combat Config|Combat Config]] (for example, an item id containing <code>axe</code> is treated like <code>dragonminez:axe</code>). 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 <code>data/<namespace>/weapon_attributes/</code>.
# Validate the JSON syntax (see [[Special:MyLanguage/How to JSON|How to JSON]]).
# Run the vanilla <code>/reload</code>, or restart. This is a plain datapack reload listener, not part of <code>/dmzreload</code> (see [[Special:MyLanguage/Reloading and Updating Changes|Reloading and Updating Changes]]).
# Test the weapon in game: range, animation, hitbox shape and any conditional variants (dual-wielding, sneaking, mounted).

{{Navbox Modding}}

Weapon Attributes/en - Revision history

FuzzyBot: Updating to match new version of source page