csanyk.com

video games, programming, the internet, and stuff

Category: GameMaker Tutorials

High quality tutorials for GameMaker, GameMaker Studio, and GameMaker Studio 2.

GameMaker Tutorial: Configuration system

Many games have options or settings that are configurable.  The specifics can vary widely, from graphics options to music and sound effects volume to to input configuration to in-game options such as difficulty level and which rules are enabled/disabled.

This article will cover how to create a basic configuration system, using external file i/o, ds_map, and json.

Define your configuration requirements

First, before you develop it, design the system.  Not every variable in your project need be subject to customization. Decide what configuration options you want, and define the variables that will be needed to control them, and decide on your default values. 

The default configuration should be safe to run on all devices the game is intended to run on, and should have the “standard” or “recommended” settings for the best or recommended game experience. 

Having defaults is important in case the external config file is missing or corrupted, and needs to be regenerated.  Create a ds_map called defaults, and use it to store all the default values.

Coding the config system

Coding a simple config system is actually very easy.

First, define variables to store the default configuration and the actual configuration, and create ds_maps for them.  The best time to create these ds_maps is immediately on launch, as soon as the program starts.  You may want to make these global variables, so that they will be accessible anywhere and will persist for the entire runtime.

global.defaults = ds_map_create();
global.config  = ds_map_create();

Of course, when we are about to exit the game, we will need to remember to destroy these data structures, to properly free up the RAM:

ds_map_destroy(global.defaults);
ds_map_destroy(global.config);

Next, initialize the defaults ds_map with all the variables that are part of the configuration, and their default values. It’s easiest to learn the shortcode for accessing ds_map values:

defaults[? "key"] = value;

In the code above, “key” is the name of your variable, in quotes, as a string. The value is the literal value of the variable.

So you can do this:

global.defaults[? "starting_lives"] = 3;

or

global.defaults[? "starting_lives"] = default_starting_lives;

As you can see, the ds_map’s key indexing allows you to choose meaningful names for the keys, which makes it easy to recall them later.

When you apply the configuration to the variables in your project, assign the value from the ds_map, like this:

variable = config[? "key"];
starting_lives = config[? "starting_lives"];

Once you have your ds_map populated with your configuration data, it’s time to write it to disk.  This is will save the file so that the configuration state can be read and applied to the game state the next time the program runs.

The gml function json_encode() makes it very easy to write the ds_map to a file, by converting the ds_map into json, or JavaScript Object Notation, which is just a commonly used data format, and can be thought of as a specially formatted string. You don’t need to know anything about the syntax of json in order to use the encoding/decoding functions.

Create a json-encoded string version of the config ds_map:

config_string = json_encode(global.config);

Check to see if an external config file exists already, and if not, create it and fill it with the default configuration:

if !file_exists(working_directory + "config.json")
{
config_file = file_text_open_write(working_directory + "config.json");
file_text_write(config_file, defaults_string);
file_text_close(config_file);
}

If the config file already exists, read it into a string variable, decode the json string to convert it back into a ds_map, validate the data in the ds_map, and, if valid, apply the configuration data:

//First read the json data out of the config file
config_file = file_text_open_read(working_directory + "config.json");
config_json = file_text_read_string(config_file);
file_text_close(config_file);

//Next, decode the json, converting it to a ds_map
global.config = json_decode(config_json);

//Now, validate the configuration data to verify the settings are good
if !config_validate(global.config) //config_validate is a script that you wrote to validate your custom configuration data.
{
   //if we failed validation, destroy the config and create a good copy using defaults.
   ds_map_destroy(global.config);
   config = ds_map_copy(global.default);
}

[...]

//apply data stored in global.config to the variables in your project as needed, where and when appropriate.

The exact details will vary depending on your project, but the above is a good example to follow to get  you started.

Implementation: Data and File I/O

It might help to explain the above, in plain English, without the code examples getting in the way.

When the game runs, the very first thing the program should do is check to see if a configuration file exists.   If it exists, we read the data out of the file using file_text_string_read(fileid) and json_decode(string).  This returns a ds_map of key:value pairs that contain all the configuration data. If the config file does not exist, then we create it, populating it with our default data values.

Next, if we’ve successfully read data out of our config file, we need to validate the configuration data that we read from the file. If the configuration data is invalid, depending on the setting and the value, the game will not work properly, and may crash or may perform unexpectedly or break.  Your program may have written the data incorrectly, or it might have a bug that results in a corrupted file, or the user may find the file and manually edit it, and introduce errors.  So check each value in the configuration ds_map, and verify that it is valid by checking to see if the value is of the correct data type (string, number, or boolean), and that it is within the range of acceptable values for that variable.  Write a script that does this, according to the particular needs of your game.

If validation fails, whether because the file is missing, or because one of the values found within it is incorrect, we can handle this in several ways.  One way is to reset all values back to their default values. Another way is per-setting, restoring the invalid value back to the default value.  Or we can simply display an error message to the player and exit the program. Decide what is best for your project, and implement it that way.

Usually, I recommend checking whether the file exists, and if not, regenerate it using defaults, and if it exists, restore individual settings to default one by one if there is an invalid value, rather than resetting the entire configuration back to the defaults if any of the values is invalid.  This way, a small error in the config file doesn’t blow out all the settings, and program will leave any valid customized settings alone, so that the user will only need to correct the values that were reset to default.

If we have a valid configuration, the next step is to apply those values to the game variables. 

Once the game variables have been set, the game is now ready to run.

Editing the configuration

One great thing about storing the configuration data in an external file is, we no longer need to re-compile the game every time we wish to tweak the settings.  This can greatly speed up testing, as compilation can take a minute or more each time, and this rapidly adds up when  you’re quitting, coding, re-launching again and again as you develop. So use the configuration system as  you test your game design.

We can edit the configuration in various ways.

The simplest to develop is to develop nothing; just rely on the user to find the configuration file on disk, open it up with a text editor, and change values, save the file, and run the game again.  You’ll find the writeable working directory for your game somewhere inside of %appdata% in a Windows build, but if you’re building the project for other platforms, you’ll need to find it.

While this is the easiest approach, this isn’t the most user friendly solution. A better user experience would be to put a GUI in the game to change the settings, and let the game program edit the config file.  This will be safer for the user, as you can constrain the input and check it for valid values before saving the config file.

The downside is that this can take a lot of extra work to build the user interface. Sadly, GameMaker does not provide a library of user input controls, such as buttons, checkboxes, text boxes, sliders, and so on. So to build the UI, we first have to build these controls.

This is a great opportunity for beginner programmers to get some experience designing and programming their own controls.  But it’s also a time-consuming task, and can be a frustrating challenge for a newbie programmer to figure out how to make a collection of robust, bug-free UI controls that are easy to use, work together, and behave in a way that the user expects based on their experience using other software. And doing this takes time away from developing the game part of the project.

It’s a lot of work, so having an easy way out is a good thing. There are assets available through GameMaker marketplace, which can be purchased for a few dollars, and provide the needed functionality. Either way, it’s good to have a set of reusable controls that you can put into any project, so whether you buy some, or you decide to make your own, you can get a lot of value out of them.

Advanced concerns

Storing arrays, ds_structures inside json

Up until now, the examples I’ve given have all been simple data types.  If you want to store something else, like an array, or a data structure, or graphics data, it gets more complicated.  This article is just an intro level tutorial, so it won’t cover these advanced topics.  But I expect I may cover them in the future, at some point.  Many games will not need the advanced techniques to store the basic configuration data.

Applying config to application state

Certain configuration changes, such as display size settings, will require the room or game to be restarted before they take effect.  In such case, you may need to use game_restart() or room_restart(). If you are confident that the data is being applied correctly to update the game variables, but you’re not seeing the change, try a room restart and see if the changes take effect.

But any room or game restart will restart the game in progress, and that may not be what you want to happen at all!  If you have a game where you can change the configuration from the Pause screen, for example, you will not want to disrupt the running game.  In that case, you’ll need to go further and handle this in some way, such as:

  1. Display a message to the user saying that the changes will take effect after they quit and relaunch the game.
  2. Give the play the option save the present game-state and then restore it with the new configuration in effect.

Details on exactly how to do this will vary considerably depending on your game’s design, but if you need to do this, you’ll essentially be building a save state feature for your game, and then calling it to save and then restore the game after the restart.

The basic logical flow of this process is as follows:

If <config change will require restart> and <game is in progress>{ save game-state to external file; restart;}

On re-start, check for existence of a game-state file, and if it exists, clear the room of default starting instances; restore room from game-state; then delete the game-state file.

This sounds fairly straightforward and simple, and, in concept at least, it is.  The difficulty is with storing all of the instances and their state data. Depending on the game, you may have hundreds of instances, and each instance may have a lot of data, and all of it needs to be written to file, then read back out of file, in order to reconstruct the game in the state where it left off.

Making it tamper resistant

You may welcome the user tinkering with the config file, or you may want to protect the config file against unwanted tampering. Usually this isn’t critical for a config file, but for a save file or a high scores file, it might be important to prevent cheating. If your game uses password-protected user accounts, or stores any kind of financial data or purchase records, you should be storing that data securely.

This should be all you need. I won’t get into technical detail here, but will outline a few tools you can make use of.

  1. Use ds_map_secure_save() and ds_map_secure_load() to securely store the configuration data in an encrypted file. The encrypted file will not be editable by a curious user. The manual doesn’t give detail about what encryption is used.  Depending on how serious you are about protecting the data, you will want to research encryption and use an algorithm that hasn’t been broken. Don’t attempt to invent your own encryption.
  2. Create a cryptographic hash of the configuration data string, and store the hash with the file.  When you read the file, re-hash the data you read out of the file, and verify that the hashes match.  If they don’t, something has changed, and you know the file has been tampered with or corrupted.  In this case, you should re-generate the entire config file from defaults. 

    Look at GML’s md5 functions to get started.  GML also provides sha1 hashing for this purpose. MD5 hashes are no longer considered secure, and sha1 is also no longer considered secure, but may be “good enough” for non-critical needs. While not “hacker proof” they will prevent casual tinkerers from being able to modify the data.

Saving external data for other purposes

Now that we know how to store data in an external file, retrieve it, validate it, and use it at runtime, there are other applications we can use these techniques for. 

The most obvious one that comes to mind is save states.  I’ve already touched on this above, in brief.  Other ideas include:

  1. High score, leaderboard, and achievement data.
  2. Telemetry data for debugging or analytics.
  3. User profiles (to allow multiple users of the same machine to each have their own configuration and save file preference).
  4. Level Editors.
  5. Mod packs, to allow a community of players to make custom modifications to your game, such as level data, or other external resources like sprites and sound effects, etc.

As these features become more and more advanced and complicated, they’re really best left to professionals working on commercial projects.  But by following the approach described in this article to do a simple configuration system, you’ll have taken the first steps toward getting your skills up to that level.

GameMaker Tutorial: Audio speedup with sync

In so many games, music speedup is a great way to get the message to the player that they need to hurry up and get things done.

It’d be great if you could simply set a new tempo with a simple GML function, and have the current background music adjust on the fly. Something like audio_sound_set_speed(sound, speed) would be lovely. But it’s not as simple as that in GameMaker, as I found out recently.

Here’s how I implemented a speedup for my GMLTetris project:

First, I created two music tracks, one at normal speed, and one at double speed, and added them to the game project as sound assets.

Everything else is just programming:

if <condition> {stop slow_music; start fast_music;}

This is easy enough, the trickiest part is probably getting the condition right to switch tracks, but depending on the game, that condition could be very simple, too.  The only real complication is that if you’re checking the condition repeatedly, as you normally would every Step, you only want to trigger the changeover once.  So to do that, set up a variable to track whether the switch has happened already, and check it, too, even if the condition that triggers the changeover continues to remain true on successive steps.

if <condition> && !music_switched {stop slow_music; start fast_music; music_switched = true;}

The music speedup that happens in a game like Super Mario Bros., where the music speedup occurs when the level timer hits 100, is a typical example of such a technique. If you only need to do a single, one-way switch, this is all you need.

If your game needs to switch back and forth between slow and fast music, your conditional needs to be more sophisticated.

if <condition>
{
   if !<fast_music_already_playing>
   {stop slow_music; start fast_music;}
}
else
{
   if !<slow_music_already_playing>
{stop fast_music; start slow_music;}
}

