Room Transitions - Grisgram/gml-raptor GitHub Wiki

From raptor Version 2.0 on, there is a RoomTransition subsystem included. It allows you to animate the change from one room to another.

Included are standard fade-in/-out effects, a blend effect, sliding (in all directions, based on Animation Curves) and pixelation. The subsystem is designed to be extended, you can add your own transition effects easily with a few lines of code.

Quite easy. Instead of doing a room_goto(newRoom) call, you do a ROOMCONTROLLER.transit(transition) call. It's really just one line of code.

See this example for a better understanding:

ROOMCONTROLLER.transit(new FadeTransition(rmMain, 30, 30));

Where the three parameters are: The room to go to, the frames (duration) of the fade-out and the frames for the fade-in of the new room. That's it!

In addition, to this very comfortable animated room-change mechanism, the ROOMCONTROLLER does more for you.

It records the chain of rooms, each room you enter will be put on a stack, so the RoomController knows, where you came from, just like in a mobile app, where's always a "back" button available.

You can go "back" to the previous room, anytime by calling ROOMCONTROLLER.transit_back(). This function needs no arguments, it knows everything from the RoomController's internal data.

However, either when you have the RoomController variable escape_leaves_room set to true, or when you manually call transit_back(), the callback method onTransitBack gets invoked on your RoomController:

/// @func	onTransitBack(_transition_data)
/// @desc	If escape_leaves_room is active, this is invoked, before the room is left.
///			THIS ONLY EVER GETS INVOKED, WHEN THE USER PRESSES THE ESC KEY **AND**
///			"escape_leaves_room" is true **AND** no popup is curently visible.
///			_target_room contains the room, this will change to, or undefined
///			if there is no room before this one. In this case, the game will exit.
///			Return true to allow the room change or false to abort it and stay in this room.
onTransitBack = function(_transition_data) {
	// Example reaction:
	// If you want to stay in this room
	// _transition_data.cancel = true;
	// ...or supply a transition to the target room
	// _transition_data.transition = new FadeTransition(_transition_data.target_room, 20, 20);
	// ...or do nothing of the above to have a simple room_goto fired to the target room
}

It receives a data struct with these members:

_transition_data = {
        escape_pressed: <whether esc has been pressed>,
	target_room: <the room you will redirect to>, 
	transition: <set a transition to use or leave it undefined>, 
	cancel: <set this to true to abort the room change>
};

As shown in the code comments above, you can set the members of this struct, to whatever you like:

• Set the transition to any animation, you would like to have occur for the travel back
• You might even redirect to another room, by manipulating target_room (not recommended! This member is sent to the function to let you see, where the travel target is, but in theory, yes, you may override this)
• Cancel the navigation, and stay in the current room, by setting _transition_data.cancel = true;

Out of the box, there are some transitions packaged with raptor.
Watch this video - here you can see all transitions in action.

new FadeTransition(rmMain, 30, 30)

Parameters:

• new room
• fade-out frames (duration)
• fade-in frames (duration)

new PixelateTransition(rmMain, 45, 45, 32)

Parameters:

• new room
• fade-out frames (duration)
• fade-in frames (duration)
• max. pixelation (cell size - 32 is a good value)

new BlendTransition(rmMain, 60)

Parameters:

• new room
• blend frames (duration)

new SlideTransition(rmMain, 60, acBounceX)

Parameters:

• new room
• slide frames (duration)
• anim curve for animation

A few words to the AnimCurve in the SlideTransition: You create an AnimCurve asset that has either a cuve named x or a curve named y. This defined the direction of the slide.

Set up your curve like this:

Linear slide from left to right

You see, a single curve, named x, and the value goes from 0 to 1. For a slide to the left, let the value go from 0 to -1. The same can be done vertically, just name your curve y instead of x.

Bouncing slide from the demo-video

By applying a Bezier or smooth effect, you can create amazing effects here.

raptor delivers some generic standard AnimCurves, and four of them are here to support you with the SlideTransition:

The names make quite clear, what each of those does.

To move the current room to the right, use acLinearXPlus, to move it to the left, use acLinearXMinus and do the same for vertical movement with the YPlus/YMinus curves.

I suggest, you take a look at the RoomTransitions script, which can be found in the _generic_objects_ folder of raptor.

It contains the base class __RoomTransition which must be the parent, when you implement your own, as well as the shown transitions in the video above. It's just a few lines of (I hope, self-explanatory) code.

Don't hesitate to ask me for assistance, if you get stuck, implementing your own transitions!