Battle

Advances all enemy dialogue bubbles

Applies equipment modifiers to the heal amount from a healing action performed by the specified party member.

Returns the equipment-modified money amount from a battle victory payout.

Sets the current message in the battlebox and moves to the BATTLETEXT state until it is advanced, where it returns to the previous state by default

Checks the current state on a state change. If waves shouldn't be active, stop them.

old:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

new:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

Checks to see whether the whole party is downed and starts a GameOver if they are

Returns whether collider collides with a Solid or the arena

Darken the battle background & party members.

Forcibly end the wave.

This should not be called in place of normal wave ending via time or enemy defeat.

This ends up entering the DEFENDINGEND state.

Gets a list of all the active (not defeated/spared) enemies

Gets a list of all the active (not downed) party members

Returns the tension gained from defending. By default, this redirects to Encounter.

A simple redirect to the Encounter's getEncounterText.
Here for encapsulation and hooking, if you need more complex behavior.

Gets an EnemyBattler in the current battle from their id

Gets an enemy in battle from their corresponding world Character

A simple redirect to the Encounter's getInitialEncounterText.
Here for encapsulation and hooking, if you need more complex behavior.

Gets a PartyBattler in the current battle from their id

Gets the index of a party member with the given id

Gets the location the soul should spawn at when waves start by default

Returns the current state of the battle.

return #1:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

Returns the current substate of the battle.

Gets whether a specific character has an action lined up

Checks if the current encounter has reduced tension. By default, this redirects to Encounter

Hide the target indicators on all party members.

Hurts the target party member(s)

