Using Game Maker

Game Maker is an easy to use program for creating your own computer games. This section of the help file gives you all the information you need for creating your first games. Later section will discuss more advanced topics, how to finish and distribute your game, and the built-in programming language GML.

Information on the basic use of Game Maker can be found in the following pages:

Introduction
Installation
Registration
The global idea
A simple example
The global user interface
Defining sprites
Sounds and music
Backgrounds
Defining objects
Events
Actions
Creating rooms
Distributing your game


Introduction

So you want to create your own computer games

Playing computer games is fun. But it is actually more fun to design your own computer games and let other people play them. Unfortunately, creating computer games is not easy. Commercial computer games as you buy nowadays typically take one to three years of development with teams of anywhere between 10 and 50 people. Budgets easily reach in the millions of dollars. And all these people are highly experienced: programmers, art designers, sound technicians, etc.

So does this mean that it is impossible to create your own computer games? Fortunately not. Of course you should not expect that you could create your own Quake or Age of Empires within a few weeks. But that is also not necessary. A bit simpler games, like Tetris, Pacman, Space Invaders, etc. are also fun to play and a lot easier to create. Unfortunately they still require good programming skills to handle the graphics, sounds, user interaction, etc.

But here comes Game Maker. Game Maker has been written to make it a lot easier to create such games. There is no need to program. An intuitive and easy to use drag-and-drop interface allows you to create your own games very quickly. You can import and create images, sprites (animated images) and sounds and use them. You easily define the objects in your game and indicate their behavior. And you can define appealing rooms with scrolling backgrounds in which the game take place. And if you want full control there is actually an easy-to-use programming language built into Game Maker that gives you full control over what is happening in your game.

Game Maker focuses on two-dimensional games. So no 3D worlds like Quake. But don’t let this put you down. Many great games, like Age of Empires, the Command & Conquer series, and Diablo use two-dimensional sprite technology, even though they look very 3-dimensional. And designing two-dimensional games is a lot easier and faster.

Game Maker can be used free of charge. And you can freely distribute the games you create with it; you can even sell them if you like. See the enclosed license agreement for more details. You are though strongly encouraged to register your copy of Game Maker. This will support the further development of Game Maker. It will also unlock a number of advanced features in Game Maker and it will remove the small logo when running games.

This document will tell you all you need to know about Game Maker and how you can create your own games with it. Please realize that, even with a program like Game Maker, designing computer games is not completely trivial. There are too many aspects that are important: game play, graphics, sounds, user interaction, etc. Start with easy examples and you will realize that creating games is great fun. Also check the web site

http://www.gamemaker.nl/

and the forum there, for lots of examples, tutorials, ideas, and help. And soon you will become a master game maker yourself. Enjoy.


Installation

You probably already did this but if not, here is how to install Game Maker. Simply run the program gmaker.exe. Follow the on-screen instructions. You can install the program anywhere you like but you best follow the default suggestions given. Once installation is completed, in the Start menu you will find a new program group where you can start Game Maker and read the documentation. Besides the Game Maker program also the documentation is installed, together with the help file.

The first time you run Game Maker you are asked whether you want to run the program in Simple or Advanced mode. If you have not used a game creation program before and you are not an experienced programmer, you better use simple mode (so select No). In simple mode fewer options are shown. You can easily switch to advanced mode letter using the appropriate item in the File menu.

Within the installation folder (default C:/Program Files/Game_Maker5/) there will be a number of other folders:

  • examples: contains a number of example games, for you to check and/or change.
  • lib: contains a number of libraries of actions. If you want to install additional action libraries you must put them in this folder.
  • sprites: this folder is meant to contain sprites you can use. The default installation does install just a few sprites but from the Game Maker website (http://www.gamemaker.nl/) you can load a number of resource packs that contain additional sprites, sounds, backgrounds, etc.
  • backgrounds, sounds: similar folders that are meant to contain the background images and sounds.
Game Maker requires a modern Pentium PC running Windows 98, NT, 2000, Me, XP, or later. It requires a screen resolution of at least 800x600 and 65000 (16-bit) colors. It requires DirectX to be installed on your computer. When designing and testing games, the memory requirements are pretty high (at least 32 MB and preferably more). When just running games, the memory requirements are a lot less severe and depend a lot on the type of game.


Registration

Game Maker can be used free of charge. The unregistered version though is a bit limited and shows a little logo when running a game. To unlock the advanced features, remove the logo, and support the further development of the software you are strongly recommended to register your copy of Game Maker. Registration will add the following features:
  • No Game Maker logo when running a game.
  • No reminder of registration in the maker.
  • Two additional collections of actions
  • The possibility to extend Game Maker using DLLs.
  • A particle system to create fireworks, flames, rain, and other effects.
  • The possibility to make multiplayer games that can be played over a network.
  • Functions to create and modify resources (sprites, backgrounds, etc.) while the game is running.
  • A number of advanced drawing functions.
  • A collection of functions to create and use data structures.
  • Functions for motion planning.
The registration fee for Game Maker is only 15 Euro or an equivalent amount in another currency, currently e.g. US $ 18. There are a number of ways in which you can register your copy of the program. The easiest way is to use online registration use a secure credit card payment system or a PayPal account. Alternatively you can transfer money to our bank account, send us a money order or send cash. Details can be found on the Game Maker registration web site:

http://www.gamemaker.nl/registration.html

To register your copy of Game Maker use the web site above or choose Registration from the Help menu. At the bottom of the form that appears click the button Registration. You will be brought to our web page were the different registration options are indicated, including the online registration.

Once your registration has been received an email will be send to you with the name and key and information how to enter the key in the program. To enter the key, again choose Registration from the Help menu. At the bottom of the form press the button Enter Key. Type the name and key and press OK. If you made no mistakes the program is registered.


The global idea

Before delving into the possibilities of Game Maker it is good to first get a feeling for the global idea behind the program. Games created with Game Maker take place in one or more rooms. (Rooms are flat, not 3D, but they can contain 3D-looking graphics.) In these rooms you place objects, which you can define in the program. Typical objects are the walls, moving balls, the main character, monsters, etc. Some objects, like walls, just sit there and don’t do anything. Other objects, like the main character, will move around and react to input from the player (keyboard, mouse, and joystick) and to each other. For example, when the main character meets a monster he might die. Objects are the most important ingredients of games made with Game Maker, so let us talk a bit more about them.

First of all, most objects need some image to make them visible on the screen. Such images are call sprites. A sprite is often not a single image but a set of images that are shown one after the other to create an animation. In this way it looks like the character walks, a ball rotates, a spaceship explodes, etc. During the game the sprite for a particular object can change. (So the character can look different when it walks to the left or to the right.) You can create you own sprite in Game Maker or load them from files (e.g. animated GIF’s).

Certain things will happen to objects. Such happenings are called events. Objects can take certain actions when events happen. There are a large number of different events that can take place and a large number of different actions that you can let your objects take. For example, there is a creation event when the object gets created. (To be more precise, when an instance of an object gets created; there can be multiple instances of the same object.) For example, when a ball object gets created you can give it some motion action such that is starts moving. When two objects meet you get a collision event. In such a case you can make the ball stop or reverse direction. You can also play a sound effect. To this end Game Maker lets you define sounds. When the player presses a key on the keyboard there is a keyboard event, and the object can take an appropriate action, like moving in the direction indicated. I hope you get the idea. For each object you design you can indicate actions for various events, in this way defining the behavior of the object.

Once you have defined your objects it is time to define the rooms in which they will live. Rooms can be used for levels in your game or to check out different places. There are actions to move from one room to another. Rooms first of all have a background. This can be a simple color or an image. Such background images can be created in Game Maker or you can load them from files. (The background can do a lot of things but for the time being, just consider it as something that makes the rooms look nice.) Next you can place the objects in the room. You can place multiple instances of the same object in a room. So, for example, you need to define just one wall object and can use it at many places. Also you can have multiple instances of the same monster objects, as long as they should have the same behavior.

Now you are ready to run the game. The first room will be shown and objects will come to life because of the actions in their creation events. They will start reacting to each other due to actions in collision events and they can react to the player using the actions in their keyboard or mouse events.

So in summary, the following things (often called resources) play a crucial role:
  • objects: which are the true entities in the game
  • rooms: the places (levels) in which the objects live
  • sprites: (animated) images that are used to represent the objects
  • sounds: these an be used in games, either as background music or as effects
  • backgrounds: the images used as background for the rooms
There are actually a number of other types of resources: paths, scripts, data files, and time lines. These are important for more complicated games. You will only see them when you run Game Maker in advanced mode. They will be treated in the advanced chapters later in this document.


A simple example

Let us look at an example

It is good to first have a look at how to make a very simple example. We assume here that you run Game Maker in simple mode. The first step is to describe the game we want to make. (You should always do this first; it will save you a lot of work later.) The game will be very simple: There is a ball that is bouncing around between some walls. The player should try to click on the ball with the mouse. Each time he succeeds he gets a point.

As can be seen we will require two different objects: the ball and the wall. We will also need two different sprites: one for the wall object and one for the ball object. Finally, we want to hear some sound when we succeed in clicking on the ball with the mouse. We will just use one room in which the game takes place. (If you don't want to make the game yourself you can load it from the Examples folder under the name touch the ball.gmd.)

Let us first make the sprites. From the Add menu select Add Sprite (you can also use the appropriate button on the toolbar). A form will open. In the Name field type “wall”. Select the Load Sprite button and choose an appropriate image. That is all and you can close the form. In the same way, create a ball sprite.

Next we make the sound. From the Add menu select Add Sound. A different form opens. Give the sound a name and choose Load Sound. Pick something appropriate and check whether it is indeed a nice sound by pressing the play button. If you are satisfied, close the form.

The next step is to create the two objects. Let us first make the wall object. Again from the Add menu choose Add Object. A form will open that looks quite a bit more complex than the ones we saw so far. At the left there is some global information about the object. Give the object an appropriate name and from the drop down menu pick the correct wall sprite. Because a wall is solid you should check the box labeled Solid. That is all for the moment. Again create a new object, name it ball, and give it the ball sprite. We don't make the ball solid. For the ball we need to define some behavior. In the middle you see an empty list of events. Below it there is a button labeled Add Event. Press it and you will see all possible events. Select the creation event. This is now added to the list of events. At the far right you see all the possible actions, in a number of groups. From the move group choose the action with the 8 red arrows and drag it to the action list in the middle. This action will make the object move in a particular direction. Once you drop it in the action list a dialog pops up in which you can indicate the direction of motion. Select all the 8 arrows to choose a random direction. You can leave the speed as 8. Now close the dialog. So now the ball will start moving at the moment it is created. Secondly we have to define what should happen in the case of a collision event with the wall. Again press Add Event. Click on the button for collision events and in the drop down menu select the wall object. For this event we need the bounce action. (You can see what each action does by holding the mouse still above it.) Finally we need to define what to do when the user presses the left mouse button on the ball. Add the corresponding event and select the left mouse button from the pop-up menu. For this event we need a few actions: one to play a sound (can be found in the group of main1 actions) and one to change the score (in the group score) and two more to move the ball to a new random position and moving in a new direction (in the same way as in the creation event). For the sound action, select the correct sound. For the score action, type in a value of 1 and check the Relative box. This means that 1 is added to the current score. (If you make a mistake you can double click the action to change its settings.)

Our objects are now ready. What remains is to define the room. Add a new room to the game, again from the Add menu. At the right you see the empty room. At the left you find some tabs, one for setting the background, one for setting some global properties like the width and height of the room, and one were you can add instances to the room. At the bottom you can select an object in the pop-up menu. By clicking in the room you can place instances of that object there. You can remove instances using the right mouse button. Create a nice boundary around the room using the wall object. Finally place 1 or 2 ball objects in the room. Our game is ready.

Now it is time to test our game. Press the Run button and see what happens. If you made no mistakes the ball starts moving around. Try clicking on it with the mouse and see what happens. You can stop the game by pressing the <Esc> key. You can now make further changes.

Congratulations. You made your first little game. But I think it is now time to learn a bit more about Game Maker.


The global user interface

When you start Game Maker the following form is shown:

(Actually, this is what you see when you run Game Maker in simple mode. In advanced mode a number of additional items are shown.) At the left you see the different resources, mention above: Sprites, Sounds, Backgrounds, Objects, Rooms and two more: Game Information and Game Options. At the top there is the well-known menu and toolbar. In this chapter I will describe briefly the various menu items, buttons, etc. In the later chapters we discuss a number of them in detail. Note that many things can be achieved in different ways: by choosing a command from the menu, by clicking a button, or by right clicking on a resource.

File menu

In the file menu you can find some of the usual commands to load and save files, plus a few special ones:
  • New. Choose this command to start creating a new game. If the current game was changed you are asked whether you want to save it. There is also a toolbar button for this.
  • Open. Opens a game file. Game Maker files have the extension .gmd. There is a toolbar button for this command. You can also open a game by dragging the file to the Game Maker window.
  • Recent Files. Use this submenu to reopen game files your recently opened.
  • Save. Saves the game design file under its current name. If no name was specified before, you are asked for a new name. You can only use this command when the file was changed. Again, there is a toolbar button for this.
  • Save As. Saves the game design file under a different name. You are asked for a new name.
  • Create Executable. Once your game is ready you probably want to give it to others to play. Using this command you can create a stand-alone version of your game. This is simply an executable that you can give to other people to run.
  • Advanced Mode. When clicking on this command Game Maker will switch between simple and advanced mode. In advanced mode additional commands and resources are available.
  • Exit. Probably obvious. Press this to exit Game Maker. If you changed the current game you will be asked whether you want to save it.

Edit menu

The edit menu contains a number of commands that relate to the currently selected resource (object, sprite, sound, etc.). Depending on the type of resource some of the commands might not be available.
  • Insert resource. Insert a new instance of the currently selected type of resource before the current one. A form will open in which you can change the properties of the resource. This will be treated in detail in the following chapters.
  • Duplicate. Makes a copy of the current resource and adds it. A form is opened in which you can change the resource.
  • Delete. Deletes the currently selected resource (or group of resources). Be careful. This cannot be undone. You will though be warned.
  • Rename. Give the resource a new name. This can also be done in the property form for the resource. Also you can select the resource and then click on the name.
  • Properties. Use this command to bring up the form to edit the properties. Note that all the property forms appear within the main form. You can edit many of them at the same time. You can also edit the properties by double clicking on the resource.
Note that all these commands can also be given in a different way. Right-click on a resource or resource group, and the appropriate pop-up menu will appear.

Add menu

In this menu you can add new resources of each of the different types. Note that for each of them there is also a button on the toolbar and a keyboard shortcut.

Run menu

This menu is used to run the game. There are two ways to run a game.
  • Run normally. Runs the game as it would normally run.
  • Run in Debug mode. Runs the game in debug mode. In this mode you can check certain aspects of the game and you can pause and step through it. This is useful when something goes wrong but is a bit advanced.
Once your game is finished, you can create a stand-alone executable of the game using the command in the file menu.

Window menu

In this menu you find some of the usual commands to manage the different property windows in the main form:
  • Cascade. Cascade all the windows such that each of them is partially visible.
  • Arrange Icons. Arrange all the iconified property windows. (Useful in particular when resizing the main form.)
  • Close All. Close all the property windows, asking the user whether or not to save the changes made.

Help menu

Here you find some commands to help you:
  • Contents. Use this command to show this help file.
  • Registration. Even though Game Maker can be used for free, you are encouraged to register the program. It will unlock a number of additional features and will help the further development of the program. Here you can find information on how to register the program. If you did register it you can use this command to enter the registration key you receive.
  • Web site. Connects you to the Game Maker website where you can find information about the most recent version of Game Maker and collections of games and resources for Game Maker. I recommend that you check out the site at
  • Forum. Connects you to the Game Maker forum where many people will help you with your questions.
  • About Game Maker. Give some short information about this version of Game Maker.

The resource explorer

At the left of the main form you find the resource explorer. Here you will see a tree-like view of all resources in your game. It works in the same way as the windows explorer and you are most likely familiar with it. If an item has a + sign in front of it you can click on the sign to see the resources inside it. By clicking on the - sign these disappear again. You can change a name of a resource (except the top level ones) by selecting it (with a single click) and then clicking on the name. Double click on resource to edit its properties. Use the right mouse button to access the same commands as in the Edit menu.

You can change the order of the resources by clicking on them with the mouse and holding the mouse button pressed. Now you can drag the resource to the appropriate place. (Of course the place must be correct. You e.g. cannot drag a sound into the list of sprites.)


Defining sprites

Sprites are the visual representations of all the objects in the game. A sprite is either a single image, drawn with any drawing program you like, or a set of images that, when played one of the other, looks like an animated motion. For example, the following four images form a sprite for a Pacman moving to the right.

When you make a game you normally start by collecting a set of nice sprites for the objects in your game. Many collections of interesting sprites can be found on the Game Maker website. Other sprites can be found on the web, normally in the form of animated gif files.

To add a sprite, choose the item Add Sprite from the Add menu, or use the corresponding button on the toolbar. The following form will pop up.

At the top you can indicate the name of the sprite. All sprites (and all other resources) have a name. You best give each sprite a descriptive name. Make sure all resources get different names. Even though this is not strictly required, you are strongly advised to only use letters and digits and the underscore symbol (_) in a name of a sprite (and any other resource) and to let is start with a letter. In particular don't use the space character. This will become important once you start using code.

To load a sprite, click on the button Load Sprite. A standard file dialog opens in which you can indicate the sprite. Game Maker can load many different graphics files. When you load an animated gif, the different sub-images form the sprite images. Once the sprite is loaded the first sub-image is shown on the right. When there are multiple sub-images, you can cycle through them using the arrow buttons.

The checkbox labeled Transparent indicates whether the background should be considered as being transparent. Most sprites are transparent. The background is determined by the color of the leftmost bottommost pixel of the image. So make sure that no pixel of the actual image has this color. (Note that gif files often define their own transparency color. This color is not used in Game Maker.)

With the button Edit Sprite you can edit the sprite, or even create a completely new sprite.


Sound and music

Sounds and music

Most games have certain sound effects and some background music. Many useful sound effects can be found on the Game Maker website. Many more can be found on other places on the web.

To add a sound resource to your game, use the item Add Sound in the Add menu or use the corresponding button on the toolbar. The following form will pop up.

To load a sound, press the button labeled Load Sound. A file selector dialog pops up in which you can select the sound file. There are two types of sound files, wave files and midi files. Wave files are used for short sound effects. They use a lot of memory but play instantaneously. Use these for all the sound effects in your game. Midi files describe music in a different way. As a result they use a lot less memory, but they are limited to instrumental background music. Also, only one midi sound can play at any time.

Once you load a music file its kind and length are shown. You can listen to the sound using the play button. There is also a button Save Sound to save the current sound to a file. This button is not really required but you might need if you lost the original sound.


Backgrounds

The third type of basic resources is backgrounds. Backgrounds are usually large images that are used as backgrounds (or foregrounds) for the rooms in which the game takes place. Often background images are made in such a way that they can tile an area without visual cracks. In this way you can fill the background with some pattern. A number of such tiling backgrounds can be found on the Game Maker website. Many more can be found at other places on the web.

To add a background resource to your game, use the item Add Background in the Add menu or use the corresponding button on the toolbar. The following form will pop up.

Press the button Load Background to load a background image. Game Maker supports many image formats. Background images cannot be animated! The checkbox Transparent indicates whether or not the background is partially transparent. Most backgrounds are not transparent so the default is not. As transparency color the color of the leftmost bottommost pixel is used.

You can change the background or create a new one using the button Edit Background.


Defining objects

With the resources you have seen so far you can add some nice images and sounds to the game, but they don't do anything. We now come to the most important resource of Game Maker, the objects. Objects are entities in the game that do things. They most of the time have a sprite as a graphical representation such that you see them. They have behavior because they can react to certain events. All things you see in the game (except for the background) are objects. (Or to be more precise, they are instances of objects.) The characters, the monsters, the balls, the walls, etc. are all objects. There might also be certain objects that you don't see but that control certain aspects of the game play.

Please realize the difference between sprites and objects. Sprites are just (animated) images that don't have any behavior. Objects normally have a sprite to represent them but objects have behavior. Without objects there is no game!

Also realize the difference between objects and instances. An object described a certain entity, e.g. a monster. There can be multiple instances of this object in the game. When we talk about an instance we mean one particular instance of the object. When we talk about an object we mean all the instances of this object.

To add an object to your game, choose Add Object from the Add menu. The following form will appear:

This is rather complex. At the left there is some general information about the object. In the middle there is the list of events that can happen to the object. At the right there are the different actions the object can perform.

As always, you can (and should) give your object a name. Next you can indicate the sprite for the object. To this end, click with the left mouse button on the sprite box or the menu button next to it. A menu will pop-up with all the available sprites. Select the one you want to use for the object. If you do not have a sprite yet, you can click the button New to add a new sprite resource and change it. Also, when you select a resource there will be a button Edit here that you can use to change the sprite. This is faster than first finding the resource in the list of resources and then indicating you want to edit it.

Below this there are two check boxes. Visible indicates whether instances of this object are visible. Clearly, most objects are visible, but sometimes it is useful to have invisible objects. For example, you can use them for waypoints for a moving monster. Invisible objects will react to events and other instances do collide with them. The box labeled Solid indicates whether this is a solid object (like a wall). Collisions with solid objects are treated differently from collisions with non-solid objects.


Events

Game Maker uses what is called an event driven approach. This works as follows. Whenever something happens in the game the instances of the objects get events (kind of messages telling that something has happened). The instances can then react to these messages by executing certain actions. For each object you must indicate to which events it responds and what actions it must perform when the event occurs. This may sound complicated but is actually very easy. First of all, for most events the object does not have to do anything. For the events where something must be done you can use a very simple drag-and-drop approach to indicate the actions.

In the middle of the object property form there is a list of events to which the object must react. Initially it is empty. You can add events to it by pressing the button labeled Add Event. A form will appear will all different types of events. Here you select the event you want to add. Sometimes a menu pops up with extra choices. For example, for the keyboard event you must select the key. Below you find a complete list of the different events plus descriptions. One event in the list will be selected. This is the event we are currently changing. You can change the selected event by clicking on it. At the right there are all the actions represented by little icons. They are grouped in a number of tabbed pages. In the next chapter you will find descriptions of all the actions and what they do. Between the events and the actions there is the action list. This list contains the actions that must be performed for the current event. To add actions to the list, drag them with your mouse from the right to the list. They will be placed below each other, with a short description. For each action you will be asked to provide a few parameters. These will also be described in the next chapter. So after adding a few actions the situation will look as follows:

Now you can start adding actions to another event. Click on the correct event with the left mouse button to select it and drag actions in the list.

You can change the order of the actions in the list again using drag-and-drop. If you hold the <Ctrl> key while dragging, you make a copy of the action. You can even use drag-and-drop between action lists for different objects. When you click with the right mouse button on an action, a menu appears in which you can delete the action (can also be done by using the <Del> key) or copy and paste actions. When you hold your mouse at rest above an action, a longer description is given of the action. See the next chapter for more information on actions.

To delete the currently selected event together with all its actions press the button labeled Delete. (Events without any actions will automatically be deleted when you close the form so there is no need to delete them manually.) If you want to assign the actions to a different event (for example, because you decided to use a different key for them) press the button labeled Change and pick the new event you want. (The event should not be defined already!)

As indicated above, to add an event, press the button Add Event. The following form pops up:

Here you select the event you want to add. Sometimes a menu pops up with extra choices. Here is a description of the various events. (Again remember that you normally use only a few of them.)

Create event
This event happens when an instance of the object is created. It is normally used to set the instance in motion and/or to set certain variables for the instance.

Destroy event
This event happens when the instance is destroyed. To be precise, it happens just before it is destroyed, so the instance does still exist when the event is executed! Most of the time this event is not used but you can e.g. use it to change the score or to create some other object.

Alarm events
Each instance has 8 alarm clocks. You can set these alarm clocks using certain actions (see next chapter). The alarm clock then ticks down until it reaches 0 at which moment the alarm event is generated. To indicate the actions for a given alarm clock, you first need to select it in the menu. Alarm clocks are very useful. You can use them to let certain things happen from time to time. For example a monster can change its direction of motion every 20 steps. (In such cases one of the actions in the event must set the alarm clock again.)

Step events
The step event happens every step of the game. Here you can put actions that need 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. Be careful with this event though. Don't put many complicated actions in the step event of objects of which there are many instances. This might slow the game down. To be more precise, there are three different step events. Normally you only need the default one. But using the menu you can also select the begin step event and the end step event. The begin step event is executed at the beginning of each step, before any other events take place. The normal step event is executed just before the instances are put in their new positions. The end step event is executed at the end of the step, just before the drawing. This is typically used for e.g. changing the sprite depending on the current direction.

Collision events
Whenever two instances collide (that is, their sprites overlap) a collision event appears. Well, to be precise two collision event occur; one for each instance. The instance can react to this collision event. To this end, from the menu select the object with which you want to define the collision event. Next you place the actions here. There is a difference in what happens when the instance collides with a solid object or a non-solid object. First of all, when there are no actions in the collision event, nothing happens. The current instance simply keeps on moving; even when the other object is solid. When the collision event contains actions the following happens:

When the other object is solid, the instance is placed back at its previous place (before the collision occurs). Then the event is executed. Finally, the instance is moved to its new position. So if the event e.g. reverses the direction of motion, the instance bounces against the wall without stopping. If there is still a collision, the instance is kept at its previous place. So it effectively stops moving.

When the other object is not solid, the instance is not put back. The event is simply executed with the instance at its current position. Also, there is no second check for a collision. If you think about it, this is the logical thing that should happen. Because the object is not solid, we can simply move over it. The event notifies us that this is happening.

There are many uses for the collision event. Instances can use it to bounce against walls. You can use it to destroy object when they are e.g. hit by a bullet, etc.

Keyboard events
When the player presses a key, a keyboard event happens for all instances of all objects. There is a different event for each key. In the menu you can pick the key for which you want to define the keyboard event and next drag actions there. Clearly, only a few objects need events for only a few keys. You get an event in every step as long as the player keeps down the key. There are two special keyboard events. One is called <No key>. This event happens in each step when no key is pressed. The second one is called <Any key> and happens whenever some key is pressed. When the player presses multiple keys, the events for all the keys pressed happen. Note that the keys on the numeric keypad only produce the corresponding events when <NumLock> is pressed.

Mouse events
A mouse event happens for an instance whenever the mouse cursor lies inside the sprite representing the instance. Depending on which mouse buttons are pressed you get the no button, left button, right button, or middle button event. The mouse button events are generated in each step as long as the player keeps the mouse button pressed. The press events are only generated once when the button is pressed. The release events are only generated when the button is released. Note that these events only occur when the mouse is above the instance. If you want to react to mouse press or release events at an arbitrary place, use the global press and global release events instead. There are two special mouse events. The mouse enter event happens when the mouse enters the instance. The mouse leave event happens when the mouse leaves the instance. These events are typically used to change the image or play some sound. Finally there are a number of events related to the joystick. You can indicate actions for the four main directions of the joystick (in a diagonal direction both events happen). Also you can define actions for up to 8 joystick buttons. You can do this both for the primary joystick and the secondary joystick.

Other events
There are a number of other events that can be useful in certain games. They are found in this menu. The following events can be found here:
  • Outside: This event happens when the instance lies completely outside the room. This is typically a good moment to destroy it.
  • Boundary: This event happens when the instance intersects the boundary of the room.
  • Game start: This event happens for all instances in the first room when the game starts. It happens before the room start event (see below) but after the creation events for the instances in the room. This event is typically defined in only one "controller" object and is used to start some background music and to initialize some variables, or load some data.
  • Game end: The event happens to all instances when the game ends. Again typically just one object defines this event. It is for example used to store certain data in a file.
  • Room start: This event happens for all instances initially in a room when the room starts. It happens after the creation events.
  • Room end: This event happens to all existing instances when the room ends.
  • No more lives: Game Maker has a built-in lives system. There is an action to set and change the number of lives. Whenever the number of lives becomes less than or equal to 0, this event happens. It is typically used to end or restart the game.
  • No more health: Game Maker has a built-in health system. There is an action to set and change the health. Whenever the health becomes less than or equal to 0, this event happens. It is typically used to reduce the number of lives or to restart the game.
  • End of animation: As indicated above, an animation consists of a number of images that are shown one after the other. After the last one is shown we start again with the first one. The event happens at precisely that moment. This can be used to e.g. change the animation, or destroy the instance.
  • End of path: This event happens when the instance follows a path and the end of the path is reached.
  • User defined: There are eight of these events. They normally never happen unless you yourself call them from a piece of code.
Drawing event
Instances, when visible, draw their sprite in each step on the screen. When you specify actions in the drawing event, the sprite is not drawn, but these actions are executed instead. This can be used to draw something else than the sprite, or first make some changes to sprite parameters. There are a number of drawing actions that are especially meant for use in the drawing event. Note that the drawing event is only executed when the object is visible. Also note that, independent of what you draw, collision events are based on the sprite that is associated with the instance.

Key press events
This event is similar to the keyboard event but it happens only once when the key is pressed, rather than continuously. This is useful when you want an action to happen only once.

Key release events
This event is similar to the keyboard event but it happens only once when the key is released, rather than continuously.

In some situation it is important to understand the order in which Game Maker processes the events. This is as follows:
  • Begin step events
  • Alarm events
  • Keyboard, Key press, and Key release events
  • Mouse events
  • Normal step events
  • (now all instances are set to their new positions)
  • Collision events
  • End step events
  • Drawing events

The creation, destroy, and other event are performed when the corresponding things happen.


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 I will describe the default actions. Additional actions might become available in the form of action libraries. These extend the possibilities of Game Maker further. Check the website for possible additional action libraries.

All the actions are found in the tabbed pages at the right of the object property form. There are seven sets of actions. You get 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 me 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 <Ctrl> 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 to remove actions (or use the <Del> key) and to copy and paste 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 I will describe these here. At the top you can indicate to which instance the action applies. The default is self, 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. In this way you can e.g. destroy the other instance. Finally, you can choose to apply the action to all instances of a particular object. In this way you can e.g. 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:

Start moving in a direction
Use this action to start the instance moving in a particular direction. You can indicate the direction using the arrow keys. 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. The default value is 8. Preferably don't use negative speeds. You can specify multiple directions. In this case a random choice is made. In this way you can e.g. let a monster start moving either left or right.

Set direction and speed of motion
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 mean 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 random(360). 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 a bit of motion to the left, the new motion will be upwards to the left.

Set the horizontal speed
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).

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

Move towards a point
This action gives another 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 spaceship.x, spaceship.y. (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 relative!)

Set the 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.

Set the 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 a given 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 the start position
This action places the instance back at the position where it was created.

Jump to a random position
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 can be used to e.g. keep the instance aligned with the cells in your game (if any). You can specify a separate horizontal snapping and vertical snapping.

Snap 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 sized of the cells of the grid). This can be very useful to make sure that instances stay on a grid.

Reverse horizontal direction
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 direction
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.

Move to contact position
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 against objects
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 satisfactory. This is though slower. Also you can indicate whether to bounce only from solid objects or from all objects. Please realize that the bounce is not completely correct 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 an instance of an object
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 an instance of an object with a speed and direction
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. To e.g. 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 direction. (This actually is a variable that always indicates the current direction in which the instance is moving.)

Change the 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, like 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.

Change the sprite
Use this action to change the sprite for the instance. You indicate the new sprite. You can also indicate a scaling factor. A factor of 1 means that the sprite is not scaled. The scaling factor must be larger than 0. Please realize that scaling the sprite will slow down the drawing. 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.

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

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

Play a sound
With this action you play one of the sound resources you added to your game. You can indicate the sound you want to play and whether it should play once (the default) or loop continuously. Multiple wave sounds can play at once but only one midi sound can play. So if you start a midi sound, the current midi sound is stopped. Unless the sound has multiple buffers only one instance of each sound can play. So if the same sound is already playing it is stopped and restarted.

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

If a sound is playing
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.

Go to previous room
Move to the previous room. You can indicate the type of transition effect between the rooms. You best experiment to see what works nice for you. If you are in the first room you get an error.

Go to next room
Move to the next room. You can indicate the transition.

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

Go to a different room
With this action can go to a particular room. You indicate the room and the transition effect.

If previous room exists
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.

If next room exists
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 an alarm clock
With this action you can set one of the eight alarm clocks for the instance. You indicate 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 for a while
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.

Set a time line
(Only available in advanced mode.) With this action you set the particular time line for an instance of an object. You indicate the time line and the starting position within the time line (0 is the beginning). You can also use this action to end a time line by choosing No Time Line as value.

Set the time line position
(Only available in advanced mode.) With this action you can change the position in the current time line (either absolute or relative). This can be used to skip certain parts of the time line or to repeat certain parts. For example, if you want to make a looping time line, at the last moment, add this action to set the position back to 0. You can also use it to wait for something to happen. Just add the test action and, if not true, set the time line position relative to -1.

Display a 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. (Note that this action does not work when your game runs in exclusive mode.)

Show the game information
With this action you pop up the game information window. (This action does not work when your game runs in exclusive mode.)

Show a video
With this action you can show a video/movie file. You specify the file name and whether it should be shown full screen or in a window. Make sure the video file exists. You should either distribute it with the game or put it in a datafile and export it.

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

End the game
With this action you end the game.

Save the 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.

Load the 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

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.

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 such that they can more easily be distinguished from other actions.)

If a position is collision free
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 either absolute or relative. You can also indicate whether only solid objects should be taken into account or all objects should be taken into account. This action is typically used to check whether the instance can move to a particular position.

If there is a collision at a position
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).

If there is an object at a position
This question returns true if the instance placed at the indicate position meets an instance of the indicated object.

If the number of instances is a value
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.

If a dice lands on one
You specify the number of sides of the dice. 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 change direction. The larger the number of sides of the dice is, 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.

If the user answers yes to a 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. This action cannot be used in exclusive mode; the answer will then always be yes.

If an expression is true
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.

If a mouse button is pressed
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 mouse_x and mouse_y).

If instance is aligned with 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 allowed when the instance is on a grid position.

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

Start of block
Indicates the start of a block of actions.

End of block
Indicates the end of a block of actions.

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

Exit the current event
When this action is encountered no further action 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.

Drawing actions

Drawing actions only make sense in the drawing event. At other places they are basically ignored. Please remember that drawing things other than sprites and background images is relatively slow. So use this only when strictly necessary.

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

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

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

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

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

