Scenes

A scene is a single screen of your game. It can contain multiple actors and triggers. A game is typically made-up of many scenes connected together with triggers using the Change Scene event.

Adding a Scene

Click the button in the Editor Tools and select Scene from the menu. Click on any empty space in the Project Viewport to place the new scene.

You can use the Editor Sidebar to give your scene a name and a background from your project's assets. See the documentation for Backgrounds & Maps for more information on adding background images.

Scene Properties

• Name - The name of your scene. Useful for locating your scene with the search bar and scene navigator.

tip

Using / characters in your scene's name will cause it to appear within folders in the scene navigator (e.g. ui/title screen will appear as title screen within the ui folder)

• Resolution Mode - Lets you choose the size of your scene, H40 features 320px width and 224px height, H32 features 256px width and 224px height. It's useful if you want to display splash screens but use less ROM space by having narrower images.

• BG Color (0 - 63) - Lets you choose the palette color index for the background, if you have automatic palettes it won't display on the editor.

• Plane B (Background) - Lets you choose a backgrounds or maps file from the assets/backgrounds folder for the Background Layer.

• Plane A (Foreground) - Lets you choose a backgrounds or maps file from the assets/backgrounds folder for the Foreground Layer.

• Initial Palettes - If automatic is selected, the palettes will be selected based on the background and foreground files as well as the actors, if you select manual, you can attach up to four different palettes created on the Palettes view.

• Force to Scene Size - This makes the scene render on the fixed resolution you selected on Resolution Mode instead of falling back to the Background or Foreground size, it's useful if you have scrolling backgrounds on the main menu or other UI scenes to have a cleaner editor.

Plane B (Background)

The Plane B (Background) is usually used for backdrops, distant scenery, or large static backgrounds.

It can also use the priority bit to appear in front of sprites if desired.

It can scroll independently of Plane A (both horizontally and vertically), make sure to review Backgrounds & Maps > Maps vs Images requirements, as parallax scrolling only works with images.

Plane A (Foreground)

Plane A (Foreground) is often used for HUDs, menus, text, or foreground scenery.

Plane A usually sits in front of Plane B, but sprites can appear in front of or behind depending on the priority bit.

It can also be used for parallax scrolling — giving the illusion of depth by moving at a different speed than Plane B, make sure to review Backgrounds & Maps > Maps vs Images requirements, as parallax scrolling only works with images.

Parallax Mode

Clicking the button to the right allows you to turn on parallax mode (the top button is for Plane B (Background) parallax and the bottom button for the Plane A (Foreground) parallax) for the scene.

When parallax mode is enabled you can split the plane into up to three slices which can be modified to scroll at different speeds as the camera moves in game.
Be aware as noted on the Backgrounds & Maps > Maps vs Images section this only works with images and not with Tiled maps.

Palettes

The palette system has two different modes per scene.

• Automatic - The automatic mode picks the palettes based on the backgrounds or maps and actor sprites placed on the scene.
• Manual - The manual mode allows you to select four different palettes from the Palettes view that would be used on the scene.

Scene Scripts

Scenes can contain four different scripts.

• On Start - This script will be called as soon as the scene is loaded in the game. You can use this to do things like playing music as the scene loads, configuring events to happen on button presses, initializing actors based on the values of variables, and much more.

• On Update - This script will be called every frame before the Actor and Trigger On Update scripts, this can control most of your scene logic, like when to pause the game, or background effects, and much more.

• On End - This script will be called as soon as the scene is unloaded in the game. You can use this to pause music, do a fade out, save score if needed, and much more.

• On Pause - This script will be called instead of the On Update when the game is paused, you can place your pause update logic here.

To start building a script, select a scene, 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.

Adding Collision to a Scene

Select the Collision Tool from the Editor Tools. There are 6 default collision types that can be added.

• Solid - Stops colliding actors from entering the tile on any side.
• Top/Bottom/Left/Right - Stops colliding actors from entering the tile from that specific side. This is useful for one-way collision and semi-solid platforms.
• Ladder (Tile type) - Allows you to check if an actor is on top of a ladder to allow moving up and down, you can check the Action Platformer example for a detailed usage.

Each tile can hold a maximum of 1 ladder and 3 collision sides. Adding 4 collision sides will replace the sides with a single solid block. Ladders will not replace existing collisions when placed on top of another collision.

Additionally there is a dropdown menu allowing you to view additional tile types:

• Tile Types - These tile types can be used to mark a tile with a specific type, then you can check if an actor overlaps a specific tile type with the If Actor Touching Tile Type event. This is featured on the Game - Inkventure example.

Changing Palettes & Priorities on a Scene

Select the from the Editor Tools. This allows you to change the default palette for the background and foreground layers as well as the tile priority.

For more information about the drawing mode used for the Palettes & Priorities tool and the Collision tool, see Keyboard Shortcuts.

Changing Palettes

You can select from P0 to P3 for either background or foreground. After that you can click on the desired tiles.

warning

This requires some testing as the final palette depends on the one you use on each layer.

For example, if the Plane A (Foreground) uses Palette 1, and you tick to use Palette 0, the result would still be Palette 1!

Tile Priority

You can change the tile priority for either Plane B (Background) or Plane A (Foreground) from low-priority, the default one, to high-priority, these tiles will appear in front of actors allowing you to create depth in your scenes.

