Scripting reference

This page is a quick reference of scripting directives, useful for map-makers to see everything in one page.

Conditions

Below is the list of all conditions usable inside scripts, along with a description of their parameters, if any. In order to negate a condition, it is enough to replace is by not.

ButtonPressedCondition

Check to see if a particular key was pressed.

Currently only “K_RETURN” is supported.

Script usage

is button_pressed <button>
Script parameters

button – A button/intention key (E.g. “K_RETURN”).

CombatStartedCondition

Check to see if combat has been started or not.

Script usage

is combat_started

DialogOpenCondition

Check to see if a dialog window is open.

Script usage

is dialog_open

EvolveMonstersCondition

Check to see if monsters can be evolved on a evolutionary path.

Script usage

is evolve_monsters <evolution>
Script parameters

evolution – Name of a monster evolution.

HasItemCondition

Check to see if a NPC inventory contains something.

Script usage

is has_item <character>,<item>[,operator][,quantity]
Script parameters
  • character – Either “player” or npc slug name (e.g. “npc_maple”).

  • item – The item slug name (e.g. “item_cherry”).

  • operator – Numeric comparison operator. Accepted values are “less_than”, “greater_than”, “equals”, “less_or_equal” and “greater_or_equal”. The default value is “greater_or_equal”.

  • quantity – Quantity to compare with. Must be a non-negative integer. The default value is 1.

HasMonsterCondition

Check to see the player is has a monster in his party.

Script usage

is has_monster <monster>
Script parameters

monster – Monster slug name (e.g. “rockitten”).

MonsterFlairCondition

Check to see if the given monster flair matches the expected value.

Script usage

is monster_flair <slot>,<category>,<name>
Script parameters
  • slot – Position of the monster in the player monster list.

  • category – Category of the flair.

  • name – Name of the flair.

MonsterPropertyCondition

Check to see if a monster property or condition is as asked.

Script usage

is monster_property <slot>,<property>,<value>
Script parameters
  • slot – Position of the monster in the player monster list.

  • property – Property of the monster to check (e.g. “level”). Valid values are:

    • name

    • level

    • level_reached

    • type

    • category

    • shape

  • value – Value to compare the property with.

MusicPlayingCondition

Check to see if a particular piece of music is playing or not.

Script usage

is music_playing <music_filename>
Script parameters

music_filename – Name of the music.

NPCAtCondition

Check to see if a character is at the condition position on the map.

Script usage

is npc_at <character>
Script parameters

character – Either “player” or npc slug name (e.g. “npc_maple”).

NPCExistsCondition

Check to see if a character object exists in the current list of NPCs.

Script usage

is npc_exists <character>
Script parameters

character – Either “player” or npc slug name (e.g. “npc_maple”).

NPCFacingTileCondition

Check to see if a character is facing a tile position.

This is checked against all the tiles included in the condition object.

Script usage

is npc_facing_tile <character>
Script parameters

character – Either “player” or npc slug name (e.g. “npc_maple”).

NPCFacingCondition

Check to see where a character is facing.

Script usage

is npc_facing <character>,<direction>
Script parameters
  • character – Either “player” or npc slug name (e.g. “npc_maple”).

  • direction – One of “up”, “down”, “left” or “right”.

PartySizeCondition

Check the party size.

Script usage

is party_size <operator>,<value>
Script parameters
  • operator – One of “equals”, “less_than” or “greater_than”.

  • value – The value to compare the party size with.

PlayerAtCondition

Check to see if the player is at the condition position on the map.

Script usage

is player_at

PlayerFacingNPCCondition

Check to see the player is next to and facing a particular NPC.

Script usage

is player_facing_npc <character>
Script parameters

character – Npc slug name (e.g. “npc_maple”).

PlayerFacingTileCondition

Check to see if an NPC is facing a tile position.

Script usage

is player_facing_tile

PlayerFacingCondition

Check to see where an NPC is facing.

Script usage

is player_facing <direction>
Script parameters

direction – One of “up”, “down”, “left” or “right”.

PlayerMovedCondition

Check to see the player has just moved into this tile.

Using this condition will prevent a condition like “player_at” from constantly being true every single frame.

  • Check if player destination collides with event

  • If it collides, wait until destination changes

  • Become True after collides and destination has changed

These rules ensure that the event is true once player in in the tile and is only true once. Could possibly be better, IDK.