Here, because the game can switch multiple times, when the condition check happens, we can’t get away with a music_switched variable that changes one time. What we need to do is check to see if the music we need to switch to is already playing, and if not, stop the current music and switch to the other music.

One thing to keep in mind, this basic technique will start the fast music from the beginning of the track. This might be what you want, but it would also be good if you could start the fast music at the position where the slow music was, for a seamless transition.

GML has the functions to do this: audio_sound_get_track_position() and audio_sound_set_track_position(). But in order to make use of them, we need to do a bit more work.

First, since the gml functions return the absolute time position of the track, and since two tracks play at different speeds, we need to adjust the position proportionately when we switch tracks, so that the position is at the same position percentage-wise. This is actually easy, as long as we know the tempo change, which we do. Since the fast track is double speed, we can easily calculate the equivalent position in the other track by multiplying or dividing by 2.

Slow to fast: position *= 0.5;

Fast to slow: position *= 2;

Where I ran into trouble was, I needed to be able to switch both ways. It seemed like it should be simple — just check whether the desired track is already playing, and if not, get the position of the current track, adjust it proportionately, start the desired track, set the position. Easy, right?

Let’s look at it in pseudocode first:

if <condition to switch to fast music>
{
   if audio_is_playing(slow_music)
   {get position; stop slow music; start fast music; set position;}
}
else
{
   if audio_is_playing(fast_music)
   {get position; stop fast music; start slow music; set position;}
}

This was when I discovered that audio_play_sound() returns a handle for identifying the specific instance of the sound that is playing. This is necessary to use to set the track position of the playing sound. You can’t just set the position for the sound_index; you have to set it for the specific handle of the currently playing instance of the sound. If you set the track position for the sound_index, any time that sound resource is played in the future, it will start from that position.

///Create Event:
bgm = audio_play_sound(slow_music, 10, true);
///Step Event:
if <condition>
{
  if audio_is_playing(slow_music)
  {
  var pos = audio_sound_get_track_position(bgm);
  audio_stop_sound(bgm);
  bgm = audio_play_sound(fast_music, 10, true);
  audio_sound_set_track_position(bgm, pos * 0.5);
  }
}
else
{
  if audio_is_playing(fast_music)
  {
  var pos = audio_sound_get_track_position(bgm);
  audio_stop_sound(bgm);
  bgm = audio_play_sound(slow_music, 10, true);
  audio_sound_set_track_position(bgm, pos * 2);
  }
}

I also discovered that detecting which track is playing with audio_is_playing() does not work for this purpose. I still don’t have a clear understanding of what was happening in my code, but some debugging showed that my track position calculations were being distorted by being called multiple times. This doesn’t make sense to me because the song should no longer be playing after the first step when the switch condition is met. But my theory is that since the audio is played in another process from the main program, there’s some messaging going between the two processes asynchronously, and as a result audio_sound_is_playing() can return true a step later after the message is sent to stop the track playing.

By trying to set the track point multiple times in quick succession, weird and unexpected results happened, and the tracks switched but did not set to the correct position.

So I had to come up with a surer method of knowing which music is playing.

Debugging was tricky, since I couldn’t tell from listening where the audio position was. To aid debugging, I drew the position of the playing track to the screen, and then I was able to see that the position was not being set correctly as expected. Somehow, switching from slow to fast would drop the track back from about 10 seconds to 2 seconds, and then switching from fast to slow would jump from 2 seconds to 38 seconds.

I couldn’t figure out why that was happening, so I tried using show_debug_message() and watched the output console, and saw that the track position would update 2 or 3 times when the tracks switched; I was expecting it to only update once.

This is what clued me in to what I believe was happening due to the multiple processes communicating synchronously.

The solution I used in the end was easy and simple: instead of checking which track was currently playing, and switching from slow to fast or vice versa based on the currently playing audio asset, I just added a new variable, condition_previous, and compared condition to condition_previous, and made the switch happen only when the current condition didn’t match condition_previous. This only happens in one step, when the condition changes from false to true, or vice versa, and so the track position is set once, when the bgm switches tracks and syncs up the new track to where the old track left off.

switch_previous = switch;

switch = <condition to check for switching to the fast music>;

if switch && !switch_previous
{
var pos = audio_sound_get_track_position(bgm);
audio_stop_sound(bgm);
bgm = audio_play_sound(fast_music, 10, true);
audio_sound_set_track_position(bgm, pos * 0.5)
}
else
{
if !switch && switch_previous
{
var pos = audio_sound_get_track_position(bgm);
audio_stop_sound(bgm);
bgm = audio_play_sound(slow_music, 10, true);
audio_sound_set_track_position(bgm, pos * 2);
}
}

This works, because it guarantees that the condition checks will be accurate, as they do not depend on checking the status of the audio playing in another thread.

GameMaker Tutorial: Delta Time

What is “delta”?

Delta is a term often used in math and science to indicate change. For example, in physics calculations, the term ΔV (pronounced “delta-vee”) is used to quantify a change in velocity as measured at two different moments in time. If you didn’t have an introduction to this concept in your education, it can seem mysterious why we talk about “delta” like this, but it is a common convention.

Background

In videogames, the game program incorporates a routine called an update loop, which repeatedly applies the rules of the game to the game’s present state in order to create the next game state. Normally, it is desirable that the program control its frame rate, the number of times this update loop executes per second, so that a consistent frame rate is achieved, in order to have the game run smoothly and consistently. Ideally, this frame rate would be constant and unvarying.

Achieving this in practice can be quite complicated. Back in the old days, when games were programmed in Assembly for specific hardware platforms, and the game program ran on the bare metal, the programmer relied on the CPU clock and the timing it took to perform various operations to ensure that everything worked in sync. This required great effort and intimate understanding of the hardware and program code.

For the most part, GameMaker makes things simple enough for basic game development, and you don’t have to worry about regulating the frame rate yourself.

In older versions of GameMaker, there’s a room property, room_speed, which sets a target number of steps the update loop will attempt to execute per second.  Typically, this is set to a value that aligns nicely to the refresh rate of the display — often 30 or 60.

In GMS2, room_speed is replaced by a global option in the project’s properties.  (Cog symbol) -> Main options -> General and set “Game frames per second”.

This simple approach, simply setting a frame rate through the Game FPS or room_speed properties, works well enough for many projects.  Just set the desired frame rate and let GameMaker manage itself to try to achieve this target frame rate.  As long as the program is able to do so, everything will run as desired.

We can run into problems, though, because of the limitations of the computer hardware to perform all the calculations needed during the update loop to generate the next game state.  As long as the computer has plenty of resources, it should have plenty of time to generate the next game state.  But if those resources are not available, or if the game demands too much work be done to allow the available system resources to create the next game state in time, the game will not run smoothly.  The program will not crash, but it may slow down or stutter, or perform in a jerky manner.

It’s not really avoidable; to avoid the problem completely, you would need to write the game in such a way that it was guaranteed that the program always requires the same amount of calculations to be performed per step, and always has the same system resources available to perform those calculations.  The first is very unlikely, and would impose constraints that would make the program’s design very rigid. The second is well beyond your control, unless you’re writing software that has direct control over the hardware it’s running on, rather than writing an application that runs on top of an operating system that also supports numerous other multi-tasking programs and services.

The solution is to write efficient code that has an extremely good chance of running all the calculations for the next game state before that game state is needed for drawing the game to the display, so that there will never be a delay that results in a dropped frame.  Doing this requires that you mostly write small, simple games, and run them on hardware robust enough that it will easily be able to guarantee that sufficient resources are available in order to complete the computation required, on time, every step. Those are both significant downsides, but even so you can create a great many games within those constraints these days, without too much of a problem.

But there’s still things that are out of your control, even if you write a small program with very efficient code. You can’t control what hardware the user will run the game on.  You can’t control what other processes might also be running on that system, in the background, while the game program is running. These uncontrolled factors can defeat all your efficient programming and give a poor experience at runtime on a system with insufficient resources to perform all the instructions that it needs to, on time.

Enter delta time

When the simple approach isn’t good enough, it’s time to turn to a concept involving delta time.  This is simply measuring, each step, the amount of time that has passed since the previous step.  This amount will vary from step to step, depending on how much work the game had to do to generate that step, and how much hardware resources were available to perform that work, in addition to whatever else the operating system may have been doing.

Once you know how much time has passed, you can use this to make adjustments in various things that depend on time, such as movement speed, timers, sprite animation speed, and so on, to keep everything looking smooth.

In a simple game, you would normally just set an instances speed to some value, V, and every step the game would update by moving the instance V pixels in direction theta.

In a delta timed game, you would first measure the amount of time that has passed since the previous step, calculate a ratio between this time and the number of game state updates desired per second (frames per second), and then use that ratio to modify the speed of everything in the game, so that even if the game runs a little behind in calculating everything, the end result is that the instance looks like it moves V pixels in direction theta each step.

Make sense?  It can be a lot to grasp at first, but it’s actually fairly simple.

Let’s look at it now in detail and walk through an implementation.

Implementing delta time

GameMaker provides a built-in global variable, delta_time, which is the time in microseconds that has passed since the previous step.  Since the engine performs this measurement for you, it’s very reliable, and all you need to do is use it.

A microsecond (μs) is one millionth of a second, or 1/1000000, or 0.000001. Typical GameMaker projects target a framerate of 30 or 60 steps per second, so each step is 1/30th or 1/60th of a second, or about 33333.333…μs per step for a 30fps game, and 16666.666…μs for a 60fps game.

So, if your game were running ideally, updating the game state every step exactly on time, every step’s delta_time should be exactly 33333.3… or 16666.6…  In the real world, you won’t hit those numbers exactly, but you’d expect that they should be very close, most of the time. (And in GameMaker, the value of delta_time drops the decimal, which introduces a problem down the road that we’ll have to deal with somehow… [[Hmm… maybe it’d be better to use a room speed that yields a whole number ideal delta_time?]] We’ll get to that in a bit.)  To the extent that delta_time differs from this ideal value, you can adjust all of the time-based variables that influence the game state, and if you do it all correctly, thereby smooth everything out.

It would be nice if you could just have a “use delta time” checkbox in your project, and all the built-in time-dependent variables — speed, hspeed, vspeed, image_speed, alarm[], etc. would just receive these adjustments by virtue of the engine, automagically.  Wouldn’t that be nice?

But for whatever reason, they don’t give us that feature, but at least they give us the built-in delta_time variable to work with.  So we’ll have to do that.  And of course, every other user-defined variable that we add to our project that depends on time will also need to be adjusted with delta_time.

So, if the game is running too slow, delta_time will be higher than the ideal value, because the amount of time that passed was longer than the ideal time.  In the game, instead of moving N pixels per step for 60 steps in a second, the instance would move N pixels per step, but only hit some number less than 60 steps per second, resulting in slowdown and jerky movement and animation.

To fix this, we should be able to see how:

ideal_delta_time = 1/room_speed * 1000000; //typically 33333 or 16666

This simplifies to 1000000 / room_speed. Next, we need to compare the measured delta between the previous step and this step (delta_time) to the ideal delta time:

dt_ratio = delta_time / ideal_delta_time

Now that we have the ratio for this step, we must use this ratio for all time-dependent calculations 

speed = ideal_speed * dt_ratio;

or, since computers multiply with fewer cpu instructions than they can divide:

speed = ideal_speed * delta_time * room_speed * 0.000001;

Or in other words, to move at an average speed of N pixels per step, you adjust the actual speed every step by multiplying it by delta_time/ideal_time:

speed = ideal_speed * (delta_time/ideal_time)

(Note, many games that use delta_time eschew the built-in speed system, instead using variables that are not managed by the engine, to give the programmer complete control over the motion. This is a very common approach taken with GameMaker projects, because the way the built-in variables are managed by the runner don’t offer the flexibility and control needed.)

Once we have the dt_ratio defined for this step, we don’t want to have to re-calculate this delta/ideal ratio again and again for every calculation performed in this step, so it’s best to do it once per step as a global variable, and have every instance that needs to use it reference this global value:

global.step_delta = delta_time/ideal_time;

That’s the basics of it.

Difficulties

The main problem that people have is that they have to adjust every variable in their game that is time-dependent.  Not just speed, but alarms, image animation, and possibly even such things as the pitch and duration of sound effects.  This can get tricky and drive you nuts.  Especially when you have things going on in your game like non-linear acceleration.

Another tricky problem with delta_time is the accumulation of rounding errors.

Let’s look at what happens when we want to use delta_time to achieve an average speed of 6 pixels/step:

