<div align="center">

<a href=""></a> <a href=""></a> <a href=""></a>

</div>

Easy, spectacular and fun melee combat system we know from Minecraft Dungeons.

Add unique behaviour to your weapon, or just reuse a preset, using data files (aka JSON API).

🎯 Project goals

• Replicate Minecraft Dungeons combat experience, by reworking the melee combat system
• Providing generic weapon capabilities, os other mods to build on top of Better Combat
• Adding no mod specific features or content, to avoid conflicts

⭐️ Features

Primary features

• [X] Weapons have combos (each attack in the combo can be different in many ways)
• [X] Better weapon idle and attack animations
• [X] Upswing weapon before hitting for natural look and feel
• [X] No more pixel hunting for target in front, accurate weapon swing calculation (based on OBB+SAT)
• [X] Hitting multiple enemies with a single strike
• [X] Weapon attributes are synchronized (server sends to client)
• [x] Bundled resources: weapon animations, weapon sounds, weapon attribute presets
• [x] Integrate any weapon from any mod by just creating data files

Auxiliary features

• [X] Attacking with dual wielded weapons (held weapons are used alternated, +20% attack speed while dual wielding, Server configurable)
• [X] Two-handed weapons ignore offhand slot (melee and ranged weapons also supported)
• [X] Movement speed reduction while attacking (Server configurable)
• [X] Cancel attack during upswing (aka "feint") (Client configurable)
• [X] Hold attack key to spam attack (Client configurable)
• [X] Target in hitbox indication (Client configurable)
• [X] Swing thru grass (Client configurable)
• [X] Can disable mining with weapons (Client configurable)
• [X] Sweeping Edge enchantment reworked

Compatibility features

Dedicated compatibility

To be used by developers and modpack creators.

Assign weapon attribute to weapons individually, using data files (similar how item models are assigned), to specify their animations and behaviour.

This also known as JSON API. Read more about it at Integrate your mod section.

Fallback compatibility

To be used by players (requires knowledge of JSON and Regex).

Built into Better Combat, tries to automatically assign weapon attributes to items without attribute file, based on item id.

To change assignments, edit: config/bettercombat/fallback_compatibility.json file.

(Note: Fallback compatibility can only assign attributes to non-attributed weapons, it cannot override data file based assignments.)

Item metadata compatibility

1.21.0 and later

Weapon attributes can be referenced in item data component. For example:

/give @p minecraft:wooden_sword[bettercombat:preset_id="bettercombat:claymore"]

Old versions

⚠️ This feature does not work correctly in multiplayer, currently.

Weapon attributes can be read from ItemStack NBT. For example:

/give @p minecraft:wooden_sword{weapon_attributes:'{"parent":"bettercombat:claymore"}'} 1

Future plans:

• [ ] Weapon trail animation while hitting
• [ ] Parry (under consideration)
• [ ] Additional weapon attributes (for example: pushback)

🔧 Configuration

Client

Fabric

You can access the client side settings via the Mod Menu.

Forge

You can access the client side settings in Main Menu > Mods > Better Combat > Config.

Server

Fallback compatibility configuration can be found at: /config/bettercombat/fallback_compatibility.json

Use fallback compatibility configuration to add compatibility for any weapon on your server. All weapon attributes are synchronized with clients upon joining the server.

Server config can be found at: /config/bettercombat/server.json5

Server configuration is synchronized with clients upon joining the server.

🔨 Integrate your mod

The next steps describe how to add dedicated compatibility for any item.

Installation

Dependencies to resolve via gradle:

• Cloth Config
• PlayerAnimator
• MixinExtras

Fabric

Download the latest release version of the mod with all of its dependencies, and put them into ./run/mods director.

Alternatively, if you would like to use the JAVA API provided by Better Combat. Install it via gradle:

repositories {
    maven { url 'https://api.modrinth.com/maven' }  
}

dependencies {
    [...]
    modImplementation "maven.modrinth:better-combat:VERSION-fabric"
}

(Note: JAVA API is only needed for special integration cases.)

Please note for both Forge and Fabric, Cloth Config and playerAnimator are required as well. Please see each link on how to add these to your dev environments.

Forge

repositories {
    maven { url 'https://api.modrinth.com/maven' }  
}

dependencies {
    [...]
    implementation fg.deobf('maven.modrinth:better-combat:VERSION-forge')
}

Prerequisite

Make sure to remove or disable all logic from your mod that is semantically conflicting with this mod:

• Player animation and or model modifications
• Attack range modifications
• Attack timing or cooldown logic modifications
• Custom attack sound playback
• Attack/mining key handler modifications (of MinecraftClient)
• Dual wielding logic
• Custom item wielding appearance

(Note: Better Combat expects all items to be held like swords, it rotates them accordingly during animations. If you have a dagger that is facing backwards, you need to disable that, otherwise it will be facing backwards during attack animations too. Better Combat offers weapon specific poses for adjusting position and rotation of items while idling.)

Basics

Weapon attributes describe the behaviour of a weapon including: range, combos (list of attacks), animations and sounds, etc...

Assign weapon attributes to weapons of your mod, just by creating resource files. This is done similar to how you assign crafting recipes to an item. No need for any java dependency.

Weapon attributes can describe:

• How the weapon is held (is two-handed, idle pose)
• Attack range
• List of attack moves (aka Combo), attacks have the following properties
  • Damage
  • Hitbox
  • Conditions
  • Animation
  • Sounds

Each mod should provide their own resources files for compatibility (preferably within their jar file) for the following reasons:

• A single source of configuration files is difficult to maintain
• More intuitive installation process for users
• Every mod developer should decide how their weapon is meant to behave
• Some mods may need to disable semantically conflicting features (mentioned at Prerequisite)

Let's see an example where we add attributes to a custom sword named "Big Sword" from your mod:

• mod id is my-mod-id
• id of the item is my-mod-id:big_sword

To assign weapon attributes to the Big Sword, create a new json file at the following location:

resources/data/my-mod-id/weapon_attributes/big_sword.json

The content of this json file should be the following:

Using a preset

Presets are out of the box collection of weapon attributes bundled with this mod, covering the common weapon types.

A fitting preset for a big two handed sword is the claymore from Better Combat, its identifier is: bettercombat:claymore. To use this preset add the following content to your JSON file:

{
  "parent": "bettercombat:claymore"
}

You can check out all available presets here.

You can check out how presets are used to add compatibility for Vanilla weapons here.

You can make and reference your own presets the same way.

Custom attributes

If you want unique behaviour for your weapon, you can create attributes from scratch.

The content of your weapon attributes JSON file is parsed into an AttributesContainer object. (Check out the inline java documentation of AttributesContainer for details.)

When no parent is specified, the value for "attributes" key must be a full json object that can be parsed into WeaponAttributes object.

{
  "attributes": { ... }
}

Check out the existing weapon presets to see practical examples of building from scratch.

Check out the available attack animations, bundled with Better Combat.

If you need more details, the java documentation of WeaponAttributes covers all the specifics.

---

When "parent" and "attributes" are both specified, you can customize attributes by partially (or fully) overriding the properties. Make sure the inheritance results i