Relevant files: partymember.lua

Before reading this page, it is recommended to read Actors first.

Creating a Party Member

Party members are classes that define information for characters that can be a part of the mod's party. All party member files should be located in scripts/data/party. Party member files should extend the global PartyMember class.

The following is a list of values that can be defined for PartyMember. Some values for party members get saved to the save file, and can be updated through gameplay. These fields will be specified.

name: The string Kristal uses when displaying the name of this party member.
level: A number defining the current level of the party member. Saved to the save file.
title: The string used by the overworld menu to describe the party member. Saved to the save file.
lw_lv: A number defining the LV value of the party member in the light world. Saved to the save file.
lw_exp: A number defining the EXP value of the party member in the light world. Saved to the save file.
lw_exp_needed: A table of values, with each index referring to a LV value, and each value for an index defining how much EXP is needed to reach that LV. By default, contains the values used by Undertale, defining numbers 1-20.
soul_priority: A number indicating which character the soul will originate from when it animates. The party member with the highest number will be the character the soul originates from.
soul_color: The color of the party member's soul. Defaults to red.
has_act, has_spells: Booleans that represent whether the party member can act or use spells.
has_xact: Whether the party member will have an X-Action in their spells menu.
xact_name: The name of the default X-Action displayed in battles for the party member.
stats: A table representing the base stats for the party member. Contains the fields health, attack, defense, and magic. Saved to the save file.
lw_stats: A table representing the stats for the party member in the light world. Contains the fields health, attack and defense. Saved to the save file.
health: The current health of the party member. Saved to the save file.
lw_health: The current health of the party member in the light world. Saved to the save file.
equipped: A table defining what equipment the party member will have by default. Contains the fields weapon and armor; weapon is a string referring to a weapon Item ID, and armor is a table of 1 or 2 strings referring to armor Item IDs.
lw_weapon_default: An Item ID referring to the weapon the party member will have equipped by default in the light world.
lw_armor_default: An Item ID referring to the armor the party member will have equipped by default in the light world.
color: Color used by the action bar and HP bar in battles.
dmg_color: Color used for the numbers when attacking enemies.
attack_bar_color: Color used by the target bar that appears for determining damage to an enemy.
attack_box_color: Color used by the attack box that appears for determining damage to an enemy.
xact_color: Color of the X-Action name.
menu_icon: Path to the sprite used to represent the party member in the Equip / Power overworld menus.
head_icons: Path to the sprite used as the icon in battle UI.
name_sprite: Path to the sprite used for the name of the party member in battle UI. If unprovided, it will default to using a custom font using the party member's name.
weapon_icon: Path to the sprite used for the weapon type for this party member.
attack_sprite: The path to the sprite used when the party member attacks.
attack_sound: The path to the sound effect used when the party member attacks.
attack_pitch: The pitch of the sound effect used when the party member attacks.
battle_offset: An optional table of 2 values, indicating the x and y offset the party member will have when in battles.
head_icon_offset: An optional table of 2 values, indicating the offset the head icon used in battles will have.
menu_icon_offset: An optional table of 2 values, indicating the offset the menu icon used in the overworld menu will have.
gameover_message: An optional string or table of strings, referring to dialogue that will be displayed in the game over screen. Dialogue is randomly selected from a party member with gameover_message defined, if the party member is not the member with the highest soul priority.
flags: A table of any arbitrary fields, used for storing extra data about the party member for gameplay. Should not be referenced directly, see setFlag() and getFlag() below. Saved to the save file.

Additionally, since PartyMembers are used throughout gameplay, some values for them need to be defined via functions instead of setting variables so that it updates the game correctly. The following are functions that should be used during initiation to define these kinds of values:

setActor(actor): Sets the party member's Actor. actor can be either a string referring to an actor ID, or an Actor instance.
setLightActor(actor): Sets an Actor for the party member to be used during light world rooms. actor can be either a string referring to an actor ID, or an Actor instance.
addSpell(spell): Adds a spell to the party member's spell list. spell can be either a string referring to a spell ID, or a Spell instance.
setWeapon(item): Sets the party member's current equipped weapon to the specified item. item can be either a string referring to an item ID, or an Item instance.
setArmor(i, item): Sets the party member's specified armor slot to the specified item. item can be either a string referring to an item ID, or an Item instance.

Using and Overriding Functions

Party members are used by Game.party, which is a table referring to a list of the current party members. You can get a specific party member by calling Game:getPartyMember(id), where id is a string referring to a party member ID. Other objects can also have a variable that refers to their personal PartyMember instance, as a method of storing data about themself. PartyBattlers have a chara variable that refers to their PartyMember instance, and overworld characters have a getPartyMember() function.