speed = ideal_speed * delta_time * room_speed * 0.000001;

speed = 6 * delta_time * 30 * 0.000001

Let’s say that delta time is always exactly the ideal delta_time, 33333 microseconds.  That would give us:

speed = 6 * 33333 * 30 * 0.000001

speed = 5.99994 //shit. um...

Close enough, right?  Well, it adds up over time.  And keep in mind, if delta_time varies from the ideal_delta_time, the error can be larger.

Can’t we just round it?

Well… no.  We can’t.  Because it’s entirely possible, and even likely, that you can have a legitimate fractional speed as a result of delta_time adjustments, especially in the event that your game is lagging frames!  And rounding the value in that case would actually result in even more error.

Well, so what? Can’t we just live with it?

Maybe? I’m not sure what else you can do, honestly.  But this does leave us with problems. Even in the simple demo project that I’ve created, after just a minute or so, I can observe my control object deviate out of sync with the various delta-based objects.  Even the different delta-based objects will fall out of sync with each other, due to tiny differences in the way they calculate their deltas.

Most distressing of all, I’ve seen the objects glitch at their reversal point, getting stuck in the edge of the screen.  This isn’t consistent, and seems to depend on fluctuations in delta_time at just the right time to adjust the instance far enough outside of the room that the Intersect Boundary event will be triggers on two successive steps, resulting in the instance oscillating, becoming stuck on the boundary.

I’m still looking for a solution for how to fix this issue.

Manual errata

The manual gives us the following incorrect example:

speed = spd * (ot - delta_time);

Where ot is the value of delta_time from one step ago, e.g. a “delta_time_previous”.

This is wrong. The manual is in error, this is not how delta_time works.  It seems whoever wrote the manual was under a mistaken impression that delta_time is basically a point-in-time value of System.DateTime(Now) that is updated every Step, and that you would then need to calculate the actual delta by subtracting the current value for Now by the value of Now from the previous step.

The way delta_time really works, it is the number of microseconds since the previous step, essentially it is already the result of the expression “ot - delta_time” used in the example.  The correct implementation for the example should be:

speed = spd * delta_time/ideal_delta_time;

Alarms and animations

If you want to use delta_time to smooth out your movement, you should also consider whether you need to also consider delta_time with other time-based variables, such as image_speed.

Sprite animation is controlled by image_speed, and is normally set to a value of 1 by default, resulting in the sprite cycling through its sub-images at a speed of 1 per step.

An instance’s image_speed can be adjusted to speed up or slow down the animation speed.  At speeds slower than 1, the same sub-image will be drawn for more than 1 step in a row.  At speeds higher than 1, the animation will skip over sub-images.  At speeds less than 0, the animation will cycle in reverse.

If you’re using delta_time, and want your animation speed to also be delta_time-based, then the best thing to do is set image_speed to 0, and control animation manually.  Each step, increment image_index by 1 * ideal_time/delta_time:

image_index += ideal_time/delta_time;

Sprites can be set up and used in too many different ways to achieve customized ends, so if you’re storing sub-images in a sprite resource and selecting them in some other way than cycling through them as an animation, this is not necessarily going to apply.

For Alarms, you’ll want to stop using the Alarm Events that are built into GameMaker, and implement your own timer system. This is simple to do.

Step Event:

if timer >= -1
{
    timer -= ideal_time/delta_time;
    if timer <= 0
    {
          //do stuff
    }
}

You can have as many timer variables as  you need, and name them however you want, store them in an array if you want, or another data structure if you want.

Once you get used to it, you’ll probably like this better than the built-in Alarm system. YellowAfterlife’s article on Custom GameMaker Alarms is a great read for more information.

Capping the delta

Delta_time is intended to smooth out minor variations in fps, but if you have a longer interruption, delta_time will break your game. It’s useful to understand why and how, so you can prevent problems.

You’ll need to cap the amount of delta that you want the game to react to.  For example, if your game loses application focus, it will stop processing, essentially pausing the action.  The timer that delta_time is based on still keeps track of time however. This means that when you return application focus to the game, so much time will have passed that the ratio between ideal_time and delta_time will be enormous.  If your game uses this enormous ratio to adjust your game speed, it will almost certainly break the game.

Say you have switched application focus for a second to respond to an instant message you receive in another app. The instant you return to the game, the delta_time between the next step and the step your game paused at is going to be several seconds, instead of a value close to 1/30th or 1/60th of a second.  This means that in that step, everything in the game is going to move the equivalent of several seconds worth of distance, missing collisions that would have happened during those “missing” seconds”, and skip several seconds worth of animation frames, and count down several seconds worth of alarms, in just one step.  Things will go haywire — unless you cap the ideal:delta ratio.

You’ll want to experiment with your game and see where this limit should be set. It should be a value that is well short of any game-breaking bugs that a too-large ratio would cause. The exact value will depend on the specifics of your game.

To implement the cap is simple, though. Revising our earlier dt_ratio expression, we just use clamp() to cap it:

dt_ratio = clamp(delta_time / ideal_delta_time, min_cap, max_cap); 

The value of max_cap is your maximum allowed delta_time/ideal_time; min_cap is your minimum allowed delta_time/ideal_time.

Controlling the tempo

Delta_time can be used for more than just smoothing out your frame rate.  You can use these same ideas in slightly different ways to “control time” — that is to create a slow motion effect, or to speed things up like a “fast forward” effect.  To do this, just add in an extra factor, which I’ll call tempo:

speed_this_step = ideal_speed * (delta_time / ideal time) * tempo;

  • If tempo is equal to 1, the game will run at normal speed.
  • If tempo is >1, the game will speed up, moving faster than normal.  You can do this within some limits, but if you speed up the game too much, you’ll start having to deal with “high speed collisions” — situations where an instance moves so far that it can skip over objects that it should have collided with — which will require more work to handle correctly.
  • If tempo <1, the game will slow down.
  • if tempo == 0, the game will freeze.
  • If tempo < 0, the game will run backwards! (Not perfectly, though; any use of randomization will cause a loss of determinism which means that things won’t run backwards exactly as they ran forwards, only in reverse — and negative tempo won’t cause events like Collision, Create, and Destroy to “undo” or run in reverse.  But for certain uses, especially if used briefly and sparingly, this may not matter.)

How cool is that!  You can do a lot of things with this.

You can have a global.tempo, for controlling the overall speed of your game, and an instance.tempo factor that is unique to each instance.  Change the value of global.tempo, and the entire game will speed up or slow down; change the value of instance.tempo for selected instances, and only that instance will be affected.

speed_this_step = ideal_speed * (delta_time / ideal time) * global.tempo * instance_tempo;

A good range for tempo, for most games, is probably anywhere from 0.10 to 2.0 or 3.0 or so. But it will depend a lot on the specifics of your project, so you’ll need to experiment and test.

You use tempo to create a pause system easily, by applying delta_time to objects that are used in the game, setting global.tempo to 0, and controlling the global.tempo using objects that are not bound by delta_time so that they will remain responsive when the rest of the game is paused.

You could also create a script that performs this function:

///delta(ideal_value, global.tempo, instance_tempo) 
///@description returns value_this_step computed from ideal_value based on delta time, global and instance tempo values.

return argument[0] * (delta_time / ideal_time) * argument[1] * argument[2]; // We assume here that ideal_time is defined elsewhere in the project, probably as a #macro, or is represented inline with the direct calculation here.

Then when you use this script, you avoid code duplication, and it will make the code more readable:

speed = delta(10, 1, 1);

Beware bogus approaches

There are a few common approaches to implementing delta_time-like solutions that you may run into if you look at other people’s code.  I’ll touch on them briefly here, in order to explain why they’re not ideal.

Changing room_speed.  In older versions of GameMaker, before Studio, the program could change the room_speed and the GameMaker engine would adjust its speed on the fly.  This was very easy to do, but wrong.  For example, if you set the room_speed to 0, or a negative number, that would break the game.  A room_speed of 0 would freeze the game, and make everything stop, even the runner, so that the game would never update again.  And negative room_speed values are not allowed.

Later on, GameMaker was updated so that the room_speed variable could be changed during runtime (so it wasn’t a read-only variable) but that changes did not take effect at runtime for the current room, meaning you could not change room_speed in the current room and see immediate results; only by leaving and returning to the room, or restarting the room would the new room_speed be in effect.  This effectively ended adjusting room_speed as a viable approach.

Programmers who have the idea of how to do a technique like delta_time, but haven’t heard of it before, will sometimes “re-invent the wheel”, usually by using fps_real and room_speed to create a ratio similar to delta_time/ideal time.  This approach can seem at first to work, but it is always off because fps_real is the actual, achieved fps for the previous frame.  For the current frame, however, fps_real could actually be a very different value from what it was one step ago, meaning that if your game just did a huge amount of work in the previous frame, say to initialize new instances that were just created, and it doesn’t need to do that work in the current frame, the calculations could be way off, giving a poor result.  As long as fps_real is not changing dramatically from one step to the next, and is reasonably close to the target fps for the game, it will appear to work well, but when fps is very inconsistent, which is when you really need it, it will not work well.

If you see these techniques in use in a project, it can be a pain to convert from the bogus delta time technique to the good technique.  You’ll need to meticulously review the code for the entire project and find every place that uses the bad technique, and refactor it to use the good technique. Depending on how well documented the code is, and how expressive the code style is, this can easily get out of hand.  The best thing to do is to use version control and create a branch, and work on the conversion in the branch, and just focus on converting the delta time system before you go about making any other changes.  Take notes and put comments in the code to keep track of your progress, remind you of things that you need to do, need to test, or need to figure out.

Demo

In writing this article, I created a demo project to help me understand the concept of delta_time, and test various approaches. You can download it for free and play with it yourself.

Summary

  • Delta_time is simply the number of microseconds that have elapsed since the previous step. This value can be used to smooth out unevenness in frame rate if the program drops below the ideal frame rate.
  • It’s easier to implement delta_time if you decide to use it from the very beginning.
  • The basic delta time expression is: 
    N * delta_time * room_speed * 0.000001
  • You can adjust the tempo of the game even more by using global and instance tempo variables, and multiplying by those as well:
    N * delta_time * room_speed * 0.000001 * global.tempo * tempo
  • You can create a simple pause system (in part) by setting the global.tempo (or a custom pause factor varable) to 0.
  • Remember to consider things like animation speed and timers as well as movement.
  • Avoid using the built-in Alarms Events, movement functions and speed variables; it’s easier to manage everything if you take complete control over the position, speed, etc. by using your own system.
  • Cap the amount that delta_time can adjust your game, to keep things from going out of control after a long pause between frames.
  • Delta_time will result in values that are slightly off the ideal target value due to decimal imprecision/rounding errors.
  • Test thoroughly!

GameMaker Studio Tutorial: Getting Into Shaders

Shaders have been a part of GameMaker Studio for a while now, having been introduced in 2014. Since their inclusion, I have mostly remained mystified by them, with a vague and cloudy understand of what they are and what they can do, and haven’t used them at all. That will [hopefully] start to change today.

As always, when try I learn something new in programming, I find that writing up what I’ve learned helps me to remember and keep my learning organized. I like to publish my notes so that they can help others, and so that others can find errors and make suggestions for better ways to do things. I’m still very new to working with shaders, so I’m not trying to put myself out there like I’m some kind of expert, but here’s what I’ve been able to learn about using shaders with GameMaker Studio so far:

Shader basics

First, we need to understand what a shader is. A shader is a specialized program that processes graphics. Shaders are executed on the Graphics Processing Unit, or GPU, which is specialized hardware for accelerated graphics processing. Thus, shaders are very fast. As well, since they work on the GPU, using shaders will free up the CPU to do other tasks, which can further help to improve the frame rate of your games.

This sounds like enough of a reason to want to use shaders, doesn’t it? Well, it gets better. The main thing about shaders is that they can do amazing visual effects, which will can make your game look better, but can also play an active role in how the game plays. For example, you could use a shader to handle the graphical processing of a special view mode in the game, such as night vision or x-ray vision. One of my favorite shader-based gameplay mechanics that was centered on the use of shaders was Daniel Linssen’s Birdsong, winner of the “Overall” and “Theme” categories of the Ludum Dare 31 compo held in 2014. The theme of LD31 was “Entire Game in One Screen”, and Linssen’s approach to this was to create a giant one-room game, that was crammed into a single screen(no scrolling), and, using a fish-eye lens effect done with a shader, magnify the area where the player is so that it was large enough and detailed enough to be playable.

