GML Functions: Moving Around

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

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

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

To be complete, each instance has the following variables and functions dealing with its position and motion:


 * x Its x-position.
 * y Its y-position.
 * xprevious Its previous x-position.
 * yprevious Its previous y-position.
 * xstart Its starting x-position in the room.
 * ystart Its starting y-position in the room.
 * hspeed Horizontal component of the speed.
 * vspeed Vertical component of the speed.
 * direction Its current direction (0-360, counter-clockwise, 0 = to the right).
 * speed Its current speed (pixels per step).
 * friction Current friction (pixels per step).
 * gravity Current amount of gravity (pixels per step).
 * gravity_direction Direction of gravity (270 is downwards).
 * motion_set(dir,speed) Sets the motion with the given speed in direction dir.
 * motion_add(dir,speed) Adds the motion to the current motion (as a vector addition).

There are a large number of functions available that help you in defining your motions:


 * place_free(x,y) Returns whether the instance placed at position(x,y) is collision-free. This is typically used as a check before actually moving to the new position.
 * place_empty(x,y) Returns whether the instance placed at position (x,y) meets nobody. So this function takes also non-solid instances into account.
 * place_meeting(x,y,obj) Returns whether the instance placed at position (x,y) meets obj. obj can be an object in which case the function returns true if some instance of that object is met. It can also be an instance id, the special word all meaning an instance of any object, or the special word other.
 * place_snapped(hsnap,vsnap) Returns whether the instance is aligned with the snapping values.
 * move_random(hsnap,vsnap) Moves the instance to a free random, snapped position, like the corresponding action.
 * move_snap(hsnap,vsnap) Snaps the instance, like the corresponding action.
 * move_wrap(hor,vert,margin) Wraps the instance when it has left the room to the other side. hor indicates whether to wrap horizontaly and vert indicates whether to wrap vertically. margin indicates how far the origin of the instance must be outside the room before the wrap happens. So it is a margin around the room. You typically use this function in the Outside event.
 * move_towards_point(x,y,sp) Moves the instances with speed sp toward position (x,y).
 * move_bounce_solid(adv) Bounces against solid instances, like the corresponding action. adv indicates whether to use advance bounce, that also takes slanted walls into account.
 * move_bounce_all(adv) Bounces against all instances, instead of just the solid ones.
 * move_contact_solid(dir,maxdist) Moves the instance in the direction until a contact position with a solid object is reached. If there is no collision at the current position, the instance is placed just before a collision occurs. If there already is a collision the instance is not moved. You can specify the maximal distance to move (use a negative number for an arbitrary distance).
 * move_contact_all(dir,maxdist) Same as the previous function but this time you stop at a contact with any object, not just solid objects.
 * move_outside_solid(dir,maxdist) Moves the instance in the direction until it no longer lies within a solid object. If there is no collision at the current position the instance is not moved. You can specify the maximal distance to move (use a negative number for an arbitrary distance).
 * move_outside_all(dir,maxdist) Same as the previous function but this time you move until outside any object, not just solid objects.
 * distance_to_point(x,y) Returns the distance of the bounding box of the current instance to (x,y).
 * distance_to_object(obj) Returns the distance of the instance to the nearest instance of object obj.
 * position_empty(x,y) Returns whether there is nothing at position (x,y).
 * position_meeting(x,y,obj) Returns whether at position (x,y) there is an instance obj. obj can be an object, an instance id, or the keywords self, other, or all.