RoomController - Grisgram/gml-raptor GitHub Wiki

In the project template, you can see, that there is one specific RoomController prepared for each room of the game. I strongly recommend, to keep that strategy through your game!

The reason is, that the RoomController has a lot of features and methods that work on the current room's settings, like Camera, Viewport(s) and the room size. It's not a good idea to create one persistent RoomController object for your entire game. That's, what a GameController is for.

It defines lots of macros and offers some very helpful methods to control the camera, like zooming and shaking and moving.

Variables of the RoomController

image

Variable Description
particle_layer_names This holds either a string or an array of strings with the names of the layers, where you want your Particle Effects to spawn. Read the documentation about the raptor particle systems for more information.
hide_mouse_cursor Some games need a mouse, some don't. Set this to true, to have your mouse cursor hidden when you enter the room that is controlled by this RoomController instance. See the next flag below, to understand the options, you have.
show_mouse_on_popups Works only, if hide_mouse_cursor is set to true. Activating this second flag will reshow the mouse cursor, whenever you show any popup view (via the show_popup() function) or use any of the MessageBox Functions.
adapt_app_surface If this is true, then the RoomController will resize the application surface to the dimensions of the main viewport in this room (index 0). As you should always use the RoomTemplate for raptor rooms, all your rooms should have viewport[0] enabled anyways.
escape_leaves_room Tired of writing the same "KeyPress-ESC" code over and over again? Just set this to true, to make the RoomController navigate back to the previous room, when you press the ESC key.
Navigation will only take place, if there is currently no popup visible.
The callback method onTransitBack will be invoked in your RoomController, so you can control the Room Transitions, that shall be used.

Game UI

With Release 3.0, a new macro, UI_ROOT has been added to the RoomController.

This is the root ControlTree for your game UI in the current room. It is recommended, that you add your UI elements for this room through the UI_ROOT tree. Please consult the UI Subsystem and ControlTree documentations for details about the new UI.

Tracking of GameWindow size changes

The RoomController detects, if the size of the game window has changed. This includes the HTML5 target, where changes of the browser window are also detected.

Macro Description
WINDOW_SIZE_X
WINDOW_SIZE_Y
Current size of the GameWindow
WINDOW_SIZE_X_PREVIOUS
WINDOW_SIZE_Y_PREVIOUS
Size of the GameWindow in the last frame
WINDOW_SIZE_DELTA_X
WINDOW_SIZE_DELTA_Y
Difference between the above values
WINDOW_SIZE_HAS_CHANGED true, if anything has changed, otherwise false

Mouse-Coordinate translation to GUI layer

These macros hold translated values from the world coordinates to the UI coordinates. The top left edge is always 0,0, no matter where your Camera is currently looking at.

Macro Description
GUI_MOUSE_X
GUI_MOUSE_Y
Current size of the GameWindow
GUI_MOUSE_X_PREVIOUS
GUI_MOUSE_Y_PREVIOUS
Size of the GameWindow in the last frame
GUI_MOUSE_DELTA_X
GUI_MOUSE_DELTA_Y
Difference between the above values
GUI_MOUSE_HAS_MOVED
MOUSE_HAS_MOVED
true, if anything has changed, otherwise false.
Both macros hold the same value, they point to the same variable, there's nothing calculated twice.
The second macro only exists for better readable code (it may look strange if you query a GUI mouse movement in a code part that has nothing to do with the GUI)

Camera control

RoomController offers some methods to animate the camera. Use these to add some nice effects to your game. But first, some details about how they work and what you need to know.

camera_action_data

All these methods return a camera_action_data struct, which, while being an internal struct of raptor, and therefore you should not tinker with it too much, offers one important end-user function.

By default the movement follows a linear AnimCurve (acLinearMove), moving (or zooming) at a constant rate to the target. To change this, you can use this function to replace the AnimCurve with a more spectacular effect if needed, like bouncing or smoother start/end movement.

set_anim_curve

/// @function		set_anim_curve(curve, x_channel_name = "x", y_channel_name = "y")
/// @description	Assigns a different AnimCurve than the default acLinearMove curve to this camera action.
///			The curve must provide the channels named in the x_ and y_channel_name parameters and
///			the value range must be 0..1, where 0 meanse "0%" and 1 means "100%" of distance done.
///			This function returns self to make it chainable.
/// @param {AnimCurve} curve 	The AnimCurve to use.
/// @param {string} x_channel_name	Name of the channel for the x-coordinate
/// @param {string} y_channel_name	Name of the channel for the y-coordinate
/// @returns {camera_action_data} struct Self, to be chainable.

A typical call to one of these functions could look like this:

Example for having the camera "look at" a specific point on the map (like hinting the player to an object, he should pay attention to), and moving back to the player object after a short wait time:

#macro MOVE_TIME   30
#macro WAIT_BEFORE_MOVE_BACK 180
camera_move_to(MOVE_TIME, super_treasure.x, super_treasure.y,, cam_align.middle_center)
    .set_anim_curve(acSmoothInOut);

run_delayed(WAIT_BEFORE_MOVE_BACK, function() {
    camera_move_to(MOVE_TIME, player.x, player.y,, cam_align.middle_center)
        .set_anim_curve(acSmoothInOut);
});

Camera animation functions

screen_shake

/// @function		screen_shake(frames, xinstensity, yintensity, camera_index = 0)
/// @description	Lets rumble! This function shakes the screen in a decreasing intensity over time.
/// @param {int} frames 	Duration of the effect in frames.
/// @param {real} xintensity	Horizontal intensity (in pixels).
/// @param {real} yintensity	Vertical intensity (in pixels).
/// @param {int=0} camera_index	Index of the camera to shake.
/// @returns {camera_action_data} struct The runtime struct for the effect.

camera_zoom_to

/// @function		camera_zoom_to(frames, new_width, enqueue_if_running = true, camera_index = 0)
/// @description	Zoom the camera animated to a new size, keeping the aspect ratio.
/// @param {int} frames			Duration of the movement in frames.
/// @param {real} new_width		The target width of the camera.
/// @param {bool} enqueue_if_running	Defaults to true. If another camera action is running, this one
///					will be queued to start afterwards.
/// @param {int=0} camera_index		Index of the camera to zoom.
/// @returns {camera_action_data} struct The runtime struct for the effect.

camera_zoom_by

/// @function		camera_zoom_by(frames, width_delta, enqueue_if_running = true, camera_index = 0)
/// @description	Zoom the camera animated to a new size, keeping the aspect ratio.
/// @param {int} frames			Duration of the movement in frames.
/// @param {real} width_delta		The amount of pixels to modify the camera width.
/// @param {bool} enqueue_if_running	Defaults to true. If another camera action is running, this one
///					will be queued to start afterwards.
/// @param {int=0} camera_index		Index of the camera to zoom.
/// @returns {camera_action_data} struct The runtime struct for the effect.

camera_move_to

/// @function		camera_move_to(frames, target_x, target_y, enqueue_if_running = true, 
///					camera_align = cam_align.top_left, camera_index = 0)
/// @description	move the camera animated over time to a specified position with an optional alignment.
///			The cam_align enum can be used to specify a different alignment than
///			the default of top_left. For instance, if you specify align.middle_center here,
///			this function works like a kind of "look at that point", as the CENTER of the view
///			will be at target_x, target_y coordinates.
/// @param {int} frames			Duration of the movement in frames.
/// @param {real} target_x		The amount of pixels to move the camera.
/// @param {real} target_y		The amount of pixels to move the camera.
/// @param {bool} enqueue_if_running	Defaults to true. If another camera action is running, this one
///					will be queued to start afterwards.
/// @param {camera_align} 		Alignment of the target coordinates. Default is cam_align.top_left.
/// @param {int=0} camera_index		Index of the camera to move.
/// @returns {camera_action_data} struct The runtime struct for the effect.

camera_move_by

/// @function		camera_move_by(frames, distance_x, distance_y, enqueue_if_running = true, camera_index = 0)
/// @description	Move the camera to a new position, relative to the current one, animated over time.
/// @param {int} frames			Duration of the movement in frames.
/// @param {real} distance_x		The amount of pixels to move the camera.
/// @param {real} distance_y		The amount of pixels to move the camera.
/// @param {bool} enqueue_if_running	Defaults to true. If another camera action is running, this one
///					will be queued to start afterwards.
/// @param {int=0} camera_index		Index of the camera to move.
/// @returns {camera_action_data} struct The runtime struct for the effect.

camera_look_at

/// @function				camera_look_at(frames, target_x, target_y, enqueue_if_running = true, 
///                                                    camera_index = 0)
/// @description			move the camera animated so that target_x and target_y are in the center
///                                     of the screen when finished.
/// @param {int} frames			Duration of the movement in frames.
/// @param {real} target_x		The x-position to look at.
/// @param {real} target_y		The y-position to look at.
/// @param {bool} enqueue_if_running	Defaults to true. If another camera action is running, this one
///					will be queued to start afterwards.
/// @param {int=0} camera_index		Index of the camera to move.
/// @returns {camera_action_data} struct The runtime struct for the effect.
⚠️ **GitHub.com Fallback** ⚠️