There’s virtually no limit to what graphical effects you can come up with using shaders, other than the limits of your imagination and of course your programming and math skills. It also helps to understand how computers work with graphical concepts such as color, pixels, binary math, and so forth. Additionally, scientific knowledge in disciplines like optics can be very useful. Shaders have their own specialized programming language that they are coded in — actually there are several related languages to choose from. Because of this, shaders are considered an advanced topic in programming, and there are numerous hurdles to surmount in order to be able to write them yourself.

That said, shaders are re-usable bits of code, and so one of the first things you can do when you start getting into shaders is to simply use pre-existing shaders that have been written by other people.

Getting Started with Shaders

Before you can use shaders, you’ll want to familiarize yourself with a few concepts.

Shader references

Here’s links to the relevant pages in the GMS manual on using shaders in the context of GameMaker Studio:

GMS1:

Shaders Overview

Shaders GML reference

Shader Constants

Tech Blog Shaders tutorial: 1 2 3 4

GMC Forums shader tutorial.

GMS2:

Shaders Overview

Shader Constants

 

Other shader resources (general)

Language References

The four shader languages that GMS supports are: GLSL ES, HLSL9, HLSL11, and GLSL. Which one you need to learn and use will depend on your target platform, but for this article we’ll focus on GLSL ES, since it supports the most target platforms (all of them, except Windows 8).

GLSL ES language specification

HLSL language specification

I haven’t gotten into the shader languages enough yet to know why you’d ever pick HLSL over GLSL, but presumably there must be some advantage to using HLSL when targeting Windows platforms, either in terms of correctness or performance. Otherwise, I would think you’d be better off just sticking with GLSL ES and be compatible with the most targets.

Tools

Shadertoy Shadertoy is a wonderful website that allows you to play with shader programming, running them in your web browser. Then you can share your shader creations with the community of users of the website, and in turn you can demonstrate and use shaders written by others.

Other graphical concepts in GameMaker, and how they relate to shaders

It’s not a bad idea to review and understand the entire chapter on Drawing in the GameMaker documentation. There are many concepts that you will need a working knowledge of in order to understand how to use drawing to its fullest capacity, and to get things working together smoothly.

But the manual isn’t the end of the story. Often I find that the manual doesn’t go far enough to explain how different concepts work. The sections on blend modes and alpha testing are particularly inadequate by themselves. The manual also doesn’t go very far to demonstrate or suggest how different features and functions can be connected to one another. That’s for the user to infer, and verify through experimentation. This is great if you are creative and love to experiment and discover. On the other hand, there’s so much that has already been figured out and discovered by others, and it would be nice if that was all documented in an easy to search reference somewhere.

Read the entire manual, cover to cover, if you can. Create little demo projects to test your understanding of what you’ve read, and figure out how to do things. Read it again. And refer to it whenever you need to. There’s no substitute for reading and understanding the manual. I’ll still touch briefly on the major concepts here, for summary:

Surfaces

All drawing happens somewhere, and in GameMaker that somewhere is called a surface. Behind the scenes, a surface is simply a chunk of memory that is used to store graphics data. You can think of it as a 2D grid of pixels, stored in the program’s memory, and drawn to the screen only when called for. You can also think of it as virtual “scratch paper” where you do some work “backstage” and then bring it out to use in the game when needed.

The application has an Application Surface, and by default everything is drawn here. But you can create other surfaces, which you can work on, composing a drawing off-screen, until you are ready to draw it to the screen. As you might imagine, there are countless reasons why this is useful, and endless ways to make use of surfaces.

Surfaces are relatively easy to use, but are considered an intermediate level programmer’s tool in GameMaker, for a couple of reasons:

  1. Surfaces consume memory, and need to be disposed of when no longer needed.
  2. Surfaces are volatile, and can be destroyed without warning, so should not be assumed to exist. For example, if the player switches focus to a different application, or if the computer enters sleep or hibernation mode, or if the game is saved and resumed, surfaces that were in existence at the time the application was last running may have been cleaned up by the operating system, and will need to be re-created if they don’t exist.
  3. All drawing must happen in one of the Draw events. If you try to use draw functions in other events, it may or may not work correctly, and this will vary from computer to computer. I once made a game where I did some set-up in the Create Event of an object, where I created a surface, drew to it, and then created a sprite from the surface, and assigned the newly created sprite to the object. It worked fine on my computer, but when other players downloaded my game to try it out, it did unexpected things and the graphics were glitched. Fortunately, I figured out what the problem was, and fixed it by moving this sprite creation into the Draw Event. Once I did this, the game ran correctly on everyone’s computer.

Drawings done to surfaces can be run through a shader, as input, and thereby be processed by the shader. In short, a surface can be the input image data for a shader, and the output of the shader will be the processed version of that surface, transformed by the shader.

Blend Modes

For a long time, long before GMS introduced shaders, GameMaker has provided blend modes. Blend modes affect what happens when GameMaker draws graphics over existing graphics that were drawn previously. Normally, when you draw something, it covers the pixels that were there before. But, by changing blend modes, you can do other things than simply replacing the previous pixels with new pixels, blending the old and the new in different ways according to the mathematical rules of whatever blend mode you had selected.

To be honest, I’m not sure what useful purpose there is for every blend mode. It would be great if there were more tutorials showing useful applications for them, especially the obscure ones that I don’t see used much, if ever.

The most commonly useful blend modes, in my experience, are bm_normal and bm_add. Normal blending is the default drawing mode, and is what you use 99% of the time in most games. Additive blending creates vivid glowing effects, and is particularly lovely when used in conjunction with particle systems to create glowing systems of overlapping particles, especially when you are drawing translucent pixels (using alpha < 1).

Blend modes are also useful for creating clipping masks. For more info on that, there are some good tutorials already written on how to create a clipping mask using surfaces and blend modes.

Some of the first questions I had when Shaders were introduced were: What do we do with blend modes now that we have shaders? Do we still need them? Can we combine them with shaders, somehow? Or do shaders make blend modes obsolete?

Basically, as I understand it, the answer seems to be that blend modes were kind of a limited predecessor to shaders, and enabled GM users to achieve some basic drawing effects simply, without exposing GM users to all that highly technical stuff that shaders involve, that I mentioned above.

Anything you could do with blend modes, can be done with shaders instead, if you wanted to. That said, if all you need is the blend mode, they’re still there, still supported like always, and you can go ahead and use them. They’re still simpler to use, so why not.

One thing to be aware of, though, when using blend modes, every time you change blend mode in GameMaker, you create a new “batch” of drawing. The more batches, the longer GM will take to draw the game each step. Thus, many batches can slow drawing down tremendously. This is an area where you may need to focus on optimization. And if you’re that focused on performance, then it might be worth looking into a shader-based approach instead.

Once you’ve become sufficiently comfortable with shaders, you may not have as much need for using GameMaker’s drawing blend modes.

D3D functions

I have not used GML’s d3d functions, much, either, so my understanding is very limited. Basically, as I understand it, the d3d functions in GameMaker wrap Microsoft’s Direct3D drawing functions, and enable drawing with more sophistication than is possible with the basic GML draw functions such as draw_rectangle, draw_line, draw_ellipse, etc.

Despite the name, the Direct3D functions are useful for 2D drawing as well as for 3D.

This article will not cover using GML’s d3d functions, as we’re focusing on shaders. But as any graphics in your game can be used as input into a shader program, anything you draw using d3d functions can become input for a shader to process.

Particles

Particles are “cheap” (efficient) graphical effects that can be created without having to instantiate an object. They are efficient because they do not incur all the processing overhead that comes with a full-blown object. Huge numbers of particles can be generated at very little cost. These can be used for all sorts of effects, so long as the particles do not need to interact with instances in the game, such as triggering collisions. Typically, particles are used for things like dust clouds, smoke, fire, glowing “energy plasma”, haze, rain, snow, and so on to create additional atmosphere.

To use particles, you have to create a particle system. As with Surfaces, particle systems take memory, and need to be disposed of when no longer needed, in order to free up that memory. Full detail on how to set up and use particle systems is beyond the scope of this article.

Several external utilities have been developed by GameMaker users over the years to make designing, building, previewing, and testing particle systems easier, and these are highly recommended.

In conjunction with shaders, I don’t know that there is any direct interplay between particle graphic effects and shaders, but certainly a shader may be used to further process a region of the room where particles exist, to create more sophisticated effects.

Using Shaders in GameMaker Studio

Right, now that we’ve introduced the concept of what a shader is, and reviewed the other main graphics concepts in GMS, here’s where we get to the heart of how to use shaders in GameMaker.

A shader is a pair of shader-language programs, consisting of: a vertex shader, and a fragment shader. Vertex shaders deal with the edges of the drawn area, while fragment shaders deal with the insides.

Let’s say you want to use a shader program that has already been written, perhaps by someone else. All you need to do is use this code in your draw event:

shader_set(my_shader);
 //draw stuff
shader_reset();

So, it’s a lot like drawing to a Surface. With surfaces, first you set which surface you want to draw to, then you draw, then you reset so that drawing resumes to the application surface. With shaders, you set the shader you want to use, draw the stuff that you want to be transformed by the shader, then reset to normal drawing.

Everything drawn between setting the shader and re-setting back to non-shader drawing will be drawn through the shader program.

Easy enough, right? Well, there’s slightly more to it than that.

Uniforms

“Uniforms” is a strange term at first, and was where shaders started to seem strange to me. This is a term that comes from the shader language itself. The GameMaker manual talks about them in a way that assumes the reader is already familiar with the concept, and doesn’t go into a lot of detail explaining it to newbies.

In essence, “uniforms” are input variables that can optionally be passed into a shader that is designed to use input values. Once you understand what a uniform is, it’s not that difficult a concept. You can read more about them at these pages:

The gist of it is, when writing a shader program, when you declare a variable, you can declare it to be a uniform variable, which means that the variable can be accessed from outside the shader, thereby giving the program that calls the shader a way to change the shader’s behavior during execution. To do this, you can’t just refer to the uniform variable by name; you have to get the uniform variable’s memory handle, using shader_get_uniform(nameOfUniformVariable), and then change the value of the variable using shader_set_uniform_f(nameOfUniformVariable, value). Uniforms are actually constants within the shader’s execution scope, so once a value is passed into the shader from the outside and it is set as a uniform, it cannot be changed (the value could be copied to another variable, and that variable could then be modified, though.)

If you’re using a shader that has uniforms that you need to set, it’s done like this:

u_color1 = shader_get_uniform(my_shader, "f_Colour1");
u_color2 = shader_get_uniform(my_shader, "f_Colour2");

shader_set(my_shader);
shader_set_uniform_f(u_color1, 1, 1, 1);
shader_set_uniform_f(u_color2, 1, 0, 0);
//draw stuff
shader_reset();

There are actually a few uniform functions in GML:

Conclusion

That’s about all I know about shaders, for now.

As I get more familiar with using shaders, I’ll update this with more complicated examples, such as (possibly):

  • How to use multiple shaders on the same drawing (eg chaining the results of one shader’s transformation of some drawing into the input for a series of shaders).
  • Other stuff…

How to write shaders in GLSL, if I ever do it, will be a topic for its own article (or series of articles).

A tale of two GML scripts: code optimization through iterative development

Today I wanted to share two versions of a function that I wrote, in order to show how my iterative approach to software development works when I am doing code optimization to improve performance.

This example comes from my iMprOVE_WRAP asset. It’s a function that returns the shortest distance (taking into account the wrap capabilities of the calling object) between the calling instance and a target object.

The first implementation works, in that it correctly does what it’s supposed to do, but I never released it, because I wasn’t satisfied that it was good enough code to ship.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
///iw_distance_to_object(target_obj, x1, y1, x2, y2, do_wrap_h, do_wrap_v,)
 
///@description Returns the distance_to_object from an improve_wrap object calling this function to another instance. 
///Compares all relevant points for the iw_object and returns the nearest distance, taking the wrap range into account.
///@param target_obj id of the target object to determine the distance to.
///@param x1 left x boundary of wrap range
///@param y1 top y boundary of wrap range
///@param x2 right x boundary of wrap range
///@param y2 bottom y boundary of wrap range
///@param do_wrap_h set whether the horizontal wrap is on (true) or off (false)
///@param do_wrap_v set whether the vertical wrap is on (true) or off (false)
 
 
//get the distance from the nine virtual positions
//return the shortest distance
var obj = argument[0];
var iw_distance, iw_distance_up, iw_distance_down, iw_distance_left, iw_distance_right, 
    iw_distance_up_left, iw_distance_up_right, iw_distance_down_left, iw_distance_down_right;
