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

Add unique behaviour to your weapon, or just reuse a preset, via the JSON API.

⭐️ Features

Primary features:

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

Auxiliary features:

Two-handed weapons ignore offhand slot
Attacking with dual wielded weapons (Server configurable)
Cancel attack during upswing (aka "feint") (Client configurable)
Hold attack key to spam attack (Client configurable)
Target in hitbox indication (Client configurable)
Swing thru grass (Client configurable)
Can disable mining with weapons (Client configurable)

Future plans:

Rolling
Additional weapon attributes (for example: movement penalty, pushback)
Weapon trail animation while hitting

🔨 Integrate your mod

Prerequisite

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

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

Download the latest release of the mod, and install it in your project run directory (./run/mods).

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 or gradle 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

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

mod id is my-mod-id
item id of the Claymore is my-mod-id:claymore

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

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

The content of this json file should be the following:

Using a preset

Presets are a collection of weapon attributes bundled with this mod, covering the most common use cases.

Example for using the bettercombat:claymore for our Claymore:

{
  "parent": "bettercombat:claymore"
}

You can check out all available presets 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 inline java documentation of WeaponAttributes for details.

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

(Attributes are merged in parent -> child order. So parent properties are copied and overridden with child. The chain of inheritance can be any length.)

{
  "parent": "bettercombat:claymore",
  "attributes": {
    "attackRange": 3.5
    "attacks": [
      {
        "angle": 100
      },
      {
        "damageMultiplier": 0.1 
      },
      {
        "damageMultiplier": 0.3,
        "angle" = 90
      }
    ]
  }
}

You can create and use your own presets:

{
  "parent": "my-mod-id:longsword",
  "attributes": { ... }
}

Custom animations

Let's say you want to create a custom attack animation with the following name: my_claymore_slash

Creating animation

Create keyframe animations using our Blender model, that includes an export script creating animation files.

Check out the Animation guide for details.

Adding animation

Add the created animation to the following location

resources/assets/my-mod-id/weapon_animations/my_claymore_slash.json

Using the animation

You can use your custom animation by referencing it, following the resource identifier pattern.

Make sure to specify a fitting upswing value next to your animation (to make it look and feel nice to use).

{
  // ...
  "attributes": {
    // ...
    "attacks": [
      {
        "animation": "my-mod-id:my_claymore_slash",
        "upswing": 0.4
      },
      // ...
    ]
  }
}

🔧 Configuration

Client

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

Server

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

Automatically created with default values, upon loading any game world for the first time.

⛓ Compatibility

This mod has been created in the spirit of maximal compatibility. However since some core mechanics are overridden, mods trying to change the same thing will never be compatible.

bernie-g/BetterCombat