Tag: improve_wrap

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.

///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:

///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]);
 //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 
 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


iMprOVE_WRAP 2.2 released

iMprOVE_WRAP 2.2 has been released.

I’ve added two new GML functions to the asset: iw_point_distance() and iw_point_direction(). These functions work much like the built-in GML functions point_distance() and point_direction(), except they take into account the iMprOVE_WRAP wrap region.

Release Notes

Version Notes
2.2 New functions:

  • iw_point_distance(): returns the shortest distance between two points, taking into account the wrap zone.
  • iw_point_direction(): returns the direction of the shortest distance between two points, taking into account the wrap zone.


GameMaker Marketplace


Full Documentation

iMprOVE_WRAP 2.1 released

iMprOVE_WRAP 2.1 has been released. Get it at GameMaker Marketplace or itch.io.

Full Documentation.

Release Notes:

1.0 Initial release
1.0.1 Updated iw_draw_self_wrap() to use image_blend rather than c_white for the color argument.
2.0.0 Added new functions:

  • iw_draw_sprite_wrap(): an iMprOVE_WRAP version of draw_sprite()
  • iw_draw_sprite_ext_wrap(): an iMprOVE_WRAP version of draw_sprite_ext()


  • Boundary drawing now occurs at wrap corners as well.
  • Phantom collison checking also occurs at wrap corners.
  • iw_collision_wrap() and iw_collision_wrap_map() functions now incorporate do_wrap_h and do_wrap_v arguments, and only perform collision checks where they are needed. They still return a value for all locations, but where no check is needed, they return noone.
2.0.1 Improvements:

  • iMprOVE_WRAP demo resources have been placed in folders to keep them tidy when importing the asset into a project.
  • oIMprOVE_WRAP_demo sprite has been updated to allow for more precise positioning. Sprite is semi-transparent, with a yellow pixel at the origin
  • oIMprOVE_WRAP_demo object now draws guide lines indicating the height and width of the wrap range. This is useful in confirming that clone drawings and wrapping is occuring where it should.
  • iMprOVE_WRAP demo dashboard text has been updated to be a bit more clear
2.1 New functions:

  • iw_distance_to_object(): returns the shortest distance to the target object from the wrapping object, taking into account all directions available.
  • iw_distance_to_point(): returns the shortest distance to the target point from the wrapping object, taking into account all directions available.

New demo room for the iw_distance_to_object() and iw_distance_to_point() functions


iMprOVE_WRAP 2.0 released

My GameMaker extension iMprOVE_WRAP has been updated with a new release to 2.0.0.

iMproVE_WRAP is an extension for GameMaker: Studio that provides a number of new functions that improve upon the built-in GML function move_wrap().

iMproVE_WRAP is an extension for GameMaker: Studio that provides a number of new functions that improve upon the built-in GML function move_wrap(). It allows you to define the range in the room where the wrap takes place, and draw the instance on both edges of the wrap, as well as detect collisions on both edges of the wrap.

Version 2.0.0 adds two new functions:

  • draw_sprite_wrap()
  • draw_sprite_ext_wrap()

And makes improvements to the existing functions as follows:

  • boundary wrap drawing occurs at the corners of the wrap range (8 phantom drawings rather than 4) when do_wrap_h and do_wrap_v are both true.
  • the collision functions iw_collision_wrap() and iw_collision_wrap_map() incorporate do_wrap_h and do_wrap_v parameters, and only perform collision checks where they are needed. The functions still return all potential collision variables so that there is never an undefined value, even where collisions are not checked. (Unchecked collision locations return noone.)

You can get it at the YoYoGames Marketplace or Itch.io.

Full documentation.

iMprOVE_WRAP extension for GameMaker Studio

Today I’ve released a new asset on the YoYoGames Marketplace, called iMprOVE_WRAP.

Many video games have the feature that exiting one side of the screen will “wrap” you around to the opposite side — notable examples of this include the smash hit classics Asteroids and Pac Man. GameMaker: Studio has a GML function, move_wrap(), which is intended to provide this feature easily, but it has a few limitations. iMprOVE_WRAP addresses these limitations, resulting in a more powerful, flexible implementation.

iMprOVE_WRAP improvements over move_wrap()