var tempx, tempy, shortest;
var x1, y1, x2, y2, range_width, range_height, do_wrap_h, do_wrap_v;
 
//keep track of original location of target object
tempx = x;
tempy = y;
 
//set up wrap range
x1 = min(argument[1], argument[3]);
y1 = min(argument[2], argument[4]);
x2 = max(argument[1], argument[3]);
y2 = max(argument[2], argument[4]);
range_width = x2 - x1;
range_height = y2 - y1;
 
do_wrap_h = argument[5];
do_wrap_v = argument[6];
 
//check distances
//check center
iw_distance = distance_to_object(obj);
 
if do_wrap_h && do_wrap_v //wrap vertical and horizontal
{
  //check corners
  x = tempx - range_width;
  y = tempx - range_height;
  iw_distance_up_left = distance_to_object(obj);
 
  y = tempx + range_height;
  iw_distance_down_left = distance_to_object(obj);
 
  x = tempx + range_width;
  iw_distance_down_right = distance_to_object(obj);
 
  y = tempy - range_height;
  iw_distance_up_right = distance_to_object(obj);
 
  //check left and right
  y = tempy;
  x = tempx - range_width;
  iw_distance_left = distance_to_object(obj);
  x = tempx + range_width;
  iw_distance_right = distance_to_object(obj);
 
  //check up and down
  x = tempx;
  y = tempy - range_height;
  iw_distance_up = distance_to_object(obj);
  y = tempy + range_height;
  iw_distance_down = distance_to_object(obj);
 
  shortest = min(iw_distance, iw_distance_up, iw_distance_down, iw_distance_left, iw_distance_right, 
                iw_distance_up_left, iw_distance_up_right, iw_distance_down_left, iw_distance_down_right);
}
if do_wrap_h && !do_wrap_v //do_wrap_h
{
  //check left and right
  x = tempx - range_width;
  iw_distance_left = distance_to_object(obj);
  x = tempx + range_width;
  iw_distance_right = distance_to_object(obj);
 
  shortest = min(iw_distance, iw_distance_left, iw_distance_right);
}
 
if do_wrap_v && !do_wrap_h //do_wrap_v
{
  //check up and down
  y = tempy - range_height;
  iw_distance_up = distance_to_object(obj);
  y = tempy + range_height;
  iw_distance_down = distance_to_object(obj);
 
  shortest = min(iw_distance, iw_distance_up, iw_distance_down);
}
if !do_wrap_h && !do_wrap_v
{
  shortest = iw_distance;
}
 
//return calling instance to original location
x = tempx;
y = tempy;
 
return shortest;

Let’s take a moment to appreciate this function as it’s written. It’s well-structured, documented, and expressive. First we declare a bunch of variables, then we do stuff with the variables, then we get our answer and return it. And this gives a correct result…

So what’s wrong with the above? It’s an inefficient approach, which checks each virtual position of the wrapping object. If the calling instance wraps vertically and horizontally, it has to temporarily move the calling instance 9 times and check the distance from each of 9 virtual positions, then return it back to its original position, only to return the shortest of those 9 virtual positions.

There’s also a lot of code duplication.

Still, it’s not horrible code. But it’s up to 9x slower than the distance_to_object() function it’s based on, if you’re wrapping in both directions, which will probably be common. I didn’t think that was good enough.

Rather than check each virtual location to see which is the shortest distance, we just need to know whether the horizontal and vertical distances are more than half of the width and height of the wrap region. If they are, then it’s shorter to go around the wrap. To know this, you simply take the x and y values of the two positions, subtract one from the other, and compare to the size of the wrap range. Once you know which virtual position is the closest one, you can temporarily place the calling instance there, and use distance_to_object() to get that distance. Put the calling instance back where it was, and then return the distance.

I realized as well that depending on whether the calling object wraps in both directions, you may not need to check for a wrap shortcut in the horizontal or vertical. So we can potentially avoid doing some or all of the checks depending on whether the do_wrap_h and do_wrap_v arguments are true or false. As well, this means we can avoid declaring certain variables if they’re not needed, which conserves both execution time as well as RAM.

I usually create local script variables in a var declaration, and assign the arguments to them so the code will be more readable, but I wanted to avoid doing that so that this function could be as lean and fast as possible. This might be an unnecessary optimization, but that’s hard to predict since I have no way of knowing ahead of time how this function might be used in a future project. In a project with many wrapping instances, it could very well be called many times per step, and every optimization could be critical. Since the script is intended to be included as a function in an extension, once I have it working properly it shouldn’t be opened for future maintenance, so making the script readable is not as important. So I opted to remove the local variable declarations as much as possible and just use the argument[] variables directly.

Also, to ensure that the wrap range is defined properly, in the non-optimized version of this function, I declare x1, y1, x2, y2 and assign their values using min() and max() so that (x1, y1) is always the top left corner, and (x2, y2) is always the bottom right corner of the wrap range. Technically for this function, we don’t care precisely where the wrap range is, only what the width and height of the wrap range are. That being the case, I can further optimize what I have here, and rather than use min and max, I can just take the absolute value of the difference of these two values.

It turns out that the process I went through to optimize this function is pretty interesting, if you care about optimizing. So I’ll go into greater detail at the end of this article about the approach I took to get there. But for now, let’s skip ahead and look at the finished, optimized function. Here it is, re-implemented, this time doing only the minimum amount of work needed:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
///iw_distance_to_object(obj, x1, y1, x2, y2, do_wrap_h, do_wrap_v)
 
///@description iw_distance_to_object returns the shortest distance in room pixels between two objects in the wrap range, 
///taking into account the horizontal and/or vertical wrap properites of the calling object.
///@param obj the id of the target object
///@param x1 left x boundary of wrap range
///@param y1 top y boundary of wrap range
///@param x2 right x boundary of wrap range
///@param y2 bottom y boundary of wrap range
///@param do_wrap_h set whether the horizontal wrap is on (true) or off (false)
///@param do_wrap_v set whether the vertical wrap is on (true) or off (false)
 
 
if !(argument[5] || argument[6]) //not wrapping actually
{
 return distance_to_object(argument[0]);
}
else
{
 //We're going to figure out which virtual position is the nearest to measure from
 //To do that, we have to compare the h-distance and v-distance of the calling instance and the target position
 //If this distance is <half the range size, then the original position of the calling instance is closest
 //Otherwise we have to use one of the virtual positions
 //Then we're going to temporarily put the calling instance in that location, get the distance, and put it back 
 
 //arguments
 var tempx = x, tempy = y;
 
 if argument[5] //do_wrap_h
 {
   var range_width = abs(argument[3] - argument[1]);
   if abs(x - argument[0].x) > (range_width * 0.5)
   {
     x -= sign(x - argument[0].x) * range_width; 
   }
 }
 
 if argument[6] //do_wrap_v
 {
   var range_height = abs(argument[4] - argument[2]);
   if abs(y - argument[0].y) > (range_height * 0.5)
   {
     y -= sign(y - argument[0].y) * range_height;
   }
 }
 
 var d = distance_to_object(argument[0]);
 
 //return calling instance to where it was
 x = tempx;
 y = tempy;
 
 return d;
}

We don’t need to measure all nine distances to know which is the shortest; we can tell by comparing the direct distance to the size of the wrap zone — if it’s less than half as big as the wrap zone, the direct distance is the shortest. If not, then we need to wrap. We can check the x and y axes separately, and if both are called for then we can just combine them.

The second function should be much faster to execute, and uses less RAM. How much faster? Well, let’s do a test project using my Simple Performance Test and compare.

Download the iMprOVE_WRAP distance_to_object test project

It turns out that the improved code runs about 50% faster than the old code! That’s a measurable and worthwhile improvement. Although, that said, the old function ran well enough that I could have released it, and likely it would not have been a problem for many uses, particularly in Windows YYC builds.

Appendix: Optimization through Iteration

(more…)

GameMaker Tutorial: Instance Pooling for performance optimization

Instance pooling is a design pattern which can potentially help performance in games where you are creating and destroying a lot of instances.

If your program is spawning and destroying objects very frequently, calling the Create and Destroy Events many times per step, it’s potentially a lot of extra processing. Creating instances and destroying others constantly seems wasteful. Why destroy the instances that need to be destroyed when instead you can re-use them, and avoid having to call the Create event on a New instance every time you need one?

The Code

You can download my demo code here:

The GMS2 demo is an import of the 1.4 demo, cleaned up to remove the Compatibility scripts.

Looking at the project code, you will see that I have used inheritance to make the Control and Instance Pool test implementations as close to identical as possible. I have included telemetry code, which tracks the FPS of the game while it runs, so that performance is quantifiable. In the GMS1.4 version of the project, all of the telemetry code is neatly separated from the demo code into its own Execute Code action. This makes it easy to modify the project for your own use, and get rid of the telemetry code entirely if you don’t need to quantify runtime performance, and only want the code that actually implements the Instance Pool pattern.

How it works

The basic concept of the Instance Pool pattern is simple. The goal is to minimize the amount of times we create new instances of some object in large numbers during the game. A good candidate for objects to use Instance Pooling with would be bullets, bonuses, and enemies. Instance Pooling is particularly beneficial when the object in the pool is somewhat “heavy” — that is when the Create or Destroy events cause a lot of processing to happen.

The way we achieve this goal is by re-using already-existing instances of the object. This is done by deactivating the instance rather than destroying it. We add the id of all deactivated instances to our Pool. Then, when a new instance is needed, we first check the pool to see if an already-created but inactive instance exists, and if so, we remove it from the pool, activate it, and re-use it.

The most efficient way to create and manage our pool is with a stack. Stacks are elementary data structures in computer science. Imagine a stack of pancakes. The stack gets bigger as you add more pancakes to it. If someone orders a pancake, you take the top one off of the stack, and give it to them.

This is what’s known as Last In, First Out, or LIFO data access. This happens to be just what we need. The stack gives us an easy way to keep track of the id of all of our deactivated instances, and when we need to activate one, we just pop it off the top of the stack. This is very simple to do, and therefore very fast. In GameMaker, stacks are created by ds_stack functions. If you’ve never used them before, take a moment to read up on them. It will help you understand how the demo works.

The code at the heart of this is quite simple. It looks like this:

//First check the pool to see if it has any deactivated instances in it that we can use
 if ds_stack_empty(pool)
 {
 //If not, we need to create a new instance. No performance gain.
 instance_create(x,y,oInstancePoolBullet);
 }
 else
 {
 //If the pool has an instance we can use, take it out and activate it.
 var bullet = ds_stack_pop(pool);
 instance_activate_object(bullet);
 
 //Reset the state of the instance. 
 //**If** this is cheaper than a new instance, we gain performance.
 bullet.x = x;
 bullet.y = y;
 bullet.direction = direction + random_range(-20,20);
 bullet.alarm[0] = bullet.TTL;
 }

There’s only a little bit of other code that you need. You need to create the ds_stack, most likely this is best done in the Create Event, using ds_stack_create(). And when the pool is no longer needed, you need to destroy the ds_stack using ds_stack_destroy(), most likely in the Destroy Event.

Of course, we also need to push instances to the stack when they are no longer needed. To do that, we do this whenever we would ordinarily destroy the instance:

ds_stack_push(oInstancePoolPlayer.pool, id);
instance_deactivate_object(id);

So, don’t destroy instances that you want to pool; deactivate them instead. With our bullet demo, I do this by giving bullets a “time to live” and then setting an timer. When the alarm goes off, the instance’s id is added to the stack, and the instance is deactivated. Then it just waits for the game to need it. In a full game, you would need to look at other occasions where you need to deactivate the bullet, such as when it goes outside the room, off the screen, or when it hits an object.

That’s basically it. But you may need to think about some additional concerns, which I will cover in the Findings section of this tutorial.

Running The Demo

Open the project with GameMaker Studio, compile, and run.

The Demo consists of an Instance Pool demo and a Create-Destroy demo for comparison.

Press the Space bar to spawn bullets. Press Tab to switch from one demo to the other.

The FPS is displayed at the top-left of the screen. The first number is the minimum fps, the middle is the average fps over the last 30 steps, and the last number is the maximum fps. The minimum and maximum fps reset once per second. The average is a rolling average over the last second.

