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.

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.

Raptor core: Macros ● Logger ● Controllers ● LG Localization ● RACE (The Random Content Engine) ● Savegame System
Game modules: UI Subsystem ● Animation ● StateMachine ● Shaders ● Particle Effects ● Tools, other Objects and Helpers

Back to Repo ● Wiki Home ● Copyright © coldrock.games

⚠️ **GitHub.com Fallback** ⚠️