Script usage

is player_moved

ToTalkCondition

Check if we are attempting to talk to an npc.

Script usage

is to_talk <character>
Script parameters

character – Npc slug name (e.g. “npc_maple”).

ToUseTileCondition

Check if we are attempting interact with a map condition tile.

Script usage

is to_use_tile

TrueCondition

This condition always returns true.

Script usage

is true

VariableIsCondition

Check an operation over a variable.

Script usage

is variable_is <value1>,<operation>,<value2>
Script parameters
  • value1 – Either a variable or a number.

  • operation – One of “==”, “!=”, “>”, “>=”, “<” or “<=”.

  • value2 – Either a variable or a number.

VariableSetCondition

Check to see if a player game variable exists and has a particular value.

If the variable does not exist it will return False.

Script usage

is variable_set <variable>[:value]
Script parameters
  • variable – The variable to check.

  • value – Optional value to check for.

Actions

Below is the list of all actions usable inside scripts, along with a description of their parameters, if any.

AddItemAction

Add an item to the current player’s inventory.

Script usage

add_item <item_slug>[,quantity]
Script parameters
  • item_slug – Item name to look up in the item database.

  • quantity – Quantity of the item to add. By default it is 1.

AddMonsterAction

Add a monster to the specified trainer’s party if there is room.

Script usage

add_monster <monster_slug>,<monster_level>[,trainer_slug]
Script parameters
  • monster_slug – Monster slug to look up in the monster database.

  • monster_level – Level of the added monster.

  • trainer_slug – Slug of the trainer that will receive the monster. It defaults to the current player.

CallEventAction

Execute the specified event’s actions by id.

Script usage

call_event <event_id>
Script parameters

event_id – The id of the event whose actions will be executed.

ChangeStateAction

Change to the specified state.

Script usage

change_state <state_name>
Script parameters

state_name – The state name to switch to (e.g. PCState).

ClearVariableAction

Clear the value of a variable from the game.

Script usage

clear_variable <variable>
Script parameters

variable – The variable to clear.

CopyVariableAction

Copy the value of var2 into var1 (e.g. var1 = var 2).

Script usage

copy_variable <var1>,<var2>
Script parameters
  • var1 – The variable to copy to.

  • var2 – The variable to copy from.

CreateNpcAction

Create an NPC object and adds it to the game’s current list of NPC’s.

Script usage

create_npc <npc_slug>,<tile_pos_x>,<tile_pos_y>[,<animations>][,<behavior>]
Script parameters
  • npc_slug – NPC slug to look up in the NPC database.

  • tile_pos_x – X position to place the NPC on.

  • tile_pos_y – Y position to place the NPC on.

  • animations – Sprite of the NPC. Deprecated in favor of the JSON.

  • behavior – Behavior of the NPC (e.g. “wander”). Unused for now.

DelayedTeleportAction

Set teleport information.

Teleport will be triggered during screen transition.

Only use this if followed by a transition.

Script usage

delayed_teleport <map_name>,<position_x>,<position_y>
Script parameters
  • map_name – Name of the map to teleport to.

  • position_x – X position to teleport to.

  • position_y – Y position to teleport to.

DialogAction

Open a single dialog and waits until it is closed.

You may also use special variables in dialog events. Here is a list of available variables:

  • ${{name}} - The current player’s name.

Script usage

dialog <text>,<avatar>
Script parameters
  • text – Text of the dialog.

  • avatar – Monster avatar. If it is a number, the monster is the corresponding monster slot in the player’s party. If it is a string, we’re referring to a monster by name.

DialogChainAction

Open a dialog and waits.

Other dialog chains will add text to the dialog without closing it. Dialog chains must be ended with the ${{end}} keyword.

You may also use special variables in dialog events. Here is a list of available variables:

  • ${{name}} - The current player’s name.

  • ${{end}} - Ends the dialog chain.

Script usage

dialog_chain <text>,<avatar>
Script parameters
  • text – Text of the dialog.

  • avatar – Monster avatar. If it is a number, the monster is the corresponding monster slot in the player’s party. If it is a string, we’re referring to a monster by name.

DialogChoiceAction

Ask the player to make a choice.

Script usage

dialog_choice <choices>,<variable>
Script parameters
  • choices – List of possible choices, separated by a colon “:”.

  • variable – Variable to store the result of the choice.

