Skip to content

Utility and Helper #macros

Grisgram edited this page Feb 26, 2024 · 14 revisions

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.

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.

GAMEFRAME

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

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

These macros 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.

Getting started

Raptor Modules

Clone this wiki locally