Tutorial: New Ability

This tutorial will show you how to add a new ability to the mod. The ability in this example will be a Firebending ability that lights the targeted mob on fire.

Basic Setup

To make the new ability, extend the Ability class. You need to call the super constructor, which takes the name of the ability as well as its bending controller. The name of the ability will be “immolate”, and the name of the bending controller is “firebending”.

Also, the abstract methods execute and getChiCost need to be implemented - leave them blank and fill them in later.

public class AbilityImmolate extends Ability

Simply creating a class isn’t enough, though - you’ll need to register the ability to the ability registry so it’s added to the game. In AvatarMod#registerAbilities(), call Abilities#register with a new instance of your ability (abilities are singletons).

Note

If you’re developing an add-on, call these methods in your main mod class’s postInit method. If your main mod class doesn’t have a postInit, just add one which has the method header @EventHandler public void postInit(FMLPostInitializationEvent e). FML will automatically call it, similar to how preInit is called.

The ability is now registered and visible in the Firebending radial menu.

Execute method

Now, it’s time to fill in the execute method. It is called whenever the ability is used, only on the server side. This is where you define the ability’s functionality.

This ability will light the targeted entity on fire. The basic logic flow will be to use a raytrace to find the targeted mob and then set it on fire.

Here is an example implementation of that ability.

@Override
public void execute(AbilityContext ctx) {
  final double range = 5;
  final float fireSeconds = 4;

  World world = ctx.getWorld();
  EntityLivingBase entity = ctx.getBenderEntity();

  Vector start = Vector.getEyePos(entity);
  Vector dir = Vector.getLookRectangular(entity);
  List<Entity> raytrace = Raytrace.entityRaytrace(world, start, dir, range);

  // only immolate 1 entity
  if (!raytrace.isEmpty()) {
    raytrace.get(0).setFire(fireSeconds);
  }

}

Here are links to detailed docs on each class used:

• AbilityContext
• Vector
• Raytrace

Improving the implementation

Although the ability works, there are still a lot of missing features common to other abilities. The ability doesn’t require chi, so can be spammed continuously. It ignores experience and level 4 options, and therefore has no progression. Fortunately, adding these features are pretty simple.

Applying Xp cost is super easy. Just override the super method getChiCost() and return the correct amount of chi. To require more chi under other conditions (such as air bubbles consuming chi each second), see Bender#consumeChi.

Adding experience only requires a few method calls, but knowledge of the ability data class is necessary. An instance of ability data can be obtained through AbilityContext#getAbilityData(). Simply adjusting the numbers can be sufficent:

@Override
public void execute(AbilityContext ctx) {
  AbilityData abilityData = ctx.getAbilityData();
  double range = 3 + abilityData.getLevel() * 0.5;
  float fireSeconds = 2 + abilityData.getLevel();

  if (abilityData.isMasterPath(AbilityTreePath.FIRST)) {
    range = 8;
    fireSeconds = 3;
  }
  if (abilityData.isMasterPath(AbilityTreePath.SECOND)) {
    range = 3;
    fireSeconds = 7;
  }

  // etc...
}

To award Xp, just call abilityData.addXp when appropriate.

Localization

For this ability, the following translations will be necessary:

• Name of the ability: avatar.ability.immolate
• Description of the ability: avatar.ability.immolate.desc
• Description of each level upgrade: avatar.ability.immolate.lvlX (see below)

For levels the following levels are used:

• lvl1 - level I
• lvl2 - level II
• lvl3 - level III
• lvl4_1 - level IV, first path
• lvl4_2 - level IV, second path

Simply add the keys to en_US.lang, for example:

Icon

There are a few icons needed, one for radial menu, one for the skills menu card, and one for the skills menu background.

For the radial menu icon, use a 256x256 image and name it icon_immolate.png. Place it in the textures/radial folder of the assets.

For the skill menu card and skill menu background, don’t bother because by the time someone else is reading this article, I’ll have scrapped that approach as EduMC can’t make skill menu pictures anymore.

AI

The ability is almost all set up - functionality, UI, translations... The only thing left is an Ai module, which tells bending mobs how to use this ability (this part is optional if bending mobs shouldn’t use the ability).

For starters, override the method getAi, and see the AiWaterArc class for an example. Bending Ai is not covered in this tutorial; detailed documentation is available here.