Skip to content

Lua scripts

Jump to bottom
Masuzu edited this page Sep 20, 2019 · 43 revisions

Scripting Zooey with Lua

You can overwrite the behaviour of Zooey during battles using your own Lua scripts. You can find plenty of Lua tutorials online but all you will need most of the time is conditions using the standard if then else end pattern which exists in several other languages.

Reminder: as already stated in the installation guide, please make sure to encode your file in UTF8, which you can do as follows with Notepad++ for instance:

Demo

Demo 1 - with Viramate

Demo 2 - without Viramate

(You can enable Viramate skill and summon hotkeys with Zooey by setting the paramter UseViramate to true in the ZooeyBot.ini file)

Examples

Please note that these examples are given for a specific party composition and weapon grid. Make sure to test your scripts with your own party and grid!

Referencing characters

You can reference your characters by name using the following syntax characters["Orchid"]. This also works with Unicode characters: you would use characters["オーキス"] if you were using the Japanese language settings. We will use Orchid for illustrative purposes in the other sections below.

You can also reference characters by position: character_1 refers to the character at the first position and character_4 to the one at the fourth position. You can't reference characters in your back row.

Accessing characters data

Field Description
characters["Orchid"].name will return a Unicode string, "Orchid" in this case
characters["Orchid"].skill_1_available true if Orchid's first skill is available, false otherwise
characters["Orchid"].skill_4_available true if Orchid's fourth skill is available, false otherwise
characters["Orchid"].hp current HP of the character (positive integer)
characters["Orchid"].max_hp max HP of the character (positive integer)
characters["Orchid"].hp_percentage remaining HP percentage of the character (positive real between 0 and 100 included)
characters["Orchid"].charge_gauge charge gauge of the character (positive integer)
characters["Orchid"].is_alive true if Orchid is still alive, false otherwise

Active status effects

Please refer to the dedicated documentation page.

Global state of the raid

The current battle/stage index can be accessed via the variable battle: you can use it in multi-stage quests to perform some actions in some stage(s).

The current turn of the current battle can be retrieved via the variable turn. It is an integer starting from 1 and which will be incremented at each turn, or reset when the stage changes or when the battle ends. In multi-stage raids, the integer variable global_turn can be used to get the total number of turns since the _beginning _of the quest. You can use it for instance to keep track of abilities which can only be used after a certain amounts of turn passed.

While your support summons are known for sure when you select your party, the friend summon which is selected before starting each battle may not be fixed. You can use the variable friend_summon_name to get the name of the friend summon which was selected, and friend_summon_evolution to get its evolution level (friend_summon_evolution is an integer X equal to the uncap level of the summon: X stars, 3 for a MLB summon and 4 for a FLB summon).

Using skills

characters["Orchid"]:UseSkill(<skill_index>)/character_2:UseSkill(<skill_index>). The skill index should be an integer number between 1 and 4 included. If you try to use a skill while it is on cooldown, the command will be ignored.

You can also customize the waiting time after using an ability with the following syntax: characters["Orchid"]:WithWaitTime(<wait_time_in_milliseconds>):UseSkill(<skill_index>) Otherwise, Zooey will wait by default for MinWaitTimeInMsAfterAbility after using any ability.

To use a skill targeting a party member, use the following syntax: character_2:OnPartyMember(3):UseSkill(2). This will order the character at position 2 to use his second skill on the party member at position 3. Please note that only skills with a single party member target are supported for now.

To use the special Nighthound Tactical relocation skill, use the following syntax: character_1:OnPartyMembers2(3, 5):UseSkill(2), assuming that you assigned the Tactical relocation skill to the second ability slot of your main character. Please note that this feature is untested for uses other than the Nighthound Tactical relocation skill.

You can also combine custom waiting time and party member targetting as follows: character_2:WithWaitTime(<wait_time_in_milliseconds>):OnPartyMember(3):UseSkill(2) or character_2:OnPartyMember(3):WithWaitTime(<wait_time_in_milliseconds>):UseSkill(2).

Ninja and Runslayer

You can use the Ninja/Runeslayer first ability as follows: character_X:Ninjutsu(<first_rune>, <second_rune>) or character_X:Runeweaving(<first_rune>, <second_rune>), where X is the position in the frontline of the main character. Possible values for runes are FIRE, WATER, EARTH, WIND. For instance, if you are using a Runeslayer: character_1:Runeweaving(FIRE, WATER) would immediately fill the main character's charge gauge when it is used at the start of the battle. Note that using the method Ninjutsu is exactly the same as using the method Runeweaving. You can also combine the calls with WithWaitTime to add override the default delay MinWaitTimeInMsAfterAbility after casting the ability. For instance: character_1:WithWaitTime(3000):Runeweaving(EARTH, EARTH).

Charge attack

You can enable or disable charge attacks using EnableChargeAttack() and DisableChargeAttack().

Using summons

Summon(<summon index as an integer number>). The summon index should be an integer number between 1 and 6 included. If you try to use a summon while it is on cooldown, the command will be ignored.

You can also check whether the summon at position X is available as follows: if summon_X_available (where X is an integer between 1 and 6 included).

Slave mode specific commands

As you will notice, Zooey ends each turn by pressing on the attack button. When you "slime blast" with a sword master, you usually just use your main character first skill and do not attack, as just doing so is enough to clear the stage. In order to reproduce the same thing with Zooey, you can use the command SkipAttack() to avoid pressing the attack button.

Note that if you use SkipAttack at each turn, then your skill won't come off cooldown!

