Lua Scripts (playing with status effects)

Introduction

Prerequisites: Lua scripts

This page describes how you can retrieve the status effects of characters and enemies and use them in your Lua scripts for an even finer control of the flow of the battles.

Obtaining status effect IDs

Status effect IDs are required to be taken into account in your Lua scripts, as detailed in the following section. To retrieve them conveniently, activate the Listener mode by setting Listener.Enable to true in the ZooeyBot.ini configuration file. With this mode, Zooey will not perform any action and let you play manually. After enabling this mode and starting ZooeyBot.exe, start the Zooey Bot extension.

By clicking on the list of status effects of party members or enemies, as shown here, the list of buffs and debuffs of the selected character or enemy will be displayed in the console, as well as their ID. A summary file named status_effects.txt located in the same folder as ZooeyBot.exe will also log the captured status effects.

Active status effects

It is also possible to access the current list of active buffs and debuffs for each party member. Note that this list is only updated at the beginning of each turn. For instance, if you cast a party buff during turn X, the Lua script won't list this party buff during the turn X. However, if the buff lasts for more than one turn, then it will be available in the Lua script at turn X+1.

To check whether character_1 is under a status effect with ID this_is_a_string_id', use character_1:HasStatusEffect("this_is_a_string_id"). This will return a boolean which you can then use in if conditions. Please note that status effect IDs have to be given as strings. If an effect has ID 123456 and you want to check whether Korwa is under that effect, you have to use the following syntax:

if characters["Korwa"]:HasStatusEffect("123456") then
  ...
end

Please refer to this page a list of IDs of common status effects.

The following paragraphs describe a more advanced feature available with status effect retrieval, with little practical use. Feel free to skip this section.

To access character_1's active buffs, use: character_1.buffs. This attribute is an array of objects and you can iterate over the elements in this array as follows:

for index, buff in pairs(character_1.buffs) do
  if buff.id == XXX then
    ...
  end
  --[[ OR you can also use instead ]]
  if buff.name == XXX then
    ...
  end
  --[[ Retrieving the number of remaining turns (or duration in seconds): ]]
  if buff.remaining_duration == 3 then
    ...
  end
  --[[ To know whether the buff is turn based or time based, use: ]]
  if buff.type == "turn" then
    ...
  end
end

To access character_1's active debuffs, use: character_1.debuffs and refer to the examples given above to iterate over the effect list and access their properties.

The following table lists the properties of status effects you can access in your Lua scripts. For a status effect:

Field	Description
name	will return a Unicode string with the name of the effect
id	integer uniquely identifying the effect
type	string indicating whether the effect is turn-based or time-based
remaining_duration	integer indicating for how long the effect will still be active. Turn-based effects with a duration of 0 last forever.

A text file named status_effects.txt listing the status effect IDs and their corresponding name will be created in the same folder to help you write your Scripts. Note that several status effects can share the same name but have different IDs. It is the case for Korwa Fils for instance, where each Fil effect has a different ID depending on its number of stacks.

If you set the configuration parameter RetrieveStatusEffects under the Combat section to false, you won't be able to access the name, type and remaining duration of the buffs or debuffs of your party members in your scripts (the buff and debuff list for each character will be empty). However, you will still be able to access as usual the IDs of the status effects of your party members.