Event Reference
Introduction
This page is a reference for all the available actions and conditions available in Tuxemon. You can use this reference to create new map events for your own maps. All action and condition parameters are separated with a comma (,).
Condition Reference
Here is a list of currently implemented conditions. New event conditions can be created by creating a new method under the core.components.event.condition module:
true
The true condition will always evaluate to *True* (unless the "not" operator is used)
Parameters
None
Examples
is true
not true
player_at
Check to see if the player is inside the event's area. This event will check the event object's X, Y, Width, and Height properties and checks to see if the player is within those bounds. That includes event areas that are greater than one tile in size. You can optionally include an x,y parameter to specify a single tile location.
Parameters
x: X tile coordinates that the player is at (optional)
y: Y tile coordinate that the player is at (optional)
Examples
is player_at
is player_at 4,3
player_facing
Check to see if the player is facing: up, down, left or right.
Parameters
direction: Direction to check for: (up, down, left, right)
Examples
is player_facing up
not player_facing down
player_facing_tile
Check to see if the player is facing a particular tile. This event will check the event object's X, Y coordinates for the tile to check for.
Parameters
None
Examples
is player_facing_tile
player_moved
Checks to see if the player has just moved. If the player is standing still, this condition will return False.
Parameters
None
Examples
is player_moved
not player_moved
has_monster
Checks to see the player is has a monster in his party.
Parameters
monster_slug: The slug of the monster to check for.
Examples
is has_monster txmn_pigabyte
inventory_contains
Not yet implemented
Parameters
item: The item name to check for.
Examples
is inventory_contains Potion
combat_started
Check to see if combat has currently started.
Parameters
None
Examples
is combat_started
button_pressed
Check to see if a particular key has been pressed. E.g. K_RETURN.
Parameters
key: A pygame key constant such as K_RETURN. For a list of all possible keys, refer to the Pygame Key Page
Examples
is button_pressed K_RETURN
is button_pressed K_ESCAPE
not button_pressed K_SPACE
dialog_open
Check to see if a dialog window is currently open.
Parameters
None
Examples
is dialog_open
not dialog_open
variable_set
Check to see if variable_name has been set to value.
Parameters
variable_name:value: A key, value pair of the variable to look up and the expected value.
Examples
is variable_set battle_won:yes
not variable_set current_badges:4
is variable_set talked_to_prof:false
npc_exists
Check to see if an NPC exists on the current map with npc_name.
Parameters
npc_name: The name of the NPC on the current map.
Examples
not npc_exists Apple
npc_at
Check to see if the npc is inside the event's area. This event will check the event object's X, Y, Width, and Height properties and checks to see if the npc is within those bounds. That includes event areas that are greater than one tile in size. You can optionally include an x,y parameter to specify a single tile location.
Parameters
name: The name of the NPC.
x: X tile coordinates that the player is at (optional)
y: Y tile coordinate that the player is at (optional)
Examples
is npc_at Maple
is npc_at Maple,4,3
npc_facing
Check to see if the npc is facing: up, down, left or right.
Parameters
name: The name of the NPC.
direction: Direction to check for: (up, down, left, right)
Examples
is npc_facing Maple,up
not npc_facing Maple,down
npc_facing_tile
Check to see if the npc is facing a particular tile. This event will check the event object's X, Y coordinates for the tile to check for.
Parameters
name: The name of the NPC.
Examples
is npc_facing_tile Maple
facing_npc
Check to see if the player is facing an NPC with the name npc_name.
Parameters
npc_name: The name of the NPC on the current map.
Examples
is facing_npc Apple
party_size
Perform a check on the player's party size. The check parameter can be: equals, less_than, or greater_than.
Parameters
check: The check to run against the party size. Can be: equals, less_than, or greater_than.
party_size: The size of the party to check against.
Examples
is party_size less_than,1
not party_size equals,0
is party_size greater_than,4
music_playing
Check to see if the specified music file is currently playing.
Parameters
music_file: The music file to check.
Examples
is music_playing 472452_8-Bit-Ambient.ogg
Action Reference
Here is a list of currently supported actions. New event actions can be created by creating a new function under the core.components.event.Action class:
teleport
Teleports the player to a given position on a map. This teleport is immediate and does not have any transition animation.
Parameters
map_name: The map file to teleport the player to.
x: The X-tile coordinate to teleport the player to.
y: The Y-tile coordinate to teleport the player to.
Examples
teleport map1.tmx,3,4
teleport room1.tmx,8,1
transition_teleport
Teleports the player to a given position on a map with a screen transition over x seconds.
Parameters
map_name: The map file to teleport the player to.
x: The X-tile coordinate to teleport the player to.
y: The Y-tile coordinate to teleport the player to.
transition_time: The time in seconds the transition will last.
Examples
teleport map2.tmx,1,6,1.5
teleport room1.tmx,8,1,4
call_event
Executes the actions from another event, ignoring its conditions. This can be especially useful for scenarios where you might need multiple sets of conditions that could be true, such as executing an action when the player is at a certain position OR has a certain item in their inventory.
Parameters
event_id: The id of the event whose actions should be executed.
Examples
call_event 11
call_event 8
set_variable
Sets an arbitrary variable to a particular value. This action is good for seeing if battles with NPCs have been fought or not. These variables are also saved when the player saves the game.
Parameters
variable_name:value: A key, value pair of the variable_name to set with value.
Examples
set_variable battle_won:yes
set_variable talked_to_prof:true
play_sound
Plays an audio file located under "sounds/".
Parameters
filename: The name of the sound file to play under "sounds/"
Examples
play_sound combat/falling_Macro.ogg
play_music
Plays an audio file located under "music/" on a loop.
Parameters
filename: The name of the music file to play under "music/"
Examples
play_music 472452_8-Bit-Ambient.ogg
player_face
Makes the player face a particular direction. Parameter can be set to: left, right, up, or down.
Parameters
direction: Direction to make the player face. Can be set to: left, right, up, or down.
Examples
player_face left
player_face up
player_stop
Stops the player from moving until player_resume is called.
Parameters
None
Examples
player_stop
player_resume
Resumes the player's ability to move. Usually used after the player_stop action.
Parameters
None
Examples
player_resume
pause_music
Pauses the currently playing music.
Parameters
None
Examples
pause_music
fadeout_music
Fades out music over x seconds.
Parameters
time_seconds: Time in seconds to fade out the currently playing music.
Examples
fadeout_music 2
dialog
Opens the dialog box with provided text. For line breaks, use the \n character. You may also use special variables in dialog events. If you have multiple dialog commands they will display sequentially. Using $Template:End does nothing as it used to denote the end of a dialog chain. Here is a list of available variables:
$Template:Name- The current player's name.
Parameters
text: The text to display in a dialog window.
Examples
dialog Red:\n This is some dialog!
dialog $Template:Name:\n Hello there! \nHow are you?
translated_dialog
Opens the dialog box with translated text for a given key found in resources/db/locale/<locale>.json. Optional variable replacement will also be translated if the value is a key in the locale file. For line breaks, use the \n character. If you have multiple translated_dialog commands they will display sequentially. Using $Template:End does nothing as it used to denote the end of a dialog chain. You may also use special variables in dialog events. Here is a list of available variables:
$Template:Name- The current player's name.
Parameters
dialog_key: The translated text for a given key found in resources/db/locale/<locale>.json to display in a dialog window.
parameters: Optional comma-separated var=value parameters to replace variables in the translation text. The value can either be text or a key found in resources/db/locale/<locale>.json.
Examples
translated_dialog received_x,name=a brand new car!
translated_dialog received_x,name=item_potion
translated_dialog combat_fainted,name=$Template:Name
translated_dialog combat_opponent_call_tuxemon,user=$Template:Name,name=some guy
dialog_chain
Deprecated. Use [#dialog dialog]
translated_dialog_chain
Deprecated. Use [#translated_dialog translated_dialog]
dialog_choice
Asks the player to select a choice.
Parameters
choices: The possible choices separated by colons.
variable: The variable to store the answer.
Examples
dialog_choice Yes:No:Maybe,myvariable
translated_dialog_choice
Asks the player to select a choice. The translations for the text are looked up based on a given key.
Parameters
choice_keys: Keys to reference translated text choices separated by colons.
variable: The variable to store the answer which will be the key for the translated text.
Examples
dialog_choice yes:no,myvariable
screen_transition
Fades the screen to black and back over x seconds.
Parameters
transition_time: Time in seconds to fade the screen to black.
Examples
screen_transition 2
create_npc
Creates an NPC and places them on the current map.
Parameters
name: The name of the NPC to create. This NPC should exist in resources/db/npc in JSON format.
tile_pos_x: The X-tile coordinate to place the NPC.
tile_pos_y: The Y-tile coordinate to place the NPC.
animations: The name of the sprite to use for the animations in resources/sprites.
behavior: The NPC's movement behavior. Currently not implemented.
==== Examples ====
create_npc Maple,2,3,maple,wander
create_npc Pine,1,6,maple,stand
remove_npc
Removes an NPC from the current map.
Parameters
name: The name of the NPC to remove.
==== Examples ====
remove_npc Maple
remove_npc Pine
npc_face
Makes the npc face a particular direction. Parameter can be set to: left, right, up, or down.
Parameters
name: The name of the npc.
direction: Direction to make the player face. Can be set to: left, right, up, or down.
Examples
npc_face Maple,left
npc_face Pine,up
pathfind
Moves an NPC to a certain tile on the map.
Parameters
name: The name of the NPC to be moved.\n
tile_pos_x: The X-tile coordinate to have the NPC to walk to.
tile_pos_y: The Y-tile coordinate to have the NPC to walk to.
==== Examples ====
pathfind Maple,2,3
pathfind Pine,1,6
start_battle
Start a battle with an NPC defined in resources/db/npc.
Here is an example NPC file:
resources/db/npc/maple.json
json
{
"monsters": [
{
"attack": 50,
"defense": 7,
"name": "Snowball",
"special_attack": 9,
"level": 5,
"monster_slug": 1,
"hp": 50,
"speed": 7,
"special_defense": 7,
"exp_give_mod": 3,
"exp_req_mod": 27
}
],
"id": 1,
"name": "Maple"
}
Parameters
npc_slug: The NPC's slug as defined in the NPC's JSON file in resources/db/npc.
Examples
start_battle npc_maple
add_monster
Add the specified monster to the player's party.
Parameters
monster_name: The name of the monster to add as defined in the monster JSON under resources/db/monster.
monster_lvl: The level of the monster to start at.
Examples
add_monster txmn_fruitera,10
remove_monster
Removes the specified monster to the player's party.
Parameters
monster_slug: The slug of the monster to add as defined in the monster JSON under resources/db/monster.
Examples
remove_monster txmn_fruitera
random_encounter
Randomly start a battle based on the encounter group looked up via the encounter_id. Encounter groups contain a list of monsters that can be encountered as well as their level and encounter rate. In most circumstances you will pair this action with the player_at and player_moved conditions.
Here is an example encounter file:
resources/db/encounter/1.json
json
{
"id": 1,
"monsters": [
{
"monster_slug": "txmn_bigfin",
"encounter_rate": 10,
"level_range": [
1,
6
]
},
{
"monster_slug": "txmn_dandylion",
"encounter_rate": 10,
"level_range": [
1,
6
]
},
{
"monster_slug": "txmn_tux",
"encounter_rate": 10,
"level_range": [
1,
6
]
}
]
}
Parameters
encounter_id: The id of the encounter JSON file to use for random battles under resources/db/encounter.
Examples
random_encounter 1
play_map_animation
Plays an animation on the map. The position parameter can also be player if you want to draw the animation at the player's location. Loop can be either loop or noloop.
Parameters
animation_name: The name of the animation to play under resources/animations/tileset.
duration: The amount of time in seconds between each frame.
loop: Whether or not to loop the animation. Can be either loop or noloop to loop the animation.
position: The position to draw the animation. Can either be an x,y coordinate or player to draw the animation over the player.
Examples
play_map_animation grass,0.1,noloop,player
play_map_animation sign01,0.4,loop,33,10
wait_for_input
Pauses execution of all events until the given input is received.
Parameters
input: The pygame input to wait for.
Examples
wait_for_input K_RETURN
wait_for_input K_Q
wait_for_secs
Pauses execution of all events for the given amount of time in seconds.
Parameters
seconds: The amount of time in seconds to wait for.
Examples
wait_for_secs 2.0
wait_for_secs 5.2