Object Events

Each object you create has its own discreet list of events which are added into it from the Object Editor. These events fall into two categories: those that run every single game step, and those that are "triggered" by a game event, like the instance reaching the room edge or a keyboard or mouse press. The full list of events is given below:

This event happens when an instance of the object is first created, and is the very first thing that happens within an instance placed in the room through the room editor when a room is entered. This means that this event is the ideal place to initialize variables, start Timelines, set Paths etc... and do anything else that generally only needs to be done once or only when an instance is first created in the room. If your object has any Object Variables or Instance Variables added in either the Object Editor or the Room Editor, then these variables will be initialised first and then the Create Event will be run.

Remember that you can modify anything you set up in the create event from the Instance Creation Code in the Room Editor, as this is run directly after the create event for the instance.

This event is the event to be executed when an instance is destroyed. It is often overlooked when adding behaviours to objects, but it can be very useful, for example by creating explosion or particle effects when an enemy is killed, or for re-spawning a new instance of the object in another part of the room, or even for adding points onto a score.

This event will be called after any event that removes an instance of the object from the room. So, it will be triggered if the instance is destroyed, if the room ends, or if the game ends, and is designed for you to use to "clean up" any dynamic resources that you may have in your game (like surfaces, data structures, etc...) or to perform any task that you need performed once when the instance is removed. Note that this event will be called instantly after the event that triggered it, but the instance will not actually be removed from the game until the end of the current event. For example, if you call instance_destroy() in the Step Event, then the Destroy Event will be called, then the Clean Up Event, and then the rest of the Step Event will finish running. This means that any code you have after the call to instance_destroy() will still be run and be a potential cause for errors if you've cleaned up a data structure or some other resource that the code requires, so care must be taken when using this event.

The alarm event is split into 12 sub events, one for each of the possible alarms that can be set in an instance. So, when you click on the add alarm button you are presented with this window: Object Editor Alarm Events