Draw a 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

'X: ' + string(x)

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. + combines the two strings.)

Set the colors
Lets you set the color used to fill the rectangles and ellipses and the color used for the lines around the rectangle and ellipse and when drawing a line.

Set a font for drawing text
You can set the font that is from this moment on used for drawing text.

Change fullscreen mode
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. (This does not work in exclusive mode.)

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 the 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.

If score has a value
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 the value of 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.

Clear the highscore table
This action clears the highscore table.

Display the highscore table
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. So you should not first add the score with the previous action. 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. (This action does not work in exclusive mode!)

Set the number of 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.

If lives is a value
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 the number of 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 the lives as image
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 the 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.

If health is a value
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 the health bar
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.

Set the window caption information
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.

Code related actions

Finally there are a number of actions that primarily deal with code.

Execute a script
(Only available in advanced mode.) With this action you can execute a script that you added to the game. You specify the script and the maximal 5 arguments for the script.

Execute a piece of code
When you add this action, a form shows in which you can type in a piece of code. This works in exactly the same way as when defining scripts. The only difference is that you can indicate for what instances the piece of code must be executed. Use the code action for small pieces of code. For longer pieces you are strongly advised to use scripts.

Set the value of a 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.

If a variable has a value
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 the value of a variable
With this action you can draw the value of a variable at a particular position on the screen.

Call the inherited event
(Only available in advanced mode.) This action is only useful when the object has a parent object. It calls the corresponding event in the parent object.

Comment
Use this action to add a line of comment to the action list. The line is shown in italic font. It does not do anything when executing the event. Adding comments helps you remember what your events are doing.

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 2*hspeed. Here hspeed 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_scale the amount the image is scaled (1 = not scaled)
image_single this variable indicate which subimage in the current sprite must be shown; if you set it to -1 (default) you loop through the images, otherwise only the indicated subimage (starting with number 0) is shown all the time
image_speed this variable indicates the speed with which the sub-images are shown. The default value is 1. If you make this value larger than 1 some sub-images are skipped to make the animation faster. If you make it smaller than 1 the animation becomes slower.
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 (coin.x , coin.y). In the case of a collision event you can refer to the x-coordinate of the other object as other.x. In conditional expressions you can use comparisons like < (smaller than), >, etc.

In your expressions you can also use functions. For example, the function random(10) gives a random real number below 10. So you can set for example the speed or direction of motion to a random value. Many more functions exist.


Creating rooms

Now that you have defined the objects with their behavior in the form of events and actions, it is time to create the rooms or levels in which the game takes place. Any game will need at least one room. In these rooms we place instances of the objects. Once the game starts the first room is shown and the instances in it come to life because of the actions in their creation events.

There are a large number of possibilities when creating rooms. Besides setting a number of properties and adding the instances of the objects you can add backgrounds, define views, and add tiles. Most of these options are discusses later in Chapter 20. In this chapter we will only discuss some basic settings, the addition of instances of objects, and the setting of background images.

To create a room, choose Add Room from the Add menu. The following form will appear:

At the top of the form there is a tool bar. On this you can indicate the size of the grid cells used for aligning objects. Also you can indicate whether to e.g. show the grid lines. (You can also indicate here whether to show the backgrounds, etc. It is sometimes useful to temporarily hide certain aspects of the room. Realize though that when you are adding instances of objects, these will always be shown, independent of the view setting.) There are also buttons to clear all instances from the room and to shift all instances over a number of pixels. Use negative numbers to shift them left or up. This is useful when you decided to e.g. enlarge the room. (You can also use this to place instances outside the room, which is sometimes useful.). Finally there is the Undo button to undo the last change to the room and the OK button to save the changes. (Click on the cross at the top right to close the form without saving the changes.)

At the left you will see three tab pages (five in advanced mode). The objects tab is where you add instances of objects to the room. In the settings tab you can indicate a number of settings for the room. In the backgrounds tab you can set background images for the room.

Adding instances

At the right in the room design form you see the room. At the start it is empty, with a gray background.

To add instances to the room, first select the objects tab if this one is not already visible. Next select the object you want to add by clicking on the button with the menu icon (or by clicking in the image area at the left). The image of the object appears at the left. (Note that there is a cross in the image. This indicates how the instances will be aligned with the grid.) Now click with your left mouse button in the room area at the right. An instance of the object appears. It will snap to the indicated grid. If you hold the <Alt> key while placing the instance it is not aligned to the grid. If you hold down the mouse button while dragging it over the room, you move the instance to the correct place. If you hold the <Shift> key while pressing and moving the mouse multiple instances are added. With the right mouse button you can remove instances. In this way you define the contents of the room.

As you will notice, if you place an instance on top of another one, the original instance disappears. Normally this is what you want, but not always. This can be avoided by unchecking the box labeled Delete underlying at the left.

If you want to change the position of an instance, hold the <Ctrl> key and click with the left mouse button on the instance and hold down the button. You can now drag it to a new position. (Use <Alt> for precise positioning.)

If you hold the <Ctrl> key while clicking with the right mouse button on an instance, a menu appears. Here you can delete the object, type in a precise position for the instance, or move the bottommost instance at the position to the top or send the topmost instance to the bottom.

Room setting

Each room has a number of settings that you can change by clicking on the settings tab.

Each room has a name. Best give it a meaningful name. There also is a caption. This caption is displayed in the window caption when the game is running. You can set the width and height of the room (in pixels). Also you can set the speed of the game. This is the number of steps per second. The higher the speed, the smoother the motion is. But you will need a faster computer to run it.

Setting the background

With the tab backgrounds you can set the background image for the room. Actually, you can specify multiple backgrounds. The tab page looks as follows:

At the top you will see the background color. You can click on it to change it. The background color is only useful if you don't use a background image that covers the whole room. Otherwise, you better uncheck the box labeled Draw background color because this will be a waste of time.

At the top you see a list of 8 backgrounds. You can define each of them but most of the time you will need just one or two. To define a background, first select it in the list. Next check the box labeled Visible when room starts otherwise you won't see it. The name of the background will become bold when it is defined. Now indicate a background image in the menu. There are a number of settings you can change. First of all you can indicate whether the background image should tile the room horizontally and/or vertically. You can also indicate the position of the background in the room (this will also influence the tiling). A different option is to stretch the background. The size will now be adapted such this is fills the entire room. Finally you can make the background scrolling by giving it a horizontal or vertical speed (pixels per step). Better don't use scrolling with a stretched background. The result will be a bit jaggy.

There is one more checkbox labeled Foreground image. When you check this box, the background is actually a foreground, which is drawn on top of everything else rather than behind it. Clearly such an image should be partially transparent to be of any use.


Distributing your game

With the information in the preceding chapters you can create your games. Once you have created a nice game you probably want to give it to other people to play. You are free to distribute your games you create with Game Maker in any way you like. You can even sell them. See the enclosed license agreement for more information.

There are basically three different ways in which you can distribute you games. The easiest way is to simply give people the *.gmd file that holds the game. This does though mean that the other person must have Game Maker. (You are not allowed to distribute Game Maker with your game but they can freely download it from the website.) Also the other person can change the game.

The second way is to create a stand-alone executable of the game. This can be achieved by choosing the item Create Executable in the File menu. You will be asked for the name of the executable that should contain the game. Indicate a name, press OK and you have your stand-alone game that you can give to anyone you like. You can set the icon for the stand-alone game in the Game Options form. (If your game uses any other files you should copy them to the folder containing the stand-alone game.) Now you should give this file to the other people (You might want to zip it first.)

The third way is to create an installer. A number of freeware installer programs are available on the web. Again you first make a stand-alone version and then you use the installer to create an installation. How to do this depends on the installer you use.


Advanced use

This section of the help file gives you information about the more advanced aspects of Game Maker. Later section will discuss how to finish and distribute your game, and the built-in programming language GML.

Information on the advanced use of Game Maker can be found in the following pages:

Advanced user interface
More about sprites
More about sounds and music
More about backgrounds
More about objects
More actions
More about rooms
Paths
Time lines
Scripts
Data files


Advanced mode

