Guide: Optimization

The code of GML-OOP is executed during the runtime of an application built with it. Executing any code with that nature will have the processor and then a graphics card of the device take time to finish completing the operation before proceeding with the next. Adding any features to a project, including features of GML-OOP is adding more code to it, and adding code means adding time necessary for execution. That time is usually measured in microseconds.

While the code of GML-OOP has many optimizations applied to it, it is still runtime code in nature. Its primary purpose is to improve the quality and readability of code written with it, turning the attention to solving bigger problems. Good practices, being able to properly understand written code, write it optimally, debug it efficiently and prevent crashes provide benefits which outweigh the cost of added execution time.

GML-OOP constructors contain several features that make creating and understanding efficient code easier. Three primary groups of their methods stand out for that purpose:

• toString(): Every constructor can be stringified to output its properties and calling this method directly allows configuring that output, making it easy to see the data being worked with.
• destroy(): Every constructor that has this method must call it after it is no longer used, unless noted otherwise. This is crucial in avoiding memory leaks, as otherwise internal data will linger in memory for the rest of the runtime. The entirety of constructors without that method is automatically handled by Garbage Collection.
• toVertexBuffer(): Every constructor which renders graphics has this method. It can be used instead of render() to pre-calculate drawn graphics once, as opposed to performing these calculations each of frames in which graphics would be drawn.

Listed below are some of most important guidelines while writing performant code, applicable both for working with GML-OOP code and often in general.

---

Core concepts

As executing code takes time, the goal of optimization is to reduce the amount of steps taken to achieve the same result in shorter time. Each GameMaker application executes its code in a cycle which happens every rendering frame. That cycle consists of executing its Events in a set order, then by default, waiting until it is time to begin the next frame. Their amount to perform in a single second can be set in Project Settings or with the game_set_speed() function. That number can be made unlimited, in which case its only limit is what the components of the device can produce at maximum load. However, the amount of frames that can actually visible is dictated by the screen the application is displayed on and mainly its refresh rate.

Because the minimal refresh rate limit found on concurrent devices is usually 60, the limit of frames produced in a second is also set to 60 for a newly created GameMaker project. With that limit, each frame has a time limit of 1/60 of a second, in which it can execute without delaying the next frame. Not managing to fit in that limit lowers the number of frames operated in that second, resulting in visible delays. All primary components of a device take part in the total execution time of each frame, but most of written code is operated by the processor. If the code relates to graphics, internal GameMaker functions will proceed to operate components relating to the graphics card. The only direct way to affect code executed by the graphics card is through the use of Shaders, written in a shading language.

Changing the frame limit of a GameMaker application will change the speed at which all logic of execution is performed. Supporting values higher than 60, while a portion of devices will not be able to effectively achieve that speed, necessities manual scaling of speed the logic is executed at. A guide for one of many ways, in which this can be achieved can be found here. However, as a starting point, it is recommended proceed with creating the application by picking an accessible, slower device and targeting executing a fixed amount of 60 frames per second on that device. Furthermore, actual execution time on that device should be tested with the YoYo Compiler target. By default, an application will be compiled to the Virtual Machine target, which is faster to compile to and provides more debugging information, but not as performant to execute actual code of the application.

---

Executing code once, instead of every frame

Majority of performance problems stem from code being executed more times than it needs to. Because this is an ubiquitous problem, steps to cover for it must be taken every time any code is written.

Events in GameMaker come in two types:

• Executing once, such as the Create or Clean Up Events.
• Executing every frame, such as the Step, Draw or Draw GUI Events and their variations.

Such separation did not have to exists, as an entire application could be written in just the Draw Event, but a primary reason for it is optimization.

This problem can be exemplified by having GameMaker render a chunk of text in such a way it fits it is line-broken to fit a rectangular box. To achieve this, the following procedure needs to be executed:

• Initial string must be declared.
• Box boundaries must be declared.
• The string must be parsed to separate each word.
• Line breaks must be inserted where the location of boundary was reached.
• Text rendering properties must be set and the string is rendered.

A programmer unaware of this problem would write their code to perform the entirety of this procedure every step. However, the only the final part needs to be executed every frame. Everything prior to it can be executed either only once or when necessary, such as as when the user resizes the application window, affecting the box boundaries. Therefore, this code can be separated into different parts to be executed at different timings, preventing redundancy:

• Properties of the string and box boundaries can be declared once.
• The string can be separated once.
• Line-breaks can be inserted only when above properties change.
• Text has to be rendered every frame.

If the application is set to execute 60 frames in a single second and that part of interface was displayed for 10 minutes, then in case where this code was not optimized, operations like inserting line-breaks would be performed 36000 times. This has at least partial effect on the performance of the rest of the application and the operating system. However, it needed to be performed once in two cases: Initially and whenever the user resized the application window. This means, the most performance impact every frame for the most intensive part of this procedure can be reduced to a single check for whether the rest of it should even execute.

