Utility and Helper #macros

raptor declares some macros that I considered useful (or I just got used to them, whatever ;-))

EXIT_GAME

GameMaker developers know that not every platform supports a clean exit from the game, especially consoles (and iOS) react not at all or even crash your game, if you call the game_end() function of GameMaker.
So, instead of calling game_end();, just write EXIT_GAME; when you want to quit. The macro does nothing if running on a platform that does not support game_end, otherwise, it calls it and ends the game.

Note

With release 2408 of raptor, this macro does even more:
It ensures, that all async operations are finished before exiting the game! So, this macro is clearly your best option to quit.

IS_HTML

Convenient replacement of the always-reappearing (os_browser != browser_not_a_browser).

IS_MOBILE

Convenient replacement of the always-reappearing (os_type == os_android || os_type == os_ios).

IS_SCRIBBLE_LOADED

It may be that you need to know whether scribble is loaded (well, you should know it in your own games...). However, raptor needs to detect whether you have removed scribble or not, so this macro is mostly used internally.. If you do generic stuff, it might become handy for you too.

SCRIBBLE_COLORS

Just another convenience thing. I do not like address globals directly, even more so when their name starts with two underscores, which normally represents a "don't touch me, I am internal" variable scope.
So, to avoid that, I declared SCRIBBLE_COLORS which is just a text replacement for global.__scribble_colours.

MY_NAME

This macro is very handy when writing logs to the console from an object. It resolves to the object name plus the instance id, producing a human readable name of the object and id in the log.
Example: log(MY_NAME + " created.");
would produce a line like PlayerObject(100036) created.
Printing out the instance id can help you find nasty bugs when something doesn't react as expected. You can always see which instance is active.
NOTE: Only works when object-scoped! In script scopes, no object_index exists.

MY_ID

Similar to MY_NAME but only holds the instance id without the name.

GAME_FRAME

A global frame counter that holds the current frame number rendered since the game has started (across all rooms).

GAME_SPEED

A global variable, has a default value of 1 and can be seen as a multiplier, similar to image_speed known from sprites.
Use this variable to fasten up or slow down your game. All Animations and real time effects of raptor react on this value. To "freeze" (pause) your game, simply set this to 0.

Together with this value, there are two evenly important globals available:

DELTA_TIME_SECS	The delta time of the last frame in seconds (this is the normal unit for delta time, not the microseconds, GameMaker delivers by default) multiplied with the GAME_SPEED! So, if you also plan all your animations and timings based on GAME_SPEED, they all will act the same. If GAME_SPEED is 0, this value also holds 0, so you can use it freely to calculate your real-time effects.
DELTA_TIME_SECS_REAL	In some situations, however, it might be important, to have the real time elapsed since the last frame, independent of the GAME_SPEED (like measuring the time, or showing a timer on screen -- time always runs at the same speed, no matter what value the GAME_SPEED variable has. Use this for a time measurement that is not affected by GAME_SPEED.

GUI_EVENTs

When an event such as a mouse click or a key press fires for an object in the GUI, you generally only want that code to run in the case it's the selected foreground element, and not on a hidden layer. The below macros provide information about, and reduce the boilerplate for checking such conditions.

The GUI_EVENT macros help you detect those situations easily in raptor, as long as you use raptor's functions for popups, messageboxes and as long as your objects are child objects of _raptorBase (the topmost class of everything, that is part of raptor).

First, there are some "private" macros, that build the base for event detection:

#macro	Description
__LAYER_OR_OBJECT_HIDDEN	The objects' visible is false or the containing layer is not visible
__HIDDEN_BEHIND_POPUP	The show_popup function or any of the MessageBox Functions is active and this object is not part of it
__CONTROL_IS_ENABLED	The object has an is_enabled property and this property is true
__CONTROL_IS_TARGET_MOUSE	The object is the top most at the current mouse position (lowest depth, closest to the user)
__CONTROL_IS_TARGET_XY	The object is the top most of its own position (x,y)
__INSTANCE_UNREACHABLE	__LAYER_OR_OBJECT_HIDDEN or __HIDDEN_BEHIND_POPUP is true

Those macros above are used to form these terms:

#macro	Resolves to
Bool expressions
SKIP_EVENT_MOUSE	(__INSTANCE_UNREACHABLE || !__CONTROL_IS_TARGET_MOUSE)
SKIP_EVENT_NO_MOUSE	(__INSTANCE_UNREACHABLE || !__CONTROL_IS_TARGET_XY)
SKIP_EVENT_UNTARGETTED	(__INSTANCE_UNREACHABLE)
Event exit conditions
GUI_EVENT_MOUSE	if (SKIP_EVENT_MOUSE) exit;
GUI_EVENT_NO_MOUSE	if (SKIP_EVENT_NO_MOUSE) exit;
GUI_EVENT_UNTARGETTED	if (SKIP_EVENT_UNTARGETTED) exit;

The summary of all these macros can be found in the last three lines of the table above.
These allow you to put a simple term as first line into your input events (mouse enter/leave/down/up/whatever), depending on what you want to check:

As an example, the left pressed event can have this as its first line of code:

GUI_EVENT_MOUSE;

This means, that the click event will only be processed, if the object is the top most at the mouse position, is currently visible and enabled, and no message box or popup is currently opened.
That's quite a lot of conditions and those macros simplify this somewhat complicated analysis extremely! Use them!

SECONDS_TO_FRAMES & FRAMES_TO_SECONDS

These macros resolve to * room_speed or / room_speed respectively, creating a neat declaration form for variables that depend on frames or seconds.

For instance, if you want something to flicker twice a second you could declare

var flicker_time = 0.5 SECONDS_TO_FRAMES;

Which is easily readable and also makes you independent of the actual room_speed and the frames per second the game processes.