--  `PartyBattler`s are a type of `Battler` that represent [`PartyMember`](file:///srv/shadow/tmp/kristal/src/engine/game/common/data/partymember.lua#73)s when they are in battle. \
--  The set of `PartyBattler`s in the current battle are stored in [`Game.battle.party`](file:///srv/shadow/tmp/kristal/src/engine/game/battle.lua#6). \
--  Unlike `EnemyBattler`, party members do not need to define a `PartyBattler` in a file as their PartyMember file defines everything necessary and is utilised by `PartyBattler`.
-- 
target:
    | "ALL"
    | "ANY"

Sets the current message in the battlebox - this text can not be advanced, only overwritten if another text is set

Responsible for actually ending the waves.

This removes the arena, returns the soul, ends all of the waves, and moves to the next turn if specified.

This should NOT be called by user code; instead, use Battle:endWaves() to end the waves if an immediate end is needed.

Advances to the next turn of the battle

Called when the BattleState is set to ACTIONSELECT.

Called when the BattleState is changed to ACTIONS.

Called when the BattleState is changed to BATTLETEXT.

Called when the BattleState is changed to DEFENDINGBEGIN.

Called when the BattleState is changed to DEFENDINGEND.

Called when the BattleState is changed to DEFENDING.

Called when the BattleState is changed to DIALOGUEEND.

Called when the BattleState is changed to ENEMYDIALOGUE.

Called when the BattleState is changed to ENEMYSELECT.

Called when the BattleState is set to INTRO.

Called when the BattleState is changed to MENUSELECT.

Called when the BattleState is changed to PARTYSELECT.

Called when the BattleState is changed via Battle:setState().

old:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

new:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

Called when the BattleState is changed to TRANSITIONOUT.

Called when the BattleState is changed to VICTORY.

Turns a party member's turn from an ACT into a SPELL cast
Should be called from inside EnemyBattler:onAct()

--  `PartyBattler`s are a type of `Battler` that represent [`PartyMember`](file:///srv/shadow/tmp/kristal/src/engine/game/common/data/partymember.lua#73)s when they are in battle. \
--  The set of `PartyBattler`s in the current battle are stored in [`Game.battle.party`](file:///srv/shadow/tmp/kristal/src/engine/game/battle.lua#6). \
--  Unlike `EnemyBattler`, party members do not need to define a `PartyBattler` in a file as their PartyMember file defines everything necessary and is utilised by `PartyBattler`.
-- 
return #1:
    | "ANY"

--  `PartyBattler`s are a type of `Battler` that represent [`PartyMember`](file:///srv/shadow/tmp/kristal/src/engine/game/common/data/partymember.lua#73)s when they are in battle. \
--  The set of `PartyBattler`s in the current battle are stored in [`Game.battle.party`](file:///srv/shadow/tmp/kristal/src/engine/game/battle.lua#6). \
--  Unlike `EnemyBattler`, party members do not need to define a `PartyBattler` in a file as their PartyMember file defines everything necessary and is utilised by `PartyBattler`.
-- 
return #1:
    | "ALL"

Registers an additional X-Action for a specific party member

Remove a party member's action from the list of actions.

Removes an enemy from the battle

Removes a single action from the list of actions.

Resets the enemies index table, closing all gaps in the enemy select menu

Ends the battle and removes itself from Game.battle

Changes the state of the battle and calls onStateChange()

state:
    | "NONE" -- An empty state which does nothing.
    | "TRANSITION" -- The state used when first entering a battle.
    | "INTRO" -- The state used after TRANSITION, where the battle intro animation plays.
    | "ACTIONSELECT" -- The state for letting the user choose actions.
    | "MENUSELECT" -- The state used when selecting an action from the menu.
    | "ENEMYSELECT" -- The state used when selecting an enemy target.
    | "PARTYSELECT" -- The state used when selecting a party member.
    | "ACTIONS" -- The state used when processing actions. Most of the time, other states will be used instead.
    | "ACTING" -- The state used when party members act.
    | "BATTLETEXT" -- A generic "writing text" state.
    | "SHORTACTTEXT" -- The state used when multiple lines of text are being written out at once, for "short acts".
    | "ATTACKING" -- The state used while party members are attacking.
    | "SPARING" -- The state used when party members spare.
    | "USINGITEMS" -- The state used when party members use items.
    | "ACTIONSDONE" -- The state used when all "actions" are done.
    | "ENEMYDIALOGUE" -- The state used when enemies are displaying dialogue.
    | "DIALOGUEEND" -- The state used after enemy dialogue ends.
    | "DEFENDINGBEGIN" -- The state used before defending begins.
    | "DEFENDING" -- The state used when the player is defending against enemy waves.
    | "DEFENDINGEND" -- The state used after defending ends.
    | "VICTORY" -- The state used when the player has won the battle.
    | "TRANSITIONOUT" -- The state used when transitioning out of battle.
    | "CUTSCENE" -- The state used when a battle cutscene is active.

Changes the substate of the battle and calls onSubStateChange()

Sets the waves table to what is specified by waves

Shakes the camera by the specified x, y.

Whether the battle should decrease the invulnerability timer.

By default, this redirects to Encounter:shouldDecreaseInvuln().

Show the target indicators on all currently targeted party members.

Spawns the soul and sets up its transition from the source character to its starting position

Starts a cutscene in battle where the cutscene receives the the currently ACTing character and the ACT's target as additional arguments \

Starts a cutscene in battle
When setting a cutscene during the ACTIONS state, see `Battle:startActCutscene() instead

Replaces the current soul (if it exists) with a different soul instance

--  `PartyBattler`s are a type of `Battler` that represent [`PartyMember`](file:///srv/shadow/tmp/kristal/src/engine/game/common/data/partymember.lua#73)s when they are in battle. \
--  The set of `PartyBattler`s in the current battle are stored in [`Game.battle.party`](file:///srv/shadow/tmp/kristal/src/engine/game/battle.lua#6). \
--  Unlike `EnemyBattler`, party members do not need to define a `PartyBattler` in a file as their PartyMember file defines everything necessary and is utilised by `PartyBattler`.
-- 
return #1:
    | "ALL"
    | "ANY"

return #1:
    | "ALL"

return #1:
    | "ANY"

Undarken the battle background & any party members which were darkened.

The current Arena instance, if any

The BattleBackground, if any

Target positions for PartyBattlers to transition to at the start of battle

The active battle cutscene, if it exists - see Battle:startCutscene() or Battle:startActCutscene() for how to start cutscenes

The BattleDarkener, if any

The encounter currently being used for this battle (only set during postInit())

An optional ChaserEnemy instance that initiated the battle

EnemyBattlers are a type of Battler that represent enemies, defining all their properties and behaviours.
Every enemy defined in a project should be located in its own file in scripts/battle/enemies/, and should extend this class.
Each enemy is assigned an id that defaults to their filepath starting from scripts/battle/enemies, unless an id is specified as an argument to Class().
Enemies are added to battles in the encounter, with Encounter:addEnemy(enemy, x, y, ...), where enemy is their unique id, and all enemies for the current battle reside in Game.battle.enemies

Recruit data is separate to enemies, see Recruit for how to set up a corresponding recruit.

The position of each EnemyBattler at the start of the battle transition

A list of mappings between EnemyBattlers and their representations as Characters in the world, if they exist

Objects parented to this will be masked to the arena

Current amount of victory money

The battle music

A table of all the PartyBattlers in the current battle

The position of each PartyBattler at the start of the battle transition

A list of mappings between PartyBattlers (by id) and their representations as Characters in the world, if they exist

(only set during postInit())

The current Soul instance, if any

A sound source for the spare sfx, should be used for every time this sound plays in battle

The current state of the battle - should never be set manually, see Battle:setState() instead

The reason for the current state of the battle - should never be set manually, see Battle:setState() instead

The current substate of the battle - should never be set manually, see Battle:setSubState() instead

The bar you see on the left of the battle UI.

This is simply a display for tension, but not where tension itself is stored.

Does not depend on battle.

A generic timer object for the battle system

Whether the battle opened with a transition (only set during postInit())

The current turn number

A sound source for the ui_move sfx, should be used for every time this sound plays in battle

A sound source for the ui_select sfx, should be used for every time this sound plays in battle

Whether any enemy was defeated through violence or not

Current amount of victory xp