Battlers and Enemy Creation

Relevant files: battler.lua, partybattler.lua, enemybattler.lua

PartyBattlers and EnemyBattlers

As mentioned on the World Objects page, Characters are not used in the Battle game state. Instead, an object called a Battler is used. There are 2 kinds of battlers: PartyBattler and EnemyBattler. The majority of this page details EnemyBattlers, as it's important to know in detail how they work in order to make any battles, but this section will briefly explain the Battler and PartyBattler variables and functions available.

Battler.highlight: An instance of a white ColorMaskFX.
Battler.hit_count: How many times the battler has been hit recently. Used when creating damage numbers to create the stacking effect.
Battler:flash(sprite): Makes the specified sprite flash white, or the battler's sprite if sprite isn't defined.
Battler:sparkle(r, g, b): Makes sparkles appear around the enemy. If r, g, and b are defined, the sparkles will be the specified color.
Battler:statusMessage(x, y, type, arg, color, kill): Spawns a DamageNumber at the specified position. type is the type of message, arg is an argument referring to data the type of message needs, color an optional table referring to the color of the message, and kill is an optional boolean defining whether other status messages should disappear when this one does. Returns the DamageNumber instance. The following are the possible types that can be passed in:

• msg: Displays a text message, with arg being the message name. Messages are sprites, relative to ui/battle/msg.
• mercy: Displays a mercy number, with arg being the amount of mercy added.
• any other: Displays a number message, with arg being the text displayed. The available characters for arg are 0-9, +, -, %, and /.

Battler:setAnimation(anim, callback), Battler:setCustomSprite(sprite, ox, oy, speed, loop, after): Shorthand for calling ActorSprite functions.
Battler:getActiveSprite(): Returns either overlay_sprite or sprite, depending on which is currently active.