It is also possible to have the slave account play several turns while the main account keeps waiting, and the other way around too. To do so, you can access the current turn of the main account in the script of the slave account with the variable main_account_turn. Conversely, you can access the current turn of the slave account in the script of the main account with the variable slave_account_turn. For instance:

main_account.lua

--[[Wait for the slave account to play 2 turns]]
if slave_account_turn >= 3 then
  DoSomething(...)
else
  SkipAttack
end

slave_account.lua

if turn == 1 then
  DoSomething(...)
end
if turn == 2 then
  DoAnotherThing(...)
end
...

Force Zooey to wait before performing the next action

For now, there is no increased wait time after your party releases a full Ougi chain and after Zooey refreshed the page. You will have to tell Zooey to wait manually, using the following syntax: Wait(X) where X is a positive integer indicating the wait time in milliseconds. Otherwise, Zooey may try to cast some skills and fail repeatedly due to trying to cast them too early after the lockout time following a full Ougi chain release.

An example of such a use can be found here for instance.

Force page refresh

You can force the page to be refreshed with the command Refresh(). This can be useful to gain some precious seconds after using some skills with a long animation.

Please note that if you force a page refresh on a multi-stage quest on one of the stages preceding the final stage and that you cleared this same stage during the same turn, Zooey will be stuck. This will be addressed later on.

Enemy status

You can reference the enemies by position using enemy_1, enemy_2 and enemy_3. If the stage has less than 3 enemies, the missing enemies enemy_X will nil.

Field Description
enemy_1.name will return a Unicode string
enemy_1.hp current HP of the enemy at position 1 (positive integer)
enemy_1.max_hp max HP of the enemy at position 1 (positive integer)
enemy_1.hp_percentage remaining HP percentage of the enemy at position 1 (positive real number between 0 and 100 included)
enemy_1.charge_diamonds charge diamonds of the enemy at position 1 (experimental, returns accurate values only if gravity is used, and number of charge diamonds + 1 otherwise)
enemy_1.is_alive true if the enemy at position 1 is still alive, false otherwise
enemy_1.break_state true if the enemy at position 1 is in break state, false otherwise
enemy_1.overdrive_state true if the enemy at position 1 is in overdrive, false otherwise

Please note that the Break and Overdrive state will be updated accurately only at the last battle stage only if the parameter ReloadPageOnLastBattle is set to true. If at the start of the turn the enemy is not in break state but you happen to use a skill which triggers the break state, break_state will still be false when the condition is evaluated. Indeed, the condition is evaluated only once at the beginning of the turn.

Enemy selection

You can select a specific enemy with the command SelectTarget(1), SelectTarget(2) and SelectTarget(3). If no target is found at the desired position, the command will be ignored.

On stages with 3 enemies, SelectTarget(1) will select the target at the left of the middle one, SelectTarget(3) will select the one in the middle and SelectTarget(2) will select the target at the right of the middle one.

Potions use

You can use green potions on party members with the following syntax: UseGreenPotionOnPartyMember(X) where X is an integer number between 1 and 4 included.

You can also use 1 blue potion with the following syntax: UseBluePotion(). Please note that this feature is only available for multiplayer raid battles and is not available for the slave mode.

If no response is received after MaxResponseTime (when you try to use the potion on a character with full HP for instance), Zooey will automatically close the popup box which is displayed.

Unite and Fight

During Guild War events, you can also use clarity herbs on party members with the following syntax: UseClarityHerbOnPartyMember(X) where X is an integer number between 1 and 4 included.

Last but not least, you can use Support potions (Guild War blue potions, limited to at most 4 per raid) with the following syntax: UseSupportPotion()

Custom user variables

You can define variables for your own use whose lifetime will span the whole duration of the current battle. This means that if you define the variable X on the first turn of the battle, the variable X and any update of this variable which you would have applied in the meantime will persist during the next turns.

Some examples could be: a counter for the number of abilities used, the last turn you used a certain ability, whether you used already a summon.

There are currently 3 different types of variables which are supported:

  • boolean variables (whose values can be either true or false)
  • numbers
  • strings (Unicode characters are also supported by these strings)

To define a boolean variable named "this_is_a_boolean_variable" whose initial value is true, use the following syntax: booleans["this_is_a_boolean_variable"]=true.

To define a "number" variable named "this_is_a_number_variable" whose initial value is 3.14, use the following syntax: numbers["this_is_a_number_variable"]=3.14. You can perform common arithmetic operations on such variables (see this link for more details).

To define a string variable named "this_is_a_string_variable" whose initial value is 3.14, use the following syntax: strings["this_is_a_string_variable"]="ゾーイ".

To delete a variable, say the boolean variable "test" for instance, use the following syntax: booleans["test"]=nil

Here are some example use cases:

Requesting backup

Please note that this feature is experimental and may cause unwanted side effects.

You can request backup for raids which allow to do so with the command RequestBackup().

Support for Viramate skill and summon hotkeys

Should you use Viramate hotkeys, make sure to set the parameter UseViramate to true in the ZooeyBot.ini file.

Check that you enabled Viramate shorcuts too beforehand:

Important final remark

Make sure to configure the delay between skill uses properly not to get any "Failed to parse ability results" warning messages when you use custom Lua scripts, or else status effect updates will be missed, among other things, resulting in unexpected behaviour. Use the WithWaitTime and Wait methods for skills with a long cast time and/or increase the value of the configuration parameter MinWaitTimeInMsAfterAbility under the Combat section of your ZooeyBot.ini configuration file.

Last but not least, boss mode changes, when they enter the overdrive or break state for instance, can also cause a significant delay.

Clone this wiki locally