Overview

This page presents a general overview of how GML-OOP operates.

---

Construction

Each constructor has multiple construction types, which allow them to be constructed based on different information they are provided. The most generic one is tagged to be suggested by the GameMaker code editor tooltip and is usually referred to as the "New constructor", in which case its arguments are not listed alongside other construction types above the code of the constructor, as it is done by the tags. Every constructor also has a "Constructor copy" construction type, which will cause them to duplicate the properties of the constructor of the same type as itself, when they are provided as the first argument.

All construction arguments are always saved in the argument_original array, which is not used by the GML-OOP code and is created for the reference by the developer. The arguments are then parsed in the construct() method, which is the only method that is generally not intended to be manually run. The isFunctional() method can be called at any point after construction in each constructor to confirm that the constructor has been constructed properly and is keeping its ability to function.

Since the construct() method and argument_original variable are relevant only for the construction and their purpose is the same for all constructors, they are not listed in the documentation of each constructor.

---

Properties and methods

In the context of this project, the word "property" refers to a non-method variable that the constructor creates in itself, which then can be read. Some can be freely modified, others are crucial for the functionality of the constructor. The type and modifiability of each is noted on the documentation page of each constructor. The word "method" refers to a static variable that holds a function declared originally by the construction upon its construction.

After creating a constructor with the new operator or returned from a function, its properties and methods can be used while the construction is functional. All properties are declared as variables in the construct() method and all usable methods are declared below it. Methods have to be called using their name ended with a pair of curly baskets. Using their name without them will cause GameMaker to read the variable that stores the function, rather than actually call that function.

If the construction failed, all of its properties will be declared as {undefined}, which might be stringified if the functional property was meant to be a string. The methods will be declared regardless, but will not fully execute if called while the constructor is not functional. Most methods first check if their constructor is usable and will create an ErrorReport if the execution was not possible, with the intention of notifying the developer about the nature of the error. This by itself will not cause a crash of the application if not specifically configured to do so, but will alter the result of the return statement to the one documented as returned "On error".

---

Arguments

Every argument used in construction or to call a method is documented, either directly in code above the constructor and method or in this documentation in a more detailed way. Their supported data types are documented first, followed by their name. One argument can support more than one data type, each separated by the | symbol in the documentation. In that case, only one data type can be provided as that argument for one specific call. The execution of the code will be adjusted according to each supported type of the argument.

Most of arguments are optional, aside from the ones that are vital for the execution of the code. Optional arguments are noted with the ? symbol after their name and can be skipped by either not providing them or by specifying them as {undefined}. In that case, the code will be executed in a way that either does not use the information otherwise provided by that argument or by replacing it with a default value that is the most similar to skipping the feature the respective argument interacts with.

GML-OOP constructors can often be specified as an argument, which is done through variable referring to them or by constructing them directly while listing an argument.

Some arguments can be repeated if noted with ... symbols after their name. If several arguments are listed in such a way, all of them can be repeated. It is done by specifying all repeatable arguments in the exact order as they are listed in, each time they are repeated.

---

Element constructors

Several constructors have their code declared inside of the code of other constructors, making them subsidiary to them. Such constructors are referred to as the element constructors. They are not accessible globally and can be constructed only within the scope of the constructor in which their code was declared in, so by using its method or through the with statement. The instanceof() function will not return their exact name, but append additional information while used with them, which can be removed using functions such as string_copy(). Aside from that, element constructors are not functionally different from other constructors, including the fact that they also can have their own element constructors.

---

Constructor prototypes

Every constructor contains a static prototype struct property, which allows for overwriting and extending their properties and methods. This struct is empty by default and can be manually filled with values. After that, its contents will be iterated before each construction of a constructor with the same name to add these values to it under the same property or method names.

Changes to prototype do not modify other contents of already existing constructors. Added contents can be removed by using variable_struct_remove(). Each constructor has an "Empty" construction type for purposes of configuration.

Please remember that values added to a constructor in this way cannot be static themselves and will occupy additional memory per affected constructor. This difference is negligible on its own, but requires cautious use to not become a memory problem due to overly high number of added properties or constructors with them.

---

Event system

Constructors which render graphics have an event system that can be set up through their event struct property. It contains another structs with names of the timing at which their respective method is executed. Each has two properties: the callback property can refer to a method called automatically on that event timing and the argument property is a value or an array of such provided to it. The callback property can also be an array of methods, which will be executed from its beginning. In that case, the argument property can be a single value provided to each of these calls or an array of them, providing one argument to each call at the respective array position. Each of these array values can also be an array in order to treat all of its values as separate arguments provided to the respective method call.

The scope of event function calls is the constructor executing them, allowing for direct access to the properties and methods of the constructor inside of that function. The properties of the event struct are declared with {undefined} values upon construction and are optional to being configured separately after that. The entire event struct can also be replaced with {undefined}, after which the event system is no longer operated by its constructor.

---

Data type listing

Each property, argument or a returned value can accept one or multiple data types. They are either of a data type used normally in GameMaker Language or a GML-OOP constructor. Recognized data types will be listed in curly brackets, separated by a vertical bar if multiple data types are relevant to the context. If a GML-OOP constructor can be specified as an argument, its exact name will be listed, including capital letters. All other data types are listed fully in lowercase. Type listings can also narrow the data type to more specific values, formats or groups when written after the : symbol.

If an array is an applicable type, it will be listed with square brackets after its recognized data type and it can only contain values of that data type. Arrays are listed separately if a non-array value of the same type is also applicable. However, arrays can be listed without type as [], in which case values contained in it can be of every type listed prior. Arrays listed with [+] will contain values of that listed type, but each of them can also be a nested array containing values of the same type.

Since {undefined} is used to skip all optional arguments, it is not listed as an acceptable data type for such arguments, but will still work. Methods that are not documented to return anything will return {self} for the purposes of method chaining.

Examples of data type listing are the following: {int}, {real|Range}, {real|real[]}, {real[+]}, {int:color}, {string:path}, {int:instance|struct|string|[]}, {undefined}.

Listed below are the descriptions of data type keywords that refer to concepts found natively in GameMaker Language.

Keyword	Description
{void}	Refers to the act of not providing any value as an argument. Used in branching the code according to argument_count with arguments that were not named in function declaration.
{any}	Any other non-void data type can be in its place. If noted along other data types, they will be handled differently. If noted as {any:string}, the value will be stringified when used.
{undefined}	A value literally declared as undefined, a unique data type in GameMaker Language that is not shared with any other data types. It always stringifies as it is written. A function or method that would not return any value by default returns undefined on attempt to read its result, but methods of GML-OOP constructors will return {self} in such case to support method chaining.
{bool}	A boolean value. Can be either a true or false constant (corresponding 1 and 0 respectively), a result of a conditional statement or a value. A numerical value that is higher than 0.5 is treated as true and any other values are treated as false.
{int}	An integer number. Refers to a whole number without a fraction. Specifying a number with a fraction in its place is not erroneous, but can cause unexpected behavior, as how it will be treated in each function by GameMaker is not disclosed. Most of features in GameMaker are referred to through an integer ID number, in which case the name of the required resource ID will be listed after a colon.
{real}	A number that is either an integer or has a fraction. While Infinity and NaN are technically treated as real numbers, they are never expected to work in GML-OOP and can cause unexpected behavior.
{string}	A line of text of any length declared in quotation marks. If noted as {string:path} it has to follow a file path format unique to the function it is being used with.
{char}	A string containing exactly one character.
{struct}	A struct of any type, not necessarily constructed by one of GML-OOP constructors.
{function}	Either a native GameMaker Language function, a method declared to a variable or a function statement directly specified as an argument.
{constant}	A numeric value referred to by a constant used in GameMaker. The beginning of the name of the relevant group of constants is always written after a colon and ended with an asterisk where the name similarities end. Note that some groups of constants are named similarly and cannot be differentiated in such a way. The appropriate constants are listed on the relevant documentation pages.
{pointer}	A pointer to a location in the memory. While pointer_null and pointer_invalid are technically treated as pointer they are never expected to work in GML-OOP and can cause unexpected behavior, although they can be returned if a valid pointer could not be returned.
{self}	Used in the code of a constructor, instance or a with statement. Refers to what is currently executing the code and can be used either to refer to its properties and methods or to return it as a value in a result of a {function} call. If stringified, it can return a {string} result of its toString() method, or if it is not present, it will stringify its non-static properties as a {struct}. Internally treated as the value -1.
{all}	Used either while specifying instances to collectively refer to all active ones in the current room or as an argument if listed directly to alter the result, most often to scope the number of affected elements to all existing ones. Internally treated as the value -3.
{noone}	Returned if a constructor or an instance would be returned, but was not possible to. Internally treated as the value -4.