Select the from the Tool Bar to change the Plane B (Background) priority, and select the from the Tool Bar to change the Plane A (Foreground) priority.

The zones with high-priority will appear with a yellow or blue square respectively like in the next image.

Magic Brush

The Magic Brush is available when adding collisions, palette changes or priorities to a scene and can be used to paint every tile in the scene that matches the one you clicked instantly.

warning

The magic brush uses the information on the background plane first, if not present then on foreground.

When the layer is a Tiled Map file it tries to use the information on the Background Layer.

Scene Limits

MD Engine uses per-scene limits to keep performance predictable.

Each scene can have a maximum of 40 actors, 60 triggers and 4 palettes.

You can check this information by selecting a scene and looking for the gray bar under your scene that reads: A: 0/40 T: 0/60 P: 0/4. The letters on this bar represent the following:

• A: represents the number of actors that the scene is using.
• T: represents the number of triggers that the scene is using.
• P: represents the number of palettes that the scene is using.

warning

The actor and trigger limit is a recommendation. The game does build even if you exceed it.

But we can't guarantee performance or that it even fits on VRAM or RAM.

Due to this we won't be reviewing support requests where the performance limits are by-passed.

Use at your own risk!

Actor Limits

Each scene can have a maximum of 40 actors.

Make sure to check the Hardware Sprite information, clustering too many actors together in a scene will cause some actors to become invisible in-game on real hardware or emulators. For Desktop Export you can avoid this with the Enhanced Mode.

Trigger Limits

Each scene can have a maximum of 60 triggers.

Background and Sprite Tile Limits

The engine by default has 1004 Background & Foreground Tiles, 420 Sprites Tiles, and 96 Font Tiles.

You can change these settings from the Settings section or use the VDP Tiles Setup event on the scene OnStart, or OnEnd.

You can use the VRAM Viewer in the Debugger to get a visual representation of how tiles are being used in each scene in your game.

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.

Scene Processes

MD Engine follows strict Scene processing steps. This ensures all functions are called at known times and avoids confusion when writing event code.

The Start Process

The On Start script is called before anything else, right before calling the script all the used modules get reset, except for the Global Arrays.

The scene start process is outlined in the following steps.

1. Setup important data such as total actors and triggers, scene size and collision map
2. Set scene mode, BG color index and reset camera module if present
3. Load the palettes and create a backup
4. Load background, then draw the background
5. Wait 1 VSync
6. Load the foreground, then draw the foreground
7. Wait 1 VSync
8. Initiate the actors
9. Scene On Start script
10. Actors On Start script
11. Preload sprites if needed

Be aware of the Scene On Start call position compared to the Actors On Start call position.

The start process is closely related to the exit process, as there is always a scene transition, even if you select no-splash build, there is a 2 frame black scene to set up the system. So it's recommended to review this closely with the Exit Process.

Setting Palettes inside On Start

Using the Load Palettes event can mess up fade-in effects. The best is to use Preload Palettes event instead.

The Update Process

The On Update script is called every frame, right before calling the function the engine runs the following tasks:

1. Pre update all actors
   • Sets the last X/Y position
   • Reset the acceleration X for actors with platformer behaviour enabled
   • Marks the hitbox as not updated
2. Update timers module if active
3. Update tweens module if active
4. Call the scene update process
5. Update camera module if active
6. Update the scroll module if active
7. Increase the game timer
8. Check if a pause request has been issued
9. Sync all actors positions

The scene update process is outlined in the following steps.

1. Run the scene On Update script logic
2. Run the actors On Update script logic
3. Update behaviours
   • Update actor position based on physics and update hitbox
   • Clear actors touching values
   • Check actor against groups overlaps
   • Check group against same group overlaps
   • Check actors against scene collisions
   • Run the async On Collide script pending logics
4. Check triggers overlaps
5. Update projectiles module if active
   • Update actor position based on physics and update hitbox
   • Check overlap with actors
   • Check projectile against scene collisions
6. Check temporary triggers overlaps
7. Update particle position based on physics

Be aware of the Scene On Update call position compared to the Actors On Update call position.

The Exit Process

The On Exit script is called when we change from one scene to another.

The scene exit process is outlined in the following steps.

1. Run the actors On Exit logic
2. Run the scene On Exit logic
3. Free preloaded sprites if needed
4. Release actors
5. Clear maps
6. Reset the scene
7. Clear loaded images
8. On Debug mode clear the VDP
9. Free projectiles module if active
10. Free all non-global arrays, if the module is active
11. Free particles module if active
12. Reset the image scrolling
13. Reset scrolling to affect entire plane
14. Free the thread module if active
15. Free the timers module if active
16. Free the tween module if active
17. Reset the camera module if active
18. Update VDP layout if requested during On Exit
19. New scene start process
20. Update camera after the start in case we moved the follow element on the start method

Be aware of the Scene On Exit call position compared to the Actors On Exit call position, as it's inverted from the other two scripts.

The Pause Process

The On Pause script is called every frame while the game is paused, right before calling the function the engine runs the following tasks:

1. Pre update all actors
   • Sets the last X/Y position
   • Reset the acceleration X for actors with platformer behaviour enabled
   • Marks the hitbox as not updated.
2. Call the scene On Pause script
3. Check if an un-pause request has been issued
4. Sync all actors positions

The pause process is very simple due to all systems being paused and it's expected that there will be very little or no animations or movements altogether. Also, there is no async script processing.