Skip to content

Features

Jump to bottom
MrOinky edited this page Dec 28, 2022 · 4 revisions

Features

Pie adds a variety of new features to items in Kristal, spanning both the Item and HealItem classes. The built in features for Pie aim to expand the capabilities of items to make them more flexible. All features' behaviour are defined by new values added to these classes. See below for a list of features and how to control them.

Controlling Features

All features can be controlled through two methods:

  • Setting new variables inside of item:init()
  • Overriding get functions in the item object. Inside of the item file, these methods would look similar to the code blocks below:
-- Excepts of stained_apron.lua from the example library.
-- Here, passive healing is set up by setting variables inside of `item:init()`.

local item, super = Class(Item)

function item:init()
    super:init(self)
    -- Normal item definitions go here

    -- Here, the variables for this item's passive healing are set.
    self.passive_heal = true

    self.passive_heal_amount = 20
    self.passive_heal_frequency = 2
end

return item
-- Excerpts of jelly_boots.lua from the example library.
-- Here, passive healing is set up by overriding the default getter functions of this item.

local item, super = Class(Item)

function item:init()
    super:init(self)
    -- Normal item definitions go here
end

-- Below, the getter functions are overriden to return the values for passive healing.

-- Sidenote: getters for booleans are prefixed 'does', but serve the same purpose.
function item:doesPassiveHeal(chara)
    return true
end

-- Getter functions reveal the chara instance of the item holder, perfect for creating character-specific behaviour!
function item:getPassiveHealAmount(chara)
    -- Heals 1/10th of the holder's max hp.
    return chara:getStat("health") / 10
end

function item:getPassiveHealFrequency(chara)
    return 1
end

return item

When retrieving a defined value for an item, always use the get function and never the variable - if the associated get is not overriden, the default function will return the variable anyway, but the variable will not update to reflect the output of the get function if overriden. As such, these variables should only be referenced when defining them, and getters should always be used to retrieve their values.

List of Features

Currently, Pie supports the following new features:

Passive Healing (Item - Equipment)

Passive Healing in Pie does exactly what the name suggests - it heals a battler by a certain amount every given number of turns. This can also optionally deduct tension as a cost for healing the battler. If the party tension is lower than the Tension cost, the battler will not be healed, and tension will not be withdrawn. Additionally, if the battler has maximum health, they will not receive healing, and tension will not be withdrawn.

Passive Healing can be added to equipment and its behaviour controlled by the following variables and getters:

  • passive_heal (boolean): Whether the item can conduct passive healing. false by default.
  • doesPassiveHeal(chara) (boolean): Returns a boolean representing whether the item can conduct passive healing or not. Returns passive_heal by default.
  • passive_heal_amount (integer): The amount of health restored by this item.
  • getPassiveHealAmount(chara) (integer): Returns the amount of health restored by this item. By default, passive_heal_amount is returned.
  • passive_heal_cost (integer): The tension cost of passive healing for this item.
  • getPassiveHealCost(chara) (integer): Returns the tension cost of passive healing for this item. By default, passive_heal_cost is returned.
  • passive_heal_frequency (integer): The number of turns between heals, with 1 healing every turn. 1 by default.
  • getPassiveHealFrequency(chara) (integer): Returns the number of turns between heals, with 1 healing every turn. Returns passive_heal_frequency by default.

Passive Tension Regeneration (Item - Equipment)

Passive Tension Regeneration behaves in the same way as Passive Healing, but tension and health have their roles reversed - tension is restored and health is used as the cost (if one exists) and, likewise, if not enough health is present, tension will not be restored, or if tension is full, no health will be withdrawn.

Passive Tension Regeneration can be added to equipment and its behaviour controlled by the following variables and getters:

  • passive_tension (boolean): Whether the item can conduct passive tension restoration. false by default.
  • doesPassiveTension(chara) (boolean): Returns a boolean representing whether the item can conduct passive tension restoration or not. Returns passive_tension by default.
  • passive_tension_amount (integer): The amount of tension restored by this item.
  • getPassiveTensionAmount(chara) (integer): Returns the amount of tension restored by this item. By default, passive_tension_amount is returned.
  • passive_tension_cost (integer): The health cost of passive tension regeneration for this item.
  • getPassiveTensionCost(chara) (integer): Returns the health cost of passive tension restoration for this item. By default, passive_tension_cost is returned.
  • passive_tension_frequency (integer): The number of turns between tension restores, with 1 triggering every turn. 1 by default.
  • getPassiveTensionFrequency(chara) (integer): Returns the number of turns between tension restores, with 1 triggering every turn. Returns passive_tension_frequency by default.