PartyMembers have many functions that can be used to retrieve or set data for them. All of these functions can potentially be overridden as well, to define custom behavior for that party member. The functions available are:

Functions that can be used or overridden for PartyMembers include:

getName(), getLevel(), getLightLV, getLightEXP(), getSoulPriority(), getSoulColor(), hasAct(), hasSpells(), hasXAct(), getXActName(), getWeaponIcon(), getColor(), getDamageColor(), getAttackBarColor(), getAttackBoxColor(), getXActColor(), getMenuIcon(), getHeadIcons(), getNameSprite(), getAttackSprite(), getAttackSound(), getAttackPitch(), getBattleOffset(), getHeadIconOffset(), getMenuIconOffset(), getGameOverMessage(), getSpells(): Functions that return their associated value by default.
getTitle(): Returns the title used in the overworld menu. By default, returns getLevel() + title.
getLightEXPNeeded(lv): Returns the EXP needed to reach the specified lv value.
getHealth(): Returns the party member's current health, depending on whether the current world is light or not.
getBaseStats(light): Returns the party member's stats table. If light is undefined, return stats depending on whether the current world is light or not; otherwise, return stats depending on whether light is true or not.
getEquipment(): Returns a table of the currently equipped weapons and armors, in that order.
getWeapon(): Returns the currently equipped weapon, if the party member has one.
getArmor(index): Returns the armor equipped at the specified index, if it exists.
getEquipmentBonus(stat): Returns the summed equipment bonus based on all equipment for the specified stat.
getStats(): Returns a table of stat names and their values, accounting for equipment bonuses.
getStat(stat, default): Returns the stat value for the specified stat, accounting for equipment bonuses. If default is defined, it will return that if the player does not have the specified stat.
getActor(light): Returns the party member's actor or lw_actor variable. By default, if light is undefined, it returns an actor depending on whether the current world is light or not; otherwise, it returns an actor depending on whether light is true or not.
getReaction(item, user): Returns the reaction the party member has to someone equipping or using an item. item is the Item instance being used, and user is the PartyMember instance associated with the party member using the item.
canEquip(item, slot_type, slot_index): Returns whether the party member is able to equip the specified item. item is the Item instance that is attempting to be equipped, slot_type is a string defining whether the item is a weapon or an armor, and slot_index is a number referring to the slot number the item is attempting to be equipped to.
onAttackHit(enemy, damage): Called when the party member damages an enemy. enemy refers to the EnemyBattler that was damaged, and damage is the amount of damage dealt.
onTurnStart(battler): Called at the start of the party member's turn in battles. battler is the PartyBattler instance that the party member is used by. Can be overridden to create a party member that attacks automatically; see Game.battle:commitForceAction() on the Game.battle functions page for more detail.
onLevelUp(level): Called when the party member levels up. level is the new level they are at.
onPowerSelect(menu): Called when the party member's Power menu is hovered over in the overworld menu. menu is the current Menu instance.
onPowerDeselect(menu): Called when the party member's Power menu stops being hovered over in the overworld menu. menu is the current Menu instance.
drawPowerStat(index, x, y, menu): Called every frame for each stat in the party member's Power menu. index refers to the index of the stat, x and y refer to the position of the text, and menu is the current Menu instance.
addSpell(spell): While this function should be used to define the initial spells a party member has, it can also be used to add spells to a party member during a mod, as spells are saved to the save file.
removeSpell(spell): Removes a spell from the party member. spell is either a Spell instance or a Spell ID.
setWeapon(item): Sets the party member's equipped weapon to the specified item. item is either an Item instance or a Item ID.
setArmor(index, item): Sets the party member's equipped armor at the specified slot to the specified item. index is a number referring to the armor slot, and item is either an Item instance or a Item ID.
checkWeapon(id): Returns whether the party member has the specified weapon equipped. id is a string referring to an Item ID.
checkArmor(id): Returns whether the party member has the specified armor equipped, and a number representing how many they have equipped. id is a string referring to an Item ID.
heal(amount, playsound): Heals the party member. If playsound is not false, the heal sound effect will play.
setHealth(amount): Sets the party member's current health to the specified value, depending on whether the world is light or not.
increaseStat(stat, amount, max): Increases the specified stat by the specified amount, not allowing it to exceed max if defined.
setFlag(flag, value): Sets a save data flag for the party member to the specified value.
addFlag(flag, amount): Adds to the value stored to the specific flag.
getFlag(flag, default): Gets a save data flag for the party member, returning default if the flag doesn't exist.