Difference between revisions of "Event Reference Action"

From Tuxepedia
Jump to navigation Jump to search
 
(28 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Here is a list of currently supported actions. New event actions can be created by creating a new page under the '''tuxemon/event/actions''':
== Actions ==


== access_pc ==  
=== AccessPCAction ===
Change to PCState. This action transitions to the PCState, typically used for viewing player character details or an NPC as if it were a PC.
Change to PCState.


This action transitions to the PCState, typically used for viewing
player character details or an NPC as if it were a PC.
'''Usage'''
<code>
access_pc <character_slug>
</code>
'''Parameters'''
'''Parameters'''
* <code>character_slug</code>: The name or identifier of the obstacle.
* <code>character_slug</code>: The slug of the character (NPC) to view in PCState.
 
=== AddCollisionAction ===
Handles the addition of a collision zone associated with a specific
label.
Optionally, with coordinates provided, it can block a specific tile
within the map.


'''Examples'''
'''Usage'''
* <code>access_pc player</code>
<code>


== add_collision ==
add_collision <label>[,x][,y]
Handles the addition of a collision zone associated with a specific label. Optionally, with coordinates provided, it can block a specific tile within the map.


</code>
'''Parameters'''
'''Parameters'''
* <code>label</code>: The name or identifier of the obstacle.
* <code>label</code>: The name or identifier of the obstacle.
Line 18: Line 33:
* <code>y</code>: (Optional) Y-coordinate of the specific tile to block.
* <code>y</code>: (Optional) Y-coordinate of the specific tile to block.


'''Examples'''
=== AddComboAction ===
* <code>add_collision obstacle,6,8</code>
Registers one or more combos from a YAML string.
* <code>add_collision wall</code> (in this case must exist a collision zone in the .tmx file)
 
'''Usage'''
<code>
 
add_combo <yaml_data>
 
</code>
'''Parameters'''
* <code>yaml_file</code>: Name of the YAML file (without extension) located in the mods folder.
 
=== AddContactsAction ===
Add contact to the app.
npc_slug must have the msgid inside the PO.
 
'''Usage'''
<code>


== add_contacts ==
add_contacts <character>,<npc_slug>[,relation][,strength],
Add contact to the app (Nu Phone). npc_slug must have the msgid inside the PO.
[,steps][,decay_rate][,decay_threshold]


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
Line 32: Line 63:
* <code>steps</code>: amount of steps, default character steps
* <code>steps</code>: amount of steps, default character steps
* <code>decay_rate</code>: decay rate of the relationship, default 0.01, capped 1.0
* <code>decay_rate</code>: decay rate of the relationship, default 0.01, capped 1.0
* <code>decay_threshold</code>: threshold of steps after which the decay triggers, default 500
* <code>decay_threshold</code>: threshold of steps after which the decay triggers,
default 500


'''Examples'''
=== AddHeldItemAction ===
* <code>add_contacts player,npc_maple</code>
Adds a held item to a specific monster.
 
'''Usage'''
<code>


== add_held_item ==
add_held_item <variable>,<item>
Adds a held item to a specific monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>item</code>: Slug of the item (e.g. "potion").
* <code>item</code>: Slug of the item (e.g. "potion").


'''Examples'''
=== AddItemAction ===
* <code>add_held_item variable,item</code>
Add an item to the specified trainer's inventory.
 
'''Usage'''
<code>


== add_item ==
add_item <item_slug>[,quantity][,npc_slug]
Add the specified item to the player's inventory.


</code>
'''Parameters'''
'''Parameters'''
* <code>item_name</code>: Monster slug to look up in the monster database or name variable where it's stored the mon_slug.
* <code>item_slug</code>: Item name to look up in the item database.
* <code>quantity</code>: Quantity of the item to add or to reduce. By default it is 1. (optional)
* <code>quantity</code>: Quantity of the item to add or to reduce. By default it is 1.
* <code>trainer_slug</code>: Slug of the trainer that will receive the item. It defaults to the current player. (optional)
* <code>npc_slug</code>: Slug of the trainer that will receive the item. It
defaults to the current player.


'''Examples'''
=== AddMonsterAction ===
* <code>add_item hatchet</code>
Add a monster to the specified trainer's party if there is room.
* <code>add_item hatchet,2</code>
 
* <code>add_item hatchet,2,npc_maple</code>
'''Usage'''
<code>


== add_monster ==
add_monster <mon_slug>,<mon_level>[,npc_slug][,exp_mod][,money_mod]
Add the specified monster to the player's party.


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_slug</code>: Monster slug to look up in the monster database.
* <code>mon_slug</code>: Monster slug to look up in the monster database or name variable
* <code>monster_level</code>: Level of the added monster.  
where it's stored the mon_slug
* <code>trainer_slug</code>: Slug of the trainer that will receive the monster. It defaults to the current player. (optional)
* <code>mon_level</code>: Level of the added monster.
* <code>exp_mod</code>: Experience modifier. (optional)
* <code>npc_slug</code>: Slug of the trainer that will receive the monster. It
* <code>money_mod</code>: Money modifier. (optional)
defaults to the current player.
* <code>exp_mod</code>: Experience modifier
* <code>money_mod</code>: Money modifier
 
=== AddStepTrackerAction ===
Adds a step tracker to a specific character.


'''Examples'''
'''Usage'''
* <code>add_monster fruitera,10</code>
<code>
* <code>add_monster fruitera,10,npc_maple,10,27</code>


== add_step_tracker ==
add_step_tracker <character>,<tracker_id>,<countdown>[,<milestones>
Adds a step tracker to a specific character.
[,<auto_reset>[,<initial_countdown>]]]


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or an NPC slug name (e.g., "npc_maple").
* <code>character</code>: Either "player" or an NPC slug name (e.g., "npc_maple").
* <code>tracker_id</code>: Unique name for identifying the step tracker.
* <code>tracker_id</code>: Unique name for identifying the step tracker.
* <code>countdown</code>: Number of steps before the tracker reaches zero.
* <code>countdown</code>: Number of steps before the tracker reaches zero.
* <code>milestones</code>: (optional) Step milestones, separated by : (e.g., "500:250:100").
* <code>milestones (optional)</code>: Step milestones, separated by : (e.g., "500:250:100").
* <code>auto_reset (optional)</code>: "true" or "false" to enable or disable automatic reset.
Defaults to false.
* <code>initial_countdown (optional)</code>: Full cycle length. Defaults to countdown value.
 
=== AddTechAction ===
Adds a tech to a specific monster.


'''Examples'''
'''Usage'''
* <code>add_step_tracker npc_maple,tracker_id,500</code>
<code>
* <code>add_step_tracker npc_maple,tracker_id,500,500:250:100</code>


== add_tech ==
add_tech <variable>,<technique>[,power][,potency][,accuracy]
Adds a tech to a specific monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where the monster UUID is stored.
* <code>variable</code>: Name of the variable where the monster UUID is stored.
Line 98: Line 148:


'''Examples'''
'''Examples'''
* <code>get_player_monster name_variable</code>
* "add_tech monster_id,flamethrower"
* <code>add_tech name_variable,bullet</code>
* "add_tech monster_id,flamethrower,2.5,0.8,0.95"


== add_tracker ==
=== AddTrackerAction ===
Add tracker.
Add tracker.


'''Usage'''
<code>
add_tracker <character>,<location>[,visited]
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>location</code>: location name (e.g. "paper_town").
* <code>location</code>: location name (e.g. "paper_town").
* <code>visited</code>: if it has been visited or not (true or false), default True
* <code>visited</code>: Optional string flag indicating if the location was visited.
Accepts "true", "1", "yes" for True (case-insensitive).
Defaults to True if omitted.
 
=== AdjustBillPenaltyAction ===
Applies a penalty to a bill for a character — either interest or late fee.
 
'''Usage'''
<code>
 
adjust_bill_penalty <character_slug>,<bill_slug>,<method>
 
</code>
'''Parameters'''
* <code>character_slug</code>: Slug of the character (e.g. "player", "npc_maple").
* <code>bill_slug</code>: Slug of the bill to modify.
* <code>method</code>: Either "interest" or "fee".


'''Examples'''
'''Examples'''
* <code>add_tracker player,paper_town</code>
* adjust_bill_penalty player,electric_bill,interest
* adjust_bill_penalty npc_maple,rent,fee
 
=== AFKThresholdAction ===
Add, modify, or remove AFK thresholds.
 
'''Usage'''
<code>
 
afk_threshold <action> <level> [duration]
 
</code>
'''Parameters'''
* <code>action</code>: One of "add", "modify", "remove"
* <code>level</code>: The threshold name (string)
* <code>duration</code>: Required for "add" and "modify" (float, seconds)
 
=== BoundaryMoveAction ===
Moves the current active boundary by the given delta values.
 
'''Usage'''
<code>
 
boundary_move  <boundary_name>[,dx:dy]
 
</code>
'''Parameters'''
* <code>boundary_name</code>: Required. The name to assign to the boundary
* <code>dx</code>: The change in the x-coordinate.
* <code>dy</code>: The change in the y-coordinate.
 
=== BoundaryResizeAction ===
Resizes the current active boundary.
 
'''Usage'''
<code>
 
boundary_resize <boundary_name>[,values]
 
</code>
'''Parameters'''
* <code>boundary_name</code>: Required. The name to assign to the boundary
(e.g., "safe_zone", "event").
* <code>values</code>: A colon-separated string of integers:
* For rectangle: dx:dy
* For circle: delta
 
=== BoundarySetAction ===
Sets or replaces the current boundary with a new one, or resets to default
if no parameters are given.
 
'''Usage'''
<code>
 
boundary_set <boundary_name>[,shape][,values]
 
</code>
'''Parameters'''
* <code>boundary_name</code>: Required. The name to assign to the boundary
(e.g., "safe_zone", "event").
* <code>shape</code>: Optional. Either "rectangle" or "circle".
* <code>values</code>: Optional. A colon-separated string of integers:
* For "rectangle": x0:x1:y0:y1
* For "circle": cx:cy:radius


== breeding ==
=== BreedingAction ===
Select a monster in the player party filtered by gender and store its id in a variables (breeding_father or breeding_mother)
Select a monster in the player party filtered by gender and store its
id in a variables (breeding_father or breeding_mother)


'''Usage'''
<code>
breeding <gender>
</code>
'''Parameters'''
'''Parameters'''
* <code>gender</code>: Gender (male or female).
* <code>gender</code>: Gender (male or female).


'''Examples'''
=== CallEventAction ===
* <code>breeding male</code>
Execute the specified event's actions by name.
* <code>breeding female</code>
 
'''Usage'''
<code>


== call_event ==
call_event <event_name>
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.


</code>
'''Parameters'''
'''Parameters'''
* <code>event_name</code>: The name of the event whose actions should be executed.
* <code>event_name</code>: The name of the event whose actions will be executed.
 
=== CameraManageAction ===
Adds, removes, or switches/follows a camera in the camera manager.


'''Examples'''
'''Usage'''
* <code>call_event name_event</code>
<code>


== camera_follow ==
camera_manage add [name] [npc_slug]
Centers the camera on a specified NPC or the original entity.
camera_manage remove [name]
camera_manage follow [name] [npc_slug]


</code>
'''Parameters'''
'''Parameters'''
* <code>npc_slug</code>: The slug of the character to center the camera on. Defaults to None, which centers the camera on the original entity.
* <code>action</code>: "add", "remove", or "follow"
* <code>camera_name</code>: The identifier for the camera.
* <code>npc_slug</code>: Optional slug of the NPC/entity to follow (used for add/follow).


'''Examples'''
=== CameraModeAction ===
* <code>camera_follow npc_slug</code>
* <code>Change camera mode</code>: freeroaming or fixed.
* <code>camera_follow</code>
 
'''Usage'''
<code>


== camera_mode ==
camera_mode <mode>
Change camera mode: freeroaming or fixed.


</code>
'''Parameters'''
'''Parameters'''
* <code>mode</code>: the camera mode, either "fixed" or "free_roaming".
* <code>mode</code>: The mode of the camera: 'free_roaming' or 'fixed'.


'''Examples'''
=== CameraMoveAction ===
* <code>camera_mode freeroaming</code>
Smoothly move the camera to a specific coordinate or reset it to its original position.
 
'''Usage'''
<code>


== camera_move ==
camera_move <time>,<x>,<y>
Smoothly move the camera to a specific coordinate or reset it to its original position.


</code>
'''Parameters'''
'''Parameters'''
* <code>time</code>: the duration (in seconds) required for the camera to transition to the target position.
* <code>time</code>: the duration (in seconds) required for the camera to transition to the target position.
* <code>x,y</code>: the coordinates where the camera needs to be centered. (optional)
* <code>x,y</code>: the coordinates where the camera needs to be centered.
 
=== CameraPositionAction ===
Move the camera on a coordinate.
 
'''Usage'''
<code>
 
camera_position <x>,<y>
 
</code>
'''Parameters'''
* <code>x,y</code>: the coordinates where the camera needs to be centered.
 
=== CameraShakeAction ===
Shake the camera with a precise intensity and duration.
 
'''Usage'''
<code>
 
camera_shake <intensity>,<duration>
 
</code>
'''Parameters'''
* <code>intensity</code>: The magnitude of the shake effect. A higher value results
in a more pronounced shake, while a lower value produces
a subtler effect (min 0.0, max 3.0).
* <code>duration</code>: The length of time (in seconds) that the shake effect
should last. The method calculates the number of frames
to shake based on an assumed frame rate.


'''Examples'''
=== ChangeBgAction ===
* <code>camera_move 2.0,32,6</code>
Handles the background change within the session, allowing users
to apply a new background color or image dynamically.
 
'''Usage'''
<code>


== camera_position ==
change_bg <background>[,image][,category]
Move the camera on a coordinate.


</code>
'''Parameters'''
'''Parameters'''
* <code>x,y</code>: the coordinates where the camera needs to be centered. (optional)
* <code>background</code>: The background identifier, which can be:
* A file name located in `gfx/ui/background/`
* An RGB color formatted as `R:G:B` (e.g., `255:0:0`)
* <code>image</code>: An optional image identifier, which can be:
* An item slug (stored in `gfx/items`)
* A direct file path
* <code>category</code>: The category of the image (e.g., item or image.
If omitted, defaults to "background".
 
* <code>Notes</code>:
* Background images must be in `gfx/ui/background/`.
* Background dimensions must be 256x144 pixels.
 
=== ChangeBgNpcAction ===
Displays an NPC sprite over a background image, using the NPC's base
sprite located in ``gfx/sprites/player/<slug>.png``.


'''Examples'''
'''Usage'''
* <code>camera_position 6,9</code>
<code>
* <code>camera_position</code>


== camera_shake ==
change_bg_char <background>,<npc_slug>
Shake the camera with a precise intensity and duration.


</code>
'''Parameters'''
'''Parameters'''
* <code>intensity</code>: the magnitude of the shake effect. A higher value results in a more pronounced shake, while a lower value produces a subtler effect (min 0.0, max 3.0).
* <code>background</code>:  
* <code>duration</code>: the length of time (in seconds) that the shake effect should last. The method calculates the number of frames to shake based on an assumed frame rate.
The background identifier, which must be the name of a file
located in ``gfx/ui/background/`` (without the ``.png``
extension). The background image must match the native
resolution of the game (256x144 pixels).
 
* <code>npc_slug</code>:  
The slug of the NPC to display. A matching sprite file must
* <code>exist at</code>:
 
``gfx/sprites/player/<npc_slug>.png``
 
The sprite will be loaded, scaled, and rendered on top of
the background.
 
* <code>Notes</code>:
* Background images must be located in ``gfx/ui/background/``.
* Background dimensions must be exactly 256x144 pixels.
* NPC sprites are loaded directly from their corresponding PNG
file in ``gfx/sprites/player/``.
* This action always pushes the ``NpcImageState``, which displays
the background and overlays the NPC sprite.
 
=== ChangeBgMonsterAction ===
Displays a monster sprite over a background image, using the
monster's front sprite extracted from its sprite sheet.


'''Examples'''
'''Usage'''
* <code>camera_shake 3.0,2.0</code>
<code>


== change_bg ==
change_bg_monster <background>,<monster_slug>
Change the background.


</code>
'''Parameters'''
'''Parameters'''
* <code>background</code>:
* <code>background</code>: The background identifier, which must be the name of
* it can be the name of the file (see below note)
a file located in `gfx/ui/background/` (without the `.png`
* it can be a RGB color separated by ":" (eg 255:0:0)
extension). The background image must match the native
* <code>image</code>: monster_slug or template_slug or path
resolution of the game (256x144 pixels).
* if path, then "gfx/ui/background/"
* <code>monster_slug</code>: The slug of the monster to display. The monster
* if template (eg. ceo) in "gfx/sprites/player"
must exist in the monster database. Its front sprite will be
* note: the background or image (if not monster or template) must be inside the folder (gfx/ui/background/)
extracted from its sprite sheet and rendered on top of the
* background size: 240x160
background.


* <code>Notes</code>:
* Background images must be located in `gfx/ui/background/`.
* Background dimensions must be exactly 256x144 pixels.
* The monster sprite is taken from the monster's sprite sheet
using the `front_rect` defined in its model.
* This action always pushes the `MonsterImageState`, which
displays the background and overlays the monster sprite.


'''Examples'''
=== ChangeFactionMembershipAction ===
* <code>change_bg gradient_blue,rockitten</code>
Makes an NPC (or player) join or leave a specific faction.
* <code>change_bg gradient_blue,ceo</code>
 
* <code>change_bg gradient_blue</code>
'''Usage'''
* <code>change_bg</code> (stop)
<code>


== change_faction_membership ==
change_faction_membership <character>,<faction_slug>,<status>
Makes an NPC (or player) join or leave a specific faction.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
Line 208: Line 442:
* <code>status</code>: Must be either "join" or "leave", indicating the membership action.
* <code>status</code>: Must be either "join" or "leave", indicating the membership action.


'''Examples'''
=== ChangeStateAction ===
* <code>change_faction_membership npc_maple,faction_slug,join</code>
Change to the specified state (generic).
* <code>change_faction_membership npc_maple,faction_slug,leave</code>
 
This action handles state transitions that do not require specific
additional parameters beyond the state name itself.
 
'''Usage'''
<code>
 
change_state <state_name>
 
</code>
'''Parameters'''
* <code>state_name</code>: The state name to switch to.
 
=== ChangeTasteAction ===
Changes the specified taste (warm or cold) of a monster.
 
'''Usage'''
<code>


== change_taste ==
change_taste <variable>,<type_taste>,<new_taste>
Changes the specified taste (warm or cold) of a monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the game variable containing the monster's UUID.
* <code>variable</code>: Name of the game variable containing the monster's UUID.
* <code>type_taste</code>: Either "warm" or "cold" to indicate which taste to change.
* <code>type_taste</code>: Either "warm" or "cold" to indicate which taste to change.
* <code>new_taste</code>: Slug of the new taste to assign, or "random" to select a new one at random (excluding "tasteless" and the current taste).
* <code>new_taste</code>: Slug of the new taste to assign, or "random" to select a new one
at random (excluding "tasteless" and the current taste).


'''Examples'''
* <code>Notes</code>:
* <code>change_taste name_variable,type_taste,new_taste</code>
* When using "random", the new taste is chosen based on rarity_score weighting.
* When specifying a taste slug, it must exist, match the selected type,
and must not be "tasteless".
* If no valid taste is found during random selection, the taste remains unchanged
and a warning is logged.
 
=== CharFaceAction ===
Make the character face a certain direction.
 
'''Usage'''
<code>


== change_state ==
char_face <character>,<direction>
Change to the specified state (generic). This action handles state transitions that do not require specific additional parameters beyond the state name itself.


</code>
'''Parameters'''
'''Parameters'''
* <code>state_name</code>: The state name to switch to.
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>direction</code>: Direction to face. It can be: "left", "right", "up", "down",
"player" or a character slug.
 
=== CharFacePlayerAction ===
Make an NPC face the player when they come within a specified distance.


'''Examples'''
'''Usage'''
* <code>change_state state_name</code>
<code>


== char_face ==
char_face_player <npc_slug>,<trigger_dist>,<persistent>
Make the character face a certain direction.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>npc_slug</code>: Slug of the NPC that will face the player.
* <code>direction</code>: Direction to make the character's face. Can be set to: <code>left</code>, <code>right</code>, <code>up</code>, <code>down</code>, <code>player</code> or a character slug.
* <code>trigger_dist</code>: Maximum tile distance at which the NPC will begin
facing the player. Defaults to 3.
* <code>persistent</code>: Whether the NPC should continue tracking the player
after the first trigger. Defaults to True.
 
=== CharLookAction ===
Make a character look around.


'''Examples'''
'''Usage'''
* <code>char_face player,down</code>
<code>
* <code>char_face npc_maple,right</code>
* <code>char_face npc_maple,player</code> (Maple faces the player)


== char_look ==
char_look <character>[,frequency][,directions]
Make a character look around.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>frequency</code>: Frequency of movements. 0 to stop looking. If set to a different value it will be clipped to the range [0.5, 5]. If not passed the default value is 1.  
* <code>frequency</code>: Frequency of movements. 0 to stop looking. If set to
* <code>directions</code>: the direction the npc is going to look, by default all. (optional)
a different value it will be clipped to the range [0.5, 5].
If not passed the default value is 1.
* <code>directions</code>: the direction the character is going to look, by default
all
 
eg. char_look character
* <code>eg. char_look character,,right</code>: left
 
=== CharMoveAction ===
Relative tile movement for characters.
 
It interprets movement instructions, updates character positions accordingly,
and blocks execution until the destination is reached.


'''Examples'''
'''Usage'''
* <code>char_look character</code> 
<code>
* <code>char_look character,,right:left</code>


== char_move ==
char_move <character>,<move>...
Relative tile movement for characters. It interprets movement instructions, updates character positions accordingly, and blocks execution until the destination is reached.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>move</code>: A sequence of movement instructions in the format: "<direction> [amount_of_tiles]" where:
* <code>move</code>: A sequence of movement instructions in the format:
"<direction> [amount_of_tiles]"
* <code>where</code>:  
* direction: One of "up", "down", "left", "right".
* direction: One of "up", "down", "left", "right".
* amount_of_tiles (optional): Number of tiles to move (default is 1). Multiple moves can be provided, e.g., "up 10, down 5, left 5".
* amount_of_tiles (optional): Number of tiles to move (default is 1).
* Multiple moves can be provided, e.g., "up 10, down 5, left 5".


'''Examples'''
=== CharPatrolAction ===
* <code>char_move spyder_homemakerpapertown,down 1,right 1,up 1,left 1</code>
Enables a character to patrol a predefined route in a continuous loop.
 
'''Usage'''
<code>


== char_patrol ==
char_patrol <character>,<move>...
Enables a character to patrol a predefined route in a continuous loop.


'''Parameters'''
</code>
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>Parameters</code>:
* <code>move</code>: A sequence of movement instructions in the format: "<direction> [amount_of_tiles]" where:
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>move</code>: A sequence of movement instructions in the format:
"<direction> [amount_of_tiles]"
* <code>where</code>:  
* direction: One of "up", "down", "left", "right".
* direction: One of "up", "down", "left", "right".
* amount_of_tiles (optional): Number of tiles to move (default is 1). Multiple moves can be provided, e.g., "up 10, down 5, left 5".
* amount_of_tiles (optional): Number of tiles to move (default is 1).
* Multiple moves can be provided, e.g., "up 10, down 5, left 5".


'''Examples'''
* <code>Functionality</code>:
* <code>char_patrol spyder_homemakerpapertown,up 4,down 4</code>
* Converts movement instructions into a looping patrol path.
* NPC moves along the predefined path, restarting when completed.
* Blocks execution if the NPC encounters an obstacle.
* Automatically resumes patrol when movement is available.


== char_plague ==
=== CharPlagueAction ===
Set the entire party as infected or inoculated or healthy.
Set the entire party as infected or inoculated or healthy.


'''Usage'''
<code>
char_plague <plague_slug>,<condition>[,character]
</code>
'''Parameters'''
'''Parameters'''
* <code>plague_slug</code>: The slug of the plague to target.
* <code>plague_slug</code>: The slug of the plague to target.
* <code>condition</code>: Infected, inoculated, or None (removes the plague from the character, indicating a healthy state). (optional)
* <code>condition</code>: Infected, inoculated, or None (removes the plague from the
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple"). (optional)
character, indicating a healthy state).
     
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
'''Examples'''
* <code>enforced_check</code>: Optional string flag to enforce eligibility rules.
* <code>char_plague plague_slug,infected,npc_maple</code>
Accepts "true", "1", or "yes" (case-insensitive).
Default is False (eligibility is bypassed).


== char_position ==
=== CharPositionAction ===
Set the position of a character.
Set the position of a character.
'''Usage'''
char_position <character>,<tile_pos_x>,<tile_pos_y>


'''Parameters'''
'''Parameters'''
Line 299: Line 603:
* <code>tile_pos_y</code>: Y position to set the character to.
* <code>tile_pos_y</code>: Y position to set the character to.


'''Examples'''
=== CharRunAction ===
* <code>char_position npc_maple,6,9</code>
Set the character movement speed to the global run speed.
 
'''Usage'''
<code>


== char_run ==
char_run <character>
Set the character movement speed to the global run speed.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
 
=== CharSpeedAction ===
Set the character movement speed to a custom value.


'''Examples'''
'''Usage'''
* <code>char_run npc_mom</code>
<code>


== char_speed ==
char_speed <character>,<speed>
Set the character movement speed to a custom value.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>speed</code>: Speed amount.
* <code>speed</code>: Speed amount.


'''Examples'''
=== CharStopAction ===
* <code>char_speed npc_mom,0.2</code>
Make the character stop moving.
 
'''Usage'''
<code>
 
char_stop <character>
 
</code>
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
 
=== CharTalkAction ===
Displays dialogue for a character based on context and location.
 
This action retrieves dialogue from the character's dialogue profile,
optionally using a location-specific override. The dialogue field determines
which type of line to display (e.g. greeting, pre_battle, farewell).
 
'''Usage'''
<code>


== char_stop ==
char_talk <character>,<field>[,location]
Make the character stop moving.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or the slug of an NPC (e.g. "npc_maple").
* <code>field</code>: The dialogue type to display. Must be one of:
* greeting
* idle
* farewell
* pre_battle
* post_battle_win
* post_battle_lose
* post_battle_draw
* <code>location</code>: Optional map identifier (e.g. "map.tmx") used to override default dialogue.
 
* <code>Behavior</code>:
* If a location is provided and a location-based override exists, it will be used.
* Otherwise, the default dialogue profile is used.
* If the dialogue field contains multiple lines, one is selected randomly.
* Dialogue text is formatted before display.


'''Examples'''
* <code>Example</code>:
* <code>char_stop npc_mom</code>
char_talk npc_maple,greeting,map_forest


== char_walk ==
=== CharWalkAction ===
Set the character movement speed to the global walk speed.
Set the character movement speed to the global walk speed.


'''Usage'''
<code>
char_walk <character>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
 
=== CharWanderAction ===
Make a character wander around the map.


'''Examples'''
'''Usage'''
* <code>char_walk npc_mom</code>
<code>


== char_wander ==
char_wander <character>[,frequency][,t_bound][,b_bound]
Make a character wander around the map.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>frequency</code>: Frequency of movements. 0 to stop wandering. If set to a different value it will be clipped to the range [0.5, 5]. If not passed the default value is 1.
* <code>frequency</code>: Frequency of movements. 0 to stop wandering. If set to
* <code>t_bound</code>: Coordinates top_bound vertex (e.g. 5,7)
a different value it will be clipped to the range [0.5, 5].
* <code>b_bound</code>: Coordinates bottom_bound vertex (e.g. 7,9)
If not passed the default value is 1.
* <code>t_bound</code>: coordinates top_bound vertex (eg 5,7)
* <code>b_bound</code>: coordinates bottom_bound vertex (eg 7,9)


'''Examples'''
eg. char_wander character,,5,7,7,9
* <code>char_wander npc_maple</code>
* <code>char_wander npc_maple,,5,7,7,9</code>


== choice_item ==
=== ChoiceItemAction ===
Ask the player to make a choice among items.
Ask the player to make a choice among items.


'''Usage'''
<code>
choice_item <choices>,<variable>
</code>
'''Parameters'''
'''Parameters'''
* <code>choices</code>: List of possible choices (item slugs eg: potion:tea), separated by a colon ":".
* <code>choices</code>: List of possible choices
* <code>(item slugs eg</code>: potion:tea),
* <code>separated by a colon "</code>: ".
* <code>variable</code>: Variable to store the result of the choice.
* <code>variable</code>: Variable to store the result of the choice.


'''Examples'''
=== ChoiceMonsterAction ===
* <code>choice_monster potion:tea,name_variable</code>
Ask the player to make a choice among monsters.
 
'''Usage'''
<code>


== choice_monster ==
choice_monster <choices>,<variable>
Ask the player to make a choice among monsters.


</code>
'''Parameters'''
'''Parameters'''
* <code>choices</code>: List of possible choices (monster slugs eg: rockitten:apeoro), separated by a colon ":".
* <code>choices</code>: List of possible choices
* <code>(monster slugs eg</code>: rockitten:apeoro),
* <code>separated by a colon "</code>: ".
* <code>variable</code>: Variable to store the result of the choice.
* <code>variable</code>: Variable to store the result of the choice.


'''Examples'''
=== ChoiceNpcAction ===
* <code>choice_monster apeoro:rockitten,name_variable</code>
Ask the player to make a choice among NPCs.
 
'''Usage'''
<code>


== choice_npc ==
choice_npc <choices>,<variable>
Ask the player to make a choice among NPCs.


</code>
'''Parameters'''
'''Parameters'''
* <code>choices</code>: List of possible choices (npc slugs eg: maple:billie), separated by a colon ":".
* <code>choices</code>: List of possible choices
* <code>(item slugs eg</code>: maple:billie),
* <code>separated by a colon "</code>: ".
* <code>variable</code>: Variable to store the result of the choice.
* <code>variable</code>: Variable to store the result of the choice.


'''Examples'''
=== CipherDialogAction ===
* <code>choice_monster billie:maple,name_variable</code>
Displays a dialog window with text that may be ciphered based on the character's
unlocked letters and the active CipherProcessor.
 
The dialog text is optionally translated, styled, and formatted based on script
parameters. Any unlocked letters will remain visible, while the remaining content
may be obfuscated depending on the cipher configuration.
 
'''Usage'''
<code>


== cipher_dialog ==
cipher_dialog <text>[,avatar][,position][,style]
Displays a dialog window with text that may be ciphered based on the character's unlocked letters and the active CipherProcessor. The dialog text is optionally translated, styled, and formatted based on script parameters. Any unlocked letters will remain visible, while the remaining content may be obfuscated depending on the cipher configuration.


</code>
'''Parameters'''
'''Parameters'''
* <code>text</code>: Text of the dialog.
* <code>text</code>: Text of the dialog.
* <code>avatar</code>: 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.
* <code>avatar</code>: Monster avatar. If it is a number, the monster is the
* <code>position</code>: Position of the dialog box. Can be 'top', 'bottom', 'center', 'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'. Default 'bottom'.
corresponding monster slot in the player's party.
* <code>h_alignment</code>: Alignment of text in the dialog box, it can be 'left', 'center' or 'right'. Default 'left'.
If it is a string, we're referring to a monster by name.
* <code>v_alignment</code>: Alignment of text in the dialog box, it can be 'bottom', 'center' or 'top'. Default 'top'.
* <code>position</code>: Position of the dialog box. Can be 'top', 'bottom', 'center',
'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'.
Default 'bottom'.
* <code>h_alignment</code>: Alignment of text in the dialog box, it can be 'left', 'center'
or 'right'. Default 'left'.
* <code>v_alignment</code>: Alignment of text in the dialog box, it can be 'bottom',
'center' or 'top'. Default 'top'.
* <code>style</code>: a predefined style in db/dialogue/dialogue.json
* <code>style</code>: a predefined style in db/dialogue/dialogue.json


'''Examples'''
=== ClearKennelAction ===
* <code>cipher_dialog msgid</code>
Clear a kennel.
 
It advisable to save the game and check twice.
 
Remember the main kennel is "Kennel"
 
Without destination (transfer) the monster will
be deleted as well as the kennel.
 
'''Usage'''
<code>


== clear_kennel ==
clear_kennel <character>,<kennel>[,transfer]
Clear a kennel. It advisable to save the game and check twice. Remember the main kennel is "Kennel" and without destination (transfer) the monster will be deleted as well as the kennel.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>kennel</code>: The kennel to clear.
* <code>kennel</code>: The kennel to clear.
* <code>transfer</code>: The kennel to transfer the monsters. (optional)
* <code>transfer</code>: The kennel to transfer the monsters.


'''Examples'''
=== ClearTuxepediaAction ===
* <code>clear_kennel npc_maple,name_kennel,new_kennel</code>
Clear the key and value in the Tuxepedia dictionary. If the
monster_slug parameter is missing, this action will completely
reset the Tuxepedia dictionary by removing all seen monsters.
 
If the monster_slug parameter is provided, this action will remove
the specified monster from the Tuxepedia dictionary.
 
'''Usage'''
<code>


== clear_tuxepedia ==
clear_tuxepedia <monster_slug>
Clear the key and value in the Tuxepedia dictionary.


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_slug</code>: Monster slug name (e.g. "rockitten").
* <code>monster_slug</code>: Monster slug name (e.g. "rockitten").


'''Examples'''
=== ClearVariableAction ===
* <code>clear_tuxepedia rockitten</code>
Removes specified variables from the player's stored variables.
 
'''Usage'''
<code>


== clear_variable ==
clear_variable <variable1>[,variable2]
Removes specified variables from the player's stored variables.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: One or more variables to be removed.
* <code>variable</code>: One or more variables to be removed.


'''Examples'''
=== CopyVariableAction ===
* <code>clear_variable name_variable</code>
Copy the value of var2 into var1 (e.g. var1 = var 2).
 
'''Usage'''
<code>


== copy_variable ==
copy_variable <var1>,<var2>
Copy the value of var2 into var1 (e.g. var1 = var 2).


</code>
'''Parameters'''
'''Parameters'''
* <code>var1</code>: The variable to copy to.
* <code>var1</code>: The variable to copy to.
* <code>var2</code>: The variable to copy from.
* <code>var2</code>: The variable to copy from.


'''Examples'''
=== CraftingStationAction ===
* <code>copy_variable new_variable,old_variable</code>
Change to the specified state.
 
'''Usage'''
<code>


== crafting_station ==
crafting_station <character_slug>,<method>[,file_yaml]
Change to the specified state.


</code>
'''Parameters'''
'''Parameters'''
* <code>character_slug</code>: The slug of the character (NPC).
* <code>character_slug</code>: The slug of the character (NPC).
* <code>method</code>: Suggests how the recipe is executed, e.g., cooking, forging.
* <code>method</code>: Suggests how the recipe is executed, e.g., cooking, forging.
* <code>file_yaml</code>: The YAML file (like `recipe.yaml`) that contains the recipe definitions to load into the system (mods folder).
* <code>file_yaml</code>: The YAML file (like `recipe.yaml`) that contains the recipe
definitions to load into the system (mods folder).


'''Examples'''
=== CreateKennelAction ===
* <code>crafting_station player,cooking</code>
Creates a new kennel with optional metadata.


== create_kennel ==
It's advisable to create a msgid in the en_US PO file.
Creates a new kennel. It's advisable to create a msgid in the en_US PO file.


msgid "kennel_name"
msgid "kennel_name"
msgstr "Kennel Name"
msgstr "Kennel Name"


'''Usage'''
<code>
# Create a visible kennel with default capacity
create_kennel player,my_kennel
# Create a hidden kennel with capacity 20
create_kennel player,my_kennel,true,20
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>kennel</code>: Name of the kennel.
* <code>kennel</code>: Name of the kennel.
* <code>hidden</code>: Optional flag ("true"/"false", "1"/"0", "yes"/"no") for
visibility.
* <code>max_capacity</code>: Optional integer for maximum capacity (defaults to
MAX_KENNEL).
=== CreateNpcAction ===
Create an NPC object and adds it to the game's current list of NPC's.


'''Examples'''
'''Usage'''
* <code>create_kennel npc_maple,new_kennel</code>
<code>


== create_npc ==
create_npc <npc_slug>,<tile_pos_x>,<tile_pos_y>[,<behavior>]
Creates an NPC and places them on the current map.


</code>
'''Parameters'''
'''Parameters'''
* <code>name</code>: The name of the NPC to create. This NPC should exist in <code>resources/db/npc</code> in JSON format.
* <code>npc_slug</code>: NPC slug to look up in the NPC database.
* <code>tile_pos_x</code>: The X-tile coordinate to place the NPC.
* <code>tile_pos_x</code>: X position to place the NPC on.
* <code>tile_pos_y</code>: The Y-tile coordinate to place the NPC.
* <code>tile_pos_y</code>: Y position to place the NPC on.
* <code>behavior</code>: The NPC's movement behavior. Currently not implemented.
* <code>behavior</code>: Behavior of the NPC (e.g. "wander"). Unused for now.
 
=== DojoMethodAction ===
Represents an event action for the monks in the Dojo (Spyder).


'''Examples'''
'''Usage'''
* <code>create_npc Maple,2,3</code> 
 
* <code>create_npc Pine,1,6,stand</code>
<code>


== delayed_teleport ==
dojo_method <variable_name>,<option>
Set teleport information. Teleport will be triggered during screen transition. Only use this if followed by a transition.


</code>
'''Parameters'''
'''Parameters'''
* <code>map_name</code>: Name of the map to teleport to.
* <code>position_x</code>: X position to teleport to.
* <code>position_y</code>: Y position to teleport to.


'''Examples'''
* <code>variable_name</code>:
* <code>delayed_teleport cotton_town,10,10</code>
The name of the variable where the monster ID will be stored.
 
* <code>option</code>:
* <code>The action to perform. Can be either</code>:


== dojo_method ==
* "technique": Learn any move the monster hasn't acquired from its base
Represents an event action for the monks in the Dojo (Spyder).
moveset, without restrictions based on level or evolution stage.
* "monster": Devolve the monster.


'''Parameters'''
=== EvolutionAction ===
* <code>variable_name</code>: The name of the variable where the monster ID will be stored.
Checks, asks and evolves.
* <code>option</code>: The action to perform. Can be either: "technique" learn any move the monster hasn't acquired from its base moveset, without restrictions based on level or evolution stage OR "monster" devolve the monster.


'''Examples'''
'''Usage'''
* <code>dojo_method variable_name,monster</code>
<code>
* <code>dojo_method variable_name,technique</code>


== evolution ==
evolution <character>
Checks, asks and evolves. It's the action responsible for evolving monster when one or more conditions are met. It's advisable to use it with the condition <code>is/not check_evolution player</code>


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters get experience.
* <code>variable</code>: Name of the variable where to store the monster id. If no
variable is specified, all monsters get experience.
* <code>evolution</code>: Slug of the evolution.
* <code>evolution</code>: Slug of the evolution.


'''Examples'''
=== FadeInAction ===
* <code>evolution player</code>
Fade in and block until the fade duration has completed.
* <code>evolution player,name_variable,rockat</code>
 
'''Usage'''
<code>


== fade_in ==
fade_in [trans_time][,rgb]
Fade in.


</code>
'''Parameters'''
'''Parameters'''
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)


'''Examples'''
* <code>eg</code>: "fade_in 3"
* <code>fade_in 2.0</code>
* <code>eg</code>: "fade_in 3,255:0:0:50" (red)
 
=== FadeOutAction ===
Fade out and block until the fade duration has completed.
 
'''Usage'''
<code>


== fade_out ==
fade_out [trans_time][,rgb]
Fade out.


</code>
'''Parameters'''
'''Parameters'''
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)