In the Instance Pool demo room, hold the space bar down until the first bullets to spawn reach the end of their life. At this point, the instance pool is filled, and no more instances will spawn; instead, deactivated instances will be re-used. At this point, you should notice the FPS dramatically shoots up and stays consistent.

Findings

To my surprise, I did not find that there was much benefit to creating an Instance Pool for bullets. Create and Destroy is about as fast as Instance Pooling with simple bullet objects in GameMaker. I expect the reason for this is that the GameMaker runtime engine is not particularly fast, but even when I did a YYC build, I still saw no real advantage to using an Instance Pool, at least in terms of fps.

Over a long game session, it may be that there is a reduction in memory fragmentation since we are updating values in RAM that has already been allocated, rather than rapidly allocating/de-allocating memory when we create new instances and destroy them constantly. But I haven’t tested that, so it’s merely speculation for now. Update: This benefit of reducing memory fragmentation is confirmed by Mike Dailly of YoYoGames.

In order to show a benefit to Instance Pooling, I had to weigh down the Create Event for my bullets. To do this, I ran a simple repeat loop to increment a variable. This is obviously inefficient and pretty pointless, but it serves the purpose of simulating a complicated object with an init script that takes some time to run. If that init script needs to be run only once, and not every time the instance is re-used, then there is a benefit and using the Instance Pool pattern will help.

When does it make sense to use the Instance Pool pattern? When there is a performance issue, and the Create or Destroy Events are more expensive than instance_activate_object() and instance_deactivate_object().

Setting up and managing the instance pool is pretty simple, but it does take some work, and incurs some overhead. It’s not worth it to incur this overhead unless there’s a tangible benefit in the form of noticeably improved performance.

Run the code profiler, and see where your code is spending the most time. If it’s heavy on Create and Destroy events, an instance pool might be just what the doctor ordered. Otherwise, you may want to look elsewhere for your low framerate fix.

Additional Considerations

As I mentioned, there are a few other considerations that you should think about when implementing an Instance Pool, which I will discuss here.

Should we Prime the pool?

In my demo, we only create new instances when there are none in the stack. This means that until we’ve deactivated our first instance, the stack is empty, and there is no performance gained by having it.

In fact, since we’re checking the stack before we create each new instance, there’s actually an infinitesimal hit to performance. When you run the Instance Pool room, we see pretty much the same fps performance as we did in the Create-Destroy room, until the first bullets start to be recycled. Only then do we see fps shoot up.

Well, what if we want the performance to be high from the very first bullet? We can do that, by priming the stack, by creating a bunch of bullets, and then immediately deactivating them and pop their id’s onto the stack.

We could create a special object that we might call oPoolPrimer, which lives for several steps, creates the instances we need and deactivates them, adds them to the Instance Pool stack, and then destroys itself when its work is done.

The best time to do this is when the performance hit won’t be noticed, such as when the game is in a menu screen. Alternately, we can create the instances gradually, over a longer time than would introduce a noticeable performance penalty.

To be effective, you will need to have a good way of calculating maximum the number of instances you need to have active in your game at any given time. Prime your pool with that many instances. That way, even when you have all of them active, you aren’t creating new ones, and your fps will stay high.

Trim the pool?

One of the downsides of the Instance Pool is that all those deactivated instances take up resources. Even though the CPU may not be spending as much time with those instances, they do incur some processing overhead to manage even when disabled, and as well they use some RAM.

Depending on your game, you might have a moment when you need a huge number of instances active, but in other parts of the game the action isn’t as intense, and you won’t need so many. For example, in my demo, I spawn 100 bullets per step, for 20 steps, resulting in some 2000 instances max if you hold the space bar down the entire time. But if you don’t need to shoot all the time, all those disabled bullets end up in the stack. Do you really need 2000 disabled instances? If there isn’t going to be as much shooting going on, you might not. We can free up resources by trimming the stack every so often.

One way to do this would be to set a recurring alarm so that every few seconds, the stack is trimmed if it goes over a certain size.

///Alarm0 Event:
while ds_stack_size(pool) > trim_limit
{
 //remove the top instance from the stack and destroy it
 with ds_stack_pop(pool) {instance_destroy();}
}
alarm[0] = reset;

This will keep the stack small when it doesn’t need to be so big.

Delete the pool?

If you delete the stack, you should realize that any disabled instances that we were tracking in the stack still exist. They will continue to do so until the game ends, or you change rooms. If you don’t change rooms right away for some reason, you may want to run through the stack before you destroy it, popping all the instances out of them so that they can be destroyed as well. Otherwise, those inactive instances will continue to take up resources.

while !ds_stack_empty(pool)
{
 //remove the top instance from the stack and destroy it
 with ds_stack_pop(pool) {instance_destroy();}
}
ds_stack_destroy(pool);

 

Benefits in network multiplayer games

This comes from GMC Forums user JuJu: There’s a nice implicit benefit of instance pooling: It makes handling multiplayer netcode for complicated scenes easier if you can refer to instances by a common index across all machines.

GMS2 Impressions: Tilesets and AutoTiling

One of the best new features in GameMaker Studio 2 is the improved tile system.

I never used tiles much in GMS1, because they were such a pain to work with, and did so little. In GMS1, tiles were a type of background resource. In the GMS1 room editor, you had to select your tiles manually, then place them one click at a time, which was very tedious. GMS users developed complicated auto-tiling scripts that would select the correct tile and place it in the room at runtime. This solution worked well, but was complicated to understand, set up, or modify. GMS1 tiles did not support animation, so if you wanted animated backgrounds, you either had to use sprites, or else come up with some sophisticated tile-swapping script that would programmatically animate your background tiles.

If you wanted your tiles to represent some kind of interactive object in the game, you had to also place an invisible object behind the tile, and program it to do whatever behaviors you needed. To me, there wasn’t much point in using tiles when I could just assign a sprite to the object, and use the object directly. If you did work with tiles in GMS1, then you may have to unlearn or relearn a few things before you feel comfortable with the new system.

I’m happy to say that in GMS2 the situation is much better. GMS2 tiles support animation and auto tiling. You can draw tiles in the room by the mouse without having to click each and every time you want to place a tile. This makes working with them much easier than it used to be.

However, there is still a lot of learning to do in order to develop the understanding necessary to set up tilesets and get the full use of them in your projects.

It took me an evening to figure out, about 4-6 hours, which isn’t bad. But after I had figured it out to the point where I have auto tile working, I realized that I could save others a lot of frustration by going a bit further to explain it.

Getting into GMS2 Tiles

First, the help manual articles on the Tileset Editor is essential reading. There are several articles which you should read first. And maybe a few YouTube videos are also helpful, to see the process of setting up a tileset for use within your project.

It’s actually pretty easy to use after you’ve gone through the process once so you understand it, but until you’ve completed your first working tileset, you’ll probably have a lot of questions and uncertainty about how it all works and what you’re supposed to do.

This article will guide you through that first time, and explain things so that they are easier to understand, and you’ll have an easier time of it than I did.

Before getting into that, there are a few constraints that you need to be aware of when working with tiles.

  1. The tile grid size must be a power of 2. So, for the most part, 8×8, 16×16, 32×32, or 64×64 tiles will be the sizes to work with.
  2. Any tile-based animations must have a number of frames that is a power of 2: 2, 4, 8, 16, etc.
  3. Tile positions in a room are constrained to a grid in GMS2. You can no longer position them at an arbitrary position in the room; they must snap to a grid the size of the tile.
  4. However, that entire grid may be offset, using the X Offset and Y Offset properties.
  5. Tiles are placed in layers, and you can use as many Tile Layers as you like in the Room Editor.

Now that we’ve covered that, let’s look at the Tileset setup and usage workflow.

GMS2 Tileset Workflow

First, let’s take a general overview of the entire workflow, before we dive deeper into each step:

Tileset setup

Before you can use a tileset to decorate a room, you have to set up a Tileset resource. A Tileset resource is a resource that depends on a Sprite resource, and defines how the image in the Sprite is sliced up to create a set of tiles.

  1. Create a sprite that will hold the image data for your tileset.
  2. Create a tileset asset.
  3. Define the tileset.
    1. Add the sprite from Step 1 to the tileset.
    2. Set tile size to split up the image into tiles.
    3. (Optional): Create any brushes, animations, and auto tile sets that are needed.
  4. Create additional tilesets, as needed.

Tileset usage:

This is where you put your tiles to work in the game. It’s all about creating and managing Tile Layers in your rooms, using the Room Editor.

  1. Add a tile layer to a room
  2. Select a tileset to use in the layer
  3. Add tiles to the tile layer.
  4. Add additional tile layers to the room, as needed.

Now that we’ve covered the workflow of Tile setup and usage at a high level, let’s go back and look at each step in depth.

Tileset Setup

Create a sprite that will hold the image data for your tileset

The first thing you need to do is create a Sprite resource, and add an image to it containing your tiles.

If you’re drawing this yourself, you’ll need to learn how to lay out this image. The first thing you’ll need to understand is that your tiles need to conform to a grid. You should set up the grid in the Image Editor to the size you’ll need for your tiles. I found that using an Image Editor grid that is half of what I want my actual tile size to be works well, so for a tile image that I wanted to draw that would have 32x32px tiles in it, I set the grid size in the Image Editor to 16×16. Then I drew out my tiles, using chunks that were 2×2 grid cells.

An important thing to realize in drawing your tiles is that your tile images should include some solid pixels as well as negative space surrounding the solid part of the tile. This is difficult to understand, especially at first, and it takes some getting used to the idea. To explain this properly, I need to illustrate.

tile_grid

As you can see here, I have drawn a brown rectangle, representing a solid object in the game room, and overlaid a green grid on top of it, showing how the tile borders should look if they’re done properly. Noticed that each tile (except for the center ones, which are completely solid) shows a certain amount of solid space and some white space.

I think a lot of people probably mistakenly think that their grid of tiles should look like this:

tile grid wrong

I know I did, at first. It’s hard to understand why tiles don’t work the second way — it seems a lot more obvious to position them that way, doesn’t it? After all, it takes fewer tiles, and there’s no overlapping into the negative space surrounding the solid object. If you’re just thinking about a simple rectangular platform or wall like this, it’s easy to think that it should simply be a 2×4 rectangle of solid brown tiles, all the same. The thing is, if you go back to the first illustration, you can see that in that illustration, we have many different types of tiles, representing edges, corners, and solid areas, working together to create the same rectangular platform, and since they’re not all the same tile, you can re-combine them in many different arrangements, to create other shapes.

Since the point of making the tile set is to enable you to create all the different types of edges and corners, you want to make sure that the sprite your tiles are drawn in is laid out in such a fashion.

We really need to create a ring so we can have inner and outer corners represented in our tile. We also need to have a tile representing a completely open space. By convention, GMS2 auto tile sets reserve the top left tile grid for this empty tile. Here’s a better image that shows all the different corner and edges that we’ll need for a complete tile set:

tile template

With this arrangement, we are able to create almost any arrangement of blocks, but we still have a few more tiles to create. We actually have a few duplicates in this tile set, which I’ll color code in the next illustration, as well as number the unique tiles.

tiles-14

As you can see, we have 14 unique tiles in this image, and a few duplicates. There are actually two more tiles that we’ll need to create a universal 16-tile auto tile set. They are:

tiles 15 and 16

We can consolidate space in our earlier image by eliminating some of the redundant tiles and replacing them with the ones we needed, like so:

tiles-16

Really, these tiles could be arranged in any ordering; this is just an example of one such arrangement.

There’s also a 47-tile auto tile but I think now that we’ve walked through the 16-tile auto tile set creation, you should be able to figure out the 47-tile version on your own. The ideas are the same, it’s just more work.

But just to make things convenient, here are two templates that I’ve created for 16×16 and 47×47 auto tiles, matching the order that the GMS2 Tile Set editor uses for its template:

16-tile tileset template for GMS2

16-tile tileset template for GMS2

47-tile tileset template for GMS2

47-tile tileset template for GMS2

You can right-click the images above, save, and use these for laying out your own tiles. No need to ask permission or give credit.

If you need 32×32 sized tiles, or larger, just scale the image up to whatever you need. Then import the image into the GMS2 Sprite Editor, set the grid to the size you need, and draw over the template in a new layer until you’ve built up your tiles!

I will point out here, that this sheet that we’ve created above just gives us a starting point to create a single auto-tile set. Most games will likely need several tilesets, for different areas of the game. Auto-tiling is best for your basic terrain, such as walls, floors, and platforms.

