Docs / Scripting Events

Scripting events allow you to dynamically control parts of your game based on interactions from the player. Use them to connect scenes together, to give dialogue to your characters or to create cutscenes.

When either a scene, an actor or a trigger is selected in the World Editor, the Editor Sidebar will contain an Add Event button at the bottom right corner, click this to add new events. If any events have already been defined they will be listed here with the topmost event being the first that will be run.

When adding events to actors they will run when the player stands next to that actor and presses the interact button. Events on triggers run when the player stands on top of the trigger which is useful for creating doorways between scenes. Events on scenes run as soon as that scene is loaded which is useful for configuring the scene based on values of variables or to kick off a cutscene.

Add Events

After clicking the Add Event button a menu will appear to choose the event to add. If you start typing you can filter this list or you can scroll through it to find what you're looking for. Click an event or press the Enter key to add the highlighted event to your script.

Copy / Paste

Clicking the down arrow next to an event name in a script shows a dropdown menu where you can copy an event to your clipboard. Clicking this on another event allows you to paste the clipboard event either before or after the selected one or to just paste the values from the first event into the second.

New in 1.2.0

You can also hold the Alt key to turn all Add Event buttons into Paste Event buttons allowing you to easily paste events into control flow branches.

Text Events

  • Text: Display Dialogue
    Show a dialogue box with up to three lines of text, 18 characters per line (and a total of 52 characters), at the bottom of the game screen. This will likely be the most used script command for interacting with actors in your game.
    When text is shown the dialogue box will slide up from the bottom of the screen and will slide down after it has been shown.

    • Using the + button you can create a dialogue sequence which will only close after the last message has been displayed.
      New in 1.2.0
    • You can display the value of any variables in a text box by using the variable's identifier shown in the variable selector (e.g. $L0$ for local variable 0 and $182$ for global variable 182).
    • You can optionally display an avatar image on the left hand side of the dialogue box by clicking Add Avatar and selecting an image to use. You are able to pick any sprite within your game that contains only a single frame (16px x 16px). Setting an avatar will reduce the amount of characters per line available to 16 on all lines.
  • Text: Display Multiple Choice
    Present two options to player allowing them to make a choice, will set the specified variable to true if the first option is chosen and to false if the second option is chosen.

  • Text: Display Menu New in 1.2.0
    Display a menu of multiple options and set the specified variable to the value of the chosen option. Each menu item has a maximum length of 6 characters.
    Multiple layouts are provided, Menu (shown below) displays as a single column on the right hand side of the game screen and Dialogue displays a full width dialogue box with two columns. You can optionally set the B button to close the menu setting the variable to 0 and can also make the last menu item return 0 when selected.

  • Text: Set Animation Speed
    Set the speed that dialogue boxes appear and disappear and how fast text appears within the box.

Scene Events

  • Scene: Change Scene
    Transition to a new scene with player at a specified position and direction. A connection line will be drawn between the source of the event and the destination scene with a icon appearing at the destination position. It's possible to drag this icon around and between scenes to modify the event.

  • Scene: Store Current On Stack
    Store the current scene and player state on to the scene stack, this allows you to return to this exact location later using the Scene Restore events. A common use of this event would be to include in a script just before a Change Scene event to open a menu scene, in the menu scene you could wait for the player to press a close button and then use the Restore Previous From Stack event to return to where the player opened the menu.

  • Scene: Restore Previous From Stack
    Transition to the last stored scene from the scene stack using the specified fade speed. The previous scene will then be removed from the stack so the next time this event is used it will transition to the scene before that.

  • Scene: Restore First From Stack
    Transition the very first scene stored on the stack, for instance if you had multiple levels of menu scenes you could use this to imediately return to the game scene. This event will cause the scene stack to become empty.

  • Scene: Empty Scene Stack
    Clears the scene stack so that no previous scenes can be restored.

Variable Events

