Relevant files: actor.lua, actorsprite.lua

Making an Actor

An Actor is a class used to define complex animation data for sprites. Party members, NPCs, and enemies all require actors to be defined for their sprites.

Actor files should be located in scripts/data/actors. To create an actor, you will need to extend the global Actor class, which will create a new version of the Actor that allows you to define the specific information it needs. A basic actor file looks something like this:

local ActorName, super = Class(Actor)

function ActorName:init()
  super:init(self)

  self.name = "Actor Name"
  self.path = "party/example_actor"
end

return ActorName

Kristal uses this process of extending classes or objects for nearly everything. When extending a class used for data, you'll want to define its properties in the override of the class's init() function. The following is a list of values that should be defined for Actors:

width, height: Refers to the size of the character's default sprite. Used to determine the actor's center and position of its hitbox and offset. The actor's position is at the bottom center of the rectangle defined by these values.
hitbox: A table containing 4 values, in the format of {x, y, width, height}. x and y are relative to the topleft of the width and height previously defined. The hitbox is used to check collision with other objects.
path: The base path, relative to assets/sprites, that all sprite definitions use.
default: The sprite path that the actor will start with when first created.
animations: A table of animation definitions, containing IDs associated to information about how to play that animation. An example of a very basic animation table:

self.animations = {
  ["id"] = {"path", 0.1, true, next="id_2"}
}

The index for each animation is its ID, and animations can be played by referring to this ID. Some IDs are called directly by the game (see Default Animations below). The table follows the same rules as the argument for setAnimation() for Sprites; for detail on this, see that page. The table can also take 2 extra definitions:

• next: A string that refers to a different animation ID; when the animation ends, the animation with this ID will play.
• temp: If true, then when the animation ends, it will go back to the animation that was playing previously.

offsets: A table similar to animations, which defines how far offset a sprite is from the default sprite's position. Each index refers to a file path to a sprite, and the value is a table of 2 values, representing the x and y offset.
talk_sprites: A table of simple animation definitions, with each index representing a sprite path, and each value being a number defining the speed the sprite will animate when setSprite() sets the actor's sprite to this path.
color: An optional table of 3 numbers, defining RGB to be used when the actor enters an outline area in the overworld.
flip: An optional string, being either left or right, that determines if the sprite should flip horizontally when the actor is facing a certain direction (eg. Virovirokun has flip = "right", because its sprite faces left by default, and it should flip when looking the other direction).
voice: An optional string defining the path to an audio file to be used for dialogue spoken by this actor, relative to assets/sounds/voice.
portrait_path: The path to a folder containing portrait images for dialogue spoken by this actor.
portrait_offset: A table of 2 numbers that, if specified, will offset the portrait's position by the specified values.

Additionally, a few functions can be overridden for Actors. These functions get called by various things, and can be used to run code at certain points. These functions are:

onWorldUpdate(chara): Called every frame during overworld gameplay. chara is the Character instance that is using the actor.
onWorldDraw(chara): Called every frame during overworld drawing. chara is the Character instance that is using the actor.
onBattleUpdate(battler): Called every frame during battle gameplay. battler is the Battler instance that is using the actor.
onBattleDraw(battler): Called every frame during battle drawing. battler is the Battler instance that is using the actor.
onTalkStart(text, sprite): Called at the beginning of dialogue text in shops. text is the string of text that is being said, and sprite is the ActorSprite instance. Can be used to set the sprite's talking animation.
onTalkEnd(text, sprite): Called when dialogue text finishes in shops. text is the string of text that is being said, and sprite is the ActorSprite instance. Can be used to set the sprite's animation back to its normal animation when the actor is done talking.
onSpriteInit(sprite): Called when an ActorSprite that uses this Actor is created. sprite is the ActorSprite instance that is using the actor. Can be used to add more sprites or other objects to an actor.
preSet(sprite, name, callback): Called before a sprite or animation is set for the ActorSprite, if ActorSprite:set() is called. sprite is the ActorSprite instance being used, name is the string that was passed into set(), and callback is the callback function that was passed into set(), if provided. If this function returns true, set() will not be called for the sprite, allowing users to override behavior.
onSet(sprite, name, callback): Called after ActorSprite:set() is called. sprite is the ActorSprite instance being used, name is the string that was passed into set(), and callback is the callback function that was passed into set(), if provided.
preSetSprite(sprite, texture, callback): Called before a sprite is set for the ActorSprite via ActorSprite:setSprite(). sprite is the ActorSprite instance being used, texture is the file path passed into setSprite(), and callback is the callback function that was passed into setSprite(), if provided. If this function returns true, setSprite() will not be called for the sprite.
onSetSprite(sprite, texture, callback): Called after ActorSprite:setSprite() is called. sprite is the ActorSprite instance being used, texture is the file path passed into setSprite(), and callback is the callback function that was passed into setSprite(), if provided.
preSetAnimation(sprite, anim, callback): Called before an animation is set for the ActorSprite via ActorSprite:setAnimation(). sprite is the ActorSprite instance being used, anim is the animation ID passed into setAnimation(), and callback is the callback function that was passed into setAnimation(), if provided. If this function returns true, setAnimation() will not be called for the sprite.
onSetAnimation(sprite, anim, callback): Called after ActorSprite:setAnimation() is called. sprite is the ActorSprite instance being used, anim is the animation ID passed into setAnimation(), and callback is the callback function that was passed into setAnimation(), if provided.
preResetSprite(sprite): Called before the sprite is reset for the ActorSprite via ActorSprite:resetSprite(). sprite is the ActorSprite instance being used. If this function returns true, resetSprite() will not be called for the sprite.
onResetSprite(sprite): Called after ActorSprite:resetSprite() is called. sprite is the ActorSprite instance being used.
preSpriteUpdate(sprite): Called before the ActorSprite updates, every frame. sprite is the ActorSprite instance being used. If this function returns true, the sprite will not update itself.
onSpriteUpdate(sprite): Called after the ActorSprite updates. sprite is the ActorSprite instance being used.
preSpriteDraw(sprite): Called before the ActorSprite draws, every frame. sprite is the ActorSprite instance being used. If this function returns true, the sprite will not draw itself.
onSpriteDraw(sprite): Called after the ActorSprite draw. sprite is the ActorSprite instance being used.
getWidth(), getHeight(), getSize(), getHitbox(), getColor(), getFlipDirection(), getSpritePath(), getDefault(), getVoice(), getPortraitPath(), getPortraitOffset(): Functions that returns the actor's respective values.
hasTalkSprite(sprite): Whether the actor has a talk animation defined for the specified sprite. sprite is a file path of a sprite for the actor. By default, returns true if the definition for sprite in the actor's talk_sprites table is not nil.
getTalkSpeed(sprite): Returns how fast a talking sprite should animate. sprite is a file path of a sprite for the actor. By default, returns the value defined in the actor's talk_sprites table for the specified sprite.
getAnimation(anim): Returns a table of animation data. anim is a string referring to an animation ID. By default, returns the value defined in the actor's animations table for the specified ID.
hasOffset(sprite): Whether the actor has an offset defined for the specified sprite. sprite is a file path of a sprite for the actor. By default, returns true if the definition for sprite in the actor's offsets table is not nil.
getOffset(sprite): Returns a table of 2 values, defining the offset a sprite should have. sprite is a file path of a sprite for the actor. By default, returns the value defined in the actor's offsets table for the specified sprite.

