{"id":15015228,"url":"https://github.com/zsoltmolnarrr/bettercombat","last_synced_at":"2026-03-07T02:09:20.868Z","repository":{"id":37832925,"uuid":"490003443","full_name":"ZsoltMolnarrr/BetterCombat","owner":"ZsoltMolnarrr","description":"⚔️ Easy, spectacular and fun melee combat system from Minecraft Dungeons.","archived":false,"fork":false,"pushed_at":"2025-03-30T18:49:28.000Z","size":21209,"stargazers_count":146,"open_issues_count":18,"forks_count":52,"subscribers_count":6,"default_branch":"1.21.1","last_synced_at":"2025-04-04T07:05:54.977Z","etag":null,"topics":["combat","dungeons","fabrcimc","fabric","melee","minecraft","minecraft-dungeons","minecraft-fabric","minecraft-mod","mod"],"latest_commit_sha":null,"homepage":"https://www.curseforge.com/minecraft/mc-mods/better-combat-by-daedelus","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZsoltMolnarrr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ZsoltMolnarrr"]}},"created_at":"2022-05-08T16:57:18.000Z","updated_at":"2025-04-02T12:56:05.000Z","dependencies_parsed_at":"2023-02-18T15:00:49.345Z","dependency_job_id":"597a4811-9549-452c-80bb-53f7ab779256","html_url":"https://github.com/ZsoltMolnarrr/BetterCombat","commit_stats":{"total_commits":657,"total_committers":27,"mean_commits":"24.333333333333332","dds":"0.24505327245053277","last_synced_commit":"21016071417b0b1ceba8882b4b65e2805d2914ec"},"previous_names":[],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZsoltMolnarrr%2FBetterCombat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZsoltMolnarrr%2FBetterCombat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZsoltMolnarrr%2FBetterCombat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZsoltMolnarrr%2FBetterCombat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZsoltMolnarrr","download_url":"https://codeload.github.com/ZsoltMolnarrr/BetterCombat/tar.gz/refs/heads/1.21.1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135143,"owners_count":20889420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["combat","dungeons","fabrcimc","fabric","melee","minecraft","minecraft-dungeons","minecraft-fabric","minecraft-mod","mod"],"created_at":"2024-09-24T19:46:38.793Z","updated_at":"2025-10-24T08:43:03.360Z","avatar_url":"https://github.com/ZsoltMolnarrr.png","language":"Java","funding_links":["https://github.com/sponsors/ZsoltMolnarrr"],"categories":[],"sub_categories":[],"readme":"![Better Combat](./logo.png)\n\n\u003cdiv align=\"center\"\u003e\n\n  \u003ca href=\"\"\u003e![Java 17](https://img.shields.io/badge/Java%2017-ee9258?logo=coffeescript\u0026logoColor=ffffff\u0026labelColor=606060\u0026style=flat-square)\u003c/a\u003e\n  \u003ca href=\"\"\u003e![Environment: Client \u0026 Server](https://img.shields.io/badge/environment-Client%20\u0026%20Server-1976d2?style=flat-square)\u003c/a\u003e\n  \u003ca href=\"\"\u003e[![Discord](https://img.shields.io/discord/973561601519149057.svg?label=\u0026logo=discord\u0026logoColor=ffffff\u0026color=7389D8\u0026labelColor=6A7EC2\u0026style=flat-square)](https://discord.gg/KN9b3pjFTM)\u003c/a\u003e\n\n\u003c/div\u003e\n\nEasy, spectacular and fun melee combat system we know from Minecraft Dungeons.\n\nAdd unique behaviour to your weapon, or just reuse a preset, using data files (aka JSON API).\n\n🎯 Project goals\n- Replicate Minecraft Dungeons combat experience, by reworking the melee combat system\n- Providing generic weapon capabilities, os other mods to build on top of Better Combat\n- Adding no mod specific features or content, to avoid conflicts\n\n# ⭐️ Features\n\n## Primary features\n- [X] Weapons have combos (each attack in the combo can be different in many ways)\n- [X] Better weapon idle and attack animations\n- [X] Upswing weapon before hitting for natural look and feel\n- [X] No more pixel hunting for target in front, accurate weapon swing calculation (based on [OBB](https://www.sciencedirect.com/topics/computer-science/oriented-bounding-box)+[SAT](https://en.wikipedia.org/wiki/Hyperplane_separation_theorem))\n- [X] Hitting multiple enemies with a single strike\n- [X] Weapon attributes are synchronized (server sends to client)\n- [x] Bundled resources: weapon animations, weapon sounds, weapon attribute presets\n- [x] Integrate any weapon from any mod by just creating data files\n\n## Auxiliary features\n- [X] Attacking with dual wielded weapons (held weapons are used alternated, +20% attack speed while dual wielding, Server configurable)\n- [X] Two-handed weapons ignore offhand slot (melee and ranged weapons also supported)\n- [X] Movement speed reduction while attacking (Server configurable)\n- [X] Cancel attack during upswing (aka \"feint\") (Client configurable)\n- [X] Hold attack key to spam attack (Client configurable)\n- [X] Target in hitbox indication (Client configurable)\n- [X] Swing thru grass (Client configurable)\n- [X] Can disable mining with weapons (Client configurable)\n- [X] Sweeping Edge enchantment reworked\n\n## Compatibility features\n\n### Dedicated compatibility\n\nTo be used by developers and modpack creators.\n\nAssign weapon attribute to weapons individually, using data files (similar how item models are assigned), to specify their animations and behaviour.\n\nThis also known as JSON API. Read more about it at [Integrate your mod](#-integrate-your-mod) section.\n\n### Fallback compatibility\n\nTo be used by players (requires knowledge of JSON and Regex).\n\nBuilt into Better Combat, tries to automatically assign weapon attributes to items without attribute file, based on item id.\n\nTo change assignments, edit: `config/bettercombat/fallback_compatibility.json` file.\n\n(Note: Fallback compatibility can only assign attributes to non-attributed weapons, it cannot override data file based assignments.)\n\n### Item metadata compatibility\n\n#### 1.21.0 and later\n\nWeapon attributes can be referenced in item data component. For example:\n\n```\n/give @p minecraft:wooden_sword[bettercombat:preset_id=\"bettercombat:claymore\"]\n```\n\n#### Old versions\n\n⚠️ This feature does not work correctly in multiplayer, currently.\n\nWeapon attributes can be read from ItemStack NBT. For example:\n```\n/give @p minecraft:wooden_sword{weapon_attributes:'{\"parent\":\"bettercombat:claymore\"}'} 1\n```\n\n## Future plans:\n- [ ] Weapon trail animation while hitting\n- [ ] Parry (under consideration)\n- [ ] Additional weapon attributes (for example: pushback)\n\n# 🔧 Configuration\n\n## Client\n\n### Fabric\n\nYou can access the client side settings via the [Mod Menu](https://github.com/TerraformersMC/ModMenu).\n\n### Forge\n\nYou can access the client side settings in Main Menu \u003e Mods \u003e Better Combat \u003e Config.\n\n## Server\n\nFallback compatibility configuration can be found at: `/config/bettercombat/fallback_compatibility.json`\n\nUse fallback compatibility configuration to add compatibility for any weapon on your server. All weapon attributes are synchronized with clients upon joining the server. \n\nServer config can be found at: `/config/bettercombat/server.json5`\n\nServer configuration is synchronized with clients upon joining the server. \n\n# 🔨 Integrate your mod\n\nThe next steps describe how to add dedicated compatibility for any item.\n\n## Installation\n\nDependencies to resolve via gradle:\n- [Cloth Config](https://shedaniel.gitbook.io/cloth-config/setup-cloth-config/cloth-config-fabric)\n- [PlayerAnimator](https://github.com/KosmX/minecraftPlayerAnimator#include-in-your-dev-environment)\n- [MixinExtras](https://github.com/LlamaLad7/MixinExtras)\n\n### Fabric\n\nDownload the latest release version of the mod with all of its dependencies, and put them into `./run/mods` director.\n\nAlternatively, if you would like to use the JAVA API provided by Better Combat. Install it via gradle:\n```groovy\nrepositories {\n    maven { url 'https://api.modrinth.com/maven' }  \n}\n\ndependencies {\n    [...]\n    modImplementation \"maven.modrinth:better-combat:VERSION-fabric\"\n}\n```\n(Note: JAVA API is only needed for special integration cases.)\n\nPlease note for both Forge and Fabric, [Cloth Config](https://shedaniel.gitbook.io/cloth-config/setup-cloth-config/cloth-config-fabric) and [playerAnimator](https://github.com/KosmX/minecraftPlayerAnimator#include-in-your-dev-environment) are required as well. Please see each link on how to add these to your dev environments.\n\n### Forge\n```groovy\nrepositories {\n    maven { url 'https://api.modrinth.com/maven' }  \n}\n\ndependencies {\n    [...]\n    implementation fg.deobf('maven.modrinth:better-combat:VERSION-forge')\n}\n```\n\n## Prerequisite\n\nMake sure to remove or disable all logic from your mod that is semantically conflicting with this mod:\n- Player animation and or model modifications\n- Attack range modifications\n- Attack timing or cooldown logic modifications\n- Custom attack sound playback\n- Attack/mining key handler modifications (of MinecraftClient)\n- Dual wielding logic\n- Custom item wielding appearance \n\n(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.)\n\n## Basics\n\nWeapon attributes describe the behaviour of a weapon including: range, combos (list of attacks), animations and sounds, etc...\n\nAssign 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.\n**No need for any java dependency**.\n\nWeapon attributes can describe:\n- How the weapon is held (is two-handed, idle pose)\n- Attack range\n- List of attack moves (aka Combo), attacks have the following properties\n  - Damage\n  - Hitbox\n  - Conditions\n  - Animation\n  - Sounds\n\nEach mod should provide their own resources files for compatibility (preferably within their jar file) for the following reasons:\n- A single source of configuration files is difficult to maintain\n- More intuitive installation process for users\n- Every mod developer should decide how their weapon is meant to behave\n- Some mods may need to disable semantically conflicting features (mentioned at [Prerequisite](#prerequisite))\n\nLet's see an example where we add attributes to a custom sword named \"Big Sword\" from your mod:\n- mod id is `my-mod-id`\n- id of the item is `my-mod-id:big_sword`\n\nTo assign weapon attributes to the Big Sword, create a new json file at the following location:\n\n```resources/data/my-mod-id/weapon_attributes/big_sword.json```\n\nThe content of this json file should be the following:\n\n## Using a preset\n\nPresets are out of the box collection of weapon attributes bundled with this mod, covering the common weapon types.\n\nA 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:\n\n```\n{\n  \"parent\": \"bettercombat:claymore\"\n}\n```\n\nYou can check out all available presets [here](common/src/main/resources/data/bettercombat/weapon_attributes).\n\nYou can check out how presets are used to add compatibility for Vanilla weapons [here](common/src/main/resources/data/minecraft/weapon_attributes).\n\nYou can make and reference your own presets the same way.\n\n## Custom attributes\n\nIf you want unique behaviour for your weapon, you can create attributes from scratch.\n\nThe content of your weapon attributes JSON file is parsed into an [AttributesContainer](common/src/main/java/net/bettercombat/api/AttributesContainer.java) object. (Check out the inline java documentation of [AttributesContainer](common/src/main/java/net/bettercombat/api/AttributesContainer.java) for details.)\n\nWhen no parent is specified, the value for `\"attributes\"` key must be a full json object that can be parsed into [WeaponAttributes](common/src/main/java/net/bettercombat/api/WeaponAttributes.java) object.\n\n```\n{\n  \"attributes\": { ... }\n}\n```\n\nCheck out the existing [weapon presets](common/src/main/resources/data/bettercombat/weapon_attributes) to see practical examples of building from scratch.\n\nCheck out the available [attack animations](common/src/main/resources/assets/bettercombat/player_animations), bundled with Better Combat. \n\nIf you need more details, the java documentation of [WeaponAttributes](common/src/main/java/net/bettercombat/api/WeaponAttributes.java) covers all the specifics.\n\n---\n\nWhen `\"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](common/src/main/java/net/bettercombat/api/WeaponAttributes.java) object.\n\n(Attributes are merged in parent -\u003e child order. So parent properties are copied and overridden with child. The chain of inheritance can be any length.)\n```\n{\n  \"parent\": \"bettercombat:claymore\",\n  \"attributes\": {\n    \"attack_range\": 3.5\n    \"attacks\": [\n      {\n        \"angle\": 100\n      },\n      {\n        \"damageMultiplier\": 0.1 \n      },\n      {\n        \"damageMultiplier\": 0.3,\n        \"angle\" = 90\n      }\n    ]\n  }\n}\n```\n\n---\n\nYou can create and use your own presets:\n```\n{\n  \"parent\": \"my-mod-id:longsword\",\n  \"attributes\": { ... }\n}\n```\n\n## Custom animations\n\nLet's say you want to create a custom attack animation with the following name: `big_sword_slash`\n\n### Creating animation\n\nCreate keyframe animations using our Blender model, that includes an export script creating animation files.\n\nCheck out the [Animation guide](animations/README.md) for details.\n![Blender example](.github/images/blender-example.png)\n\n### Adding animation\n\nAdd the created animation to the following location\n\n```resources/assets/my-mod-id/player_animations/big_sword_slash.json```\n\n### Using the animation\n\nYou can use your custom animation by referencing it, following the resource identifier pattern. \n\nMake sure to specify a fitting `upswing` value next to your animation (to make it look and feel nice to use).\n\n```\n{\n  // ...\n  \"attributes\": {\n    // ...\n    \"attacks\": [\n      {\n        \"animation\": \"my-mod-id:big_sword_slash\",\n        \"upswing\": 0.5\n      },\n      // ...\n    ]\n  }\n}\n```\n\n# 📦 Using datapacks\n\nYou can create datapacks to add dedicated compatibility for any weapon.\n\n⚠️ Caution! Some mods may have conflicting features, that causes incorrect appearance or behaviour of weapons, even if compatibility is added. In this case mod developers need to resolve incompatibilities. (Check [mod compatibility](https://github.com/ZsoltMolnarrr/BetterCombat#-mod-compatibility) section for potential source of problems.)\n\nSteps:\n1. [Create a datapack](https://minecraft.fandom.com/wiki/Tutorials/Creating_a_data_pack)\n2. Add weapon attribute files based on our [integration guide](https://github.com/ZsoltMolnarrr/BetterCombat#-integrate-your-mod), the easiest way to [use existing presets](https://github.com/ZsoltMolnarrr/BetterCombat#using-a-preset) of Better Combat\n\nFor example, adding compatibility for an item with id `fruits:banana_sword` from Fruits mod, to make it act like a `claymore`, would look like the following.\n\nFile path:\n```\nDataPackName/data/fruits/weapon_attributes/banana_sword.json\n```\n\nContent:\n```\n{\n  \"parent\": \"bettercombat:claymore\"\n}\n```\n\n# ⛓ Mod compatibility\n\nThis 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.\n\nMods with one or more of these features are considered as a semantic incompatibility\n- Dual wielding implementation\n- Attack range modifications\n- Attack timing or attack cooldown logic modifications\n- Attack/mining key handler modifications (of MinecraftClient)\n- Player model modification\n\n# ✍️ Contribution\n\nBefore committing yourself to implementing any change for the project, it is strongly suggested to check with us on Discord. The project has a strong vision for what technical solutions are accepted, and what features belong to the scope of the project.\n\nAvoid creating pull requests with the following content:\n- huge code changes\n- feature that is out of scope\n- feature that already exist in some form\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsoltmolnarrr%2Fbettercombat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzsoltmolnarrr%2Fbettercombat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsoltmolnarrr%2Fbettercombat/lists"}