We could also choose to include numerous additional tiles in one sprite image if we desire, for decorative things that do not make sense to do auto-tiling with, or create additional tiles to represent terrain features in the game such tables and chairs, or other furniture, or trees, bushes, you name it. Or we could store each type of terrain, decorative elements, etc. in its own tileset resource.

We could also duplicate this 16-tile layout multiple times, and include in a variety of different terrain types, or different colors, all in a single large tilesheet. Or we could have multiple tile sheets. But be cautious about making the sheet too large. You’ll want to read the Texture Groups section of the manual to understand the limits of how large your sheets can be.

One last thing: If you wanted to create an animated auto-tiling tileset, you would need to create additional copies of our 16-tile auto tile layout, and draw each one as a different frame of animation. We’ll explain how to do this in the section on creating tile animations.

Create a tileset asset

Now that we have a sprite holding the image for our tile set, it’s time to create the tile set asset. To do this, right-click on the Tile Sets section of the resource tree, and select Create. You can name the new Tileset something meaningful, such as grassland, or ocean, or city, or indoors, or whatever suits your game.

Define the tileset

The Tileset editor looks like this:

GMS2 Tileset editorThe first thing to do is to add the sprite from Step 1 to the tileset. Click on Select Sprite, and select the sprite. Next, set tile size to split up the image, by entering the information in the Tile Properties fields at the right, as appropriate. The sprite image will appear sliced up by a grid as you change these values. At this point, we could use our newly created Tileset right away, by going to the Room editor, adding a Tile Layer, and drawing in some Tiles from our newly created Tileset.

(Optional): Create any brushes, animations, and auto tile sets that are needed

Once the grid looks how you want it, we’re ready to create any Brushes, Animations, and/or Auto Tiling sets that are needed. These are very useful, and powerful, new features that have been added to GMS2’s tiles. Not every Tileset needs Brushes, Animations, or Auto Tiling to be defined for it, but when you do use these, especially Auto Tiling, it will make creating your rooms much easier and faster.

This is where it really starts to get good.

Brushes

A brush is a selection of tiles, grouped together and added to your tile layer as one. Let’s say you have something in your tile that takes up more than one tile. This could be a large terrain feature, such as a building, or a mountain, or a tree. Without using brushes, every time you wanted to plant one of these multi-tile features in your room, you’d need to select each tile one at a time, place it in your Tile Layer, in the correct arrangement… this is tedious work and easy to screw up. So Tile Brushes make this easier by collecting the related tiles together, so that they can be added to the Tile Layer with just a single click to place the entire Brush.

You can use Brushes not just to place multi-tile graphics, but to place arrangements of platforms. Say you have a particular jumping puzzle that you want to repeat several times in a level; you can create a Brush with the tiles spaced out in just the way you want them, then place them quickly and easily into your Tile Layer.

Animation

Setting up Animation Tiles is pretty easy. Simply add a new Animation, specify the number of frames (which must be a power of 2), and then add the tiles that make up the animation one at a time until you’ve filled out the animation.

It’s worth noting that you don’t have to use Tilesets to do animation. You can place any sprite resource into a room directly, without the need to place an instance of some object to draw the sprite for you. These can be added to asset layers or background layers. Background layers can tile or stretch or both, and can move. So consider whether you need to do your animations in tiles or if you can do them more easily another way.

Auto Tile

Setting up an auto tile set is pretty easy too, although at first it seems complicated. Taking the sprite that we created, above, we have all the tiles we need to create a 16-tile auto tile set. GMS2 also supports a 47-tile system, but it is much the same to set up.

Create a new Auto Tile set. The auto tile set will present a template which you have to fill in with tiles from your tileset sprite. Simply go through the template by clicking on each tile in the template, then click on a tile from your tileset sprite to connect it to the template. The currently selected tile in the template is red, and as you go through your tileset adding tiles to the auto tile template, it will fill in the tile you selected, then advance to the next tile in the template automatically.

GMS2 auto tile editorThe key to understanding the auto tile template is that the light grey parts of the template are meant to represent the solid parts of your tile, and the dark grey parts are meant to represent the empty space. If you didn’t know this up front, it’s very difficult to read the template correctly, and this was one of the most confusing parts of figuring out the auto tile editor.

Each of auto tiles (remember, there can be more than one in a tileset resource) is called an auto tile library. The image above shows two auto tile libraries about to be created; a 16-tile library, and a 47-tile library, just to show what they both look like.

It’s also important to understand the buttons to the right of the auto tile templates, which look a bit like a yinyang. These control how the tileset treats the borders of the room. Outside the edges of the room, the tileset must make an assumption: either the tiles outside the room count as empty, or as filled. This influences the auto tile system to select the appropriate tile at the room edge, and will result in an edge border around the room if the outside is treated as empty.

Once you’re done setting up the Tile Set resource, when you go to the Room Editor, in the Tile Layer editor, you’ll see a section in your tile palette called Libraries. Here, you can select Brushes, Animations, and Auto Tile sets to draw, rather than selecting individual Tiles from your Tile Set.

Pro Tip: An auto tile library will not work until and unless every tile in the template has been assigned. If you try laying out auto tiles in a tile layer and they just won’t draw, no matter what you do, go back and look at the template. Somewhere in there, some part of the template has not been assigned to a valid tile in your tileset.

The auto-tiling section in the manual illustrates this pretty well, with some nice animations showing how it works.

Animated Auto Tile sets

To create an animated Auto Tile set, simply make sure that each tile in your Auto Tile set is the first tile in an Animation set. In the room editor, the tiles will not animate, but as long as you place animated tiles in the editor using the first image in the animation, they will animate at runtime.

Re-Auto Tiling (Auto Tiling at runtime)

What if your room changes once the game starts? For example, if you have destructible terrain, and a piece of a platform gets destroyed, will the tiles automatically adjust accordingly? Unfortunately, no. Not yet; Dynamically re-auto-tiling at runtime is not supported by GMS2 at present, but it is a planned feature according to YYG lead programmer Mike Dailly, albeit with no release date announced yet.

This means that, at least for now, your auto-tiled setup will not automatically update the tiles if something changes during the game, for example if a new platform is created, or an existing one is destroyed, the tiles in the adjacent region will not update. This can cause things to look weird.

Presently the only way to handle this would be through a custom coded solution to evaluate the neighbors and determine an updated arrangement of tiles. This is pretty much the old system from GMS1, when auto-tiling was done at runtime.

There are scripts published on the GMC Forums and available for purchase in the Marketplace that will do auto-tiling for you, and YouTube videos describing how they work. These will need to be updated in order to be compatible with GMS2. At this time I haven’t evaluated these solutions, so I won’t be making a recommendation for any here. Hopefully YYG will provide a built-in solution in the form of GML functions, and there won’t be a need to invest time into developing custom solutions.

Create additional tilesets, as needed.

Your project can have as many tilesets as needed. Create as many as you like, to allow you to create as many different environments as you need for your game. It’s probably best to start simple and just create one at first, and then once you’re happy with it and satisfied that you know how to use the tile system, create additional Tilesets.

You can use multiple Tilesets in the same room, and in different layers, overlapping them. This is how you can develop very nice looking rooms.

Can a tile layer move/scroll?

Short answer: Yes. The functions tilemap_x() and tilemap_y() allow you to move a tile layer around the room. For complete details of all the things you can do with tilemaps, consult the manual.

The individual tiles in the tile layer have to align to their grid. So you can’t offset individual tiles, and make them move. But you can move the entire tilemap. If need be, you could put a few tiles in a layer that moves, and use this to create moving terrain features. For things like crumbling tiles, or tiles that break loose and drop one at a time when the player stands on them, it’s better to handle these with objects rather than tiles; of course, you can just use a sprite that looks the same as the tileset that you’re using, so everything blends together.

Tile Collisions

GMS2 can handle collisions between instances and tiles directly, without the need to use instances of hidden collision object behind the tiles. This is very handy, since you no longer need to lay out a bunch of instances in a room, then tile over them, and as well it offers greater performance, because there’s much less overhead involved with tiles than there is with instances.

Tile Collisions are meant for solid, stationary objects, such as platforms in a side-scrolling game, or walls in a top-down game, not for handling all possible collisions in your game. You will still want to use normal collision events for handling collisions between different objects in the game.

I mention them here so you’re aware of it, but rather than make this article even longer, I recommend you watch the tutorial video by GMWolf, which explains one approach for how to make a tilemap collision system in GMS2. His approach is to create a separate, invisible tile layer for the collision tilemap, which separates collisions from the decorative tile layer, which allows you to have decorative tiles which have rough edge texture, for surfaces like tall grass or uneven rock. The collision checking is performed by the objects in your game, which check to see if their sprite’s collision mask overlaps the tiles in the collision map.

It’s a very good approach, but it is just one way to do it. In GMWolf’s demo, a player object is prevented from entering into the region covered by the collision map. But there may be other types of collision checking, for example to determine if the player has entered a region that does damage, or is overlapping a ladder tile. Each of these situations can be handled by some variation of this basic approach, using additional collision tilemaps for different types of collisions. For example, you could have a collision tilemap for solid platforms, another collision tilemap for ladders (which triggers your character’s climbing behavior), one for water (which triggers water physics), one for slippery platforms, one for danger zones, etc., as many as needed. You can even use a collision tilemap to trigger events, such as to spawn or activate enemies when the player reaches a certain region of the game. There are many possibilities, so use your imagination.

Isometric and Hexagon tiling?

Because of GMS2’s requirement that tiles align to grid, you can’t lay out isometric or hexagonal tiles in a single tile layer. You’ll need to use a two layer approach, with the second layer offset horizontally and vertically, so that the two layers blend together.

This approach has its downsides. Having to switch back and forth between the two layers when laying them out in the room editor is a pain. And checking both layers for collisions doubles the amount of work the game needs to do at runtime for handling tile-based collisions.

I hope that something is done about these problems, I would like to see an “isometric grid” checkbox in the layer editor that allows aligning to a half-sized grid, or perhaps a new tile layer type for isometric tiles. But for now a two layer solution seems to be the best approach.

Update: YYG lead developer Mike Dailly recommends that we refer to the Isometric demo in GMS1.x for their recommended approach to do isometric games, and adapt that for GMS2 as necessary. (Hopefully a GMS2 Isometric demo will be happening eventually).

GML move functions and Tiles

If you use the GML functions

move_bounce_all() move_bounce_solid()

move_contact_all() move_contact_solid()

move_outside_all() move_outside_solid()

these work with the collision mask of objects, not tiles. So they will not be helpful to you if you’re implementing a tile-based collision system.

However, you can write your own version of these functions to work with tiles; to do so you just need to understand how the built-in functions work, and how to detect collisions with tiles.

The function move_bounce simply reverses the hspeed and vspeed of the bouncing object:

So, first determine whether the tile collision is horizontal or vertical, then use:

hspeed *= -1;
vspeed *= -1;

to reverse the appropriate speed variable.

If the bbox_left or bbox_right is in collision, set hspeed *= -1. If the bbox_top or bbox_bottom is in collision, set vspeed *= -1.

The move_bounce functions also take a boolean argument to turn on “advanced” collisions, which use the collision mask to do precise checking. These are slower to calculate, and the manual recommends not to use advanced unless it’s necessary, but they otherwise work the same. If you wanted to, you could come up with a tile collision check that uses the sprite’s collision mask to check for collisions with tiles, and use that.

The move_contact and move_outside functions work by using a while loop to check for collisions with the calling object, moving it one pixel at a time until the while condition is satisfied. This is easy enough to implement in a tile-based system as well.

Further Reading/Videos

Fun enum ideas for game development

Most video games have a counting, ranking, or level system of some sort. It’s often good to have a thematic flavor to your counting systems. This way, rather than calling your level progression by boring old regular numbers, you can give each level number a meaningful, or flavorful, name. This can add character or meaning to your game world, or it can be used to help disguise the underlying math, resulting in a game where the underlying mechanics are masked away from the player, leading to a more mysterious experience where they need to experiment and discover. What’s cooler: a “level 3 sword?” Or “the sword of autumn?” What’s more powerful: the knight sword or the rook sword?

To that end, I thought I’d demonstrate a few example enums that you can use to spice up your game design.

ENUMerate all the things!

Alphabet {A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z}