When creating something that needs an Actor, you will need to provide an ID. By default, the ID for all scripts defined in scripts/data will be the filepath relative to their respective folder, eg. an actor at scripts/data/actors/example_actor/dark.lua will have an ID of example_actor/dark. However, it is possible to define a custom ID, by passing in a string as the second argument when calling Class(). For example, the following code:

local ActorName, super = Class(Actor, "kris")

will create an actor with the ID kris. This allows you to override previously defined scripts, by defining a new actor with the same ID as a previous one.

ActorSprite

ActorSprite is a class that extends Sprite. Objects that use actors use an ActorSprite for their sprite variable instead of a normal Sprite, and these ActorSprites will use Actors to store data for their animations. ActorSprites are useful for these objects because they have extra variables and functions that are commonly useful for actors:

actor: The Actor instance corresponding to this sprite.
sprite: The name of the sprite's current animation.
directional: Whether the current animation has facing directions.
facing: The facing direction of the actor, checked if directional is true. Defaults to down.
shake_x, shake_y: How much the sprite should shake visually.
aura: If true, the actor will emit a red aura. Used by overworld enemies.
resetSprite(): Resets the sprite to its default animations.
setSprite(texture, keep_anim): Sets the sprite to the specified path, relative to the actor's path. setCustomSprite(sprite, ox, oy, keep_anim): Sets the sprite to the specified path, relative to assets/sprites. ox and oy will offset the texture by the specified amount if defined.
setAnimation(anim, callback): Sets the sprite's animation. anim can be either a string, referring to the ID of an animation defined for the actor, or a table, corresponding to the same arguments for Sprite's setAnimation() function. callback, if defined, will be called when the animation is complete.
set(name, callback): Sets the sprite's texture or animation. If name refers to an animation ID for the actor, it will set that animation, and call callback when the animation completes if defined; otherwise, it will attempt to set the sprite to the specified path, and call callback immediately if defined.

Default Animations

Many IDs are used by Kristal when certain actions are done. They are optional, and the game will just not play an animation when trying to use a default ID that has not been specified. The following is a list of default IDs called by the game:

For enemies

hurt: Used when the enemy is hit.
spared: Used when the enemy is spareable or spared.
defeat: Used when the enemy is defeated, if it doesn't run away or die.

For party members

battle/idle: Idle animation when the player is in battle.
battle/attack: Used when the player attacks an enemy.
battle/act: Used when the player acts.
battle/spell: Used when the player uses a spell.
battle/item: Used when the player uses an item.
battle/spare: Used when the player attempts to spare an enemy.
battle/defend: Used when the player defends.
battle/attack_ready, battle/act_ready, battle/spell_ready, battle/item_ready, battle/spare_ready: Used when the player has selected the respective action, but has not yet performed it. (Note that there is no battle/defend_ready: the game just uses battle/defend immediately.)
battle/act_end: Used after the player has acted, if their animation is currently battle/act.
battle/hurt: Used when the player takes damage.
battle/defeat: Used when the player has less than 0 hp.
battle/transition: Used when the player first enters a battle, and is moving to their in-battle position.
battle/intro: Used once the player reaches their position in-battle, or when the battle starts if the mod immediately loads into a battle.
battle/victory: Used once the battle is won and the player is returning to the overworld.