Documentation:Using Game Maker/Actions

Actions indicate the things that happen in a game created with Game Maker. Actions are placed in events of objects. Whenever the event takes place these actions are performed, resulting in certain behavior for the instances of the object. There are a large number of different actions available and it is important that you understand what they do. In this chapter we describe the actions available in simple mode. Note that a number of these actions are only available in the Pro Edition of Game Maker. This will be indicated.

All the actions are found in the tabbed pages at the right of the object property form. There are six sets of actions. You select the set you want by clicking on the correct tab. When you hold you mouse above one of the actions, a short description is shown to remind you of its function.

Let us briefly repeat: To put an action in an event, just drag it from the tabbed pages to the action list. You can change the order in the list, again using dragging. Holding the  key while dragging makes a copy of the action. (You can drag and copy actions between the lists in different object property forms.) Use the right mouse button and select the correct menu item to remove actions (or use the  key) and to copy and paste selected actions.

When you drop an action in the action list, a window will pop-up most of the time, in which you can fill in certain parameters for the action. The parameters will be described below when describing the actions. Two types of parameters appear in many actions so we will describe these here. At the top you can indicate to which instance the action applies. The default is, which is the instance for which the action is performed. Most of the time, this is what you want. In the case of a collision event, you can also specify to apply the action to the other instance involved in the collision. For instance, in this way you can destroy the other instance. Finally, you can choose to apply the action to all instances of a particular object. In this way you could change all red balls into blue balls. The second type of parameter is the box labeled Relative. By checking this box, the values you type in are relative to the current values. For example, in this way you can add something to the current score, rather than changing the current score to the new value. The other parameters will be described below. You can later change the parameters by double clicking on the action.

Move actions
The first set of actions consists of those related to movement of objects. The following actions exist:

Move Fixed
Use this action to start the instance moving in a particular direction. You can indicate the direction using the buttons with the arrows on it. Use the middle button to stop the motion. Also you need to specify the speed of the motion. This speed is given in pixels per step. Preferably don't use negative speeds. You can specify multiple directions. In this case a random choice is made. In this way you can let a monster start moving either left or right.

Move Free
This is the second way to specify a motion. Here you can indicate a precise direction. This is an angle between 0 and 360 degrees. 0 means to the right. The direction is counter-clockwise. So for example 90 indicates an upward direction. If you want an arbitrary direction, you can type. As you will see below the function random gives a random number smaller than the indicated value. As you might have noticed there is a checkbox labeled Relative. If you check this, the new motion is added to the previous one. For example, if the instance is moving upwards and you add some motion to the left, the new motion will be upwards to the left.

Move Towards
This action gives a third way to specify a motion. You indicate a position and a speed and the instance starts moving with the speed towards the position. (It won't stop at the position!) For example, if you want a bullet to fly towards the position of the spaceship you can use as position,. (You will learn more about the use of variables like these below.) If you check the Relative box, you specify the position relative to the current position of the instance. (The speed is not taken relatively!)

Speed Horizontal
The speed of an instance consists of a horizontal part and a vertical part. With this action you can change the horizontal speed. A positive horizontal speed means a motion to the right. A negative one means a motion to the left. The vertical speed will remain the same. Use relative to increase the horizontal speed (or decrease it by providing a negative number).

Speed Vertical
In a similar way, with this action you can change the vertical speed of the instance.

Set Gravity
With this action you can create gravity for this particular object. You specify a direction (angle between 0 and 360 degrees) and a speed, and in each step this amount of speed in the given direction is added to the current motion of the object instance. Normally you need a very small speed increment (like 0.01). Typically you want a downward direction (270 degrees). If you check the Relative box you increase the gravity speed and direction. Note that, contrary to real life, different object can have different gravity directions.

Reverse Horizontal
With this action you reverse the horizontal motion of the instance. This can for example be used when the object collides with a vertical wall.

Reverse Vertical
With this action you reverse the vertical motion of the instance. This can for example be used when the object collides with a horizontal wall.

Set Friction
Friction slows down the instances when they move. You specify the amount of friction. In each step this amount is subtracted from the speed until the speed becomes 0. Normally you want a very small number here (like 0.01).

Jump to Position
Using this action you can place the instance in a particular position. You simply specify the x- and y-coordinate, and the instance is placed with its reference point on that position. If you check the Relative box, the position is relative to the current position of the instance. This action is often used to continuously move an instance. In each step we increment the position a bit.

Jump to Start
This action places the instance back at the position where it was created.

Jump to Random
This action moves the instance to a random position in the room. Only positions are chosen where the instance does not intersect any solid instance. You can specify the snapping used. If you specify positive values, the coordinates chosen with be integer multiples of the indicated values. This could for example be used to keep the instance aligned with the cells in your game (if any). You can specify a separate horizontal snapping and vertical snapping.

Align to Grid
With this action you can round the position of the instance to a grid. You can indicate both the horizontal and vertical snapping value (that is, the size of the cells of the grid). This can be very useful to make sure that instances stay on a grid.

Wrap Screen
With this action you can let an instance wrap around, that is, when it leaves on one side of the room it reappears at the other side. This action is normally used in the Outside event. Note that the instance must have a speed for wrapping to work, cause the direction of wrapping is based on the direction of the motion. You can indicate whether to wrap only horizontal, only vertical, or in both directions.

Move to Contact
With this action you can move the instance in a given direction until a contact position with an object is reached. If there already is a collision at the current position the instance is not moved. Otherwise, the instance is placed just before a collision occurs. You can specify the direction but also a maximal distance to move. For example, when the instance is falling you can move a maximal distance down until an object is encountered. You can also indicate whether to consider solid object only or all objects. You typically put this action in the collision event to make sure that the instance stops in contact with the other instance involved in the collision.

Bounce
When you put this action in the collision event with some object, the instance bounces back from this object in a natural way. If you set the parameter precise to false, only horizontal and vertical walls are treated correctly. When you set precise to true also slanted (and even curved) walls are treated correctly. This is though slower. Also you can indicate whether to bounce only against solid objects or against all objects. Please realize that the bounce is not completely accurate because this depends on many properties. But in many situations the effect is good enough.

Main actions, set 1
The following set of actions deals with creating, changing, and destroying instances of objects, with sounds, and with rooms.

Create Instance
With this action you can create an instance of an object. You specify which object to create and the position for the new instance. If you check the Relative box, the position is relative to the position of the current instance. Creating instances during the game is extremely useful. A space ship can create bullets; a bomb can create an explosion, etc. In many games you will have some controller object that from time to time creates monsters or other objects. For the newly created instance the creation event is executed.

Create Moving
This action works the same as the action above but with two additional fields. You can now also specify the speed and direction of the newly created instance. Note that if you check the Relative box, only the position is relative, not the speed and direction. For example, to make a bullet move in the direction of the person shooting you have to use a little trick. As position use 0,0 and check Relative. As direction we need the current direction of the instance. This can be obtained by typing in the word. (This actually is a variable that always indicates the current direction in which the instance is moving.)

Create Random
This action lets you create an instance of one out of four objects. You specify the four objects and the position. An instance of one of these four objects is created at the given position. If you check the Relative box, the position is relative to the position of the current instance. If you need a choice out of less than four objects you can use No Object for some of them. This is for example useful to generate a random enemy at a location.

Change Instance
With this action you can change the current instance into an instance of another object. So for example, you can change an instance of a bomb into an explosion. All settings, such as the motion and the value of variables, will stay the same. You can indicate whether or not to perform the destroy event for the current object and the creation event for the new object.

Destroy Instance
With this action you destroy the current instance. The destroy event for the instance is executed.

Destroy at Position
With this action you destroy all instances whose bounding box contains a given position. This is useful, for example, when you use an exploding bomb. When you check the Relative box the position is taken relative to the position of the current instance.

Change Sprite
Use this action to change the sprite for the instance. You indicate which new sprite. You can also indicate with subimage must be shown. Normally you would use 0 for this (the first subimage) unless you want to see a particular subimage. Use -1 if you do not want to change the current subimage shown. Finally you change the speed of the animation of the subimages. If you only want to see a particular subimage, set the speed to 0. If the speed is larger than one subimages will be skipped. If it is smaller than 1 subimages will be shown multiple times. Don't use a negative speed. Changing sprites is an important feature. For example, often you want to change the sprite of a character depending on the direction in which it walks. This can be achieved by making different sprites for each of the (four) directions. Within the keyboard events for the arrow keys you set the direction of motion and the sprite.

Transform Sprite
Use this action to change the size and orientation of the sprite for the instance. Use the scale factors to make it larger or smaller. The angle gives the counter-clockwise orientation of the sprite. For example, to make the sprite oriented in the direction of motion use as a value. For example, this is useful for a car. You can also indicate whether the sprite should be mirrored horizontally and/or flipped vertically. This action is only available in the Pro Edition.

Color Sprite
Normally the sprite is drawn as it is defined. Using this action you can change the color of the sprite. This color is blended with the sprite, that is, it is combined with the colors of the sprite. If you want to draw a sprite in different colors you better define the sprite in black and white and use the blend color to set the actual color. You can also indicate an alpha transparency. With a value of 1 the sprite is opaque. With a value of 0 it is completely transparent. With a value in between you will partially see the background shine through it. This is great for making explosions. This action is only available in the Pro Edition.

Play Sound
With this action you play one of the sound resources you added to your game. You can select the sound you want to play and choose whether it should play only once (the default) or loop continuously. Multiple wave sounds can play at once but only one midi sound can play at a time. So if you start a midi sound, the current midi sound is stopped.

Stop Sound
This action stops the indicated sound. If multiple instances of this sound are playing all are stopped.

Check Sound
If the indicated sound is playing the next action is performed. Otherwise it is skipped. You can select Not to indicate that the next action should be performed if the indicated sound is not playing. For example, you can check whether some background music is playing and, if not, start some new background music. Note that this action returns true when the sound actually plays through the speakers. After you call the action to play a sound it does not immediately reach the speakers so the action might still return false for a while. Similar, when the sound is stopped you still hear it for a while (e.g. because of echo) and the action will still return true.

Previous Room
Move to the previous room. You can indicate the type of transition effect between the rooms. You should experiment to see what works best for you. When the rooms do not have the same size you better do not use transitions. If you are in the first room you get an error.

Next Room
Move to the next room. You can indicate the transition.

Restart Room
The current room is restarted. You indicate the transition effect.

Different Room
With this action you can go to a particular room. You indicate the room and the transition effect.

Check Previous
This action tests whether the previous room exists. If so, the next action is executed. You normally need this test before moving to the previous room.

Check Next
This action tests whether the next room exists. If so, the next action is executed. You normally need this test before moving to the next room.

Main actions, set 2
Here are some more main actions, dealing with timing, giving messages to the user, and dealing with the game as a whole.

Set Alarm
With this action you can set one of the twelve alarm clocks for the instance. You select the number of steps and the alarm clock. After the indicated number of steps, the instance will receive the corresponding alarm event. You can also increase or decrease the value by checking the Relative box. If you set the alarm clock to a value less than or equal to 0 you switch it off, so the event is not generated.

Sleep
With this action you can freeze the scene for a particular time. This is typically used at the beginning or end of a level or when you give the player some message. You specify the number of milliseconds to sleep. Also you can indicate whether the screen should first be redrawn to reflect the most recent situation.

Display Message
With this action you can display a message in a dialog box. You simply type in the message. If you use a # symbol in the message text it will be interpreted as a new line character. (Use \# to get the # symbol itself.) If the message text starts with a quote or double quote symbol, it is interpreted as an expression. See below for more information about expressions.

Show Info
With this action you pop up the game information window.

Restart Game
With this action you restart the game from the beginning.

End Game
With this action you end the game.

Save Game
With this action you can save the current game status. You specify the filename for saving (the file is created in the working directory for the game). Later the game can be loaded with the next action. (Please realize that only the basic game status is save. Things that are for example not saved are the current sound that is playing, and advanced aspects like the contents of data structures, particles, etc.)

Load Game
Load the game status from a file. You specify the file name. Make sure the saved game is for the same game and created with the same version of Game Maker. Otherwise an error will occur. (To be precise, the game is loaded at the end of the current step. So some actions after this one are still executed in the current game, not the loaded one!)

Control actions
There are a number of actions with which you can control which other actions are performed. Most of these actions ask a question, for example whether a position is empty. When the answer is yes (true) the next action is executed, otherwise it is skipped. If you want multiple actions to be executed or skipped based on the outcome you can put them in a block by putting start block and end block actions around them. There can also be an else part which is executed when the answer is no. So a question typically looks as follows:



Here the question is asked whether a position for the current instance is collision free. If so, the instance starts moving in a given direction. If not, the instance jumps to a given position. Note that the blocks are indented. This gives a better overview of the actions. (In particular when you use blocks inside blocks.) Also it is easier to detect when you forgot a start block or end block action.

For all questions there is a field labeled NOT. If you check this field, the result of the question is reversed. That is, if the result was true it becomes false and if it was false, it becomes true. This allows you to perform certain actions when a question is not true.

For many questions you can indicate that they should apply to all instances of a particular object. In this case the result is true only if it is true for all instances of the object. For example, you can check whether for all balls the position slightly to the right is collision free.

The following questions and related actions are available. (Note that they all have a differently shaped icon and a different background color so that they can more easily be distinguished from other actions.)

Check Empty
This question returns true if the current instance, placed at the indicated position does not generate a collision with an object. You can specify the position as either absolute or relative. You can also indicate whether only solid, or all objects, should be taken into account. This action is typically used to check whether the instance can move to a particular position.

Check Collision
This is the reverse of the previous action. It returns true if there is a collision when the current instance is placed at the given position (again, either only with solid objects or with all objects).

Check Object
This question returns true if the instance placed at the indicate position meets an instance of the indicated object.

Test Instance Count
You specify an object and a number. If the current number of instances of the object is equal to the number the question returns true. Otherwise it returns false. You can also indicate that the check should be whether the number of instances is smaller than the given value or larger than the given value. This is typically used to check whether all instances of a particular type are gone. This is often the moment to end a level or a game.

Test Chance
You specify the number of sides of a dice which is then thrown. Then if the dice lands on one, the result is true and the next action is performed. This can be used to put an element of randomness in your game. For example, in each step you can generate with a particular chance a bomb or a change of direction. The larger the number of sides of the dice, the smaller the chance. You can actually use real numbers. For example if you set the number of sides to 1.5 the next action is performed two out of three times. Using a number smaller than 1 makes no sense.

Check Question
You specify a question. A dialog is shown to the player with a yes and a no button. The result is true is the player answers yes.

Test Expression
This is the most general question action. You can enter an arbitrary expression. If the expression evaluates to true (that is, a number larger or equal to 0.5) the next action is performed. See below for more information on expressions.

Check Mouse
Returns true if the indicated mouse button is pressed. A standard use is in the step event. You can check whether a mouse button is pressed and, if so, for example move to that position (use the jump to a point action with values  and  ).

Check Grid
Returns true if the position of the instance lies on a grid. You specify the horizontal and vertical spacing of the grid. This is very useful when certain actions, like making a turn, are only a llowed when the instance is on a grid position.

Start Block
Indicates the start of a block of actions.

End Block
Indicates the end of a block of actions.

Else
Behind this action the else part follows, that is executed when the result of the question is false.

Repeat
This action is used to repeat the next action (or block of actions) a number of times. You simply indicate the number.

Exit Event
When this action is encountered no further actions in this event are executed. This is typically used after a question. For example, when a position is free nothing needs to be done so we exit the event. In this example, the following actions are only executed when there is a collision.

If you want more control over what is happening in the game you can use the built-in programming language that is described in Part 4 of the documentation. If gives you much more flexibility than using the actions. There are also actions to define and test variables. They are simpler to use than code and can be very useful for your games. The following actions deal with this.

Execute Code
When you add this action, a form shows in which you can type a piece of code which must be execute. This can contain simple function calls or more complex code. Use the code action preferably only for small pieces of code. For longer pieces you are strongly advised to use scripts which are described in Part 2 of the documentation.

Comment
Use this action to add a line of comment to the action list. The line is shown in italic font. Adding comments helps you remember what your events are doing. The action does not do anything. But realize that it still is an action. So when you place it after a conditional action it is the action that is executed if the condition is true (even though it does not do anything).

Set Variable
There are many built-in variables in the game. With this action you can change these. Also you can create your own variables and assign values to them. You specify the name of the variable and the new value. When you check the Relative box, the value is added to the current value of the variable. Please note that this can only be done if the variable already has a value assigned to it! See below for more information about variables.

Test Variable
With this action you can check what the value of a particular variable is. If the value of the variable is equal to the number provided, the question returns true. Otherwise it returns false. You can also indicate that the check should be whether the value is smaller than the given value or larger than the given value. See below for more information about variables. Actually, you can use this action also to compare two expressions.

Draw Variable
With this action you can draw the value of a variable at a particular position on the screen. Note that this can only be used in the draw event of an object.

Score Actions
In most games the player will have a certain score. Also many games give the player a number of lives. Finally, often the player has a certain health. The following actions make it easy to deal with the score, lives, and health of the player.

Set Score
Game Maker has a built-in score mechanism. The score is normally displayed in the window caption. You can use this action to change the score. You simply provide the new value for the score. Often you want to add something to the score. In this case don't forget the check the Relative box.

Test Score
With this question action you can check whether the score has reached a particular value. You indicate the value and whether the score should be equal to that value, be smaller than the value or be larger than the value.

Draw Score
With this action you can draw the value of the score at a particular position on the screen. You provide the positions and the caption that must be placed in front of the score. The score is drawn in the current font. This action can only be used in the drawing event of an object.

Show Highscore
For each game the top ten scores are maintained. This action displays the highscore list. If the current score is among the top ten, the new score is inserted and the player can type his or her name. You can indicate what background image to use, whether the window should have a border, what the color for the new entry and the other entries must be, and which font to use.

Clear Highscore
This action clears the highscore table.

Set Lives
Game Maker also has a built-in lives system. With this action you can change the number of lives left. Normally you set it to some value like 3 at the beginning of the game and then decrease or increase the number depending on what happens. Don't forget to check the Relative box if you want to add or subtract from the number of lives. At the moment the number of lives becomes 0 (or smaller than 0) a "no more lives" event is generated.

Test Lives
With this question action you can check whether the number of lives has reached a particular value. You indicate the value and whether the number of lives should be equal to that value, be smaller than the value or be larger than the value.

Draw Lives
With this action you can draw the number of lives at a particular position on the screen. You provide the positions and the caption that must be placed in front of the number of lives. The number of lives is drawn in the current font. This action can only be used in the drawing event of an object.

Draw Life Images
Rather than drawing the number of lives left as a number, it is often nicer to use a number of small images for this. This action does precisely that. You specify the position and the image and at the indicated position the number of lives is drawn as images. This action can only be used in the drawing event of an object.

Set Health
Game Maker has a built-in health mechanism. You can use this action to change the health. A value of 100 is considered full health and 0 is no health at all. You simply provide the new value for the health. Often you want to subtract something from the health. In this case don't forget the check the Relative box. When the health becomes smaller or equal to 0 an out of health event is generated.

Test Health
With this question action you can check whether the health has reached a particular value. You indicate the value and whether the health should be equal to that value, be smaller than the value or be larger than the value.

Draw Health
With this action you can draw the health in the form of a health bar. When the health is 100 the full bar is drawn. When it is 0 the bar is empty. You indicate the position and size of the health bar and the color of the bar and the background.

Score Caption
Normally in the window caption the name of the room and the score is displayed. With this action you can change this. You can indicate whether or not to show the score, lives, and/or health and what the caption for each of these must be.

Draw actions
Normally in each step of the game, for each instance, its sprite is drawn in the room. You can change this by putting actions in the draw event. (Note that these are only executed when the instance is visible!) The following drawing actions are available. These actions only make sense in the drawing event. At other places they are basically ignored.

Draw Sprite
You specify the sprite, the position (either absolute or relative to the current instance position) and the subimage of the sprite. (The subimages are numbered from 0 upwards.) If you want to draw the current subimage, use number -1.

Draw Background
You indicate the background image, the position (absolute or relative) and whether the image should be tiled all over the room or not.

Draw Text
You specify the text and the position. A # symbol in the text is interpreted as going to a new line. (Use \# to get the # symbol itself.) So you can create multi-line texts. If the text starts with a quote or a double quote, it is interpreted as an expression. For example, you can use to display the value of the x-coordinate of the instance. (The variable x stores the current x-coordinate. The function string turns this number into a string. + concatenates the two strings.)

Draw Scaled Text
This action is similar to the previous action but this time you can also specify a horizontal and vertical scaling factor to change the size of the text and you can specify an angle to rotate it. This action is only available in the Pro Edition.

Draw Rectangle
You specify the coordinates of the two opposite corners of the rectangle; either absolute or relative to the current instance position.

Horizontal Gradient
This action also draws a rectangle but this time using a gradient color that changes from left to right. You specify the rectangle and the two colors to use. This action is only available in the Pro Edition.

Vertical Gradient
This action also draws a rectangle but this time using a gradient color that changes from top to bottom. You specify the rectangle and the two colors to use. This action is only available in the Pro Edition.

Draw Ellipse
This action draws an ellipse. You specify the coordinates of the two opposite corners of the surrounding rectangle; either absolute or relative to the current instance position.

Gradient Ellipse
Again an ellipse is drawn but this time you specify a color for the center and the boundary. This action is only available in the Pro Edition.

Draw Line
You specify the coordinates of the two endpoints of the line; either absolute or relative to the current instance position.

Draw Arrow
Draws an arrow. You specify the coordinates of the two endpoints of the line and the size of the arrow tip.

Set Color
Lets you set the color used for drawing shapes, lines, and text. (It does not influence the way sprites and backgrounds are drawn.)

Set Full Screen
With this action you can change the screen mode from windowed to fullscreen and back. You can indicate whether to toggle the mode or whether to go to windowed or fullscreen mode.

Take Snapshot
With this action you can take a snapshot image of the game and store it in a .png file. You specify the filename to store the image in. This action is only available in the Pro Edition.

Create Effect
With this action you can create all sorts of effects in a very simple way. You specify the type of effect, e.g. an explosion or smoke, its position, its size and its color and whether it should be shown below the objects or on top of them. For the rest it works automatic. (For rain and snow the position is irrelevant as it always falls down from the top of the screen. To get continuous rain you should create it in each step.) Please note that below actually means at a depth of 100000 and above means at a depth of -100000. This action is only available in the Pro Edition.

Using expressions and variables
In many actions you need to provide values for parameters. Rather than just typing a number, you can also type a formula, e.g. 32*12. But you can actually type much more complicated expressions. For example, if you want to double the horizontal speed, you could set it to. Here  is a variable indicating the current horizontal speed of the instance. There are a large number of other variables that you can use. Some of the most important ones are:
 * x the x-coordinate of the instance
 * y the y-coordinate of the instance
 * hspeed the horizontal speed (in pixels per step)
 * vspeed the vertical speed (in pixels per step)
 * direction the current direction of motion in degrees (0-360)
 * speed the current speed in this direction
 * visible whether the object is visible (1) or invisible (0)
 * image_index this variable indicate which subimage in the current sprite is currently shown. If you change it and set the speed to 0 (see below) you can display a fixed subimage.
 * image_speed this variable indicates the speed with which the subimages are shown. The default value is 1. If you make this value larger than 1 some subimages are skipped to make the animation faster. If you make it smaller than 1 the animation becomes slower by repeating subimages.
 * score the current value of the score
 * lives the current number of lives health the current health (0-100)
 * mouse_x x-position of the mouse
 * mouse_y y-position of the mouse

You can change most of these variables using the set variable action. You can also define your own variables by setting them to a value. (Don't use relative, because they don't exist yet.) Then you can use these variables in expressions. Variables you create are local to the current instance. That is, each object has its own copy of them. To create a global variable, put the word global and a dot in front of it.

You can also refer to the values of variables for other objects by putting the object name and a dot in front of them. So for example, if you want a ball to move to the place where the coin is you can set the position to. In the case of a collision event you can refer to the x-coordinate of the other object as. In conditional expressions you can use comparisons like < (smaller than), >, etc.

In your expressions you can also use functions. For example, the function  gives a random integer number below 10. So you can set for example the speed or direction of motion to a random value. Many more functions exist. They are described in Part 4 of the documentation.