Greek Alphabet {Alpha, Beta, Gamma, Delta, Epsilon, Zeta, Eta, Theta, Iota, Kappa, Iota, Kappa, Lambda, Mu, Nu, Xi, Omicron, Pi, Rho, Sigma, Tau, Upsilon, Phi, Chi, Psi, Omega}

Military Phonetic Alphabet {Alpha, Beta, Charlie, Delta, Echo, Foxtrot, Golf, Hotel, India, Juliett, Kilo, Lima, Mike, November, Oscar, Papa, Quebec, Romeo, Sierra, Tango, Uniform, Victor, Whiskey, Xray, Yankee, Zulu}

Army (simplified) {Private, Specialist, Corporal, Sergeant, Officer, Lieutenant, Captain, Major, Colonel, General}

Navy (simplified) {Seaman, Petty Officer, Ensign, Lieutenant, Commander, Captain, Admiral}

Chess {Pawn, Knight, Bishop, Rook, Queen, King}

Rainbow {Red, Orange, Yellow, Green, Blue, Indigo, Violet}

Elements {Earth, Air, Fire, Water}

CardRank {Two, Three, Four, Five, Six, Seven, Eight, Nine, Ten, Jack, Queen, King, Ace, Joker}

CardSuit {Clubs, Diamonds, Hearts, Spades}

Zodiac {Aquarius, Pisces, Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn}

Seasons {Spring, Summer, Autumn, Winter}

Months {January, February, March, April, May, June, July, August, September, October, November, December}

Weekdays {Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday}

Lunar Cycle {New, WaxingCrescent, FirstQuarter, WaxingGibbous, Full, WaningGibbous, ThirdQuarter, WaningCresent}

Some of these may not necessarily have a natural order to them, but might just be a set of categories which you could use to organize something in your game. That something could be worlds, or items, or creature types, or powers, or anything else you can think of.

What else?

What else is there? Probably a whole lot! You could probably make a good basis for a game system out of gemstones, or metals, or barnyard animals, or anything, really!

If you know of a set of things that would make a good enum that I’ve left out, leave a comment below.

Using enums in GameMaker Studio

Enums are covered in the manual in the article on Data Types.

The basic syntax is as follows:

First, you have to declare the enum.

enum <variable>{<constant> [= <value>]}

You create the enum using the enum keyword, naming the enum <variable>. Then, in brackets, you list all the constants that make up the values in the enum. You can explicitly declare values for the enum constants, or you can leave them implied, in which case GameMaker will assign them integer values starting at 0, and increasing in order through the collection. You can even use expressions rather than a static value.

To access the enum constants, you use the syntax enum_variable.constant.

In your code, there are all kinds of situations where using an enum is potentially useful. Here’s a few things to look for in your code that might signal a good opportunity to use an enum:

Conditionals for checking state

Consider the following ways of checking the state of some object:

//check state using string matching
if state == "state_idle" {//do state actions}
//check state using literal numbers
if state == 0 {//do idle actions}
//check state using variable
state_idle = 0;
[...]
if state == state_idle {//do state0 actions}
//check state using enums
if state == enum.value {//do state actions}

Out of these, using enums is the best approach. Why are enums better?

Conditional checking by string matching is much slower than number matching. Your string value provides semantic meaning to the reader, making the code easier to understand when a human reads it. But when the program goes to check the conditional, it has to check every letter in both strings to see if they match.

As well, this approach is fairly error prone. It’s very easy to type the strings in slightly wrong. If you’re not careful, it’s easy to type one string where the state is assigned, and another string value where you’re checking state in order to do something state-specific. If you don’t catch the error, you’ll have a hard to diagnose bug because the conditional check won’t match what you’ve set the state variable to. One extra space, or misspelled word, or inconsistent use of capital letters, and the string match check will fail. The compiler won’t help you catch this sort of bug.

It’s a lot faster to do conditional checking via numbers. But naming your states with literal numbers: 0, 1, 2, etc. provides no meaning. Is 0 the idle state? is 1 running? is 2 jumping? Keeping track of this stuff in your head makes your work as a programmer harder, and makes the code hard to read, and brittle. You can do slightly better by creating a named variable and assigning the number value to it. The named variable can be expressive, e.g. state_idle = 0, state_running = 1, etc. But variables values can change, and storing each value takes a little bit of memory. By contrast, an enum value is constant — it cannot be changed once it is declared. And enums are global, so they are only declared and set in memory once, and thus require fewer resources. Even if you have ten thousand instances that use your enum, the memory used by them is the same as if there is only once instance.

Create an enum that provides expressive labels on these values, and you have the best of both worlds: expressive code that checks conditions fast, and uses computer resources efficiently.

Iteration over a set

Conventionally, programmers often rely on conventional looping variable names such as i or j to iterate over a collection of things, such as the members of an array, or other data structure. While this is OK, you can make your code more expressive by using enums to denote important numbers.

For example, it’s common for programmers to use a nested for loop iterating over the variables i and j to create a grid structure. Instead of using i and j, we can use variables named row and column instead. As we iterate over the range of rows and columns, we can use enums as flags to do something special at row (or column) == enum.constant.

Another example:

Say we want to implement an inventory equipping system for the player. The character has inventory slots for head, body, gloves, right hand, left hand, shoes. We decide to create an array, called inventory[], and assign the equipped item in each slot.

We could simply index the array with numbers:

inventory[0] = hat;
inventory[1] = armored_breastplate;
inventory[2] = iron_gauntlets;
inventory[3] = sword;
inventory[4] = empty;
inventory[5] = double_jump_boots;

Now, it’s not too hard to tell what each inventory slot is for. But it’s not as easy as it could be, either. Is the sword in the left hand or the right hand?

Let’s use an enum, and make the code easier understand.

enum inv_slots{head, body, gloves, right_hand, left_hand, shoes};
 
inventory[inv_slots.head] = hat;
inventory[inv_slots.body] = armored_breastplate;
inventory[inv_slots.gloves] = iron_gauntlets;
inventory[inv_slots.right_hand] = sword;
inventory[inv_slots.left_hand] = empty;
inventory[inv_slots.shoes] = double_jump_boots;

Now, it’s quite easy to see that the double_jump_boots are being worn on the player’s feet, rather than being carried in the player’s hands. It’s simple to keep track of which slot is which.

Creating a set of related, named values

Here’s a useful enum for direction angles for a top-down game:

enum compass {e = 0, ne = 45, n = 90, nw = 135, w = 180, sw = 225, s = 270, se = 315};

It’s much easier to remember and understand direction = compass.sw instead of direction = 225. You can use this enum for 4-direction and 8-direction movement or aiming, and you could even expand upon it if you wanted by adding constants for ene, nne, nnw, wnw, wsw, ssw, sse, and ese, like so:

enum compass {
 e = 0, 
 ene = 22.5, 
 ne = 45, 
 nne = 67.5, 
 n = 90, 
 nnw = 112.5
 nw = 135, 
 wnw = 157.5
 w = 180, 
 wsw = 202.5
 sw = 225, 
 ssw = 252.5
 s = 270, 
 sse = 292.5
 se = 315,
 ese = 337.5
 };

(I like to format my code like this; lining up the variable names, equals signs, and values makes it easy to scan down the file, and makes it clear that these values are all related.)

If I wanted, I could go a step further and use radians to make it clearer that these values are fractions of a circle:

enum compass {
 e = 0, 
 ene = radtodeg(pi * 0.125), 
 ne = radtodeg(pi * 0.25),
 nne = radtodeg(pi * 0.375), 
 n = radtodeg(pi * 0.5), 
 nnw = radtodeg(pi * 0.625),
 nw = radtodeg(pi * 0.75),
 wnw = radtodeg(pi * 0.875),
 w = radtodeg(pi), 
 wsw = radtodeg(pi * 1.125),
 sw = radtodeg(pi * 1.25),
 ssw = radtodeg(pi * 1.375),
 s = radtodeg(pi * 1.5),
 sse = radtodeg(pi * 1.625,
 se = radtodeg(pi * 1.75),
 ese = radtodeg(pi * 1.875)
 };

You can group together, and name other values that go together in a system using enums in this way, too.

Parting thoughts

Hopefully, these examples will help you see how enums can be useful to make your code more expressive, easier to read, and easier to maintain. Look for opportunities to use them in your code. They can really help!

Tutorial: GameMaker Object with multiple collision zones

GM Version: GameMaker:Studio 1.4 (concept should work in earlier versions)
Target Platform: ALL
Example Download: https://csanyk.com/cs/releases/games/LD48-36_AncientTechnologies/LD48_36_Ancient_Technologies_csanyk.gmz
Links: http://ludumdare.com/compo/ludum-dare-36/?action=preview&uid=10473

Summary:

How to make an object that handles multiple collision zones by using multiple sub-objects

Tutorial:

I used this technique in my recent Ludum Dare game, Ancient Technologies. The project has a TON of extraneous code in it, some of which is pretty messy, so I’ll replace the download link with a cleaner example project of just this technique in coming days.

If you look at the Atari 2600 console in this game, it is actually multiple objects, made to look like a single object. This enables each switch to have its own collision detection and mouse events.

I accomplished this with a few simple techniques that work really well:

The console itself is the main object. Then there are 6 objects for the 6 switches on the console.

I then took the image I wanted to use for the sprite, and cut out all the different clickable regions, putting each into its own subimage by itself. Then once all the subimages were created, I removed each subimage into its own sprite, and set the collision mask to cover just the pixels in the image

Atari 2600 clickmap sheet

As you can see, this approach results in a lot of “wasted” space in the sprite sheet in the form of transparent pixels, but if you’re concerned about this, you could always achieve the same effect by using sprite origin and sprite offset to position the images without all the whitespace in the sprite sheet. I skipped using sprite origin because I didn’t feel like bothering with counting pixels and setting each sprite origin differently. That would have been tedious, and if I had ever needed to change the sprites, could have thrown everything off and required extensive rework to recalculate again. If your sprites are tiny, it probably doesn’t matter too much, but if they’re quite large, then you should probably use sprite origin/offset.

(Note: With the small pieces, you’d need to use origin numbers that are larger than the dimensions of the sprite itself, or possibly negative values for the origin. You’d also need to carefully calculate the distance to set the origin so that the images all line up precisely. The goal is to make all the images align when each instance’s x and y are identical. This makes them easy to move around together as a group, without having to deal with offsets and so on. To make everything align easy, I created sprites that have the same height and width, so that getting them to align takes no extra effort or calculation at all.)

Next, use the “main” object to generate the collision zone objects, in the create event:

Note the example code below isn’t exactly the code in my project, but is cleaned up a bit for easier comprehension.

///oConsole Create Event:
power_switch = instance_create(x, y, oPowerSwitch);
tv_type_switch = instance_create(x, y, oTVTypeSwitch);
left_difficulty_switch = instance_create(x, y, oLeftDifficultySwitch);
right_difficulty_switch = instance_create(x, y, oRightDifficultySwitch);
select_switch = instance_create(x, y, oSelectSwitch);
reset_switch = instance_create(x, y, oResetSwitch);

Since these objects all use sprites that are the same size, they all line up together when their x,y position is the same. Now you have an easy way to place just the main object and have it create all of its collision zone objects, perfectly aligned.

If the main object needs to be able to move, you just need to update the x,y of all the objects whenever you need to.

Another great thing is that each of these instances can have its own animation which is completely separate from the rest of the collection of objects. This means you can do really sophisticated animation rigging.

Also, you can access the instance variables of the collision instances by using the main instance, like so:

oConsole.power_switch.position = UP;

is (essentially) equivalent to:

oPowerSwitch.position = UP;

This allows you to use the collision zone instances’ instance variables like you would use properties of a helper class in another language, which may make accessing these variables easier if you’re used to other programming languages.

As well, if each of these switch instances were of the same object, using the id returned by instance_create() would allow you to differentiate between them. This could be useful for, say, a battleship with multiple turrets that are all of the same object type.

Finally, you’ll want to be mindful that if you destroy the main object, you’ll likely want to destroy all the sub-objects. Perhaps not — maybe you’re doing a spaceship with an escape pod or a rocket with multiple stages that break away. But in that case you’ll wan to be sure that once the main object is gone, you are handling whatever remains somehow.

Getting into version control with GameMaker Studio

Version control makes sense whether you are working alone or with a team. It should be a mandatory practice. But you won’t be able to enjoy the benefits of version control unless you know how to do it right. If you’re working with a team, it’s essential that you all know how to do it right. This article will help you get started.

(more…)

csanyk.com © 2016
%d bloggers like this: