Encounters

Relevant files: encounter.lua, battle.lua

Making an Encounter

Encounters are what the game uses to create battles against enemies. They contain information about what enemies are present, what the environment is like (background, music, etc), and so on. Encounter files should go in scripts/battle/encounters.

Encounter files can be made by extending the global Encounter class. A basic encounter looks something like this:

local EncounterName, super = Class(Encounter)

function EncounterName:init() -- does not take arguments
  -- needs to be the first line, otherwise values you set
  -- will be changed back to default by this
  super:init(self)

  self:addEnemy("enemyName", 500, 200)

  -- define the rest of the default variables (listed below)
end

-- remember to return the class at the end
return EncounterName

The following variables and functions can be used to set information for the encounter. Since Encounter is not an object, this means that it does not have any default object variables; as such, any variables or functions that are not defined here do not exist (or are irrelevant to making a mod).

text: The message that first appears when you enter the battle.
background: Whether the game draws the default background. True by default. If the battle is entered through the overworld, and this is false, then the overworld room will be displayed.
hide_world: If true, then the overworld room will not be displayed in battle, even if background is false. True by default, if background is true.
music: File path for the encounter's music, relative to assets/music.
default_xactions: Determines whether the battle has X-Actions enabled. True by default.
no_end_message: If true, the encounter will not display the victory message when the battle is won.
addEnemy(enemy, x, y): Adds an enemy to the battle at the x and y positions. enemy is a string referring to the file name of an enemy file (see Enemies for more detail).

Additionally, the following functions can be overridden (though it is not necessary to do so for an encounter to work):

onBattleStart(): Called when the battle first starts.
onBattleEnd(): Called when the battle ends.
onTurnStart(): Called when the battle turn starts, when the player can select actions.
onTurnEnd(): Called when the battle turn ends, when the player is about to select actions, after waves.
update(): Called every frame.
drawBackground(fade): Called every frame, before anything has rendered. fade is a value between 0 and 1, representing the opacity of the background as it fades in from the overworld.
draw(fade): Called every frame, after everything else has rendered. fade is a value between 0 and 1, equivalent to the opacity of the background.
getEncounterText(): Returns a string to set the encounter message as at the start of a turn. By default, this function randomly selects an enemy from the encounter and returns the result of their getEncounterText().
getDialogueCutscene(): If this function returns arguments, start a battle cutscene with those arguments instead of displaying enemy dialogue like normal. When the cutscene ends, the battle automatically moves on to the waves state. See Starting Cutscenes for more detail.
getNextWaves(): Returns a table of strings referring to wave IDs. By default, this function calls selectWave() for each enemy, and returns a table of all results returned. selectWave() must be called on at least one enemy for waves to work properly; see Waves for more detail.
onDialogueEnd(): Called after enemy dialogue finishes. Responsible for creating and starting the next wave, and setting the battle state to DEFENDING (see Battle States below for more detail).
onWavesDone(): Called when a wave finishes. Responsible for ending the wave and starting the next turn, and setting the battle state to DEFENDINGEND.
beforeStateChange(old, new): Called each time the battle state changes. old is a string referring to the previous state, and new is a string referring to the newly set state. If this function returns true, Game.battle:onStateChange() won't be called, essentially overriding the behavior for that state. See Battle States below for more detail.
onStateChange(old, new): Called after the battle state changes. old is a string referring to the previous state, and new is a string referring to the newly set state.
createSoul(x, y): Returns an instance of a Soul class. Called at the beginning of each wave. By default, returns Soul(x, y), passing in the x and y provided. See Soul for details about how to use this to implement custom soul types.

Game.battle Functions

Beyond functions that the Encounter class has for itself, there are also variables and functions in the state Game.battle. These are generally used by encounters, enemies, and waves. These include:

arena: Refers to the Arena instance when it exists.
party: A table of the party members in the battle.
enemies: A table of the enemies in the battle.
soul: Refers the the instance of the player during waves.
tension: Refers to the current amount of TP.
mask: An Object that masks its children to the arena. See Arena for more detail.
waves: A table of the current wave instances, if an attack is happening.
timer: An instance of a Timer object.
state: A string referring to the current state of the battle. Should not be set directly; see Battle States below for more detail.