'''Examples'''
* <code>eg</code>: "fade_out 3"
* <code>fade_out 2.0</code>
* <code>eg</code>: "fade_out 3,255:0:0:50" (red)
 
=== FadeoutMusicAction ===
Fade out the music over a set amount of time in milliseconds.
 
'''Usage'''
<code>


== fadeout_music ==
fadeout_music [duration]
Fades out music over <code>x</code> milliseconds.


</code>
'''Parameters'''
'''Parameters'''
* <code>time_seconds</code>: Time in milliseconds to fade out the currently playing music. (optional)
* <code>duration</code>: Number of milliseconds to fade out the music over.
 
=== FormatVariableAction ===
Format the value of a variable from the game (eg. float or int).
By default the game variable is a dict[str, Any].


'''Examples'''
'''Usage'''
* <code>fadeout_music 2</code>
<code>


== format_variable ==
format_variable <variable>,<type_format>
Format the value of a variable from the game (eg. float or int).


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: The variable to format.
* <code>variable</code>: The variable to format.
* <code>type_format</code>: Kind of format (float or int).
* <code>type_format</code>: Kind of format (float or int).


'''Examples'''
eg. "format_variable name_variable,int"
* <code>format_variable name_variable,int</code>
 
* <code>format_variable name_variable,float</code>
=== GetPartyMonsterAction ===
Saves all the iids (party) in variables.
 
'''Usage'''
<code>


== get_monster_tech ==
get_party_monster [npc_slug]
Select a tech among the monster's moves. Supports filtering by slug, element, range, and numeric comparisons for power and accuracy. Accepted comparison operators: "less_than", "less_or_equal", "greater_than", "greater_or_equal", "equals", and "not_equals".


</code>
'''Parameters'''
'''Parameters'''
* <code>variable_name</code>: Name of the game variable where the technique ID will be stored.
* <code>npc_slug</code>: npc slug name (e.g. "npc_maple") - default "player"
* <code>monster_id</code>: Name of the game variable that contains the monster ID.
* <code>skip_eligibility_check</code>: Optional string flag to bypass level/evolution eligibility checks. Accepts "true", "1", or "yes" (case-insensitive).
* <code>filter_name</code>: Optional filter key—e.g., "slug", "element", "range", "power", or "accuracy".
* <code>value_name</code>: Value to apply against the filter (e.g., "water", "stage1", "greater_than").
* <code>extra</code>: Optional numeric value for comparison filters (e.g., "1.6").


'''Examples'''
=== GetPendingMovesAction ===
* <code>get_monster_tech chosen_id,monster_ref</code>
Display a menu of pending techniques for monsters listed in
* <code>get_monster_tech chosen_id,monster_ref,true</code>
event_data["check_max_tech"], and store the selected technique ID
* <code>get_monster_tech chosen_id,monster_ref,false,element,water</code>
in a game variable.
* <code>get_monster_tech chosen_id,monster_ref,true,power,greater_than,2.0</code>
 
'''Usage'''
<code>


== get_party_monster ==
get_pending_moves <variable_name>
Saves all the iids (party) in variables. Names are saved in game variables: <code>iid_slot_{index}</code>. Where index is the position in the party (the 1st one is 0, 2nd one is 1, etc.)


</code>
'''Parameters'''
'''Parameters'''
* <code>npc_slug</code>: npc slug name (e.g. "npc_maple") - if absent default "player" (optional)
* <code>variable_name</code>: Name of the game variable to store the selected
technique ID.


'''Examples'''
* <code>Example</code>:
* <code>get_party_monster</code>
* "get_pending_moves chosen_move"
* <code>get_party_monster npc_maple</code>


== get_player_monster ==
=== GetPlayerMonsterAction ===
Select a monster in the player party and store its id in a variable.
Select a monster in the player party and store its id in a variable.
* <code>It allows filtering</code>: slug, gender, evolution_stage, element, shape,
taste_warm, taste_cold, level, weight, height, max_hp, current_hp,
armour, dodge, melee, ranged and speed.
eg "get_player_monster name_variable,shape,serpent"
eg "get_player_monster name_variable,shape,serpent"
* <code>For the definition</code>: level, weight, height, max_hp, current_hp, armour, dodge,
melee, ranged and speed (all numeric values) is necessary to use a numeric
comparison operator. Accepted values are "less_than", "less_or_equal",
"greater_than", "greater_or_equal", "equals" and "not_equals".
eg "get_player_monster name_variable,speed,more_than,50"
eg "get_player_monster name_variable,level,less_than,15"


It allows filtering: slug, gender, evolution_stage, element, shape, taste_warm, taste_cold, level, weight, height, max_hp, current_hp, armour, dodge, melee, ranged and speed.
* <code>Note</code>:  
let's say a player doesn't has no options, then the variable
* <code>will result as</code>: name_variable:no_option
let's say a player has options, but clicks return, then the
* <code>variable will result as</code>: name_variable:no_choice


For the definition: level, weight, height, max_hp, current_hp, armour, dodge, melee, ranged and speed (all numeric values) is necessary to use a numeric comparison operator. Accepted values are "less_than", "less_or_equal", "greater_than", "greater_or_equal", "equals" and "not_equals".
'''Usage'''
<code>


Note:
get_player_monster <variable_name>,<filter_name>,<value_name>[,extra]
* let's say a player doesn't has no options, then the variable will result as: name_variable:no_option
* let's say a player has options, but clicks return, then the variable will result as: name_variable:no_choice


</code>
'''Parameters'''
'''Parameters'''
* <code>variable_name</code>: Name of the variable where to store the monster id.
* <code>variable_name</code>: Name of the variable where to store the monster id.
* <code>filter_name</code>: the name of the first filter (optional)
filter
* <code>value_name</code>: the actual value to filter (optional)
* <code>filter_name</code>: the name of the first filter
* <code>extra</code>: used to filter more (optional)
* <code>value_name</code>: the actual value to filter
* <code>extra</code>: used to filter more


'''Examples'''
=== GiveExperienceAction ===
* <code>get_player_monster name_variable</code>
Gives experience points to the monster.
* <code>get_player_monster name_variable,speed,more_than,50</code>
 
* <code>get_player_monster name_variable,level,less_than,15</code>
'''Usage'''
* <code>get_player_monster name_variable,shape,serpent</code>
<code>
* <code>get_player_monster name_variable,shape,serpent</code>


== give_experience ==
give_experience <variable>,<exp>
Gives experience points to the monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id. If no
* <code>exp</code>: Name of the variable where to store the experience points or directly the number of points. Negative value will result in 0.
variable is specified, all monsters get experience.
* <code>exp</code>: Name of the variable where to store the experience points or
directly the number of points. Negative value will result in 0.
 
eg. "give_experience name_variable,steps_variable"
eg. "give_experience name_variable,420"
 
=== InfoAction ===
Records monster's attribute values inside a game variable.
It allows recording the monster's owner attribute values too.
 
'''Usage'''


'''Examples'''
<code>
* <code>give_experience name_variable,steps_variable"</code>
* <code>give_experience name_variable,420</code>


== info ==
info <variable>,<attribute>
Records monster's attribute values inside a game variable. It allows to record the monster's owner attribute values too.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
 
* <code>attribute</code>: The attribute to check (level, speed, etc.).
* <code>variable</code>:  
Name of the variable where to store the monster id.
 
* <code>attribute</code>:  
The attribute to check (level, speed, etc.)


'''Examples'''
'''Examples'''
* <code>info name_variable,level</code> -> if the monster is lv 4, then it'll create a variable called: "info_level:4"
* <code>info name_variable,owner_steps</code> -> if the owner walked 69 steps, then it'll create a variable called: "info_owner_steps:69"


== input_variable ==
* "info name_variable,level"
Set a code and checks if it's correct or not. The player's output will be by default lowercase.
* -> if the monster is lv 4, then it'll create a variable called:
* <code>"info_level</code>: 4"
 
* "info name_variable,owner_steps"
* -> if the owner walked 69 steps, then it'll create a variable called:
* <code>"info_owner_steps</code>: 69"
 
=== InputLoadAction ===
Load a recording from a file into memory under a given name.
 
'''Usage'''
<code>
 
input_load <filepath> <name>
</code>
 
=== InputPlaybackAction ===
Start or stop playback of a named recording.


'''Usage'''
<code>
input_playback <action> <name>
</code>
=== InputRecordAction ===
Start or stop input recording, optionally naming the recording.
'''Usage'''
<code>
input_record <action> [name]
</code>
=== InputSaveAction ===
Save a named recording to a file.
'''Usage'''
<code>
input_save <filepath> [name]
</code>
=== InputVariableAction ===
Set a code and check if it's correct or not.
The player's output will be by default lowercase.
'''Usage'''
<code>
input_variable <variable>,<question>[,answer][,escape]
</code>
'''Parameters'''
'''Parameters'''
* <code>question</code>: The question the player needs to reply. (eg. "access_code") then you create the msgid "access_code" inside the English PO file, as follows: msgid "access_code" and msgstr "Here the actual question?"
 
* <code>variable</code>: Name of the variable where to store the output.
* <code>question</code>:  
* <code>escape</code>: Whether the input can be closed or not. Default False.
The question the player needs to reply (e.g. "access_code").
* <code>Then you create the msgid "access_code" inside the PO file</code>:  
 
msgid "access_code"
msgstr "Here the actual question?"
 
* <code>variable</code>:  
Name of the variable where to store the output.
 
* <code>escape</code>:  
Optional string flag ("true", "1", "yes" for True),
defaults to False when omitted.


'''Examples'''
'''Examples'''
* <code>input_variable access_code,response_question</code>
* <code>input_variable access_code,response_question,escape</code>


== learn_tech_by_method ==
* "input_variable access_code,response_question"
* "input_variable access_code,response_question,escape"
 
* -> "is variable_set response_question:whatswrittenbytheplayer"
* -> "not variable_set response_question:whatswrittenbytheplayer"
 
=== LearnTechByMethodAction ===
Teaches a technique to a specific monster using a specific learning method.
Teaches a technique to a specific monster using a specific learning method.