PartyBattler.chara: The battler's associated PartyMember instance.
PartyBattler.actor: The battler's actor data table.
PartyBattler.sprite: The battler's ActorSprite instance.
PartyBattler.overlay_sprite: A second ActorSprite copy. Enabled on occasion to display certain animations (eg. hurt animation) without interrupting the main animation.
PartyBattler.defending: Whether the party member is defending this turn.
PartyBattler.hurt_timer: How long to display the party member's overlay_sprite before reverting back to sprite.
PartyBattler.is_down: Whether the party member is downed.
PartyBattler:hurt(amount, exact): Damages a party member, calling removeHealth() and playing animations. If exact is not true, then it will adjust amount based on the party member's defense.
PartyBattler:removeHealth(amount): Removes health from the party member's chara.health value, and calls checkHealth() after.
PartyBattler:checkHealth(): Checks the party member's health and calls down() or revive() if they aren't in the correct state.
PartyBattler:down(): Knocks out a party member.
PartyBattler:revive(): Revives a party member if they're down. Does not heal them.
PartyBattler:heal(amount): Heals a party member.
PartyBattler:statusMessage(type, arg, color, kill): Spawns a DamageNumber at the party member's position.
PartyBattler:toggleOverlay(state): Toggle's the party member's overlay sprite (see EnemyBattler's toggleOverlay() below for more detail).
PartyBattler:setActSprite(sprite, ox, oy, speed, loop, after): Calls setCustomSprite() and adds multiple visual effects. Used to mimic Deltarune's effects when changing sprites for certain actions.

Creating an Enemy

EnemyBattlers are the Battlers that are used within encounters to create a battle. Enemy files are made through extending this class. This is necessary not only because functions need to be called during instantiation, but also because they have many functions that need to be overridden. Enemy files should go in script/battle/enemies. A basic enemy file looks something like this:

local EnemyName, super = Class(EnemyBattler)

function EnemyName:init()
  super:init(self)

  self.name = "Enemy Name"
  self:setActor("actorID")
end

function EnemyName:onAct(battler, name)
  -- define act stuff (see Overridable Functions below)
  -- at the end, return super:onAct, which handles Check
  return super:onAct(self, battler, name)
end

return EnemyName

The following are fields for EnemyBattler. Most of these values should be set in the init function to define the enemy's data:

name: Name of the enemy that displays in menus.
max_health: Maximum health the enemy can have.
health: Amount of health the enemy starts with for battles.
attack: Attack stat of the enemy, used to calculate damage from bullets spawned by this enemy.
defense: Defense stat of the enemy, affecting how much damage player attacks can do to it.
gold: Used to calculate how much gold is earned from winning a battle.
experience: How much experience the player gets from defeating the enemy with violence. Currently unused by default.
spare_points: How much the enemy's mercy will go up when spared before it can be spared.
defeat_type: A string referring to the animation to play when the enemy is defeated. Can be either run, fatal, or none/nil (defaults to run).
can_freeze: Whether the enemy can be frozen by Iceshock (defaults to true).
waves: A table of strings, each referring to a file name of a wave (see Waves for more detail). If not defined, the enemy won't start waves.
check: The message that displays when the enemy is checked.
text: A table of strings, containing flavor text that the game randomly selects from by default.
low_health_text: The message that displays when the enemy is tired.
tired_percentage: A number between 0 and 1 representing how much the enemy needs to be damaged to feel tired (defaults to 0.5, meaning at 50% health an enemy can be pacified).
dialogue: A table of strings or tables, containing lines of dialogue that the enemy will randomly select from by default. If a value is a table of strings, the enemy will have multiple dialogue boxes. If not defined, the game will skip giving the enemy dialogue.
acts: A table of tables, each containing data for an ACT available for the enemy. The following fields can be defined for each act:

• name: The name that will be displayed in the act menu, as well as what is passed into onAct (see Overridable Functions below).
• description: An optional string that displays when hovering over the act, briefly describing it.
• party: An optional value, being either a string, referring to either a single party member ID or all, which refers to all party members, or a table of IDs that refer to party members; if defined, the listed party members will be required for the act.
• tp: The TP cost of the act. Defaults to 0.
• highlight: An optional table of Battler instances; if defined, the listed Battlers will be highlighted when the ACT is hovered over.

encounter: A reference to the Encounter instance the enemy is in. Cannot be referenced within init, and should not be set.

Additionally, functions that can be called to initialize data are:

setActor(id): Sets the actor for the enemy to use.
registerAct(name, description, party, tp, highlight): Adds an act that the player can use for the enemy, with each argument correlating with values that can be defined in the enemy's initial acts table.
registerShortAct(name, description, party, tp, highlight): Same as registerAct(), but for short actions. Short actions all occur at the same time, instead of giving each act their own message.
registerActFor(chara, name, description, party, tp, highlight): Same as registerAct(), but allows you to specify which party member the ACT should be available for, if there are multiple ACTing party members.
registerShortActFor(chara, name, description, party, tp, highlight): Same as registerShortAct(), but allows you to specify which party member the ACT should be available for, if there are multiple ACTing party members.
getAttackTension(points): Returns a value determining how much TP% the player gets when attacking the enemy. points is a number determined by how accurate the attack was; a critical hit gives 150 points, and other accuracies give a value between 0 and 120. By default, this returns points divided by 25 (giving 6% TP for a crit).

Overridable Functions

Due to the complexity of battles, enemies have several functions that they can override to define behavior. Many of these functions contain overlap in variable names: battler is the party member that is performing the action, and name is the name of the action. Note that battler refers to the instance of a PartyBattler class, and not the PartyMember; to get the PartyMember instance, you use battler.chara, and to get the ID of the PartyBattler (useful for performing character-specific actions), you can check battler.chara.id.

Functions that can be overridden include:

onActStart(battler, name): Called for each act immediately after each party member has selected their action, but before any acts are actually processed. Used for changing party member sprites.
onAct(battler, name): Called when the game processes an act. Enemy responses to acts, such as adding mercy (see Misc. Functions below), should be done here. battler is the PartyBattler instance performing the act, and name is a string referring to the act being used. Returning a string will set the message box to that text, and proceed to the next action. Returning nil causes the game to wait until Game.battle:finishAction() is called manually (see Game.battle Functions for more detail).
onShortAct(battler, name): If an act is a short act, this will be called instead of onAct(), then immediately be called again for any other short acts. Other than that, it functions the same as onAct(). The returned text will be combined, separated by newlines.
onCheck(battler): Called when the enemy is checked.
onSpareable(): Called when the enemy reaches 100% mercy. By default, sets the enemy's animation to spared if it exists.
onSpare(): Called when the enemy is spared. By default, sets the enemy's animation to spared if it exists.
onMercy(): Called when a party member attempts to spare the enemy. Returns true if the enemy is successfully spared, and false otherwise. By default, this function calls spare() if mercy is at 100; otherwise, it calls addMercy(spare_points).
onHurt(damage, battler): Called when a party member hurts the enemy. damage refers to the amount of damage dealt to the enemy, and battler refers to the PartyBattler that dealt the damage. By default, sets the enemy's animation to hurt if it exists, shakes the enemy's sprite, and makes the enemy tired if they were hurt to a percentage below tired_percentage.
onHurtEnd(): Called some time after the enemy is hurt. By default, it resets the animation to what it was before it was set to hurt, and stops shaking the enemy.
onDefeat(damage, battler): Called when the enemy is defeated through violence. damage refers to the amount of damage dealt to the enemy, and battler refers to the PartyBattler that dealt the damage. By default, calls onDefeatRun() if defeat_type is run, calls onDefeatFatal() if defeat_type is fatal, and sets the enemy's animation to defeat if it exists otherwise.
onDefeatRun(damage, battler), onDefeatFatal(damage, battler): Called by onDefeat() based on the corresponding defeat_type.
getXAction(battler): Returns the name of what the X-Action is for a specific party member. By default, the function returns "Standard". It is not necessary to override this to use X-Actions: you can simply check if the act name is "Standard" in onAct() or onShortAct().
isXActionShort(battler): Returns a boolean defining whether a specific party member's X-Action is considered a short act or a normal act. By default, it returns false.
getEncounterText(): Returns a message for the encounter to use, called at the start of each player turn. By default, if the enemy is made tired through violence, it returns low_health_text; otherwise, it returns a randomly selected message from text.
getEnemyDialogue(): Returns dialogue for the enemy to use, called at the start of each enemy turn. By default, if dialogue_override is defined, it will return that; otherwise, it returns a randomly selected dialogue from dialogue.
getNextWaves(): Returns a table of strings referring to wave IDs. By default, returns waves.
selectWave(): Returns a string referring to a wave ID. By default, calls getNextWaves(), randomly selects a value from the result, and sets the enemy's selected_wave to the result before returning it. If overridden, it is important to set selected_wave to the wave ID returned; if this is not done, bullets spawned by the wave will not deal damage, as they have no enemy associated with it.

Misc. Functions and Variables

Enemies also have miscellaneous other functions and variables that can be used during battle. Acts will generally need to use these to function. These include:

sprite: The enemy's ActorSprite.
overlay_sprite: A second instance of the enemy's ActorSprite. This is used by certain actions like hurting the enemy, so that it doesn't interrupt the enemy's current animation.
hurt_timer: How long to display the enemy's overlay_sprite before reverting to sprite.
tired: A boolean that states whether the enemy is tired or not.
mercy: A number between 0 and 100 that determines how close the enemy is to being spared. Generally, you should not set this directly; instead, use addMercy().
dialogue_override: If defined, getEnemyDialogue will return this, instead of selecting randomly from dialogue.
selected_wave: A string referring to a wave ID. Bullets spawned by a wave with this ID will use the attack value from this enemy to determine its damage.
addMercy(amount): Handles changing mercy for the enemy.
spare(): Spares the enemy (regardless of current mercy amount).
hurt(amount, battler): Damages the enemy.
heal(amount): Heals the enemy.
freeze(): Freezes the enemy if can_freeze is true.
defeat(reason, violent): Defeats the enemy. reason is a string referring to the method the enemy was defeated, and violent is a bool determining whether the enemy was defeated violently.
toggleOverlay(state): Enables or disables the enemy's overlay_sprite.