Up to now we considered the simple features of Game Maker. But there are a lot more possibilities. To be able to use these you must run Game Maker in advanced mode. This is easy to change. In the File menu, click on the menu item Advanced mode. (To fully see the effects you should restart Game Maker or at least save your game and load it anew.

When you start Game Maker in advanced mode, the following form is shown:

It contains all that was there in simple mode, but there are a number of additional resources, buttons, and menu items. Also, as we will see in the chapters that follow the different resources have additional options. Here we will discuss the additional menu items.

File menu

In the file menu you can find the following additional commands:

  • Merge Game. With this command you can merge all the resources (sprites, sounds, objects, rooms, etc.) from another game into the current game. This is very useful if you want to make parts you want to reuse (e.g. menu systems). (Note that all resources and instances and tiles will get a new id which might cause problems if you use these in scripts.) It is your responsibility to make sure that the resources in the two files have different names, otherwise problems might occur.
  • Preferences. Here you can set a number of preferences about Game Maker. They will be remembered between different calls of Game Maker. The following preferences can be set:
    • Show recently edited games in the file menu. If checked the eight most recently edited games are shown under the recent files in the file menu.
    • Load last opened file on startup. If checked when you start Game Maker the most recently opened file is opened automatically.
    • Keep backup copies of files. If checked the program saves a backup copy of your game with the extension gb0-gb9. You can open these games in Game Maker.
    • Maximal number of backups. Here you can indicate how many (1-9) different backup copies should be remembered by the program.
    • Show progress while loading and saving files. If checked, when load or save a file a progress indicator is shown.
    • At startup check for, and remove old temporary files. Game Maker and games created with it create temporary files. Normally these are automatically removed but sometimes, for example when games crash, they are left behind. If this option is checked, Game Maker checks whether such files exist and removed them at startup.
    • Run games in secure mode. If checked, any game created with Game Maker that runs on your machine will not be allowed to execute external programs or change or delete files at a place different from the game location. (This is a safeguard against Trojan horses although success is not guaranteed.) Checking this might make that certain games don't work correctly. The setting only works while Game Maker is running. So if you run the game independently of Game Maker it is NOT run in secure mode.
    • Show the origin and bounding box in the sprite image. If checked, in the sprite properties form, in the sprite image, the origin and bounding box for the sprite are indicated.
    • In object properties, show hints for actions. If checked, in the object properties form, when you hold your mouse over one of the actions, a description is shown.
    • When closing, remove instances outside the room. If checked, the program warns you when there are instances or tiles outside a room and lets you remove them.
    • Remember room settings when closing the form. If checked, a number of room settings, like whether to show the grid, whether to delete underlying objects, etc. are remembered when you edit the same room later.
    • >External sound editors. You can indicate here which external editors to use for the different sound types. (Note that Game Maker does not have a built-in sound editor so if you don't specify editors here you cannot edit the sounds.)
    • Scripts and code and colors. See below for more information about these preferences.
    • Image editor. Default Game Maker uses a built-in editor for images. If you have a better other image editing program you can indicate here to use a different program for editing the images.

Edit menu

In the file menu you can find the following additional commands:

  • Insert group. Resources can be grouped together. This is very useful when you make large games. For example, you can put all sounds related to a certain object in a group, or you can group all objects that are used in a particular level. This command creates a new group in the currently selected resource type. You will be asked for a name. Groups can again contain groups, etc. As indicated below you can drag resources into the groups.
  • Find Resource. With this command you type in the name of a resource and open the corresponding property form.
  • Show Object Information. Using this command you can get an overview of all objects in the game.

Add menu

In this menu you can now also add the additional resources. Note that for each of them there is also a button on the toolbar and a keyboard shortcut.

Scripts menu

In the scripts menu you can find the following additional commands:
  • Import Scripts. Can be used to import useful scripts from files.
  • Export Scripts. Can be used to save your scripts in a file, to be used by others. When you select a script resource only this script is saved. When you select a group all scripts in the group are saved. When you select the root resource (or a different type of resource) all scripts are saved. This menu item is also available when right-clicking on a script or group of scripts.
  • Show Built-in Variables. Shows a sorted list of all built-in variables, both local and global.
  • Show Built-in Functions. Shows a sorted list of all built-in functions.
  • Show Constants. Shows a sorted list of all built-in constants and constants defined in the game options.
  • Show Resource Names. Shows a sorted list of all resource names. You can click on a name to open the particular resource for editing.
  • Search in Scripts. You can search for a string in all scripts. You can click on one of the reported places to move there for editing.
  • Check Resource Names. Does a check of all resource names. Names will be reported if they are not correct, if there are duplicate resource names, or when a resource name is the name of a variable, function, or constant. You can click on a name to open the particular resource for editing.
  • Check All Scripts. Checks all scripts for errors. You can click on one of the reported places to move there for editing.


More about sprites

Up to now we loaded our sprites from files. It is though also possible to create and in particular modify them within Game Maker. To do this, open the sprite property window by double clicking on one of your sprite (or by creating a new one). Now press the button labeled Edit Sprite. A new form will appear showing all the sub-images that make up the sprite.

Editing your sprites

The sprite edit form will look as follows:

At the right you see the different images that make up the sprite. Note that in Game Maker all sub-images of a sprite must have the same size. At the left an animation of the sprite plays. (If you don't see the animation, check the box labeled Show Preview. Below the preview you can change the speed of the animation and the background color. In this way you can get an idea of what the animation will look like in the game. (Note that this speed is only for preview. The speed of the animation during the game depends on the room speed.)

The sprite editor contains many commands to create and change the sprite. These are all given through the menus. (For some there are buttons on the toolbar.) Some commands work on individual images. They require that you first select a sub-image with the mouse.

File menu

The file menu contains a number of commands related to loading and saving sprites.
  • New. Create a new, empty sprite. You must indicate the size of the sprite. (Remember, all images in a sprite must have the same size.)
  • Create from file. Create the sprite from a file. Many file types can be used. They all create a sprite consisting of a single image, except for animated GIF files that are split into the sub-images. Please note that the transparency color is the bottommost leftmost pixel, not the transparency color in the GIF file. You can select multiple images which will then all be loaded. They must though have the same size.
  • Add from file. Add an image (or images) from a file to the current sprite. If the images do not have the same size you can choose were to place them or to stretch them. You can select multiple images which will then all be loaded. They must though have the same size.
  • Save as GIF. Saves the sprite as an animated gif.
  • Save as strip. Saves the sprite as a bitmap, with all images next to each other.
  • Create from strip. Allows you to create a sprite from a strip. See below for more information.
  • Add from strip. Use this to add images from a strip. See below.
  • Close saving changes. Closes the form, saving the changes made to the sprite. If you don't want to save the changes, click on the close button of the window.
Edit menu

The edit menu contains a number of commands that deal with the currently selected sprite. You can cut it to the clipboard, paste an image from the clipboard, clear the current sprite, delete it, and move sprites left and right in the sequence. Finally, there is a command to edit an individual image using the built-in painting program (see below).

Transform menu

In the transform menu you can perform a number of transformations on the images.
  • Mirror horizontal. Mirrors the images horizontally.
  • Flip vertical. Flips the images vertically.
  • Shift. Here you can shift the images an indicated amount horizontally and vertically.
  • Rotate. You can rotate the images 90 degrees, 180 degrees, or an arbitrary amount. In the latter case you can also specify the quality. Experiment to get the best effects.
  • Resize Canvas. Here you can change the size of the canvas. You can also indicate where the old images are placed on the new canvas.
  • Stretch. Here you can stretch the images into a new size. You can indicate the scale factor and the quality.
  • Scale. This command scales the images (but not the image size!). You can indicate the scale factor, the quality, and the position of the current images in the scaled ones.
Images menu

In the images menu you can perform a number of operation on the images.
  • Cycle left. Cycles all images one place to the left. This effectively starts the animation at a different point.
  • Cycle right. Cycles all images one place to the right.
  • Black and white. Makes the sprite black and white (does not affect the transparency color!).
  • Colorize. Here you can change the color (hue) of the images. Use the slider to pick the different colors.
  • Colorize Partial. Here you can change the color (hue) of part of the images. You can select an old color and a range around it and then indicate the new color with which to replace this range of colors. This can be used to e.g. only change the color of the shirts of players.
  • Shift Hue. Another way of changing the color of the images. But this time the colors are shifted over the amount indicated giving rather interesting effects.
  • Intensity. Here you can change the intensity by providing values for the color saturation and the lightness of the images.
  • Fade. Here you specify a color and an amount. The colors in the images are now faded towards this color.
  • Transparency. Here you can indicate a level of screen-door transparency. This is achieved by making a number of pixels transparent.
  • Blur. By blurring the images the colors are mixed a bit, making it more vague. The higher the value, the more vague it becomes.
  • Crop. This makes the images as small as possible. This is very useful because the larger the images, the more video memory Game Maker will use. You might want to leave a little border around the images though to avoid transparency problems.

You will have to experiment with these commands to get the sprites you want.

Animation menu

Under the animation menu you can create new animations out of the current animation. There are many options and you should experiment a bit with them to create the effects you want. Also don't forget that you can always save an animation and later add it to the current one. Also you can always add some empty images and delete unwanted ones. I will briefly go through the different possibilities.
  • Set Length. Here you can change the length of your animation. The animation is repeated enough times to create the number of frames you indicate. (Normally you want this to be a multiple of the current number of frames.)
  • Stretch. This command also changes the length of the animation. But this time, frames are duplicated or removed to get the right number. So if you increase the number of frames the animation goes slower and if you decrease the number it goes faster.
  • Reverse. Well, as you could guess this reverses the animation. So it is played backwards.
  • Add Reverse. This time the reverse sequence is added, doubling the number of frames. This is very useful for making an object go left and right, change color and return, etc. You sometimes might want to remove the double first and middle frame that occur.
  • Translation sequence. You can create an animation in which the image slightly translates in each step. You must provide the number of frames and the total amount to move horizontally and vertically.
  • Rotation sequence. Creates an animation in which the image rotates. You can either choose clockwise or counterclockwise rotation. Specify the number of frames and the total angle in degrees (360 is a complete turn). (You might need to resize the canvas first to make sure the total image remains visible during the rotation.)
  • Colorize. Creates an animation that turns the image into a particular color.
  • Fade to color. Creates an animation that fades the image to a particular color.
  • Disappear. Makes the image disappear using screen-door transparency.
  • Shrink. Shrinks the image to nothing. You can indicate the direction.
  • Grow. Grows the image from nothing.
  • Flatten. Flattens the image to nothing in a given direction.
  • Raise. Raises the image from a given direction
  • Overlay. Overlays the animation with another animation or image in a file.
  • Morph. Morphs the animation to an animation or image from a file. Note that morphing works best if the two animations cover the same area of the image. Otherwise, halfway certain pixels disappear and others suddenly appear.
In particular the last two commands are very powerful. For example, to blow up an object, add a number of copies and then a number of empty frames. Then overlay it with an explosion animation. (Make sure the numbers of images match.) Alternatively, morph it to the explosion. With some practice you can make great sprites.

Strips

As indicated above, sprites are normally either stored as animated gif files or as strips. A strip is one big bitmap that stores all the images next to each other. The only problem is that the size of the individual sub-images is not stored in the image. Also, many strip files available on the web store multiple sprites in one file. For example, in the following piece of a strip file contains four different animations.

To select individual sprites out of such files, you can choose Create from Strip or Add from Strip from the File menu. After indicating the appropriate strip image file, the following form will show:

At the right you see (part of) the strip image you selected. At the left you can specify a number of parameters that specify which subimages you are interested in. Note that one or more rectangles in the image indicate the images you are selecting. The following parameters can be specified:

  • Number of images. This is the number of images you want to take from the strip.
  • Images per row. How many images of the ones you want are there per row. For example, by setting this to 1 you will select a vertical sequence of images.
  • Image width. Width of the individual images.
  • Image height. Height of the individual images.
  • Horizontal cell offset. If you don't want to select the top-left images, you can set here how many images should be skipped horizontally.
  • Vertical cell offset. Here you indicate how many images to skip vertically.
  • Horizontal pixel offset. Sometimes there is some additional space at the left top. Here you indicate this amount (in pixels).
  • Vertical pixel offset. Vertical amount of extra space.
  • Horizontal separation. In some strips there are lines or empty space between the images. Here you can indicate the horizontal amount to skip between the images (in pixels).
  • Vertical separation. Vertical amount to skip between the images.
Once you selected the correct set of images, press OK to create your sprite. Please remember that you are only allowed to use images created by others when you have their permission or when they are freeware.

Editing individual sub-images

You can also edit the individual sub-images. To this end select a sub-image and choose Edit Image from the Image menu. This will open a little built-in painting and imaging program. Please realize that this is a limited program that is mainly meant to make small changes in existing images and not to draw new ones. For that, you better use a full-blown drawing program and use files (or copy and paste) to put the image into Game Maker.

The form shows the image in the middle and a number of basic drawing buttons at the left. Here you can zoom in and out, draw pixels, lines, rectangles, text, etc. Note that the color depends on whether you use the left or right mouse button. For some drawing tools you can set properties (like line width or border visibility). There is a special button to change all pixels that have one color into another color. This is in particular useful to change the background color that is used for transparency. On the toolbar there are some special buttons to move all pixels in the image in a particular direction. Also you can indicate whether to show a grid when the image is zoomed (works only with a zoom factor of at least 4).

At the right of the form you can select the colors to be used (one by the left mouse button and one by the right button). There are four ways to change the color. First of all you can click with the mouse button (left or right) in one of the 16 basic colors. Note that there is a special color box that contains the color of the bottom-left pixel of the image that is used as transparency color if the sprite is transparent. You can use this color to make part of your image transparent. The second way is to click in the image with the changing color. Here you choose many more colors. You can hold down the mouse to see the color you are selecting. Thirdly, you can click with the left mouse in the boxes indicating the left and right color. A color dialog pops up in which you can select the color. Finally, you can select the color dropper tool at the left and click on a position in the image to copy the color there.

In the menus you can finds the same transformation and image changing commands that are also available in the sprite editor. This time though they only apply to the current image. (When the sprite has multiple images, commands that change the size, like stretch, are not available.) You can also save the image as a bitmap file. There are two additional commands in the Image menu:

  • Clear. Clear the image to the left color (which then automatically becomes the transparency color).
  • Gradient fill. With this command you can fill the image with a gradually changing color (not very useful for making sprites, but it looks nice, and can be used for backgrounds, which use the same paint program).
Note that there is no mechanism to select parts of the image. Also some fancy drawing routines are missing. For this you should use a more advanced drawing program (or simply the paint program that comes with Windows). The easiest way to do this is to use the copy button to put the image on the clipboard. Now in your painting program, use paste to get it. Change it and copy it to the clipboard. Now, in Game Maker you can paste the updated image back in.

Advanced sprite settings

In advanced mode, in the sprite properties form there are a number of advanced options that we will treat here.

First of all there are options related to collision checking. Whenever two instances meet a collision event is generated. Collisions are checked in the following way. Each sprite has a bounding box. This box is such that it contains the non-transparent part of all the sub-images. When the bounding boxes do overlap, it is checked whether two pixels in the current sub-images of the two sprites overlap. This second operation is expensive and requires extra memory and preprocessing. So if you are not interested in precise collision checking for a certain sprite, you should uncheck the box labeled Precise collision checking. In this case only bounding box checking is performed. You can also change the bounding box. This is hardly ever required but sometimes you might want to make the bounding box smaller, such that collisions with some extending parts of the sprite are not taken into account.

Sprites can be stored in two places: video memory and standard memory. Video memory is normally locate on the graphics card and is faster. So if you have many instances of the sprite you prefer to store it there. But the amount of video memory is limited, depending on the graphics card the player has. So you are recommended to store large sprites not in video memory.

Some sprites you might use only in one or two levels of your game. It is a bit wasteful to keep these sprites in memory all the time. In this case you can check the box labeled Load only on use. The sprite is now loaded at the first moment it is required. At the end of the room it is discarded again to free the memory. For large games with many sprites it is important to carefully manage which sprites are loaded and which ones are in video memory. (You can also load and discard sprites from pieces of code.)

Finally, you can indicate the origin of the sprite. This is the point in the sprite that corresponds with its position. When you set an instance at a particular position, the origin of the sprite is placed there. Default it is the top left corner of the sprite but it is sometimes more convenient to use the center or some other important point. You can even choose an origin outside the sprite. You can also set the origin by clicking in the sprite image (when the origin is shown in the image).


More about sounds and music

When you add sound resources to your game there are a number of other aspects that you can indicate. These are only visible in advanced mode.

For all sounds you can indicate whether they should be loaded only on use. This is the default for midi files but not for wave files. If you check this box, the sound is not loaded into memory when the game starts. Only at the moment it is needed it is loaded. This might give a slight hick-up. But is saves a lot of memory and it means that loading the game is faster. Also, at the end of the room, the sound is discarded and the memory is freed. Only if it is required again is it loaded again. Don't use this for short sound effects but only for longer background music or fragments that are played only occasionally.

For wave files you can indicate the number of buffers. This number indicated the number of times the sound can play simultaneously. For example, when you have some exploding sound and a number of explosions can happen at almost the same time, you might want to increase this number such that all explosions can be heard simultaneously. Be careful though. Multiple buffers cost (depending on the sound card) more memory.

Also you can indicate whether the sound should be prepared for sound effects. These effects, like panning the sound and changing the volume, can only be used from code. Sounds that allow for sound effects take up more resources.

Game Maker does not have a built-in sound editor. But in the preferences you can indicate external editors that you want to use for editing sounds. If you filled these in you can press the button labeled Edit Sound to edit the current sound. (The Game Maker window will be hidden while you edit the sound and returns when you close the sound editor.)

Besides wave files and midi files, there is actually a third kind of sound files: mp3 files. These are compressed wave files. Although you don't see them when selecting a sound file you can actually use them in Game Maker. First select to show all files at the bottom of the file open dialog, and you can load them. Be careful though. There are a number of disadvantages. First of all, they need to be decompressed which takes processing time and might slow down the game. The fact that the file size is smaller does not mean that they use less memory. Secondly, not all machines support them. So your game might not run on all machines. Preferably don't use them but convert your mp3 files into wave files. If you still want to use them, only use them as background music.


More about backgrounds

Besides loading them from files, you can also create your own backgrounds. To this end, press the button labeled Edit Background. A little built-in painting program opens in which you can create or change your background. Please realize that this is not a full-blown program. For more advanced editing tools use some paint program. There is one option that is particularly useful. In the Image menu you find a command Gradient Fill. This can be used to create some nice gradient backgrounds.

In advanced mode, the background property from has a number of advanced options.

Normally backgrounds are stored in video memory. This is fine when they are small but when you use large backgrounds you might want to use normal memory instead. This will be slightly slower, but video memory is limited. To this end uncheck the box labeled Use video memory.

Also, default backgrounds are loaded when they are needed and discarded again at the end of the room. This saves a lot of memory but will make the starting of room slightly slower and can give a little hick-up when changing the background halfway a room. To avoid this, uncheck the box labeled Load only on use.


More about objects

When you create an object in advanced mode, you can change some more advanced settings.

Depth

First of all, you can set the Depth of the instances of the object. When the instances are drawn on the screen they are drawn in order of depth. Instances with the largest depth are drawn first. Instances with the smallest depth are drawn last. When instances have the same depth, they are drawn in the order in which they were created. If you want to guarantee that an object lies in front of the others give it a negative depth. If you want to make sure it lies below other instances, give it a large positive depth. You can also change the depth of an instance during the game using the variable called depth.

Persistent objects

Secondly, you can make an object persistent. A persistent object will continue existing when you move from one room to the next. It only disappears when you explicitly destroy it. So you only need to put an instance of the object in the first room and then it will remain available in all rooms. This is great when you have e.g. a main character that moves from room to room. Using persistent objects is a powerful mechanism but also one that easily leads to errors.

Parents

Every object can have a parent object. When an object has a parent, it inherits the behavior of the parent. Stated differently, the object is sort of a special case of the parent object. For example, if you have 4 different balls, named ball1, ball2, ball3 and ball4, that all behave the same but have a different sprite, you can make ball1 the parent of the other three. Now you only need to specify events for ball1. The others will inherit the events and behave exactly the same way. Also, when you apply actions to instances of the parent object they will also be applied to the children. So, for example, if you destroy all ball1 instances also the ball2, ball3, and ball4 instances will be destroyed. This saves a lot of work.

Often, objects should behave almost completely the same but there will be some small differences. For example, one monster might move up and down and the other left and right. For the rest they have exactly the same behavior. In this case almost all events should have the same actions but one or two might be different. Again we can make one object the parent of the other. But in this case we also define certain events for the child object. These events "override" the parent events. So whenever an event for the child object contains actions, these are executed instead of the event of the parent. If you also want to execute the parent event you can call the so-called "inherited" event using the appropriate action.

It is actually good practice in such cases to create one base object, for example a ball0 object. This base object contains all the default behavior but is never used in the game. All actual objects have this base object as parent. Parent objects can again have parents, and so on. (Obviously you are not allowed to create cycles.) In this way you can create an object hierarchy. This is extremely useful to keep you game structured and you are strongly advised to learn to use this mechanism.

There is also a second use of the parent object. It also inherits the collision behavior for other objects. Let me explain this with an example. Assume you have four different floor objects. When a ball hits the floor it must change direction. This has to be specified in the collision event of the ball with the floor. Because there are four different floors we need to put the code on four different collision events of the ball. But when you make one base floor object and make this one the parent of the four actual floor objects, you only need to specify the collision event with this base floor. The other collisions will perform the same event. Again, this saves a lot of copying.

As indicated, wherever you use an object, this also implies the descendants. This happens when, in an action, you indicate that the action must be applied to instances of a certain object. It also happens when you use the with() statement in code (see below). And it works when you call functions like instance_position, instance_number, etc. Finally, it works when you refer to variables in other objects. In the example above when you set ball1.speed to 10 this also applies to ball2, ball3 and ball4.

Masks

When two instances collide a collision event occurs. To decide whether two instances intersect, the sprites are used. This is fine in most cases, but sometimes you want to base collisions on a different shape. For example, if you make an isometric game, objects typically have a height (to give them a 3D view). But for collisions you only want to use the ground part of the sprite. This can be achieved by creating a separate sprite that is used as collision mask for the object.

Information

The button Show Information gives an overview of all information for the object that can also be printed. This is in particular useful when you loose overview of all your actions and events.


More actions

In advanced mode there are some additional action libraries available with additional actions.

More move actions

An additional set of move actions is available. These actions are only available in advanced mode. The following actions exist:

Set a path for the instance
With this action you can indicate that the instance should follow a particular path. You indicate the path that must be followed and the speed in pixels per step. When the speed is positive the instance starts at the beginning of the path. If it is negative it starts at the end. Next you specify the end behavior, that is, what should happen when the end of the path is reached. You can choose to stop the motion, restart from the beginning, restart from the current position (which is the same when the path is closed), or reverse the motion. Finally you can indicate that the path must be seen as absolute, that is, the position will be as indicated in the path (this is useful when you have designed the path at a particular place in the room) or relative, in which case the start point of the path is placed at the current location of the instance (end point when speed is negative). See the chapter on paths for more information.

End the path for the instance
Use this action to stop the path for the instance.

Set the position on the path
With this action you can change the current position of the instance in the path. This must be a value between 0 and 1 (0=beginning, 1=end).

Set the speed for the path
With this action you can change the speed of the instance on the path. A negative speed moves the instance backwards along the path. Set it to 0 to temporarily stop the motion along the path.

Perform a step towards a point
This action should be placed in the step event to let the instance take a step towards a particular position. When the instance is already at the position it will not move any further. You specify the position to move to, the speed with which to move, that is, the size of the step, and whether the motion should stop when hitting a solid instance or when hitting any instance.

Step towards a point avoiding objects
This is a very powerful motion action. It should be placed in the step event. Like the previous action it lets the instance take a step towards a particular position. But in this case it tries to avoid obstacles. When the instance would run into a solid instance (or any instance) it will change the direction of motion to try to avoid the instance and move around it. The approach is not guaranteed to work but in most easy cases it will effectively move the instance towards the goal. For more complicated cases, there are motion planning functions. You specify the position to move to, the speed with which to move, that is, the size of the step, and whether the motion should avoid solid instances or any instance.

Particle actions

Particle systems are meant to create special effects. Particles are small elements (represented by a pixel or a little shape). Such particles move around according to predefined rules and can change color while they move. Many such particles together can create e.g. fireworks, flames, rain, snow, star fields, flying debris, etc.

Game Maker contains an extensive particle system that can be accessed through functions. A more limited particle system can be accessed through the actions described below.

A particle system can deal with particles of different types. After creating the particle system the first thing to do is specify the particle types. Using the actions below you can specify up to 16 types of particles. Each type has a shape, a size, a start color and an end color. The color slowly changes from the start color to the end color. Particles have a limited life time. In the type you specify the minimal and maximal life time of the particles. Particles also have a speed and a direction. Finally, gravity and friction can work on particles.

After you specified the particle types you must create them at places on in the room. You can either burst a number of particles of a particular type from a place or you can create a constant stream of particles appearing. Particles appear at emitters. The particle system can have up to 8 emitters working at the same time. So after you created the particle types you must create the emitters and tell them to burst or stream particles.

Here is the complete set of actions. Best experiment with them to get the required effect. These actions are only available in the registered version of Game Maker.

Create the particle system
This action created the particle system. It must be called before any other actions can be used. You only need to call it once. You can specify the depth at which the particles are drawn. If you use a large positive depth the particles appear behind the instances. If you use a negative depth they appear before the instances.

Destroy the particle system
This action destroys the particle system, freeing all its memory. Don't forget to call this (e.g. when you move to a different room) because particle systems use a lot of storage.

Clear all particles in the system
This action removes all the particles currently visible. It does not stop the emitters so new particles might be created again if you have streaming emitters (see below).

Create a type of particle
With this action you create a particle type. You can choose one of the 16 types available. For the particle type you can specify its shape, its minimal and maximal size (when the particle appears a random value between these bounds is used), the color with which the particle starts and the color to which it changes over its lifetime. Note that only a particle type is created, not an actual particle. For this you need emitters (see below).

Set the life time for a particle type
A particle lives for a limited number of steps. After this is disappears. With this action you set the life time for a particle type. You give two bounds and the actual life time is chosen randomly between them.

Set the motion for a particle type
With this action you can set the speed and direction of motion for a particle type. Again you give two bounds and the actual value is chosen randomly between them. For example, to make the particle move in a random direction, give 0 and 360 for the bounds for the direction. You can also specify a friction. This amount is subtracted from the speed in each step until it becomes 0. (You can make a particle speed up by using a negative friction.)

Set the gravity of a particle type
With this action you set the amount of gravity and direction of gravity for a particular particle type. 270 is downwards.

Create secondary particles
This is a bit more complicated. Particles can create other particles during their life time and when they die. With this action you can specify this. You can specify the type and number of particles that must be created at each step during the life time and you can specify the type and number of particles that must be created when the particle dies. Be very careful here. You can easily create huge numbers of particles in this way, slowing down the system considerably. For the numbers you can also use a negative value. A negative value x means that e.g. in each step a particle is created with chance -1/x. So for example, if you want to generate a secondary particle about every 4 steps, use a value of -4. Secondary particles are great for e.g. creating tails of particles or exploding particles.

Create a particle emitter
This action creates a particle emitter. Particles are generated by emitters. You can have up to eight emitters. Choose the emitter and specify the shape of it and its size and position (in the form of a bounding box).

Destroy an emitter
This action destroys the indicated emitter. Note that existing particles that came from this emitter are not removed.

Burst a number of particles from an emitter
Even if you defined a particle type and an emitter there are still no particles. You still have to tell the emitter to generate the particles. With this action you tell a particular emitter to generate a given number of particles of a given type. All these particles are generated at once. For the number you can also use a negative value. A negative value x means that a particle is created with chance -1/x. So for example, if you want to generate a particle with a chance of 25 percent, use a value of -4.

Stream particles from an emitter
With this action you tell a particular emitter to stream a given number of particles of a given type. In each step this number of particles is generated, leading to a continuous stream of particles. The emitter will continue streaming particles until you destroy it or tell it to stream 0 particles. For the number you can also use a negative value. A negative value x means that in each step a particle is created with chance -1/x. So for example, if you want to generate a particle about every 4 steps, use a value of -4.

Extra actions

Here you can find a number of useful extra actions. These actions are only available in the registered version of Game Maker.

Play a CD
With this action you can play some tracks from a CD in the default CD-drive. You specify the starting track and the final track.

Stop the CD
Stops the currently playing CD.

Pause the CD
Pause the currently playing CD.

Resume the CD
Resumes a paused CD.

If a CD exists in the drive
If there is a CD in the default drive then the next action is executed.

If the CD is playing
If a CD is playing in the default drive then the next action is executed.

Replace a sprite from a file
This action can be used to replace a sprite from the contents of a file. You indicate the sprite you want to replace, the filename (.bmp, .jpg, or .gif) and the number of subimages in the sprite when you load it from a bmp or jpg file. For a gif file the number of subimages is automatically decided based on the number of subimages in the gif file. Other settings for the sprite, e.g. whether it is transparent or not, are not changed. You can use this action to avoid storing all sprites in the program itself. At the beginning of a level you can replace sprites by e.g. the actual character sprites you want to use. DON'T change a sprite that is at that moment used in an instance in the room. This might give unwanted effects with collisions.

Replace a sound from a file
With this action you can replace a sound by the contents of a file (.wav, .mid, or .mp3). You specify the sound and the filename. This avoids having to store all the sounds in the game itself. For example, you can use different pieces of background music and pick the one you want to play. DON'T change a sound while it is playing.

Replace a background from a file
With this action you can replace a background by the contents of a file (.bmp, or .jpg). You specify the background and the filename. This avoids having to store all the backgrounds in the game itself. DON'T change a background that is visible.

Set the mouse cursor
You can use this action to replace the windows mouse cursor by a sprite. You specify the sprite and whether the windows mouse cursor should still be shown. The sprite can be animation. Note that the sprite will only be shown in the room, not in the area outside it.

Take a snapshot image of the game
With this action you can take a snapshot image of the game and store it in a .bmp file. You specify the filename to store the image in.

Set the room background to a gradient With this action you can give the current room a gradient background. You specify the two colors that make up the gradient and the direction (horizontal or vertical).

Open a webpage in a browser You can indicate a web address in this action. This webpage is then opened in the default browser on the machine. (The action can actually also be used to open other documents.) The action does not work in secure mode.


More about rooms

Rooms in Game Maker have many options. Before we only treated the most important ones. In this chapter we will discuss the other options. When you open the room form in advanced mode it looks as follows:

As you will see, some new buttons have been added to the toolbar. There are buttons to sort the instances horizontally or vertically. This is useful when instance partially overlap. (When adding tiles these buttons and the others work on the tiles rather than the instances.) Also there are buttons to lock all instances or unlock all instances. Locked instances cannot be moved or deleted. This saves you from incidentally removing instances. Using the right mouse button menu (hold <Ctrl> and right click on an instance) you can also lock or unlock individual instances.

Finally, you can indicate that you want to use an isometric grid. This is very useful when creating isometric games. First of all, the grid lines now run diagonal. Also the snapping of instances is different. (It works best when the origin of the instance is at the top left corner as is default.)

Also there are two new tabs which we will discuss below.

Advanced settings

There where two aspects in the settings tab that we did not yet discuss. First of all, there is a checkbox labeled Persistent. Normally, when you leave a room and return to the same room later, the room is reset to its initial settings. This is fine if you have a number of levels in your game but it is normally not what you want in for example an RPG. Here the room should be the way you left it the last time. Checking the box labeled Persistent will do exactly that. The room status will be remembered and when you return to it later, it will be exactly the same as you left it. Only when you restart the game will the room be reset. Actually, there is one exception to this. If you marked certain objects as being persistent (see Chapter 19), instances of this object will not stay in the room but move to the next room.

Secondly, there is a button labeled Creation code. Here you can type in a piece of code in GML (see later) that is executed when the room is created. This is useful to e.g. fill in certain variables for the room, create certain instances, etc. It is useful to understand what exactly happens when you move to a particular room in the game.
  • First, in the current room (if any) all instances get a room-end event. Next the non-persistent instances are removed (no destroy event is generated!).
  • Next, for the new room the persistent instances from the previous room are added.
  • All new instances are created and their creation events are executed (if the room is not persistent or has not been visited before).
  • When this is the first room, for all instances the game-start event is generated.
  • Now the room creation code is executed.
  • Finally, all instances get a room-start event.
So, for example, the room-start events can use variables set by the creation code for the room and in the creation code you can refer to the instances (both new ones and persistent ones) in the room.

There is one further option. In the pop-up menu when you right click on an instance with the <Ctrl> key you can now indicate some creation code for the specific instance. This code is executed when the room is started, just before the creation event of the instance is executed. This is very useful to e.g. set certain parameters that are specific to the instance.

Adding tiles

You can also create so-called tiled background. The reason for this is as follows: In many games you like to have nice looking backgrounds. For example, in a maze game, the walls of the maze should nicely match up, and in platform game you like to see beautifully drawn platforms, trees, etc. You can do this in Game Maker by defining many different objects and composing your rooms from these objects. The problem though is that this takes a lot of work, uses large amounts of resources, and makes the games run slow because of the many different objects. For example, to create nice walls in maze games you already need 15 differently shaped wall objects.

The standard way out, used in many games, is that the walls and other static objects are actually drawn on the background. But, you might ask, how does the game know that an object hits a wall if it is drawn on the background only? The trick is as follows: You create just one wall object in your game. It must have the right size but it does not need to look nice. When creating the room, place this object at all places where there is a wall. And, here comes the trick, we make this object invisible. So when playing the game you don't see the wall objects. You see the beautiful background instead. But the solid wall objects are still there and the object in the game will react to them.

You can use this technique for any object that is not changing its shape or position. (You can also not use it when the object must be animated.) For platform games, you probably need just one floor and one wall object, but you can make beautifully looking backgrounds where it looks as if you walk on grass, on tree branches, etc.

To add tiles to your room you first need to add a background image to your game that contains the tiles. A few of these are provided with Game Maker. If you want to have your tiles partially transparent, make sure you make the background image transparent. Now, when defining your room, click on the tab tiles. The following form is shown (actually, we already added some tiles in this room).

At the left top there is the current set of tiles used. To select the set, click on the menu button below it and select the appropriate background image. By pressing the Tile Settings button you can change a number of settings. You can set the width and height of an individual tile, a separation between the tiles (this is normally 0 or 1) and an offset where the top leftmost tile starts.

Now you can add tile by selecting the tile you want at the top left, and next clicking at the appropriate place in the room at the right. This works in exactly the same way as for adding instances. Underlying tiles are removed, unless you uncheck the box Delete underlying. You can use the right button to delete tiles. Hold the <Shift> key to add multiple tiles. And hold the <Ctrl> key to move tiles to a new place. The <Alt> key will avoid snapping to the gird. Also there is again a pop-up menu when you hold the <Ctrl> key and click on a tile with the right mouse button. The buttons in the toolbar will now clear all tiles, shift all tiles, sort the tiles or lock/unlock them. (Actually they only operate on the current layer; see below.)

In some situations you might want to put a part of the background in the room that is not exactly the size of a tile. This can be done as follows. In the top-left image press the left mouse button while holding the <Alt> key. Now you can drag an area which you can then place in the room in the same way as tiles.

Tiles can be placed in layers at different depths. At the bottom you see the current depth. Default this is 1000000 which is normally behind all instances. So the instances will move in front of the tiles. You can use the Add button to add new tile layers, each with a different depth. Negative depths can be used to put tiles in front of instances. If you also give objects different depths you can put them between different tile layers. If you press Delete you delete a tile layer together with all its tiles. (There must always be at least on layer.) If you press Change you can change the depth of a tile layer. If you give it the same depth as another layer, the layers are merged.

Using tiles is a powerful feature that should be used as much as possible. It is much faster than using objects and the tile images are stored only once. So you can use large tiled rooms with very little memory consumption.

Views

Finally, there is a tab labeled views. This gives a mechanism of drawing different parts of your room at different places on the screen. There are many uses for views. First of all, in a number of games you want to show only part of the room at any time. For example, in most platform games, the view follows the main character. In two-player games you often want a split-screen mode in which in one part of the screen you see one player and in another part you see the other player. A third use is in games in which part of the room should scroll with e.g. the main character while another part is fixed (for example some status panel). This can all be easily achieved in Game Maker.

When you click the tab labeled views the following information will show:

At the top there is a box labeled Enable the use of Views. You much check this box to use views. Below this you see the list of at most eight views you can define. Below the list you can give information for the views. First of all you must indicate whether the view should be visible when the room starts. Make sure at least one view is visible. Visible views are shown in bold. Next you indicate the area of the room that should be shown in the view. You specify the left and top position, and the width and the height of the view. Below that you indicate the position of the view on the screen.

As indicated above, you often want the view to follow a certain object. This object you can indicate at the bottom. If there are multiple instances of this object, only the first one is followed by the view. (In code you can also indicate that a particular instance must be followed.) Normally the character should be able to walk around a bit without the view changing. Only when the character gets close to the boundary of the view, should the view change. You can specify the size of the border that must remain visible around the object. Finally, you can restrict the speed with which the view changes. This might mean that the character can walk of the screen, but it gives a much smoother game play. Use -1 if you want the view to change instantaneously.


Paths

In more advanced games you often want to let instances follow certain paths. Even though you can indicate this by e.g. using timer events or code, this is rather complicated. Path resources are an easier mechanism for this. The idea is rather simple. You define a path by drawing it. Next you can place an action in e.g. the creation event of the object to tell the object to follow the particular path. This chapter will explain this in detail.

Defining paths

To add a path to your game, choose Add Path from the Add menu. The following form will pop up (in the example we already added a little path).

At the left top of the form you can set the name of the path, as usual. Below it you find the points that define the path. Each point has both a position and a speed (indicated with sp). Depending on how you use the path, the position is either absolute, that is, the instance for which you will later use the path will follow it at that particular place, or it is relative, that is, the instance will always start at the first position on the path and follow the path from there. The speed should be interpreted as follows. A value of 100 means the original speed given for the path when assigning it to the instance. A lower value reduces the speed, a higher value increases it (so it indicates the percentage of the actual speed). Speed will be interpolated between points, so the speed changes gradually.

To add a point press the button Add. A copy is made of the currently selected point. Now you can change the actual position and speed by changing the values in the edit boxes. Whenever you select a point in the list, you can also change its values. Press Insert to insert a new point before the current one, and Delete to delete the current point.

At the right of the form you will see the actual path. The red dot indicates the currently selected control point. The blue dots are the other control points. The green square indicates the position where the path starts. You can also change the path using the mouse. Click anywhere on the image to add a point. Click on an existing point and drag it to change its position. When you hold <Shift> while clicking on a point, you insert a point. Finally, you can use the right mouse button to remove points. (Note that you cannot change the speed this way.) Normally the points will be aligned with a grid. You can change the grid settings at the top tool bar. Here you can also indicate whether the grid should be visible or not. If you want to precisely position a point, hold the <Alt> key while adding or moving it.

You can influence the shape of the path in two ways. Fist of all you can use the type of connection. You can either choose straight line connections or a smooth path. Secondly, you can indicate whether the path must be closed or not.

On the toolbar there are a number of important controls. From left to right they have the following meaning. The first button indicates that you are ready and want to close the form, keeping the changes. (If you want to discard the changes, press the cross to close the window and indicate that you do not want to save the changes.) Next there is the button to undo the last change.

The following set of toolbar buttons allows you the clear the path, reverse the order in which the path is traversed, shift the path, mirror it horizontally, flip it vertically, rotate it, and scale it. Next there are buttons to shift the view (not the path itself; the actual view area is indicated in the status bar at the bottom) and to center the view.

As already indicated above you can next set the snap values and whether to show the grid. Finally there is a button to indicate that you want to see a particular room as background for the path. Using this you can easily put the path at a particular place in the room, for example on a race track, such that later the instances will follow the correct route. (This only makes sense when you use absolute paths; see below.)

Assigning paths to objects

To assign a path to an instance of an object, you can place the path action in some event, for example in the creation event. In this action you must specify the path from the drop down menu. There are some further values you can provide.

You must indicate the path that must be followed and the speed in pixels per step. When the speed is positive the instance starts at the beginning of the path. If it is negative it starts at the end. Remember that when you defined the path you specify the actual speed relative to this indicated speed. There is also an action to change the speed with which the path is executed. You can use this to e.g. let an instance slow down or speed up along its path. Note that the normal speed of the instance is ignored (actually set to 0) when executing a path. Also things like gravity and friction do not influence the motion along a path.

Next you specify the end behavior, that is, what should happen when the end of the path is reached. You can choose to stop the motion and end the path. You can also restart the path from the beginning, that is, the instance jumps back to the position where the path was started and executes the path again. A third option is to restart from the current position, that is, the instance follows the path again but now with this new starting position (this is the same when the path is closed). Finally you can choose to reverse the motion, making the instance go back and forth along the path. Note that also at the end of the path an event happens; see below.

Finally you can indicate whether the path must be absolute or relative. An absolute path is executed at the place where it is defined. The instance is placed at the start position and moved from there (end position when speed is negative). This is useful when you e.g. have a race track and defined the path on that race track. When you choose relative the instances starts executing the path from its current position. This is useful when an instance should make a local motion. For example, space ships in a space invader game can make a particular turn from their current position.

When you want to place the instance at a different point along its path you can use the action to set the path position. A path position always lies between 0 and 1, 0 indicating the start position and 1 the end position on the path. Note that in each step the direction variable is automatically set to the correct direction along the path. So you can use this variable to e.g. choose the correct subimage.

When using scripts or pieces of code you have more control over the way the path is executed. There is a function to start a path for an instance. The variable path_position indicates the current position on the path (between 0 and 1 as indicated above). The variable path_speed indicated the speed along the path. A variable path_scale can be used to scale the path. A value of 1 is the original size. A larger value indicates that the path is made larger; a smaller value makes it smaller. The variable path_orientation indicates the orientation in which the path is executed (in degrees counter-clockwise). This enables you to execute the path in a different orientation (e.g. moving up and down rather than left and right). There is also a variable to control the end behavior. Finally there are lots of functions to ask for properties of paths (e.g. the x and y coordinate at a certain positions) and there are functions to create paths. There are even functions that created collision free paths for an instance to reach a certain goal. See the later sections on GML for details on this.

You might wonder what happens when the instance collides with another instance while it follows a path. Basically the same happens as when the instance moves with a speed. When there is a solid instance, the instance is place back to its previous place. When both instances are not solid they are placed at their new positions Next the collision event(s) are executed and it is checked whether the collision has been resolved. If not and the other instance is solid the instance will stop, as it should (assuming there is a collision event defined). Also, the path_position variable is not increased. When the blocking instance disappears the instance will continue to follow its path. To handle collisions yourself the variable path_positionprevious can be useful. It holds the previous position for the path and you can set the path position to this variable to avoid advancing along the path.

The path event

As described above, you can indicate what must happen when the instance reaches the end of the path. At this moment also an End of Path event occurs. You can find it under the Other events. Here you can place actions. For example, you might want to destroy the instance, or let it start a new (different) path.


Time Lines

In many games certain things must happen at certain moments in time. You can try to achieve this by using alarm events but when things get too complicated this won't work any more. The time line resource is meant for this. In a time line you specify which actions must happen at certain moments in time. You can use all the actions that are also available for the different events. Once you created a time line you can assign it to an instance of an object. This instance will then execute the actions at the indicated moments of time. Let me explain this with an example. Assume you want to make a guard. This guard should move 20 time steps to the left, then 10 upwards, 20 to the right, 10 downwards and then stop. To achieve this you make a time line where you start with setting a motion to the left. At moment 20 you set a motion upward, at moment 30 a motion to the right, at moment 50 a motion downwards and at moment 60 you stop the motion. Now you can assign this time line to the guard and the guard will do exactly what you planned. You can also use a time line to control your game more globally. Create an invisible controller object, create a time line that at certain moments creates enemies, and assign it to the controller object. If you start to work with it you will find out it is a very powerful concept.

To create a time line, choose Add Time Line from the Add menu. The following form will pop up.

It looks a bit like the object properties form. At the left you can set the name and there are buttons to add and modify moments in the time line. Next there is the list of moments. This list specifies the moments in time steps at which assigned action(s) will happen. Then there is the familiar list of actions for the selected moment and finally there is the total set of actions available.

To add a moment press the button Add. Indicate the moment of time (this is the number of steps since the time line was started). Now you can drag actions to the list as for object events. There are also buttons to delete the selected moment, to change the time for the selected moment and to clear the time line.

Finally there are two special buttons. With the Merge button you can merge all moments in a time interval into one. With the Shift button you can shift all moment in a time interval forwards or backwards by a given amount of time. Make sure you do not create negative time moments. They will never be executed.

There are two actions related to time lines.

Set a time line
With this action you set the particular time line for an instance of an object. You indicate the time line and the starting position within the time line (0 is the beginning). You can also use this action to end a time line by choosing No Time Line as value.

Set the time line position
With this action you can change the position in the current time line (either absolute or relative). This can be used to skip certain parts of the time line or to repeat certain parts. For example, if you want to make a looping time line, at the last moment, add this action to set the position back to 0. You can also use it to wait for something to happen. Just add the test action and, if not true, set the time line position relative to -1.


Scripts

Game Maker has a built-in programming language. Once you get more familiar with Game Maker and want to use it to its fullest extend, it is advisable to start learning to use this language. There are two ways to use the language. First of all you can create scripts. These are pieces of code that you give a name. They are shown in the resource tree and can be saved to a file and loaded from a file. They can be used to form a library that extends the possibilities of Game Maker. Alternatively, you can add a code action to some event and type a piece of code there. Adding code actions works in exactly the same way as adding scripts except for two differences. Code actions don't have a name and cannot use arguments. Also they have the well-known field to indicate to what objects the action should apply. For the rest you enter code in exactly the same way as in scripts. So we further concentrate on scripts in this chapter.

As stated before, a script is a piece of code in the built-in programming language that performs a particular task. A script can take a number of arguments. To execute a script from within some event, you can use the script action. In this action you specify the script you want to execute, together with the up to five arguments. (You can also execute scripts from within a piece of code in the same way you call a function. In that case you can use up to 16 arguments.) When the script returns a value, you can also use it as a function when providing values in other actions.

To add a script to your game, choose Add Script from the Add menu. The following form will pop up (in the example we already added a little script that computed the product of the two arguments).

(Actually, this is the built-in script editor. In the preferences you can also indicate that you want to use an external editor.) At the top right you can indicate the name of the script. You have a little editor in which you can type the script. Note that at the bottom a list is shown of all functions, built-in variables, and constants. This helps you find the one you need. You can double click one to add it (or use <Ctrl>P for the same purpose.) Showing this list can be switched off in the preferences. The editor has a number of useful properties many available through buttons (press the right mouse button for some additional commands):
  • Multiple undo and redo either per key press or in groups (can be changed in the preferences)
  • Intelligent auto indent that aligns with the previous line (can be set in the preferences)
  • Intelligent tabbing that tabs till the first non space in the previous lines (can be set in the preferences)
  • Use <Ctrl>I to indent selected lines and <Shift><Ctrl>I to unindent selected lines
  • Cut and paste
  • Search and replace
  • Use <Ctrl> + up, down, page-up, or page-down to scroll without changing the cursor position
  • Use F4 to open the script or resource whose name is at the cursor position (does not work in the code action; only in scripts)
  • Saving and loading the script as a text file
Also there is a button with which you can test whether the script is correct. Not all aspects can be tested at this stage but the syntax of your script will be tested, together with the existence of functions used.

As you might have noticed, parts of the script text are colored. The editor knows about existing objects, built-in variables and functions, etc. Color-coding helps a lot in avoiding mistakes. In particular, you see immediately if you misspelled some name or use a keyword as a variable. Color-coding is though a bit slow. In the preferences in the file menu you can switch color-coding on and off. Here you can also change the color for the different components of the programs. (If something goes wrong with color coding, press F12 twice, to switch it off and back on.) Also you can change the font used in scripts and code.

Scripts are extremely useful to extend the possibilities of Game Maker. This does though require that you design your scripts careful. Scripts can be stored in libraries that can be added to your game. To import a library, use the item Import scripts from the file menu. To save your scripts in the form of a library use Export scripts. Script libraries are simple text files (although they have the extension .gml). Preferably don't edit them directly because they have a special structure. Some libraries with useful scripts are included. (To avoid unnecessary work when loading the game, after importing a library, best delete those scripts that you don't use.)

When creating scripts you easily make mistakes. Always test the scripts by using the appropriate button. When an error occurs during the execution of a script this is reported, with an indication of the type of error and the place. If you need to check things more carefully, you can run the game in debug mode. Now a form appears in which you can monitor lots of information in your game.

Under the Run menu you can pause the game, run it step by step and even restart it. Under the Watch menu you can watch the value of certain expressions. Use Add to type in some expression whose value is shown in each step of the game. In this way you can see whether your game is doing things the right way. You can watch many expressions. You can save them for later use (e.g. after you made a correction to the game). Under the Tools menu you find items to see even more information. You can see a list of all instances in the game, you can watch all global variables (well, the most important ones) and the local variables of an instance (either use the object name or the id of the instance). You can also view messages which you can send from your code using the function show_debug_message(str). Finally you can give the game commands and change the speed of the game. If you make complicated games you should really learn how to use the debug options.


Data files

In more advanced games you often need to use additional files, for example files that describe certain properties, backgrounds and sprites that you want to load during the game, movies, DLL files (see later) or your own fonts. You can distribute these files with your game but it is nicer to embed them in the game itself. For this you can use data file resources. A data file resource simply stores the contents of a file. When the game starts this file is written to the disk and can then be used in the game.

To add a data file choose Add Data File from the Add menu. The following form will show:

You can give the resource a name as always. Press the button Load Data File to load the file into the resource. You can choose the File Name that must be used for storing the resource (no path is allowed in the filename). Next you can indicate what to do with the data file when the game starts:
  • Don't Export. Don't export it at all. (There is a GML function to export it later.)
  • To Temporary Folder. The file is written to the temporary folder for the game. This is in particular useful for e.g. loading backgrounds, etc.
  • To Working Folder. The file is written to the folder in which the game is running. Many routines search for files there but you must be careful as the player might run the game from a read-only device.
  • Install a Font. If your file is a font file you can choose this option. The file is saved in the temporary folder and next installed as a font such that it can be used in the game.
Finally there are a few options
  • Free Data Memory. When checked the memory used for the data file is freed after exporting. This saves memory but means that the resource can no longer be used in functions.
  • Overwrite the File. When checked the file is overwritten if it already exists.
  • Remove at Game End. When check the file is removed again when the game ends. (Note that files in the temporary folder are always removed when the game ends.)
If an error occurs during exporting the game will still run. But the file or font might not be available.

Data files can take a lot of memory but loading and exporting them is fast.


Finishing your game

When you want to distribute your game you better make sure that it has all the ingredients that make it a great game. Besides the game itself this means that you should provide game information, set the correct graphics options, and take care of speed. This section of the help file gives you information about these aspects.

Information on finishing your game can be found in the following pages:


Game information

A good game provides the player with some information on how to play the game. This information is displayed when the player presses the <F1> key during game play. To create the game information, double click Game Information in the resource tree at the left of the screen. A little build-in editor is opened where you can edit the game information. You can use different fonts, different colors, and styles. Also you can set the background color.

One interesting option in the Format menu is to Mimic Main Form. When you check this option the help form is displayed exactly at the position and the size of the game form. As a result it looks like the text appears in the game window. Choosing the correct background color now provides a nice visual effect. (You might want to indicate at the bottom of the help file that the user must press Escape to continue playing.)

A good advice is to make the information short but precise. Of course you should add your name because you created the game. All example games provided have an information file about the game and how it was created.

If you want to make a bit more fancy help, use e.g. Word. Then select the part you want and use copy and paste to move it from Word to the game information editor.


Game options

There are a number of options you can change for your game. They can be found by double clicking on Game Options in the resource tree at the left of the screen. They are subdivided in a number of tabbed pages. (Some options are only available in advanced mode.)

Graphics options

In this tab you can set a number of options that are related to the graphical appearance of your game. It is normally useful to check out the effects of these options because they can have a significant effect on the way the game looks. Remember though that different users have different machines. So better make sure that the settings also work on other peoples machines.

Start in fullscreen mode
When checked the game runs in the full screen; otherwise it runs in a window.

Scale percentage in windowed mode
Here you can indicate that the image in windowed mode should be scaled. 100 is no scaling. You typically use when your sprites and rooms are very small. Scaling is slower but most modern graphics cards can do this with little overhead. Better don't use values below 100 because scaling down is normally very slow.

Scale percentage in fullscreen mode
Here you can indicate that the image in fullscreen mode should be scaled. 100 is no scaling. A value of 0 indicates maximal possible scaling. Scaling is slower but most modern graphics cards can do this with little overhead. Better don't use values below 100 because scaling down is normally very slow.

Only scale when there is hardware support
If you check this scaling is only done when there is hardware support for this. Unfortunately though some graphics cards indicate that there is hardware support even if there is not.

Don't draw a border in windowed mode
When checked in windowed mode the game window will not have a border or a caption bar.

Don't show the buttons in the window caption
When checked in windowed mode the window caption will not show the buttons to close the window or to minimize it.

Wait for vertical blank before drawing
The screen of your computer is refreshed a number of times per second (normally between 50 and 100). After refreshing the screen there is a so-called vertical blank in which nothing happens on the screen. If you draw the screen continuously, part of one image and part of the next might show on the screen, which can give a poor visual effect. If you wait for the vertical blank before drawing the next frame, this problem disappears. The disadvantage is that the program must wait for the vertical blank which will slow it down slightly.

Display the cursor
Indicates whether you want the mouse pointer to be visible. Turning it off is normally faster and nicer. (You can easily make you own cursor object in Game Maker.)

Display the caption in fullscreen mode
When checked, in fullscreen mode a little white box is drawn at the left top, displaying the room caption, the score and the number of lives. You can switch this off here. It is normally nicer if you draw these things yourself at an appropriate place in your rooms.

Freeze the game when the form looses focus
When checked, whenever the player brings some other form to the top (e.g. another application) the game freezes until the game window again gets the focus.

Resolution

In this tab you can set the screen resolution in which your game must run.

Set the resolution of the screen
The screen has a particular resolution. Three aspects play a role here: the number of pixels (horizontal and vertical) on the screen, the number of bits used for representing the colors, and the frequency with which the screen is refreshed. Normally Game Maker does not change these settings, that is, it uses the settings for the machine on which the game is running. This can lead to poor graphics. For example, if your rooms are small and a user uses a large screen resolution, the game will play in a very small window. You can solve this by using full screen mode and scaling the image, but that might slow down the game. The best way to solve this is to tell Game Maker to change the screen resolution when running the game. It will change it back afterwards. To do so, check this option. A number of additional options will occur. First of all you can indicate the color depth setting (16 or 32 bits; normally 16 bits is best; on Windows'98 games will always run in 16 bit color depth, even if you specify 32 bits). Secondly you can indicate the screen size (320x240, 640x480, 800x600, 1024x768, 1280x1024, or 1600x1200). Some warnings are in place here though. If you choose a small resolution (e.g. 320x240) Windows will resize all your forms when you run the game. This might cause problems with other applications you are running (and also in Game Maker itself). (Use exclusive mode to avoid this.) When you use the largest two you should also be careful because not all computers support it. You can also indicate not to change the screen size. Finally you can indicate the frequency (60, 70, 85, 100; if the one you specify is too high, the default frequency is used; you can also specify to use the default frequency). Also the following option occurs:

Use exclusive graphics mode
In exclusive mode, the game has the full control over the screen. No other applications can use it anymore. It makes the graphics often a bit faster and allows for some special effects (like gamma settings). If you want to make sure the computer of the player is and stays in the right screen resolution, you best use exclusive mode. A warning is in place though. In exclusive mode no other windows can show. This e.g. means that you cannot use actions that display a message, ask a question, show the highscore list, or show the game information. Also no errors can be reported. In general, when something goes wrong in exclusive mode the game ends, and sometimes this does not help and the player has no other option than to restart the computer. So make sure your game works absolutely correct. You cannot run your game in debug mode when using exclusive mode.

Other options

Here you can set a number of additional options. First of all you can set some default keys:

Let <Esc> end the game
When checked, pressing the escape key will end the game. More advanced games normally don't want this to happen because they might want to do some processing (like saving) before ending the game. In this case, uncheck this box and provide your own actions for the escape key. (Clicking on the cross of the window will also generate an escape key event.)

Let <F1> show the game information
When checked pressing the F1 key will display the game information (not in exclusive mode).

Let <F4> switch between screen modes
When checked the F4 key will switch between fullscreen and windowed mode (not in exclusive mode).

Let <F5> and <F6> load and save the game
When checked the player can use <F5> to store the current game situation and <F6> to load the last saved game.

Also you can set the priority of the game process. This priority indicates how much processor time is allotted to the game. In normal mode the operating system tries to give processor time to each process that needs it in some reasonable way. The higher you put the priority the more time is allotted to the game, making it run more smoothly and faster. But other processes get less time (also windows processes so e.g. even the mouse might not move anymore).

Loading options

Here you can indicate what should happen when loading a game. First of all you can specify your own loading image. Secondly, you can indicate whether to display a loading progress bar at the bottom of the image. You have three options here. Either no loading bar is displayed, or the default bar is displayed or you can specify two images: the background of the loading bar and the foreground. You can indicate whether the front progress bar must be scaled (default) or clipped while it becomes longer. In the second case, make sure enough the image is large enough to fill the bar. (Note that both images must be specified in this case, not just one.)

It is possible to indicate that the loading image must be transparent. In this case the left bottom pixel of the background image is used as transparent color. Also the alpha translucency can be indicated. A value of 0 means fully translucent. A value of 255 means fully opaque. (Both only work under Windows 2000, XP, or later.)

Secondly, you can indicate here the icon that should be used for stand-alone games. You can only use 32x32 icons. If you try to select another type of icon you will get a warning.

Finally you can change the unique game id. This id is used for storing the highscore list and save game files. If you release a new version of your game and don't want to take over the old highscore list, you should change this number.

Constants

Under this tab you can define global constants that can be used in all scripts, pieces of code or values for actions. Each constant has a name and a value. Names should follow the same rules as variables, that is, they must start with a letter or underscore symbol and further consist of letters, digits or underscore symbols. You are though strongly recommended to make all your constants easily distinguishable. A usual convention is to use only capital letters and underscores.

A value of a constant should be a constant expression. That is, it is either a constant number or string (with quotes around it) or it is an expression. The expression is evaluated before anything else happens in the game. So it cannot reference the current room, instances or scripts. But it can contain the built-in constants and the names of resources.

You can add a constant using the button Add and delete it using Delete. You can change a constant name or value by clicking on it. There are also buttons to clear all constants or to sort them by name.

Error options

Here you can set a number of options that relate to the way errors are reported.

Display error messages
When checked, error messages are shown to the player (except in exclusive mode). In the final version of the game you might want to uncheck this option.

Write error messages to file game_errors.log
When checked all error messages are written to a file called game_errors.log in the game folder.

Abort on all error messages
Normally, certain errors are fatal while others can be ignored. When checking this option all errors are considered fatal and lead to aborting the game. In the final version of the game you distribute you might want to check this option.

Treat uninitialized variables as 0
One common error is to use a variable before a value is assigned to it. Sometimes this is difficult to avoid. When checking this option such uninitialized variables no longer report an error but are treated as value 0. Be careful though. It might mean that you don't spot typing mistakes anymore.

Info options

Here you can indicate the author of the game, the version of the game, and some information about the game. Also the last changed date is maintained. This is useful if you are working with multiple people on a game or make new, updated version. The information is not accessible when the game is running.


Speed considerations

If you are making complicated games you probably want to make them run as fast as possible. Even though Game Maker does its best to make games run fast, a lot depends on how you design your game. Also, it is rather easy to make games that use large amounts of memory. In this chapter I will give some hints on how to make your games faster and smaller.

First of all, look carefully at the sprites and backgrounds you use. Animated sprites take a lot of memory and drawing lots of sprites takes a lot of time. So make your sprites as small as possible. Remove any invisible area around it (there is a command for this in the sprite editor). Carefully decide which sprites to store in video memory and which ones to only load on use. The same applies to background images. In general you want to load them on use and, in particular when they are large, you don't want to store them in video memory. If you have a covering background, make sure you switch off the use of a background color.

If you use full screen mode or exclusive mode, make sure the size of the room (or window) is never larger than the screen size. Most graphics card can efficiently scale images up but they are very slow in scaling images down! Also, preferably draw as few other things than sprites. This is slow. If you do need them, preferably draw them immediately after each other. Finally, whenever possible, switch off the cursor. It slows down the graphics.

Also be careful with the use of many views. For each view the room is redrawn.

Besides the graphics, there are also other aspects that influence the speed. Make sure you have as few instances as possible. In particular, destroy instances once they are no longer required (e.g. when they leave the room). Avoid lots of work in the step event or drawing event of instances. Often things do not need to be checked in each step. Interpretation of code is reasonably fast, but it is interpreted. Also, some functions and actions take a lot of time; in particular those that have to check all instances (like for example the bounce action).

Think about where to treat the collision events. You normally have two options. Objects that have no collision events at all are treated much faster, so preferably treat them in those objects for which there are just a few instances.

Be careful with using large sound files. They take a lot of memory and also compress badly. You might want to check your sounds and see whether you can sample them down.

Finally, if you want to make a game that many people can play, make sure you test it on older machines.


The Game Maker Language (GML)

Game Maker contains a built-in programming language. This programming language gives you much more flexibility and control than the standard actions. This language we will refer to as GML (the Game Maker Language). In this section we describe the language GML and we give an overview of all the (close to 1000) functions and variables available to control all aspects of your game.

Information on GML can be found in the following pages:

Language overview
Computing things
Game play
User interaction
Game graphics
Sound and music
Splash screens, highscores and other pop-ups
Resources
Changing resources
Files, registry, and executing programs
Data structures
Creating particles
Multiplayer games
Using DLL's


Language overview

Game Maker contains a built-in programming language. This programming language gives you much more flexibility and control than the standard actions. This language we will refer to as GML (the Game Maker Language). There are a number of different places where you can type programs in this language. First of all, when you define scripts. A script is a program in GML. Secondly, when you add a code action to an event. In a code action you again have to provide a program in GML. Thirdly, in the room creation code. And finally, wherever you need to specify a value in an action, you can also use an expression in GML. An expression, as we will see below is not a complete program, but a piece resulting in a value.

In this chapter I will describe the basic structure of programs in GML. When you want to use programs in GML, there are a couple of things you have to be careful about. First of all, for all your resources (sprites, objects, sounds, etc.) you must use names that start with a letter and only consist of letters, digits and the underscore '_' symbol. Otherwise you cannot refer to them from within the program. Make sure all resources have different names. Also be careful not to name resources self, other, global, or all because these have special meaning in the language. Also you should not use any of the keywords, indicated below.

A program

A program consists of a set of instructions, called statements. A program must start with the symbol '{' and end with the symbol '}'. Between these symbols there are the statements. Statements must be separated with a ';' symbol. So the global structure of every program is:

{
  <statement>;
  <statement>;
  ...
}
There are a number of different types of statements, which will be discussed below.

Variables

Like any programming language GML contains variables. Variables are memory locations that store information. They have a name such that you can refer to them. A variable in GML can store either a real number or a string. Variables do not need to be declared like in many other languages. There are a large number of built-in variables. Some are general, like mouse_x and mouse_y that indicate the current mouse position, while all others are local to the object instance for which we execute the program, like x and y that indicate the current position of the instance. A variable has a name that must start with a letter and can contain only letters, numbers, and the underscore symbol '_'. (The maximal length is 64 symbols.) When you use a new variable it is local to the current instance and is not known in programs for other instances (even of the same object). You can though refer to variables in other instances; see below.

Assignments

An assignment stores a value in a variable. An assignment has the form:

<variable> = <expression>;
An expression can be a simple value but can also be more complicated. Rather than assigning a value to a variable, one can also add the value to the current value of the variable using +=. Similar, you can subtract it using -=, multiply it using *=, divide it using /= ,or use bitwise operators using |=, &\, or ^=.

Expressions

Expressions can be real numbers (e.g. 3.4), strings between single or double quotes (e.g. 'hello' or “hello”) or more complicated expressions. For expressions, the following binary operators exist (in order of priority):
  • && || ^^: combine Boolean values (&& = and, || = or, ^^ = xor)
  • < <= == != > >=: comparisons, result in true (1) or false (0)
  • | & ^: bitwise operators (| = bitwise or, & = bitwise and, ^ = bitwise xor)
  • << >>: bitwise operators (<< = shift left, >> = shift right)
  • + -: addition, subtraction
  • * / div mod: multiplication, division, integer division, and modulo
Also, the following unary operators exist:
  • !: not, turns true into false and false into true
  • -: negates the next value
  • ~: negates the next value bitwise
As values you can use numbers, variables, or functions that return a value. Sub-expressions can be placed between brackets. All operators work for real values. Comparisons also work for strings and + concatenates strings. (Please note that, contrary to certain languages, both arguments to a Boolean operation are always computed, even when the first argument already determines the outcome.)

Example

Here is an example with some useless assignments.
{
  x = 23;
  str = 'hello world';
  y += 5;
  x *= y;
  x = y << 2;
  x = 23*((2+4) / sin(y));
  str = 'hello' + " world";
  b = (x < 5) && !(x==2 || x==4);
}

Extra variables

You create new variables by assigning a value to them (no need to declare them first). If you simply use a variable name, the variable will be stored with the current object instance only. So don't expect to find it when dealing with another object (or another instance of the same object) later. You can also set and read variables in other objects by putting the object name with a dot before the variable name.

To create global variables, that are visible to all object instances, precede them with the word global and a dot. So for example you can write:
{
  if (global.doit)
  {
    // do something
    global.doit = false;
  }
}
Sometimes you want variables only within the current piece of code or script. In this way you avoid wasting memory and you are sure there is no naming conflict. It is also faster than using global variables. To achieve this you must declare the variables at the beginning of the piece of code using the keyword var. This declaration looks as follows.

var <varname1>,<varname2>,<varname3>, ...
For example, you can write:

{
  var xx,yy;
  xx = x+10;
  yy = y+10;
  instance_create(xx,yy,ball);
}

Addressing variables in other instances

As described above, you can set variables in the current instance using statements like
x = 3;
But in a number of cases you want to address variables in another instance. For example, you might want to stop the motion of all balls, or you might want to move the main character to a particular position, or, in the case of a collision, you might want to set the sprite for the other instance involved. This can be achieved by preceding the variable name with the name of an object and a dot. So for example, you can write
ball.speed = 0;
This will change the speed of all instances of object ball. There are a number of special "objects".
  • self: The current instance for which we are executing the action
  • other: The other instance involved in a collision event
  • all: All instances
  • noone: No instance at all (sounds weird probably but it does come in handy as we will see later on)
  • global: Not an instance at all, but a container that stores global variables
So, for example, you can use the following kind of statements:

other.sprite_index = sprite5;
all.speed = 0;
global.message = 'A good result';
global.x = ball.x;
Now you might wonder what the last assignment does when there are multiple balls. Well, the first one is taken and its x value is assigned to the global value.

But what if you want to set the speed of one particular ball, rather than all balls. This is slightly more difficult. Each instance has a unique id. When you put instances in a room in the designer, this instance id is shown when you rest the mouse on the instance. These are numbers larger than or equal to 100000. Such a number you can also use as the left-hand side of the dot. But be careful. The dot will get interpreted as the decimal dot in the number. To avoid this, put brackets around it. So for example, assuming the id of the ball is 100032, you can write:
(100032).speed = 0;
When you create an instance in the program, the call returns the id. So a valid piece of program is
{
  nnn = instance_create(100,100,ball);
  nnn.speed = 8;
}
This creates a ball and sets its speed. Note that we assigned the instance id to a variable and used this variable as indication in front of the dot. This is completely valid. Let me try to make this more precise. A dot is actually an operator. It takes a value as left operand and a variable (address) as right operand, and returns the address of this particular variable in the indicated object or instance. All the object names, and the special objects indicated above simply represent values and these can be dealt with like any value. For example, the following program is valid:
{
  obj[0] = ball;
  obj[1] = flag;
  obj[0].alarm[4] = 12;
  obj[1].id.x = 12;
}
The last statement should be read as follows. We take the id of the first flag. For the instance with that id we set the x coordinate to 12.

Object names, the special objects, and the instance id's can also be used in a number of functions. They are actually treated as constants in the programs.

Arrays

You can use 1- and 2-dimensional arrays in GML. Simply put the index between square brackets for a 1-dimensional array, and the two indices with a comma between them for 2-dimensional arrays. At the moment you use an index the array is generated. Each array runs from index 0. So be careful with using large indices because memory for a large array will be reserved. Never use negative indices. The system puts a limit of 32000 on each index and 1000000 on the total size. So for example you can write the following:
{
  a[0] = 1;
  i = 1;
  while (i < 10) { a[i] = 2*a[i-1]; i += 1;}
  b[4,6] = 32;
}

If statement

An if statement has the form

if (<expression>) <statement>
or
if (<expression>) <statement> else <statement>
The statement can also be a block. The expression will be evaluated. If the (rounded) value is <=0 (false) the statement after else is executed, otherwise (true) the other statement is executed. It is a good habit to always put curly brackets around the statements in the if statement. So best use
if (<expression>)
{
  <statement>
}
  else
{
  <statement>
}
Example
The following program moves the object toward the middle of the screen.
{
  if (x<200) {x += 4} else {x -= 4};
}

Repeat statement

A repeat statement has the form
repeat (<expression>) <statement>
The statement is repeated the number of times indicated by the rounded value of the expression.

Example
The following program creates five balls at random positions.
{
  repeat (5) instance_create(random(400),random(400),ball);
}

While statement

A while statement has the form
while (<expression>) <statement>
As long as the expression is true, the statement (which can also be a block) is executed. Be careful with your while loops. You can easily make them loop forever, in which case your game will hang and not react to any user input anymore.

Example
The following program tries to place the current object at a free position (this is about the same as the action to move an object to a random position).
{
  while (!place_free(x,y))
  {
    x = random(room_width);
    y = random(room_height);
  }
}

Do statement

A do statement has the form
do <statement> until (<expression>)
The statement (which can also be a block) is executed until the expression is true. The statement is executed at least once. Be careful with your do loops. You can easily make them loop forever, in which case your game will hang and not react to any user input anymore.

Example
The following program tries to place the current object at a free position (this is about the same as the action to move an object to a random position).
{
  do
  {
    x = random(room_width);
    y = random(room_height);
  }
  until (place_free(x,y))
}

For statement

A for statement has the form
for (<statement1> ; <expression> ; <statement2>) <statement3>
This works as follows. First statement1 is executed. Then the expression is evaluated. If it is true, statement 3 is executed; then statement 2 and then the expression is evaluated again. This continues until the expression is false.

This may sound complicated. You should interpret this as follows. The first statement initializes the for-loop. The expression tests whether the loop should be ended. Statement2 is the step statement that goes to the next loop evaluation.

The most common use is to have a counter run through some range.

Example
The following program initializes an array of length 10 with the values 1-10.
{
  for (i=0; i<=9; i+=1) list[i] = i+1;
}

Switch statement

In a number of situations you want to let your action depend on a particular value. You can do this using a number of if statements but it is easier to use the switch statement. A switch statement has the following form:
switch (<expression>)
{
  case <expression1>: <statement1>; ... ; break;
  case <expression2>: <statement2>; ... ; break;
  ...
  default: <statement>; ...
}
This works as follows. First the expression is executed. Next it is compared with the results of the different expressions after the case statements. The execution continues after the first case statement with the correct value, until a break statement is encountered. If no case statement has the right value, execution is continued after the default statement. (No default statement is required. Note that multiple case statements can be placed for the same statement. Also, the break is not required. If there is no break statement the execution simply continues with the code for the next case statement.

Example
The following program takes action based on a key that is pressed.
switch (keyboard_key)
{
  case vk_left:
  case vk_numpad4:
    x -= 4; break;
  case vk_right:
  case vk_numpad6:
    x += 4; break;
}

Break statement

The break statement has the form
break
If used within a for-loop, a while-loop, a repeat-loop, a switch statement, or a with statement, it end this loop or statement. If used outside such a statement it ends the program (not the game).

Continue statement

The continue statement has the form
continue
If used within a for-loop, a while-loop, a repeat-loop, or a with statement, it continues with the next value for the loop or with statement.

Exit statement

The exit statement has the form
exit
It simply ends the execution of this script or piece of code. (It does not end the execution of the game! For this you need the function game_end(); see below.)

Functions

A function has the form of a function name, followed by zero or more arguments between brackets, separated by commas.
<function>(<arg1>,<arg2>,...)
There are two types of functions. First of all, there is a huge collection of built-in functions, to control all aspects of your game. Secondly, any script you define in your game can be used as a function.

Note that for a function without arguments you still need to use the brackets. Some functions return values and can be used in expressions. Others simply execute commands.

Note that it is impossible to use a function as the lefthand side of an assignment. For example, you cannot write instance_nearest(x,y,obj).speed = 0. Instead you must write (instance_nearest(x,y,obj)).speed = 0.

Scripts

When you create a script, you want to access the arguments passed to it (either when using the script action, or when calling the script as a function from a program (or from another, or even the same script). These arguments are stored in the variables argument0, argument1, ..., argument15. So there can be at most 16 arguments. (Note that when calling the script from an action, only the first 5 arguments can be specified.) You can also use argument[0] etc.

Scripts can also return a value, such that they can be used in expressions. For this end you use the return statement:
return <expression>
Execution of the script ends at the return statement!

Example
Here is the definition for a little script that computes the square of the argument:
{
  return (argument0*argument0);
}
To call a script from within a piece of code, just act the same way as when calling functions. That is, write the script name with the argument values in parentheses.

With constructions

As indicated before, it is possible to read and change the value of variables in other instances. But in a number of cases you want to do a lot more with other instances. For example, imagine that you want to move all balls 8 pixels down. You might think that this is achieved by the following piece of code
ball.y = ball.y + 8;
But this is not correct. The right side of the assignment gets the value of the y-coordinate of the first ball and adds 8 to it. Next this new value is set as y-coordinate of all balls. So the result is that all balls get the same y-coordinate. The statement
ball.y += 8;
will have exactly the same effect because it is simply an abbreviation of the first statement. So how do we achieve this? For this purpose there is the with statement. Its global form is
with (<expression>) <statement>
<expression> indicates one or more instances. For this you can use an instance id, the name of an object (to indicate all instances of this object) or one of the special objects (all, self, other, noone). <statement> is now executed for each of the indicated instances, as if that instance is the current (self) instance. So, to move all balls 8 pixels down, you can type.
with (ball) y += 8;
If you want to execute multiple statements, put curly brackets around them. So for example, to move all balls to a random position, you can use
with (ball)
{
  x = random(room_width);
  y = random(room_height);
}
Note that, within the statement(s), the indicated instance has become the self instance. Within the statements the original self instance has become the other instance. So for example, to move all balls to the position of the current instance, you can type
with (ball)
{
  x = other.x;
  y = other.y;
}
Use of the with statement is extremely powerful. Let me give a few more examples. To destroy all balls you type
with (ball) instance_destroy();
If a bomb explodes and you want to destroy all instances close by you can use
with (all)
{
  if (distance_to_object(other) < 50) instance_destroy();
}

Comment

You can add comment to your programs. Everything on a line after // is not read. You can also make a multi-line comment by placing the text between /* and */. (Colorcoding might not work correctly here! Press F12 to re-colorcode the text if an error occurs.)

Functions and variables in GML

GML contains a large number of built-in functions and variables. With these you can control any part of the game. For all actions there are corresponding functions so you actually don't need to use any actions if you prefer using code. But there are many more functions and variables that control aspects of the game that cannot be used with actions only. So if you want to make advanced games you are strongly advised to read through the following chapters to get an overview of all that is possible. Please note that these variables and functions can also be used when providing values for actions. So even if you don't plan on using code or writing scripts, you will still benefit from this information.

The following convention is used below. Variable names marked with a * are read-only, that is, their value cannot be changed. Variable names with [0..n] after them are arrays. The range of possible indices is given.


Computing things

Game Maker contains a large number of functions to compute certain things. Here is a complete list.

Constants

The following constants exist:

true Equal to 1.
false Equal to 0.
pi Equal to 3.1415...

Real-values functions

The following functions exist that deal with real numbers.

random(x) Returns a random real number between 0 and x. The number is always smaller than x.
abs(x) Returns the absolute value of x.
sign(x) Returns the sign of x (-1, 0 or 1).
round(x) Returns x rounded to the nearest integer.
floor(x) Returns the floor of x, that is, x rounded down to an integer.
ceil(x) Returns the ceiling of x, that is, x rounded up to an integer.
frac(x) Returns the fractional part of x, that is, the part behind the decimal dot.
sqrt(x) Returns the square root of x. x must be non-negative.
sqr(x) Returns x*x.
power(x,n) Returns x to the power n.
exp(x) Returns e to the power x.
ln(x) Returns the natural logarithm of x.
log2(x) Returns the log base 2 of x.
log10(x) Returns the log base 10 of x.
logn(n,x) Returns the log base n of x.
sin(x) Returns the sine of x (x in radians).
cos(x) Returns the cosine of x (x in radians).
tan(x) Returns the tangent of x (x in radians).
arcsin(x) Returns the inverse sine of x.
arccos(x) Returns the inverse cosine of x.
arctan(x) Returns the inverse tangent of x.
arctan2(y,x) Calculates arctan(Y/X), and returns an angle in the correct quadrant.
degtorad(x) Converts degrees to radians.
radtodeg(x) Converts radians to degrees.
min(val1,val2,val3,...) Returns the minimum of the values. The function can have up to 16 arguments. They must either be all real or all strings.
max(val1,val2,val3,...) Returns the maximum of the values. The function can have up to 16 arguments. They must either be all real or all strings.
mean(val1,val2,val3,...) Returns the average of the values. The function can have up to 16 arguments. They must all be real values.
point_distance(x1,y1,x2,y2) Returns the distance between point (x1,y1) and point (x2,y2).
point_direction(x1,y1,x2,y2) Returns the direction from point (x1,y1) toward point (x2,y2) in degrees.
lengthdir_x(len,dir) Returns the horizontal x-component of the vector determined by the indicated length and direction.
lengthdir_y(len,dir) Returns the vertical y-component of the vector determined by the indicated length and direction.
is_real(x) Returns whether x is a real value (as opposed to a string).
is_string(x) Returns whether x is a string (as opposed to a real value).

String handling functions

The following functions deal with characters and string.

chr(val) Returns a string containing the character with asci code val.
ord(str) Returns the asci code of the first character in str.
real(str) Turns str into a real number. str can contain a minus sign, a decimal dot and even an exponential part.
string(val) Turns the real value into a string using a standard format (no decimal places when it is an integer, and two decimal places otherwise).
string_format(val,tot,dec) Turns val into a string using your own format: tot indicates the total number of places and dec indicated the number of decimal places.
string_length(str) Returns the number of characters in the string.
string_pos(substr,str) Returns the position of substr in str (0=no occurrence).
string_copy(str,index,count) Returns a substring of str, starting at position index, and of length count.
string_char_at(str,index) Returns the character in str at position index.
string_delete(str,index,count) Returns a copy of str with the part removed that starts at position index and has length count.
string_insert(substr,str,index) Returns a copy of str with substr added at position index.
string_replace(str,substr,newstr) Returns a copy of str with the first occurrence of substr replaced by newstr.
string_replace_all(str,substr,newstr) Returns a copy of str with all occurrences of substr replaced by newstr.
string_count(substr,str) Returns the number of occurrences of substr in str.
string_lower(str) Returns a lowercase copy of str.
string_upper(str) Returns an uppercase copy of str.
string_repeat(str,count) Returns a string consisting of count copies of str.
string_letters(str) Returns a string that only contains the letters in str.
string_digits(str) Returns a string that only contains the digits in str.
string_lettersdigits(str) Returns a string that contains the letters and digits in str.
The following functions deal with the clipboard for storing text.
clipboard_has_text() Returns whether there is any text on the clipboard.
clipboard_get_text() Returns the current text on the clipboard.
clipboard_set_text(str) Sets the string str on the clipboard.

Dealing with dates and time

In Game Maker there are a number of functions to deal with dates and time. A date-time combination is stored in a real number. The integral part of a date-time value is the number of days that have passed since 12/30/1899. The fractional part of the date-time value is fraction of a 24 hour day that has elapsed. The following functions exist:
date_current_datetime() Returns the date-time value that corresponds to the current moment.
date_current_date() Returns the date-time value that corresponds to the current date only (ignoring the time).
date_current_time() Returns the date-time value that corresponds to the current time only (ignoring the date).
date_create_datetime(year,month,day,hour,minute,second) Creates a date-time value corresponding to the indicated date and time.
date_create_date(year,month,day) Creates a date-time value corresponding to the indicated date.
date_create_time(hour,minute,second) Creates a date-time value corresponding to the indicated time.
date_valid_datetime(year,month,day,hour,minute,second) Returns whether the indicated date and time are valid.
date_create_date(year,month,day) Returns whether the indicated date is valid.
date_create_time(hour,minute,second) Returns whether the indicated time is valid.
date_inc_year(date,amount) Returns a new date that is amount years after the indicated date. amount must be an integer number.
date_inc_month(date,amount) Returns a new date that is amount months after the indicated date. amount must be an integer number.
date_inc_week(date,amount) Returns a new date that is amount weeks after the indicated date. amount must be an integer number.
date_inc_day(date,amount) Returns a new date that is amount days after the indicated date. amount must be an integer number.
date_inc_hour(date,amount) Returns a new date that is amount hours after the indicated date. amount must be an integer number.
date_inc_minute(date,amount) Returns a new date that is amount minutes after the indicated date. amount must be an integer number.
date_inc_second(date,amount) Returns a new date that is amount seconds after the indicated date. amount must be an integer number.
date_get_year(date) Returns the year corresponding to the date.
date_get_month(date) Returns the month corresponding to the date.
date_get_week(date) Returns the week of the year corresponding to the date.
date_get_day(date) Returns the day of the month corresponding to the date.
date_get_hour(date) Returns the hour corresponding to the date.
date_get_minute(date) Returns the minute corresponding to the date.
date_get_second(date) Returns the second corresponding to the date.
date_get_weekday(date) Returns the day of the week corresponding to the date.
date_get_day_of_year(date) Returns the day of the year corresponding to the date.
date_get_hour_of_year(date) Returns the hour of the year corresponding to the date.
date_get_minute_of_year(date) Returns the minute of the year corresponding to the date.
date_get_second_of_year(date) Returns the second of the year corresponding to the date.
date_year_span(date1,date2) Returns the number of years between the two dates. It reports incomplete years as a fraction.
date_month_span(date1,date2) Returns the number of months between the two dates. It reports incomplete months as a fraction.
date_week_span(date1,date2) Returns the number of weeks between the two dates. It reports incomplete weeks as a fraction.
date_day_span(date1,date2) Returns the number of days between the two dates. It reports incomplete days as a fraction.
date_hour_span(date1,date2) Returns the number of hours between the two dates. It reports incomplete hours as a fraction.
date_minute_span(date1,date2) Returns the number of minutes between the two dates. It reports incomplete minutes as a fraction.
date_second_span(date1,date2) Returns the number of seconds between the two dates. It reports incomplete seconds as a fraction.
date_compare_datetime(date1,date2) Compares the two date-time values. Returns -1, 0, or 1 depending on whether the first is smaller, equal, or larger than the second value.
date_compare_date(date1,date2) Compares the two date-time values only taking the date part into account. Returns -1, 0, or 1 depending on whether the first is smaller, equal, or larger than the second value.
date_compare_time(date1,date2) Compares the two date-time values only taking the time part into account. Returns -1, 0, or 1 depending on whether the first is smaller, equal, or larger than the second value.
date_date_of(date) Returns the date part of the indicated date-time value, setting the time part to 0.
date_time_of(date) Returns the time part of the indicated date-time value, setting the date part to 0.
date_datetime_string(date) Returns a string indicating the given date and time in the default format for the system.
date_date_string(date) Returns a string indicating the given date in the default format for the system.
date_time_string(date) Returns a string indicating the given time in the default format for the system.
date_days_in_month(date) Returns the number of days in the month indicated by the date-time value.
date_days_in_year(date) Returns the number of days in the year indicated by the date-time value.
date_leap_year(date) Returns whether the year indicated by the date-time value is a leap year.
date_is_today(date) Returns whether the indicated date-time value is on today.


Game play

There are a large number of variables and functions that you can use to define the game play. These in particular influence the movement and creation of instances, the timing, and the handling of events.

Moving around

Obviously, an important aspect of games is the moving around of object instances. Each instance has two built-in variables x and y that indicate the position of the instance. (To be precise, they indicate the place where the origin of the sprite is placed. Position (0,0) is the top-left corner of the room. You can change the position of the instance by changing its x and y variables. If you want the object to make complicated motions this is the way to go. You typically put this code in the step event for the object.

If the object moves with constant speed and direction, there is an easier way to do this. Each object instance has a horizontal speed (hspeed) and a vertical speed (vspeed). Both are indicated in pixels per step. A positive horizontal speed means a motion to the right, a negative horizontal speed mean a motion to the left. Positive vertical speed is downwards and negative vertical speed is upwards. So you have to set these variables only once (for example in the creating event) to give the object instance a constant motion.

There is quit a different way for specifying motion, using a direction (in degrees 0-359), and a speed (should be non-negative). You can set and read these variables to specify an arbitrary motion. (Internally this is changed into values for hspeed and vspeed.) Also there is the friction and the gravity and gravity direction. Finally, there is the function motion_add(dir,speed) to add a motion to the current one.

To be complete, each instance has the following variables and functions dealing with its position and motion:
x Its x-position.
y Its y-position.
xprevious Its previous x-position.
yprevious Its previous y-position.
xstart Its starting x-position in the room.
ystart Its starting y-position in the room.
hspeed Horizontal component of the speed.
vspeed Vertical component of the speed.
direction Its current direction (0-360, counter-clockwise, 0 = to the right).
speed Its current speed (pixels per step).
friction Current friction (pixels per step).
gravity Current amount of gravity (pixels per step).
gravity_direction Direction of gravity (270 is downwards).
motion_set(dir,speed) Sets the motion with the given speed in direction dir.
motion_add(dir,speed) Adds the motion to the current motion (as a vector addition).
There are a large number of functions available that help you in defining your motions:
place_free(x,y) Returns whether the instance placed at position(x,y) is collision-free. This is typically used as a check before actually moving to the new position.
place_empty(x,y) Returns whether the instance placed at position (x,y) meets nobody. So this function takes also non-solid instances into account.
place_meeting(x,y,obj) Returns whether the instance placed at position (x,y) meets obj. obj can be an object in which case the function returns true is some instance of that object is met. It can also be an instance id, the special word all meaning an instance of any object, or the special word other.
place_snapped(hsnap,vsnap) Returns whether the instance is aligned with the snapping values.
move_random(hsnap,vsnap) Move the instance to a free random, snapped position, like the corresponding action.
move_snap(hsnap,vsnap) Snap the instance, like the corresponding action.
move_towards_point(x,y,sp) Moves the instances with speed sp toward position (x,y).
move_bounce_solid(adv) Bounce against solid instances, like the corresponding action. adv indicates whether to use advance bounce, that also takes slanted walls into account.
move_bounce_all(adv) Bounce against all instances, instead of just the solid ones.
move_contact_solid(dir,maxdist) Move the instance in the direction until a contact position with a solid object is reached. If there is no collision at the current position, the instance is placed just before a collision occurs. If there already is a collision the instance is not moved. You can specify the maximal distance to move (use a negative number for an arbitrary distance).
move_contact_all(dir,maxdist) Same as the previous function but this time you stop at a contact with any object, not just solid objects.
move_outside_solid(dir,maxdist) Move the instance in the direction until it no longer lies within a solid object. If there is no collision at the current position the instance is not moved. You can specify the maximal distance to move (use a negative number for an arbitrary distance).
move_outside_all(dir,maxdist) Same as the previous function but this time you move until outside any object, not just solid objects.
distance_to_point(x,y) Returns the distance of the bounding box of the current instance to (x,y).
distance_to_object(obj) Returns the distance of the instance to the nearest instance of object obj.
position_empty(x,y) Returns whether there is nothing at position (x,y).
position_meeting(x,y,obj) Returns whether at position (x,y) there is an instance obj. obj can be an object, an instance id, or the keywords self, other, or all.

Paths

In Game Maker you can define paths and order instances to follow such paths. Although you can use actions for this, there are functions and variables that give you more flexibility:
path_start(path,speed,endaction,absolute) Starts a path for the current instance. The path is the name of the path you want to start. The speed is the speed with which the path must be followed. A negative speed means that the instance moves backwards along the path. The endaction indicates what should happen when the end of the path is reached. The following values can be used: 0 : stop the path 1: continue from the start position (if the path is not closed we jump to the start position 2: continue from the current position 3: reverse the path, that is change the sign of the speed The argument absolute should be true or false. When true the absolute coordinates of the path are used. When false the path is relative to the current position of the instance. To be more precise, if the speed is positive, the start point of the path will be placed on the current position and the path is followed from there. When the speed is negative the end point of the path will be placed on the current position and the path is followed backwards from there.
path_end() Ends the following of a path for the current instance.
path_index* Index of the current path the instance follows. You cannot change this directly but must use the function above.
path_position Position in the current path. 0 is the beginning of the path. 1 is the end of the path. The value must lie between 0 and 1.
path_positionprevious Previous position in the current path. This can be used e.g. in collision events to set the position on the path back to the previous position.
path_speed Speed (in pixels per step) with which the path must be followed. Use a negative speed to move backwards.
path_orientation Orientation (counter-clockwise) into which the path is performed. 0 is the normal orientation of the path.
path_scale Scale of the path. Increase to make the path larger. 1 is the default value.
path_endaction The action that must be performed at the end of the path. You can use the values indicated above.

Motion planning

Motion planning helps you to move certain instances from a given location to a different location while avoiding collisions with certain other instances (e.g. walls). Motion planning is a difficult problem. It is impossible to give general functions that will work satisfactory in all situations. Also, computing collision free motions is a time-consuming operation. So you have be careful how and when you apply it. Please keep these remarks in mind when you use any of the following functions.

Different forms of motion planning are provided by Game Maker. The simplest form lets an instance take a step towards a particular goal position, trying to go straight if possible but taking a different direction if required. These functions should be used in the step event of an instance. They correspond to the motion planning actions that are also available:

mp_linear_step(x,y,stepsize,checkall) This function lets the instance take a step straight towards the indicated position (x,y). The size of the step is indicated by the stepsize. If the instance is already at the position it will not move any further. If checkall is true the instance will stop when it hits an instance of any object. If it is false it only stops when hitting a solid instance. Note that this function does not try to make detours if it meets an obstacle. It simply fails in that case. The function returns whether the goal position was reached.
mp_potential_step(x,y,stepsize,checkall) Like the previous function, this function lets the instance take a step towards a particular position. But in this case it tries to avoid obstacles. When the instance would run into a solid instance (or any instance when checkall is true) it will change the direction of motion to try to avoid the instance and move around it. The approach is not guaranteed to work but in most easy cases it will effectively move the instance towards the goal. The function returns whether the goal was reached.
mp_potential_settings(maxrot,rotstep,ahead,onspot) The previous function does its work using a number of parameters that can be changed using this function. Globally the method works as follows. It first tries to move straight towards the goal. It looks a number of steps ahead which can be set with the parameter ahead (default 3). Reducing this value means that the instance will start changing direction later. Increasing it means it will start changing direction earlier. If this check leads to a collision it starts looking at directions more to the left and to the right of the best direction. It does this in steps of size rotstep (default 10). Reducing this gives the instance more movement possibilities but will be slower. The parameter maxrot is a bit more difficult to explain. The instance has a current direction. maxrot (default 30) indicates how much it is allowed to change its current direction in a step. So even if it can move e.g. straight to the goal it will only do so if it does not violate this maximal change of direction. If you make maxrot large the instance can change a lot in each step. This will make it easier to find a short path but the path will be uglier. If you make the value smaller the path will be smoother but it might take longer detours (and sometimes even fail to find the goal). When no step can be made the behavior depends on the value of the parameter onspot. If onspot is true (the default value), the instance will rotate on its spot by the amount indicated with maxrot. If it is false it will not move at all. Setting it to false is useful for e.g. cars but reduced the chance of finding a path.
Please note that the potential approach uses only local information. So it will only find a path if this local information is enough to determine the right direction of motion. It for example will fail to find a path out of a maze (most of the time).

The second kind of functions computes a collision-free path for the instance. Once this path has been computed you can assign it to the instance to move towards the goal. The computation of the path will take some time but after that the execution of the path will be fast. Of course this is only valid if the situation has not changed in the meantime. For example, if obstacles change you possibly need to recompute the path. Again notice that these functions might fail. These functions are only available in the registered version of Game Maker.

The first two functions use the linear motion and potential field approach that were also used for the step functions.

mp_linear_path(path,xg,yg,stepsize,checkall) This function computes a straight-line path for the instance from its current position to the position (xg,yg) using the indicated step size. It uses steps like in the function mp_linear_step(). The indicated path must already exist and will be overwritten by the new path. (See a later chapter on how to create and destroy paths.) The function will return whether a path was found. The function will stop and report failure if no straight path exists between start and goal. If it fails still a path is created that runs till the position where the instance was blocked.
mp_potential_path(path,xg,yg,stepsize,checkall,factor) This function computes a path for the instance from its current position and orientation to the position (xg,yg) using the indicated step size trying to avoid collision with obstacles. It uses potential field steps like in the function mp_potential_step() and also the parameters that can be set with mp_potential_settings(). The indicated path must already exist and will be overwritten by the new path. (See a later chapter on how to create and destroy paths.) The function will return whether a path was found. To avoid the function keeping on computing forever you need to provide a length factor larger than 1. The function will stop and report failure if it cannot find a path shorter than this factor times the distance between start and goal. A factor of 4 is normally good enough but if you expect long detours you might make it longer. If it fails still a path is created that runs in the direction of the goal but it will not reach it.
The other functions use a much more complex mechanism using a grid-based approach (sometimes called an A* algorithm). It will be more successful in finding paths (although it still might fail) and will find shorter paths but it required more work on your side. The global idea is as follows. First of all we put a grid on (the relevant part of) the room. You can choose to use a fine grid (which will be slower) or a coarse grid. Next, for all relevant objects we determine the grid cells they overlap (either using bounding boxes or precise checking) and mark these cells as being forbidden. So a cell will be marked totally forbidden, even if it only partially overlaps with an obstacle. Finally we specify a start and a goal position (which must lie in free cells) and the function computes the shortest path (actually close to the shortest) between these. The path will run between centers of free cells. So if the cells are large enough such that the instance placed at its center will lie completely inside it this will be successful. This path you can now give to an instance to follow.

The grid-based approach is very powerful (and is used in many professional games) but it requires that you do some careful thinking. You must determine which area and cell size are good enough for solving the game. Also you must determine which objects must be avoided and whether precise checking is important. All these parameters strongly influence the efficiency of the approach.

In particular the size of the cells is crucial. Remember that the cells must be large enough such that the moving object placed with its origin on the center of a cell must lie completely inside the cell. (Be careful about the position of the origin of the object. Also realize that you can shift the path if the origin of the object is not in its center!) On the other hand, the smaller the cells the more possible paths exist. If you make cells too large openings between obstacles might get closed because all cells intersect an obstacle. The actual functions for the grid-based approach are as follows:

mp_grid_create(left,top,hcells,vcells,cellwidth,cellheight) This function creates the grid. It returns an index that must be used in all other calls. You can create and maintain multiple grid structures at the same moment. left and top indicate the position of the top-left corner of the grid. hcells and vcells indicate the number of horizontal and vertical cells. Finally cellwidth and cellheight indicate the size of the cells.
mp_grid_destroy(id) Destroys the indicated grid structure and frees its memory. Don't forget to call this if you don't need the structure anymore.
mp_grid_clear_all(id) Mark all cells in the grid to be free.
mp_grid_clear_cell(id,h,v) Clears the indicated cell. Cell 0,0 is the top left cell.
mp_grid_clear_rectangle(id,left,top,right,bottom) Clears all cells that intersect the indicated rectangle (in room coordinates).
mp_grid_add_cell(id,h,v) Marks the indicated cell as being forbidden. Cell 0,0 is the top left cell.
mp_grid_add_rectangle(id,left,top,right,bottom) Marks all cells that intersect the indicated rectangle as being forbidden.
mp_grid_add_instances(id,obj,prec) Marks all cells that intersect an instance of the indicated object as being forbidden. You can also use an individual instance by making obj the id of the instance. Also you can use the keyword all to indicate all instances of all objects. prec indicate whether precise collision checking must be used (will only work if precise checking is enabled for the sprite used by the instance).
mp_grid_path(id,path,xstart,ystart,xgoal,ygoal,allowdiag) Computes a path through the grid. path must indicate an existing path that will be replaced by the computer path. xstart and ystart indicate the start of the path and xgoal and ygoal the goal. allowdiag indicates whether diagonal moves are allowed instead of just horizontal or vertical. The function returns whether it succeeded in finding a path. (Note that the path is independent of the current instance; It is a path through the grid, not a path for a specific instance.)
mp_grid_draw(id) This function draws the grid with green cells being free and red cells being forbidden. This function is very slow and only provided as a debug tool.

Collision checking

When planning motions or deciding on certain actions, it is often important to see whether there are collisions with other objects at certain places. The following routines can be used for this. All these have three arguments in common: The argument obj can be an object, the keyword all, or the id of an instance. The argument prec indicates whether the check should be precise or only based on the bounding box of the instance. Precise checking is only done when the sprite for the instance has the precise collision checking set. The argument notme can be set to true to indicate that the calling instance should not be checked. All these functions return either the id of one of the instances that collide, or they return a negative value when there is no collision.
collision_point(x,y,obj,prec,notme) This function tests whether at point (x,y) there is a collision with entities of object obj.
collision_rectangle(x1,y1,x2,y2,obj,prec,notme) This function tests whether there is a collision between the (filled) rectangle with the indicated opposite corners and entities of object obj. For example, you can use this to test whether an area is free of obstacles.
collision_circle(xc,yc,radius,obj,prec,notme) This function tests whether there is a collision between the (filled) circle centered at position (xc,yc) with the given radius and entities of object obj. For example, you can use this to test whether there is an object close to a particular location.
collision_ellipse(x1,y1,x2,y2,obj,prec,notme) This function tests whether there is a collision between the (filled) ellipse with the indicated opposite corners and entities of object obj.
collision_line(x1,y1,x2,y2,obj,prec,notme) This function tests whether there is a collision between the line segment from (x1,y1) to (x2,y2) and entities of object obj. This is a powerful function. You can e.g. use it to test whether an instance can see another instance by checking whether the line segment between them intersects a wall.

Instances

In the game, the basic units are the instances of the different objects. During game play you can change a number of aspects of these instances. Also you can create new instances and destroy instances. Besides the movement related variables discussed above and the drawing related variables discussed below, each instance has the following variables:

object_index* Index of the object this is an instance of. This variable cannot be changed.
id* The unique identifier for the instance (>= 100000). (Note that when defining rooms the id of the instance under the mouse is always indicated.)
mask_index Index of the sprite used as mask for collisions. Give this a value of -1 to make it the same as the sprite_index.
solid Whether the instance is solid. This can be changed during the game.
persistent Whether the instance is persistent and will reappear when moving to another room. You often want to switch persistence off at certain moments. (For example if you go back to the first room.)
There is one problem when dealing with instances. It is not so easy to identify individual instances. They don't have a name. When there is only one instance of a particular object you can use the object name but otherwise you need to get the id of the instance. This is a unique identifier for the instance. you can use it in with statements and as object identifier. Fortunately there are a number of variables and routines that help you locate instance id's.

instance_count* Number of instances that currently exist in the room.
instance_id[0..n-1]* The id of the particular instance. Here n is the number of instance. Note that the assignment of the instances to the instance id's changes every step so you cannot use values from previous steps.
Let me give an example. Assume each unit in your game has a particular power and you want to locate the strongest one, you could use the following code:
{
  maxid = -1;
  maxpower = 0;
  for (i=0; i<instance_count; i+=1)
  {
    iii = instance_id[i];
    if (iii.object_index == unit)
    {
      if (iii.power > maxpower)
        {maxid = iii; maxpower = iii.power;}
    }
  }
}
After the loop maxid will contain the id of the unit with largest power. (Don't destroy instances during such a loop because they will automatically be removed from the array and as a result you will start skipping instances.)
instance_find(obj,n) Returns the id of the (n+1)'th instance of type obj. obj can be an object or the keyword all. If it does not exist, the special object noone is returned. Note that the assignment of the instances to the instance id's changes every step so you cannot use values from previous steps.
instance_exists(obj) Returns whether an instance of type obj exists. obj can be an object, an instance id, or the keyword all.
instance_number(obj) Returns the number of instances of type obj. obj can be an object or the keyword all.
instance_position(x,y,obj) Returns the id of the instance of type obj at position (x,y). When multiple instances are at that position the first is returned. obj can be an object or the keyword all. If it does not exist, the special object noone is returned.
instance_nearest(x,y,obj) Returns the id of the instance of type obj nearest to (x,y). obj can be an object or the keyword all.
instance_furthest(x,y,obj) Returns the id of the instance of type obj furthest away from (x,y). obj can be an object or the keyword all.
instance_place(x,y,obj) Returns the id of the instance of type obj met when the current instance is placed at position (x,y). obj can be an object or the keyword all. If it does not exist, the special object noone is returned.
The following functions can be used for creating and destroying instances.
instance_create(x,y,obj) Creates an instance of obj at position (x,y). The function returns the id of the new instance.
instance_copy(performevent) Creates a copy of the current instance. The argument indicates whether the creation event must be executed for the copy. The function returns the id of the new copy.
instance_destroy() Destroys the current instance.
instance_change(obj,perf) Changes the instance into obj. perf indicates whether to perform the destroy and creation events.
position_destroy(x,y) Destroy all instances whose sprite contains position (x,y).
position_change(x,y,obj,perf) Change all instances at (x,y) into obj. perf indicates whether to perform the destroy and creation events.

Deactivating instances

When you create large room, for example in platform games, with a small view, many instances lie outside the view. Such instances though are still active and will execute their events. Also when e.g. performing collision checks these instances are taken into account. This can cost a lot of time, which is often not necessary. (For example, often it is not important whether instances outside the view move.) To solve this problem Game Maker contains some functions to deactivate and activate instances. Before using them you must though clearly understand how they work.

When you deactivate instance they are in some sense removed from the game. They are not visible anymore not are any events executed for them. So for all actions and functions they don't exist anymore. This saves a lot of time but you have to be careful. For example, when you delete all instances of a particular type, deactivated instances are not deleted (because they don't exist). So don't think that a key a player picks up can unlock a deactivated door.

The most crucial mistake you can make is to deactivate the instance that is responsible for the activation. To avoid this some of the routines below allow you to indicate that the calling instance should not be deactivated itself.

Here are the available routines:
instance_deactivate_all(notme) Deactivates all instances in the room. If notme is true the calling instance is not deactivated (which is normally what you want).
instance_deactivate_object(obj) Deactivates all instances in the room of the given object. You can also use all to indicate that all instances must be deactivated or the id of an instance to deactivate an individual instance.
instance_deactivate_region(left,top,width,height,inside,notme) Deactivates all instances in the indicated region (that is, those whose bounding box lies partially inside the region). If inside is false the instances completely outside the region are deactivated. If notme is true the calling instance is not deactivated (which is normally what you want).
instance_activate_all() Activates all instances in the room.
instance_activate_object(obj) Activates all instances in the room of the given object. You can also use all to indicate that all instances must be activated or the id of an instance to activate an individual instance.
instance_activate_region(left,top,width,height,inside) Activates all instances in the indicated region. If inside is false the instances completely outside the region are activated.
For example, to deactivate all instances outside the view and activate the ones inside the view, you could place the following code in the step event of the moving character:
{
  instance_activate_all();
  instance_deactivate_region(view_left[0],view_top[0],
                        view_width[0],view_height[0],false,true);
}
In practice you might want to use a region slightly larger than the view.

Timing

Good games required careful timing of things happening. Fortunately Game Maker does most of the timing for you. It makes sure things happen at a constant rate. This rate is defined when defining the rooms. But you can change it using the global variable room_speed. So for example, you can slowly increase the speed of the game, making it more difficult, by adding a very small amount (like 0.001) to room_speed in every step. If your machine is slow the game speed might not be achieved. This can be checked using the variable fps that constantly monitors the actual number of frames per second. Finally, for some advance timing you can use the variable current_time that gives the number of milliseconds since the computer was started. Here is the total collection of variables available (only the first one can be changed):

room_speed Speed of the game in the current room (in steps per second).
fps* Number of frames that are actually drawn per second.
current_time* Number of milliseconds that have passed since the system was started.
current_year* The current year.
current_month* The current month.
current_day* The current day.
current_weekday* The current day of the week (1=sunday, ..., 7=saturday).
current_hour* The current hour.
current_minute* The current minute.
current_second* The current second.
Sometimes you might want to stop the game for a short while. For this, use the sleep function.
sleep(numb) Sleeps numb milliseconds.
As you should know, every instance has 8 different alarm clocks that you can set. To change the values (or get the values) of the different alarm clocks use the following variable:
alarm[0..7] Value of the indicated alarm clock. (Note that alarm clocks only get updated when the alarm event for the object contains actions!)
We have seen that for complex timing issues you can use the time line resource. Each instance can have a time line resource associated with it. The following variables deal with this:
timeline_index Index of the time line associated with the instance. You can set this to a particular time line to use that one. Set it to -1 to stop using a time line for the instance.
timeline_position Current position within the time line. You can change this to skip certain parts or to repeat parts.
timeline_speed Normally, in each step the position in the time line is increased with 1. You can change this amount by setting this variable to a different value. You can use reals, e.g. 0.5. If the value is larger than one, several moments can happen within the same time step. They will all be performed in the correct order, so no actions will be skipped.

Rooms and score

Games work in rooms. Each room has an index that is indicated by the name of the room. The current room is stored in variable room. You cannot assume that rooms are numbered in a consecutive order. So never add or subtract a number from the room variable. Instead use the functions and variables indicated below. So a typical piece of code you will use is:
{
  if (room != room_last)
  {
    room_goto_next();
  }
    else
  {
    game_end();
  }
}
The following variables and functions exist that deal with rooms.
room Index of the current room; can be changed to go to a different room, but you better use the routines below.
room_first* Index of the first room in the game.
room_last* Index of the last room in the game.
room_goto(numb) Goto the room with index numb.
room_goto_previous() Go to the previous room.
room_goto_next() Go to the next room.
room_restart() Restart the current room.
room_previous(numb) Return the index of the room before numb (-1 = none) but don't go there.
room_next(numb) Return the index of the room after numb (-1 = none).
game_end() End the game.
game_restart() Restart the game.
Rooms have a number of additional properties:
room_width* Width of the room in pixels.
room_height* Height of the room in pixels.
room_caption Caption string for the room that is displayed in the caption of the window.
room_persistent Whether the current room is persistent.
Many games offer the player the possibility to save the game and load a saved game. In Game Maker this happens automatically when the player press <F5> for saving and <F6> for loading. You can also save and load games from within a piece of code (note that loading only takes place at the end of the current step).
game_save(string) Save the game to the file with name string.
game_load(string) Load the game from the file with name string.
Another important aspect of many games is the score, the health, and the number of lives. Game Maker keeps track of the score in a global variable score and the number of lives in a global variable lives. You can change the score by simply changing the value of this variable. The same applies to health and lives. If lives is larger than 0 and becomes smaller than or equal to 0 the no-more-lives event is performed for all instances. If you don't want to show the score and lives in the caption, set the variable show_score, etc., to false. Also you can change the caption. For more complicated games you better display the score yourself.
score The current score.
lives Number of lives.
health The current health (0-100).
show_score Whether to show the score in the window caption.
show_lives Whether to show the number of lives in the window caption.
show_health Whether to show the health in the window caption.
caption_score The caption used for the score.
caption_lives The caption used for the number of lives.
caption_health The caption used for the health.
There is also a built-in mechanism to keep track of a highscore list. It can contain up to ten names.

Generating events

As you know, Game Maker is completely event driven. All actions happen as the result of events. There are a number of different events. Creation and destroy events happen when an instance is created or destroyed. In each step, the system first handles the alarm events. Next it handles keyboard and mouse events and next the step event. After this the instances are set to their new positions after which the collision event is handled. Finally the draw event is used to draw the instances (note that when there are multiple views the draw event is called multiple times in each step). You can also apply an event to the current instance from within a piece of code. The following functions exist:
event_perform(type,numb) Performs event numb of the indicated type to the current instance. The following event types can be indicated:
ev_create
ev_destroy
ev_step
ev_alarm
ev_keyboard
ev_mouse
ev_collision
ev_other
ev_draw
ev_keypress
ev_keyrelease
When there are multiple events of the given type, numb can be used to specify the precise event. For the alarm event numb can range from 0 to 7. For the keyboard event you have to use the keycode for the key. For mouse events you can use the following constants:
ev_left_button
ev_right_button
ev_middle_button
ev_no_button
ev_left_press
ev_right_press
ev_middle_press
ev_left_release
ev_right_release
ev_middle_release
ev_mouse_enter
ev_mouse_leave
ev_global_press
ev_global_release
ev_joystick1_left
ev_joystick1_right
ev_joystick1_up
ev_joystick1_down
ev_joystick1_button1
ev_joystick1_button2
ev_joystick1_button3
ev_joystick1_button4
ev_joystick1_button5
ev_joystick1_button6
ev_joystick1_button7
ev_joystick1_button8
ev_joystick2_left
ev_joystick2_right
ev_joystick2_up
ev_joystick2_down
ev_joystick2_button1
ev_joystick2_button2
ev_joystick2_button3
ev_joystick2_button4
ev_joystick2_button5
ev_joystick2_button6
ev_joystick2_button7
ev_joystick2_button8
For the collision event you give the index of the other object. Finally, for the other event you can use the following constants:
ev_outside
ev_boundary
ev_game_start
ev_game_end
ev_room_start
ev_room_end
ev_no_more_lives
ev_no_more_health
ev_animation_end
ev_end_of_path
ev_user0
ev_user1
ev_user2
ev_user3
ev_user4
ev_user5
ev_user6
ev_user7
For the step event you give the index can use the following constants:
ev_step_normal
ev_step_begin
ev_step_end
event_perform_object(obj,type,numb) This functions works the same as the function above except that this time you can specify events in another object. Note that the actions in these events are applied to the current instance, not to instances of the given object..
event_user(numb) In the other events you can also define 8 user events. These are only performed if you call this function. numb must lie in the range 0 to 7.
event_inherited() Performs the inherited event. This only works if the instance has a parent object.
You can get information about the current event being executed using the following read-only variables:
event_type* Type of the current event begin executed.
event_number* Number of the current event begin executed.
event_object* The object index for which the current event is being executed.
event_action* The index of the action that is currently being executed (0 is the first in the event, etc.).

Miscellaneous variables and functions

Here are some variables and functions that deal with errors.
error_occurred Indicates whether an error has occurred
error_last String indicating the last error message
show_debug_message(str) Shows the string in debug mode
The following functions exist that allows you to check whether certain variables exist and with which you can set variables and get their values. In all these functions the variable name is passed as a string!
variable_global_exists(name) Returns whether a global variable with the given name (a string) exists.
variable_local_exists(name) Returns whether a local variable with the given name (a string) exists for the current instance.
variable_global_get(name) Returns the value of the global variable with the given name (a string).
variable_global_array_get(name,ind) Returns the value of index ind of the global array variable with the given name (a string).
variable_global_array2_get(name,ind1,ind2) Returns the value of index ind1,ind2 of the global 2-dimensional array variable with the given name (a string).
variable_local_get(name) Returns the value of the local variable with the given name (a string).
variable_local_array_get(name,ind) Returns the value of index ind of the local array variable with the given name (a string).
variable_local_array2_get(name,ind1,ind2) Returns the value of index ind1,ind2 of the local 2-dimensional array variable with the given name (a string).
variable_global_set(name,value) Sets the global variable with the given name (a string) to the given value.
variable_global_array_set(name,ind,value) Sets the index ind in the global array variable with the given name (a string) to the given value.
variable_global_array2_set(name,ind1,ind2,value) Sets the index ind1,ind2 in the global 2-dimensional array variable with the given name (a string) to the given value.
variable_local_set(name,value) Sets the local variable with the given name (a string) to the given value.
variable_local_array_set(name,ind,value) Sets the index ind in the local array variable with the given name (a string) to the given value.
variable_local_array2_set(name,ind1,ind2,value) Sets the index ind1,ind2 in the local 2-dimensional array variable with the given name (a string) to the given value.
For example, you can write:
{
  if variable_global_exists('ammunition')
    global.ammunition += 1
  else
    global.ammunition = 0
}
You can also use these functions to pass variables to a script in a sort of by-reference way, by passing their names as strings and using the functions to change them.

You can change the program priority using the following function:
set_program_priority(priority) Sets the priority for the program. You can indicate a value between -3 and +3. A value of -3 means that the program will only run if no other process on the computer requires processing time, or stated differently, when all other processes are idle. Values of -2 and -1 are below normal, so other processes will get priority. 0 is the normal value. +1 and +2 give a higher priority, resulting possibly in higher speed and more smooth game flow. But other processes will get much fewer processing time. +3 indicates real-time mode. In real-time mode basically all time is allotted to the game. This can lead to serious problems with any other applications running on the computer. Also keyboard events and e.g. the pressing of the close box might no longer be recorded by Windows. So only use this if you run the game in exclusive mode and want all the processor time. Also better check carefully before using it.


User interaction

There is no game without interaction with the user. The standard way of doing this in Game Maker is to put actions in mouse or keyboard events. But sometimes you need more control. From within a piece of code you can check whether certain keys on the keyboard are pressed and you can check for the position of the mouse and whether its buttons are pressed. Normally you check these aspects in the step event of some controller object and take action accordingly. The following variables and functions exist:
mouse_x* X-coordinate of the mouse in the room. Cannot be changed.
mouse_y* Y-coordinate of the mouse in the room. Cannot be changed.
mouse_button Currently pressed mouse button. As value use mb_none, mb_any, mb_left, mb_middle, or mb_right.
keyboard_lastkey Keycode of last key pressed. See below for keycode constants. You can change it, e.g. set it to 0 if you handled it.
keyboard_key Keycode of current key pressed (see below; 0 if none).
keyboard_lastchar Last character pressed (as string).
keyboard_string String containing the last at most 1024 characters typed. This string will only contain the printable characters typed. It also correctly responds to pressing the backspace key by erasing the last character.
Sometime it is useful to map one key to another. For example you might want to allow the player to use both the arrow keys and the numpad keys. Rather than duplicating the actions you can map the numpad keys to the arrow keys. Also you might want to implement a mechanism in which the player can set the keys to use. For this the following functions are available
keyboard_set_map(key1,key2) Maps the key with keycode key1 to key2.
keyboard_get_map(key) Returns the current mapping for key.
keyboard_unset_map() Resets all keys to map to themselves.
To check whether a particular key or mouse button is pressed you can use the following functions. This is in particular useful when multiple keys are pressed simultaneously.
keyboard_check(key) Returns whether the key with the particular keycode is pressed.
keyboard_check_direct(key) Returns whether the key with the particular keycode is pressed by checking the hardware directly. The result is independent of which application has focus. It allows for a few more checks. In particular you can use keycodes vk_lshift, vk_lcontrol, vk_lalt, vk_rshift, vk_rcontrol and vk_ralt to check whether the left or right shift, control or alt key is pressed. (This does not work under windows 95!).
mouse_check_button(numb) Returns whether the mouse button is pressed (use as values mb_none, mb_left, mb_middle, or mb_right).
The following routines can be used to manipulate the keyboard state:
keyboard_get_numlock() Returns whether the numlock is set.
keyboard_set_numlock(on) Sets (true) or unsets (false) the numlock. (Does not work under Windows 95.)
keyboard_key_press(key) Simulates a press of the key with the indicated keycode.
keyboard_key_release(key) Simulates a release of the key with the indicated keycode.
The following constants for virtual keycodes exist:
vk_nokey keycode representing that no key is pressed
vk_anykey keycode representing that any key is pressed
vk_left keycode for left arrow key
vk_right keycode for right arrow key
vk_up keycode for up arrow key
vk_down keycode for down arrow key
vk_enter enter key
vk_escape escape key
vk_space space key
vk_shift shift key
vk_control control key
vk_alt alt key
vk_backspace backspace key
vk_tab tab key
vk_home home key
vk_end end key
vk_delete delete key
vk_insert insert key
vk_pageup pageup key
vk_pagedown pagedown key
vk_pause pause/break key
vk_printscreen printscreen/sysrq key
vk_f1 ... vk_f12 keycodes for the function keys F1 to F12
vk_numpad0 ... vk_numpad9 number keys on the numeric keypad
vk_multiply multiply key on the numeric keypad
vk_divide divide key on the numeric keypad
vk_add add key on the numeric keypad
vk_subtract subtract key on the numeric keypad
vk_decimal decimal dot keys on the numeric keypad
For the letter keys use for example ord('A'). (The capital letters.) The following constants can only be used in keyboard_check_direct:

vk_lshift left shift key
vk_lcontrol left control key
vk_lalt left alt key
vk_rshift right shift key
vk_rcontrol right control key
vk_ralt right alt key
They do not work on older version of Windows!

For example, assume you have an object that the user can control with the arrow keys you can put the following piece of code in the step event of the object:
{
  if (keyboard_check(vk_left))  x -= 4;
  if (keyboard_check(vk_right)) x += 4;
  if (keyboard_check(vk_up))    y -= 4;
  if (keyboard_check(vk_down))  y += 4;
}
Of course it is a lot easier to simply put this in the keyboard events.

There are some additional functions related to interaction.
keyboard_clear(key) Clears the state of the key. This means that it will no longer generate keyboard events until it starts repeating.
mouse_clear(button) Clears the state of the mouse button. This means that it will no longer generate mouse events until the player releases it and presses it again.
io_clear() Clears all keyboard and mouse states.
io_handle() Handle user io, updating keyboard and mouse status.
keyboard_wait() Waits till the user presses a key on the keyboard.
mouse_wait() Waits till the user presses a mouse button.

Joystick support

There are some events associated with joysticks. But to have full control over the joysticks there is a whole set of functions to deal with joysticks. Game Maker supports up to two joysticks. So all of these functions take a joystick id as argument.
joystick_exists(id) Returns whether joystick id (1 or 2) exists.
joystick_name(id) Returns the name of the joystick
joystick_axes(id) Returns the number of axes of the joystick.
joystick_buttons(id) Returns the number of buttons of the joystick.
joystick_has_pov(id) Returns whether the joystick has point-of-view capabilities.
joystick_direction(id) Returns the keycode (vk_numpad1 to vk_numpad9) corresponding to the direction of joystick id (1 or 2).
joystick_check_button(id,numb) Returns whether the joystick button is pressed (numb in the range 1-32).
joystick_xpos(id) Returns the position (-1 to 1) of the x-axis of joystick id.
joystick_ypos(id) Returns the joysticks y-position.
joystick_zpos(id) Returns the joysticks z-position (if it has a z-axis).
joystick_rpos(id) Returns the joysticks rudder position (or fourth axis).
joystick_upos(id) Returns the joysticks u-position (or fifth axis).
joystick_vpos(id) Returns the joysticks v-position (or sixth axis).
joystick_pov(id) Returns the joysticks point-of view position. This is an angle between 0 and 360 degrees. 0 is forwards, 90 to the right, 180 backwards and 270 to the left. When no point-of-view direction is pressed by the user -1 is returned.


Game graphics

An important part of a game is the graphics. Game Maker normally takes care of most of this and for simple games there is need to worry about it. But sometimes you want to take more control. For some aspects there are actions but from code you can control many more aspects. This chapter describes all variables and functions available for this and gives some more information about what is really happening.

Window and cursor

Default the game runs inside a centered window. The player can change this to full screen by pressing the <F4> key unless this was disabled. You can also do this from within the program using the following variable:
full_screen This variable is true when in full-screen mode. You can change the mode by setting this variable to true or false.
Note that in full screen mode the caption and the score are shown on the screen. (This can be avoided using the game options.) In full screen mode the image is either centered or scaled. You can control this using the following variable:
scale_window This variable indicates the percentage of scaling in windowed mode. 100 indicates no scaling.
scale_full This variable indicates the percentage of scaling in fullscreen mode. 100 indicates no scaling. 0 indicates the maximum scaling possible.
Scaled mode can be slow on machines with a slow processor or graphics card. A more general function can be used to set the graphics mode during game play:

set_graphics_mode(exclusive,horres,coldepth,freq,fullscreen,winscale,fullscale) This function sets the graphics mode during run time. exclusive indicated whether to use exclusive graphics mode. horres indicates the horizontal resolutions (use one of the following values: 320, 640, 800, 1024, 1280, 1600). Use 0 to not change the resolution. The correct vertical resolution it taken. coldepth indicates the color depth (16 or 32). frequency indicates the frequency (use one of the following values 60, 70, 75, 80, 100, 120). fullscreen indicates whether to run in fullscreen mode. winscale indicates the scaling factor in windowed mode (1=no scaling). fullscale indicates the scaling factor in fullscreen mode (1 = no scaling, 0 = maximal scaling). Please realize that changing the graphics mode normally results in some flickering of the screen. So only do it when strictly necessary. You can e.g. use this routine to create a first room in which the user can select the resolution. Only available in the registered version.
Default each game runs with a visible cursor. For lots of games you don't want this. To remove the cursor, use the variable:
show_cursor If set to false the cursor is made invisible inside the playing area, otherwise it is made visible.
You can also set the cursor to one of the many predefined cursors in windows using the following function:
set_cursor(cur) Set the cursor to the given value. You can use the following constant:
cr_default
cr_none
cr_arrrow
cr_cross
cr_beam
cr_size_nesw
cr_size_ns
cr_size_nwse
cr_size_we
cr_uparrow
cr_hourglass
cr_drag
cr_nodrop
cr_hsplit
cr_vsplit
cr_multidrag
cr_sqlwait
cr_no
cr_appstart
cr_help
cr_handpoint
cr_size_all
By the way, note that it is very easy to make your own cursor sprite and assign it to the following variable:
cursor_sprite Indicates the sprite to be used to represent the mouse cursor. A value of -1 (default) indicates that no sprite should be drawn. When the sprite is animated it will also be drawn animated.
To change the position of the mouse cursor, use the following function:
mouse_set_screen_position(x,y) Sets the mouse to a particular position on the screen. (Note that you must specify a position on the screen, not a position in the room. If you want a position in the room you have to calculate that yourself using e.g the window position.)
To find out the resolution of the monitor you can use the following two read-only variables:
monitor_width* The width of the monitor, in pixels.
monitor_height* The height of the monitor, in pixels.
To get information about the position of the window on the screen, use the following variables:
window_left The left position of the game window on the screen. You can change this (when not in fullscreen mode) to adapt the position of the window in the screen.
window_top The top position of the game window on the screen. You can change this (when not in fullscreen mode) to adapt the position of the window in the screen.
window_width* The width of the game window on the screen.
window_height* The height of the game window on the screen.
window_client_left* The left position of the client region of the game window on the screen.
window_client_top* The top position of the client region of the game window on the screen.
window_client_width* The width of the client region of the game window on the screen.
window_client_height* The height of the client region of the game window on the screen.

Sprites and images

Each object has a sprite associated with it. This is either a single image or it consists of multiple image. For each instance of the object the program draws the corresponding image on the screen, with its origin (as defined in the sprite properties) at the position (x,y) of the instance. When there are multiple images, it cycles through the images to get an animation effect. There are a number of variables that affect the way the image is drawn. These can be used to change the effects. Each instance has the following variables:
visible If visible is true (1) the image is drawn, otherwise it is not drawn. Invisible instances are still active and create collision events; you only don't see them. Setting the visibility to false is useful for e.g. controller objects (make them non-solid to avoid collision events) or hidden switches.
sprite_index This is the index of the current sprite for the instance. You can change it to give the instance a different sprite. As value you can use the names of the different sprites you defined. Changing the sprite does not change the index of the currently visible sub-image.
sprite_width* Indicates the width of the sprite. This value cannot be changed but you might want to use it.
sprite_height* Indicates the height of the sprite. This value cannot be changed but you might want to use it.
sprite_xoffset* Indicates the horizontal offset of the sprite as defined in the sprite properties. This value cannot be changed but you might want to use it.
sprite_yoffset* Indicates the vertical offset of the sprite as defined in the sprite properties. This value cannot be changed but you might want to use it.
image_number* The number of sub-images for the current sprite for the instance (cannot be changed).
image_index When the image has multiple sub-images the program cycles through them. This variable indicates the currently drawn sub-image (they are numbered starting from 0). You can change the current image by changing this variable. The program will continue cycling, starting at this new index.
image_single Sometimes you want a particular sub-image to be visible and don't want the program to cycle through all of them. This can be achieved by setting this variable to the index of the sub-image you want to see (first sub-image has index 0). Give it a value -1 to cycle through the sub-images. This is useful when an object has multiple appearances. For example, assume you have an object that can rotate and you create a sprite that has sub-images for a number of orientations (counter-clockwise). Then, in the step event of the object you can set
{
  image_single = direction * image_number/360;
}
image_speed The speed with which we cycle through the sub-images. A value of 1 indicates that each step we get the next image. Smaller values will switch sub-images slower, drawing each sub-image multiple times. Larger values will skip sub-images to make the motion faster.
depth Normally images are drawn in the order in which the instances are created. You can change this by setting the image depth. The default value is 0, unless you set it to a different value in the object properties. The higher the value the further the instance is away. (You can also use negative values.) Instances with higher depth will lie behind instances with a lower depth. Setting the depth will guarantee that the instances are drawn in the order you want (e.g. the plane in front of the cloud). Background instances should have a high (positive) depth, and foreground instances should have a low (negative) depth.
image_xscale A scale factor to make larger or smaller images. A value of 1 indicates the normal size. You must separately set the horizontal xscale and vertical yscale. Changing the scale also changes the values for the image width and height and influences collision events as you might expect. Realize that scaled images (in particular when you make them smaller) take more time to draw. Changing the scale can be used to get a 3-D effect.
image_yscale The vertical yscale. 1 is no scaling.
image_alpha Transparency (alpha) value to use when drawing the image. A value of 1 is the normal setting; a value of 0 is completely transparent. Use with care. Drawing partially transparent images takes a lot of time and will slow down the game.
bbox_left* Left side of the bounding box used of the image of the instance (taking scaling into account).
bbox_right* Right side of the bounding box of the instance image
bbox_top* Top side of the bounding box of the instance image.
bbox_bottom* Bottom side of the bounding box of the instance image.

Backgrounds

Each room can have up to 8 backgrounds. Also it has a background color. All aspects of these backgrounds you can change in a piece of code using the following variables (note that some are arrays that range from 0 to 7, indicating the different backgrounds):
background_color Background color for the room.
background_showcolor Whether to clear the window in the background color.
background_visible[0..7] Whether the particular background image is visible.
background_foreground[0..7] Whether the background is actually a foreground.
background_index[0..7] Background image index for the background.
background_x[0..7] X position of the background image.
background_y[0...7] Y position of the background image.
background_width[0...7]* Width of the background image.
background_height[0...7]* Height of the background image.
background_htiled[0..7] Whether horizontally tiled.
background_vtiled[0..7] Whether vertically tiled.
background_xscale[0..7] Horizontal scaling factor for the background.
background_yscale[0..7] Vertical scaling factor for the background.
background_hspeed[0..7] Horizontal scrolling speed of the background (pixels per step).
background_vspeed[0..7] Vertical scrolling speed of the background (pixels per step).
background_alpha[0..7] Transparency (alpha) value to use when drawing the background. A value of 1 is the normal setting; a value of 0 is completely transparent. Use with care. Drawing partially transparent backgrounds takes a lot of time and will slow down the game.

Tiles

As you should know you can add tiles to rooms. A tile is a part of a background resource. Tiles are just visible images. They do not react to events and they do not generate collisions. As a result, tiles are handled a lot faster than objects. Anything that does not need events or collisions can best be done through tiles. Also, often one better uses a tile for the nice graphics while a simple object is used to e.g. generate the collision events.

You actually have more control over tiles than you might think. You can add them when designing the room but you can also add them during the running of the game. You can change their position, and even scale them or make them partially transparent. A tile has the following properties:
  • background. The background resource from which the tile is taken.

  • left, top, width, height. The part of the background that is used.

  • x,y. The position of the top left corner of the tile in the room.

  • depth. The depth of the tile. You can choose any depth you like, making tiles appear between object instances.

  • visible. Whether the tile is visible.

  • xscale, yscale. Each tile can be drawn scaled (default is 1).

  • alpha. An alpha value indicating tile transparency. 1 = not transparent, 0 = fully transparent. You should use this with care because partially transparent tiles are very slow to draw and can lead to problems on certain systems.
To change the properties of a particular tile you need to know its id. When you add tiles when creating rooms the id is shown in the information bar at the bottom. There is also a function to find the id of a tile at a particular position.

The following functions exist that deal with tiles:
tile_add(background,left,top,width,height,x,y,depth) Adds a new tile to the room with the indicated values (see above for their meaning). The function returns the id of the tile that can be used later on.
tile_delete(id) Deletes the tile with the given id.
tile_exists(id) Returns whether a tile with the given id exists.

tile_get_x(id) Returns the x-position of the tile with the given id.
tile_get_y(id) Returns the y-position of the tile with the given id.
tile_get_left(id) Returns the left value of the tile with the given id.
tile_get_top(id) Returns the top value of the tile with the given id.
tile_get_width(id) Returns the width of the tile with the given id.
tile_get_height(id) Returns the height of the tile with the given id.
tile_get_depth(id) Returns the depth of the tile with the given id.
tile_get_visible(id) Returns whether the tile with the given id is visible.
tile_get_xscale(id) Returns the xscale of the tile with the given id.
tile_get_yscale(id) Returns the yscale of the tile with the given id.
tile_get_background(id) Returns the background of the tile with the given id.
tile_get_alpha(id) Returns the alpha value of the tile with the given id.

tile_set_position(id,x,y) Sets the position of the tile with the given id.
tile_set_region(id,left,right,width,height) Sets the region of the tile with the given id in its background.
tile_set_background(id,background) Sets the background for the tile with the given id.
tile_set_visible(id,visible) Sets whether the tile with the given id is visible.
tile_set_depth(id,depth) Sets the depth of the tile with the given id.
tile_set_scale(id,xscale,yscale) Sets the scaling of the tile with the given id.
tile_set_alpha(id,alpha) Sets the alpha value of the tile with the given id.
The following functions deal with layers of tiles, that is, collections of tiles at the same depth.

tile_layer_hide(depth) Hide all tiles at the indicated depth layer.
tile_layer_show(depth) Show all tiles at the indicated depth layer.
tile_layer_delete(depth) Delete all tiles at the indicated depth layer.
tile_layer_shift(depth,x,y) Shift all tiles at the indicated depth layer over the vector x,y. Can be used to create scrolling layers of tiles.
tile_layer_find(depth,x,y) Returns the id of the tile with the given depth at position (x,y). When no tile exists at the position -1 is returned. When multiple tiles with the given depth exist at the position the first one is returned.
tile_layer_delete_at(depth,x,y) Deletes the tile with the given depth at position (x,y). When multiple tiles with the given depth exist at the position they are all deleted.
tile_layer_depth(depth,newdepth) Changes the depth of all tiles at the indicated depth to the new depth. With this function you can move whole tile layers to a new depth.

Drawing functions

It is possible to let objects look rather different from their image. There is a whole collection of functions available to draw different shapes. Also there are functions to draw text. You can only use these in the drawing event of an object; these functions don't make any sense anywhere else in code. Please realize that the graphics hardware in computers only makes the drawing of images fast. So any other drawing routine will be relatively slow. Also Game Maker is optimized towards drawing images. So avoid other drawing routines as much as possible. (Whenever possible, create a bitmap instead.) Also realize that collisions between instances are determined by their sprites (or masks) and not by what you actually draw. The following image related drawing functions exist:
draw_sprite(sprite,subimg,x,y) Draws subimage subimg (-1 = current) of the sprite with index n with its origin at position (x,y).
draw_sprite_ext(sprite,subimg,x,y,xscale,yscale,alpha) Draws the sprite scaled with factors xscale and yscale. alpha indicates the transparency factor with which the images is merged with its background. A value of 0 makes the sprite completely transparent. A value of 1 makes it completely solid. This function can create great effect (for example partially transparent explosions). It is though slow when using a value different from 1 because it is done in software. So use it with care.
draw_sprite_stretched(sprite,subimg,x,y,w,h) Draws the sprite stretched such that it fills the region with top-left corner (x,y) and width w and height h.
draw_sprite_stretched_ext(sprite,subimg,x,y,w,h,alpha) Draws the sprite stretched such that it fills the region with top-left corner (x,y) and width w and height h. alpha indicates the transparency setting.
draw_sprite_tiled(sprite,subimg,x,y) Draws the sprite tiled such that it fills the entire room. (x,y) is the place where one of the sprites is drawn.
draw_sprite_tiled_ext(sprite,subimg,x,y,xscale,yscale,alpha) Draws the sprite tiled such that it fills the entire room but now with scale factors and a transparency setting. It is though slow when using an alpha value different from 1 because it is done in software. So use it with care.
draw_sprite_part(sprite,subimg,left,top,right,bottom,x,y) Draws the indicated part of subimage subimg (-1 = current) of the sprite with its origin at position (x,y).
draw_sprite_part_ext(sprite,subimg,left,top,right,bottom,x,y,xscale,yscale,alpha) Draws the indicated part of subimage subimg (-1 = current) of the sprite with its origin at position (x,y) but now with scale factors and a transparency setting.
draw_sprite_alpha(sprite,subimg,x,y,xscale,yscale,alphaspr,ind) Draws the sprite scaled with factors xscale and yscale. The alpha transparency factor is now determined on a per pixel basis by the intensity in another sprite alphaspr. Of this we take subimage ind. A black pixel makes the sprite completely transparent. A white pixel makes it completely solid. This function can create great effect (for example partially transparent explosions). It is though slow so use it with care. Only available in the registered version.
draw_sprite_part_alpha(sprite,subimg,left,top,right,bottom,x,y,xscale,yscale,alphaspr,ind) Draws the indicated part of subimage subimg (-1 = current) of the sprite with its origin at position (x,y) but now with scale factors and an alpha bitmap. Only available in the registered version.

draw_background(back,x,y) Draws the background at position (x,y).
draw_background_ext(back,x,y,xscale,yscale,alpha) Draws the background scaled with transparency alpha (0-1) (slow when alpha < 1!).
draw_background_stretched(back,x,y,w,h) Draws the background stretched to the indicated region.
draw_background_stretched_ext(back,x,y,w,h,alpha) Draws the background stretched to the indicated region. alpha indicates the transparency setting.
draw_background_tiled(back,x,y) Draws the background tiled such that it fills the entire room.
draw_background_tiled_ext(back,x,y,xscale,yscale,alpha) Draws the background tiled such that it fills the entire room but now with scale factors and a transparency setting.
draw_background_part(back,left,top,right,bottom,x,y) Draws the indicated part of the background with its origin at position (x,y).
draw_background_part_ext(back,left,top,right,bottom,x,y,xscale,yscale,alpha) Draws the indicated part of the background with its origin at position (x,y) but now with scale factors and a transparency setting.
draw_background_alpha(back,x,y,xscale,yscale,alphaback) Draws the background scaled with factors xscale and yscale. The alpha transparency factor is now determined on a per pixel basis by the intensity in another background alphaback. A black pixel makes the background completely transparent. A white pixel makes it completely solid. This function is slow so use it with care. Only available in the registered version.
draw_background_part_alpha(back,left,top,right,bottom,x,y,xscale,yscale,alphaback) Draws the indicated part of the background with its origin at position (x,y) but now with scale factors and an alpha bitmap. Only available in the registered version.

The following drawing functions draw basic shapes. They use a number of properties, in particular the brush and pen color that can be set using certain variables.

draw_pixel(x,y) Draws a pixel at (x,y) in the brush color.
draw_getpixel(x,y) Returns the color of the pixel at (x,y).
draw_fill(x,y) Flood fill from position (x,y) in the brush color.
draw_line(x1,y1,x2,y2) Draws a line from (x1,y1) to (x2,y2).
draw_arrow(x1,y1,x2,y2,size) Draws an arrow from (x1,y1) to (x2,y2). size indicates the size of the arrow in pixels.
draw_circle(x,y,r) Draws a circle at (x,y) with radius r.
draw_ellipse(x1,y1,x2,y2) Draws an ellipse.
draw_rectangle(x1,y1,x2,y2) Draws a rectangle.
draw_roundrect(x1,y1,x2,y2) Draws a rounded rectangle.
draw_triangle(x1,y1,x2,y2,x3,y3) Draws a triangle.
draw_arc(x1,y1,x2,y2,x3,y3,x4,y4) Draws an arc of an ellipse.
draw_chord(x1,y1,x2,y2,x3,y3,x4,y4) Draws a chord of an ellipse.
draw_pie(x1,y1,x2,y2,x3,y3,x4,y4) Draws a pie of an ellipse.
draw_button(x1,y1,x2,y2,up) Draws a button, up indicates whether up (1) or down (0).
draw_text(x,y,string) Draws the string at position (x,y). A # symbol or carriage return chr(13) or linefeed chr(10) are interpreted as newline characters. In this way you can draw multi-line texts. (Use \# to get the # symbol itself.)
draw_text_ext(x,y,string,sep,w) Similar to the previous routine but you can specify two more things. First of all, sep indicates the separation distance between the lines of text in a multiline text. Use -1 to get the default distance. Use w to indicate the width of the text in pixels. Lines that are longer than this width are split-up at spaces or - signs. Use -1 to not split up lines.
draw_text_sprite(x,y,string,sep,w,sprite,firstchar,scale) Drawing text using the functions above is relatively costly. This function works exactly the same as the previous one but takes its character images from a sprite. This sprite must have a subimage for each character. The first character is indicate with the argument firstchar. From this character on the characters should follow the ASCII order. You can check the character map tool of windows to see the correct order of the characters. If you only need the first few (e.g. up to the numbers or the uppercase characters) you don't need to provide the other characters. scale indicates the scale factor used (1 is the normal size). Be careful will scaling though, it can slow down the game considerably. Please realize that these sprites tend to be large. Also, you obviously don't need precise collision checking for them.
draw_polygon_begin() Start describing a polygon for drawing.
draw_polygon_vertex(x,y) Add vertex (x,y) to the polygon.
draw_polygon_end() End the description of the polygon. This function actually draws it.
draw_path(path,x,y,absolute) With this function you can draw the indicated path in the room with its start at position (x,y). If absolute is true the path is drawn at the position where it was defined and the values of x and y are ignored.
draw_healthbar(x1,y1,x2,y2,amount,backcol,mincol,maxcol,direction,showback,showborder) With this function you can draw a healthbar (or any other bar that indicates some value, like e.g. the damage). The arguments x1, y1, x2 and y2 indicate the total area for the bar. amount indicates the percentage of the bar that must be filled (must lie between 0 and 100). backcol is the color of the background for the bar. mincol and maxcol indicate the color when the amount is 0 and 100 respectively. For an amount in between the color is interpolated. So you can easily make a bar that goes e.g. from green to red. The direction is the direction in which the bar is drawn. 0 indicates that the bar is anchored at the left, 1 at the right, 2 at the top and 3 at the bottom. Finally showback indicates whether a background box must be shown and showborder indicated whether the box and bar should have a black border line.
You can change a number of settings, like the color of the lines (pen), region (brush) and font, and many other font properties. The effect of these variables is global! So if you change it in the drawing routine for one object it also applies to other objects being drawn later. You can also use these variables in other event. For example, if they don't change, you can set them once at the start of the game (which is a lot more efficient).
brush_color Color used to fill shapes. A whole range of predefined colors is available:
c_aqua
c_black
c_blue
c_dkgray
c_fuchsia
c_gray
c_green
c_lime
c_ltgray
c_maroon
c_navy
c_olive
c_purple
c_red
c_silver
c_teal
c_white
c_yellow
make_color(red,green,blue) Make other colors using this routine, where red, green and blue must be values between 0 and 255.
brush_style Current brush style used for filling. The following styles are available:
bs_hollow
bs_solid
bs_bdiagonal
bs_fdiagonal
bs_cross
bs_diagcross
bs_horizontal
bs_vertical
pen_color Color of the pen to draw boundaries.
pen_size Size of the pen in pixels.
font_color Color of the font to use.
font_size Size of the font to use (in points).
font_name Name of the font (a string).
font_style Style for the font. The following styles are available (you can add them if you want the combination of the styles):
fs_normal
fs_bold
fs_italic
fs_underline
fs_strikeout
font_angle Angle with which the font is rotated (0-360 degrees). For example, for vertical text use value 90.
font_align Alignment of the text w.r.t. the position given. The following values can be used
fa_left
fa_center
fa_right
font_pixels_per_inch* The user of a computer can change the number of pixels per inch to e.g. get larger fonts. This can be a problem in games because the fonts will then be scaled and might no longer fit. This read-only variable will indicate the actual number of pixels per inch. The normal Windows setting is 96. (A large setting is normally 120.) You can check this variable to see whether this is changed and, if required, adapt the size of the fonts used in the game to this.
The following routines exist that deal with colors:
make_color_rgb(red,green,blue) Returns a color with the indicated red, green, and blue components, where red, green and blue must be values between 0 and 255.
make_color_hsv(hue,saturation,value) Returns a color with the indicated hue, saturation and value components (each between 0 and 255).
color_get_red(col) Returns the red component of the color.
color_get_green(col) Returns the green component of the color.
color_get_blue(col) Returns the blue component of the color.
color_get_hue(col) Returns the hue component of the color.
color_get_saturation(col) Returns the saturation component of the color.
color_get_value(col) Returns the value component of the color.
merge_color(col1,col2,amount) Returns a merged color of col1 and col2. The merging is determined by amount. A value of 0 corresponds to col1, a value of 1 to col2, and values in between to merged values.
Sometimes you want to temporarily change the settings, draw something and then return them to the original settings (in particular when you make some general purpose scripts). For this the following functions exist:
push_graphics_settings() Saves the current graphics settings on an internal stack. You can call this function multiple time. (When you push too many times the settings on the stack without popping them an error message appears. This is normally the result of a bug in your code.)
pop_graphics_settings() Restores the graphics settings from the top of the stack. Each pop call has a corresponding push call. Gives an error when there are no settings on the stack.
A few miscellaneous functions exist:
string_width(string) Width of the string in the current font as it would drawn using the draw_text() function. Can be used for precisely positioning graphics.
string_height(string) Height of the string in the current font as it would drawn using the draw_text() function.
string_width_ext(string,sep,w) Width of the string in the current font as it would drawn using the draw_text_ext() function. Can be used for precisely positioning graphics.
string_height_ext(string,sep,w) Height of the string in the current font as it would drawn using the draw_text_ext() function.
screen_gamma(r,g,b) Sets the gamma correction values. r,g,b must be in the range from -1 to 1. The default is 0. When you use a value smaller than 0 that particular color becomes darker. If you use a value larger than 0 that color becomes lighter. Most of the time you will keep the three values the same. For example, to get the effect of lightning you can temporarily make the three values close to 1. This function works only in exclusive mode!
screen_save(fname) Saves a bmp image of the screen in the given filename. Useful for making screenshots.
screen_save_part(fname,left,top,right,bottom) Saves part of the screen in the given filename. (Note that the right and bottom line of pixels are included.)

Views

As you should know you can define up to eight different views when designing rooms. In this way you can show different parts of the room at different places on the screen. Also, you can make sure that a particular object always stays visible. You can control the views from within code. You can make views visible and invisible and change the place or size of the views on the screen or the position of the view in the room (which is in particular useful when you indicated no object to be visible), you can change the size of the horizontal and vertical border around the visible object, and you can indicate which object must remain visible in the views. The latter is very important when the important object changes during the game. For example, you might change the main character object based on its current status. Unfortunately, this does mean that it is no longer the object that must remain visible. This can be remedied by one line of code in the creation event of all the possible main objects (assuming this must happen in the first view):
{
  view_object[0] = object_index;
}
The following variables exist that influence the view. All, except the first two are arrays ranging from 0 (the first view) to 7 (the last view).
view_enabled Whether views are enabled or not.
view_current* The currently drawn view (0-7). Use this only in the drawing event. You can for example check this variable to draw certain things in only one view. Variable cannot be changed.
view_visible[0..7] Whether the particular view is visible on the screen.
view_left[0..7] Left position of the view in the room.
view_top[0..7] Top position of the view in the room.
view_width[0..7] Width of the view (in pixels).
view_height[0..7] Height of the view (in pixels).
view_x[0..7] X-position of the view on the screen.
view_y[0..7] Y-position of the view on the screen.
view_hborder[0..7] Size of horizontal border around the visible object (in pixels).
view_vborder[0..7] Size of vertical border around visible object (in pixels).
view_hspeed[0..7] Maximal horizontal speed of the view.
view_vspeed[0..7] Maximal vertical speed of the view.
view_object[0..7] Object whose instance must remain visible in the view. If there are multiple instances of this object only the first one is followed. You can also assign an instance id to this variable. In that case the particular instance is followed.
Note that the size of the image on the screen is decided based on the visible views at the beginning of the room. If you change views during the game, they might no longer fit on the screen. The screen size though is not adapted automatically. So if you need this you have to do it yourself, using the following variables:
screen_width Width of the image on the screen, that is, the area in which we draw. When there are no views, this is the same as room_width.
screen_height Height of the image on the screen.

Transitions

As you know, when you move from one room to another you can indicate a transition. You can also set the transition for the next frame without moving to another room using the variable called transition_kind. If you assign a value between 1 and 17 to it the corresponding transition is used (these are the same transitions you can indicate for the rooms). A value of 0 indicates no transition. It only affects the next time a frame is drawn. You can also set these variables before going to the next room using code.
transition_kind Indicates the next frame transition (0-17).
transition_time Total time used for the transition (in milliseconds).
transition_steps Number of steps for the transition.

Repainting the screen

Normally at the end of each step the room is repainted on the screen. But in rare circumstances you need to repaint the room at other moments. This happens when your program takes over the control. For example, before sleeping a long time a repaint might be wanted. Also, when your code displays a message and wants to wait for the player to press a key, you need a repaint in between. There are two different routines to do this.
screen_redraw() Redraws the room by calling all draw events.
screen_refresh() Refreshes the screen using the current room image (not performing drawing events).
To understand the second function, you will need to understand a bit better how drawing works internally. There is internally an image on which all drawing happens. This image is not visible on the screen. Only at the end of a step, after all drawing has taken place, the screen image is replaced by this internal image. (This is called double buffering.) The first function redraws the internal image and then refreshes the screen image. The second function only refreshes the image on the screen.

Now you should also realize why you couldn't use drawing actions or functions in other events than drawing events. They will draw things on the internal image but these won't be visible on the screen. And when the drawing events are performed, first the room background is drawn, erasing all you did draw on the internal image. But when you use screen_refresh() after your drawing, the updated image will become visible on the screen. So, for example, a script can draw some text on the screen, call the refresh function and then wait for the player to press a key, like in the following piece of code.
{
  draw_text(screen_width/2,100,'Press any key to continue.');
  screen_refresh();
  keyboard_wait();
}
Please realize that, when you draw in another event than the drawing event, you draw simply on the image, not in a view! So the coordinates you use are the same as if there are no views.

Be careful when using this technique. Make sure you understand it first and realize that refreshing the screen takes some time.


Sound and music

Sound plays a crucial role in computer games. There are two different types of sounds: background music and sound effects. Background music normally consists of a long piece of midi music that is infinitely repeated. Sound effects on the other hand are short wave files. To have immediate effects, these pieces are stored in memory. So you better make sure that they are not too long.

Sounds are added to your game in the form of sound resources. Make sure that the names you use are valid variable names. There is one aspect of sounds that might be puzzling at first, the number of buffers. The system can play a wave file only once at the same time. This means that when you use the effect again before the previous sound was finished, the previous sound is stopped. This is not very appealing. So when you have a sound effect that is used multiple times simultaneously (like e.g. a gun shot) you need to store it multiple times. This number is the number of buffers. The more buffers for a sound, the more times it can be played simultaneously, but it also uses more memory. So use this with care. Game Maker automatically uses the first buffer available, so once you indicated the number you don't have to worry about it anymore.

There are five basic functions related to sounds, two to play a sound, one to check whether a sound is playing, and two to stop sounds. Most take the index of the sound as argument. The name of the sound represents its index. But you can also store the index in a variable, and use that one.
sound_play(index) Plays the indicates sound once.
sound_loop(index) Plays the indicates sound, looping continuously.
sound_stop(index) Stops the indicates sound. If there are multiple sounds with this index playing simultaneously, all will be stopped.
sound_stop_all() Stops all sounds.
sound_isplaying(index) Returns whether the indicates sound is playing.
It is possible to use further sound effects. These only apply to wave files, not to midi files. When you want to use special sound effects, you have to indicate this in the advanced tab of the sound properties by checking the appropriate box. Note that sounds that enable effects take more resources than other sounds. So only check this box when you use the calls below. There are three types of sound effects. First of all you can change the volume. A value of 0 means no sound at all. A value of 1 is the volume of the original sound. (You cannot indicate a volume larger than the original volume.) Secondly, you can change the pan, that is, the direction from which the sound comes. A value of 0 is completely at the left. A value of 1 indicates completely at the right. 0.5 is the default value that is in the middle. You can use panning to e.g. hear that an object moves from left to right. Finally you can change the frequency of sound. This can be used to e.g. change the speed of an engine. A value of 0 is the lowest frequency; a value of 1 is the highest frequency.
sound_volume(index,value) Changes the volume for the indicates sound (0 = low, 1 = high).
sound_pan(index,value) Changes the pan for the indicates sound (0 = left, 1 = right).
sound_frequency(index,value) Changes the frequency for the indicates sound (0 = low, 1 = high).
Sound is a complicated matter. Midi files are played using the standard multimedia player. Only one midi file can be played at once and there is no support for sound effects. For wave files Game Maker uses DirectSound. In this case all wave files are stored in memory and can have effects. Game Maker actually also tries to play other music files when you specify them, in particular mp3 files. It uses the standard multimedia player for this. Be careful though. Whether this works depends on the system and sometimes on other software installed or running. So you are recommended not to use mp3 files when you want to distribute your games.

There are also a number of functions dealing with playing music from a CD:
cd_init() Must be called before using the other functions. Should also be called when a CD is changed (or simply from time to time).
cd_present() Returns whether a CD is present in the default CD drive.
cd_number() Returns the number of tracks on the CD.
cd_playing() Returns whether the CD is playing.
cd_paused() Returns whether the CD is paused or stopped.
cd_track() Returns the number of the current track (1=the first).
cd_length() Returns the length of the total CD in milliseconds.
cd_track_length(n) Returns the length of track n of the CD in milliseconds.
cd_position() Returns the current position on the CD in milliseconds.
cd_track_position() Returns the current position in the track being played in milliseconds.
cd_play(first,last) Tells the CD to play tracks first until last. If you want to play the full CD give 1 and 1000 as arguments.
cd_stop() Stops playing.
cd_pause() Pauses the playing.
cd_resume() Resumes the playing.
cd_set_position(pos) Sets the position on the CD in milliseconds.
cd_set_track_position(pos) Sets the position in the current track in milliseconds.
cd_open_door() Opens the door of the CD player.
cd_close_door() Closes the door of the CD player.
There is one very general function to access the multimedia functionality of windows.
MCI_command(str) This functions sends the command string to the windows multimedia system using the Media Control Interface (MCI). It returns the return string. You can use this to control all sorts of multimedia devices. See the Windows documentation for information in how to use this command. For example MCI_command('play cdaudio from 1') plays a cd (after you have correctly initialized it using other commands. This function is only for advanced use!


Splash screens, highscores, and other pop-ups

Many games have so-called splash screen. These screens show a video, an image, or some text. Often they are used at the beginning of the game (as an intro), the beginning of a level, or at the end of the game (for example the credits). In Game Maker such splash screens with text, images or video can be shown at any moment during the game. The game is temporarily paused while the splash screen is shown. These are the functions to use:
show_text(fname,full,backcol,delay) Shows a text splash screen. fname is the name of the text file (.txt or .rtf). You must put this file in the folder of the game yourself. Also when you create a stand-alone version of your game, you must not forget to add the file there. full indicates whether to show it in full screen mode. backcol is the background color, and delay is the delay in seconds before returning to the game. (The player can always click with the mouse in the screen to return to the game.)
show_image(fname,full,delay) Shows an image splash screen. fname is the name of the image file (only .bmp, .jpg and .wmf files). You must put this file in the folder of the game yourself. full indicates whether to show it in full screen mode. delay is the delay in seconds before returning to the game.
show_video(fname,full,loop) Shows a video splash screen. fname is the name of the video file (.avi,.mpg). You must put this file in the folder of the game yourself. full indicates whether to show it in full screen mode. loop indicates whether to loop the video.
show_info() Displays the game information form.
load_info(fname) Load the game information from the file named fname. This should be an rtf file. This makes it possible to show different help files at different moments. You can use the data file resource to put these file inside the game.
A number of other functions exist to pop up messages, questions, a menu with choices, or a dialog in which the player can enter a number, a string, or indicate a color or file name:
show_message(str) Displays a dialog box with the string as a message.
show_message_ext(str,but1,but2,but3) Displays a dialog box with the string as a message and up to three buttons. But1, but2 and but3 contain the button text. An empty string means that the button is not shown. In the texts you can use the & symbol to indicate that the next character should be used as the keyboard shortcut for this button. The function returns the number of the button pressed (0 if the user presses the Esc key).
show_question(str) Displays a question; returns true when the user selects yes and false otherwise.
get_integer(str,def) Asks the player in a dialog box for a number. str is the message. def is the default number shown.
get_string(str,def) Asks the player in a dialog box for a string. str is the message. def is the default value shown.
message_background(back) Sets the background image for the pop-up box for any of the functions above. back must be one of the backgrounds defined in the game. If back is partially transparent so is the message image (only for Windows 2000 or later).
message_alpha(alpha) Sets the alpha translucence for the pop-up box for any of the functions above. alpha must lie between 0 (completely translucent) and 1 (not translucent) (only for Windows 2000 or later).
message_button(spr) Sets the sprite used for the buttons in the pop-up box. spr must be a sprite consisting of three images, the first indicates the button when it is not pressed and the mouse is far away, the second indicates the button when the mouse is above it but not pressed and the third is the button when it is pressed.
message_text_font(name,size,color,style) Sets the font for the text in the pop-up box.
message_button_font(name,size,color,style) Sets the font for the buttons in the pop-up box.
message_input_font(name,size,color,style) Sets the font for the input field in the pop-up box.
message_mouse_color(col) Sets the color of the font for the buttons in the pop-up box when the mouse is above it.
message_input_color(col) Sets the color for the background of the input filed in the pop-up box.
message_caption(show,str) Sets the caption for the pop-up box. show indicates whether a border must be shown (1) or not (0) and str indicates the caption when the border is shown.
message_position(x,y) Sets the position of the pop-up box on the screen.
message_size(w,h) Fixes the size of the pop-up box on the screen. If you choose 0 for the width the width of the image is used. If you choose 0 for the height the height is calculated based on the number of lines in the message.
show_menu(str,def) Shows a popup menu. str indicates the menu text. This consists of the different menu items with a vertical bar between them. For example, str = 'menu0|menu1|menu2'. When the first item is selected a 0 is returned, etc. When the player selects no item, the default value def is returned.
show_menu_pos(x,y,str,def) Shows a popup menu as in the previous function but at position x,y on the screen.
get_color(defcol) Asks the player for a color. defcol is the default color. If the user presses Cancel the value -1 is returned.
get_open_filename(filter,fname) Asks the player for a filename to open with the given filter. The filter has the form 'name1|mask1|name2|mask2|...'. A mask contains the different options with a semicolon between them. * means any string. For example: 'bitmaps|*.bmp;*.wmf'. If the user presses Cancel an empy string is returned.
get_save_filename(filter,fname) Asks for a filename to save with the given filter. If the user presses Cancel an empy string is returned.
get_directory(dname) Asks for a directory. dname is the default name. If the user presses Cancel an empy string is returned.
get_directory_alt(capt,root) An alternative way to ask for a directory. capt is the caption to be show. root is the root of the directory tree to be shown. Use the empty string to show the whole tree. If the user presses Cancel an empy string is returned.
show_error(str,abort) Displays a standard error message (and/or writes it to the log file). abort indicates whether the game should abort.
One special pop-up is the highscore list that is maintained for each game. The following functions exist:
highscore_show(numb) Shows the highscore table. numb is the new score. If this score is good enough to be added to the list, the player can input a name. Use -1 to simple display the current list.
highscore_show_ext(numb,back,border,col1,col2,name,size) Shows the highscore table. numb is the new score. If this score is good enough to be added to the list, the player can input a name. Use -1 to simple display the current list. back is the background image to use, border indicates whether or not to show the border. col1 is the color for the new entry, col2 the color for the other entries. name is the name of the font to use, and size is the font size.
highscore_clear() Clears the highscore list.
highscore_add(str,numb) Adds a player with name str and score numb to the list.
highscore_add_current() Adds the current score to the highscore list. The player is asked to provide a name.
highscore_value(place) Returns the score of the person on the given place (1-10). This can be used to draw your own highscore list.
highscore_name(place) Returns the name of the person on the given place (1-10).
draw_highscore(x1,y1,x2,y2) Draws the highscore table in the room in the indicated box, using the current font.
Please realize that none of these pop-ups can be shown when the game runs in exclusive graphics mode!


Resources

In Game Maker you can define various types of resources, like sprites, sounds, data files, objects, etc. In this chapter you will find a number of functions that give information about the resources. In the next chapter you find information on how to modify and create resources on the fly.

Sprites

The following functions will give you information about a sprite:
sprite_exists(ind) Returns whether a sprite with the given index exists.
sprite_get_name(ind) Returns the name of the sprite with the given index.
sprite_get_number(ind) Returns the number of subimages of the sprite with the given index.
sprite_get_width(ind) Returns the width of the sprite with the given index.
sprite_get_height(ind) Returns the height of the sprite with the given index.
sprite_get_transparent(ind) Returns whether the sprite with the given index is transparent.
sprite_get_xoffset(ind) Returns the x-offset of the sprite with the given index.
sprite_get_yoffset(ind) Returns the y-offset of the sprite with the given index.
sprite_get_bbox_left(ind) Returns the left side of the bounding box of the sprite with the given index.
sprite_get_bbox_right(ind) Returns the right side of the bounding box of the sprite with the given index.
sprite_get_bbox_top(ind) Returns the top side of the bounding box of the sprite with the given index.
sprite_get_bbox_bottom(ind) Returns the bottom side of the bounding box of the sprite with the given index.
sprite_get_bbox_mode(ind) Returns the bounding box mode (0=automatic, 1=full image, 2=manual) of the sprite with the given index.
sprite_get_precise(ind) Returns whether the sprite with the given index uses precise collision checking.
sprite_get_videomem(ind) Returns whether the sprite with the given index uses video memory.
sprite_get_loadonuse(ind) Returns whether the sprite with the given index is loaded only on use.
Sprites take lots of memory. To draw them fast enough it is important to store them in video memory. As indicated above you can indicate which sprites should be stored in video memory. Also you can indicate that certain sprites should only be loaded when needed. These sprites will be discarded again at the end of the level. You can partially control this process from code. The following functions exist:
sprite_discard(numb) Frees the (video) memory used for the sprite. If the sprite has the load-on-use property set it will be completely removed. Otherwise, a copy is maintained in normal memory (of which there is normally enough) such that the sprite can be restored when needed.
sprite_restore(numb) Restores the sprite in (video) memory. Normally this happens automatically when the sprite is needed. But this might cause a small hick-up, in particular when load-on-use is set and the sprite is large. So you might want to force this for example at the beginning of the room in which the sprite is needed.
discard_all() Discard all sprites, backgrounds and sounds that have load-on-use set.

Sounds

The following functions will give you information about a sound:
sound_exists(ind) Returns whether a sound with the given index exists.
sound_get_name(ind) Returns the name of the sound with the given index.
sound_get_kind(ind) Returns the kind of the sound with the given index (0=wave, 1=midi, 2=mp3, 10=unknown).
sound_get_buffers(ind) Returns the number of buffers of the sound with the given index.
sound_get_effect(ind) Returns whether the sound with the given index allows for special effects.
sound_get_loadonuse(ind) Returns whether the sound with the given index is loaded only on use.
Sounds use many resources and most systems can store and play only a limited number of sounds. If you make a large game you would like to have more control over which sounds are loaded in memory at what times. You can use the load-on-use option for sounds to make sure sounds are only loaded when used. This though has the problem that you might get a small hick-up when the sound is used first. Also, it does not help much when you have just one large room. For more control you can use the following functions.
sound_discard(index) Frees the memory used for the indicated sound.
sound_restore(index) Restores the indicated sound in memory.
discard_all() Discard all sprites, backgrounds and sounds that have load-on-use set.

Backgrounds

The following functions will give you information about a background:
background_exists(ind) Returns whether a background with the given index exists.
background_get_name(ind) Returns the name of the background with the given index.
background_get_width(ind) Returns the width of the background with the given index.
background_get_height(ind) Returns the height of the background with the given index.
background_get_transparent(ind) Returns whether the background with the given index is transparent.
background_get_videomem(ind) Returns whether the background with the given index uses video memory.
background_get_loadonuse(ind) Returns whether the background with the given index is loaded only on use.
Background images take lots of memory. To draw them fast enough it can be useful to store them in video memory. As indicated in above you can indicate which backgrounds should be stored in video memory. Also you can indicate that certain backgrounds should only be loaded when needed. These backgrounds will be discarded again at the end of the level. You can partially control this process from code. The following functions exist:
background_discard(numb) Frees the (video) memory used for the background image. If the background has the load-on-use property set it will be completely removed. Otherwise, a copy is maintained in normal memory (of which there is normally enough) such that the background can be restored when needed.
background_restore(numb) Restores the background image in (video) memory. Normally this happens automatically when the background is needed. But this might cause a small hick-up, in particular when load-on-use is set and the background is large. So you might want to force this for example at the beginning of the room in which the background is needed.
discard_all() Discard all sprites, backgrounds and sounds that have load-on-use set.

Paths

The following functions will give you information about a path:
path_exists(ind) Returns whether a path with the given index exists.
path_get_name(ind) Returns the name of the path with the given index.
path_get_length(ind) Returns the length of the path with the given index.
path_get_kind(ind) Returns the kind of connections of the path with the given index (0=straight, 1=smooth).
path_get_closed(ind) Returns whether the path is closed or not.
path_get_precision(ind) Returns the precision used for creating smoothed paths.
path_get_number(ind) Returns the number of defining points for the path.
path_get_point_x(ind,n) Returns the x-coordinate of the n'th defining point for the path. 0 is the first point.
path_get_point_y(ind,n) Returns the y-coordinate of the n'th defining point for the path. 0 is the first point.
path_get_point_speed(ind,n) Returns the speed factor at the n'th defining point for the path. 0 is the first point.
path_get_x(ind,pos) Returns the x-coordinate at position pos for the path. pos must lie between 0 and 1.
path_get_y(ind,pos) Returns the y-coordinate at position pos for the path. pos must lie between 0 and 1.
path_get_speed(ind,pos) Returns the speed factor at position pos for the path. pos must lie between 0 and 1.

Scripts

The following functions will give you information about a script:
script_exists(ind) Returns whether a script with the given index exists.
script_get_name(ind) Returns the name of the script with the given index.
script_get_text(ind) Returns the text string of the script with the given index.

Data files

The following functions will give you information about a data file:
datafile_exists(ind) Returns whether a data file with the given index exists.
datafile_get_name(ind) Returns the name of the data file with the given index.
datafile_get_filename(ind) Returns the file name of the data file with the given index.
The following functions can be used if you did not automatically export the data file on game start.
datafile_export(ind,fname) Exports the data file to the given file name (if you did not already do that default on startup).
datafile_discard(ind) Frees the internally stored data for the data file.

Time lines

The following functions will give you information about a timeline:
timeline_exists(ind) Returns whether a time line with the given index exists.
timeline_get_name(ind) Returns the name of the time line with the given index.

Objects

The following functions will give you information about an object:
object_exists(ind) Returns whether an object with the given index exists.
object_get_name(ind) Returns the name of the object with the given index.
object_get_sprite(ind) Returns the index of the default sprite of the object with the given index.
object_get_solid(ind) Returns whether the object with the given index is default solid.
object_get_visible(ind) Returns whether the object with the given index is default visible.
object_get_depth(ind) Returns the depth of the object with the given index.
object_get_persistent(ind) Returns whether the object with the given index is persistent.
object_get_mask(ind) Returns the index of the mask of the object with the given index (-1 if is has no special mask).
object_get_parent(ind) Returns index of the parent object of object ind (-1 if it has no parent).
object_is_ancestor(ind1,ind2) Returns whether object ind2 is an ancestor of object ind1.

Rooms

The following functions will give you information about a room:
room_exists(ind) Returns whether a room with the given index exists.
room_get_name(ind) Returns the name of the room with the given index
Note that because rooms change during the playing of the room there are other routines to get information about the contents of the current room.


Changing resources

These functions are only available in the registered version of Game Maker.

It is possible to create new resources during the game. Also you can change existing resources. This chapter describes the possibilities. Be warned though. Changing resources easily leads to serious errors in your games!!! You must follow the following rules when changing resources:
  • Don't change resources that are being used. This will lead to errors! For example, don't change a sprite that is being used by an instance.
  • When you save the game during playing, added and changed resources are NOT stored with the save game. So if you load the saved game later, these might not be there anymore. In general, when you manipulate resources you can no longer use the built-in system for loading and saving games.
  • When you restart the game during playing, the changed resources are NOT restored to their original shape. In general, when you manipulate resources you can no longer use the action or function to restart the game.
  • Resource manipulation can be slow. For example, changing sprites or backgrounds is relatively slow. So don't use it during the game play.
  • Creating resources during game play (in particular sprites and background) easily uses huge amount of memory. So be extremely careful with this. For example, if you have a 32 frame 128x128 animated sprite and you decide to create 36 rotated copies of it you will use up 36x32x128x128x4 = 36 MB of memory!
  • Make sure you delete resources you no longer need. Otherwise the system soon runs out of memory.
In general, you should not change any resources during game play. Better create and change the resources at the beginning of the game or maybe at the beginning of a room.

Sprites

The following routines are available for manipulating sprite properties:
sprite_set_transparent(ind,transp) Sets the transparency (true or false) of the sprite with the given index.
sprite_set_offset(ind,xoff,yoff) Sets the offset of the sprite with the given index.
sprite_set_bbox_mode(ind,mode) Sets the bounding box mode of the sprite (0=automatic, 1=full image, 2=manual).
sprite_set_bbox(ind,left,top,right,bottom) Sets the bounding box of the sprite with the given index. Works only when the bounding box mode is manual.
sprite_set_precise(ind,mode) Sets whether the sprite with the given index uses precise collision checking (true or false).
sprite_set_videomem(ind,mode) Sets whether the sprite with the given index uses video memory (true or false).
sprite_set_loadonuse(ind,mode) Sets whether the sprite with the given index is loaded only on use(true or false).
The following routines can be used to create new sprites and to remove them.
sprite_duplicate(ind) Creates a duplicate of the sprite with the given index. It returns the index of the new sprite. When an error occurs -1 is returned.
sprite_assign(ind,spr) Assigns the indicated sprite to sprite ind. So this makes a copy of the sprite. In this way you can easily set an existing sprite to a different, e.g. new sprite.
sprite_merge(ind1,ind2) Merges the images from sprite ind2 into sprite ind1, adding them at the end. If the sizes don't match the sprites are stretched to fit. Sprite ind2 is not deleted!
sprite_add(fname,imgnumb,precise,transparent,videomem,loadonuse,xorig,yorig) Add the image stored in the file fname to the set of sprite resources. Only bmp, jpg and gif images can be dealt with. When the image is a bmp or jpg image it can be a strip containing a number of subimages for the sprite next to each other. Use imgnumb to indicate their number (1 for a single image). For (animated) gif images, this argument is not used; the number of images in the gif file is used. precise indicates whether precise collision checking should be used. transparent indicates whether the image is partially transparent, videomem indicates whether the sprite must be stored in videomemory, and loadonuse indicates whether the sprite should only be loaded when used. xorig and yorig indicate the position of the origin in the sprite. The function returns the index of the new sprite that you can then use to draw it or to assign it to the variable sprite_index of an instance. When an error occurs -1 is returned.
sprite_replace(ind,fname,imgnumb,precise,transparent,videomem,loadonuse,xorig,yorig) Same as above but in this case the sprite with index ind is replaced. The function returns whether it is successful.
sprite_create_from_screen(left,top,right,bottom,precise,transparent,videomem,loadonuse,xorig,yorig) Creates a sprite by copying the given area from the screen. (Note that the right and bottom line of pixels are included.) This makes it possible to create any sprite you want. Draw the image on the screen using the drawing functions and next create a sprite from it. (If you don't do this in the drawing event you can even do it in such a way that it is not visible on the screen by not refreshing the screen.) The other parameters are as above. The function returns the index of the new sprite.
sprite_add_from_screen(ind,left,top,right,bottom) Adds an area of the screen as a next subimage to the sprite with index ind. (Note that the right and bottom line of pixels are included.)
sprite_delete(ind) Deletes the sprite from memory, freeing the memory used. (It can no longer be restored.)
The following routines can be used to manipulate a sprite in a way similar to the commands in the sprite editor. These routines are not really fast. You can make them faster by not using precise collision checking for the sprite, setting load on use to true and setting the bounding box mode to manual. Once your manipulated sprite is ready you can set these properties again to the values you want.
sprite_mirror(ind) Mirrors the image(s) in the sprite horizontally.
sprite_flip(ind) Flips the image(s) in the sprite vertically.
sprite_shift(ind,x,y) Shifts the image(s) in the sprite over the given vector.
sprite_rotate180(ind) Rotates the image(s) in the sprite 180 degrees.
sprite_rotate90(ind,clockwise,resize) Rotates the image(s) in the sprite 90 degrees. clockwise indicates whether to rotate clockwise. resize indicates whether the image must be resized (that is width and height reversed).
sprite_rotate(ind,angle,quality) Rotates the image(s) in the sprite over angle degrees. quality gives the quality of the image (1-9). The large the better the quality but the longer it takes.
sprite_resize(ind,w,h,corner) Resizes the image(s) in the sprite to wxh pixels. The image is not scaled. corner indicates the place for the original image (1-9 as in the numberic keypad).
sprite_stretch(ind,w,h,quality) Stretches the image(s) in the sprite to size wxh. quality indicates the quality (1-9).
sprite_scale(ind,xscale,yscale,quality,corner,resize) Scales the image(s) in the sprite with factor xscale and yscale. quality indicates the quality (1-9). resize indicates whether the image must be resized. corner indicates the for the original image (1-9 as in the numberic keypad) if the image is not resized.
sprite_black_white(ind) Turns the image(s) in the sprite into black and white (that is, grayscale).
sprite_set_hue(ind,amount) Sets the hue (0-255) for the image(s) in the sprite.
sprite_set_hue_partial(ind,from,till,newhue) All pixels in the sprite with a hue between from and till are replaced by the new hue.
sprite_shift_hue(ind,amount) Shifts the hue for the image(s) in the sprite by the given amount.
sprite_change_value(ind,amount) Changes the value (0-255) for the image(s) in the sprite.
sprite_change_saturation(ind,amount) Changes the saturation (0-255) for the image(s) in the sprite.
sprite_fade(ind,col,amount) Fades the image(s) in the sprite towards color col with amount (0-255).
sprite_screendoor(ind,amount) Adds an amount (0-255) of screendoor transparency to the image(s) in the sprite.
sprite_blur(ind,amount) Blurs the image(s) in the sprite with a given amount (1-9).

Sounds

The following routines can be used to create new sounds and to remove them.
sound_add(fname,buffers,effects,loadonuse) Adds a sound resource to the game. fname is the name of the sound file. buffers indicates the number of buffers to be used, and effects and loadonuse indicate whether sound effects are allowed and whether the sound should be stored in internal memory (true or false). The function returns the index of the new sound, which can be used to play the sound. (-1 if an error occurred, e.g. the file does not exist).
sound_replace(index,fname,buffers,effects,loadonuse) Same as the previous function but this time not a new sound is created but the existing sound index is replaced, freeing the old sound. Returns whether correct.
sound_delete(index) Deletes the indicated sound, freeing all memory associated with it. It can no longer be restored.

Backgrounds

The following routines are available for manipulating background properties:
background_set_transparent(ind,transp) Sets the transparency (true or false) of the background with the given index.
background_set_videomem(ind,mode) Sets whether the background with the given index uses video memory (true or false).
background_set_loadonuse(ind,mode) Sets whether the background with the given index is loaded only on use(true or false).
The following routines can be used to create new backgrounds and to remove them.
background_duplicate(ind) Creates a duplicate of the background with the given index. It returns the index of the new background. When an error occurs -1 is returned.
background_assign(ind,back) Assigns the indicated background to background ind. So this makes a copy of the background.
background_create_color(w,h,col,transparent,videomem,loadonuse) Creates a background of the given size and with the given color and with the indicated settings. It returns the index of the new background. When an error occurs -1 is returned.
background_create_gradient(w,h,col1,col2,kind,transparent,videomem,loadonuse) Creates a gradient filled background of the given size and with the indicated settings. col1 and col2 indicate the two colors. kind is a number between 0 and 5 indicating the kind of gradient: 0=horizontal 1=vertical, 2= rectangle, 3=ellipse, 4=double horizontal, 5=double vertical. It returns the index of the new background. When an error occurs -1 is returned.
background_add(fname,transparent,videomem,loadonuse) Add the image stored in the file fname to the set of background resources. Only bmp and jpg images can be dealt with. transparent indicates whether the image is partially transparent, videomem indicates whether the background must be stored in videomemory, and loadonuse indicates whether the background should only be loaded when used. The function returns the index of the new background that you can then use to draw it or to assign it to the variable background_index[0] to make it visible in the current room. When an error occurs -1 is returned.
background_replace(ind,fname,transparent,videomem,loadonuse) Same as above but in this case the background with index ind is replaced. The function returns whether it is successful. When the background is currently visible in the room it wil be replaced also.
background_create_from_screen(left,top,right,bottom,transparent,videomem,loadonuse) Creates a background by copying the given area from the screen. (Note that the right and bottom line of pixels are included.) This makes it possible to create any background you want. Draw the image on the screen using the drawing functions and next create a background from it. (If you don't do this in the drawing event you can even do it in such a way that it is not visible on the screen by not refreshing the screen.) The other parameters are as above. The function returns the index of the new background.
background_delete(ind) Deletes the background from memory, freeing the memory used. (It can no longer be restored.)
The following routines can be used to manipulate a background in a way similar to the commands in the background editor.
background_mirror(ind) Mirrors the image in the background horizontally.
background_flip(ind) Flips the image in the background vertically.
background_shift(ind,x,y) Shifts the image in the background over the given vector.
background_rotate180(ind) Rotates the image in the background 180 degrees.
background_rotate90(ind,clockwise,resize) Rotates the image in the background 90 degrees. clockwise indicates whether to rotate clockwise. resize indicates whether the image must be resized (that is width and height reversed).
background_rotate(ind,angle,quality) Rotates the image in the background over angle degrees. quality gives the quality of the image (1-9). The large the better the quality but the longer it takes.
background_resize(ind,w,h,corner) Resizes the image in the background to wxh pixels. The image is not scaled. corner indicates the place for the original image (1-9 as in the numberic keypad).
background_stretch(ind,w,h,quality) Stretches the image in the background to size wxh. quality indicates the quality (1-9).
background_scale(ind,xscale,yscale,quality,corner,resize) Scales the image in the background with factor xscale and yscale. quality indicates the quality (1-9). resize indicates whether the image must be resized. corner indicates the for the original image (1-9 as in the numberic keypad) if the image is not resized.
background_black_white(ind) Turns the image in the background into black and white (that is, grayscale).
background_set_hue(ind,amount) Sets the hue (0-255) for the image in the background.
background_set_hue_partial(ind,from,till,newhue) All pixels in the background with a hue between from and till are replaced by the new hue.
background_shift_hue(ind,amount) Shifts the hue for the image in the background by the given amount.
background_change_value(ind,amount) Changes the value (0-255) for the image in the background.
background_change_saturation(ind,amount) Changes the saturation (0-255) for the image in the background.
background_fade(ind,col,amount) Fades the image in the background towards color col with amount (0-255).
background_screendoor(ind,amount) Adds an amount (0-255) of screendoor transparency to the image in the background.
background_blur(ind,amount) Blurs the image in the background with a given amount (1-9).

Paths

It is possible to create paths and to add points to paths. However, never change a path that is being used by an instance. This can lead to unexpected results. The following functions exist:
path_set_kind(ind,val) Sets the kind of connections of the path with the given index (0=straight, 1=smooth).
path_set_closed(ind,closed) Sets whether the path must be closed (true) or open (false).
path_set_precision(ind,prec) Sets the precision with which the smooth path is calculated (should lie between 1 and 8).
path_add() Adds a new empty paths. The index of the path is returned.
path_delete(ind) Deletes the path with the given index.
path_duplicate(ind) Creates a duplicate copy of the path with the given index. Returns the index of the copy.
path_assign(ind,path) Assigns the indicated path to path ind. So this makes a copy of the path. In this way you can easily set an existing path to a different, e.g. new path.
path_add_point(ind,x,y,speed) Adds a point to the path with the given index, at position (x,y) and with the given speed factor. Remember that a factor of 100 corresponds to the actual speed. Lower values mean slowing down and higher mean speeding up.
path_insert_point(ind,n,x,y,speed) Inserts a point in the path with the given index before point n, at position (x,y) and with the given speed factor.
path_change_point(ind,n,x,y,speed) Changes the point n in the path with the given index to position (x,y) and the given speed factor.
path_delete_point(ind,n) Delete the point n in the path with the given index.
path_clear_points(ind) Clears all the points in the path, turning it into an empty path.
path_reverse(ind) Reverses the path.
path_mirror(ind) Mirrors the path horizontally (with respect to its center).
path_flip(ind) Flips the path vertically (with respect to its center).
path_rotate(ind,angle) Rotates the path counter clockwise over angle degrees (around its center).
path_scale(ind,xscale,yscale) Scales the path with the given factors (from its center).
path_shift(ind,xshift,yshift) Shifts the path over the given amount.

Scripts

Scripts cannot be changed during the execution of the game. The scripts are part of the game logic. Changing scripts would lead to self-rewriting code which very easily leads to errors. Also there are other ways to achieve this. If you really need to execute a piece of code that is not known at design time (e.g. from a file) you can use the following functions:
execute_string(str) Execute the piece of code in the string str.
execute_file(fname) Execute the piece of code in the file.
Sometimes you want to store a script index in a variable and execute it. For this you can use the following function
script_execute(scr,arg0,arg1,...) Execute the script with index scr with the given arguments.

Data files

No routines to manipulate data files are available.

Time lines

The following routines are available for creating and changing time lines. Don't change time lines that are in use!
timeline_add() Adds a new time line. It returns the index of the time line.
timeline_delete(ind) Deletes the time line with the given index. Make sure no instances uses the time line in any room.
timeline_moment_add(ind,step,codestr) Adds a code action to the time line at moment step. codestr contains the code for the actions. If the step does not exist it is created. So you can add multiple code actions for the same moment.
timeline_moment_clear(ind,step) You can use this function to clear all the actions for a particular moment.

Objects

Also objects can be manipulated and created during the game play. NEVER change or delete an object for which there are instances. This can lead to unexpected effects as certain object properties are stored with the instance and, hence, changing them in the object will not have the desired effect.
object_set_sprite(ind,spr) Sets the sprite of the object with the given index. Use -1 to remove the current sprite from the object.
object_set_solid(ind,solid) Sets whether instances created of the object must default be solid (true or false).
object_set_visible(ind,vis) Sets whether instances created of the object must default be visible (true or false).
object_set_depth(ind,depth) Sets the default depth of instances created of the object.
object_set_persistent(ind,pers) Sets whether instances created of the object must default be persistent (true or false).
object_set_mask(ind,spr) Sets the sprite mask of the object with the given index. Use -1 to set the mask to be the sprite of the object.
object_set_parent(ind,obj) Sets the parent of the object. Use -1 to not have a parent. Changing the parent changes the behavior of instances of the object.
The following routines are useful for creating objects on the fly. As with all resource changing routines, be very careful that you don't create new objects all the time.
object_add() Adds a new object. It returns the index of the object. You can now use this index in the routines above to set certain properties of the object and then you can use the index to create instances of the object.
object_delete(ind) Deletes the object with the given index. Make sure no instances of the object exist in any of the rooms.
object_event_add(ind,evtype,evnumb,codestr) To give the object a behavior we must define events for the object. You can only add code actions to events. You need to specify the object, the event type, the event number (use the constants that have been specified before for the event_perform() function). Finally you provide the code string that must be executed. You can add multiple code actions to each event.
object_event_clear(ind,evtype,evnumb) You can use this function to clear all the actions for a particular event.
Creating object is in particular useful when you are designing scripts or action libraries. For example, an initialization script can create an object to display a text and another script can add such an object with a particular text. In this way you have a simple mechanism to display texts without the need to create objects using the standard interface.

Rooms

Manipulating rooms on the fly is a dangerous thing to do. You have to realize that rooms change all the time due to what is happening in the game. This normally only involved the currently active room and there are many routines described in previous sections to manipulate the instances, backgrounds, and tiles in the active room. But changes in the active room will last if the room is persistent. Hence, you should never manipulate aspects of the currently active room or any room that is persistent and that has already been visited before. Such changes in general won't be noticed but might sometimes even lead to unexpected errors. Due to the fact that rooms are linked in a complicated way there is also no routine to delete a room.

The following routines are available
room_set_width(ind,w) Sets the width for the room with the indicated index.
room_set_height(ind,w) Sets the height for the room with the indicated index.
room_set_caption(ind,str) Sets the caption for the room with the indicated index.
room_set_persistent(ind,val) Sets whether the room with the indicated index is persistent or not.
room_set_code(ind,str) Sets the initialization code string for the room with the indicated index.
room_set_background_color(ind,col,show) Sets the color properties for the room with the indicated index if is does not have a background image. col indicates the color and show indicates whether the color must be shown or not.
room_set_background(ind,bind,vis,fore,back,x,y,htiled,vtiled,hspeed,vspeed,alpha) Sets background with index bind (0-7) for the room with the indicated index. vis indicates whether the background is visible and fore whether it is actually a foreground. back is the index of the background image. x,y indicate the position of the image and htiled and vtiled indicate whether the image must be tiled. hspeed and vspeed indicate the speed with which the background moves and alpha indicates an alpha translucency value (1 = solid and fastest).
room_set_view(ind,vind,vis,left,top,width,height,x,y,hborder,vborder,hspeed,vspeed,obj) Sets the view with index vind (0-7) for the room with the indicated index. vis indicates whether the view is visible. left, top, width and height indicate the position of the view in the room. x,y indicate the position on the screen. When the view must follow an object hborder and vborder indicate the minimal visible border that must be kept around the object. hspeed and vspeed indicate the maximal speed with which the view can move. obj is the index of the object or the index of the instance.
room_set_view_enabled(ind,val) Sets whether views must be enabled for the room with the indicated index.
room_add() Adds a new room. It returns the index of the room. Note that the room will not be part of the room order. So the new room does not have a previous or a next room. If you want to move to an added room you must provide the index of the room.
room_duplicate(ind) Adds a copy of the room with the given index. It returns the index of the room.
room_assign(ind,room) Assigns the indicated room to room ind. So this makes a copy of the room.
room_instance_add(ind,x,y,obj) Adds a new instance of object obj to the room at the indicate position. It returns the index of the instance.
room_instance_clear(ind) Removes all instances from the indicated room.
room_tile_add(ind,back,left,top,width,height,x,y,depth) Adds a new tile to the room at the indicate position. It returns the index of the tile. back is the background from which the tile is taken. left, top, width and height indicate the part of the background that forms the tile. x,y is the position of the tile in the room and depth is the depth of the tile.
room_tile_add_ext(ind,back,left,top,width,height,x,y,depth,xscale,yscale,alpha) Same as the previous routine but this time you can also specify a scaling factor in x and y direction and an alpha transparency for the tile.
room_tile_clear(ind) Removes all tiles from the indicated room.


Files, registry, and executing programs

In more advanced games you probably want to read data from a file that you provide with the game. For example, you could make a file that describes at what moments certain things should happen. Also you probably want to save information for the next time the game is run (for example, the current room). The following functions exist to read and write data in text files:
file_text_open_read(fname) Opens the file with the indicated name for reading. The function returns the id of the file that must be used in the other functions. You can open multiple files at the same time (32 max). Don't forget to close them once you are finished with them.
file_text_open_write(fname) Opens the indicated file for writing, creating it if it does not exist. The function returns the id of the file that must be used in the other functions.
file_text_open_append(fname) Opens the indicated file for appending data at the end, creating it if it does not exist. The function returns the id of the file that must be used in the other functions.
file_text_close(fileid) Closes the file with the given file id.
file_text_write_string(fileid,str) Writes the string to the file with the given file id.
file_text_write_real(fileid,x) Write the real value to the file with the given file id.
file_text_writeln(fileid) Write a newline character to the file.
file_text_read_string(fileid) Reads a string from the file with the given file id and returns this string. A string ends at the end of line.
file_text_read_real(fileid) Reads a real value from the file and returns this value.
file_text_readln(fileid) Skips the rest of the line in the file and starts at the start of the next line.
file_text_eof(fileid) Returns whether we reached the end of the file.
To manipulate files in the file system you can use the following functions:
file_exists(fname) Returns whether the file with the given name exists (true) or not (false).
file_delete(fname) Deletes the file with the given name.
file_rename(oldname,newname) Renames the file with name oldname into newname.
file_copy(fname,newname) Copies the file fname to the newname.
directory_exists(dname) Returns whether the indicated directory does exist.
directory_create(dname) Created a directory with the given name (including the path towards it) if it does not exist.
file_find_first(mask,attr) Returns the name of the first file that satisfies the mask and the attributes. If no such file exists, the empty string is returned. The mask can contain a path and can contain wildchars, for example 'C:\temp\*.doc'. The attributes give the additional files you want to see. (So the normal files are always returned when they satisfy the mask.) You can add up the following constants to see the type of files you want:
fa_readonly read-only files
fa_hidden hidden files
fa_sysfile system files
fa_volumeid volume-id files
fa_directory directories
fa_archive archived files
file_find_next() Returns the name of the next file that satisfies the previously given mask and the attributes. If no such file exists, the empty string is returned.
file_find_close() Must be called after handling all files to free memory.
file_attributes(fname,attr) Returns whether the file has all the attributes given in attr. Use a combination of the constants indicated above.
The following functions can be used to change file names. Note that these functions do not work on the actual files they only deal with the strings.
filename_name(fname) Returns the name part of the indicated file name, with the extension but without the path.
filename_path(fname) Returns the path part of the indicated file name, including the final backslash.
filename_dir(fname) Returns the directory part of the indicated file name, which normally is the same as the path except for the final backslash.
filename_drive(fname) Returns the drive information of the filename.
filename_ext(fname) Returns the extension part of the indicated file name, including the leading dot.
filename_change_ext(fname,newext) Returns the indicated file name, with the extension (including the dot) changed to the new extension. By using an empty string as the new extension you can remove the extension.
In rare situation you might need to read data from binary files. The following low-level routines exist for this:
file_bin_open(fname,mod) Opens the file with the indicated name. The mode indicates what can be done with the file: 0 = reading, 1 = writing, 2 = both reading and writing). The function returns the id of the file that must be used in the other functions. You can open multiple files at the same time (32 max). Don't forget to close them once you are finished with them.
file_bin_rewrite(fileid) Rewrite the file with the given file id, that is, clear it and start writing at the start.
file_bin_close(fileid) Closes the file with the given file id.
file_bin_size(fileid) Returns the size (in bytes) of the file with the given file id.
file_bin_position(fileid) Returns the current position (in bytes; 0 is the first position) of the file with the given file id.
file_bin_seek(fileid,pos) Moves the current position of the file to the indicated position. To append to a file move the position to the size of the file before writing.
file_bin_write_byte(fileid,byte) Writes a byte of data to the file with the given file id.
file_bin_read_byte(fileid) Read a byte of data from the file and returns this.
If the player has checked secure mode in his preferences, for a number of these routines, you are not allowed to specify a path, and only files in the application folder can e.g. be written.

The following three read-only variables can be useful:
game_id* Unique identifier for the game. You can use this if you need a unique file name.
working_directory* Working directory for the game. (Not including the final backslash.)
temp_directory* Temporary directory created for the game. You can store temporary files here. They will be removed at the end of the game.
In certain situations you might want to give players the possibility to give command line arguments to the game they are running (for example to create cheats or special modes). To get these arguments you can use the following two routines.
parameter_count() Returns the number of command-line parameters (note that the name of the program itself is one of them.
parameter_string(n) Returns command-line parameters n. The first parameter has index 0. This is the name of the program.
You can read the value of environment variables using the following function:
environment_get_variable(name) Returns the value (a string) of the environment variable with the given name.
If you want to store a small amount of information between runs of the game there is a simpler mechanism than using a file. You can use the registry. The registry is a large database that Windows maintains to keep track of all sorts of settings for programs. An entry has a name, and a value. You can use both string and real values. The following functions exist:
registry_write_string(name,str) Creates an entry in the registry with the given name and string value.
registry_write_real(name,x) Creates an entry in the registry with the given name and real value.
registry_read_string(name) Returns the string that the given name holds. (The name must exist. otherwise an empty string is returned.)
registry_read_real(name) Returns the real that the given name holds. (The name must exist. Otherwise the number 0 is returned.)
registry_exists(name) Returns whether the given name exists.
Actually, values in the registry are grouped into keys. The above routines all work on values within the key that is especially created for your game. Your program can use this to obtain certain information about the system the game is running on. You can also read values in other keys. You can write them also but be very careful. YOU EASILY DESTROY YOUR SYSTEM this way. (Write is not allowed in secure mode.) Note that keys are again placed in groups. The following routines default work on the group HKEY_CURRENT_USER. But you can change the root group. So, for example, if you want to find out the current temp dir, use
path = registry_read_string_ext('\Environment','TEMP');
The following functions exist.
registry_write_string_ext(key,name,str) Creates an entry in the key in the registry with the given name and string value.
registry_write_real_ext(key,name,x) Creates an entry in the key in the registry with the given name and real value.
registry_read_string_ext(key,name) Returns the string that the given name in the indicated key holds. (The name must exist. otherwise an empty string is returned.)
registry_read_real_ext(key,name) Returns the real that the given name in the indicated key holds. (The name must exist. Otherwise the number 0 is returned.)
registry_exists_ext(key,name) Returns whether the given name exists in the given key.
registry_set_root(root) Sets the root for the other routines. Use the following values:
0 = HKEY_CURRENT_USER
1 = HKEY_LOCAL_MACHINE
2 = HKEY_CLASSES_ROOT
3 = HKEY_USERS
To pass certain parameter settings to programs a standard mechanism is the use of INI files. INI files contain sections and each section contains a number of name-value pairs. For example, here is a typical INI file:
[Form]
Top=100
Left=100
Caption=The best game ever
[Game]
MaxScore=12324
This file contains two sections, one call Form and the other called Game. The first section contains three pairs. The first two have a real value while the third has a string value. Such INI files are easy to create and change and the following functions exist in Game Maker to read and change the data in them
ini_open(name) Opens the INI file with the given name. The ini file must be stored in the same folder as the game!
ini_close() Closes the currently open INI file.
ini_read_string(section,key,default) Reads the string value of the indicated key in the indicated section. When the key or section does not exist the default value is returned.
ini_read_real(section,key,default) Reads the real value of the indicated key in the indicated section. When the key or section does not exist the default value is returned.
ini_write_string(section,key,value) Writes the string value for the indicated key in the indicated section.
ini_write_real(section,key,value) Writes the real value for the indicated key in the indicated section.
ini_key_exists(section,key) Returns whether the indicated key exists in the indicated section.
ini_section_exists(section) Returns whether the indicated section exists.
ini_key_delete(section,key) Deletes the indicated key from the indicated section.
ini_section_delete(section) Deletes the indicated section.
Game Maker also has the possibility to start external programs. There are two functions available for this: execute_program and execute_shell. The function execute_program starts a program, possibly with some arguments. It can wait for the program to finish (pausing the game) or continue the game. The function execute_shell opens a file. This can be any file for which some association is defined, e.g. an html-file, a word file, etc. Or it can be a program. It cannot wait for completion so the game will continue.
execute_program(prog,arg,wait) Execute program prog with arguments arg. wait indicates whether to wait for finishing.
execute_shell(prog,arg) Executes the program (or file) in the shell.
Both functions will not work if the player set the secure mode in the preferences. You can check this using the read-only variable:
secure_mode* Whether the game is running in secure mode.


Data structures

This functionality is only available in the registered version of Game Maker.

In games you often need to store information. For example you need to store lists of items that a person carries or you want to store places that still need to be visited. You can use the arrays for this. But if you want to do more complicated operations, like sorting the data or searching for a particular item, you need to write large pieces of GML code which can be slow to execute.
To remedy this, Game Maker has a number of built-in data structures that can be accessed through functions. At the moment there are five different types of data structures available: stacks, queues, lists, maps, and priority queues. Each of these data structures is tuned for a particular type of use (see below).

All data structures work globally in the same way. You can create a data structure with a function that returns an id for the structures. You use this id to perform operations on the data structures. Once you are done you destroy the data structure again to save storage. You can use as many of the structures at the same moment as you want. All structure can store both strings and real values.

When comparing values, for example when searching in a map or sorting a list, Game Maker must decide when two values are equal. For strings and integer values this is clear but for real numbers, due to round-off errors, equal number can easily become unequal. For example (5/3)*3 will not be equal to 5. To avoid this, a precision is used. When the difference between two numbers is smaller than this precision they are considered equal. Default a precision of 0.0000001 is used. You can change this precision using the following functions:
ds_set_precision(prec) Sets the precision used for comparisons.
This precision is used in all data structures but not in other comparisons in GML!

Stacks

A stack data structure is a so called LIFO (Last-In First-Out) structures. You can push values on a stack and the remove them again by popping them from the stack. The value that was pushed on the stack most recently is the first to be popped from it again. Stacks are often used when there are interrupts to handle, or when having recursive functions. The following functions exist for stacks:
ds_stack_create() Creates a new stack. The function returns an integer as an id that must be used in all other functions to access the particular stack. You can create multiple stacks.
ds_stack_destroy(id) Destroys the stack with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_stack_clear(id) Clears the stack with the given id, removing all data from it but not destroying it.
ds_stack_size(id) Returns the number of values stored in the stack.
ds_stack_empty(id) Returns whether the stack is empty. This is the same as testing whether the size is 0.
ds_stack_push(id,val) Pushed the value on the stack.
ds_stack_pop(id) Returns the value on the top of the stack and removes it from the stack.
ds_stack_top(id) Returns the value on the top of the stack but does not remove it from the stack.

Queues

A queue is somewhat similar to a stack but it works on a FIFO (First-In First-Out) basis. The value that is put in the queue first is also the first to be removed from it. It works similar as a queue in a shop. The person that is first in a queue is served first. Queues are typically used to store things that still need to be done but there are many other uses. The following functions exist (note that the first five are equivalent to the functions for stacks; all data structures have these five functions).
ds_queue_create() Creates a new queue. The function returns an integer as an id that must be used in all other functions to access the particular queue. You can create multiple queues.
ds_queue_destroy(id) Destroys the queue with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_queue_clear(id) Clears the queue with the given id, removing all data from it but not destroying it.
ds_queue_size(id) Returns the number of values stored in the queue.
ds_queue_empty(id) Returns whether the queue is empty. This is the same as testing whether the size is 0.
ds_queue_enqueue(id,val) Enters the value in the queue.
ds_queue_dequeue(id) Returns the value that is longest in the queue and removes it from the queue.
ds_queue_head(id) Returns the value at the head of the queue, that is, the value that has been the longest in the queue. (It does not remove it from the queue.)
ds_queue_tail(id) Returns the value at the tail of the queue, that is, the value that has most recently been added to the queue. (It does not remove it from the queue.)

Lists

A list stores a collection of values in a particular order. You can add values at the end or insert them somewhere in the middle of the list. You can address the values using an index. Also you can sort the elements, either in ascending or descending order. List can be used in many ways, for example to store changing collections of values. They are implemented using simple arrays but, as this is done in compiled code it is a lot faster than using an array yourself. The following functions are available:
ds_list_create() Creates a new list. The function returns an integer as an id that must be used in all other functions to access the particular list.
ds_list_destroy(id) Destroys the list with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_list_clear(id) Clears the list with the given id, removing all data from it but not destroying it.
ds_list_size(id) Returns the number of values stored in the list.
ds_list_empty(id) Returns whether the list is empty. This is the same as testing whether the size is 0.
ds_list_add(id,val) Add the value at the end of the list.
ds_list_insert(id,pos,val) Inserts the value at position pos in the list. The first position is position 0, the last one the size minus 1.
ds_list_replace(id,pos,val) Replaces the value at position pos in the list with the new value.
ds_list_delete(id,pos) Deletes the value at position pos in the list. (Position 0 is the first element.)
ds_list_find_index(id,val) Find the position storing the indicated value. If the value is not in the list -1 is returned.
ds_list_find_value(id,pos) Returns the value stored at the indicated position in the list.
ds_list_sort(id,ascend) Sorts the values in the list. When ascend is true the values are sorted in ascending order, otherwise in descending order.

Maps

In quite a few situations you need to store pairs consisting of a key and a value. For example, a character can have a number of different items and for each item it has a particular number of those. In this case the item is the key and the number is the value. Maps maintain such pairs, sorted by key. You can add pairs to the map and search for the value corresponding to certain keys. Because the keys are sorted you can also find previous and next keys. Sometimes it is also useful to use a map to just store keys without a corresponding value. In that case you can simply use a value of 0. The following functions exist:
ds_map_create() Creates a new map. The function returns an integer as an id that must be used in all other functions to access the particular map.
ds_map_destroy(id) Destroys the map with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_map_clear(id) Clears the map with the given id, removing all data from it but not destroying it.
ds_map_size(id) Returns the number of key-value pairs stored in the map.
ds_map_empty(id) Returns whether the map is empty. This is the same as testing whether the size is 0.
ds_map_add(id,key,val) Add the key-value pair to the map.
ds_map_replace(id,key,val) Replaces the value corresponding with the key with a new value.
ds_map_delete(id,key) Deletes the key and the corresponding value from the map. (If there are multiple entries with the same key, only one is removed.)
ds_map_exists(id,key) Returns whether the key exists in the map.
ds_map_find_value(id,key) Returns the value corresponding to the key.
ds_map_find_previous(id,key) Returns the largest key in the map smaller than the indicated key. (Note that the key is returned, not the value. You can use the previous routine to find the value.)
ds_map_find_next(id,key) Returns the smallest key in the map larger than the indicated key.
ds_map_find_first(id) Returns the smallest key in the map.
ds_map_find_last(id) Returns the largest key in the map.

Priority queues

In a priority queue a number of values are stored, each with a priority. You can quickly find the values with minimum and maximum priority. Using this data structure you can handle certain things in the order of priority. The following functions exist:
ds_priority_create() Creates a new priority queue. The function returns an integer as an id that must be used in all other functions to access the particular priority queue.
ds_priority_destroy(id) Destroys the priority queue with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_priority_clear(id) Clears the priority queue with the given id, removing all data from it but not destroying it.
ds_priority_size(id) Returns the number of values stored in the priority queue.
ds_priority_empty(id) Returns whether the priority queue is empty. This is the same as testing whether the size is 0.
ds_priority_add(id,val,prio) Add the value with the given priority to the priority queue.
ds_priority_change_priority(id,val,prio) Changes the priority of the given value in the priority queue.
ds_priority_find_priority(id,val) Returns the priority of the given value in the priority queue.
ds_priority_delete_value(id,val) Deletes the given value (with its priority) from the priority queue.
ds_priority_delete_min(id) Returns the value with the smallest priority and deletes it from the priority queue.
ds_priority_find_min(id) Returns the value with the smallest priority but does not delete it from the priority queue.
ds_priority_delete_max(id) Returns the value with the largest priority and deletes it from the priority queue.
ds_priority_find_max(id) Returns the value with the largest priority but does not delete it from the priority queue.


Creating particles

This functionality is only available in the registered version of Game Maker.

Particle systems are meant to create special effects. Particles are small elements (either represented by a little sprite, a pixel or a little shape). Such particles move around according to predefined rules and can change color while they move. Many such particles together can create e.g. fireworks, flames, rain, snow, star fields, flying debris, etc.

Game Maker contains an extensive particle system that can be used to create great effects. It is though not trivial to use so better read this section carefully before trying. Particle systems have many parameters and it is not always easy to understand how to create the effects you want.

First of all there are particle types. A particle type defines a particular kind of particles. Such types have many parameters that describe the shape, size, color, and motion of the particles.

Secondly there are particle systems. There can be different particle systems in the game. A particle system can have particles of the different types. A particle system has emitters that create the particles, either continuously or in bursts. It can also have attractors that attract particles. Finally, it can have destroyers that destroy particles.

Realize that your game is responsible for updating the particle system and drawing it. So typically a particle system will be associated with an object in the game. In the step event it calls the function to update the particle system and in the drawing event it calls the function to draw the particle system at a particular location.

Particle types

A particle type describes the shape, color, and motion of a particular kind of particles. It has a large number of parameters. The following parameters describe the shape of the particle:
  • shape indicates the shape of the particles. This is only relevant if the particle system does not use sprites as particles. It can be one of the following:
    • pt_shape_pixel
    • pt_shape_disk
    • pt_shape_square
    • pt_shape_diamond
    • pt_shape_star
    • pt_shape_plus
    • pt_shape_cross
  • sprite indicates the sprite used for the particle when the particle system is sprite based.
  • sprite_animate indicates whether the sprite must be animated (true) or not (false).
  • sprite_stretch indicates whether the sprite animation must be stretched over the whole lifetime of the particle (true) or whether the animation must be repeated (false). (This assumes the previous value is true.)
  • sprite_random indicates whether the sprite animation must start at a random subimage (true) or at the first subimage (false). If the sprite is not animated use this to get a random subimage rather than the first one.
  • size_min, size_max indicates the size of the particles. The size is chosen randomly between the given bounds. This is not relevant for pixel shaped particles. For sprite-based particles it indicates the scaling factor used.
  • size_incr indicates the size increment in each step. It lets you grow or shrink the particles (a size below 0 is treated as 0) over time.
  • size_rand indicates a random offset of the size in each step. If you give it a large value the particles with rapidly switch size, giving a blinking effect.
  • color_start, color_middle, color_end indicate the color of the (non sprite based) particle. It starts with the first color and over its lifetime slowly changed color to the middle color and finally to the end color.
A particle lives for a limited amount of time. This is indicated using the following parameters:
  • life_min, life_max indicates the lifetime of the particles. A random value between the bounds is chosen when the particle is created. When the life is over the particle dies.
The following parameters influence the motion of the particle:
  • speed_min, speed_max indicate the speed of the particle (in pixels per step). A random value between the given bounds is chosen when the particle is created.
  • speed_incr indicates the speed increase in each step. Use a negative value to let the particle slow down (the speed will never become smaller than 0).
  • speed_rand indicates the maximal random amount of speed that is added in each step to the speed used in that step. It can be used to give the particles a more random way.
  • dir_min, dir_max indicate the direction of motion of the particle (in counterclockwise degrees; 0 indicated a motion to the right). A random value between the given bounds is chosen when the particle is created. For example, to let the particle move in a random direction choose 0 and 360 as values.
  • dir_incr indicates the direction increase (or decrease) in each step. This will make particles move around in circles.
  • dir_rand indicates the maximal random amount of direction that is added in each step to the direction used in that step. It can be used to give the particles a more random way.
  • grav_amount indicates the amount of gravity in each step.
  • grav_dir indicates the direction of gravity; use 270 for a downwards direction.
Particles can create particles themselves. For this the following parameters are available:
  • step_type indicates the type of new particles created in each step.
  • step_number indicates the number of such particles generated in each step. These two parameters can for example be used to give particles a tails while flying around. Be careful that the total number of particles does not get too high.
  • death_type indicates the type of particles generated when the particle dies.
  • death_number indicates the number of particles generated when the particle dies. These two parameters can be used to create secondary effects, e.g. a particle exploding after a while into a number of other particles. Be careful though. This can easily create a huge number of particles. Note that these particles are only created when the particle dies at the end of its life. Not when it dies because of a destroyer (see below).
The following functions are available to define particle types. Note that each function gets an id of the type as argument. These must be numbers between 0 and 1000. You should preferably pick small positive integer numbers for this (e.g. 1,2,3,4, etc.).
    part_type_create() Creates a new particle type. It returns the index of the type. This index must be used in all calls below to set the properties of the particle type.
    part_type_destroy(ind) Destroys particle type ind. Call this if you don't need it anymore to save space.
    part_type_destroy_all() Destroys all particle types that have been created.
    part_type_exists(ind) Returns whether the indicated particle type exists.
    part_type_clear(ind) Clears the particle type ind to its default settings.
    part_type_shape(ind,shape) Sets the shape of the particle type. Use one of the following constants (default is pt_shape_pixel).
    • pt_shape_pixel
    • pt_shape_disk
    • pt_shape_square
    • pt_shape_diamond
    • pt_shape_star
    • pt_shape_plus
    • pt_shape_cross
    part_type_sprite(ind,sprite,animat,stretch,random) Sets the sprite for the particle type (if the particle system is sprite-based; see below). With animate you indicate whether the sprite should be animated. With stretch you indicate whether the animation must be stretched over the lifetime of the particle. And with random you can indicate whether a random subimage must be choosen as starting image.
    part_type_size(ind,size_min,size_max,size_incr,size_rand) Sets the size parameters for the particle type. (Default the size is 1 and the size does not change.)
    part_type_color(ind,color_start,color_middle,color_end) Sets the color parameters for the particle type. (Default all colors are white.)
    part_type_color2(ind,color_start,color_end) Similar but this time only the start and end color are set. The middle color is taken in between.
    part_type_life(ind,life_min,life_max) Sets the lifetime bounds for the particle type. (Default both are 100.)
    part_type_speed(ind,speed_min,speed_max,speed_incr,speed_rand) Sets the speed properties for the particle type. (Default all values are 0.)
    part_type_direction(ind,dir_min,dir_max,dir_incr,dir_rand) Sets the direction properties for the particle type. (Default all values are 0.)
    part_type_gravity(ind,grav_amount,grav_dir) Sets the gravity properties for the particle type. (Default there is no gravity.)
    part_type_step(ind,step_number,step_type) Sets the number and type of particles that must be generated in each step for the indicated particle type. (Default no particles are generated.)
    part_type_death(ind,death_number,death_type) Sets the number and type of particles that must be when a particle of the indicated type dies. (Default no particles are generated.)

Particle systems

Particles live in particle systems. So to have particles in your game you need to create one or more particle systems. There can be many different particle systems. For example, if you game has a number of ball and each ball should have a tail of particles, most likely each ball has its own particle system. The easiest way to deal with particle systems is to create one and then create particles in it, using the particle types you specified before. But, as we will see below, particle systems can contain emitters that automatically produce particles, attractors that attract them, and destroyers that destroy them.

Particle systems can be sprite-based or not. In a sprite-based particle system, each particle is represented by a sprite. In a non sprite-based particle system, particles are a pixel or have some geometric shape (like a square). You cannot mix sprite-based and geometric particles in the same system (this is for efficiency reasons) but you can define different particle systems for this.

Your game is responsible for letting the particle system do its work. That is, you must create the particle system (typically in the creation event of some object), indicate that is must update the position of all particles (typically in the step event), and draw the particles (typically in the draw event of the object). Also you better destroy the particle system if you don't need it anymore.

The following functions deal with particle systems:
part_system_create() Creates a new particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the particle system.
part_system_destroy(ind) Destroys particle system ind. Call this if you don't need it anymore to save space.
part_system_destroy_all() Destroys all particle systems that have been created.
part_system_exists(ind) Returns whether the indicated particle system exists.
part_system_clear(ind) Clears the particle system ind to its default settings, removing all particles and emitter and attractors in it.
part_system_sprite_based(ind,set) Sets whether the particle system is sprite-based (true) or not (false). (Default is false.)
part_system_draw_order(ind,oldtonew) Sets the order in which the particle system draws the particles. When oldtonew is true the oldest particles are drawn first and the newer one lie on top of them (default). Otherwise the newest particles are drawn first. This can give rather different effects.
part_system_doastep(ind) This functions updates the position of all particles in the system and lets the emitters create particles. It should be called exactly once in each step of the game.
part_system_draw(ind,x,y) This functions draws the particles in the system, relative at position (x,y). It should be called in the draw event of some object. Often you want to use (0,0) as position cause in general the particle system itself takes care of the positions.
The following functions deal with particles in a particle systems:
part_particles_create(ind,x,y,parttype,number) This functions creates number particles of the indicated type at postion (x,y) in the system.
part_particles_clear(ind) This functions removes all particles in the system.
part_particles_count(ind) This functions returns the number of particles in the system.

Emitters

Emitters create particles. They can either create a continuous stream of particles or can burst out a number of particles when using the appropriate function. A particle system can have an arbitrary number of emitters. An emitter has the following properties:
  • xmin, xmax, ymin, ymax indicate the extend of the region in which the particles are generated.
  • shape indicates the shape of the region. It can have the following values:
    • ps_shape_rectangle
    • ps_shape_ellipse
    • ps_shape_diamond
    • ps_shape_line
  • distribution indicates the distribution used to generate the particles. It can have the following values:
    • ps_distr_linear indicates a linear distribution, that is everywhere in the region the chance is equal
    • ps_distr_gaussian indicates a Gaussian distribution in which more particles are generated in the center than at the sides of the region
  • particle type indicates the type of particles being generated
  • number indicates the number of particles generated in each step. If smaller than 0, in each step a particle is generated with a chance -1/number. So for example with a value of -5 a particle is generated on average once every 5 steps.
The following functions are available to set the emitters and to let them create particles. Note that each of them gets the index of the particle system to which it belongs as a first argument.
part_emitter_create(ps) Creates a new emitter in the given particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the emitter.
part_emitter_destroy(ps,ind) Destroys emitter ind in the particle system. Call this if you don't need it anymore to save space.
part_emitter_destroy_all(ps) Destroys all emitters in the particle system that have been created.
part_emitter_exists(ps,ind) Returns whether the indicated emitter exists in the particle system.
part_emitter_clear(ps,ind) Clears the emitter ind to its default settings.
part_emitter_region(ps,ind,xmin,xmax,ymin,ymax,shape,distribution) Sets the region and distribution for the emitter.
part_emitter_burst(ps,ind,parttype,number) Burst once number particles of the indicated type from the emitter.
part_emitter_stream(ps,ind,parttype,number) From this moment on create number particles of the indicated type from the emitter in every step. If you indicate a number smaller than 0 in each step a particle is generated with a chance of -1/number. So for example with a value of -5 a particle is generated on average once every 5 steps.

Attractors

Besides emitters a particle system can also contain attractors. An attractor attracts the particles (or pushes them away). A particle system can have multiple attractors. You are though recommended to use few of these because they will slow down the processing of the particles. An attractor has the following properties
  • x,y indicate the position of the attractor.
  • force indicates the attracting force of the attractor. How the force acts on the particles depends on the following parameters.
  • dist indicates the maximal distance at which the attractor has effect. Only particles closer that this distance to the attractor will be attracted.
  • kind indicates the kind of attractor. The following values exist
    • ps_force_constant indicates that the force is constant independent of the distance.
    • ps_force_linear indicates a linearly growing force. At the maximal distance the force is 0 while at the position of the attractor it attains the given value.
    • ps_force_quadratic indicates that the force grows quadratic.
  • additive indicates whether the force is added to the speed and direction in each step (true) or only applied to the position of the particle (false). When additive the particle will accelerate towards the attractor while with a non-additive force it will move there with constant speed.
The following functions exist to define attractors. Note that each of them gets the index of the particle system to which it belongs as a first argument.
part_attractor_create(ps) Creates a new attractor in the given particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the emitter.
part_attractor_destroy(ps,ind) Destroys attractor ind in the particle system. Call this if you don't need it anymore to save space.
part_attractor_destroy_all(ps) Destroys all attractor in the particle system that have been created.
part_attractor_exists(ps,ind) Returns whether the indicated attractor exists in the particle system.
part_attractor_clear(ps,ind) Clears the attractor ind to its default settings.
part_attractor_position(ps,ind,x,y) Sets the position of attractor ind to (x,y).
part_attractor_force(ps,ind,force,dist,kind,aditive) Sets the force parameters of attractor ind.

Destroyers

Destroyers destroy particles when they appear in their region. A particle system can have an arbitrary number of destroyers. A destroyer has the following properties:
  • xmin, xmax, ymin, ymax indicate the extend of the region in which the particles are destroyed.
  • shape indicates the shape of the region. It can have the following values:
    • ps_shape_rectangle
    • ps_shape_ellipse
    • ps_shape_diamond
The following functions are available to set the properties of the destroyers. Note that each of them gets the index of the particle system to which it belongs as a first argument.
part_destroyer_create(ps) Creates a new destroyer in the given particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the destroyer.
part_destroyer_destroy(ps,ind) Destroys destroyer ind in the particle system. Call this if you don't need it anymore to save space.
part_destroyer_destroy_all(ps) Destroys all destroyer in the particle system that have been created.
part_destroyer_exists(ps,ind) Returns whether the indicated destroyer exists in the particle system.
part_destroyer_clear(ps,ind) Clears the destroyer ind to its default settings.
part_destroyer_region(ps,ind,xmin,xmax,ymin,ymax,shape) Sets the region for the destroyer.

Deflectors

Deflectors deflect particles when they appear in their region. A particle system can have an arbitrary number of deflectors. A deflector has the following properties:
  • xmin, xmax, ymin, ymax indicate the extend of the region in which the particles are deflected.
  • kind indicates the kind of deflector. It can have the following values:
    • ps_deflect_horizontal deflects the particle horizontally; typically used for vertical walls
    • ps_deflect_vertical deflects the particle vertically; typically used for horizontal walls
  • friction the amount of friction as a result of the impact with the deflector. The higher this amount the more the particle is slowed down on impact.
The following functions are available to set the properties of the deflector. Note that each of them gets the index of the particle system to which it belongs as a first argument.
part_deflector_create(ps) Creates a new deflector in the given particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the deflector.
part_deflector_destroy(ps,ind) Destroys deflector ind in the particle system. Call this if you don't need it anymore to save space.
part_deflector_destroy_all(ps) Destroys all deflectors in the particle system that have been created.
part_deflector_exists(ps,ind) Returns whether the indicated deflector exists in the particle system.
part_deflector_clear(ps,ind) Clears the deflector ind to its default settings.
part_deflector_region(ps,ind,xmin,xmax,ymin,ymax) Sets the region for the deflector.
part_deflector_kind(ps,ind,kind) Sets the kind for the deflector.
part_deflector_friction(ps,ind,friction) Sets the friction for the deflector.

Changers

Changers change certain particles when they appear in their region. A particle system can have an arbitrary number of changers. A changer has the following properties:
  • xmin, xmax, ymin, ymax indicate the extend of the region in which the particles are changed.
  • shape indicates the shape of the region. It can have the following values:
    • ps_shape_rectangle
    • ps_shape_ellipse
    • ps_shape_diamond
  • parttype1 indicates the particle type that is changed.
  • parttype2 indicates the particle type into which it is changed.
  • kind indicates the kind of changer. It can have the following values:
    • ps_change_motion only change the motion parameters of the particle, not the color and shape or lifetime settings
    • ps_change_shape only change the shpae parameters like size and color and shape
    • ps_change_all change all parameters, this basically means that the particle is destroyed and a new one of the new type is created.
The following functions are available to set the properties of the changer. Note that each of them gets the index of the particle system to which it belongs as a first argument.
part_changer_create(ps) Creates a new changer in the given particle system. It returns the index of the type. This index must be used in all calls below to set the properties of the changer.
part_changer_destroy(ps,ind) Destroys changer ind in the particle system. Call this if you don't need it anymore to save space.
part_changer_destroy_all(ps) Destroys all changers in the particle system that have been created.
part_changer_exists(ps,ind) Returns whether the indicated changer exists in the particle system.
part_changer_clear(ps,ind) Clears the changer ind to its default settings.
part_changer_region(ps,ind,xmin,xmax,ymin,ymax,shape) Sets the region for the changer.
part_changer_types(ps,ind,parttype1,parttype2) Sets which particle type the changer must changed into what other type.
part_changer_kind(ps,ind,kind) Sets the kind for the changer.

Example

Here is an example of a particle system that creates fireworks. The firework uses two particle types: one that forms the rocket and one that forms the actual fireworks. The rocket generates the firework particles when it dies. We also generate one emitter in the particle system that regularly stream out rocket particles along the bottom of the screen. To make this work you need an object. In its creation event we place the following code that creates the particle types, particle system, and the emitter:
{
  // make the particle system
  ps = part_system_create();

  // the firework particles
  pt1 = part_type_create();
  part_type_speed(pt1,0,3,0,0);
  part_type_direction(pt1,0,360,0,0);
  part_type_color(pt1,c_red,c_yellow,c_black);
  part_type_life(pt1,30,40);
  part_type_gravity(pt1,0.2,270);

  // the rocket
  pt2 = part_type_create();
  part_type_shape(pt2,pt_shape_disk);
  part_type_size(pt2,4,4,0,0);
  part_type_speed(pt2,10,14,0,0);
  part_type_direction(pt2,80,100,0,0);
  part_type_color(pt2,c_white,c_ltgray,c_gray);
  part_type_life(pt2,30,60);
  part_type_gravity(pt2,0.2,270);
  part_type_death(pt2,100,pt1);         // create the firework on death

  // create the emitter
  em = part_emitter_create(ps);
  part_emitter_region(ps,em,100,540,480,490,
                                         ps_shape_rectangle,ps_distr_linear);
  part_emitter_stream(ps,em,pt2,-4);   // create one every four steps
}

In the step event of the object we must tell the particle system to make a step. So here we put the following code:

{
  part_system_doastep(ps);
}
Finally, in the draw event of the object we indicate to draw the particle system using the following code:
{
  part_system_draw(ps,0,0);
}


Multiplayer games

This functionality is only available in the registered version of Game Maker.

Playing games against the computer is fun. But playing games against other human players can be even more fun. It is also relatively easy to make such games because you don't have to implement complicated computer opponent AI. You can of course sit with two players behind the same monitor and use different keys or other input devices, but it is a lot more interesting when each player can sit behind his own computer. Or even better, one player sits on the other side of the ocean. Game Maker has multiplayer support. Please realize that creating effective multiplayer games that synchronize well and have no latency is a difficult task. This chapter gives a brief description of the possibilities. On the website a tutorial is available with more information.

Setting up a connection

For two computer to communicate they will need some connection protocol. Like most games, Game Maker offers four different types of connections: IPX, TCP/IP, Modem, and Serial. The IPX connection (to be more precise, it is a protocol) works almost completely transparent. It can be used to play games with other people on the same local area network. It needs to be installed on your computer to be used. (If it does not work, consult the documentation of Windows. Or go to the Network item in the control panel of Windows and add the IPX protocol.) TCP/IP is the internet protocol. It can be used to play with other players anywhere on the internet, assuming you know their IP address. On a local network you can use it without providing addresses. A modem connection is made through the modem. You have to provide some modem setting (an initialization string and a phone number) to use it. Finally, when using a serial line (a direct connection between the computers) you need to provide a number of port settings. There are four GML functions that can be used for initializing these connections:
mplay_init_ipx() initializes an IPX connection.
mplay_init_tcpip(addr) initializes a TCP/IP connection. addr is a string containing the web address or IP address, e.g. 'www.gameplay.com' or '123.123.123.12', possibly followed by a port number (e.g. ':12'). Only when joining a session (see below) you need to provide an address. On a local area network no addresses are necessary.
mplay_init_modem(initstr,phonenr) initializes a modem connection. initstr is the initialization string for the modem (can be empty). phonenr is a string that contains the phone number to ring (e.g. '0201234567'). Only when joining a session (see below) you need to provide a phone number.
mplay_init_serial(portno,baudrate,stopbits,parity,flow) initializes a serial connection. portno is the port number (1-4). baudrate is the baudrate to be used (100-256K). stopbits indicates the number of stopbits (0 = 1 bit, 1 = 1.5 bit, 2 = 2 bits). parity indicates the parity (0=none, 1=odd, 2=even, 3=mark). And flow indicates the type of flow control (0=none, 1=xon/xoff, 2=rts, 3=dtr, 4=rts and dtr). Returns whether successful. A typical call is mplay_init_serial(1,57600,0,0,4). Give 0 as a first argument to open a dialog for the user to change the settings.
Your game should call one of these functions exactly once. All functions report whether they were successful. They are not successful if the particular protocol is not installed or supported by your machine. To check whether there is a successful connection available you can use the following function
mplay_connect_status() returns the status of the current connection. 0 = no connection, 1 = IPX connection, 2 = TCP/IP connection, 3 = modem connection, and 4 = serial connection.
To end the connection call
mplay_end() ends the current connection.
When using a TCP/IP connection you might want to tell the person you want to play the game with what the ip address of your computer is. The following function helps you here:
mplay_ipaddress() returns the IP address of your machine (e.g. '123.123.123.12') as a string. You can e.g. display this somewhere on the screen. Note that this routine is slow so don't call it all the time.

Creating and joining sessions

When you connect to a network, there can be multiple games happening on the same network. We call these sessions. These different sessions can correspond to different games or to the same game. A game must uniquely identify itself on the network. Fortunately, Game Maker does this for you. The only thing you have to know is that when you change the game id in the options form this identification changes. In this way you can avoid that people with old versions of your game will play against people with new versions.

If you want to start a new multiplayer game you need to create a new session. For this you can use the following routine:
mplay_session_create(sesname,playnumb,playername) creates a new session on the current connection. sesname is a string indicating the name of the session. playnumb is a number that indicates the maximal number of players allowed in this game (use 0 for an arbitrary number). playname is the name of you as player. Returns whether successful.
One instance of the game must create the session. The other instance(s) of the game should join this session. This is slightly more complicated. You first need to look what sessions are available and then choose the one to join. There are three routines important for this:
mplay_session_find() searches for all sessions that still accept players and returns the number of sessions found.
mplay_session_name(numb) returns the name of session number numb (0 is the first session). This routine can only be called after calling the previous routine.
mplay_session_join(numb,playername) makes you join session number numb (0 is the first session). playername is the name of you as a player. Returns whether successful.

There is one more routine that can change the session mode. Should be called before creating a session:
mplay_session_mode(move) sets whether or not to move the session host to another computer when the host ends. move should either be true or false (the default).
To check the status of the current session you can use the following function
mplay_session_status() returns the status of the current session. 0 = no session, 1 = created session, 2 = joined session.
A player can stop a session using the following routine:
mplay_session_end() ends the session for this player.

Players

Each instance of the game that joins a session is a player. As indicated above, players have names. There are three routines that deal with players.
mplay_player_find() searches for all players in the current session and returns the number of players found.
mplay_player_name(numb) returns the name of player number numb (0 is the first player, which is always yourself). This routine can only be called after calling the previous routine.
mplay_player_id(numb) returns the unique id of player number numb (0 is the first player, which is always yourself). This routine can only be called after calling the first routine. This id is used in sending and receiving messages to and from individual players.

Shared data

Shared data communication is probably the easiest way to synchronize the game. All communication is shielded from you. There is a set of 1000000 values that are common to all entities of the game (preferably only use the first few to save memory). Each entity can set values and read values. Game Maker makes sure that each entity sees the same values. A value can either be a real or a string. There are just two routines:
mplay_data_write(ind,val) write value val (string or real) into location ind (ind between 0 and 1000000).
mplay_data_read(ind) returns the value in location ind (ind between 0 and 1000000). Initially all values are 0.
To synchronize the data on the different machines you can either use a guaranteed mode that makes sure that the change arrives on the other machine (but which is slow) or non-guaranteed. To change this use the following routine:
mplay_data_mode(guar) sets whether or not to use guaranteed transmission for shared data. guar should either be true (the default) or false.

Messages

The second communication mechanism that Game Maker supports is the sending and receiving of messages. A player can send messages to one or all other players. Players can see whether messages have arrived and take action accordingly. Messages can be sent in a guaranteed mode in which you are sure they arrive (but this can be slow) or in a non-guaranteed mode, which is faster.

The following messaging routines exist:
mplay_message_send(player,id,val) sends a message to the indicated player (either an identifier or a name; use 0 to send the message to all players). id is an integer message identifier and val is the value (either a real or a string). The message is sent in non-guaranteed mode. If val contains a string the maximal string length allowed is 30000 characters.
mplay_message_send_guaranteed(player,id,val) sends a message to the indicated player (either an identifier or a name; use 0 to send the message to all players). id is an integer message identifier and val is the value (either a real or a string). This is a guaranteed send. If val contains a string the maximal string length allowed is 30000 characters.
mplay_message_receive(player) receives the next message from the message queue that came from the indicated player (either an identifier or a name). Use 0 for messages from any player. The routine returns whether there was indeed a new message. If so you can use the following routines to get its contents:
mplay_message_id() Returns the identifier of the last received message.
mplay_message_value() Returns the value of the last received message.
mplay_message_player() Returns the player that sent the last received message.
mplay_message_name() Returns the name of the player that sent the last received message.
mplay_message_count(player) Returns the number of messages left in the queue from the player (use 0 to count all message).
mplay_message_clear(player) Removes all messages left in the queue from the player (use 0 to remove all message).
A few remarks are in place here. First of all, if you want to send a message to a particular player only, you will need to know the players unique id. As indicated earlier you can obtain this with the function mplay_player_id(). This player identifier is also used when receiving messages from a particular player. Alternatively, you can give the name of the player as a string. If multiple players have the same name, only the first will get the message.

Secondly, you might wonder why each message has an integer identifier. The reason is that this helps your application to send different types of messages. The receiver can check the type of message using the id and take appropriate actions. (Because messages are not guaranteed to arrive, sending id and value in different messages would cause serious problems.)


Using DLL's

This functionality is only available in the registered version of Game Maker.

In those cases were the functionality of GML is not enough for your wishes, you can actually extend the possibilities by using plug-ins. A plug-in comes in the form of a DLL file (a Dynamic Link Library). In such a DLL file you can define functions. Such functions can be programmed in any programming language that supports the creation of DLL's (e.g. Delphi, Visual C++, etc.) You will though need to have some programming skill to do this. Plug-in functions must have a specific format. They can have between 0 and 11 arguments, each of which can either be a real number (double in C) or a null-terminated string. (For more than 4 arguments, only real arguments are supported at the moment.) They must return either a real or a null-terminated string.

In Delphi you create a DLL by first choosing New from the File menu and then choosing DLL. Here is an example of a DLL you can use with Game Maker written in Delphi. (Note that this is Delphi code, not GML code!)

library MyDLL;

uses SysUtils, Classes;

function MyMin(x,y:double):double;  cdecl;
begin
  if x<y then Result := x else Result := y;
end;

var res : array[0..1024] of char;

function DoubleString(str:PChar):PChar; cdecl;
begin
  StrCopy(res,str);
  StrCat(res,str);
  Result := res;
end;

exports MyMin, DoubleString;

begin
end.
This DLL defines two functions: MyMin that takes two real arguments and returns the minimum of the two, and DoubleString that doubles the string. Note that you have to be careful with memory management. That is why I declared the resulting string global. Also notice the use of the cdecl calling convention. You can either use cdecl or stdcall calling conventions. Once you build the DLL in Delphi you will get a file MyDLL.DLL. This file must be placed in the running directory of your game. (Or any other place where windows can find it.) You can also use a data file resource to store the DLL inside the game.

To use this DLL in Game Maker you first need to specify the external functions you want to use and what type of arguments they take. For this there is the following function in GML:

external_define(dll,name,calltype,restype,argnumb,arg1type,arg2type, ...) Defines an external function. dll is the name of the dll file. name is the name of the functions. calltype is the calling convention used. For this use either dll_cdecl or dll_stdcall. restype is the type of the result. For this use either ty_real or ty_string. argnumb is the number of arguments (0-11). Next, for each argument you must specify its type. For this again use either ty_real or ty_string. When there are more than 4 arguments all of them must be of type ty_real.
This function returns the id of the external function that must be used for calling it. So in the above example, at the start of the game you would use the following GML code:
{
  global.mmm =
  external_define('MYOWN.DLL','MyMin',dll_cdecl,
                                    ty_real,2,ty_real,ty_real);
  global.ddd =
  external_define('MYOWN.DLL','DoubleString',dll_cdecl,
                                    ty_string,1,ty_string);
}
Now whenever you need to call the functions, you use the following function:
external_call(id,arg1,arg2,...) Calls the external function with the given id, and the given arguments. You need to provide the correct number of arguments of the correct type (real or string). The function returns the result of the external function.
So, for example, you would write:
{
  aaa = external_call(global.mmm,x,y);
  sss = external_call(global.ddd,'Hello');
}
If you don't need to use the DLL anymore you better free it.
external_free(dll) Frees the DLL with the given name. This is in particular necessary if the game should remove the DLL (e.g. because it is a data file). As long as the DLL is not freed it cannot be removed. Best do this e.g. in an end of game event.
You might wander how to make a function in a DLL that does something in the game. For example, you might want to create a DLL that adds instances of objects to your game. The easiest way is to let your DLL function return a string that contains a piece of GML code. This string that contains the piece of GML can be executed using the GML function
execute_string(str) Execute the piece of code in the string str.
Alternatively you can let the DLL create a file with a script that can be executed (this function can also be used to later modify the behavior of a game).
execute_file(fname) Execute the piece of code in the file.
Now you can call an external function and then execute the resulting string, e.g. as follows:
{
  ccc = external_call(global.ddd,x,y);
  execute_string(ccc);
}
In some rare cases your DLL might need to know the handle of the main graphics window for the game. This can be obtained with the following function and can then be passed to the DLL:
window_handle() Returns the window handle for the main window.
Note that DLLs cannot be used in secure mode.

Using external DLLs is an extremely powerful function. But please only use it if you know what you are doing.