'''Parameters'''
'''Usage'''
<code>
 
learn_tech_by_method <monster_var>,<technique>,<method>
 
</code>
* <code>Parameters</code>:
* <code>monster_var</code>: Game variable name containing the monster UUID.
* <code>monster_var</code>: Game variable name containing the monster UUID.
* <code>technique</code>: Slug of the technique to learn.
* <code>technique</code>: Slug of the technique to learn.
Line 640: Line 1,193:


'''Examples'''
'''Examples'''
* <code>learn_tech_by_method monster_id,flamethrower,EVENT</code>
* "learn_tech_by_method monster_id,flamethrower,EVENT"
* <code>learn_tech_by_method monster_id,fireblast,TM</code>
* "learn_tech_by_method monster_id,fireblast,TM"
 
=== LoadGameAction ===
Loads the game.
 
If the index parameter is absent, then it'll load
slot4.save


== load_game ==
index = 0 > slot 1
Loads the game. If the index parameter is absent, then it'll load slot4.save (index = 0 > slot 1, index = 1 > slot 2, index = 2 > slot 3)
index = 1 > slot 2
index = 2 > slot 3


'''Usage'''
<code>
load_game [index]
</code>
'''Parameters'''
'''Parameters'''
* <code>index</code>: Selected index. (optional)
* <code>index</code>: Selected index.


'''Examples'''
* <code>eg</code>: "load_game" (slot4.save)
* <code>load_game</code> (it's going to load slot4.save)
* <code>eg</code>: "load_game 1"
* <code>load_game 0</code> (it's going to load slot1.save)
 
=== LoadWeatherAction ===
Loads a YAML file containing weather previsions using the Pydantic schema
and registers it with the WorldWeatherManager.
 
'''Usage'''
<code>
 
load_weather <path_to_yaml_file>
 
</code>
'''Parameters'''
* <code>model_file</code>: Path to the YAML file (e.g., "weather_previsions.yml").
 
=== LoadYamlAction ===
Loads the yaml file. It must be in the maps folder.
 
'''Usage'''
<code>


== lock_controls ==
load_yaml file
Lock player controls.


</code>
'''Parameters'''
'''Parameters'''
* <code>None</code>
* <code>file</code>: File to load.
 
* <code>eg</code>: "load_yaml file_yaml"
 
=== LockControlsAction ===
Lock player controls
 
'''Usage'''
<code>
 
lock_controls
</code>
 
=== ManageMapCacheAction ===
Adds or removes a map from the cache.
 
'''Usage'''
<code>
 
manage_map_cache <action>,<map_name>


'''Examples'''
</code>
* <code>lock_controls</code>
'''Parameters'''
* <code>action</code>: "add" or "remove"
* <code>map_name</code>: Name of the map (map.tmx)


== menu ==
=== MenuAction ===
Toggle visibility of one or more world menu entries, or apply a preset.
Toggle visibility of one or more world menu entries, or apply a preset.


'''Parameters'''
'''Usage'''
<code>
 
menu <flag>[,menu_1:menu_2:...]  # toggles specific menus
menu <preset>                    # applies preset config
 
</code>
* <code>Parameters</code>:
* <code>flag</code>: "enable" or "disable", applied to specified menus (or all)
* <code>flag</code>: "enable" or "disable", applied to specified menus (or all)
* <code>preset</code>: one of defined presets ("minimal", etc.)
* <code>preset</code>: one of defined presets ("minimal", etc.)


'''Examples'''
'''Examples'''
* <code>menu reset</code>                         > clears all menu flags
* menu reset                        > clears all menu flags
* <code>menu enable</code>                       > enables all menus
* menu enable                        > enables all menus
* <code>menu disable,menu_bag:menu_player</code>  > disables specified menus
* <code>menu disable,menu_bag</code>: menu_player > disables specified menus
* <code>menu enable,all</code>                   > enables all menus
* menu enable,all                    > enables all menus
* <code>menu minimal</code>                       > applies "minimal" preset
* menu minimal                      > applies "minimal" preset


== modify_bill ==
=== ModifyBillAction ===
Add or remove an amount of money from a bill (slug).
Add or remove an amount of money from a bill (slug).


'''Usage'''
<code>
modify_bill <slug>,<bill_slug>,[amount][,variable]
</code>
'''Parameters'''
'''Parameters'''
* <code>slug</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>slug</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>bill_slug</code>: Slug of the bill.
* <code>bill_slug</code>: Slug of the bill.
* <code>amount</code>: Amount of money to add/remove (-/+)
* <code>amount</code>: Amount of money to add/remove (-/+)
* <code>variable</code>: Name of the variable where is stored the amount.
* <code>variable</code>: Name of the variable where to store the amount.


'''Examples'''
eg. "modify_bill player,bill_slug,-50"
* <code>modify_bill player,bill_slug,100</code>
eg. "modify_bill player,bill_slug,,name_variable"
* <code>modify_bill player,bill_slug,,name_variable</code>
 
=== ModifyCharAttributeAction ===
Modify the given attribute of the character by modifier.
 
By default this is achieved via addition, but prepending a '%' will cause
it to be multiplied by the attribute.
 
'''Usage'''
<code>


== modify_char_attribute ==
modify_char_attribute <character>,<attribute>,<value>
Modify the given attribute of the character by modifier. By default this is achieved via addition, but prepending a '%' will cause it to be multiplied by the attribute.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>attribute</code>: Name of the attribute to modify.
* <code>attribute</code>: Name of the attribute to modify.
* <code>value</code>: Value of the attribute modifier.
* <code>value</code>: Value of the attribute modifier.


'''Examples'''
=== ModifyContactsAction ===
* <code>modify_char_attribute character,attribute,value</code>
Modify contact relationship.
 
'''Usage'''
<code>


== modify_contacts ==
modify_contacts <character>,<npc_slug>,<attribute>,<value>
Modify contact relationship.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>npc_slug</code>: slug name (e.g. "npc_maple").
* <code>npc_slug</code>: slug name (e.g. "npc_maple").
* <code>attribute</code>: it can be 'strength', 'decay_rate' or 'decay_threshold'
* <code>attribute</code>: it can be 'strength', 'decay_rate' or 'decay_threshold'
* <code>value</code>: the new value
* <code>value</code>: the new value


'''Examples'''
=== ModifyFactionReputationAction ===
* <code>modify_contacts player,npc_maple,strength,100</code>
Modifies an NPC's (or player's) reputation with a specific faction.
 
'''Usage'''
<code>


== modify_faction_reputation ==
modify_faction_reputation <character>,<faction_slug>,<amount>
Modifies an NPC's (or player's) reputation with a specific faction.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>faction_slug</code>: The slug identifier of the faction to modify reputation for.
* <code>faction_slug</code>: The slug identifier of the faction to modify reputation for.
* <code>amount</code>: A string representation of an integer. Positive or negative values (e.g. "25", "-50") that change the reputation score accordingly.
* <code>amount</code>: A string representation of an integer. Positive or negative values
(e.g. "25", "-50") that change the reputation score accordingly.
 
=== ModifyMoneyAction ===
Add or remove an amount of money for a wallet (slug).


'''Examples'''
'''Usage'''
* <code>modify_faction_reputation npc_maple,faction_slug,25</code>
<code>
* <code>modify_faction_reputation npc_maple,faction_slug,-50</code>


== modify_money ==
modify_money <slug>,[amount][,variable]
Add or remove an amount of money for a wallet (slug).


</code>
'''Parameters'''
'''Parameters'''
* <code>slug</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>slug</code>: Either "player" or character slug name (e.g. "npc_maple").
Line 732: Line 1,367:
* <code>variable</code>: Name of the variable where to store the amount.
* <code>variable</code>: Name of the variable where to store the amount.


'''Examples'''
eg. "modify_money player,-50"
* <code>modify_money npc_maple,100</code>
eg. "modify_money player,,name_variable"
* <code>modify_money npc_maple,-50</code>
 
* <code>modify_money player,,name_variable</code>
=== ModifyMonsterBondAction ===
Change the bond of a monster in the current player's party.
 
'''Usage'''
<code>


== modify_monster_bond ==
modify_monster_bond [variable][,amount]
Add or remove an amount of money for a wallet (slug).


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are touched.
* <code>variable</code>: Name of the variable where to store the monster id. If no
variable is specified, all monsters are touched.
* <code>amount</code>: An int or float value, if no amount, then default 1 (int).
* <code>amount</code>: An int or float value, if no amount, then default 1 (int).
* <code>lower_bound</code>: Lower bound of range to return an integer between (inclusive)
* <code>upper_bound</code>: Upper bound of range to return an integer between (inclusive)


'''Examples'''
eg. "modify_monster_bond"
* <code>modify_monster_bond</code>
eg. "modify_monster_bond name_variable,25"
* <code>modify_monster_bond name_variable,25</code>
eg. "modify_monster_bond name_variable,-0.5"
* <code>modify_monster_bond name_variable,-0.5</code>
eg. "modify_monster_bond name_variable,,1,5" (random between 1 and 5)
eg. "modify_monster_bond name_variable,,-5,-1" (random between -5 and -1)


== modify_monster_health ==
=== ModifyMonsterHealthAction ===
Modify the hp of a monster in the current player's party.
Modify the hp of a monster in the current player's party.


'''Usage'''
<code>
modify_monster_health [variable][,health]
</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are healed.
* <code>variable</code>: Name of the variable where to store the monster id. If no
* <code>health</code>: A float value between 0 and 1, which is the percent of max hp to be restored to. A int value, which is the number of HP to be restored to. If no health is specified, the hp is maxed out.
variable is specified, all monsters are healed.
* <code>health</code>: A float value between 0 and 1, which is the percent of max
hp to be restored to. A int value, which is the number of HP
to be restored to. If no health is specified, the hp is maxed
out.


'''Examples'''
=== ModifyMonsterStatsAction ===
* <code>modify_monster_health</code>
Change the stats of a monster in the current player's party.
* <code>modify_monster_health ,0.25</code>


'''Usage'''
<code>


== modify_monster_stats ==
modify_monster_stats [variable][,stat][,amount]
Change the stats of a monster in the current player's party.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are touched. (Optional)
* <code>variable</code>: Name of the variable where to store the monster id. If no
* <code>stat</code>: A stat among armour, dodge, hp, melee, speed and ranged. If no stat, then all the stats. (Optional)
variable is specified, all monsters are touched.
* <code>amount</code>: A/an float/int value, if no amount, then default 1 (+). (Optional)
* <code>stat</code>: A stat among armour, dodge, hp, melee, speed and ranged. If no
stat, then all the stats.
* <code>amount</code>: A/an float/int value, if no amount, then default 1 (+).
* <code>lower_bound</code>: Lower bound of range to return an integer between (inclusive)
* <code>upper_bound</code>: Upper bound of range to return an integer between (inclusive)
 
eg. "modify_monster_stats"
eg. "modify_monster_stats ,,0.25"
eg. "modify_monster_stats name_variable,speed,25"
eg. "modify_monster_stats name_variable,dodge,-12"
eg. "modify_monster_stats name_variable,dodge,-0.4"
eg. "modify_monster_stats name_variable,,,1,5" (random between 1 and 5)
 
=== OpenJournalAction ===
Change to JournalInfoState.
 
This action transitions to the JournalInfoState, displaying information
about a specific monster in the player's journal.


'''Examples'''
'''Usage'''
* <code>modify_monster_stats</code>
<code>
* <code>modify_monster_stats ,,0.25</code>
* <code>modify_monster_stats name_variable,speed,25</code>
* <code>modify_monster_stats name_variable,dodge,-12</code>
* <code>modify_monster_stats name_variable,dodge,-0.4</code>


== open_journal ==
open_journal <monster_slug>
Change to JournalInfoState. This action transitions to the JournalInfoState, displaying information about a specific monster in the player's journal.


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_slug</code>: The slug of the monster to display in the journal.
* <code>monster_slug</code>: The slug of the monster to display in the journal.


'''Examples'''
=== OpenShopAction ===
* <code>open_journal player</code>
Opens a shop interface between the player and a target NPC.


== open_shop ==
'''Usage'''
Opens a shop interface between the player and a target NPC.
open_shop <npc_slug>,<menu>[,model]


'''Parameters'''
* <code>Parameters</code>:
* <code>npc_slug</code>: Either "player" or the NPC slug identifier (e.g. "npc_maple").
* <code>npc_slug</code>: Either "player" or the NPC slug identifier (e.g. "npc_maple").
* <code>menu</code>: Type of shop interaction to open. Must be one of: "buy_item", "sell_item", "both_item", "buy_monster", "sell_monster" or "both_monster"
* <code>menu</code>: Type of shop interaction to open. Must be one of:
* "buy_item"
* "sell_item"
* "both_item"
* "buy_monster"
* "sell_monster"
* "both_monster"
* "train_monster"
* "heal_monster"
* <code>model (optional)</code>: A configuration profile name used to load custom shop behavior.


Notes:
* <code>Notes</code>:  
* The target NPC must have an economy assigned.
* The target NPC must have an economy assigned.
* If menu is "both_*", a choice dialog is shown for selection.
* If menu is "both_*", a choice dialog is shown for selection.


'''Examples'''
=== OverwriteTechAction ===
* <code>open_shop npc_maple,both_item</code>  
Replaces a known technique with another for a specific monster.
 
This action is typically used when a monster chooses to forget a move
and learn a new one.
 
'''Usage'''
<code>


== overwrite_tech ==
overwrite_tech <removed>,<added>
Replaces a known technique with another for a specific monster. This action is typically used when a monster chooses to forget a move and learn a new one.


</code>
'''Parameters'''
'''Parameters'''
* <code>removed</code>: Name of the game variable that stores the UUID of the technique to be replaced.
* <code>removed</code>: Name of the game variable that stores the UUID of the
technique to be replaced.
* <code>added</code>: Slug of the technique to be added (e.g., "peck", "fireball")
* <code>added</code>: Slug of the technique to be added (e.g., "peck", "fireball")


'''Examples'''
* <code>Example</code>:
* <code>overwrite_tech name_variable,peck</code>
"overwrite_tech name_variable,peck"


== park_experience ==
=== ParkExperienceAction ===
Shows the results of the Park session.
Shows the results of the Park session.


'''Usage'''
<code>
park_experience
</code>
'''Parameters'''
'''Parameters'''
* <code>option</code>: Either 'start' or 'stop'
* <code>option</code>: Either 'start' or 'stop'


'''Examples'''
=== PathfindAction ===
* <code>park_experience start</code>
Pathfind the player / npc to the given location.
* <code>park_experience stop</code>
 
This action blocks until the destination is reached.
 
'''Usage'''
<code>


== pathfind ==
pathfind <npc_slug>
Moves an NPC to a certain tile on the map.


</code>
'''Parameters'''
'''Parameters'''
* <code>name</code>: The name of the NPC to be moved.
* <code>npc_slug</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>tile_pos_x</code>: The X-tile coordinate to have the NPC to walk to.
* <code>tile_pos_y</code>: The Y-tile coordinate to have the NPC to walk to.    


'''Examples'''
=== PathfindToCharAction ===
* <code>pathfind Maple,2,3</code>
Handles pathfinding movement where one entity navigates toward another
* <code>pathfind Pine,1,6</code>
with configurable direction and distance.
 
'''Usage'''
<code>


== pathfind_to_player ==
pathfind_to_char <target_entity>,<moving_entity>,
Pathfind NPC close the player.
[direction],[distance]


</code>
'''Parameters'''
'''Parameters'''
* <code>npc_slug</code>: Npc slug name (e.g. "npc_maple").
* <code>target_entity</code>: The target entity being approached
* <code>direction</code>: Approaches the player from up, down, left or right.
(e.g. "character_maple").
* <code>distance</code>: How many tiles (2, 3, 4, etc.)
* <code>moving_entity</code>: The entity that will move toward the target
(e.g. "character_jimmy").
* <code>direction</code>: Determines approach direction
(up, down, left, or right).
* <code>distance</code>: Number of tiles to maintain from the player
(e.g. 2,3,4).
 
=== PauseMusicAction ===
Pause the current music playback.


'''Examples'''
'''Usage'''
* <code>pathfind_to_player spyder_route2_roddick</code>
<code>
* <code>translated_dialog spyder_route2_roddick1</code>
* <code>start_battle player,spyder_route2_roddick</code>  


== pause_music ==
pause_music
Pauses the currently playing music.
</code>


'''Parameters'''
=== PlayMapAnimationAction ===
* <code>None</code>
Trigger a map animation at a specified position based on the character's
coordinates within the world map


'''Examples'''
'''Usage'''
* <code>pause_music</code>
<code>


== play_map_animation ==
play_map_animation <animation_name>,<duration>,<loop>,<character>
Trigger a map animation at a specified position based on the character's coordinates within the world map.


</code>
'''Parameters'''
'''Parameters'''
* <code>animation_name</code>: The name of the animation stored in the resources/animations/tileset directory. For example, an animation named "grass" will load frames named "grass_xx.png".  
* <code>animation_name</code>: The name of the animation stored in the
resources/animations/tileset directory. For example, an animation
named "grass" will load frames named "grass_xx.png".
* <code>frame_duration</code>: Duration (in seconds) for each frame of the animation.
* <code>frame_duration</code>: Duration (in seconds) for each frame of the animation.
* <code>loop_mode</code>: Indicates whether the animation should loop. Options: "loop" or "noloop".
* <code>loop_mode</code>: Indicates whether the animation should loop. Options: "loop"
or "noloop".
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").


'''Examples'''
=== PlayMusicAction ===
* <code>play_map_animation grass,0.1,noloop,player</code> 
Play a music file from "resources/music/".
 
'''Usage'''
<code>


== play_music ==
play_music <filename>[,volume][,loop][,fade_ms]
Plays an audio file.


</code>
'''Parameters'''
'''Parameters'''
* <code>filename</code>: The name of the music file to play.
* <code>filename</code>: The name of the music file to play.
* <code>volume</code>: A value between 0.0 and 1.0 that adjusts the music volume. (optional)
* <code>volume</code>: A value between 0.0 and 1.0 that adjusts the music
* <code>loop</code>: The number of times to loop the music. Default is to loop forever. (optional)
volume.
* <code>fade_ms</code>: The time in milliseconds to fade in the music before reaching maximum volume. (optional)
* <code>loop</code>: The number of times to loop the music. Default is to loop
forever.
* <code>fade_ms</code>: The time in milliseconds to fade in the music before
reaching maximum volume.
 
* <code>Note</code>:
The volume will be based on the main value in the options menu.
e.g. if you set volume = 0.5 here, but the player has 0.5 among
its options, then it'll result into 0.25 (0.5*0.5)


'''Examples'''
=== PlaySoundAction ===
* <code>play_music music_mystic_island</code>  
Plays a short sound effect from the "resources/sounds/" folder.
 
'''Usage'''
<code>


== play_sound ==
play_sound <filename>[,volume]
Plays a short sound effect from the "resources/sounds/" folder. This is intended for short non-looping sound effects (e.g., cues, UI feedback), not for ambient or background music.


</code>
'''Parameters'''
'''Parameters'''
* <code>filename</code>: The sound file to load (must exist in the sounds database).
* <code>filename</code>: The sound file to load (must exist in the sounds database).
* <code>volume</code>: A float between 0.0 and 1.0 representing the relative volume level. This value is multiplied by the user's configured sound volume.
* <code>volume</code>: A float between 0.0 and 1.0 representing the relative volume level.
This value is multiplied by the user's configured sound volume.
 
* <code>Example</code>:
If volume=0.5 and the player's sound setting is also 0.5,
the resulting effective playback volume will be 0.25.


'''Examples'''
* <code>Note</code>:
If volume=0.5 and the player's sound setting is also 0.5, the resulting effective playback volume will be 0.25.
This is intended for short non-looping sound effects (e.g., cues, UI feedback),
* <code>play_sound sound_confirm</code>
not for ambient or background music.


== play_tile_animation ==
=== PlayTileAnimationAction ===
Trigger a map animation at a specified tile position on the world map.
Trigger a map animation at a specified tile position on the world map.


'''Usage'''
<code>
play_tile_animation <tile_pos_x>,<tile_pos_y>,<animation_name>,<duration>,<loop>
</code>
'''Parameters'''
'''Parameters'''
* <code>tile_pos_x, tile_pos_y</code>: Coordinates (x, y) specifying the tile position where the animation will be drawn on the map.
* <code>tile_pos_x, tile_pos_y</code>: Coordinates (x, y) specifying the tile position
* <code>animation_name</code>: The name of the animation stored in the resources/animations/tileset directory. For example, an animation named "grass" will load frames named "grass_xx.png".  
where the animation will be drawn on the map.
* <code>animation_name</code>: The name of the animation stored in the
resources/animations/tileset directory. For example, an animation
named "grass" will load frames named "grass_xx.png".
* <code>frame_duration</code>: Duration (in seconds) for each frame of the animation.
* <code>frame_duration</code>: Duration (in seconds) for each frame of the animation.
* <code>loop_mode</code>: Indicates whether the animation should loop. Options: "loop" or "noloop".
* <code>loop_mode</code>: Indicates whether the animation should loop. Options: "loop"
or "noloop".


'''Examples'''
=== PrintAction ===
* <code>play_tile_animation 33,10,sign01,0.4,loop</code>
Print the current value of one or more game variables to the console.
 
If no variable is specified, print out values of all game variables.


== print ==
'''Usage'''
Print the current value of a game variable to the console. If no variable is specified, print out values of all game variables.
<code>


'''Parameters'''
print
* <code>variable</code>: Prints out the value of this variable (optional)
print <variables>


'''Examples'''
Script parameters:
* <code>print</code> 
variables: Optional, prints out the value of this/these variable/s,
* <code>print name_variable</code>
multiple variables separated by ':'.
</code>


== quarantine ==
=== QuarantineAction ===
Quarantine or release monsters infected with a specific plague.
Quarantine or release monsters infected with a specific plague.


'''Parameters'''
* <code>Usage</code>:
quarantine <character>,<plague_slug>,<value>[,amount]
 
* <code>Parameters</code>:
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>plague_slug</code>: The slug of the plague to target.
* <code>plague_slug</code>: The slug of the plague to target.
* <code>value</code>: "in" to quarantine infected monsters, "out" to release them.
* <code>action_type</code>: "in" to quarantine infected monsters, "out" to release them.
* <code>amount</code>: (Optional, only for "out") The number of monsters to release randomly.
* <code>amount</code>: (Optional, only for "out") The number of monsters to release
randomly.


'''Examples'''
* <code>Example</code>: "quarantine out,5" (Release 5 infected monsters randomly)
* <code>quarantine npc_maple,plague_slug,out</code> everything out (player's party -> if full, then box)
* <code>quarantine npc_maple,plague_slug,out,5</code> eg. box contains 30 monsters <code>quarantine out,5</code>, it means 5 monsters by random


== quit ==
=== QuitAction ===
Completely quit the game.
Completely quit the game.


'''Usage'''
<code>
quit
</code>
=== QuitWorldAction ===
Exit the current world without quitting the game.
'''Usage'''
<code>
quit_world
</code>
=== RandomBattleAction ===
Starts a random battle with a randomly chosen NPC and a party of randomly
generated monsters within a specified level range.
'''Usage'''
<code>
random_battle nr_txmns,min_level,max_level
</code>
'''Parameters'''
'''Parameters'''
* <code>None</code>
* <code>nr_txmns</code>: The number of Tuxemon in the opponent's party (1 to 6).
* <code>min_level</code>: The minimum level for the opponent's monsters.
* <code>max_level</code>: The maximum level for the opponent's monsters.
 
=== RandomEncounterAction ===
Randomly start an 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".


'''Examples'''
'''Usage'''
* <code>quit</code> 
<code>


== random_battle ==
random_encounter <encounter_slug>[,total_prob][,rgb]
Start random battle with a random npc with a determined number of monster in a certain range of levels.


</code>
'''Parameters'''
'''Parameters'''
* <code>nr_txmns</code>: Number of tuxemon (1 to 6).
* <code>encounter_slug</code>: Slug of the encounter list.
* <code>min_level</code>: Minimum level of the party.
* <code>total_prob</code>: Total sum of the probabilities.
* <code>max_level</code>: Maximum level of the party.
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)


'''Examples'''
=== RandomHordeAction ===
* <code>random_battle 6,1,99</code>
Randomly start an horde.


== random_encounter ==
Randomly starts a battle with a monster defined in the "encounter" table
Randomly start a battle based on the encounter group looked up via the <code>encounter_id</code>. 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 <code>char_at</code> and <code>char_moved</code> conditions.
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.


Here is an example encounter file: ''resources/db/encounter/route1.json''
'''Usage'''
<code>


  "slug": "route1",
random_horde <encounter_slug>[,rgb]
  "monsters": [
    {
      "monster": "pairagrin",
      "encounter_rate": 3.5,
      "variable": "daytime:true",
      "exp_req_mod": 1,
      "level_range": [
        2,
        4
      ]
    },


</code>
'''Parameters'''
'''Parameters'''
* <code>encounter_slug</code>: Slug of the encounter list.
* <code>encounter_slug</code>: Slug of the encounter list.
* <code>total_prob</code>: Total sum of the probabilities. (optional)
* <code>total_prob</code>: Optional float between 0 and 100 representing the chance
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255) (optional)
of triggering a horde encounter.
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)
 
=== RandomIntegerAction ===
Randomly chooses an integer between two numbers (inclusive) and sets a key in
the player's game_variables dictionary to this value.
 
For example, 'random_integer xyz,1,6' will set the value of the game variable
'xyz' to be a random integer from 1, 2, 3, 4, 5, or 6.


'''Examples'''
'''Usage'''
* <code>random_encounter route1</code>
<code>
* <code>random_encounter route1,20</code>


== random_integer ==
random_integer <variable>,<lower_bound>,<upper_bound>
Randomly choose an integer between 2 numbers (inclusive), and set the key in the player.game_variables dictionary to be this value. For example, 'random_integer xyz,1,6' will set the value of the game variable 'xyz' to be either 1, 2, 3, 4, 5, or 6.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable.
* <code>variable</code>: Name of the variable to set.
* <code>lower_bound</code>: Lower bound of range to return an integer between (inclusive)
* <code>lower_bound</code>: The inclusive lower bound of the integer range.
* <code>upper_bound</code>: Upper bound of range to return an integer between (inclusive)
* <code>upper_bound</code>: The inclusive upper bound of the integer range.
 
=== RandomItemAction ===
Picks a random item from a list and adds it to the trainer's inventory.


'''Examples'''
'''Usage'''
* <code>random_integer name_variable,1,9</code>
<code>


== random_item ==
random_item <item_slugs>[,quantity][,trainer_slug]
Pick a random item from a list and add it to the trainer's inventory.


</code>
'''Parameters'''
'''Parameters'''
* <code>item_slug</code>: Item name to look up in the item database (multiple items separated by ":").
* <code>item_slugs</code>: A colon-separated string of item names to choose from.
* <code>quantity</code>: Quantity of the item to add or to reduce. By default it is 1. (optional)
* <code>Example</code>: 'potion:super-potion:hyper-potion'.
* <code>trainer_slug</code>: Slug of the trainer that will receive the item. It defaults to the current player. (optional)
* <code>quantity</code>: The number of the item to add. Defaults to 1.
* <code>trainer_slug</code>: The slug of the trainer to receive the item.
Defaults to the current player.
 
=== RandomMonsterAction ===
Adds a random monster to the specified trainer's party, if there is room.


'''Examples'''
'''Usage'''
* <code>random_item potion:tea:revive</code> (adds 1 potion or tea or revive to the trainer's inventory).
<code>
* <code>random_item potion:tea:revive,2</code> (adds 2 potions or teas or revives to the trainer's inventory).
* <code>random_item potion:tea:revive,2,npc_maple</code> (adds 2 potions or teas or revives to the maple's inventory).
* <code>random_item potion:tea:revive,,npc_maple</code> (adds 1 potion or tea or revive to the maple's inventory).


== random_monster ==
random_monster <level>[,npc_slug][,exp][,mon][,shape][,evo]
Add a monster to the specified trainer's party if there is room.


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_level</code>: Level of the added monster.
* <code>level</code>: The level of the added monster.
* <code>trainer_slug</code>: Slug of the trainer that will receive the monster. It defaults to the current player. (optional)
* <code>npc_slug</code>: The slug of the trainer to receive the monster
* <code>exp_mod</code>: Experience modifier. (optional)
Defaults to the current player.
* <code>money_mod</code>: Money modifier. (optional)
* <code>exp</code>: A modifier for the monster's experience.
* <code>shape</code>: Shape (eg. varmint, brute, etc.). (optional)
* <code>mon</code>: A modifier for the monster's money yield.
* <code>evo</code>: Stage (eg. basic, stage1, etc.). (optional)
* <code>shape</code>: The monster's shape (e.g., 'varmint', 'brute').
* <code>evo</code>: The monster's evolution stage (e.g., 'basic', 'stage1').


'''Examples'''
=== RemoveCollisionAction ===
* <code>random_monster 10</code>
Removes a collision zone associated with a specific label from the
* <code>random_monster 10,npc_maple</code>
world map.
* <code>random_monster 10,npc_maple,10,27</code>
 
* <code>random_monster 10,npc_maple,10,27,aquatic,basic</code>
'''Usage'''
* <code>random_monster 10,npc_maple,,,brute,basic</code>
<code>


== remove_collision ==
remove_collision <label>
Removes a collision zone associated with a specific label from the world map.


</code>
'''Parameters'''
'''Parameters'''
* <code>label</code>: The name or identifier of the obstacle to be removed.
* <code>label</code>: The name or identifier of the obstacle to be removed.


'''Examples'''
=== RemoveComboAction ===
* <code>remove_collision obstacle</code> (it can one added with add_collision or an existing zone in the .tmx file).
Removes a registered combo sequence from the ComboDetector.
 
'''Usage'''
<code>
 
remove_combo  <combo_name>[,buttons]
 
</code>
'''Parameters'''
* <code>combo_name</code>: Required. A name or ID for the combo (used for logging).
* <code>buttons</code>: Required. A colon-separated list of button names (e.g. LEFT:RIGHT:A).
 
=== RemoveContactsAction ===
Remove contact from the app.
 
'''Usage'''
<code>


== remove_contacts ==
remove_contacts <character>,<slug>
Remove contact from the app (Nu Phone).


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>slug</code>: slug name (e.g. "npc_maple").
* <code>slug</code>: slug name (e.g. "npc_maple").


'''Examples'''
=== RemoveFlairAction ===
* <code>remove_contacts npc_maple</code>
Remove a flair from a monster.
 
'''Usage'''
<code>
 
remove_flair <variable>,<category>
 
</code>
'''Parameters'''
* <code>variable</code>: The name of the variable that holds the monster's UUID.
* <code>category</code>: The category of the flair to remove. If omitted, all flairs will be removed.


== remove_held_item ==
=== RemoveHeldItemAction ===
Removes a held item from a specific monster.
Removes a held item from a specific monster.


'''Usage'''
<code>
remove_held_item <variable>
</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.


'''Examples'''
=== RemoveMonsterAction ===
* <code>remove_held_item variable</code>
Remove a monster from the party if the monster is there.
 
Monster is determined by instance_id, which must be passed in a game
variable.
 
'''Usage'''
<code>


== remove_monster ==
remove_monster <variable>
Remove a monster from the party if the monster is there.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.


'''Examples'''
=== RemoveNpcAction ===
* <code>get_player_monster name_variable</code>
Remove an NPC object from the list of NPCs.
* <code>remove_monster name_variable</code>
 
'''Usage'''
<code>


== remove_npc ==
remove_npc <npc_slug>
Removes an NPC from the current map.


</code>
'''Parameters'''
'''Parameters'''
* <code>name</code>: The name of the NPC to remove.
* <code>npc_slug</code>: Npc slug name (e.g. "npc_maple").


'''Examples'''
=== RemoveStateAction ===
* <code>remove_npc Maple</code> 
Remove the specified state or the last active one.
* <code>remove_npc Pine</code>
 
This action allows the removal of a specific state from the client's
active state list. If no state name is provided, it removes the current
state, except for certain protected states (e.g., "WorldState" and
"BackgroundState").
 
'''Usage'''
<code>


== remove_state ==
remove_state [state_name]
Remove the specified state or the last active one. This action allows the removal of a specific state from the client's active state list. If no state name is provided, it removes the current state, except for certain protected states (e.g., "WorldState" and "BackgroundState").


</code>
'''Parameters'''
'''Parameters'''
* <code>state_name</code>: The name of the state to remove (e.g., "PCState"). If not provided, the last active state will be removed, unless it's a protected state.
* <code>state_name</code>: The name of the state to remove (e.g., "PCState").
If not provided, the last active state will be removed, unless it's a
protected state.


'''Examples'''
=== RemoveStepTrackerAction ===
* <code>remove_state</code>
Removes a step tracker from a specific character.
* <code>remove_state JournalInfoState</code>
 
'''Usage'''
<code>


== remove_step_tracker ==
remove_step_tracker <character>,<tracker_id>
Removes an NPC from the current map.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or an NPC slug name (e.g., "npc_maple").
* <code>character</code>: Either "player" or an NPC slug name (e.g., "npc_maple").
* <code>tracker_id</code>: Unique name for identifying the step tracker.
* <code>tracker_id</code>: Unique name for identifying the step tracker.


'''Examples'''
=== RemoveTechAction ===
* <code>remove_step_tracker npc_maple,tracker_id</code>
Remove a specific technique from a specific monster in the party.
 
'''Usage'''
<code>


== remove_tech ==
remove_tech <tech_id>[,<force_remove>]
Remove a specific technique from a specific monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>tech_id</code>: Name of the variable where the technique ID is stored.
* <code>tech_id</code>: Name of the variable where the technique ID is stored.
* <code>force_remove</code>: Optional string flag to override forget rules. Accepts "true", "1", or "yes" (case-insensitive).
* <code>force_remove</code>: Optional string flag to override forget rules.
Accepts "true", "1", or "yes" (case-insensitive).


'''Examples'''
'''Examples'''
* <code>remove_tech name_variable</code>
* "remove_tech name_variable"
* <code>remove_tech name_variable,true</code>
* "remove_tech name_variable,true"
* "remove_tech name_variable,1"


== remove_tracker ==
=== RemoveTrackerAction ===
Remove tracker.
Remove tracker.


'''Usage'''
<code>
remove_tracker <character>,<location>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>location</code>: location name (e.g. "paper_town").
* <code>location</code>: location name (e.g. "paper_town").


'''Examples'''
=== RenameMonsterAction ===
* <code>remove_tracker player,paper_town</code>
Open the text input screen to rename the monster.
 
'''Usage'''
<code>


== rename_monster ==
rename_monster <variable>
Open the text input screen to rename the monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.
=== RenamePlayerAction ===
Open the text input screen to rename the character.
'''Usage'''
<code>
rename_player <character> [random]
</code>
'''Parameters'''
* <code>character</code>: Either "player" or an NPC slug (e.g. "npc_maple")
* <code>random</code>: Adding "random" makes appear the dontcare button in the input.
=== ReplacePartyFromYamlAction ===
Replaces a character's party with a predefined set of monsters from a YAML file.
This action loads a named party configuration from a YAML file and assigns it
to the specified character (either the player or an NPC). Each monster entry
in the YAML can define attributes like slug, level, and weight for random selection.
'''Usage'''
<code>
replace_party_from_yaml <character>,<yaml_file>,<set_name>
</code>
'''Parameters'''
* <code>character</code>: Either "player" or an NPC slug (e.g. "npc_maple").
* <code>yaml_file</code>: Name of the YAML file (without extension) located in the mods folder.
* <code>set_name</code>: The key of the party to use within the YAML file.


'''Examples'''
'''Examples'''
* <code>rename_monster name_variable</code> 
* "replace_party_from_yaml npc_maple,parties,starter_set"


== rename_player ==
=== ReplaceTechsFromYamlAction ===
Open the text input screen to rename the player.
Replaces a monster's moveset using a predefined set from a YAML file.


'''Usage'''
<code>
replace_techs_from_yaml <variable>,<yaml_file>,<set_name>
</code>
'''Parameters'''
'''Parameters'''
* <code>None</code>
* <code>variable</code>: Name of the variable where the monster UUID is stored.
* <code>yaml_file</code>: Path to the YAML file containing movesets.
* <code>set_name</code>: The key of the moveset to use within the YAML file.


'''Examples'''
'''Examples'''
* <code>rename_player</code>
* "replace_techs_from_yaml monster_id,movesets,starter_set"


== rumble ==
=== RumbleAction ===
Rumble available controllers with rumble support.
Rumble available controllers with rumble support.


'''Usage'''
<code>
rumble <duration>,<power>[,period][,delay][,attack_length]
[,attack_level][,fade_length][,fade_level][,direction]
</code>
'''Parameters'''
'''Parameters'''
* <code>duration</code>: Time in seconds to rumble for.
* <code>duration</code>: Time in seconds to rumble for.
* <code>power</code>: Percentage of power to rumble (0 to 100).
* <code>power</code>: Percentage of power to rumble (0 to 100).
* <code>period</code>: Time period between vibrations in milliseconds. Default 25.
* <code>period</code>: Time period between vibrations in milliseconds.
* <code>delay</code>: Time in seconds before the rumble starts. Default 0.
Default 25.
* <code>attack_length</code>: Time in milliseconds for the rumble to ramp up. Default 256.
* <code>delay</code>: Time in seconds before the rumble starts.
* <code>attack_level</code>: Initial intensity level during ramp-up. Default 0.
Default 0.
* <code>fade_length</code>: Time in milliseconds for the rumble to fade out. Default 256.
* <code>attack_length</code>: Time in milliseconds for the rumble to ramp up.
* <code>fade_level</code>: Final intensity level during ramp-down. Default 0.
Default 256.
* <code>direction</code>: Direction of the rumble effect, for spatial control. Default 16384.
* <code>attack_level</code>: Initial intensity level during ramp-up.
Default 0.
* <code>fade_length</code>: Time in milliseconds for the rumble to fade out.
Default 256.
* <code>fade_level</code>: Final intensity level during ramp-down.
Default 0.
* <code>direction</code>: Direction of the rumble effect, for spatial control.
Default 16384.
 
=== RumblePatternAction ===
Play a named rumble pattern on available controllers.
 
'''Usage'''
<code>
 
rumble_pattern <pattern_name>[,target]
 
</code>
'''Parameters'''
* <code>pattern_name</code>: Name of the pattern ('pulse', 'heartbeat', 'explosion').
* <code>target</code>: Optional device index (-1 for all). Default -1.
 
=== SaveGameAction ===
Saves the game.
 
If the index parameter is absent, then it'll create
slot4.save
 
index = 0 > slot 1
index = 1 > slot 2
index = 2 > slot 3
 
'''Usage'''
<code>


'''Examples'''
save_game [index]
* <code>rumble duration,power</code>
 
</code>
'''Parameters'''
* <code>index</code>: Selected index.
 
* <code>eg</code>: "save_game" (slot4.save)
* <code>eg</code>: "save_game 1"
 
=== SaveTimestampAction ===
Saves the current Unix timestamp (in seconds) into a game variable.
 
'''Usage'''
<code>


== save_game ==
save_timestamp <variable>
Saves the game. If the index parameter is absent, then it'll create slot4.save (index = 0 > slot 1, index = 1 > slot 2, index = 2 > slot 3)


</code>
'''Parameters'''
'''Parameters'''
* <code>index</code>: Selected index. (optional)
* <code>variable</code>: The name of the game variable to store the timestamp in.


'''Examples'''
=== ScreenTransitionAction ===
* <code>save_game</code> (it's going to save slot4.save)
Initiate a screen transition that blocks until both fade out and fade in
* <code>save_game 1</code> (it's going to save slot2.save)
are complete.
 
'''Usage'''
<code>


== screen_transition ==
screen_transition [trans_time][,rgb]
Fades the screen to black and back over <code>x</code> seconds.


</code>
'''Parameters'''
'''Parameters'''
* <code>trans_time</code>: Time in seconds - default 0.3 (optional).
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255) (optional)
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)


'''Examples'''
* <code>eg</code>: "screen_transition 3"
* <code>screen_transition 2</code>
* <code>eg</code>: "screen_transition 3,255:0:0:50" (red)
 
=== SetBattleAction ===
Appends a new battle to the player's battle history.
 
'''Usage'''
<code>


== set_battle ==
set_battle <fighter>,<result>,<opponent>
Append a new element in player.battles.


</code>
'''Parameters'''
'''Parameters'''
* <code>fighter</code>: Npc slug name (e.g. "npc_maple").
* <code>fighter_slug</code>: The slug of the battle participant (e.g., "player").
* <code>result</code>: One among "won", "lost" or "draw"
* <code>outcome</code>: The desired battle outcome ("won", "lost", or "draw").
* <code>opponent</code>: Npc slug name (e.g. "npc_maple").
* <code>opponent_slug</code>: The slug of the opponent (e.g., "npc_maple").
 
* <code>Example</code>:
`set_battle player,won,npc_maple`
Add the 'player' has won against 'npc_maple' to the history.


'''Examples'''
=== SetBillAction ===
* <code>set_battle player,won,npc_maple</code> (player won against npc_maple)
Initializes or updates a bill for a character, including its amount,
interest rate, late fee and share rate.
 
'''Usage'''
<code>


== set_bill ==
set_bill <character>,<bill_slug>[,amount][,interest_rate][,late_fee][,share_rate]
Set a bill.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: "player" or the slug of an NPC (e.g. "npc_maple").
* <code>bill_slug</code>: Slug of the bill.
* <code>bill_slug</code>: identifier for the bill (must be translated in en_US base.po).
* <code>amount</code>: Amount of money (>= 0) (default 0)
* <code>amount</code>: initial amount of the bill (optional, defaults to 0).
* <code>interest_rate</code>: interest rate applied to the bill (optional, e.g. 0.1 for 10%).
* <code>late_fee</code>: flat fee added to the bill when triggered (optional, eg. 10).
* <code>share_rate</code>: percentage of battle earnings automatically applied to the bill
(optional, e.g. 0.2 for 20%).


'''Examples'''
'''Examples'''
* <code>set_bill player,bill_slug</code>
* set_bill player,bill_cathedral,100,0.1,50,0.5
* <code>set_bill player,bill_slug,500</code>
* set_bill npc_maple,bill_rent,,0.05,25,0.2
 
* <code>Notes</code>:
* Interest and late fee are stored but not automatically applied.
* Use separate actions to trigger interest or fee accumulation.
* Amount must be non-negative.


== set_bubble ==
=== SetBubbleAction ===
Put a bubble above player sprite.
Put a bubble above player sprite.


'''Usage'''
<code>
set_bubble <npc_slug>[,bubble]
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>npc_slug</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>bubble</code>: dots, drop, exclamation, heart, note, question, sleep, angry, confused, fireworks
* <code>bubble</code>: dots, drop, exclamation, heart, note, question, sleep,
angry, confused, fireworks
 
* <code>Example usage</code>:
"set_bubble spyder_shopassistant" (remove bubble from NPC)
"set_bubble spyder_shopassistant,note" (set bubble for NPC)
"set_bubble player,note" (set bubble for player)
"set_bubble player" (remove bubble from player)
 
=== SetCharAttributeAction ===
Set the given attribute of the character to the given value.
 
'''Usage'''
<code>
 
set_char_attribute <character>,<attribute>,<value>
 
</code>
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>attribute</code>: Name of the attribute.
* <code>value</code>: Value of the attribute.
 
=== SetPlayerBirthdayAction ===
Open the date picker to set the player's birthday.
 
'''Usage'''
<code>
 
set_char_birthday <character> [random]


'''Examples'''
</code>
* <code>set_bubble spyder_shopassistant</code> (remove bubble NPC)
'''Parameters'''
* <code>set_bubble spyder_shopassistant,note</code> (set bubble NPC)
* <code>character</code>: Either "player" or an NPC slug (e.g. "npc_maple")
* <code>set_bubble player,note</code> (set bubble player)
* <code>random</code>: If provided, assigns a random birthday instead of
* <code>set_bubble player</code> (remove bubble player)
opening the date picker.


== set_cipher ==
=== SetCipherAction ===
Toggles ciphering for dialogue by enabling or disabling the CipherProcessor.
Toggles ciphering for dialogue by enabling or disabling the CipherProcessor.


'''Usage'''
<code>
set_cipher <option>,<cipher_map>
</code>
* <code>Parameters</code>:
* <code>option</code>:
* "enable": Activates ciphering using the provided cipher map (if any).
* "disable": Disables ciphering entirely.
* <code>cipher_map</code>:
The filename (without extension) of a YAML file located in the mods folder.
* If omitted during "enable", the default cipher map is used.
* Ignored when option is "disable".
=== SetEconomyAction ===
Sets the economy (prices and initial stock of items/monsters) for a specific NPC.
This action orchestrates loading the economy data and then applying it to
the target character's shop/inventory, including handling initial quantities
and variable-based availability.
'''Usage'''
<code>
set_economy <npc_slug>,<economy_slug>
</code>
'''Parameters'''
'''Parameters'''
* <code>option</code>: "enable": Activates ciphering using the provided cipher map (if any) OR "disable": Disables ciphering entirely.
* <code>npc_slug</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>cipher_map</code>: the filename (without extension) of a YAML file located in the mods folder. If omitted during "enable", the default cipher map is used. Ignored when option is "disable".
* <code>economy_slug</code>: Slug of an economy.
 
=== SetEnvironmentAction ===
Switch or unload the active battle environment.
 
'''Usage'''
<code>
 
set_environment [slug]
 
</code>
'''Parameters'''
* <code>slug</code>: Optional. If provided, loads the environment slug from the
database. If omitted, unloads the current environment.


'''Examples'''
'''Examples'''
* <code>set_cipher enable</code>
* set_environment grass
* set_environment


== set_economy ==
=== SetFacingModeAction ===
Sets the economy (prices and initial stock of items/monsters) for a specific NPC. This action orchestrates loading the economy data and then applying it to the target character's shop/inventory, including handling initial quantities and variable-based availability.
Change the facing mode of an NPC.


'''Usage'''
<code>
set_facing_mode <npc_slug>,<mode>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>npc_slug</code>: Slug of the NPC whose facing mode will be changed.
* <code>economy_slug</code>: Slug of an economy.
* <code>mode</code>: One of the valid facing mode names:
* follow_movement
* locked
* scripted
 
This action immediately updates the NPC's facing behavior. When set to
'locked' or 'scripted', the NPC will no longer automatically rotate to
match movement direction. When set to 'follow_movement', the NPC resumes
normal facing updates driven by the PathController.
 
=== SetKennelVisibleAction ===
Set a kennel's visibility state for a character.
 
* <code>From hidden to visible</code>:  
set_kennel_visible player,name_kennel,true


'''Examples'''
* <code>From visible to hidden</code>:
* <code>set_economy spyder_shopkeeper,spyder_candy_scoop</code>
set_kennel_visible player,name_kennel,false


== set_kennel_visible ==
'''Usage'''
Set the kennel visible or hidden.
<code>


From hidden to visible: set_kennel_visible name_kennel,true
set_kennel_visible <character>,<kennel>,<visible>
From visible to hidden: set_kennel_visible name_kennel,false


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or NPC slug name (e.g. "npc_maple").
* <code>kennel</code>: Name of the kennel.
* <code>kennel</code>: Name of the kennel.
* <code>visible</code>: true/false.
* <code>visible</code>: Optional string flag to set visibility.
Accepts "true", "1", "yes" for visible (case-insensitive).
Defaults to False when omitted or invalid.
 
=== SetLayerAction ===
Allows to change the color of the transparent layer.


'''Examples'''
'''Usage'''
* <code>set_kennel_visible npc_maple,name_kennel,true</code>
<code>
* <code>set_kennel_visible npc_maple,name_kennel,false</code>


== set_layer ==
set_layer <rgb>
Allows to change the color of the transparent layer.


</code>
'''Parameters'''
'''Parameters'''
* <code>rgb</code>: color (eg red > 255,0,0,128 > 255:0:0:128) - default transparent
* <code>rgb</code>: color (eg red > 255,0,0,128 > 255:0:0:128)
default transparent


'''Examples'''
* <code>Note</code>: this is not a separate state, so it's advisable
* <code>set_layer 255:0:0:128</code>
to add a 4th value to the rgb, if not you're not
going to see the character, ideally 128.


== set_mission ==
=== SetMissionAction ===
Set missions by updating it and by checking the prerequisites.
Set missions by updating it and by checking the prerequisites.


'''Usage'''
<code>
set_mission <character>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").


'''Examples'''
=== SetMoneyAction ===
* <code>set_mission player</code>
Set an amount of money for a specific slug.
 
'''Usage'''
<code>


== set_money ==
set_money <slug>,[amount]
Set an amount of money for a specific slug.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>amount</code>: Amount of money (>= 0) (default 0)
* <code>amount</code>: Amount of money (>= 0) (default 0)


'''Examples'''
=== SetMonsterAttributeAction ===
* <code>set_money player</code>
Set the given attribute of the monster to the given value.
* <code>set_money player,500</code>
 
'''Usage'''
<code>


== set_monster_attribute ==
set_monster_attribute <variable>,<attribute>,<value>
Set the given attribute of the monster to the given value.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.
Line 1,265: Line 2,348:
* <code>value</code>: Value of the attribute.
* <code>value</code>: Value of the attribute.


'''Examples'''
=== SetMonsterFlairAction ===
* <code>set_monster_attribute name_variable,name,jimmy</code> (the monster will be named jimmy)
Set or replace a monster's flair in a given category.
 
'''Usage'''
<code>


== set_monster_flair ==
set_monster_flair <variable>,<category>,<flair>[,<sprite_type_1>:<sprite_type_2>:...]
Set a monster's flair to the given value.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are changed.
* <code>variable</code>: Name of the variable that holds the monster's UUID.
* <code>category</code>: Category of the monster flair.
* <code>category</code>: Category of the monster flair.
* <code>flair</code>: Name of the monster flair.
* <code>flair</code>: Name of the monster flair.
* <code>sprite_type(s)</code>: Optional pipe-separated list of sprite types
* <code>(e.g., front</code>: menu01)
* <code>Behavior</code>:
* If the category already has a flair, it will be replaced.
* If the category is new, the flair will be added.
* If sprite types are provided, the flair will only apply to those views.
=== SetMonsterHealthAction ===
Set the hp of a monster in the current player's party.


'''Examples'''
'''Usage'''
* <code>get_player_monster name_variable</code>
<code>
* <code>set_monster_flair name_variable,category,flair</code>


== set_monster_health ==
set_monster_health [variable][,health]
Set the hp of a monster in the current player's party. The action parameters may contain a monster slot and the amount of health.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are healed. (optional)
* <code>variable</code>: Name of the variable where to store the monster id. If no
* <code>health</code>: A float value between 0 and 1, which is the percent of max hp to be restored to. A int value, which is the number of HP to be restored to. If no health is specified, the hp is maxed out. (optional)
variable is specified, all monsters are healed.
* <code>health</code>: A float value between 0 and 1, which is the percent of max
hp to be restored to. A int value, which is the number of 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.


'''Examples'''
'''Usage'''
* <code>set_monster_health</code> (heals all the monsters in the party)
<code>
or
* <code>get_player_monster name_variable</code>
* <code>set_monster_health name_variable,1</code>


== set_monster_level ==
set_monster_level [variable][,levels_added]
Change the level of a monster in the current player's party.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters are changed. (optional)
* <code>variable</code>: Name of the variable where to store the monster id. If no
* <code>levels_added</code>: Number of levels to add. Negative numbers are allowed. Default 1. (optional)
variable is specified, all monsters level up.
* <code>levels_added</code>: Number of levels to add. Negative numbers are allowed.
Default 1.
 
=== SetMonsterPlagueAction ===
Set a monster's plague to the given condition.


'''Examples'''
'''Usage'''
* <code>set_monster_level</code> (all the monsters in the party level up by 1)
<code>
or
* <code>get_player_monster name_variable</code>
* <code>set_monster_level name_variable,1</code>


== set_monster_plague ==
set_monster_plague <variable>,<plague_slug>,<condition>
Set a monster's plague to the given condition. '''To get the mechanics going, it's crucial to know that must be a technique called 'plague_slug' (eg. spyderbite)'''.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>plague_slug</code>: The slug of the plague to target.
* <code>plague_slug</code>: The slug of the plague to target.
* <code>condition</code>: Infected, inoculated, or None (removes the plague from the character, indicating a healthy state). (optional)
* <code>condition</code>: Infected, inoculated, or None (removes the plague from the
 
character, indicating a healthy state).
'''Examples'''
* <code>enforced_check</code>: Optional string flag to enforce eligibility rules.
* <code>get_player_monster name_variable</code>
Accepts "true", "1", or "yes" (case-insensitive).
* <code>set_monster_plague name_variable,spyderbite,infected</code>
Default is False (eligibility is bypassed).


== set_monster_status ==
=== SetMonsterStatusAction ===
Change the status of a monster in the current player's party.
Change the status of a monster in the current player's party.


'''Parameters'''
'''Usage'''
* <code>variable</code>: Name of the variable where to store the monster id. If no variable is specified, all monsters get/lose status.. (optional)
<code>
* <code>status</code>: Inoculated, healthy or infected, default healthy (optional)


'''Examples'''
set_monster_status [slot][,status]
* <code>set_monster_status</code> (all the monsters in the party lose their status)
or
* <code>get_player_monster name_variable</code>
* <code>set_monster_status name_variable,status_blinded</code>


== set_char_attribute ==
</code>
Set the given attribute of the character to the given value.
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id. If no
variable is specified, all monsters get/lose status.
* <code>status</code>: Status to set. If no status is specified, the status is
cleared.


'''Parameters'''
=== SetPartyAttributeAction ===
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
Set the given attribute of party's monsters to the given value.
* <code>attribute</code>: Name of the attribute.
* <code>value</code>: Value of the attribute.


'''Examples'''
'''Usage'''
* <code>set_char_attribute character,attribute,value</code>
<code>


== set_party_attribute ==
set_party_attribute <character>,<attribute>,<value>
Set the given attribute of party's monsters to the given value.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
Line 1,350: Line 2,448:
* <code>value</code>: Value of the attribute.
* <code>value</code>: Value of the attribute.


'''Examples'''
=== SetPartyStatusAction ===
* <code>set_party_attribute player,name,jimmy</code> (all the monsters in the party will be named jimmy)
Records important information about all monsters in the party.
 
'''Usage'''
<code>


== set_party_status ==
set_party_status <player>
Records important information about all monsters in the party (eg average level of the party, etc.)


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").


'''Examples'''
=== SetPricePolicyAction ===
* <code>set_party_status player</code>
Sets the PricePolicy for a specific NPC's economy.
 
'''Usage'''
<code>


== set_player_name ==
set_price_policy <npc_slug>,<policy_slug>
Set player name without opening the input screen.


</code>
'''Parameters'''
'''Parameters'''
* <code>choice</code>: Single name or multiple names separated by ":" (random choice). NB: the names must be in the en_US PO file.
* <code>npc_slug</code>: Either "player" or NPC slug (e.g. "npc_maple").
* <code>policy_slug</code>: Slug of a price policy (e.g. "black_market").
 
=== SetRandomVariableAction ===
Sets a key in the player's `game_variables` dictionary to a randomly
selected value from a specified list. Values can be repeated or
weighted to influence selection probability.


'''Examples'''
'''Usage'''
* <code>set_player_name jimmy</code>
<code>
* <code>set_player_name jimmy:richard:linus</code> (random choice among jimmy, richard and linus)
 
set_random_variable <variable>,<value1>:<value2>:<value3>


== set_price_policy ==
You can also use weighted values:
Sets the PricePolicy for a specific NPC's economy.
set_random_variable <variable>,<apple=1>:<banana=3>:<cherry=2>


</code>
'''Parameters'''
'''Parameters'''
* <code>npc_slug</code>: Either "player" or NPC slug (e.g. "npc_maple").
* <code>variable</code>: The name of the game variable to set.
* <code>policy_slug</code>: Slug of a price policy (e.g. "black_market") (YAML).
* <code>values</code>: A colon-separated string of values to choose from.
* Repeated values increase their selection chance.
* Alternatively, use `value=weight` to assign explicit weights.
 
=== SetRoutingPolicyAction ===
Sets or resets the routing policy for future monster additions.
This does not add a monster — it modifies how PartyHandler.add_monster behaves.


'''Examples'''
'''Usage'''
* <code>set_price_policy npc_maple,black_market</code>
<code>


== set_random_variable ==
set_routing_policy <npc_slug>[,policy_name]
Set the key in the player.game_variables dictionary with a random value.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable.
* <code>npc_slug</code>: NPC slug to apply the policy to.
* <code>values</code>: Multiple values of the variable separated with ":".
* <code>policy_name</code>: Name of the routing policy defined in routing_policies.yaml.


'''Examples'''
'''Examples'''
* <code>set_random_variable alpha,one:two:three</code> (variable "alpha" can be "alpha:one" or "alpha:two" or "alpha:three").
* set_routing_policy player,starter_policy
* set_routing_policy player,event_policy
* set_routing_policy player  # resets to 'default'


== set_teleport_faint ==
=== SetStepTrackerMilestoneShownAction ===
Marks a milestone on a step tracker as shown for a specific character.
 
'''Usage'''
<code>
 
set_step_tracker_milestone_shown <character>,<tracker_id>,<milestone>
 
</code>
'''Parameters'''
* <code>character</code>: Either "player" or an NPC slug name (e.g., "npc_maple").
* <code>tracker_id</code>: Unique name for identifying the step tracker.
* <code>milestone</code>: Step milestone to mark as shown.
 
=== SetTeleportFaintAction ===
Set teleport faint data
Set teleport faint data


'''Usage'''
<code>
set_teleport_faint <character>,<map_name>,<x>,<y>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
Line 1,401: Line 2,541:
* <code>y</code>: The y-coordinate to validate against.
* <code>y</code>: The y-coordinate to validate against.


'''Examples'''
=== SetTemplateAction ===
* <code>set_teleport_faint player,healing_center.tmx,6,7</code>
Switch template (sprite and combat_sheet).
 
Please remember that if you change the combat_sheet,
it automatically changes the combat_back.
 
* <code>Example</code>: if you put xxx, it's going to be xxx_back.png.
 
* <code>By using default</code>:
 
set_template player,default
 
it's going to reassign the default sprite.


== set_template ==
'''Usage'''
Switch template (sprite and combat_front).


Please remember that if you change the combat_front, automatically will change the combat_back.
<code>
Eg if you set the sprite xxx, then it's going to add _back.png -> xxx_back.png


By using default: <code>set_template player,default</code> it's going to reassign the default sprite
set_template <character>,<sprite>[,combat_sheet]


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>sprite</code>: must be inside mods/tuxemon/sprites, eg: adventurer_brown_back.png -> adventurer
* <code>combat_front</code>: must be inside mods/tuxemon/gfx/sprites/player, eg: adventurer.png -> adventurer (optional)


'''Examples'''
* <code>character</code>:
* <code>set_template player,adventurer,adventurer</code>
Either "player" or npc slug name (e.g. "npc_maple").
 
* <code>sprite</code>:
Must be inside mods/tuxemon/sprites.
* <code>Example</code>: adventurer_brown_back.png -> adventurer.
 
* <code>combat_sheet</code>:
Must be inside mods/tuxemon/gfx/sprites/player.
* <code>Example</code>: adventurer.png -> adventurer.


== set_tuxepedia ==
=== SetTuxepediaAction ===
Set the key and value in the Tuxepedia dictionary.
Set the key and value in the Tuxepedia dictionary.


'''Usage'''
<code>
set_tuxepedia <character>,<monster_slug>,<label>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>monster_slug</code>: Monster slug name (e.g. "rockitten").  
* <code>monster_slug</code>: Monster slug name (e.g. "rockitten").
* <code>label</code>: seen / caught
* <code>label</code>: seen / caught


'''Examples'''
=== SetVariableAction ===
* <code>set_tuxepedia player,rockitten,caught</code>
Updates the player's game variables by setting key-value pairs.


== set_variable ==
'''Usage'''
Updates the player's game variables by setting key-value pairs.
<code>


Also used to set the [[:Category:Environment|environment]].
set_variable <variable>:<value>[,<variable>:<value>]


</code>
'''Parameters'''
'''Parameters'''
* <code>set_variable variable_name:value</code>:
* <code>variable</code>: The name of the variable.
* <code>variable_name</code>: The name of the variable.
* <code>value</code>: The assigned value for the variable.
* <code>value</code>: The assigned value for the variable.


This implementation supports multiple parameters, allowing multiple variable assignments in one call.
This implementation supports multiple parameters, allowing multiple
variable assignments in one call.


'''Examples'''
=== SetWeatherAction ===
* <code>set_variable battle_won:yes</code>
Sets the weather to a specific slug using the WorldWeatherManager.
* <code>set_variable environment:grass</code>
If no slug is provided, it triggers a weather advancement check.
* <code>set_variable <variable>:<value>[,<variable>:<value>]</code>
 
'''Usage'''
<code>
 
set_weather <weather_slug>     # Sets weather directly
set_weather                    # Advances weather based on previsions
 
</code>
'''Parameters'''
* <code>slug</code>: Optional weather slug (e.g., "rain", "sunny", "foggy").
 
=== ShowMonsterAction ===
Change to MonsterInfoState.
 
This action transitions to the MonsterInfoState, displaying detailed
information about a specific monster.
 
'''Usage'''
<code>


== show_monster ==
monster_info_state <monster_variable>
Change to MonsterInfoState. This action transitions to the MonsterInfoState, displaying detailed information about a specific monster.


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_variable</code>: The name of the game variable holding the monster's UUID.
* <code>monster_variable</code>: The name of the game variable holding the monster's UUID.


'''Examples'''
=== SpawnMonsterAction ===
* <code>show_monster player</code>
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.
 
'''Usage'''
<code>


== spawn_monster ==
spawn_monster [npc_slug]
Breed a new monster. Add a new monster, created by breeding the two given monsters (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.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple"). The one who is going to receive the new born.
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
the one who is going to receive the new born
 
=== StartBattleAction ===
Start a battle between two characters and switch to the combat module.


'''Examples'''
'''Usage'''
* <code>spawn_monster</code>
<code>


== start_battle ==
start_battle <character1>,<character2>[,music]
Start a battle between two characters and switch to the combat module.


</code>
'''Parameters'''
'''Parameters'''
* <code>character1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character2</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character2</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>music</code>: The name of the music file to play. (optional)
* <code>music</code>: The name of the music file to play (Optional).
 
=== StartCinemaModeAction ===
Start cinema mode by animating black bars to narrow the aspect ratio.
 
For a cinematic experience, specify the width of the horizontal and
vertical black bars as a ratio of the screen resolution.
* <code>For example, to achieve a 2.39</code>: 1 aspect ratio on a 1920x1080 screen,
you would set the horizontal ratio to 0.42 (1920 / 1080 * (16/9 - 2.39/1))
and the vertical ratio to 0 (no vertical bars).
 
By default only bar up and down.


'''Examples'''
'''Usage'''
* <code>start_battle player,npc_maple</code>
<code>
* <code>start_battle npc_maple,npc_apple</code>


== start_cinema_mode ==
start_cinema_mode [aspect_y_ratio][,aspect_x_ratio]
Start cinema mode by animating black bars to narrow the aspect ratio.
For a cinematic experience, specify the width of the horizontal and vertical black bars as a ratio of the screen resolution. For example, to achieve a 2.39:1 aspect ratio on a 1920x1080 screen, you would set the horizontal ratio to 0.42 (1920 / 1080 * (16/9 - 2.39/1)) and the vertical ratio to 0 (no vertical bars). By default only bar up and down.


</code>
'''Parameters'''
'''Parameters'''
* <code>aspect_y_ratio</code>: The width of the horizontal black bars as a ratio of the screen resolution. Default standard cinema mode.
* <code>aspect_y_ratio</code>: The width of the horizontal black bars as a ratio of
* <code>aspect_x_ratio</code>: The width of the vertical black bars as a ratio of the screen resolution. Default None.
the screen resolution. Default standard cinema mode.
* <code>aspect_x_ratio</code>: The width of the vertical black bars as a ratio of
the screen resolution. Default None.


'''Examples'''
=== StartDoubleBattleAction ===
* <code>start_cinema_mode</code> default, bar up and down
Start a double battle between two characters and switch to the combat module.
* <code>start_cinema_mode ,2.0</code> bar left and right
 
* <code>start_cinema_mode 2.0</code> bar up and down
'''Usage'''
* <code>start_cinema_mode 2.0,2.0</code> bar up, down, left and right
<code>


== start_double_battle ==
start_double_battle <character1>,<character2>[,music]
Start a double battle between two characters and switch to the combat module. At least 3 monsters in total (eg 2 vs 1 or 1 vs 2).


</code>
'''Parameters'''
'''Parameters'''
* <code>character1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character2</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>character2</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>music</code>: The name of the music file to play. (optional)
* <code>music</code>: The name of the music file to play (Optional).
 
=== StopCinemaModeAction ===
Stop cinema mode by animating black bars back to the normal aspect ratio.
 
'''Usage'''
<code>


'''Examples'''
stop_cinema_mode
* <code>start_double_battle player,npc_maple</code>
</code>
* <code>start_double_battle npc_maple,npc_apple</code>
 
=== 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.
 
'''Usage'''
<code>


== stop_cinema_mode ==
store_monster <variable>[,box]
Stop cinema mode by animating black bars back to the normal aspect ratio.


</code>
'''Parameters'''
'''Parameters'''
* <code>None</code>
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>box</code>: An existing box where the monster will be stored.
 
=== StorePartyAction ===
Store the entire party in a box.
 
Save all monsters from the character's party into the named storage box,
removing them from the party if successful.


'''Examples'''
'''Usage'''
* <code>stop_cinema_mode</code>
<code>


== store_monster ==
store_party <character>[,box]
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.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>character</code>: Either "player" or an NPC slug (e.g. "npc_maple").
* <code>box</code>: An existing box where the monster will be stored. (optional)
* <code>box</code>: An existing box where the monsters will be stored.
If omitted, defaults to KENNEL.
 
=== TeleportAction ===
Teleport a character to a specific map and tile coordinates.
 
If a screen transition is in progress, the teleport will be queued
and executed at the apex of the transition.


'''Examples'''
'''Usage'''
* <code>get_player_monster name_variable</code>
<code>
then:
* <code>store_monster name_variable</code>
or
* <code>store_monster name_variable,name_kennel</code>


== teleport_faint ==
teleport <character>,<map_name>,<x>,<y>
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.


</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Slug of the character to teleport.
* <code>trans_time</code>: Transition time in seconds - default 0.3.
* <code>map_name</code>: Name of the map to teleport to.
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
* <code>x</code>: X coordinate of the map to teleport to.
* <code>y</code>: 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.


'''Examples'''
'''Usage'''
* <code>teleport_faint player</code>
<code>
* <code>teleport_faint player,6.9</code>
* <code>teleport_faint player,3,255:0:0:50</code> (red)


== teleport ==
teleport_faint <character>,<healing>[,trans_time][,rgb]
Teleports the player to a given position on a map. This teleport is immediate and does not have any transition animation.


</code>
'''Parameters'''
'''Parameters'''
* <code>map_name</code>: The map file to teleport the player to.
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>x</code>: The X-tile coordinate to teleport the player to.
* <code>healing</code>: Trigger healing string flag ("true", "1", "yes" for True),
* <code>y</code>: The Y-tile coordinate to teleport the player to.
* <code>trans_time</code>: Transition time in seconds - default 0.3
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)


'''Examples'''
* <code>eg</code>: "teleport_faint player,true,3"
* <code>teleport map1.tmx,3,4</code>
* <code>eg</code>: "teleport_faint player,true,3,255:0:0:50" (red)
* <code>teleport room1.tmx,8,1</code>


== toggle_evolution_block ==
=== ToggleEvolutionBlockAction ===
Blocks or unblocks a specific evolution for a monster.
Blocks or unblocks a specific evolution for a monster.


'''Usage'''
<code>
toggle_evolution_block <character> <monster_variable> <evolution_slug> <action>
</code>
'''Parameters'''
'''Parameters'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
Line 1,561: Line 2,801:
* <code>action</code>: "block" to permanently block, "unblock" to unblock.
* <code>action</code>: "block" to permanently block, "unblock" to unblock.


'''Examples'''
=== TradingAction ===
* <code>toggle_evolution_block player,variable_name,rockat,block</code> 
Select a monster in the player party and trade.
* <code>toggle_evolution_block player,variable_name,rockat,unblock</code>  
 
'''Usage'''
<code>


== trading ==
trading <variable>,<added>
Select a monster in the player party and trade. It's advisable to use it with the condition <code>not has_monster monster_slug</code>.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id (removed).
* <code>variable</code>: Name of the variable where to store the monster id (removed).
* <code>added</code>: Slug monster or Name of the variable where to store the monster id (added).
* <code>added</code>: Slug monster or Name of the variable where to store the monster
id (added).


'''Examples'''
eg. "trading name_variable,apeoro"
* <code>get_player_monster name_variable</code>
eg. "trading name_variable,name_variable"
then
 
* <code>trading name_variable,nut</code>
=== TransferMoneyAction ===
Transfer money between entities.
 
'''Usage'''
<code>


== transfer_money ==
transfer_money <slug1>,<amount>,<slug2>
Transfer money between entities. Both entities needs to have a wallet.


</code>
'''Parameters'''
'''Parameters'''
* <code>slug1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>slug1</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>amount</code>: Amount of money.
* <code>amount</code>: amount of money.
* <code>slug2</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>slug2</code>: Either "player" or character slug name (e.g. "npc_maple").


'''Examples'''
* <code>eg</code>: player,100,mom (player transfer 100 to mom)
* <code>transfer_money player,100,npc_mom</code> (player transfers 100 to mom)
 
=== 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.
 
'''Usage'''
<code>


== transition_teleport ==
transition_teleport <character>,<map_name>,<x>,<y>[,trans_time][,rgb]
Teleports the player to a given position on a map with a screen transition over <code>x</code> seconds.


</code>
'''Parameters'''
'''Parameters'''
* <code>map_name</code>: The map file to teleport the player to.
* <code>character</code>: Slug of the character to teleport.
* <code>x</code>: The X-tile coordinate to teleport the player to.
* <code>map_name</code>: Name of the map to teleport to.
* <code>y</code>: The Y-tile coordinate to teleport the player to.
* <code>x</code>: X coordinate of the map to teleport to.
* <code>trans_time</code>: The time in seconds - default 2. (optional)
* <code>y</code>: Y coordinate of the map to teleport to.
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255) (optional)
* <code>trans_time</code>: (Optional) Transition time in seconds. Default is 0.3.
* <code>rgb</code>: (Optional) Transition color in RGB format (e.g. "255:0:0" for red).
Default is black (0,0,0).
 
=== TransitionTeleportReturnAction ===
Teleport a character back to their previously recorded location,
using a screen transition.
 
This action retrieves the last executed teleport request and sends
the character back to its source map and coordinates. It must be
used after a teleport that stored return data (e.g. source_map, source_x, source_y).


'''Examples'''
'''Usage'''
* <code>teleport map2.tmx,1,6,1.5</code> 
<code>
* <code>teleport room1.tmx,8,1,4</code>


== translated_dialog_choice ==
transition_teleport_return <character>,<facing>[,trans_time][,rgb]
Asks the player to select a choice. The translations for the text are looked up based on a given key.


</code>
'''Parameters'''
'''Parameters'''
* <code>choice_keys</code>: Keys to reference translated text choices separated by colons.
* <code>character</code>: Either "player" or character slug name (e.g. "npc_maple").
* <code>variable</code>: The variable to store the answer which will be the key for the translated text.
* <code>facing</code>: One of "up", "down", "left", "right". Case-insensitive.
* <code>trans_time</code>: (Optional) Transition time in seconds. Default is 0.3.
* <code>rgb</code>: (Optional) Transition color in RGB format (e.g. "255:0:0" for red).
Default is black (0,0,0).
 
* <code>Requirements</code>:
* A previous teleport must have been executed and stored in
`teleporter.last_teleport_request`.
* The previous request must include valid source map and coordinates.


'''Examples'''
* <code>Example</code>:
* <code>translated_dialog_choice yes:no,myvariable</code>
* <code>transition_teleport_return player,down,0.5,255</code>: 255:255
 
=== 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.
 
'''Usage'''
<code>


== translated_dialog ==
translated_dialog <text>[,avatar][,position][,style]
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.


</code>
'''Parameters'''
'''Parameters'''
* <code>text</code>: The msgid in the PO file.
* <code>text</code>: Text of the dialog.
* <code>avatar</code>: 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.
* <code>avatar</code>: Monster avatar. If it is a number, the monster is the
* <code>position</code>: Position of the dialog box. Can be 'top', 'bottom', 'center', 'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'. Default 'bottom'.
corresponding monster slot in the player's party.
* <code>h_alignment</code>: Alignment of text in the dialog box, it can be 'left', 'center' or 'right'. Default 'left'.
If it is a string, we're referring to a monster by name.
* <code>v_alignment</code>: Alignment of text in the dialog box, it can be 'bottom', 'center' or 'top'. Default 'top'.
* <code>position</code>: Position of the dialog box. Can be 'top', 'bottom', 'center',
'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'.
Default 'bottom'.
* <code>h_alignment</code>: Alignment of text in the dialog box, it can be 'left', 'center'
or 'right'. Default 'left'.
* <code>v_alignment</code>: Alignment of text in the dialog box, it can be 'bottom',
'center' or 'top'. Default 'top'.
* <code>style</code>: a predefined style in db/dialogue/dialogue.json
* <code>style</code>: a predefined style in db/dialogue/dialogue.json
=== TranslatedDialogChoiceAction ===
Ask the player to make a choice.
'''Usage'''
<code>
translated_dialog_choice <choices>,<variable>
</code>
'''Parameters'''
* <code>choices</code>: List of possible choices, separated by a colon ":".
* <code>variable</code>: Variable to store the result of the choice.
=== TriggerStatusAction ===
Triggers the current status effect of a monster (e.g., poison, burn, sleep).
'''Usage'''
<code>
trigger_status <variable>,<status_name>
</code>
'''Parameters'''
* <code>variable</code>: Name of the variable containing the monster ID. If not specified,
all monsters in the party will be affected.
* <code>status_name</code>: Optional. If provided, only triggers the status effect if it matches
the monster's current status slug.


'''Examples'''
'''Examples'''
* <code>translated_dialog msgid</code>
* "trigger_status name_variable,poison"
* "trigger_status name_variable"
* "trigger_status"
 
=== TuneRadioAction ===
Launches the NuPhoneRadio interface for a given character, optionally tuned
to a specific frequency.
 
This action transitions the game into a radio interface state, allowing the
player to access broadcasts associated with a specific NPC. It can launch
either the standard radio menu or the tuner interface, depending on whether
a frequency is provided.
 
This is typically used in scripted events to simulate tuning into a radio
station from a character's perspective or location, enabling dynamic
storytelling and immersive audio experiences.
 
'''Usage'''
<code>
 
tune_radio <character_slug>
tune_radio <character_slug>[,frequency]
 
</code>
'''Parameters'''
* <code>character_slug</code>: The slug of the character (NPC) whose context will be
used to determine available radio stations and broadcasts.
* <code>frequency</code>: If provided, launches the tuner interface and attempts to
tune directly to the specified frequency (in MHz). If omitted, the
standard radio menu is shown instead.


== unload_sound ==
=== UnloadSoundAction ===
Unload a specific sound from memory cache, or all sounds if no filename is given.
Unload a specific sound from memory cache, or all sounds if no filename is given.


'''Usage'''
<code>
unload_sound <filename>
unload_sound
</code>
'''Parameters'''
'''Parameters'''
* <code>filename</code>: Name of the sound file to unload. If omitted, all cached sounds will be removed from memory.
* <code>filename</code>: Name of the sound file to unload.
If omitted, all cached sounds will be removed from memory.


'''Examples'''
=== UnlockControlsAction ===
* <code>unload_sound</code>
* <code>unload_sound filename</code>
 
== unlock_controls ==
Unlock player controls
Unlock player controls


'''Parameters'''
'''Usage'''
* <code>None</code>
<code>


'''Examples'''
unlock_controls
* <code>unlock_controls</code>
</code>


== unpause_music ==
=== UnpauseMusicAction ===
Unpause the current (paused) music playback.
Unpause the current (paused) music playback.


'''Parameters'''
'''Usage'''
* <code>None</code>
<code>


'''Examples'''
unpause_music
* <code>pause_music</code>
</code>


== update_cipher ==
=== UpdateCipherAction ===
Updates the list of unlocked letters for a character used by the CipherProcessor.
Updates the list of unlocked letters for a character used by the CipherProcessor.


'''Parameters'''
'''Usage'''
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
 
* <code>letter</code>: A single uppercase letter (or multiple separated by ':') to add to the character's unlocked set. If omitted, no new letters will be added, but the CipherProcessor will be updated with the current unlocked state.
<code>
 
update_cipher <character>[,letter]
 
</code>
* <code>Parameters</code>:
 
* <code>character</code>:  
Either "player" or npc slug name (e.g. "npc_maple").


'''Examples'''
* <code>letter</code>:
* <code>update_cipher player,a:b:c:d</code>
* <code>A single uppercase letter (or multiple separated by '</code>: ') to add to
the character's unlocked set. If omitted, no new letters will be added,
but the CipherProcessor will be updated with the current unlocked state.


== update_tile_properties ==
=== UpdateTilePropertiesAction ===
Update tile properties by modifying movement settings or accessibility.
Update tile properties by modifying movement settings or accessibility.


'''Usage'''
<code>
update_tile_properties <label>[,moverate]
</code>
'''Parameters'''
'''Parameters'''
* <code>label</code>: The name of the property to update (e.g., surfable, walkable).
* <code>label</code>: The name of the property to update (e.g., surfable, walkable).
* <code>moverate</code>: The value of the movement rate (e.g., 1 for normal movement, 0 for inaccessible).
* <code>moverate</code>: The value of the movement rate (e.g., 1 for normal movement,
0 for inaccessible).
 
* <code>Example</code>:
"update_tile_properties surfable,0.5" sets the surfable property to 0.5
for relevant tiles.
 
=== UpdateTimeAction ===
Update time variables.
 
'''Usage'''
<code>
 
update_time player
 
</code>
'''Parameters'''
* <code>file</code>: File to load.
 
* <code>eg</code>: "update_time player"


'''Examples'''
=== VariableMathAction ===
* <code>update_tile_properties surfable,0.5</code>
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``.
 
'''Usage'''
<code>


== variable_math ==
variable_math <var1>,<operation>,<var2>,<result>
Performs a mathematical operation on the key in the player.game_variables dictionary.
variable_math <var1>,<operation>,<var2>


</code>
'''Parameters'''
'''Parameters'''
* <code>variable_name</code>
* <code>var1</code>: First operand.
* <code>operation</code>: +, -, * or /
* <code>operation</code>: Operator symbol.
* <code>value</code>
* <code>var2</code>: Second operand.
* <code>result</code>: Variable where to store the result. If missing, it will be
``var1``.


'''Examples'''
=== WaitAction ===
* <code>variable_math badge_count,+,1</code>
Block the event chain for a given duration.
 
'''Usage'''
<code>


== wait ==
wait <seconds>
Pauses execution of all events for the given amount of time in seconds.


</code>
'''Parameters'''
'''Parameters'''
* <code>seconds</code>: The amount of time in seconds to wait for.
* <code>seconds</code>: Duration in seconds for the event engine to wait.
The wait is measured using accumulated delta time (dt)
from the game loop, not wall clock time.
 
=== WildEncounterAction ===
Start a encounter with a single wild monster.


'''Examples'''
'''Usage'''
* <code>wait 2.0</code> 
<code>
* <code>wait 5.2</code>


== wild_encounter ==
wild_encounter <monster_slug>,<monster_level>[,exp_mod]
Start an encounter with a single wild monster.
[,mon_mod][,env][,rgb][,held_item]


</code>
'''Parameters'''
'''Parameters'''
* <code>monster_slug</code>: Monster slug.
* <code>monster_slug</code>: Monster slug.
* <code>monster_level</code>: Level of monster.
* <code>monster_level</code>: Level of monster.
* <code>exp_mod</code>: Experience modifier. (optional)
* <code>exp_mod</code>: Experience modifier.
* <code>mon_mod</code>: Money modifier. (optional)
* <code>mon_mod</code>: Money modifier.
* <code>env</code>: Environment (grass default) -> [[Battle Terrain]] (optional)
* <code>env</code>: Environment (grass default)
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255) (optional)
* <code>rgb</code>: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)
* <code>held_item</code>: item held by the monster (optional)
* <code>held_item</code>: item held by the monster


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


'''Examples'''
* <code>Note</code>:
* <code>wild_encounter rockitten,5</code>
If the trainer's party is already full then the monster will be
* <code>wild_encounter rockitten,5,2,2,desert</code>
deposited into the default storage box automatically.
 
'''Usage'''
<code>


== withdraw_monster ==
withdraw_monster <variable>,<character>
Pull a monster from the given trainer's storage and puts it in their party.


</code>
'''Parameters'''
'''Parameters'''
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>variable</code>: Name of the variable where to store the monster id.
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple"). The one who is going to receive the monster.
* <code>character</code>: Either "player" or npc slug name (e.g. "npc_maple").
           
the one who is going to receive the monster
'''Examples'''
* <code>get_player_monster name_variable</code>
then
* <code>withdraw_monster name_variable</code>
or
* <code>withdraw_monster name_variable,npc_maple</code>

Latest revision as of 15:51, 2 February 2026

Actions[edit | edit source]

AccessPCAction[edit | edit source]

Change to PCState.

This action transitions to the PCState, typically used for viewing player character details or an NPC as if it were a PC.

Usage

access_pc <character_slug>

Parameters

  • character_slug: The slug of the character (NPC) to view in PCState.

AddCollisionAction[edit | edit source]

Handles the addition of a collision zone associated with a specific label. Optionally, with coordinates provided, it can block a specific tile within the map.

Usage

add_collision <label>[,x][,y]

Parameters

  • label: The name or identifier of the obstacle.
  • x: (Optional) X-coordinate of the specific tile to block.
  • y: (Optional) Y-coordinate of the specific tile to block.

AddComboAction[edit | edit source]

Registers one or more combos from a YAML string.

Usage

add_combo <yaml_data>

Parameters

  • yaml_file: Name of the YAML file (without extension) located in the mods folder.

AddContactsAction[edit | edit source]

Add contact to the app. npc_slug must have the msgid inside the PO.

Usage

add_contacts <character>,<npc_slug>[,relation][,strength], [,steps][,decay_rate][,decay_threshold]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • npc_slug: slug name (e.g. "npc_maple").
  • relation: type of relation
  • strength: amount of strength (higher, better), default 50, capped 100
  • steps: amount of steps, default character steps
  • decay_rate: decay rate of the relationship, default 0.01, capped 1.0
  • decay_threshold: threshold of steps after which the decay triggers,

default 500

AddHeldItemAction[edit | edit source]

Adds a held item to a specific monster.

Usage

add_held_item <variable>,<item>

Parameters

  • variable: Name of the variable where to store the monster id.
  • item: Slug of the item (e.g. "potion").

AddItemAction[edit | edit source]

Add an item to the specified trainer's inventory.

Usage

add_item <item_slug>[,quantity][,npc_slug]

Parameters

  • item_slug: Item name to look up in the item database.
  • quantity: Quantity of the item to add or to reduce. By default it is 1.
  • npc_slug: Slug of the trainer that will receive the item. It

defaults to the current player.

AddMonsterAction[edit | edit source]

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

Usage

add_monster <mon_slug>,<mon_level>[,npc_slug][,exp_mod][,money_mod]

Parameters

  • mon_slug: Monster slug to look up in the monster database or name variable

where it's stored the mon_slug

  • mon_level: Level of the added monster.
  • npc_slug: Slug of the trainer that will receive the monster. It

defaults to the current player.

  • exp_mod: Experience modifier
  • money_mod: Money modifier

AddStepTrackerAction[edit | edit source]

Adds a step tracker to a specific character.

Usage

add_step_tracker <character>,<tracker_id>,<countdown>[,<milestones> [,<auto_reset>[,<initial_countdown>]]]

Parameters

  • character: Either "player" or an NPC slug name (e.g., "npc_maple").
  • tracker_id: Unique name for identifying the step tracker.
  • countdown: Number of steps before the tracker reaches zero.
  • milestones (optional): Step milestones, separated by : (e.g., "500:250:100").
  • auto_reset (optional): "true" or "false" to enable or disable automatic reset.

Defaults to false.

  • initial_countdown (optional): Full cycle length. Defaults to countdown value.

AddTechAction[edit | edit source]

Adds a tech to a specific monster.

Usage

add_tech <variable>,<technique>[,power][,potency][,accuracy]

Parameters

  • variable: Name of the variable where the monster UUID is stored.
  • technique: Slug of the technique to add (e.g. "bullet").
  • power: Optional float (0.0-3.0). Overrides default power.
  • potency: Optional float (0.0-1.0). Overrides default potency.
  • accuracy: Optional float (0.0-1.0). Overrides default accuracy.

Examples

  • "add_tech monster_id,flamethrower"
  • "add_tech monster_id,flamethrower,2.5,0.8,0.95"

AddTrackerAction[edit | edit source]

Add tracker.

Usage

add_tracker <character>,<location>[,visited]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • location: location name (e.g. "paper_town").
  • visited: Optional string flag indicating if the location was visited.

Accepts "true", "1", "yes" for True (case-insensitive). Defaults to True if omitted.

AdjustBillPenaltyAction[edit | edit source]

Applies a penalty to a bill for a character — either interest or late fee.

Usage

adjust_bill_penalty <character_slug>,<bill_slug>,<method>

Parameters

  • character_slug: Slug of the character (e.g. "player", "npc_maple").
  • bill_slug: Slug of the bill to modify.
  • method: Either "interest" or "fee".

Examples

  • adjust_bill_penalty player,electric_bill,interest
  • adjust_bill_penalty npc_maple,rent,fee

AFKThresholdAction[edit | edit source]

Add, modify, or remove AFK thresholds.

Usage

afk_threshold <action> <level> [duration]

Parameters

  • action: One of "add", "modify", "remove"
  • level: The threshold name (string)
  • duration: Required for "add" and "modify" (float, seconds)

BoundaryMoveAction[edit | edit source]

Moves the current active boundary by the given delta values.

Usage

boundary_move <boundary_name>[,dx:dy]

Parameters

  • boundary_name: Required. The name to assign to the boundary
  • dx: The change in the x-coordinate.
  • dy: The change in the y-coordinate.

BoundaryResizeAction[edit | edit source]

Resizes the current active boundary.

Usage

boundary_resize <boundary_name>[,values]

Parameters

  • boundary_name: Required. The name to assign to the boundary

(e.g., "safe_zone", "event").

  • values: A colon-separated string of integers:
  • For rectangle: dx:dy
  • For circle: delta

BoundarySetAction[edit | edit source]

Sets or replaces the current boundary with a new one, or resets to default if no parameters are given.

Usage

boundary_set <boundary_name>[,shape][,values]

Parameters

  • boundary_name: Required. The name to assign to the boundary

(e.g., "safe_zone", "event").

  • shape: Optional. Either "rectangle" or "circle".
  • values: Optional. A colon-separated string of integers:
  • For "rectangle": x0:x1:y0:y1
  • For "circle": cx:cy:radius

BreedingAction[edit | edit source]

Select a monster in the player party filtered by gender and store its id in a variables (breeding_father or breeding_mother)

Usage

breeding <gender>

Parameters

  • gender: Gender (male or female).

CallEventAction[edit | edit source]

Execute the specified event's actions by name.

Usage

call_event <event_name>

Parameters

  • event_name: The name of the event whose actions will be executed.

CameraManageAction[edit | edit source]

Adds, removes, or switches/follows a camera in the camera manager.

Usage

camera_manage add [name] [npc_slug] camera_manage remove [name] camera_manage follow [name] [npc_slug]

Parameters

  • action: "add", "remove", or "follow"
  • camera_name: The identifier for the camera.
  • npc_slug: Optional slug of the NPC/entity to follow (used for add/follow).

CameraModeAction[edit | edit source]

  • Change camera mode: freeroaming or fixed.

Usage

camera_mode <mode>

Parameters

  • mode: The mode of the camera: 'free_roaming' or 'fixed'.

CameraMoveAction[edit | edit source]

Smoothly move the camera to a specific coordinate or reset it to its original position.

Usage

camera_move

Parameters

  • time: the duration (in seconds) required for the camera to transition to the target position.
  • x,y: the coordinates where the camera needs to be centered.

CameraPositionAction[edit | edit source]

Move the camera on a coordinate.

Usage

camera_position <x>,<y>

Parameters

  • x,y: the coordinates where the camera needs to be centered.

CameraShakeAction[edit | edit source]

Shake the camera with a precise intensity and duration.

Usage

camera_shake <intensity>,<duration>

Parameters

  • intensity: The magnitude of the shake effect. A higher value results

in a more pronounced shake, while a lower value produces a subtler effect (min 0.0, max 3.0).

  • duration: The length of time (in seconds) that the shake effect

should last. The method calculates the number of frames to shake based on an assumed frame rate.

ChangeBgAction[edit | edit source]

Handles the background change within the session, allowing users to apply a new background color or image dynamically.

Usage

change_bg <background>[,image][,category]

Parameters

  • background: The background identifier, which can be:
  • A file name located in `gfx/ui/background/`
  • An RGB color formatted as `R:G:B` (e.g., `255:0:0`)
  • image: An optional image identifier, which can be:
  • An item slug (stored in `gfx/items`)
  • A direct file path
  • category: The category of the image (e.g., item or image.

If omitted, defaults to "background".

  • Notes:
  • Background images must be in `gfx/ui/background/`.
  • Background dimensions must be 256x144 pixels.

ChangeBgNpcAction[edit | edit source]

Displays an NPC sprite over a background image, using the NPC's base sprite located in ``gfx/sprites/player/<slug>.png``.

Usage

change_bg_char <background>,<npc_slug>

Parameters

  • background:

The background identifier, which must be the name of a file located in ``gfx/ui/background/`` (without the ``.png`` extension). The background image must match the native resolution of the game (256x144 pixels).

  • npc_slug:

The slug of the NPC to display. A matching sprite file must

  • exist at:

``gfx/sprites/player/<npc_slug>.png``

The sprite will be loaded, scaled, and rendered on top of the background.

  • Notes:
  • Background images must be located in ``gfx/ui/background/``.
  • Background dimensions must be exactly 256x144 pixels.
  • NPC sprites are loaded directly from their corresponding PNG

file in ``gfx/sprites/player/``.

  • This action always pushes the ``NpcImageState``, which displays

the background and overlays the NPC sprite.

ChangeBgMonsterAction[edit | edit source]

Displays a monster sprite over a background image, using the monster's front sprite extracted from its sprite sheet.

Usage

change_bg_monster <background>,<monster_slug>

Parameters

  • background: The background identifier, which must be the name of

a file located in `gfx/ui/background/` (without the `.png` extension). The background image must match the native resolution of the game (256x144 pixels).

  • monster_slug: The slug of the monster to display. The monster

must exist in the monster database. Its front sprite will be extracted from its sprite sheet and rendered on top of the background.

  • Notes:
  • Background images must be located in `gfx/ui/background/`.
  • Background dimensions must be exactly 256x144 pixels.
  • The monster sprite is taken from the monster's sprite sheet

using the `front_rect` defined in its model.

  • This action always pushes the `MonsterImageState`, which

displays the background and overlays the monster sprite.

ChangeFactionMembershipAction[edit | edit source]

Makes an NPC (or player) join or leave a specific faction.

Usage

change_faction_membership <character>,<faction_slug>,<status>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • faction_slug: The slug identifier of the faction whose membership will be changed.
  • status: Must be either "join" or "leave", indicating the membership action.

ChangeStateAction[edit | edit source]

Change to the specified state (generic).

This action handles state transitions that do not require specific additional parameters beyond the state name itself.

Usage

change_state <state_name>

Parameters

  • state_name: The state name to switch to.

ChangeTasteAction[edit | edit source]

Changes the specified taste (warm or cold) of a monster.

Usage

change_taste <variable>,<type_taste>,<new_taste>

Parameters

  • variable: Name of the game variable containing the monster's UUID.
  • type_taste: Either "warm" or "cold" to indicate which taste to change.
  • new_taste: Slug of the new taste to assign, or "random" to select a new one

at random (excluding "tasteless" and the current taste).

  • Notes:
  • When using "random", the new taste is chosen based on rarity_score weighting.
  • When specifying a taste slug, it must exist, match the selected type,

and must not be "tasteless".

  • If no valid taste is found during random selection, the taste remains unchanged

and a warning is logged.

CharFaceAction[edit | edit source]

Make the character face a certain direction.

Usage

char_face <character>,<direction>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • direction: Direction to face. It can be: "left", "right", "up", "down",

"player" or a character slug.

CharFacePlayerAction[edit | edit source]

Make an NPC face the player when they come within a specified distance.

Usage

char_face_player <npc_slug>,<trigger_dist>,<persistent>

Parameters

  • npc_slug: Slug of the NPC that will face the player.
  • trigger_dist: Maximum tile distance at which the NPC will begin

facing the player. Defaults to 3.

  • persistent: Whether the NPC should continue tracking the player

after the first trigger. Defaults to True.

CharLookAction[edit | edit source]

Make a character look around.

Usage

char_look <character>[,frequency][,directions]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • frequency: Frequency of movements. 0 to stop looking. If set to

a different value it will be clipped to the range [0.5, 5]. If not passed the default value is 1.

  • directions: the direction the character is going to look, by default

all

eg. char_look character

  • eg. char_look character,,right: left

CharMoveAction[edit | edit source]

Relative tile movement for characters.

It interprets movement instructions, updates character positions accordingly, and blocks execution until the destination is reached.

Usage

char_move <character>,<move>...

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • move: A sequence of movement instructions in the format:

"<direction> [amount_of_tiles]"

  • where:
  • direction: One of "up", "down", "left", "right".
  • amount_of_tiles (optional): Number of tiles to move (default is 1).
  • Multiple moves can be provided, e.g., "up 10, down 5, left 5".

CharPatrolAction[edit | edit source]

Enables a character to patrol a predefined route in a continuous loop.

Usage

char_patrol <character>,<move>...

  • Parameters:
  • character: Either "player" or character slug name (e.g. "npc_maple").
  • move: A sequence of movement instructions in the format:

"<direction> [amount_of_tiles]"

  • where:
  • direction: One of "up", "down", "left", "right".
  • amount_of_tiles (optional): Number of tiles to move (default is 1).
  • Multiple moves can be provided, e.g., "up 10, down 5, left 5".
  • Functionality:
  • Converts movement instructions into a looping patrol path.
  • NPC moves along the predefined path, restarting when completed.
  • Blocks execution if the NPC encounters an obstacle.
  • Automatically resumes patrol when movement is available.

CharPlagueAction[edit | edit source]

Set the entire party as infected or inoculated or healthy.

Usage

char_plague <plague_slug>,<condition>[,character]

Parameters

  • plague_slug: The slug of the plague to target.
  • condition: Infected, inoculated, or None (removes the plague from the

character, indicating a healthy state).

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • enforced_check: Optional string flag to enforce eligibility rules.

Accepts "true", "1", or "yes" (case-insensitive). Default is False (eligibility is bypassed).

CharPositionAction[edit | edit source]

Set the position of a character.

Usage char_position <character>,<tile_pos_x>,<tile_pos_y>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • tile_pos_x: X position to set the character to.
  • tile_pos_y: Y position to set the character to.

CharRunAction[edit | edit source]

Set the character movement speed to the global run speed.

Usage

char_run <character>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").

CharSpeedAction[edit | edit source]

Set the character movement speed to a custom value.

Usage

char_speed <character>,<speed>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • speed: Speed amount.

CharStopAction[edit | edit source]

Make the character stop moving.

Usage

char_stop <character>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").

CharTalkAction[edit | edit source]

Displays dialogue for a character based on context and location.

This action retrieves dialogue from the character's dialogue profile, optionally using a location-specific override. The dialogue field determines which type of line to display (e.g. greeting, pre_battle, farewell).

Usage

char_talk <character>,<field>[,location]

Parameters

  • character: Either "player" or the slug of an NPC (e.g. "npc_maple").
  • field: The dialogue type to display. Must be one of:
  • greeting
  • idle
  • farewell
  • pre_battle
  • post_battle_win
  • post_battle_lose
  • post_battle_draw
  • location: Optional map identifier (e.g. "map.tmx") used to override default dialogue.
  • Behavior:
  • If a location is provided and a location-based override exists, it will be used.
  • Otherwise, the default dialogue profile is used.
  • If the dialogue field contains multiple lines, one is selected randomly.
  • Dialogue text is formatted before display.
  • Example:

char_talk npc_maple,greeting,map_forest

CharWalkAction[edit | edit source]

Set the character movement speed to the global walk speed.

Usage

char_walk <character>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").

CharWanderAction[edit | edit source]

Make a character wander around the map.

Usage

char_wander <character>[,frequency][,t_bound][,b_bound]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • frequency: Frequency of movements. 0 to stop wandering. If set to

a different value it will be clipped to the range [0.5, 5]. If not passed the default value is 1.

  • t_bound: coordinates top_bound vertex (eg 5,7)
  • b_bound: coordinates bottom_bound vertex (eg 7,9)

eg. char_wander character,,5,7,7,9

ChoiceItemAction[edit | edit source]

Ask the player to make a choice among items.

Usage

choice_item <choices>,<variable>

Parameters

  • choices: List of possible choices
  • (item slugs eg: potion:tea),
  • separated by a colon ": ".
  • variable: Variable to store the result of the choice.

ChoiceMonsterAction[edit | edit source]

Ask the player to make a choice among monsters.

Usage

choice_monster <choices>,<variable>

Parameters

  • choices: List of possible choices
  • (monster slugs eg: rockitten:apeoro),
  • separated by a colon ": ".
  • variable: Variable to store the result of the choice.

ChoiceNpcAction[edit | edit source]

Ask the player to make a choice among NPCs.

Usage

choice_npc <choices>,<variable>

Parameters

  • choices: List of possible choices
  • (item slugs eg: maple:billie),
  • separated by a colon ": ".
  • variable: Variable to store the result of the choice.

CipherDialogAction[edit | edit source]

Displays a dialog window with text that may be ciphered based on the character's unlocked letters and the active CipherProcessor.

The dialog text is optionally translated, styled, and formatted based on script parameters. Any unlocked letters will remain visible, while the remaining content may be obfuscated depending on the cipher configuration.

Usage

cipher_dialog <text>[,avatar][,position][,style]

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.

  • position: Position of the dialog box. Can be 'top', 'bottom', 'center',

'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'. Default 'bottom'.

  • h_alignment: Alignment of text in the dialog box, it can be 'left', 'center'

or 'right'. Default 'left'.

  • v_alignment: Alignment of text in the dialog box, it can be 'bottom',

'center' or 'top'. Default 'top'.

  • style: a predefined style in db/dialogue/dialogue.json

ClearKennelAction[edit | edit source]

Clear a kennel.

It advisable to save the game and check twice.

Remember the main kennel is "Kennel"

Without destination (transfer) the monster will be deleted as well as the kennel.

Usage

clear_kennel <character>,<kennel>[,transfer]

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • kennel: The kennel to clear.
  • transfer: The kennel to transfer the monsters.

ClearTuxepediaAction[edit | edit source]

Clear the key and value in the Tuxepedia dictionary. If the monster_slug parameter is missing, this action will completely reset the Tuxepedia dictionary by removing all seen monsters.

If the monster_slug parameter is provided, this action will remove the specified monster from the Tuxepedia dictionary.

Usage

clear_tuxepedia <monster_slug>

Parameters

  • monster_slug: Monster slug name (e.g. "rockitten").

ClearVariableAction[edit | edit source]

Removes specified variables from the player's stored variables.

Usage

clear_variable <variable1>[,variable2]

Parameters

  • variable: One or more variables to be removed.

CopyVariableAction[edit | edit source]

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

Usage

copy_variable <var1>,<var2>

Parameters

  • var1: The variable to copy to.
  • var2: The variable to copy from.

CraftingStationAction[edit | edit source]

Change to the specified state.

Usage

crafting_station <character_slug>,<method>[,file_yaml]

Parameters

  • character_slug: The slug of the character (NPC).
  • method: Suggests how the recipe is executed, e.g., cooking, forging.
  • file_yaml: The YAML file (like `recipe.yaml`) that contains the recipe

definitions to load into the system (mods folder).

CreateKennelAction[edit | edit source]

Creates a new kennel with optional metadata.

It's advisable to create a msgid in the en_US PO file.

msgid "kennel_name" msgstr "Kennel Name"

Usage

  1. Create a visible kennel with default capacity

create_kennel player,my_kennel

  1. Create a hidden kennel with capacity 20

create_kennel player,my_kennel,true,20

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • kennel: Name of the kennel.
  • hidden: Optional flag ("true"/"false", "1"/"0", "yes"/"no") for

visibility.

  • max_capacity: Optional integer for maximum capacity (defaults to

MAX_KENNEL).

CreateNpcAction[edit | edit source]

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

Usage

create_npc <npc_slug>,<tile_pos_x>,<tile_pos_y>[,<behavior>]

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.
  • behavior: Behavior of the NPC (e.g. "wander"). Unused for now.

DojoMethodAction[edit | edit source]

Represents an event action for the monks in the Dojo (Spyder).

Usage

dojo_method <variable_name>,<option>

Parameters

  • variable_name:

The name of the variable where the monster ID will be stored.

  • option:
  • The action to perform. Can be either:
  • "technique": Learn any move the monster hasn't acquired from its base

moveset, without restrictions based on level or evolution stage.

  • "monster": Devolve the monster.

EvolutionAction[edit | edit source]

Checks, asks and evolves.

Usage

evolution <character>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters get experience.

  • evolution: Slug of the evolution.

FadeInAction[edit | edit source]

Fade in and block until the fade duration has completed.

Usage

fade_in [trans_time][,rgb]

Parameters

  • trans_time: Transition time in seconds - default 0.3
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
  • eg: "fade_in 3"
  • eg: "fade_in 3,255:0:0:50" (red)

FadeOutAction[edit | edit source]

Fade out and block until the fade duration has completed.

Usage

fade_out [trans_time][,rgb]

Parameters

  • trans_time: Transition time in seconds - default 0.3
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
  • eg: "fade_out 3"
  • eg: "fade_out 3,255:0:0:50" (red)

FadeoutMusicAction[edit | edit source]

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

Usage

fadeout_music [duration]

Parameters

  • duration: Number of milliseconds to fade out the music over.

FormatVariableAction[edit | edit source]

Format the value of a variable from the game (eg. float or int). By default the game variable is a dict[str, Any].

Usage

format_variable <variable>,<type_format>

Parameters

  • variable: The variable to format.
  • type_format: Kind of format (float or int).

eg. "format_variable name_variable,int"

GetPartyMonsterAction[edit | edit source]

Saves all the iids (party) in variables.

Usage

get_party_monster [npc_slug]

Parameters

  • npc_slug: npc slug name (e.g. "npc_maple") - default "player"

GetPendingMovesAction[edit | edit source]

Display a menu of pending techniques for monsters listed in event_data["check_max_tech"], and store the selected technique ID in a game variable.

Usage

get_pending_moves <variable_name>

Parameters

  • variable_name: Name of the game variable to store the selected

technique ID.

  • Example:
  • "get_pending_moves chosen_move"

GetPlayerMonsterAction[edit | edit source]

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

  • It allows filtering: slug, gender, evolution_stage, element, shape,

taste_warm, taste_cold, level, weight, height, max_hp, current_hp, armour, dodge, melee, ranged and speed.

eg "get_player_monster name_variable,shape,serpent" eg "get_player_monster name_variable,shape,serpent"

  • For the definition: level, weight, height, max_hp, current_hp, armour, dodge,

melee, ranged and speed (all numeric values) is necessary to use a numeric comparison operator. Accepted values are "less_than", "less_or_equal", "greater_than", "greater_or_equal", "equals" and "not_equals".

eg "get_player_monster name_variable,speed,more_than,50" eg "get_player_monster name_variable,level,less_than,15"

  • Note:

let's say a player doesn't has no options, then the variable

  • will result as: name_variable:no_option

let's say a player has options, but clicks return, then the

  • variable will result as: name_variable:no_choice

Usage

get_player_monster <variable_name>,<filter_name>,<value_name>[,extra]

Parameters

  • variable_name: Name of the variable where to store the monster id.

filter

  • filter_name: the name of the first filter
  • value_name: the actual value to filter
  • extra: used to filter more

GiveExperienceAction[edit | edit source]

Gives experience points to the monster.

Usage

give_experience <variable>,<exp>

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters get experience.

  • exp: Name of the variable where to store the experience points or

directly the number of points. Negative value will result in 0.

eg. "give_experience name_variable,steps_variable" eg. "give_experience name_variable,420"

InfoAction[edit | edit source]

Records monster's attribute values inside a game variable. It allows recording the monster's owner attribute values too.

Usage

info <variable>,<attribute>

Parameters

  • variable:

Name of the variable where to store the monster id.

  • attribute:

The attribute to check (level, speed, etc.)

Examples

  • "info name_variable,level"
  • -> if the monster is lv 4, then it'll create a variable called:
  • "info_level: 4"
  • "info name_variable,owner_steps"
  • -> if the owner walked 69 steps, then it'll create a variable called:
  • "info_owner_steps: 69"

InputLoadAction[edit | edit source]

Load a recording from a file into memory under a given name.

Usage

input_load <filepath> <name>

InputPlaybackAction[edit | edit source]

Start or stop playback of a named recording.

Usage

input_playback <action> <name>

InputRecordAction[edit | edit source]

Start or stop input recording, optionally naming the recording.

Usage

input_record <action> [name]

InputSaveAction[edit | edit source]

Save a named recording to a file.

Usage

input_save <filepath> [name]

InputVariableAction[edit | edit source]

Set a code and check if it's correct or not. The player's output will be by default lowercase.

Usage

input_variable <variable>,<question>[,answer][,escape]

Parameters

  • question:

The question the player needs to reply (e.g. "access_code").

  • Then you create the msgid "access_code" inside the PO file:

msgid "access_code" msgstr "Here the actual question?"

  • variable:

Name of the variable where to store the output.

  • escape:

Optional string flag ("true", "1", "yes" for True), defaults to False when omitted.

Examples

  • "input_variable access_code,response_question"
  • "input_variable access_code,response_question,escape"
  • -> "is variable_set response_question:whatswrittenbytheplayer"
  • -> "not variable_set response_question:whatswrittenbytheplayer"

LearnTechByMethodAction[edit | edit source]

Teaches a technique to a specific monster using a specific learning method.

Usage

learn_tech_by_method <monster_var>,<technique>,<method>

  • Parameters:
  • monster_var: Game variable name containing the monster UUID.
  • technique: Slug of the technique to learn.
  • method: Learning method enum name (e.g. "EVENT", "TM")

Examples

  • "learn_tech_by_method monster_id,flamethrower,EVENT"
  • "learn_tech_by_method monster_id,fireblast,TM"

LoadGameAction[edit | edit source]

Loads the game.

If the index parameter is absent, then it'll load slot4.save

index = 0 > slot 1 index = 1 > slot 2 index = 2 > slot 3

Usage

load_game [index]

Parameters

  • index: Selected index.
  • eg: "load_game" (slot4.save)
  • eg: "load_game 1"

LoadWeatherAction[edit | edit source]

Loads a YAML file containing weather previsions using the Pydantic schema and registers it with the WorldWeatherManager.

Usage

load_weather <path_to_yaml_file>

Parameters

  • model_file: Path to the YAML file (e.g., "weather_previsions.yml").

LoadYamlAction[edit | edit source]

Loads the yaml file. It must be in the maps folder.

Usage

load_yaml file

Parameters

  • file: File to load.
  • eg: "load_yaml file_yaml"

LockControlsAction[edit | edit source]

Lock player controls

Usage

lock_controls

ManageMapCacheAction[edit | edit source]

Adds or removes a map from the cache.

Usage

manage_map_cache <action>,<map_name>

Parameters

  • action: "add" or "remove"
  • map_name: Name of the map (map.tmx)

MenuAction[edit | edit source]

Toggle visibility of one or more world menu entries, or apply a preset.

Usage

menu <flag>[,menu_1:menu_2:...] # toggles specific menus menu <preset> # applies preset config

  • Parameters:
  • flag: "enable" or "disable", applied to specified menus (or all)
  • preset: one of defined presets ("minimal", etc.)

Examples

  • menu reset > clears all menu flags
  • menu enable > enables all menus
  • menu disable,menu_bag: menu_player > disables specified menus
  • menu enable,all > enables all menus
  • menu minimal > applies "minimal" preset

ModifyBillAction[edit | edit source]

Add or remove an amount of money from a bill (slug).

Usage

modify_bill <slug>,<bill_slug>,[amount][,variable]

Parameters

  • slug: Either "player" or character slug name (e.g. "npc_maple").
  • bill_slug: Slug of the bill.
  • amount: Amount of money to add/remove (-/+)
  • variable: Name of the variable where to store the amount.

eg. "modify_bill player,bill_slug,-50" eg. "modify_bill player,bill_slug,,name_variable"

ModifyCharAttributeAction[edit | edit source]

Modify the given attribute of the character by modifier.

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

Usage

modify_char_attribute <character>,<attribute>,<value>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • attribute: Name of the attribute to modify.
  • value: Value of the attribute modifier.

ModifyContactsAction[edit | edit source]

Modify contact relationship.

Usage

modify_contacts <character>,<npc_slug>,<attribute>,<value>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • npc_slug: slug name (e.g. "npc_maple").
  • attribute: it can be 'strength', 'decay_rate' or 'decay_threshold'
  • value: the new value

ModifyFactionReputationAction[edit | edit source]

Modifies an NPC's (or player's) reputation with a specific faction.

Usage

modify_faction_reputation <character>,<faction_slug>,<amount>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • faction_slug: The slug identifier of the faction to modify reputation for.
  • amount: A string representation of an integer. Positive or negative values

(e.g. "25", "-50") that change the reputation score accordingly.

ModifyMoneyAction[edit | edit source]

Add or remove an amount of money for a wallet (slug).

Usage

modify_money <slug>,[amount][,variable]

Parameters

  • slug: Either "player" or character slug name (e.g. "npc_maple").
  • amount: Amount of money to add/remove (-/+)
  • variable: Name of the variable where to store the amount.

eg. "modify_money player,-50" eg. "modify_money player,,name_variable"

ModifyMonsterBondAction[edit | edit source]

Change the bond of a monster in the current player's party.

Usage

modify_monster_bond [variable][,amount]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters are touched.

  • amount: An int or float value, if no amount, then default 1 (int).
  • lower_bound: Lower bound of range to return an integer between (inclusive)
  • upper_bound: Upper bound of range to return an integer between (inclusive)

eg. "modify_monster_bond" eg. "modify_monster_bond name_variable,25" eg. "modify_monster_bond name_variable,-0.5" eg. "modify_monster_bond name_variable,,1,5" (random between 1 and 5) eg. "modify_monster_bond name_variable,,-5,-1" (random between -5 and -1)

ModifyMonsterHealthAction[edit | edit source]

Modify the hp of a monster in the current player's party.

Usage

modify_monster_health [variable][,health]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable 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. A int value, which is the number of HP to be restored to. If no health is specified, the hp is maxed out.

ModifyMonsterStatsAction[edit | edit source]

Change the stats of a monster in the current player's party.

Usage

modify_monster_stats [variable][,stat][,amount]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters are touched.

  • stat: A stat among armour, dodge, hp, melee, speed and ranged. If no

stat, then all the stats.

  • amount: A/an float/int value, if no amount, then default 1 (+).
  • lower_bound: Lower bound of range to return an integer between (inclusive)
  • upper_bound: Upper bound of range to return an integer between (inclusive)

eg. "modify_monster_stats" eg. "modify_monster_stats ,,0.25" eg. "modify_monster_stats name_variable,speed,25" eg. "modify_monster_stats name_variable,dodge,-12" eg. "modify_monster_stats name_variable,dodge,-0.4" eg. "modify_monster_stats name_variable,,,1,5" (random between 1 and 5)

OpenJournalAction[edit | edit source]

Change to JournalInfoState.

This action transitions to the JournalInfoState, displaying information about a specific monster in the player's journal.

Usage

open_journal <monster_slug>

Parameters

  • monster_slug: The slug of the monster to display in the journal.

OpenShopAction[edit | edit source]

Opens a shop interface between the player and a target NPC.

Usage open_shop <npc_slug>,<menu>[,model]

  • Parameters:
  • npc_slug: Either "player" or the NPC slug identifier (e.g. "npc_maple").
  • menu: Type of shop interaction to open. Must be one of:
  • "buy_item"
  • "sell_item"
  • "both_item"
  • "buy_monster"
  • "sell_monster"
  • "both_monster"
  • "train_monster"
  • "heal_monster"
  • model (optional): A configuration profile name used to load custom shop behavior.
  • Notes:
  • The target NPC must have an economy assigned.
  • If menu is "both_*", a choice dialog is shown for selection.

OverwriteTechAction[edit | edit source]

Replaces a known technique with another for a specific monster.

This action is typically used when a monster chooses to forget a move and learn a new one.

Usage

overwrite_tech <removed>,<added>

Parameters

  • removed: Name of the game variable that stores the UUID of the

technique to be replaced.

  • added: Slug of the technique to be added (e.g., "peck", "fireball")
  • Example:

"overwrite_tech name_variable,peck"

ParkExperienceAction[edit | edit source]

Shows the results of the Park session.

Usage

park_experience

Parameters

  • option: Either 'start' or 'stop'

PathfindAction[edit | edit source]

Pathfind the player / npc to the given location.

This action blocks until the destination is reached.

Usage

pathfind <npc_slug>

Parameters

  • npc_slug: Either "player" or npc slug name (e.g. "npc_maple").

PathfindToCharAction[edit | edit source]

Handles pathfinding movement where one entity navigates toward another with configurable direction and distance.

Usage

pathfind_to_char <target_entity>,<moving_entity>, [direction],[distance]

Parameters

  • target_entity: The target entity being approached

(e.g. "character_maple").

  • moving_entity: The entity that will move toward the target

(e.g. "character_jimmy").

  • direction: Determines approach direction

(up, down, left, or right).

  • distance: Number of tiles to maintain from the player

(e.g. 2,3,4).

PauseMusicAction[edit | edit source]

Pause the current music playback.

Usage

pause_music

PlayMapAnimationAction[edit | edit source]

Trigger a map animation at a specified position based on the character's coordinates within the world map

Usage

play_map_animation <animation_name>,<duration>,<loop>,<character>

Parameters

  • animation_name: The name of the animation stored in the

resources/animations/tileset directory. For example, an animation named "grass" will load frames named "grass_xx.png".

  • frame_duration: Duration (in seconds) for each frame of the animation.
  • loop_mode: Indicates whether the animation should loop. Options: "loop"

or "noloop".

  • character: Either "player" or character slug name (e.g. "npc_maple").

PlayMusicAction[edit | edit source]

Play a music file from "resources/music/".

Usage

play_music <filename>[,volume][,loop][,fade_ms]

Parameters

  • filename: The name of the music file to play.
  • volume: A value between 0.0 and 1.0 that adjusts the music

volume.

  • loop: The number of times to loop the music. Default is to loop

forever.

  • fade_ms: The time in milliseconds to fade in the music before

reaching maximum volume.

  • Note:

The volume will be based on the main value in the options menu. e.g. if you set volume = 0.5 here, but the player has 0.5 among its options, then it'll result into 0.25 (0.5*0.5)

PlaySoundAction[edit | edit source]

Plays a short sound effect from the "resources/sounds/" folder.

Usage

play_sound <filename>[,volume]

Parameters

  • filename: The sound file to load (must exist in the sounds database).
  • volume: A float between 0.0 and 1.0 representing the relative volume level.

This value is multiplied by the user's configured sound volume.

  • Example:

If volume=0.5 and the player's sound setting is also 0.5, the resulting effective playback volume will be 0.25.

  • Note:

This is intended for short non-looping sound effects (e.g., cues, UI feedback), not for ambient or background music.

PlayTileAnimationAction[edit | edit source]

Trigger a map animation at a specified tile position on the world map.

Usage

play_tile_animation <tile_pos_x>,<tile_pos_y>,<animation_name>,<duration>,<loop>

Parameters

  • tile_pos_x, tile_pos_y: Coordinates (x, y) specifying the tile position

where the animation will be drawn on the map.

  • animation_name: The name of the animation stored in the

resources/animations/tileset directory. For example, an animation named "grass" will load frames named "grass_xx.png".

  • frame_duration: Duration (in seconds) for each frame of the animation.
  • loop_mode: Indicates whether the animation should loop. Options: "loop"

or "noloop".

PrintAction[edit | edit source]

Print the current value of one or more game variables to the console.

If no variable is specified, print out values of all game variables.

Usage

print print <variables>

Script parameters: variables: Optional, prints out the value of this/these variable/s, multiple variables separated by ':'.

QuarantineAction[edit | edit source]

Quarantine or release monsters infected with a specific plague.

  • Usage:

quarantine <character>,<plague_slug>,<value>[,amount]

  • Parameters:
  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • plague_slug: The slug of the plague to target.
  • action_type: "in" to quarantine infected monsters, "out" to release them.
  • amount: (Optional, only for "out") The number of monsters to release

randomly.

  • Example: "quarantine out,5" (Release 5 infected monsters randomly)

QuitAction[edit | edit source]

Completely quit the game.

Usage

quit

QuitWorldAction[edit | edit source]

Exit the current world without quitting the game.

Usage

quit_world

RandomBattleAction[edit | edit source]

Starts a random battle with a randomly chosen NPC and a party of randomly generated monsters within a specified level range.

Usage

random_battle nr_txmns,min_level,max_level

Parameters

  • nr_txmns: The number of Tuxemon in the opponent's party (1 to 6).
  • min_level: The minimum level for the opponent's monsters.
  • max_level: The maximum level for the opponent's monsters.

RandomEncounterAction[edit | edit source]

Randomly start an 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".

Usage

random_encounter <encounter_slug>[,total_prob][,rgb]

Parameters

  • encounter_slug: Slug of the encounter list.
  • total_prob: Total sum of the probabilities.
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)

RandomHordeAction[edit | edit source]

Randomly start an horde.

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.

Usage

random_horde <encounter_slug>[,rgb]

Parameters

  • encounter_slug: Slug of the encounter list.
  • total_prob: Optional float between 0 and 100 representing the chance

of triggering a horde encounter.

  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)

RandomIntegerAction[edit | edit source]

Randomly chooses an integer between two numbers (inclusive) and sets a key in the player's game_variables dictionary to this value.

For example, 'random_integer xyz,1,6' will set the value of the game variable 'xyz' to be a random integer from 1, 2, 3, 4, 5, or 6.

Usage

random_integer <variable>,<lower_bound>,<upper_bound>

Parameters

  • variable: Name of the variable to set.
  • lower_bound: The inclusive lower bound of the integer range.
  • upper_bound: The inclusive upper bound of the integer range.

RandomItemAction[edit | edit source]

Picks a random item from a list and adds it to the trainer's inventory.

Usage

random_item <item_slugs>[,quantity][,trainer_slug]

Parameters

  • item_slugs: A colon-separated string of item names to choose from.
  • Example: 'potion:super-potion:hyper-potion'.
  • quantity: The number of the item to add. Defaults to 1.
  • trainer_slug: The slug of the trainer to receive the item.

Defaults to the current player.

RandomMonsterAction[edit | edit source]

Adds a random monster to the specified trainer's party, if there is room.

Usage

random_monster <level>[,npc_slug][,exp][,mon][,shape][,evo]

Parameters

  • level: The level of the added monster.
  • npc_slug: The slug of the trainer to receive the monster

Defaults to the current player.

  • exp: A modifier for the monster's experience.
  • mon: A modifier for the monster's money yield.
  • shape: The monster's shape (e.g., 'varmint', 'brute').
  • evo: The monster's evolution stage (e.g., 'basic', 'stage1').

RemoveCollisionAction[edit | edit source]

Removes a collision zone associated with a specific label from the world map.

Usage

remove_collision <label>

Parameters

  • label: The name or identifier of the obstacle to be removed.

RemoveComboAction[edit | edit source]

Removes a registered combo sequence from the ComboDetector.

Usage

remove_combo <combo_name>[,buttons]

Parameters

  • combo_name: Required. A name or ID for the combo (used for logging).
  • buttons: Required. A colon-separated list of button names (e.g. LEFT:RIGHT:A).

RemoveContactsAction[edit | edit source]

Remove contact from the app.

Usage

remove_contacts <character>,<slug>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • slug: slug name (e.g. "npc_maple").

RemoveFlairAction[edit | edit source]

Remove a flair from a monster.

Usage

remove_flair <variable>,<category>

Parameters

  • variable: The name of the variable that holds the monster's UUID.
  • category: The category of the flair to remove. If omitted, all flairs will be removed.

RemoveHeldItemAction[edit | edit source]

Removes a held item from a specific monster.

Usage

remove_held_item <variable>

Parameters

  • variable: Name of the variable where to store the monster id.

RemoveMonsterAction[edit | edit source]

Remove a monster from the party if the monster is there.

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

Usage

remove_monster <variable>

Parameters

  • variable: Name of the variable where to store the monster id.

RemoveNpcAction[edit | edit source]

Remove an NPC object from the list of NPCs.

Usage

remove_npc <npc_slug>

Parameters

  • npc_slug: Npc slug name (e.g. "npc_maple").

RemoveStateAction[edit | edit source]

Remove the specified state or the last active one.

This action allows the removal of a specific state from the client's active state list. If no state name is provided, it removes the current state, except for certain protected states (e.g., "WorldState" and "BackgroundState").

Usage

remove_state [state_name]

Parameters

  • state_name: The name of the state to remove (e.g., "PCState").

If not provided, the last active state will be removed, unless it's a protected state.

RemoveStepTrackerAction[edit | edit source]

Removes a step tracker from a specific character.

Usage

remove_step_tracker <character>,<tracker_id>

Parameters

  • character: Either "player" or an NPC slug name (e.g., "npc_maple").
  • tracker_id: Unique name for identifying the step tracker.

RemoveTechAction[edit | edit source]

Remove a specific technique from a specific monster in the party.

Usage

remove_tech <tech_id>[,<force_remove>]

Parameters

  • tech_id: Name of the variable where the technique ID is stored.
  • force_remove: Optional string flag to override forget rules.

Accepts "true", "1", or "yes" (case-insensitive).

Examples

  • "remove_tech name_variable"
  • "remove_tech name_variable,true"
  • "remove_tech name_variable,1"

RemoveTrackerAction[edit | edit source]

Remove tracker.

Usage

remove_tracker <character>,<location>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • location: location name (e.g. "paper_town").

RenameMonsterAction[edit | edit source]

Open the text input screen to rename the monster.

Usage

rename_monster <variable>

Parameters

  • variable: Name of the variable where to store the monster id.

RenamePlayerAction[edit | edit source]

Open the text input screen to rename the character.

Usage

rename_player <character> [random]

Parameters

  • character: Either "player" or an NPC slug (e.g. "npc_maple")
  • random: Adding "random" makes appear the dontcare button in the input.

ReplacePartyFromYamlAction[edit | edit source]

Replaces a character's party with a predefined set of monsters from a YAML file.

This action loads a named party configuration from a YAML file and assigns it to the specified character (either the player or an NPC). Each monster entry in the YAML can define attributes like slug, level, and weight for random selection.

Usage

replace_party_from_yaml <character>,<yaml_file>,<set_name>

Parameters

  • character: Either "player" or an NPC slug (e.g. "npc_maple").
  • yaml_file: Name of the YAML file (without extension) located in the mods folder.
  • set_name: The key of the party to use within the YAML file.

Examples

  • "replace_party_from_yaml npc_maple,parties,starter_set"

ReplaceTechsFromYamlAction[edit | edit source]

Replaces a monster's moveset using a predefined set from a YAML file.

Usage

replace_techs_from_yaml <variable>,<yaml_file>,<set_name>

Parameters

  • variable: Name of the variable where the monster UUID is stored.
  • yaml_file: Path to the YAML file containing movesets.
  • set_name: The key of the moveset to use within the YAML file.

Examples

  • "replace_techs_from_yaml monster_id,movesets,starter_set"

RumbleAction[edit | edit source]

Rumble available controllers with rumble support.

Usage

rumble <duration>,<power>[,period][,delay][,attack_length] [,attack_level][,fade_length][,fade_level][,direction]

Parameters

  • duration: Time in seconds to rumble for.
  • power: Percentage of power to rumble (0 to 100).
  • period: Time period between vibrations in milliseconds.

Default 25.

  • delay: Time in seconds before the rumble starts.

Default 0.

  • attack_length: Time in milliseconds for the rumble to ramp up.

Default 256.

  • attack_level: Initial intensity level during ramp-up.

Default 0.

  • fade_length: Time in milliseconds for the rumble to fade out.

Default 256.

  • fade_level: Final intensity level during ramp-down.

Default 0.

  • direction: Direction of the rumble effect, for spatial control.

Default 16384.

RumblePatternAction[edit | edit source]

Play a named rumble pattern on available controllers.

Usage

rumble_pattern <pattern_name>[,target]

Parameters

  • pattern_name: Name of the pattern ('pulse', 'heartbeat', 'explosion').
  • target: Optional device index (-1 for all). Default -1.

SaveGameAction[edit | edit source]

Saves the game.

If the index parameter is absent, then it'll create slot4.save

index = 0 > slot 1 index = 1 > slot 2 index = 2 > slot 3

Usage

save_game [index]

Parameters

  • index: Selected index.
  • eg: "save_game" (slot4.save)
  • eg: "save_game 1"

SaveTimestampAction[edit | edit source]

Saves the current Unix timestamp (in seconds) into a game variable.

Usage

save_timestamp <variable>

Parameters

  • variable: The name of the game variable to store the timestamp in.

ScreenTransitionAction[edit | edit source]

Initiate a screen transition that blocks until both fade out and fade in are complete.

Usage

screen_transition [trans_time][,rgb]

Parameters

  • trans_time: Transition time in seconds - default 0.3
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
  • eg: "screen_transition 3"
  • eg: "screen_transition 3,255:0:0:50" (red)

SetBattleAction[edit | edit source]

Appends a new battle to the player's battle history.

Usage

set_battle <fighter>,<result>,<opponent>

Parameters

  • fighter_slug: The slug of the battle participant (e.g., "player").
  • outcome: The desired battle outcome ("won", "lost", or "draw").
  • opponent_slug: The slug of the opponent (e.g., "npc_maple").
  • Example:

`set_battle player,won,npc_maple` Add the 'player' has won against 'npc_maple' to the history.

SetBillAction[edit | edit source]

Initializes or updates a bill for a character, including its amount, interest rate, late fee and share rate.

Usage

set_bill <character>,<bill_slug>[,amount][,interest_rate][,late_fee][,share_rate]

Parameters

  • character: "player" or the slug of an NPC (e.g. "npc_maple").
  • bill_slug: identifier for the bill (must be translated in en_US base.po).
  • amount: initial amount of the bill (optional, defaults to 0).
  • interest_rate: interest rate applied to the bill (optional, e.g. 0.1 for 10%).
  • late_fee: flat fee added to the bill when triggered (optional, eg. 10).
  • share_rate: percentage of battle earnings automatically applied to the bill

(optional, e.g. 0.2 for 20%).

Examples

  • set_bill player,bill_cathedral,100,0.1,50,0.5
  • set_bill npc_maple,bill_rent,,0.05,25,0.2
  • Notes:
  • Interest and late fee are stored but not automatically applied.
  • Use separate actions to trigger interest or fee accumulation.
  • Amount must be non-negative.

SetBubbleAction[edit | edit source]

Put a bubble above player sprite.

Usage

set_bubble <npc_slug>[,bubble]

Parameters

  • npc_slug: Either "player" or npc slug name (e.g. "npc_maple").
  • bubble: dots, drop, exclamation, heart, note, question, sleep,

angry, confused, fireworks

  • Example usage:

"set_bubble spyder_shopassistant" (remove bubble from NPC) "set_bubble spyder_shopassistant,note" (set bubble for NPC) "set_bubble player,note" (set bubble for player) "set_bubble player" (remove bubble from player)

SetCharAttributeAction[edit | edit source]

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

Usage

set_char_attribute <character>,<attribute>,<value>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • attribute: Name of the attribute.
  • value: Value of the attribute.

SetPlayerBirthdayAction[edit | edit source]

Open the date picker to set the player's birthday.

Usage

set_char_birthday <character> [random]

Parameters

  • character: Either "player" or an NPC slug (e.g. "npc_maple")
  • random: If provided, assigns a random birthday instead of

opening the date picker.

SetCipherAction[edit | edit source]

Toggles ciphering for dialogue by enabling or disabling the CipherProcessor.

Usage

set_cipher <option>,<cipher_map>

  • Parameters:
  • option:
  • "enable": Activates ciphering using the provided cipher map (if any).
  • "disable": Disables ciphering entirely.
  • cipher_map:

The filename (without extension) of a YAML file located in the mods folder.

  • If omitted during "enable", the default cipher map is used.
  • Ignored when option is "disable".

SetEconomyAction[edit | edit source]

Sets the economy (prices and initial stock of items/monsters) for a specific NPC.

This action orchestrates loading the economy data and then applying it to the target character's shop/inventory, including handling initial quantities and variable-based availability.

Usage

set_economy <npc_slug>,<economy_slug>

Parameters

  • npc_slug: Either "player" or npc slug name (e.g. "npc_maple").
  • economy_slug: Slug of an economy.

SetEnvironmentAction[edit | edit source]

Switch or unload the active battle environment.

Usage

set_environment [slug]

Parameters

  • slug: Optional. If provided, loads the environment slug from the

database. If omitted, unloads the current environment.

Examples

  • set_environment grass
  • set_environment

SetFacingModeAction[edit | edit source]

Change the facing mode of an NPC.

Usage

set_facing_mode <npc_slug>,<mode>

Parameters

  • npc_slug: Slug of the NPC whose facing mode will be changed.
  • mode: One of the valid facing mode names:
  • follow_movement
  • locked
  • scripted

This action immediately updates the NPC's facing behavior. When set to 'locked' or 'scripted', the NPC will no longer automatically rotate to match movement direction. When set to 'follow_movement', the NPC resumes normal facing updates driven by the PathController.

SetKennelVisibleAction[edit | edit source]

Set a kennel's visibility state for a character.

  • From hidden to visible:

set_kennel_visible player,name_kennel,true

  • From visible to hidden:

set_kennel_visible player,name_kennel,false

Usage

set_kennel_visible <character>,<kennel>,<visible>

Parameters

  • character: Either "player" or NPC slug name (e.g. "npc_maple").
  • kennel: Name of the kennel.
  • visible: Optional string flag to set visibility.

Accepts "true", "1", "yes" for visible (case-insensitive). Defaults to False when omitted or invalid.

SetLayerAction[edit | edit source]

Allows to change the color of the transparent layer.

Usage

set_layer <rgb>

Parameters

  • rgb: color (eg red > 255,0,0,128 > 255:0:0:128)

default transparent

  • Note: this is not a separate state, so it's advisable

to add a 4th value to the rgb, if not you're not going to see the character, ideally 128.

SetMissionAction[edit | edit source]

Set missions by updating it and by checking the prerequisites.

Usage

set_mission <character>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").

SetMoneyAction[edit | edit source]

Set an amount of money for a specific slug.

Usage

set_money <slug>,[amount]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • amount: Amount of money (>= 0) (default 0)

SetMonsterAttributeAction[edit | edit source]

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

Usage

set_monster_attribute <variable>,<attribute>,<value>

Parameters

  • variable: Name of the variable where to store the monster id.
  • attribute: Name of the attribute.
  • value: Value of the attribute.

SetMonsterFlairAction[edit | edit source]

Set or replace a monster's flair in a given category.

Usage

set_monster_flair <variable>,<category>,<flair>[,<sprite_type_1>:<sprite_type_2>:...]

Parameters

  • variable: Name of the variable that holds the monster's UUID.
  • category: Category of the monster flair.
  • flair: Name of the monster flair.
  • sprite_type(s): Optional pipe-separated list of sprite types
  • (e.g., front: menu01)
  • Behavior:
  • If the category already has a flair, it will be replaced.
  • If the category is new, the flair will be added.
  • If sprite types are provided, the flair will only apply to those views.

SetMonsterHealthAction[edit | edit source]

Set the hp of a monster in the current player's party.

Usage

set_monster_health [variable][,health]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable 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. A int value, which is the number of HP to be restored to. If no health is specified, the hp is maxed out.

SetMonsterLevelAction[edit | edit source]

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

Usage

set_monster_level [variable][,levels_added]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters level up.

  • levels_added: Number of levels to add. Negative numbers are allowed.

Default 1.

SetMonsterPlagueAction[edit | edit source]

Set a monster's plague to the given condition.

Usage

set_monster_plague <variable>,<plague_slug>,<condition>

Parameters

  • variable: Name of the variable where to store the monster id.
  • plague_slug: The slug of the plague to target.
  • condition: Infected, inoculated, or None (removes the plague from the

character, indicating a healthy state).

  • enforced_check: Optional string flag to enforce eligibility rules.

Accepts "true", "1", or "yes" (case-insensitive). Default is False (eligibility is bypassed).

SetMonsterStatusAction[edit | edit source]

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

Usage

set_monster_status [slot][,status]

Parameters

  • variable: Name of the variable where to store the monster id. If no

variable is specified, all monsters get/lose status.

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

cleared.

SetPartyAttributeAction[edit | edit source]

Set the given attribute of party's monsters to the given value.

Usage

set_party_attribute <character>,<attribute>,<value>

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • attribute: Name of the attribute.
  • value: Value of the attribute.

SetPartyStatusAction[edit | edit source]

Records important information about all monsters in the party.

Usage

set_party_status <player>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").

SetPricePolicyAction[edit | edit source]

Sets the PricePolicy for a specific NPC's economy.

Usage

set_price_policy <npc_slug>,<policy_slug>

Parameters

  • npc_slug: Either "player" or NPC slug (e.g. "npc_maple").
  • policy_slug: Slug of a price policy (e.g. "black_market").

SetRandomVariableAction[edit | edit source]

Sets a key in the player's `game_variables` dictionary to a randomly selected value from a specified list. Values can be repeated or weighted to influence selection probability.

Usage

set_random_variable <variable>,<value1>:<value2>:<value3>

You can also use weighted values: set_random_variable <variable>,<apple=1>:<banana=3>:<cherry=2>

Parameters

  • variable: The name of the game variable to set.
  • values: A colon-separated string of values to choose from.
  • Repeated values increase their selection chance.
  • Alternatively, use `value=weight` to assign explicit weights.

SetRoutingPolicyAction[edit | edit source]

Sets or resets the routing policy for future monster additions. This does not add a monster — it modifies how PartyHandler.add_monster behaves.

Usage

set_routing_policy <npc_slug>[,policy_name]

Parameters

  • npc_slug: NPC slug to apply the policy to.
  • policy_name: Name of the routing policy defined in routing_policies.yaml.

Examples

  • set_routing_policy player,starter_policy
  • set_routing_policy player,event_policy
  • set_routing_policy player # resets to 'default'

SetStepTrackerMilestoneShownAction[edit | edit source]

Marks a milestone on a step tracker as shown for a specific character.

Usage

set_step_tracker_milestone_shown <character>,<tracker_id>,<milestone>

Parameters

  • character: Either "player" or an NPC slug name (e.g., "npc_maple").
  • tracker_id: Unique name for identifying the step tracker.
  • milestone: Step milestone to mark as shown.

SetTeleportFaintAction[edit | edit source]

Set teleport faint data

Usage

set_teleport_faint <character>,<map_name>,<x>,<y>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • map_name: The name of the map to validate against.
  • x: The x-coordinate to validate against.
  • y: The y-coordinate to validate against.

SetTemplateAction[edit | edit source]

Switch template (sprite and combat_sheet).

Please remember that if you change the combat_sheet, it automatically changes the combat_back.

  • Example: if you put xxx, it's going to be xxx_back.png.
  • By using default:

set_template player,default

it's going to reassign the default sprite.

Usage

set_template <character>,<sprite>[,combat_sheet]

Parameters

  • character:

Either "player" or npc slug name (e.g. "npc_maple").

  • sprite:

Must be inside mods/tuxemon/sprites.

  • Example: adventurer_brown_back.png -> adventurer.
  • combat_sheet:

Must be inside mods/tuxemon/gfx/sprites/player.

  • Example: adventurer.png -> adventurer.

SetTuxepediaAction[edit | edit source]

Set the key and value in the Tuxepedia dictionary.

Usage

set_tuxepedia <character>,<monster_slug>,<label>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • monster_slug: Monster slug name (e.g. "rockitten").
  • label: seen / caught

SetVariableAction[edit | edit source]

Updates the player's game variables by setting key-value pairs.

Usage

set_variable <variable>:<value>[,<variable>:<value>]

Parameters

  • variable: The name of the variable.
  • value: The assigned value for the variable.

This implementation supports multiple parameters, allowing multiple variable assignments in one call.

SetWeatherAction[edit | edit source]

Sets the weather to a specific slug using the WorldWeatherManager. If no slug is provided, it triggers a weather advancement check.

Usage

set_weather <weather_slug> # Sets weather directly set_weather # Advances weather based on previsions

Parameters

  • slug: Optional weather slug (e.g., "rain", "sunny", "foggy").

ShowMonsterAction[edit | edit source]

Change to MonsterInfoState.

This action transitions to the MonsterInfoState, displaying detailed information about a specific monster.

Usage

monster_info_state <monster_variable>

Parameters

  • monster_variable: The name of the game variable holding the monster's UUID.

SpawnMonsterAction[edit | edit source]

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.

Usage

spawn_monster [npc_slug]

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").

the one who is going to receive the new born

StartBattleAction[edit | edit source]

Start a battle between two characters and switch to the combat module.

Usage

start_battle <character1>,<character2>[,music]

Parameters

  • character1: Either "player" or character slug name (e.g. "npc_maple").
  • character2: Either "player" or character slug name (e.g. "npc_maple").
  • music: The name of the music file to play (Optional).

StartCinemaModeAction[edit | edit source]

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

For a cinematic experience, specify the width of the horizontal and vertical black bars as a ratio of the screen resolution.

  • For example, to achieve a 2.39: 1 aspect ratio on a 1920x1080 screen,

you would set the horizontal ratio to 0.42 (1920 / 1080 * (16/9 - 2.39/1)) and the vertical ratio to 0 (no vertical bars).

By default only bar up and down.

Usage

start_cinema_mode [aspect_y_ratio][,aspect_x_ratio]

Parameters

  • aspect_y_ratio: The width of the horizontal black bars as a ratio of

the screen resolution. Default standard cinema mode.

  • aspect_x_ratio: The width of the vertical black bars as a ratio of

the screen resolution. Default None.

StartDoubleBattleAction[edit | edit source]

Start a double battle between two characters and switch to the combat module.

Usage

start_double_battle <character1>,<character2>[,music]

Parameters

  • character1: Either "player" or character slug name (e.g. "npc_maple").
  • character2: Either "player" or character slug name (e.g. "npc_maple").
  • music: The name of the music file to play (Optional).

StopCinemaModeAction[edit | edit source]

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

Usage

stop_cinema_mode

StoreMonsterAction[edit | edit source]

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.

Usage

store_monster <variable>[,box]

Parameters

  • variable: Name of the variable where to store the monster id.
  • box: An existing box where the monster will be stored.

StorePartyAction[edit | edit source]

Store the entire party in a box.

Save all monsters from the character's party into the named storage box, removing them from the party if successful.

Usage

store_party <character>[,box]

Parameters

  • character: Either "player" or an NPC slug (e.g. "npc_maple").
  • box: An existing box where the monsters will be stored.

If omitted, defaults to KENNEL.

TeleportAction[edit | edit source]

Teleport a character to a specific map and tile coordinates.

If a screen transition is in progress, the teleport will be queued and executed at the apex of the transition.

Usage

teleport <character>,<map_name>,<x>,<y>

Parameters

  • character: Slug of the character to teleport.
  • 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[edit | edit source]

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.

Usage

teleport_faint <character>,<healing>[,trans_time][,rgb]

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • healing: Trigger healing string flag ("true", "1", "yes" for True),
  • trans_time: Transition time in seconds - default 0.3
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(0,0,0)
  • eg: "teleport_faint player,true,3"
  • eg: "teleport_faint player,true,3,255:0:0:50" (red)

ToggleEvolutionBlockAction[edit | edit source]

Blocks or unblocks a specific evolution for a monster.

Usage

toggle_evolution_block <character> <monster_variable> <evolution_slug> <action>

Parameters

  • character: Either "player" or npc slug name (e.g. "npc_maple").
  • monster_variable: Name of the variable storing the monster's instance ID.
  • evolution_slug: The slug of the evolution to block/unblock.
  • action: "block" to permanently block, "unblock" to unblock.

TradingAction[edit | edit source]

Select a monster in the player party and trade.

Usage

trading <variable>,<added>

Parameters

  • variable: Name of the variable where to store the monster id (removed).
  • added: Slug monster or Name of the variable where to store the monster

id (added).

eg. "trading name_variable,apeoro" eg. "trading name_variable,name_variable"

TransferMoneyAction[edit | edit source]

Transfer money between entities.

Usage

transfer_money <slug1>,<amount>,<slug2>

Parameters

  • slug1: Either "player" or character slug name (e.g. "npc_maple").
  • amount: amount of money.
  • slug2: Either "player" or character slug name (e.g. "npc_maple").
  • eg: player,100,mom (player transfer 100 to mom)

TransitionTeleportAction[edit | edit source]

Combines the "teleport" and "screen_transition" actions.

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

Usage

transition_teleport <character>,<map_name>,<x>,<y>[,trans_time][,rgb]

Parameters

  • character: Slug of the character to teleport.
  • 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.
  • trans_time: (Optional) Transition time in seconds. Default is 0.3.
  • rgb: (Optional) Transition color in RGB format (e.g. "255:0:0" for red).

Default is black (0,0,0).

TransitionTeleportReturnAction[edit | edit source]

Teleport a character back to their previously recorded location, using a screen transition.

This action retrieves the last executed teleport request and sends the character back to its source map and coordinates. It must be used after a teleport that stored return data (e.g. source_map, source_x, source_y).

Usage

transition_teleport_return <character>,<facing>[,trans_time][,rgb]

Parameters

  • character: Either "player" or character slug name (e.g. "npc_maple").
  • facing: One of "up", "down", "left", "right". Case-insensitive.
  • trans_time: (Optional) Transition time in seconds. Default is 0.3.
  • rgb: (Optional) Transition color in RGB format (e.g. "255:0:0" for red).

Default is black (0,0,0).

  • Requirements:
  • A previous teleport must have been executed and stored in

`teleporter.last_teleport_request`.

  • The previous request must include valid source map and coordinates.
  • Example:
  • transition_teleport_return player,down,0.5,255: 255:255

TranslatedDialogAction[edit | edit source]

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.

Usage

translated_dialog <text>[,avatar][,position][,style]

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.

  • position: Position of the dialog box. Can be 'top', 'bottom', 'center',

'topleft', 'topright', 'bottomleft', 'bottomright', 'right', 'left'. Default 'bottom'.

  • h_alignment: Alignment of text in the dialog box, it can be 'left', 'center'

or 'right'. Default 'left'.

  • v_alignment: Alignment of text in the dialog box, it can be 'bottom',

'center' or 'top'. Default 'top'.

  • style: a predefined style in db/dialogue/dialogue.json

TranslatedDialogChoiceAction[edit | edit source]

Ask the player to make a choice.

Usage

translated_dialog_choice <choices>,<variable>

Parameters

  • choices: List of possible choices, separated by a colon ":".
  • variable: Variable to store the result of the choice.

TriggerStatusAction[edit | edit source]

Triggers the current status effect of a monster (e.g., poison, burn, sleep).

Usage

trigger_status <variable>,<status_name>

Parameters

  • variable: Name of the variable containing the monster ID. If not specified,

all monsters in the party will be affected.

  • status_name: Optional. If provided, only triggers the status effect if it matches

the monster's current status slug.

Examples

  • "trigger_status name_variable,poison"
  • "trigger_status name_variable"
  • "trigger_status"

TuneRadioAction[edit | edit source]

Launches the NuPhoneRadio interface for a given character, optionally tuned to a specific frequency.

This action transitions the game into a radio interface state, allowing the player to access broadcasts associated with a specific NPC. It can launch either the standard radio menu or the tuner interface, depending on whether a frequency is provided.

This is typically used in scripted events to simulate tuning into a radio station from a character's perspective or location, enabling dynamic storytelling and immersive audio experiences.

Usage

tune_radio <character_slug> tune_radio <character_slug>[,frequency]

Parameters

  • character_slug: The slug of the character (NPC) whose context will be

used to determine available radio stations and broadcasts.

  • frequency: If provided, launches the tuner interface and attempts to

tune directly to the specified frequency (in MHz). If omitted, the standard radio menu is shown instead.

UnloadSoundAction[edit | edit source]

Unload a specific sound from memory cache, or all sounds if no filename is given.

Usage

unload_sound <filename> unload_sound

Parameters

  • filename: Name of the sound file to unload.

If omitted, all cached sounds will be removed from memory.

UnlockControlsAction[edit | edit source]

Unlock player controls

Usage

unlock_controls

UnpauseMusicAction[edit | edit source]

Unpause the current (paused) music playback.

Usage

unpause_music

UpdateCipherAction[edit | edit source]

Updates the list of unlocked letters for a character used by the CipherProcessor.

Usage

update_cipher <character>[,letter]

  • Parameters:
  • character:

Either "player" or npc slug name (e.g. "npc_maple").

  • letter:
  • A single uppercase letter (or multiple separated by ': ') to add to

the character's unlocked set. If omitted, no new letters will be added, but the CipherProcessor will be updated with the current unlocked state.

UpdateTilePropertiesAction[edit | edit source]

Update tile properties by modifying movement settings or accessibility.

Usage

update_tile_properties <label>[,moverate]

Parameters

  • label: The name of the property to update (e.g., surfable, walkable).
  • moverate: The value of the movement rate (e.g., 1 for normal movement,

0 for inaccessible).

  • Example:

"update_tile_properties surfable,0.5" sets the surfable property to 0.5 for relevant tiles.

UpdateTimeAction[edit | edit source]

Update time variables.

Usage

update_time player

Parameters

  • file: File to load.
  • eg: "update_time player"

VariableMathAction[edit | edit source]

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``.

Usage

variable_math <var1>,<operation>,<var2>,<result> variable_math <var1>,<operation>,<var2>

Parameters

  • var1: First operand.
  • operation: Operator symbol.
  • var2: Second operand.
  • result: Variable where to store the result. If missing, it will be

``var1``.

WaitAction[edit | edit source]

Block the event chain for a given duration.

Usage

wait <seconds>

Parameters

  • seconds: Duration in seconds for the event engine to wait.

The wait is measured using accumulated delta time (dt) from the game loop, not wall clock time.

WildEncounterAction[edit | edit source]

Start a encounter with a single wild monster.

Usage

wild_encounter <monster_slug>,<monster_level>[,exp_mod] [,mon_mod][,env][,rgb][,held_item]

Parameters

  • monster_slug: Monster slug.
  • monster_level: Level of monster.
  • exp_mod: Experience modifier.
  • mon_mod: Money modifier.
  • env: Environment (grass default)
  • rgb: color (eg red > 255,0,0 > 255:0:0) - default rgb(255,255,255)
  • held_item: item held by the monster

WithdrawMonsterAction[edit | edit source]

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.

Usage

withdraw_monster <variable>,<character>

Parameters

  • variable: Name of the variable where to store the monster id.
  • character: Either "player" or npc slug name (e.g. "npc_maple").

the one who is going to receive the monster

Retrieved from "https://wiki.tuxemon.org/index.php?title=Event_Reference_Action&oldid=37492"