Helpers

Description

Helpers are functions which contain a series of statements that perform a specific task. These functions are defined once and can then be reused in various formula functions whenever they are required.

Every helper is defined in a separate file, has a unique name, and is located in the helpers directory.

The helpers.lua file contains a list of all helpers and in which order they will be loaded (higher first). The latter is important in cases where one requires another.

Layout

helpers/getCharacterMaxHp.lua

local function getCharacterMaxHp(argument)
  --your code
end

return getCharacterMaxHp

helpers.lua

local helpers = {
  --more helpers
  "getCharacterMaxHp"
}

return helpers

The former file returns a function that performs a specific task.

The latter file returns a table with every helper. The value of a table entry equals the filename of the helper (e.g. getCharacterMaxHp).

Usage

Helpers are very useful when you want to reuse a block of code in various formula functions.

Let's say you wanted to create a formula function that heals the caster based on the amount of max hp they have. For that, you would usually write something like this:

local function func(formula, caster, target, functions, classes, helpers)
  formula.caster.addedHp = caster.maxHp
end

return func

Now the issue with this is that you are not taking the status effects bubble and disease into account. So let's change that.

local function func(formula, caster, target, functions, classes, helpers)
  local maxHp = 0
  if caster.temporaryStatusEffects.disease == 1 or caster.permanentStatusEffects.disease == 1 then
    maxHp = caster.currentHp
    if maxHp < 1 then
      maxHp = 1
    end
  else
    maxHp = caster.maxHp
    if caster.temporaryStatusEffects.bubble == 1 or caster.permanentStatusEffects.bubble == 1 then
      maxHp = maxHp * 2
    end
  end

  formula.caster.addedHp = maxHp
end

return func

As you can see, this required quite a lot more code.

When you want to use a character's max hp, you usually expect it be with the status effects bubble and disease in mind. However, it would be very tiresome to always write this huge block of code every time you need that. That's where helpers come in handy.

So whenever you notice yourself writing the same block of code more than a couple of times, define it as a helper and then call it in a formula function like this:

local function func(formula, caster, target, functions, classes, helpers)
  formula.caster.addedHp = helpers.getCharacterMaxHp(caster)
end

return func

Expansion

You can modify existing helpers created by me and add entirely new ones if you want. I also highly encourage you to do this as it saves time and is less error prone than constantly rewriting the same code. In addition, it also makes your code much more readable, not only for others, but also for you in the future.