Skip to main content

Actors

Actors are the player, characters and objects in your scene that you can interact with.

Adding an Actor​

To add an actor to a scene click the button in the Editor Tools and select Actor from the menu (alternatively press the A key), then click on the scene and position where you wish to place the actor.

Add Actor

Actor Properties​

There are several settings you can adjust on the Editor Sidebar for your actors:

  • Name - Names your actor. Giving your actors a name helps organize them in your project. An actor's name will be visible in any drop-down menu that asks you to pick an actor, such as the Hide Actor event.
  • Position - Sets the X and Y position where the actor will be positioned in a scene. You can also change this by dragging the actor around the Game World.
  • Pin to Screen - Using the button next to the actor position you can choose to pin the actor to the screen which causes it to not move as the game screen scrolls.
  • Palette Slot - Selects the desired palette slot to use for this actor, if Auto Select is selected it will decide based on the spritesheet palette and the rest of the palettes in the scene.
  • Is Priority Actor - If enabled it will make the actor appear over the foreground.
  • Direction - The start direction of the actor.
  • Flip X - If the actor sprite sheet should initially be flipped on the X axis when starting.
  • Flip Y - If the actor sprite sheet should initially be flipped on the Y axis when starting.
  • Sprite Sheet - Choose which sprite graphics should be used to display the actor.
  • Preload Frames - Whether the sprite sheet will be fully preloaded into VRAM or streamed.
  • Collision Group - Choose the collision group this actor belongs to.
  • Disable Scene Collision - Fully disables the actor vs scene collision, this helps with performance.

Negative Coordinates​

warning

Actors with negative coordinates will be treated outside screen, most logic discards actors with X or Y below 0.

Pin to Screen​

When an actor is pinned it will appear in a fixed location as your game camera moves. The pinned actor will not move without a script, and does not create collisions with other actors in your scene.

Enabling this property will temporarily change your scene to be blacked-out, with a 320px x 224px (H40) or 256px x 224px (H32) boundary in the top-left corner showing part of your original scene. Use your mouse to drag the actor to where you want it to be pinned to the screen.

Select a different actor, the scene, or the project to return the blacked-out view of your scene to normal.

A common example of usage would be UIs, such as health bar, ammo, etc.

Collision Groups​

Actors can be given a collision group in the Editor Sidebar. When enabled, the option to run scripts based on collisions will appear in the Editor Sidebar. To learn more about On Collide scripts, see the documentation for Scripting.

Actor Scripts​

Actors can contain multiple scripts that will be called at different points in your game.

  • On Start: Called as soon as the scene is loaded in the game.
  • On Update: (only if Update Mode is set to Parallel) Repeatedly called every frame, once the script finishes it will repeat. You can use this to create movement scripts.
  • On Interact: (only if Update Mode is set to Interact) This is called if another actor stands in front of this actor and the Actor Interact event is called.
  • On End: This script will be called as soon as the scene is unloaded in the game.
  • On Collide: (only if collision group is set) This is called when this actor collides with either the player or a projectile with a specified collision group.

To start building a script, select an actor, click the script type you want to edit and click the Add Event button in the Editor Sidebar to open the event menu. Select an event to add it to the script.

For more information see the documentation for Scripting.

On Update Settings​

Inside the On Update script there are two extra settings, Update Mode and Keep Running While Offscreen.

  • Update Mode: If you select Parallel the script will run every frame, if you select Interact it will only run when something interacts with it.
  • Keep Running While Offscreen: If ticked the OnUpdate script will keep running even if the actor is outside screen.
Actor OnUpdate

Interactions​

Actor interactions can be invoked with Actor Interact event.

When this event is called, the X/Y position as well the actor direction would be used.
If there are other actors (such as NPCs) in front of the interacting actor (Player) their On Interact script will be called. (In other words, you must be facing the actor to interact. Set your direction using the Set Actor Direction event).

See the Top-Down Action example for a demonstration of usage.

Actor Scripting Properties​

There are several actor properties you can use inside Script Values when creating scripts.

  • Tile X - The left side position value in tile coordinates.
  • Tile Y - The top side position value in tile coordinates.
  • Tile X (Right Side) - The right side position value in tile coordinates.
  • Tile Y (Bottom Side) - The bottom side position value in tile coordinates.
  • Tile X (Center) - The center position value in tile coordinates.
  • Tile Y (Center) - The center position value in tile coordinates.
  • Pixel X - The left side position value in pixel coordinates.
  • Pixel Y - The top side position value in pixel coordinates.
  • Pixel X (Right Side) - The right side position value in pixel coordinates.
  • Pixel Y (Bottom Side) - The bottom side position value in pixel coordinates.
  • Pixel X (Center) - The center position value in pixel coordinates.
  • Pixel Y (Center) - The center position value in pixel coordinates.
  • Width - The actor bounding box width value in pixels.
  • Height - The actor bounding box height value in pixels.
  • Velocity X - The actor velocity in the x axis in pixels per second.
  • Velocity Y - The actor velocity in the y axis in pixels per second.
  • Acceleration X - The actor acceleration in the x axis in pixels per second squared.
  • Acceleration Y - The actor acceleration in the y axis in pixels per second squared.
  • Is Touching Floor - If the actor was, in the last frame, touching any collision tile/actor with the actor's bottom side of the collision box (i.e., standing on something).
  • Is Touching Left - If the actor was, in the last frame, touching any collision tile/actor on the left side of the actor's collision box.
  • Is Touching Right - If the actor was, in the last frame, touching any collision tile/actor on the right side of the actor's collision box.
  • Is Touching Up - If the actor was, in the last frame, touching any collision tile/actor with the actor's top side of the collision box (e.g., hitting your head on a ceiling).
  • Current Animation Index - The actor current animation index value as number (0 being the 1st animation row).
  • Direction - The actor current direction value as number.
  • Frame - The actor current animation frame value as number (0 being the 1st animation frame).
  • Is Animation Done - If the actor current animation is finished.
  • Is Visible - If the actor is visible (not hidden via Hide Actor).
  • Is Active - If the actor is active (activated in the scene and receiving updates).
  • Is Pinned - If the actor is currently pinned to screen (HUD-style, ignores camera scroll).
  • Is Flickering - If the actor's flicker effect is currently counting down.
  • Is Flipped X - If the actor's sprite is horizontally flipped.
  • Is Flipped Y - If the actor's sprite is vertically flipped.
  • Is On Screen - If the actor's position is inside the visible viewport.
  • Is Outside Screen - If the actor's position is outside the visible viewport (opposite of Is On Screen).
  • Is Outside Scene - If the actor's position is outside the scene bounds entirely.
  • Is Movement Enabled - If the actor is allowed to move (its movement flag has not been disabled).
  • Is Immovable X - If the actor is immovable on the X axis — collisions on its left or right will not push it.
  • Is Immovable Y - If the actor is immovable on the Y axis — collisions on its top or bottom will not push it.
  • Is Immovable - If the actor is immovable on both axes (X and Y).
  • Is Solid - If the actor blocks other actors on collision (active AND collisions enabled).
  • Is On One Way - If the actor is currently standing on a one-way platform tile.
  • Is Jumping - If the actor has a negative Y velocity (moving upward).
  • Is Falling - If the actor has a positive Y velocity (moving downward).

These properties can be selected in the Script Values area with the Property button.

This will create a selector like this:

Variable Set To Value
Variable
$Variable0
Value
Tile X

Replicate Actor​

You can replicate an actor, this will copy the actor across all created scenes in the game.

This has been created to make it easier to replicate UI across different levels.