Skip to main content

Built-in Variables & Constants

GML+ includes a number of built-in variables and constants which can be accessed in your own code. These can provide useful information or behaviors that are commonly needed, but have no implementation in vanilla GML.

All built-in variables are provided by the obj_server_gmlp object. This object must be present in the current project, but does not need to be added to any rooms to function.

Mouse Variables#

VariableTypeDescription
mouse_hspeedrealStores the current horizontal mouse speed, as a value of pixels.
mouse_vspeedrealStores the current vertical mouse speed, as a value of pixels.
mouse_speedrealStores the current directional mouse speed, as a value of pixels.
mouse_directionrealStores the current mouse direction of travel, as a value of degrees.
mouse_xstartrealStores the mouse X coordinate upon starting the game. If no mouse is used, -1 will be returned. Like the instance xstart variable, this variable is not read-only and can be redefined if needed.
mouse_ystartrealStores the mouse Y coordinate upon starting the game. If no mouse is used, -1 will be returned. Like the instance ystart variable, this variable is not read-only and can be redefined if needed.
mouse_xpreviousrealStores the mouse X coordinate from the previous Step. Like the instance xprevious variable, this variable is not read-only and can be redefined if needed.
mouse_ypreviousrealStores the mouse Y coordinate from the previous Step. Like the instance yprevious variable, this variable is not read-only and can be redefined if needed.
mouse_visiblebooleanShows or hides the mouse, while preserving cursor state and/or sprite. Set to true by default. Replaces cr_none, which can no longer be used while obj_server_gmlp is present.
note

GameMaker Studio 2 uses two separate functions for setting different types of cursors. For system cursors, use window_set_cursor([cursor]). For sprite cursors, use GML+'s window_set_cursor_sprite([sprite]). Unlike vanilla GML, GML+ will automatically switch the cursor type when either command is used.

Time Constants & Variables#

ConstantTypeDescription
frame_targetrealStores the amount of time a single frame should take to render at the current game speed (FPS), as a value of milliseconds.
frame_timerealStores the actual time the previous frame took to render, as a value of milliseconds.
frame_deltarealStores the difference (or delta) between the target and actual frame time, as a multiplier.

While the use-case for these constants and variables may not be immediately obvious, in reality they're some of the most important properties in your entire project. Much game logic occurs over time, and while it may be tempting to rely on FPS as a unit of time, this will cause a host of problems down the road. FPS-based logic can never run at another framerate without altering its real-world speed--frustrating for users on high-end systems that could run the game faster, and frustrating for low-end users that can't hit the target framerate to begin with.

A better unit of time is the time it took to render the previous frame, or simply frame_time. Frame time-based logic will always run at the same real-world speed regardless of framerate. This both compensates for lag on low-end systems and allows high-end systems to run to their full potential.

You may have previously heard of this concept referred to as delta time. However, this is a bit of a misnomer. Strictly speaking, delta time is not the previous frame time, but rather the difference between the current frame time and the previous frame time. Though the term is often misused, frame_delta is nonetheless a very useful property to be aware of. In fact, frame_time and frame_delta are like two sides of the same coin, only forming a whole when used together.

Which available time constant or variable you should use in your logic depends on the kind of logic itself. For time-based logic (e.g. clocks, timers, etc.), use frame_time as a unit of milliseconds. For distance-based logic (e.g. movement, rotation, etc.), use frame_delta as a multiplier of pixels, degrees, and so forth.

Example#

For further explanation of how to implement frame time and delta time in your projects, see the video tutorial below:

Deprecated Variables#

The following variables were previously included for full functionality of instance_link, which no longer requires them. Universally updating these variables has a measurable performance cost whether or not they are used. This feature is now disabled by default, but can be re-enabled by modifying obj_server_gmlp:

  • In the object Create Event, under "Configure GML+", change expanded_image_previous to true.
  • No other modifications to obj_server_gmlp should be made.
VariableTypeDescription
image_angle_previousrealStores the instance sprite rotation from the previous step, as a value of degrees.
image_xscale_previousrealStores the instance sprite X scale from the previous step, as a value of degrees.
image_yscale_previousrealStores the instance sprite Y scale from the previous step, as a value of degrees.
note

image_angle should not be confused with direction. While both are built-in to each instance, image_angle modifies the sprite while direction modifies movement.