Wrap behavior is no longer based on the built-in GML speed variables.

One of the most troublesome limitations of move_wrap() is that it only works for instances that have a speed. In standard GML, the variables speed, hspeed, and vspeed are used to move instances. But you can also “move” an instance by changing it’s x and y position in the room, without setting a speed. Many GM:S users will implement their own movement systems that eschew these variables, in order to give themselves complete control over the movement engine. When they do so, they are often confused when they discover that move_wrap() doesn’t do what they expect.

iMprOVE_WRAP eliminates this dependency, so that an instance no longer need to use the GML speed variables in order to wrap; wrap behavior in iMprOVE_WRAP is based entirely on an instance’s x,y position.


Wrap region no longer limited to room borders

Another problem with move_wrap() is that it is intended to work with the Outside Room or Intersect Boundary GML Events. This means that move_wrap() is only useful when an instance moves outside the room, or encounters the edge of a room. But in many games, the “play field” may not be synonymous with the entire room — the room might have a border, or “dashboard” or “heads up display” which ideally should be considered “out of bounds” with regard to the play field.

iMprOVE_WRAP allows you to define a “wrap region” — a rectangular area inside the room, which instances wrap around the borders of, rather than the borders of the room.

Independent horizontal, vertical margins

With move_wrap() the margin argument which determines the margin by which the instance must be outside of the room is the same for both horizontal and vertical travel; with iMprOVE_WRAP the horizontal and vertical margins may be set independently of each other.

Wrapping instances can (optionally) draw themselves on both sides of the border

With move_wrap(), an instance still draws its sprite in the default draw in only one location: at (x,y). If the instance is off the edge of the wrap boundary, but hasn’t yet crossed over, the instance draws on the “pre-wrap” side of the room; after the instance progresses by margin pixels over the border, then the instance’s position is moved over to the “post-wrap” side of the room, and the instance is drawn there. This is not a big deal if the instance crosses the wrap boundary quickly, and has a relatively small sprite; but for slower-moving instances, or instances with larger sprites, it creates a jarring “jump” effect, where suddenly the instance appears on the “post-wrap” side of the boundary, with no real warning, rather than gradually entering the room.

iMprOVE_WRAP solves this by providing a new function, iw_draw_self_wrap(). This new function augments the default draw by drawing the calling instance four additional times, at positions left, right, up, and down from the actual instance, the width or height of the wrap region away from the actual instance. Thus, when your wrapping instance is moving off the edge of the wrap region, one of these extra drawings is poking out on the opposite side, creating an illusion of continuity as the instance leaves one side and emerges from the other.

For a wrap region that is smaller than the room itself, it’s best to do your drawing on a surface that is sized to the area of the wrap region; otherwise the parts of the drawing that should be outside of the region will be visible outside of the wrap region. Alternately, if drawing to a surface is not something you want to do, you can “mask off” the portions of the room outside of the wrap region by layering objects at a higher depth around the border, like a picture frame or dashboard.

Collision detection on both edges of the border

To compliment the iw_draw_self_wrap() function, I’ve added a new collision function, iw_collision_wrap(). This function checks for collisions at the four places occupied by the four drawings drawn by iw_draw_self_wrap(). There are actually two iw_collision_wrap() functions.

The more basic, iw_collision_wrap() sets five instance variables in the calling instance to store the id of any instance in collision: other_center, other_up, other_down, other_left, and other_right.

The more advanced, iw_collision_wrap_map(), returns the id of a ds_map, which holds those same five instance variables as keys, which you can access using ds_map_find_value().

Which to use is up to you, and the style of programming you prefer. iw_collision_wrap() is easier to use, and if you don’t mind the instance variable names, is probably slightly faster at runtime. iw_collision_wrap_map() is for programmers who get pedantic about “correctness” and want their functions to return something, not cause side effects in the application state. Since it’s not possible in GML to have a function return 5 separate values, we return a data structure that stores the five values. The downside of this is that you have some overhead, namely a need to clean up the ds_map when it is no longer needed. Fortunately, it’s not hard. The example project will demonstrate how to do this properly, so don’t worry.

iMprOVE_WRAP is available at the YoYoGames Marketplace for $2.99; however I am making it free for the first 10 downloads. Please rate it and review it if you give it a try!