Transition Example

On this page we will go through a transition implementation from a menu/starting room to a play/level room.

Define, what we need

First, let's take a look at what we want to achieve:

• We are in the main menu, there's a "Start Game" or "Continue Game" button
• When this button is clicked, the game shall switch to the "Play" room
• But the "Play" room needs some information, like "which level to load".
• We could solve this through some global variable, yes, but this is not a desirable way for many reasons
• Instead, we will give the room the information it needs through the transition object that will start the room

Transit from rmMain to rmPlay

We will do a FadeTransition from the main room to the play room.

In the on_left_click callback of the button (see raptor UI documentation in Clickables) we will transit to the play room:

ROOMCONTROLLER.transit(new FadeTransition(rmPlay, 45, 45, { level_to_load: 1 });

• This starts a fading transition, 45 frames to fade out this room and 45 frames to fade in the rmPlay.
• As data object we deliver a struct with only one member: level_to_load

In rmPlay

When the transition starts, there will not be happening anything for the next 45 frames (fade out).

After that, the ROOMCONTROLLER will do a room_goto and switch to rmPlay.

This point in time is important, because the ROOMCONTROLLER of rmPlay will be created now, when the new room gets instantiated.

There are two important moments in the target room (rmPlay):

• The Create event of the room controller in the target room
• The onTransitFinished callback in this room controller

The room controller you get for a room when you use the raptor room template, which is the only valid way to create a raptor-compatible room in your game, already contains an empty implementation of onTransitFinished (and onTransitBack, more on this later), located in the Create event:

onTransitFinished = function(_data) {
}

onTransitBack = function(_transition_data) {
}

Make sure, you are aware of the timing:

• Create runs immediately, when the instance of the room controller is created
• onTransitFinished will be invoked in 45 frames from now, when the fade-in is completed

Knowing this, we can say:

• "I should load the level, when the room controller gets created, as the scene is black currently and if the level loading takes some milliseconds, the player won't recognize"
• "I should start the level (maybe spawn the player object, depends on the game you have in mind), when the transition is finished and the scene has become visible"

Ok, so let's do this.

We sent a data structure, containing level_to_load with the transition.
To access the currently running transition in the room controller, you use the ACTIVE_TRANSITION macro.

So, let's load the level in the Create event, but not in the onTransitFinished method. Do it directly in the Create code:

// The ACTIVE_TRANSITION has a "data" member, which holds the struct you supplied in the main room
var to_load = ACTIVE_TRANSISITION.data.level_to_load;
load_level(to_load);

onTransitFinished = function(_data) {
}

...and we said, you start the level, when the transition is finished. So, step 2 is now to add code to the callback:

// The ACTIVE_TRANSITION has a "data" member, which holds the struct you supplied in the main room
var to_load = ACTIVE_TRANSISITION.data.level_to_load;
load_level(to_load);

onTransitFinished = function(_data) {
    start_level();
}

The _data argument, the callback receives is also the same data struct as in ACTIVE_TRANSITION.data, but as the callback gets invoked only after the transition has finished, ACTIVE_TRANSITION is already undefined again, when the callback occurs. That's why the callback receives the data struct as argument, because it can't be accessed any longer through the macro at this time.

Going back to rmMain

There are two ways to go back to the main room:

• First, of course, you can simple do another transit from rmPlay to rmMain
• The more elegant solution is to use the transit chain of raptor. It records the navigation history between rooms of your game, just like a mobile app, where you can always use the "back" button to get back to the form you had before.

To simply "go back to where I came from", you can call transit_back() in the room controller.

Let's illustrate this with a "game_over" function in your create event of the room controller:

// The ACTIVE_TRANSITION has a "data" member, which holds the struct you supplied in the main room
var to_load = ACTIVE_TRANSISITION.data.level_to_load;
load_level(to_load);

onTransitFinished = function(_data) {
    start_level();
}

game_over = function() {
    // Do your game-over thing, show highscore, whatever

    // This will go back to the rmMain
    // but invokes the "onTransitBack" callback before doing so.
    transit_back(); 
}

onTransitBack = function(_transition_data) {
    _transition_data.transition = new FadeTransition(_transition_data.target_room, 45, 45);
}

Using transit_back will set up everything to leave the room and invoke onTransitBack. The struct you receive here contains a transition member, where you can add any transition you like to happen when travelling between the rooms. The Room Transitions page contains a full documentation of this callback and the struct it receives.

---

That's it!
I hope, this example could explain, how you can communicate between rooms while a transition animation is running!