EvolveMonstersAction

Evolve all monsters in the player’s party for a evolutionary path.

Script usage

evolve_monsters <path>
Script parameters

path – Name of the intended evolution.

FadeoutMusicAction

Fade out the music over a set amount of time in milliseconds.

Script usage

fadeout_music <duration>
Script parameters

duration – Number of milliseconds to fade out the music over.

GetPlayerMonsterAction

Select a monster in the player party and store its id in a variable.

Script usage

get_player_monster <variable_name>
Script parameters

variable_name – Name of the variable where to store the monster id.

ModifyNpcAttributeAction

Modify the given attribute of the npc by modifier.

By default this is achieved via addition, but prepending a ‘%’ will cause it to be multiplied by the attribute.

Script usage

modify_npc_attribute <npc_slug>,<name>,<value>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • name – Name of the attribute to modify.

  • value – Value of the attribute modifier.

ModifyPlayerAttributeAction

Modify the given attribute of the player character by modifier.

By default this is achieved via addition, but prepending a ‘%’ will cause it to be multiplied by the attribute.

Script usage

modify_player_attribute <name>,<value>
Script parameters
  • name – Name of the attribute to modify.

  • value – Value of the attribute modifier.

NpcFaceAction

Make the NPC face a certain direction.

Script usage

npc_face <npc_slug>,<direction>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • direction – Direction to face. It can be: “left”, “right”, “up”, “down”, “player” or a npc slug.

NpcMoveAction

Relative tile movement for NPC.

This action blocks until the destination is reached.

Script usage

npc_move <npc_slug>,<move>...
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • move – A tuple with format <direction> [amount_of_tiles] where direction can be one of “up”, “down”, “left” and “right” and amount_of_tiles is the number of tiles moved in that direction, being 1 by default. Several movements can be passed, that will be executed one after the other. For example: up 10, down 5, left 5.

NpcRun

Set the NPC movement speed to the global run speed.

Script usage

npc_run <npc_slug>
Script parameters

npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

NpcSpeed

Set the NPC movement speed to a custom value.

Script usage

npc_speed <npc_slug> <speed>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • speed – Speed amount.

NpcWalk

Set the NPC movement speed to the global walk speed.

Script usage

npc_walk <npc_slug>
Script parameters

npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

NpcWanderAction

Make an NPC wander around the map.

Script usage

npc_wander <npc_slug> <frequency>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • frequency – Frequency of movements.

OpenShopAction

Open the shop menu for a NPC.

Script usage

open_shop <npc_slug>
Script parameters

npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

PathfindAction

Pathfind the player / npc to the given location.

This action blocks until the destination is reached.

Script usage

pathfind <npc_slug>
Script parameters

npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

PauseMusicAction

Pause the current music playback.

Script usage

pause_music

PlayMapAnimationAction

Play a map animation at a given position in the world map.

Script usage

play_map_animation <animation_name> <duration> <loop> "player"
play_map_animation <animation_name> <duration> <loop> <tile_pos_x> <tile_pos_y>
Script parameters
  • animation_name – The name of the animation stored under resources/animations/tileset. For example, an animation called “grass” will load frames called “grass.xxx.png”.

  • duration – The duration of each frame of the animation in seconds.

  • loop – Can be either “loop” or “noloop” to loop the animation.

  • tile_pos – Can be either an x,y coordinate or “player” to draw the animation at the player’s location.

PlayMusicAction

Play a music file from “resources/music/”.

Script usage

play_music <filename>
Script parameters

filename – Music file to load.

PlaySoundAction

Play a sound from “resources/sounds/”.

Script usage

play_sound <filename>
Script parameters

filename – Sound file to load.

PlayerFaceAction

Make the player face a certain direction.

Script usage

player_face <direction>
Script parameters

direction – Direction to face. It can be a npc slug to face or one of “left”, “right”, “up”, or “down”.

PlayerResumeAction

Make the player resume movement.

Script usage

player_resume

PlayerStopAction

Make the player stop moving.

Script usage

player_stop

QuitAction

Completely quit the game.

Script usage

quit

RandomEncounterAction

Randomly start a encounter.

Randomly starts a battle with a monster defined in the “encounter” table in the “monster.db” database. The chance that this will start a battle depends on the “encounter_rate” specified in the database. The “encounter_rate” number is the chance walking in to this tile will trigger a battle out of 100. “total_prob” is an optional override which scales the probabilities so that the sum is equal to “total_prob”.