Here you select the alarm that you wish to create and, once that is done, you will see that it has been added to the event window allowing you to add code to it as normal. But what is an alarm? Well, it is a special event that does nothing unless the alarm has been previously set, and then it will wait until that alarm has counted down to 0 before running the actions or code that you have added into it. Once the alarm has reached 0 and run the code, it will then count down to -1, where it will remain until set again (meaning you can check the value of an alarm to see if it is greater than -1, which will tell you if it's running or not). So, say you set alarm[0] in the create event of the object to 30, this means that GameMaker Studio 2 will count down 30 game steps before it runs the actions or code that are placed in the alarm[0] event. Note that setting an alarm to 0 will not run the alarm code, as the event is triggered, but the alarm set to -1 immediately, so the code is skipped. If you need an alarm to run the very next step, then you should set it to 1.

This can be very useful as it allows you to set things in motion at precise moments, and you can even have them repeat as there is nothing to stop you setting an alarm in its own event. Imagine you have a monster and you want it to turn right every three seconds... well, you would set an alarm in its create event to the room speed * 3 (if the room speed is 30, that's 30 steps per second, so multiply that by 3 and you get 3 seconds!) and then in the alarm event you would have the code or action to set its direction, as well as the action (or code) to set its alarm to room speed * 30 again. In this way, you can set up simple game loops where things only happen at specific intervals.

It is worth noting that an alarm with no actions or code in it in it will not run down. However, even with just a comment and no code or actions, then the alarm will continue to count down and can be set and checked as you would normally.

GameMaker Studio 2 splits time into steps with the room speed defining how many of these steps there are supposed to be per second. A step, is basically the loop that runs constantly with all the events being checked and triggered as necessary while the game runs, so as you can imagine, the Step Event is an event that is checked every single step of the game while the instance exists.

The step event is actually comprised of three sub events that are outlined below: Object Editor Step Events

For most things the standard step event will be fine to use, but sometimes you want a bit more control over what code runs and at what time, so for that you are provided with the Begin and End step events. All three are checked every step, but their order will never vary even through future updates to the GameMaker Studio 2 engine, which means that this is the only reliable method of making sure that something always happens before something else.

What can the step event be used for? Well, it can be used for actions or code that needs to be executed continuously. For example, if one object should follow another, here you can adapt the direction of motion towards the object we are following to keep it moving smoothly behind. Be careful with this event though, and don't put many complicated actions in the step event of objects, especially if you are planning on having lots of instances of the object in your game room, as this might slow the game down. Many things can be placed into alarms, or set to trigger using some of the Other events, rather than happening all the time.

Obviously when making a game, it is very important that you know when two (or more) instances of an object have collided, and for that we have the collision event. This is an event that you place in an object and then specify against which other object you should be checking for collisions.

When you don't have physics turned on, these collisions will be calculated based on the mask of the two objects (the mask is defined within the sprite properties, or can be assigned independently in the object properties) and whether they overlap or not. Note, that if one or the other instances in the collision does not have a mask assigned (or the sprite mask is set to nothing), even if it is drawing something no collisions will be detected.

If you have Physics on, then the collision will be based on the type of collision shape (Fixture) that you have defined for the object in its physics properties, as will its reaction to the collision. This means you may not need any code to deal with the collision, but this event will still need to have at least a comment in it for the collisions to be detected.

Finally, it should be noted that all collisions will be calculated once per game step before the collision event is triggered, such that when the collision event runs, all collisions will have been calculated already and pre-assigned. This means that if you create an instance in this event and then try to check for a collision with it, the collision wont be detected or resolved until the next iteration of the game loop.

Letting the player control the different aspects of your game is very important, and to that end GameMaker Studio 2 provides you with a very comprehensive list of keyboard sub events that can be used in any of the three main keyboard events. For the general keyboard event, it is triggered continuously, every step, for as long as the selected key is pressed down.

It should be noted that keyboard events are actually triggered in all active instances in a room whenever a key is used, but only those that have an event defined for that particular key will respond and you can create multiple keyboard events in any object and the instances of that object will respond to all of them while the game is running.

When you add any keyboard event to an object, you will be presented with the keyboard sub event menu where you can specify the key you are to be checking for: Object Editor Keyboard Events

Most of them are fairly obvious, but let's just go through the sections briefly - at the top we have the arrow keys, followed by the most used modifier keys, then the rest of the keyboard (split into further sub-sections so you can get the exact key required like or ) and finally two very special sub events, No Key and Any Key. As their names imply, these are sub events that check for when no key is pressed or for when any key is pressed. Please note that the keys on the numeric keypad only produce the corresponding events when Number Lock is enabled.

The Press and Release events for the keyboard are almost exactly the same as the regular keyboard event, except that instead of being triggered continuously, they are triggered once only. When the keyboard first registers that a key has been pressed it will generate a Keyboard Pressed event (as well as a regular Keyboard event), and the first time after that where a key is no longer being detected as pressed it will trigger a single Keyboard Release event.

The mouse event is separated into a series of sub events that can be selected to give you a more precise control over what is happening in your game. Here you can see exactly what these sub events are: Object Editor Mouse Events

The left , right and middle button events (whether normal, pressed or released) all work on the mask of the instance that has the event. What this means is that GameMaker Studio 2 will check the position of the mouse in the room when those buttons are used against the collision masks of the instances that have a mouse event. If there is a "collision" then the event will be triggered, so make sure that any instance with these events has a sprite with a valid mask or that the object has a mask selected in the object properties. As their names imply, these events will be triggered either once when the chosen mouse button is first pressed or released, or continuously each step while the button is maintained.

The mouse enter and leave events are also similar to the button events in that they too rely on the mask of the instance to work, but this time they are triggered when the mouse first "enters" (touches) the instance or when the mouse "leaves" (stops touching) the instance. These events are not continuous however, and are triggered only once for each time the mouse enters or leaves the object - so they are an ideal method for creating, for example, buttons that need to change as the mouse hovers over them before going back to normal when the mouse is removed.

Finally we have another section to the mouse events which is called the Global Mouse. In this sub-menu you will find a selection of events that are for recording mouse events in instances even when the mouse is not over them or even near them. These are events that are generated for all instances and if there are actions or code defined for the specified event then it will be run, regardless of the position of the mouse within the game room.

Please note that on mobile or touch-screen devices the left mouse button can also be used to check for a finger tab on a touch screen, and the right mouse button is triggered by a double tap on the screen (this behaviour can be changed using code).

This event is the one that will be triggered by the user touching the screen (on mobile) or clicking and moving the mouse (on all other platforms). It detects the following:

  • taps - when a user clicks/touches and releases quickly

  • drags - when a user touches/clicks and maintains it then moves their finger/cursor

  • flicks - when the user moves and releases a touch/click in one movement

  • pinches - when the user has two fingers on the screen and then moves them together/apart

  • rotates - when the user has two fingers on the screen and then rotates them around a point
Object Editor Gesture Events

The different events will always contain a DS Map called the "event_data" map, which will contain a number of key/value pairs with data on the touch/click position and movement. For full details on all the available sub-events and how they work, please see the following section:

  1. Gesture Events List

There are a number of special events for use when making games with GameMaker Studio 2 and they are mostly grouped together under the Other event and can be selected from the pop up menu of sub events that comes up when you select this. Here is an image of all these other events: Object Editor Other Events

This event is triggered when an instance goes outside the room, and is based on a check done against the assigned sprite (and its properties) of the instance, so that even if you have set the image x or y scale to a value other than one, this event will only be triggered when the whole sprite would be out the screen. If the instance has no sprite, then the position of the instance is used and the moment its x or y position is outside of the room then it will trigger the event too. This event is typically used for things like bullets, where they are destroyed once they leave the room so you don't end up with millions of bullets flying away infinitely and causing your game to slow down. Note that this event is only triggered once when the instance leaves the room initially.

This event is triggered when an instance "touches" the inside edge of the room, and, like the outside room event, is based on a check done against the assigned sprite (and its properties) of the instance, so that even if you have set the image x or y scale to a value other than one, this event still be triggered the moment a part of the sprite intersects the room boundary. If the instance has no sprite, then the position of the instance is used and the moment its x or y position intersects the room boundary then it will trigger the event too. You can use this event to do things like tell an instance to "bounce" back in towards the room again rather than go outside.

Views are normally defined in the room editor and used to show only a small area of a large room at any one time. This event has its own sub event list that is split into two categories (outside view and intersect boundary), with eight different events in each corresponding to the eight available views. These two categories function exactly the same as the respective room events, only taking the boundary of the view as the thing for the instance to check against rather than the room.

This special event is triggered only once in the whole game and only for those instances with actions or code placed in the event. These instances must be present in the first room of the game and have been placed there in the room editor, rather than have been created dynamically. It should be noted that this event happens after the create event of all instances and so can contain code or actions with variables that have been previously defined in that event. This event is typically defined in only one "controller" object and is typically used to initialize global variables, start music, read from files and any other thing that is usually only done once at the start of a game.

Similar to the above mentioned Game Start event, this event is only triggered once in the whole game and that is just before the game window actually closes. Again, for an instance with this event to actually do anything it has to be in the room as the game is closed. Please note that this event in really only viable for Windows, Ubuntu (Linux) and MacOS games as mobile devices may just close the game without giving GameMaker Studio 2 the chance to call this event. For browser games made with the HTML5 module, this event should work when the game tab or browser is closed, but not all browsers support this feature (Firefox, Chrome and Safari do at the time of writing) so care must be taken when using it. Typically you would use this event to save data.

This event happens for all instances initially in a room when the room starts. Please note that it happens after the creation event and so can depend on variables and things defined previously in that event.

This event happens to all instances that are in the room when the room ends. This event is very useful for "cleaning up" after a level has ended, for example you can delete loaded resources here, or remove a particle system to prevent memory leaks etc...

In GameMaker Studio 2 sprites are not static things as they can have sub-images and be animated at different speeds. Each frame of an animation (called a sub-image) has its own number, starting at 0, which can be checked in code or even through actions, but sometimes all you really need to know is when the animation has ended. That's when this event is triggered, right at the end of the animation when the sub image index shows that the last frame has been reached. This event is really useful for many things, for example an explosion object where you can set the instance to destroy itself when the last frame of the animation is reached.

This event is designed only for use with the Skeletal Animation Functions. It is a special event that is triggered every step in an instance that uses a skeletal animation sprite, and is designed to "intercept" the bone data after the orientation of the bones has been calculated for the current animation state but before this data is committed to use for drawing. This allows you to make modifications to the bone data using the appropriate functions.

This event is designed only for use with the Skeletal Animation Functions. This event is triggered in an object which has a skeletal animation sprite assigned to it, and where the object is using the default draw for the assigned sprite, or the sprite is being drawn via draw_self(). It currently won't trigger on skeleton animation sprites drawn any other way. The event is designed to capture and transmit data that has been assigned to particular events in the sprite animation as defined in the editor used to make them.

When the Animation Event is triggered, a special ds_map will be created called the event_data map (much the same as we have the async_load map for an async event). This map will have all of the following key/value pairs that you can parse to get information about the event:

  • "name": the name of the event (as defined in the animation program)
  • "track": the index of the track the animation is playing on (default is 0)
  • "integer": an integer value associated with the event (as defined in the animation program, default is 0)
  • "float": a float value associated with the event (as defined in the animation program, default is 0.0)
  • "string": a string value associated with the event (as defined in the animation program, default is an empty string "")

Paths can be an important part of making any game, whether it is for a tower defence type game, or a shoot-em-up or whatever, and it's often really important that an instance does some particular action when it reaches the end of its path. This event detects this and is triggered when it happens allowing you to add in code or actions to deal with the circumstances, for example in a tower defence game you would use this to destroy the instance and remove a health point from the goal object.

These are special events that are not triggered by GameMaker Studio 2 itself, but have to be implicitly called by you from a code box while the game is running. These events can contain code or actions and do the same things as any other event, making them very useful for creating your own events that happen when you decide.

This event is the one that governs what you see on the screen when you run your game, and is split into various separate "sub-events": Object Editor Draw Events

As you can see, the draw event category has multiple different event types. Draw Begin, Draw and Draw End are the "standard" draw events which you will probably use most. By default the main Draw event is always called for every instance, regardless of whether it has a sprite or not, although if you flag the instance as invisible, the event will not be triggered (so keep this in mind if you have any game logic in the draw event of an invisible object, as it won't run). The main draw event is also where GameMaker Studio 2 default draws the instance sprite when there is no code nor actions in the event (ie: you haven't added it into the event list for the object). Default drawing uses the sprite associated with the instance and will draw that with any transforms set in code or actions applied.

The standard draw events draw before the Draw GUI events and between the Pre Draw and Post Draw events, meaning that everything that is drawn in this event is drawn beneath that of the Draw GUI event, regardless of the layer (ie: anything drawn in the Draw GUI event will always be drawn over anything drawn in the normal draw event, regardless of layer order).

Note that the above is simply an overview of how the Draw Events work, but for full details on all the available sub-events, please see the following section:

  1. Draw Events List

This event is special in that it is not triggered by default by GameMaker Studio 2, but rather by the end of some other action, like the loading of a file, or the reply from a web server. The actual event is split into various sub-events: Object Editor Asynchronous Events

So, say you want to add an image file to GameMaker Studio 2. Well, you would code this in another event (maybe the Create Event) of an object and then have that object draw a loading bar while waiting, polling the appropriate asynchronous event until the callback that tells GameMaker Studio 2 the file has loaded. You can then use the data returned in this event to do other things, like change room, or purchase an item.

Note that the above is simply an overview of how the Asynchronous Event works, but for full details on all the available sub-events, please see the following section:

  1. Asynchronous Events List

It is worth noting that you can name events, or at least give them a short descriptive text that will be shown beside them in the Event Editor. To do this, simply add the following into the very first line of the code editor for the event:

/// @description Your text here

So, you could have something like this in - for example - an Alarm event

/// @description This is the AI Fight alarm

And now in your Event Editor you'll see this: Object Editor Named Events

Event Order

When considering Events in GameMaker Studio 2, it should be noted that the exact order that the events are going to occur in each step cannot be clearly stated, simply because it depends on the internal workings of GameMaker Studio 2 and this is subject to change as the software develops. However there are certain events that will always run in the same order. The first set of events that will always happen the same way are those that occur when a room is first entered. The order that the different events will fire is:

It is also worth noting that you can also set the order in which specific instances are created within the room editor itself by moving them up or down the list of the Instance Layer Properties window.

Other than those specific events, the only known order that will always occur in the same way no matter what belongs to the three step events and the different draw events. These will always remain consistent, so if you have code that relies on specific timing during each step of your game, you should use:

All of the sub events for drawing are also always dealt with in the same order as follows (except for the Resize event, which is triggered differently):