While basing a system on GML-OOP, it should become natural to separate preparatory single-frame data and active every-frame operations. Constructors condense the preparatory data in universal, reusable structures. Properties of two concepts from this example, the drawn text and the rectangular box, become encapsulated into a single variable each. These variables would refer to TextRenderer and Rectangle constructors, respectively. These constructions should happen only once, such as in the Create event, so that they exist in memory until the system stops being needed, rather than being redeclared every frame. Operations happening each frame should be reduced only to calling methods executing that prepared data whenever possible.

Additionally, it should be noted that:

• Setting properties of a GML-OOP constructor should happen by either constructing them or using appropriate methods if a documentation page for a given constructor states the value is not directly modifiable. These properties can be used to read a saved value of that data, without a need to call a getter function or a method.
• Graphical data can also be prepared once ahead of rendering it multiple times through the use of their toVertexBuffer() methods.

---

Optimizing loops

The chunks of code that require most attention when considering performance are ones that execute repeatedly after all other code was separated to run only once. Most of loops in GML-OOP follow this pattern:

var _i = 0;
repeat (/*amount of iterations*/)
{
	// loop content

	++_i;
}

This declaration is the fastest possible general-use loop GameMaker can execute:

• Contrary to its popularity, there is little to no reason to ever use a for loop, as GameMaker Language features the simpler repeat loop. The difference between them is that the for loop always checks for its ending point before every iteration, whereas a repeat loop does that only once. Regardless of the type of loop used, if the loop should be able to end prematurely, the break statement can be used, and if it should be able to execute until a specific result is achieved, the while loop should be utilized instead. Changing the end point of a loop in any other way reduces the readability of code and presents a risk of an infinite loop preventing further execution of the application.
• The use of _i iterator variable can be omitted on simplest loops, when current iteration does not need to be known. Left-side ++_i; incremental operator refers to a marginally faster operation than right-side _i++;, as it writing it on left side specifies a number to be incremented, then returned. Writing it on right side specifies the value to be copied separately, then the original be incremented, to then return the copy. There is no need to read the returned value, so the simpler way is used.
• If the loop is created to iterate though a linearly-stored data, such as in an array, the currently iterated value should be first saved to a local variable before reading it multiple times. Reading data assigned to a local variable is the fastest possible way to obtain its value.
• All data that does not change during the loop should be declared before it, not inside of it.

As an option, data-oriented GML-OOP constructors feature a forEach() method executing a loop with a known ending point. However, the above is loop declaration is recommended for a majority of cases, as it is the simplest and therefore the fastest to execute.

In situations where the number of iterations in one loop reaches extreme amounts, such as thousands or tens of thousands, simplifying the code to native GameMaker functions, rather than the use of constructors and their methods will yield faster execution times. However, such amount of iterations should first be considered a symptom of inadequate code separation or preparation prior to executing it.

---

Using Vertex Buffers

Like other data, graphical data can be pre-calculated for reuse in advance. GameMaker primarily offers two ways to do so. One is with Surfaces saving raster data of each pixel, other is through primitives saving the location, color, alpha and optionally texture coordinates of a drawn graphics, which can be saved in a Vertex Buffer. The amount of memory used by surfaces grows larger with its total pixel size, whereas the size of a vertex buffer grows with the amount of graphics to draw, regardless of their size. More specifically, the data of vertices it contains. Working with primitives involves a significant amount of repetitive steps to fill aforementioned data for each property of every vertex, but GML-OOP constructors greatly simplify their usage to just three method calls: creating a Vertex Buffer, rendering with it and destroying it. This is the same amount of operations as when using a Surface. When calling a draw function, GameMaker calculates primitive data to then render the graphic. Preparing that data ahead of time simplifies that step.

Vertex Buffers come with two limitations:

• Pre-calculated data is static, meaning its content cannot be modified after it is added to a Vertex Buffer. However, all of its properties can still be altered with a Shader.
• Graphics for a single primitive render can only come from a single Texture Page, as a texture swap will not be performed automatically. Unloading a current texture and loading in a different texture in its place takes time, so grouping sprites that are usually used at once on a single texture reduces the length of rendering operation.

---

Example

Code

Create Event
shape = new RoundRectangle(new Vector4(50, 50, 550, 500), new Vector2(25), make_color_rgb(0, 100, 200), 1, 5, c_white, 1);
renderData = shape.toVertexBuffer();
Draw GUI Event
renderData.render();
Clean Up Event
renderData = renderData.destroy();

---

Explanation
• Create Event: A RoundRectangle is constructed and assigned to the shape variable. That variable is then used to call RoundRectangle.toVertexBuffer() method, which constructs RoundRectangle.PrimitiveRenderData assigned to the renderData variable, containing all information necessary for rendering.
• Step Event: The renderData variable is referenced to call a RoundRectangle.PrimitiveRenderData.render() method, causing it to render content of the VertexBuffer to the current Surface. The filling of the shape is rendered first, then its outline.
• Clean Up Event: When the object instance is being removed, the RoundRectangle.PrimitiveRenderData.destroy() method is called and assigned to the renderData variable, using the method of a constructor it is about to stop referencing, to remove VertexBuffer data from memory, along with references to related constructors, as that method returns {undefined}.