Script usage

random_encounter <encounter_slug>[,total_prob]
Script parameters
  • encounter_slug – Slug of the encounter list.

  • total_prob – Total sum of the probabilities.

RemoveMonsterAction

Remove a monster from the given trainer’s party if the monster is there.

Monster is determined by instance_id, which must be passed in a game variable.

Script usage

remove_monster <instance_id>[,trainer_slug]
Script parameters
  • instance_id – Id of the monster.

  • trainer_slug – Slug of the trainer. If no trainer slug is passed it defaults to the current player.

RemoveNpcAction

Remove an NPC object from the list of NPCs.

Script usage

remove_npc <npc_slug>
Script parameters

npc_slug – Npc slug name (e.g. “npc_maple”).

RenameMonsterAction

Open the monster menu and text input screens to rename a selected monster.

Script usage

rename_monster

RenamePlayerAction

Open the text input screen to rename the player.

Script usage

rename_player

RumbleAction

Rumble available controllers with rumble support.

Script usage

rumble <duration>,<power>
Script parameters
  • duration – Time in seconds to rumble for.

  • power – Percentage of power to rumble.

ScreenTransitionAction

Initiate a screen transition.

Script usage

screen_transition <transition_time>
Script parameters

transition_time – Transition time in seconds.

SetInventoryAction

Overwrite the inventory of the npc or player.

Script usage

set_inventory <npc_slug>,<inventory_slug>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • inventory_slug – Slug of an inventory.

SetMonsterFlairAction

Set a monster’s flair to the given value.

Script usage

set_monster_flair <slot>,<category>,<name>
Script parameters
  • slot – Slot of the monster in the party.

  • category – Category of the monster flair.

  • name – Name of the monster flair.

SetMonsterHealthAction

Change the hp of a monster in the current player’s party.

Script usage

set_monster_health [slot][,health]
Script parameters
  • slot – Slot of the monster in the party. If no slot is specified, all monsters are healed.

  • health – A float value between 0 and 1, which is the percent of max hp to be restored to. If no health is specified, the hp is maxed out.

SetMonsterLevelAction

Change the level of a monster in the current player’s party.

Script usage

set_monster_level [slot][,level]
Script parameters
  • slot – Slot of the monster in the party. If no slot is specified, all monsters are leveled.

  • level – Number of levels to add. Negative numbers are allowed.

SetMonsterStatusAction

Change the status of a monster in the current player’s party.

Script usage

set_monster_status [slot][,status]
Script parameters
  • slot – Slot of the monster in the party. If no slot is specified, all monsters are modified.

  • status – Status to set. If no status is specified, the status is cleared.

SetNpcAttributeAction

Set the given attribute of the npc to the given value.

Script usage

set_npc_attribute <npc_slug>,<name>,<value>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • name – Name of the attribute.

  • value – Value of the attribute.

SetPlayerAttributeAction

Set the given attribute of the player character to the given value.

Script usage

set_player_attribute <name>,<value>
Script parameters
  • name – Name of the attribute.

  • value – Value of the attribute.

SetVariableAction

Set the key in the player.game_variables dictionary.

Script usage

set_variable <variable>:<value>
Script parameters
  • variable – Name of the variable.

  • value – Value of the variable.

SpawnMonsterAction

Breed a new monster.

Add a new monster, created by breeding the two given mons (identified by instance_id, stored in a variable) and adds it to the given character’s party (identified by slug). The parents must be in either the trainer’s party, or a storage box owned by the trainer.

Script usage

spawn_monster <npc_slug>,<breeding_mother>,<breeding_father>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • breeding_mother – Id of the mother monster.

  • breeding_father – Id of the father monster.

StartBattleAction

Start a battle with the given npc and switch to the combat module.

Script usage

start_battle <npc_slug>
Script parameters

npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

StartCinemaModeAction

Start cinema mode by animating black bars to narrow the aspect ratio.

Script usage

start_cinema_mode

StopCinemaModeAction

Stop cinema mode by animating black bars back to the normal aspect ratio.

Script usage

stop_cinema_mode

StoreMonsterAction

Store a monster in a box.

Save the player’s monster with the given instance_id to the named storage box, removing it from the player party.

