Enemy Attack System

Overview

An attack is split in two:

an attack component that knows how to attack (range, cooldown, windup, damage, knockback), and
an AI task that decides when to attack and tells the component to try (see Enemy AI Tasks).

The two only talk through events on the enemy's own EventHandler. A task triggers an event such as meleeAttack; the component listens for it. That is why an animation controller can react to an attack without knowing which component made it: it listens for the same events.

The attack components

All are in components/attacks/.

Component	What it does	Used by
`MeleeAttackComponent`	a close-range hit after a windup	Skeleton, Minotaur, Cyclops (stomp), Medusa, Cerberus, Zeus, Harpy
`RangedAttackComponent`	fires a projectile after a windup	Ranged Skeleton, Centaur, Medusa (gaze), Zeus (lightning), Ranged Harpy
`RockAttackComponent`	a `RangedAttackComponent` that throws a rock in an arc	Cyclops
`LaserAttackComponent`	a `RangedAttackComponent` that fires a fast straight shot	Cyclops
`TouchAttackComponent`	damage on contact, with an on/off switch and a hit limit	Minotaur, Centaur (during a charge)
`ChargeComponent`	a windup, then a fast rush that drives the touch attack	Minotaur, Centaur
`PetrifyEffectComponent`	stops whatever the attack hits from walking, for a set time	Medusa (on the shooter); a projectile form is kept but unused
`LightningFreezeComponent`	freezes the target when a lightning bolt hits	Zeus's lightning

The life of one attack

Melee and ranged attacks follow the same four steps.

Trigger. The task triggers the attack event with the target, every frame the target is in range.
Checks. The component refuses if it is on cooldown, already winding up, the target is missing, dead, out of range or has no CombatStatsComponent.
Windup. The component announces a windup event and waits. The windup length comes from the weapon (or the config for a natural weapon) and is always shorter than the cooldown.
Resolve. When the windup ends the component checks the target again.
- Melee: if the target is still alive and in range it takes the damage and knockback; otherwise the swing misses and a whiff event is announced. Either way the cooldown starts.
- Ranged: if the target died the shot is cancelled; otherwise a projectile is created and registered. A target that only moved out of range is still shot at.

Events

Component	Listens for	Announces
`MeleeAttackComponent`	`meleeAttack`	`meleeAttackWindup`, `meleeAttackHit`, `meleeAttackWhiff`
`RangedAttackComponent`	`<prefix>`	`<prefix>Windup`, `<prefix>Fired`, `<prefix>Hit`, `<prefix>Cancelled`
`ChargeComponent`	`movementBlocked`	`chargeStart`, `chargeWindupStart`, `chargeRushStart`, `chargeEnd`
`TouchAttackComponent`	`collisionStart`	`touchAttackHit`

The ranged prefix is rangedAttack by default. The Cyclops holds two ranged attacks, so its rock uses rockAttack and its laser uses laserAttack; otherwise one trigger would fire both.

Damage and weapons

Damage comes from a WeaponItem. An enemy that holds a real weapon (a Skeleton's sword, a Minotaur's axe) uses that weapon's damage and can drop it. An enemy with no held weapon uses a natural weapon (WeaponItem.natural(name, damage, windup)), for example "Cyclops Fists", which is never added to the inventory and never drops.

The difficulty setting scales damage through each component's damage multiplier, without changing the enemy's stored base attack.

The charge

ChargeComponent does not deal damage itself. On create() it switches the enemy's TouchAttackComponent off and limits it to one hit per activation. A charge then runs in two phases:

Windup. The enemy stands still. Touch damage is off, so standing next to a winding-up Minotaur is safe.
Rush. The enemy's speed is multiplied, the touch attack is activated with the charge's damage multiplier, and the first thing it touches takes one boosted hit. If endOnHit is set the charge ends on that hit.

The charge also ends when its duration runs out, or when a hazard blocks the rush (the movementBlocked event from the movement guard). Ending starts the cooldown and switches touch damage off again.

Projectiles

A ranged attack builds its projectile through ArrowFactory. A projectile is an entity with:

ProjectileComponent: owns a ProjectileMovementStrategy and despawns at maximum range.
ProjectileHitComponent: damages the target layer, stops on the blocking layer, and announces projectileHit.
optionally an effect component. LightningFreezeComponent is added to a lightning bolt by ArrowFactory.

Medusa's petrify.

PetrifyEffectComponent is attached to Medusa herself, not to a projectile. It listens for Medusa's rangedAttackHit event, which RangedAttackComponent fires when its projectile lands, and triggers applySpeedEffect on the entity that was hit with a speed multiplier of 0 for the petrify duration. The duration comes from the petrify block in NPCs.json (PetrifyConfig.duration, in seconds) and is converted to ticks at 60 a second. The team rule is that the attack's cooldown must be at least twice the petrify duration, so the player always gets a window to move and retaliate, and the factory enforces it with an error that names the cooldown and the minimum. A target without a speed effect component is not affected.

The projectile form (built with a tick count) listens for projectileHit instead, like LightningFreezeComponent. Nothing uses it yet. The movement strategy decides the flight path:

Strategy	Path	Used for
`StraightLineMovementStrategy`	level, left or right	arrows, Medusa's gaze
`AimedLineMovementStrategy`	straight along any direction	aimed arrows, the laser
`VerticalMovementStrategy`	straight down	Zeus's lightning
`ArcMovementStrategy`	a ballistic arc under gravity, aimed at a point	the Cyclops's rock

Adding a new attack

If it is a new kind of ranged attack, subclass RangedAttackComponent, give it its own event prefix, and override createProjectile.
Add its numbers as a config block and read them in the factory.
Add a task with a priority that fits the ranges (see Enemy AI Tasks).
Look the component up by its own class: getComponent(RangedAttackComponent.class) does not find a subclass.

UML

Class diagram of the attack components (melee, ranged, laser, rock, charge, touch, petrify and lightning freeze) and the tasks that drive them.

Attack system class diagram

Enemy Attack System: Testing Plan

Every attack component has its own JUnit test class in components/attacks/. The shared set-up (a physics world, an attacker, a target and a mocked GameTime) is in AttackTestWorld, so time can be advanced one frame at a time.