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
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
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 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: big_sword_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/attack_animations/big_sword_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:big_sword_slash",
"upswing": 0.5
},
// ...
]
}
}
🔧
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.