Your game has 512 variables that can be shared across all the scripts in your game. New in 1.2.0 Additionally every Actor, Trigger and Scene has 4 local variables that can only be accessed by that specific entity. Local variables are useful for keeping track of state specific to an entity such as how many times you have spoken to a character or if a treasure chest is open or closed.

  • Variable: Set To ‘True’
    Set the value of the specified variable to true.

  • Variable: Set To ‘False’
    Set the value of the specified variable to false.

  • Variable: Set To Value
    Set the specified variable to a defined value.

  • Variable: Increment By 1
    Increase the value of the specified value by one, up to a maximum of 255. If the value was previously false it will now be 1 (and also true), if it was previously true it will now be 2.

  • Variable: Decrement By 1
    Decrease the value of the specified value by one, down to a minimum of 0. If the value was previously true it will now be 0 (and also false).

  • Variable: Math Functions
    Allows you to perform various maths functions on a variable to add/subtract/multiply/divide/modulus a value/variable/random number.
    Note: Variables have max values of 255 and will wrap if increased above 255 or below 0.

  • Variable: Set Flags New in 1.2.0
    Set the value of a variable by enabling individual bits of the 8-bit number. Allows 8 true/false values to be stored within a single variable. Setting the flags will replace the previous value of the variable.

  • Variable: Add Flags New in 1.2.0
    Set selected flags to true on a variable. All unselected flags will keep their previous value.

  • Variable: Clear Flags New in 1.2.0
    Set selected flags to false on a variable. All unselected flags will keep their previous value.

  • Variable: Reset All Variables To ‘False’
    Reset all variables used by your project back to false.

Control Flow Events

  • If Variable Is ‘True’
    Conditionally execute part of the script if the specified variable is set to true.

  • If Variable Is ‘False’
    Conditionally execute part of the script if the specified variable is false.

  • If Variable Compare With Value
    Conditionally execute part of the script if the specified variable matches a rule, such as “Equal To”, “Greater Than” or “Less Than” against a value.

  • If Variable Compare With Variable
    Conditionally execute part of the script if the specified variable matches a rule, such as “Equal To”, “Greater Than” or “Less Than” against a second variable.

  • If Variable Has Flag New in 1.2.0
    Conditionally execute part of the script if the specified variable has the chosen flag set as true.

  • If Joypad Input Pressed
    Conditionally execute part of the script if the specified joypad input is currently pressed. Will not wait for user input so use directly after a Joypad Input: Pause Script Until Pressed event if waiting is required. Event will only execute once, if you wish to run a script every time a button is pressed use Joypad Input: Attach Script To Button instead.

  • If Actor At Position
    Conditionally execute part of the script if the specified actor is at a certain position in the scene.

  • If Actor Facing Direction
    Conditionally execute part of the script if the specified actor is facing a certain direction.

  • If Game Data Saved
    Conditionally execute part of the script if there is a saved game available.

  • Switch New in 1.2.0
    Conditionally execute from multiple options depending on the value of the specified variable. First choose how many options you want to compare the variable against, then set the values to compare and what scripts to execute when the value is matched.

  • Loop Forever
    Execute part of the script in a loop forever. Remember to break out of the loop otherwise the player will become stuck at this point. You can use a Stop Script or Change Scene event to stop the loop.

  • Label: Define / Label: Goto New in 1.2.0
    Define markers in your script using Label: Define giving the label a name and jump to markers using Label: Goto.
    Note: The name must be identical for the define/goto event pair to work. Use with care!

  • Event Group
    Provides no in game functionality but allows you to group a sequence of events together and give them a label (using the Rename Event option on the event menu) and collapse the events into a single block.

  • Script: Stop
    Stops the current script from running.

  • Disable Else New in 1.2.0
    If you don't require an Else branch in any of your control flow events you can now disable it by selecting Disable Else from the event dropdown menu. The same menu can be used to restore an Else branch if needed at a later time.

Camera Events

  • Camera: Move To
    Move the camera to a specifed position in the scene.

  • Camera: Lock To Player
    Move the camera back to focusing on the player, locking into position when the player moves.

  • Camera: Shake
    Shake camera effect for up to 10 seconds.

Screen Events

  • Screen: Fade In
    Fade the scene to a white screen.

  • Screen: Fade Out
    Fade the scene in from a white screen.

Actor Events

  • Actor: Set Direction
    Set the facing direction of the specified actor.

  • Actor: Set Direction Using Variable New in 1.2.0
    Set the facing direction of the specified actor from the value of a variable.

  • Actor: Set Position
    Set the position in the scene of the specified actor.

  • Actor: Set Position Using Variables
    Set the position in the scene of the specified actor from the values of two variables.

  • Actor: Set Relative Position
    Set the position in the scene of the specified actor relative to their current position.

  • Actor: Move To
    Make the actor walk to a specified position in the scene. Actor will ignore all collisions along path so combine multiple of these events if you need to specify an exact path avoiding obstacles in the scene.

  • Actor: Move Relative
    Make the actor walk to a position relative to their current position.

  • Actor: Move To Using Variables
    Make the actor walk to a position from the values of two variables.

  • Actor: Store Position In Variables
    Store the current position of an actor into two variables.

  • Actor: Store Direction In Variable New in 1.2.0
    Store the current direction of an actor into a variable.

  • Actor: Push Away From Player
    Push an actor in the direction the player is currently facing. By default pushes by one tile, but can optionally slide until a collision occurs.

  • Actor: Emote Bubble
    Display an emote bubble above the specified actor from one of Shock, Question, Love, Pause, Anger, Sweat, Music and Sleep. You can change the graphics used for these bubbles by editing the UI Elements of your game.

  • Actor: Set Animation Frame
    Set the current animation frame of the specified actor.

  • Actor: Set Animation Frame Using Variable New in 1.2.0
    Set the current animation frame of the specified actor to the value of a variable.

  • Actor: Set Animation Speed
    Set the animation speed of the specified actor.

  • Actor: Set Movement Speed
    Set the movement speed of the specified actor.

  • Actor: Set Player Sprite Sheet
    Change the player sprite sheet from the default defined in the Project Editor. Changes to the player sprite sheet will persist between scene transitions so make sure to change it back if the change was supposed to be temporary.

  • Actor: Collisions Disable New in 1.2.0
    Prevent collisions from affecting the selected actor. If a scene actor is selected then the player will be able to walk through them, if the player is selected then you will be able to walk through all actors and collisions in the scene.
    Note: While collisions are disabled it is still posible to interact with the actor.

  • Actor: Collisions Enable New in 1.2.0
    Reenable collisions on the selected actor.

  • Actor: Invoke Script
    Call the script on another actor in the scene as if the player had interacted with that actor.

  • Actor: Hide
    Hide an actor so it is no longer visible. Hidden actors will no longer cause collisions and will not be able to be interacted with. You can hide the player on a Scene Start Script to make menu and title screens.

  • Actor: Show
    Unhide a previously hidden actor.

Sprite Events

  • Sprites: Hide All
    Hide all sprites in scene. Can be useful to create cutscenes where the player should not be visible by adding to a scene's starting script.

  • Sprites: Show All
    Show all sprites that were previously hidden.

Overlay Events

  • Overlay: Show
    Show either a black or white window over the top of the current game screen. Can be used to obscure and then reveal parts of the scene background for example on the sample project logo screen.

  • Overlay: Hide
    Hides the screen overlay.

  • Overlay: Move To
    Moves the overlay to a new position on the screen.

Input Events

  • Joypad Input: Pause Script Until Pressed
    Pauses the script until one of the specified joypad inputs are pressed.

  • Joypad Input: Attach Script To Button
    Execute the specified script any time a joypad input button is pressed. If you attach scripts to a direction button or the A button the scripts will override the default game actions.

  • Joypad Input: Remove Attached Script
    Remove an attached script from a joypad input button restoring the default functionality of the button.

Music Events

  • Music: Play Track
    Plays a music file, optionally looping the file when finished.

  • Music: Stop
    Stops any currently playing music.

Sound Events

  • Sound: Play Effect New in 1.2.0
    Play a sound effect, choose from playing a beep with a given pitch, a tone with a given frequency or cymbal crash. Using Custom Events you can combine multiple effects into a single reusable event to make jingles.

Timing Events

  • Wait
    Pause script for up to 10 seconds.

  • Timer: Set Timer Script New in 1.2.0
    Execute the specified script repeatedly after a time interval. The script will keep running in the background until a Disable Timer Script event is called or the scene is changed using a Change Scene event.

  • Timer: Restart Timer New in 1.2.0
    Reset the countdown timer back to zero. The script will call again after the time specified originally.

  • Timer: Disable Timer Script New in 1.2.0
    Remove the timer script so it will no longer be called.

Game Data Events

  • Game Data: Save
    Save the current game data.

  • Game Data: Load
    Load the previously saved game data.

  • Game Data: Clear
    Remove any previously saved game data.

Miscellaneous Events

  • Comment New in 1.2.0
    Provides no functionality in game but allows you to leave notes within your scripts. The text you type automatically gets set in the event title so you can collapse the comment and still read its content.
    You can also use the event dropdown menu to disable and reenable any event.
    Disabled events will be skipped when run in game.