Ability Framework¶

Ability API Method Reference¶

Method Signature	Return Type	Description
`cast()`	`boolean`	Executes the ability if not on cooldown; returns `true` on success.
`canCast()`	`boolean`	Checks if the ability is off cooldown and executor has required resources.
`getRemainingCooldown()`	`int`	Returns remaining cooldown duration in milliseconds.
`getExecutor()`	`Creature`	Returns the entity executing the ability.
`getAttributes()`	`AbilityAttributes`	Returns configured cooldown, range, and impact duration attributes.
`addEffect(IEffect effect)`	`void`	Attaches a modular status or damage effect applied on impact.

The Ability Framework provides a structured way to implement combat abilities, spells, and special actions. It handles cooldowns, execution timing, and applying effects to targets.

Basic Ability¶

@AbilityInfo(cooldown = 500, duration = 300, value = 240)
public class Jump extends Ability {

  public Jump(Creature executor) {
    super(executor);
    this.addEffect(new JumpEffect(this));
  }
}

AbilityInfo Annotation¶

Configure ability properties:

@AbilityInfo(
cooldown = 1000, // Milliseconds between uses
duration = 500, // How long ability executes
value = 100, // Custom value (damage, etc.)
origin = EntityPivotType.CENTER, // Where ability originates
range = 200, // Maximum range
multiTarget = false // Can hit multiple targets
)
public class Fireball extends Ability {
  // ...
}

Using Abilities¶

Creature creature = ...;
Jump jumpAbility = new Jump(creature);

// Check if ability can be cast
if (jumpAbility.canCast()) {
  jumpAbility.cast();
}

// Check if currently executing
if (jumpAbility.isExecuting()) {
  // Ability in progress
}

Ability Effects¶

Effects are applied when an ability executes:

public class JumpEffect extends ForceEffect {

  public JumpEffect(Ability ability) {
    super(ability, ability.getAttributes().value().get(), EffectTarget.EXECUTINGENTITY);
  }

  @Override
  protected Force applyForce(IMobileEntity entity) {
    GravityForce force = new GravityForce(entity, getStrength(), Direction.UP);
    entity.movement().apply(force);
    return force;
  }

  @Override
  protected boolean hasEnded(EffectApplication appliance) {
    return super.hasEnded(appliance) || isTouchingCeiling();
  }
}

Effect Targets¶

Define who receives the effect:

// Affect the entity using the ability
EffectTarget.EXECUTINGENTITY

// Affect enemies
EffectTarget.ENEMY

// Affect all entities in range
EffectTarget.ALL

Damage Abilities¶

Create combat abilities that deal damage:

public class SwordSlash extends Ability {

  public SwordSlash(Creature executor) {
    super(executor);
    this.addEffect(new DamageEffect(this));
  }
}

public class DamageEffect extends Effect {

  public DamageEffect(Ability ability) {
    super(ability, EffectTarget.ENEMY);
  }

  @Override
  public void apply(IEntity entity) {
    if (entity instanceof ICombatEntity) {
      ICombatEntity target = (ICombatEntity) entity;
      int damage = getAbility().getAttributes().value().get();
      target.hit(damage);
    }
  }
}

Ability Events¶

ability.onCast(event -> {
  System.out.println("Ability cast!");
});

ability.onFinished(event -> {
  System.out.println("Ability finished!");
});

Cooldown Management¶

// Get remaining cooldown
float remaining = ability.getRemainingCooldownInSeconds();

// Check if ready
boolean ready = ability.canCast();

// Reset cooldown
ability.reset();

Entity Actions¶

Mark methods as invokable abilities:

public class Player extends Creature {

  @Action(description = "Perform a jump")
  public void jump() {
    if (jumpAbility.canCast()) {
      jumpAbility.cast();
    }
  }

  @Action(description = "Attack with sword")
  public void attack() {
    // Perform attack
  }
}

// Invoke by name
player.perform("jump");
player.perform("attack");