registerXAction(party, name, description, tp): Adds an X-Action to a party member. party refers to the ID of a party member that receives the action, name is the name of the X-Action, description is the brief description used in battle, and tp is how much TP the act costs to use (defaults to 0).
finishAction(action, keep_animation): Marks an action as processed and moves on. action is a table of data which can be received via getActionBy() (see below), and keep_animation is a boolean that determines whether party members should continue their current animations or have it reset (defaulting to false). If action is not specified, it will refer to the current action being processed.
finishActionBy(battler): Marks the action for the specified battler as processed.
getCurrentAction(): Returns the current action.
getActionBy(battler): Returns the action for the specified battler.
markAsFinished(action, keep_animation): Prepares an action to be processed, but does not automatically move on; the action will be properly processed during setActText() (see below for more detail) if this is called. action is a table of data which can be received by getActionBy(), and keep_animation is a boolean that determines whether party members should continue their current animations or have it reset (defaulting to false). If action is not specified, it will refer to the current action being processed.
commitAction(battler, action_type, target, data, extra): Prepares an action to be performed. battler is the battler performing the action, action_type is a string defining what the action is (see PartyBattler below), target is the Battler that will be targeted by the action, data is a table of data defining the fields party (which party members are involved in the action), name (if the action is an act, the name of the act used), and data (if the action is a spell or an item, the Spell or Item instance that's being used), and extra is a table of extra fields that the action may need (such as points for the ATTACK action).
commitForceAction(battler, action_type, target, data, extra): Commits an action that cannot be cancelled. Can be used at the start of a battler's turn (see PartyMember functions for more detail) to create a forced action, akin to Susie's behavior in chapter 1 of Deltarune.
powerAct(spell, battler, user, target): Turns a party member's turn from an ACT to a spell cast. spell is the name of the spell the party member should use, battler is the PartyBattler that initiates the ACT, user is a string referring to the PartyBattler that should cast the spell, and target is an optional Battler instance or table of Battler instances referring to the battlers affected by the spell. Can be used during EnemyBattler:onAct() to make an action cast a spell.
resetAttackers(): If any party members are currently attacking, end the attack prematurely.
checkSolidCollision(collider): Returns whether the collider is colliding with the arena. If true, it also returns the arena itself. See Collision for more detail.
hurt(amount, element): Damages a random player. Currently half-implemented.
setWaves(waves): Called just before the waves start, clearing previous waves and setting the new wave to what waves specifies. waves is either a table of Wave instances or a table of strings referring to wave IDs. selectWave() must be called on at least one enemy for waves to work properly; see Waves for more detail.
nextTurn(): Sets the battle to the next player turn.
returnToWorld(): Ends the battle and returns to the overworld.
battleText(text, post_func): Sets the current message to the string text. post_func is an optional function that will be called after the text is proceeded.
setActText(text, dont_finish): Sets the current message to the string text. dont_finish is an optional boolean determining whether the current action should not be finished (defaulting to false). If an action is prepared via markAsFinished(), finishAction() will be called on that action when this function is called.
infoText(text): Sets the current message to the string text. Messages created by this cannot be proceeded by the player, and will only proceed if other text is set.
spawnEnemyTextbox(enemy, text): Sets dialogue for the specified enemy to the string text. enemy should be an instance of an EnemyBattler.
startCutscene(), startActCutscene(): See Starting Cutscenes for more detail.
setState(state, reason): Changes the encounter's current state. state is a string referring to the new state the battle is going into, and reason is a second optional string providing more information if necessary. See Battle States below for more detail.
returnToWorld(): Ends the battle and removes the Game.battle instance.
swapSoul(soul): If there's a current instance of the player, swap its instance with the instance passed into the function. See Soul for more detail.
removeEnemy(enemy, defeated): Removes an enemy from the encounter. If defeated is true, it will also consider the enemy to be defeated.
getActiveEnemies(): Returns a table of all currently participating enemies.
getActiveParty(): Returns a table of all currently alive party members.
getEnemyByID(id): Returns an enemy with the specified ID, if one is present.
getPartyByID(id): Returns a party member with the specified ID, if one is present.

Battle and PartyBattler States

Battles work by using "states" to define what behavior should be happening at each moment, and to transition between different phases of a turn in a battle. Battle.state refers to the current state of the battle, and Battle:setState() is called every time the battle changes state, in order to end the previous state and set up the next. Battle:setState() can also be called by other code to manipulate the progression of a turn.

The following is a list of all states that the battle goes through, as well as a description of what they do, and what information they may need (provided by the reason argument in Battle:setState()). The available states are:

TRANSITION: Used if the battle is transitioning from the overworld into the battle. This only occurs once, and only if the battle is transitioned into (if not, the battle starts immediately in INTRO).
INTRO: Used when the battle starts, after the transition completes. This only occurs once, at the beginning of the battle. Encounter:onBattleStart() is called when this state is set.
BATTLETEXT: Used when encounter text is being displayed.
ACTIONSELECT: Used at the start of each party member's turn, before they select any action (such as attacking, using an item, etc).
ENEMYSELECT: Used when an action requires selecting an enemy, such as attacking or sparing. reason will be the specific action being used (ATTACK, ACT, ITEM, SPELL, or SPARE).
MENUSELECT: Used when an action requires selecting some subaction. Selecting an ACT, item or spell all use this. reason will be the specific action being used.
XACTENEMYSELECT: Used when selecting an enemy for an X-Action.
PARTYSELECT: Used when an action requires selecting a party member, such as using an item or spell. reason will be the specific action being used.
ATTACKING: Used while party members are in the attacking phase. Updates attack boxes while set.
ACTIONSDONE: Used after party members have attacked, while the damage numbers are present. Sets state to ENEMYDIALOGUE once damage numbers are gone.
ENEMYDIALOGUE: Used while enemies are saying dialogue. Note that this state is not used during dialogue cutscenes created by Encounter:getDialogueCutscene(); the CUTSCENE state is used instead. Sets state to VICTORY if no enemies are present when set.
DIALOGUEEND: Used after enemy dialogue ends. Calls Encounter:onDialogueEnd() when set.
DEFENDING: Used during the dodging phase of a turn, when a wave is active. Updates waves while set.
DEFENDINGEND: Used after a wave ends, while transitioning to the next turn.
VICTORY: Used when the battle is won. Ends battle, updates values such as gold and EXP, displays end message, calls Encounter:onBattleEnd(), and sets state to TRANSITIONOUT when set.
TRANSITIONOUT: Used to transition from the battle to the overworld. Calls Battle:returnToWorld() after the transition is finished.

Additionally, during a battle, every PartyBattler will perform an action every turn. When a function refers to a battler's "action", this usually refers to a table of data, containing the information needed to perform that action. By default, most actions define the following fields:

action: The name of the action being performed, such as ATTACK or DEFEND.
character_id: A number referring to the index of the PartyBattler performing the action.
target: The Battler that the action is targetting.

The following is a list of all strings recognize for action.action, as well as when they're used and what extra information they might receive from the action table.

SPARE: Used when the party member attempts to spare an enemy.
ATTACK, AUTOATTACK: Used when the party member attacks an enemy. The difference between ATTACK and AUTOATTACK is that AUTOATTACK won't spawn an attack bar if it's used, and it won't use the critical hit effects even if it's a crit. The action will also use damage if it's defined to specify the damage dealt to the enemy, or points to calculate the damage dealt based on Deltarune values (with 150 being the max value and performing a critical hit).
ACT: Used when the party member performs an act. Party members involved in a group act will all use an ACT action. name is a data value defining the name of the act used.
SPELL: Used when the party member casts a spell. data is a data value referring to the Spell instance that will be used.
ITEM: Used when the party member uses an item. data is a data value referring to the Item instance that will be used.
DEFEND: Used when the party member defends.
SKIP: Skips the party member's turn.