Note: this tutorial is written for MCreator, though the troubleshooting logic applies to any GeckoLib entity you build in a standalone IDE. It includes light code sections that assume basic programming knowledge.
The symptom#
You build an attack animation in Blockbench — a big wind-up, a swing, a recovery — and it looks right in the preview. In game, the mob hits you the instant it raises its arm, and the damage number floats up while the animation is still winding up. The attack lands at frame 0, not at the frame where the weapon connects.
Combat mods interact with each other more than with the base game; we broke down how the layers stack in multi-mod combat systems.
It is not an animation bug. The animation plays exactly as authored; the damage is simply being applied by a completely different system, on a different clock.
Why it happens#
When an entity attacks, vanilla calls doHurtTarget at the start of the attack. That method calculates and applies damage immediately, in the same tick the attack begins. Attack animations are cosmetic: they play over time on the client, but they have no connection to when the damage actually happens.
With vanilla mobs you never notice, because their attack animation is short and the weapon connects almost immediately. With a GeckoLib attack animation that runs for half a second or more, the gap becomes obvious — and on a boss with a 1.5-second wind-up it is the difference between a dodgeable attack and an unavoidable one.
The fix is to stop letting the default attack apply damage, play your animation, and apply the damage yourself at the frame where the swing connects.
Before you start#
This assumes:
- Minecraft 1.20.1 with Forge
- MCreator with the GeckoLib and Attributes plugins installed
- An animated entity that already works — it spawns, moves, and plays idle and walk animations
If the entity does not animate at all yet, fix that first. This guide changes when damage happens, and it cannot fix an entity whose animations are not loading.
Step 1: turn off the built-in attack animation#
Open your entity’s animation settings and uncheck the built-in attack animation toggle, then save. That single checkbox is what removes the default “play attack animation and call doHurtTarget on the same tick” behaviour.
After saving, MCreator generates code with the attack animation hook removed. That is expected — you are replacing it with a procedure.
Step 2: build the replacement procedure#
Create a procedure named something like [YourEntity] Attack and wire it in the visual editor. The logic has five parts.
- Cancel the default attack event so no damage is applied at frame zero.
- Trigger your custom animation — the one you made in Blockbench, not a built-in.
- Delay by the number of ticks it takes to reach the hit frame, then apply damage.
- Check range and facing before applying the damage, so the mob cannot hit you through a wall or over its shoulder.
- Check for a shield before applying, so blocking works.
The delay number#
This is the part people guess and get wrong. Animation time in Minecraft is measured in ticks, 20 per second.
- Hit frame at 0.25 s → 5 ticks
- Hit frame at 0.45 s → 9 ticks
- Hit frame at 0.75 s → 15 ticks
Read the hit frame off the Blockbench timeline, multiply seconds by 20, round to the nearest tick. If the mob feels late, you are one or two ticks over; if it feels early, under. Adjust in single-tick steps, not by eye.
The range check#
Do not use “is the target within N blocks” as a box. Use straight-line 3D distance:
sqrt((x2-x1)² + (y2-y1)² + (z2-z1)²)
and compare it against your reach value (the 2 in the example is two blocks; set it to whatever your weapon’s visual length suggests). Pair it with a facing check: a mob that has already turned away mid-animation should miss, and without the facing test it will still connect.
The shield check#
Insert this custom code so damage only lands when the target is not actively blocking:
!(entity instanceof LivingEntity && ((LivingEntity) entity).isUsingItem() && ((LivingEntity) entity).getUseItem().getItem().equals(Items.SHIELD))
With it, a raised shield nullifies the damage and the normal block effects play. Without it, your custom attack is the one thing in the game that ignores shields — which players notice immediately and report as a bug.
This snippet is also the most fragile part of the whole setup: it references Items.SHIELD and the isUsingItem pattern, both of which can change shape in a version port. If the procedure compiles but does nothing after an update, check this line first.
Step 3: test the timing, not the animation#
Animation previews lie about timing because they play at editor speed with no server involved. Test in game:
- Spawn the mob in a flat, lit area and stand in range.
- Watch where the damage lands relative to the swing — you want the number to appear at the contact frame, not before it.
- Walk out of range mid-animation. The attack should whiff; if it still connects, your range check is running before the delay instead of after it.
- Hold a shield and repeat. If you take damage while blocking, the shield check is missing or in the wrong branch.
Common mistakes#
Delay inserted before the animation trigger. The mob stands still for half a second and then swings. The animation must fire first, then the delay.
Damage applied inside the same procedure call as the trigger. MCreator’s visual editor makes it easy to place the damage block above the delay without noticing; the procedure runs top to bottom.
Range checked against the wrong entity. In the procedure context, “entity” and “source entity” are different things. Checking the wrong one makes the attack always hit or never hit.
Forgetting that the delay is in ticks. A “1 second” animation needs a 20, not a 1.
Does this still work on newer versions?#
The approach does; the exact blocks may not. doHurtTarget, the shield check and the GeckoLib animation trigger have all changed shape across 1.20 → 1.21. If you are porting, the procedure usually needs three fixes: the shield snippet, the animation call signature, and the attack event hook. Everything else — delay, range, facing — is logic you can keep.
Quick answers#
Why does my GeckoLib mob deal damage before its attack animation? Because doHurtTarget fires at the start of the attack. Damage is instant; the animation is cosmetic.
How many ticks should the delay be? Hit frame in seconds × 20. A 0.45 s hit frame is 9 ticks.
Do I need the Attributes plugin? For a working animated entity in MCreator, yes — this guide assumes it is installed.
Will this break on 1.21? The logic survives; the shield snippet and animation call need updating.
If animation work is new to you, the atmosphere mod guide shows what finished mods look like at the visual end, and the Create: Aeronautics addons are a good example of how much a single animation layer can change a mod.
Procedure structure and code snippet follow the original MCreator/GeckoLib write-up this page is based on; timing guidance (ticks = seconds × 20) follows Minecraft’s tick rate.
