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.
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. |
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.
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
|
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 ) |
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.
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.
/// @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);
});
/// @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.
/// @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.
/// @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.
/// @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.
/// @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.
/// @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.