Passive Item Generation (Item - Equipment)

Passive item generation takes a slightly more abstract principle than other passive effects - rather than healing or restoring tension, it instead focuses on granting items to the party. As with the other passive effects, it still follows the same set of rules, and can charge both health and tension to grant items.

Passive Item Generation can be implemented and controlled on equipment by using the following variables and getters:

  • passive_item (boolean): Whether this item can passively grant other items to the party. false by default.
  • doesPassiveItem(chara) (boolean): Returns whether this item can passively grant other items to the party. By default, this is set to return passive_item.
  • passive_item_name (string): The name of the passive item to be given to the party. Must be able to go into the items storage.
  • getPassiveItemName(chara) (string): Returns the name of the passive item to be given to the party. By default, this is set to return passive_item_name.
  • passive_item_tensioncost (integer): The amount of tension withdrawn when given this item.
  • getPassiveItemTensionCost(chara) _(integer)_: Returns the amount of tension withdrawn when given this item. By default, this is set to return passive_item_tensioncost`.
  • passive_item_healthcost (integer): The amount of health deducted upon giving this item.
  • getPassiveItemHealthCost(chara) _(integer)_: Returns the amount of health dedcuted upon giving this item. By default, this is set to return passive_item_healthcost`.
  • passive_item_frequency (integer): The number of turns between each item being generated, with 1 being every turn. 1 by default.
  • getPassiveItemFrequency(chara) _(integer)_: Returns the number of turns between each item being generated. By default, this is set to return passive_item_frequency`.

Passive Damage (Item - Equipment)

Passive damage is another of the passive effects available, functioning as the inverse of healing; Unsurprisingly, passive damage deals damage to the holder of the item over time, however, unlike the main trio of passive effects, this one has no settable cost (because who would want to pay to be hurt?) as well as being able to kill the holder if they are hurt too much.

Note: this can not be used to replicate a Thorn Ring-styled health sapping effect.

Passive Damage can be added to equipment and controlled using the following variables and getters:

  • passive_hurt (boolean): Whether the item can inflict passive damage. false by default.
  • doesPassiveHurt(chara) (boolean): Returns a boolean representing whether the item can inflict passive damage or not. Returns passive_hurt by default.
  • passive_hurt_amount (integer): The amount of damage inflicted by this item.
  • getPassiveHurtAmount(chara) (integer): Returns the amount of damage inflicted by this item. By default, passive_hurt_amount is returned.
  • passive_hurt_frequency (integer): The number of turns between each hit, with 1 hitting every turn. 1 by default.
  • getPassiveHurtFrequency(chara) (integer): Returns the number of turns between hits, with 1 hitting every turn. Returns passive_hurt_frequency by default.

Healing Boost (Item - Equipment) (Updated in v1.1.0)

Healing boosts are a bonus applicable to equipment that increases how effective HealItem healing is, functioning alike the Burnt Pan from UNDERTALE. Heal bonuses can also be multiplicative, specifying a factor to multiply by, which takes priority over additive bonuses if set.

The following variables and getters can be used to give items Healing Boosts:

  • heal_bonus (integer): The amount of bonus health restored when the holder of this item uses a HealItem.
  • heal_bonuses (table): A table that specifies the amount of bonus health restored when the holder of this item uses a HealItem with a specific id. Each key, value pair should be an item id and an integer for the heal bonus.
  • getHealBonus(chara, item) (integer): Returns the amount of bonus health restored when the holder of this item uses a HealItem. By default, this returns heal_bonuses[item.id] or heal_bonus if it is not set.
  • multiplicative_heal_bonus (float): The factor to multiply item healing by when the holder of this item uses a HealItem.
  • multiplicative_heal_bonuses (table): A table of factors to multiply item healing by for specific HealItem ids. Each key, value pair should be an item id and a float for the multiplication factor.
  • getMutliplicativeHealBonus(chara, item) (float): Returns the multiplication factor for healing when the holder of this item uses a HealItem. By default, this returns multiplicative_heal_bonuses[item.id] or multiplicative_heal_bonus if it is not set.
  • block_heal_bonus (boolean): Settable on any HealItem. If true, its healing cannot be affected by heal bonuses.

Victory Healing (Item - Equipment)

Victory healing is a bonus applicable to equipment that restores health to the wearer when the battle ends.

The following variables and getters can be used to give items Victory Healing:

  • victory_heal (integer): The amount of health restored at the end of battle.
  • getVictoryHealAmount(chara) (integer): Returns the amount of health restored at the end of battle. By default, this will return victory_heal.

Starting Tension (Item - Equipment) (New in v1.1.1)

Starting tension is a bonus applicable to equipment that gives the party tension at the start of battle.

The following variables and getters can be used to give items Starting Tension:

  • starting_tension (integer): The amount of tension granted at the start of battle.
  • getStartingTensionAmount(chara) (integer): Returns the amount of tension granted at the start of battle. By default, this will return starting_tension.

Future Heals (HealItem)

Future Heals are a new method of healing for any HealItem, usable in conjunction with normal healing, or on its own.

The following variables and getters can be used to give healing items Future Healing:

  • future_heal_amount (integer): The amount of health restored through future healing.
  • future_heal_turns (integer): The amount of turns the future healing will take place in.
  • getFutureHealAmount(chara) (integer): Returns the amount of health restored through future healing. By default, this will return future_heal_amount.
  • getFutureHealTurns(chara) (integer): Returns the number of turns before future healing will occur for this item. By default, this will return future_heal_turns.

Attack Dodging (Item - Equipment) (New in v1.1.0)

Attack Dodging allows equipment to have a dodge chance, allowing an item holder to completely negate an entire hit of damage.

The following variables and getters can be used to give items Attack Dodging:

  • dodge_chance (float): A value between 0 and 1 that determines the chance of a dodge being triggered.
  • getBaseDodgeChance(chara) (float): Returns a value between 0 and 1 that determines the chance of a dodge being triggered. Returns dodge_chance by default.
  • dodge_defend_bonus (float): A value between 0 and 1 that is added to dodge_chance whilst defending.
  • getDodgeDefendBonus(chara) (float): Returns a value between 0 and 1 that determines the bonus dodge chance whilst defending. Returns dodge_defend_bonus by default.
  • `getDodgeChance(chara, defending) (float): Returns a value between 0 and 1 representing the dodge chance for this item, combining both the dodge chance and bonus (if it should apply).
  • dodge_color (table): A table of floats that represent the RGB color of the "miss" text to display on a successful dodge.
  • getDodgeColor(chara) (table): Returns a table of floats that represent the RGB color of the "miss" text to display on a successful dodge. Returns dodge_color by default.
  • dodge_sound (string): A string referencing the name of the sound to play upon a successful dodge. Set to "none" for no sound, defaults to "mus_sfx_a_pullback" (Asriel's sword pullback sfx from Undertale).
  • getDodgeSound(chara) _(string)_: Returns a string referencing the name of the sound to play on a successful dodge. Returns dodge_sound` by default.

Thorns (Item - Equipment) (New in v1.1.0)

Thorns allows equipment to have a chance to hurt an enemy for a proportion of the damage dealt to the holder of the item.

The following variables and getters can be used to give items Thorns:

  • thorns_chance (float): A value between 0 and 1 that determines the chance of thorns being triggered.
  • getBaseThornsChance(chara) (float): Returns a value between 0 and 1 that determines the chance of thorns being triggered. Returns thorns_chance by default.
  • thorns_defend_bonus (float): A value between 0 and 1 that is added to thorns_chance whilst defending.
  • getThornsDefendBonus(chara) (float): Returns a value between 0 and 1 that determines the bonus dodge chance whilst defending. Returns dodge_defend_bonus by default.
  • `getThornsChance(chara, defending) (float): Returns a value between 0 and 1 representing the thorns chance for this item, combining both the thorns chance and bonus (if it should apply).
  • thorns_damage_proportion (float): A value between 0 and 1 that reflects the proportion of damage that should be dealt to an enemy.
  • getThornsDamageProportion(chara) _(float)_: Returns a value between 0 and 1 that reflects the proportion of damage that should be dealt to an enemy. Returns thorns_damage_proportion` by default.
  • thorns_sound (string): A string referencing the name of the sound to play upon thorns. Set to "none" for no sound, defaults to "screenshake".
  • getDodgeSound(chara) _(string)_: Returns a string referencing the name of the sound to play on successful thorns. Returns thorns_sound` by default.

Attack Reflecting (Item - Equipment) (New in v1.1.0)

Attack reflecting allows equipment to have a chance to reflect a proportion of damage to its holder back at an enemy.

The following variables and getters can be used to give items Attack Reflecting:

  • reflect_chance (float): A value between 0 and 1 that determines the chance of reflection being triggered.
  • getBaseReflectChance(chara) (float): Returns a value between 0 and 1 that determines the chance of reflection being triggered. Returns reflect_chance by default.
  • reflect_defend_bonus (float): A value between 0 and 1 that is added to reflect_chance whilst defending.
  • getReflectDefendBonus(chara) (float): Returns a value between 0 and 1 that determines the bonus dodge chance whilst defending. Returns reflect_defend_bonus by default.
  • `getReflectChance(chara, defending) (float): Returns a value between 0 and 1 representing the reflection chance for this item, combining both the reflect chance and bonus (if it should apply).
  • reflect_damage_proportion (float): A value between 0 and 1 that represents the proportion of damage that should be reflected to an enemy.
  • getReflectDamageProportion(chara) _(float)_: Returns a value between 0 and 1 that represents the proportion of damage that should be reflected to an enemy. Returns reflect_damage_proportion` by default.
  • reflect_sound (string): A string referencing the name of the sound to play upon attack reflection. Set to "none" for no sound, defaults to "bell_bounce_short".
  • getReflectSound(chara) _(string)_: Returns a string referencing the name of the sound to play on successful reflection. Returns reflect_sound` by default.

Config Options (New in v1.1.0)

Pie includes some config options visible inside of lib.json that can be overriden inside mod.json to alter library behaviour.

alwaysDoHealItemHealing (boolean): When true, HealItems will always call heal(), even if they would restore 0 hp (standard Kristal behaviour). When false, they will not call heal() and therefore will not produce the healing effect. false by default.

alwaysApplyHealBonus (boolean): When true, heal bonuses will always apply to items, even if they originally healed nothing. Otherwise, bonuses will not apply to items with 0 hp of healing. false by default.

passiveHurtCanKill (boolean): When true, passive hurt items can knock down battlers through their damage. true by default.

passiveEffectCostCanKill (boolean): When true, passive item effects with a hp cost can knock down battlers with hp damage. false by default.

Bonuses

The implementation of some of the above features has also resulted in new functionality for some other parts of Kristal. Although not technically primary features of this library, they can be used by any part of a mod as they are necessary. These features are as follows:

Future Heals Everywhere

PartyMember:futureHeal(amount, turns) - Used internally by Future Heal items, this function can be called from any PartyMember whilst in battle to create a new future heal.

  • amount (integer): The amount of health to restore.
  • turns (integer): The number of turns to restore health in.

self.future_heals (PartyMember) - A table of all pending future heals. Just like PartyMember:futureHeal(), it is used internally for Future Heal items.

Encounter Turn Tracker

This does only take about 5 seconds to manually implement, but a feature is a feature either way!

  • turn (Encounter) - Reflects the current turn of the battle. Starts at 1, and is increased in Encounter:onTurnEnd().

Note: If Pie behaves strangely or causes unexpected interactions inside a mod, it may be a result of several instances of turn being incremented in the Encounter object. If this is the case, all other instances of turn being set/modified should be removed.

PartyMember Heal Bonuses

Heal bonuses are managed by the PartyMember performing the healing, given that they are holding all the items that should apply their bonuses. As a little bonus, this allows for extending PartyMember:applyHealBonus() to make a PartyMember have bonus healing independent of items.

This can be achieved with code such as:

local PartyMember, super = Class(PartyMember)

function PartyMember:applyHealBonus(amount, item)
    -- Call super:applyHealBonus() to apply all of the item bonuses first.
    local new_amount = super:applyHealBonus(self, amount, item)
    -- Add 10 bonus HP to all healing done by this PartyMember.
    new_amount = new_amount + 10

    -- Return the final amount.
    return new_amount
end

return PartyMember

Clone this wiki locally