Script usage

store_monster <monster_id>,<box>
Script parameters
  • monster_id – Id of the monster to store.

  • box – Box where the monster will be stored.

TeleportAction

Teleport the player to a particular map and tile coordinates.

Script usage

teleport <map_name>,<x>,<y>
Script parameters
  • map_name – Name of the map to teleport to.

  • x – X coordinate of the map to teleport to.

  • y – Y coordinate of the map to teleport to.

TeleportFaintAction

Teleport the player to the point in the teleport_faint variable.

Usually used to teleport to the last visited Tuxcenter, as when all monsters in the party faint.

Script usage

teleport_faint

TransitionTeleportAction

Combines the “teleport” and “screen_transition” actions.

Perform a teleport with a screen transition. Useful for allowing the player to go to different maps.

Script usage

transition_teleport <map_name>,<x>,<y>,<transition_time>
Script parameters
  • map_name – Name of the map to teleport to.

  • x – X coordinate of the map to teleport to.

  • y – Y coordinate of the map to teleport to.

  • transition_time – Transition time in seconds.

TranslatedDialogAction

Open a dialog window with translated text according to the passed translation key. Parameters passed to the translation string will also be checked if a translation key exists.

You may also use special variables in dialog events. Here is a list of available variables:

  • ${{name}} - The current player’s name.

Parameters following the translation name may represent one of two things: If a parameter is var1=value1, it represents a value replacement. If it’s a single value (an integer or a string), it will be used as an avatar image. TODO: This is a hack and should be fixed later on, ideally without overloading the parameters.

Script usage

translated_dialog <text>,<avatar>
translated_dialog <text>[,var1=value1]...
Script parameters
  • text – Text of the dialog.

  • avatar – Monster avatar. If it is a number, the monster is the corresponding monster slot in the player’s party. If it is a string, we’re referring to a monster by name.

TranslatedDialogChainAction

Open a chain of dialogs in order.

Dialog chain must be ended with the ${{end}} keyword. You may also use special variables in dialog events. Here is a list of available variables:

  • ${{name}} - The current player’s name.

  • ${{end}} - Ends the dialog chain.

Parameters following the translation name may represent one of two things: If a parameter is var1=value1, it represents a value replacement. If it’s a single value (an integer or a string), it will be used as an avatar image. TODO: This is a hack and should be fixed later on, ideally without overloading the parameters.

Script usage

translated_dialog_chain <text>,<avatar>
Script parameters
  • text – Text of the dialog.

  • avatar – Monster avatar. If it is a number, the monster is the corresponding monster slot in the player’s party. If it is a string, we’re referring to a monster by name.

TranslatedDialogChoiceAction

Ask the player to make a choice.

Script usage

translated_dialog_choice <choices>,<variable>
Script parameters
  • choices – List of possible choices, separated by a colon “:”.

  • variable – Variable to store the result of the choice.

UpdateInventoryAction

Update the inventory of the npc or player.

Overwrites the quantity of an item if it’s already present, but leaves other items alone.

Script usage

update_inventory <npc_slug>,<inventory_slug>
Script parameters
  • npc_slug – Either “player” or npc slug name (e.g. “npc_maple”).

  • inventory_slug – Slug of an inventory.

VariableMathAction

Perform a mathematical operation on the player.game_variables dictionary.

Optionally accepts a fourth parameter to store the result, otherwise it is stored in var1.

Script usage

variable_math <var1>,<operation>,<var2>,<result>
variable_math <var1>,<operation>,<var2>
Script parameters
  • var1 – First operand.

  • operation – Operator symbol.

  • var2 – Second operand.

  • result – Variable where to store the result. If missing, it will be var1.

WaitAction

Block event chain for some time.

Script usage

wait <seconds>
Script parameters

seconds – Time in seconds for the event engine to wait for.

WaitForSecsAction

Pause the event engine for a number of seconds.

Script usage

wait_for_secs <seconds>
Script parameters

seconds – Time in seconds for the event engine to wait for.

WithdrawMonsterAction

Pull a monster from the given trainer’s storage and puts it in their party.

Note

If the trainer’s party is already full then the monster will be deposited into the default storage box automatically.

Script usage

withdraw_monster <trainer>,<monster_id>
Script parameters
  • trainer – The trainer slug.

  • monster_id – The id of the monster to pull.