Second LTS Cycle Preview

Important

This is a preview release for Release 2, published for testing and upgrade preparation purposes. As the development process is ongoing, it might contain errors, undergo design changes and contain experimental changes. This release will be removed some time after its final version is released. Listed below are subsidiary testing versions, published as they are developed in the SecondLTSCycle branch. Change notes for each will refer to previous subsequent version and will note the version of GameMaker they are intended for. These changes will not be reflected on Wiki for now. A discussion for this preview release will be ongoing until its completion.

As Long-Term Stable branch of GameMaker was announced to release in a two-year cycle, this preview is being made in preparation to the approaching end of its first cycle. September 2024 marks the second year since the first Long-Term Stable release, but the actual release date for the second major Long-Term Stable release is not exactly clear. Until that, this preview will be periodically updated for use with monthly versions of GameMaker and to make new changes available for testing.

Achieving compatibility with newer releases of GameMaker required performing project-wide changes, following changes to design inside the GameMaker engine, particularly new handling of data types. Included changes should reduce the amount of overhaul necessary in case of another such change. It should be noted that in the process, majority of calls to check types of constructors were changed from using the instanceof() function to use the new is_instanceof() function. The difference between them is that the first is compared to string, but the second takes an argument with index of the constructor to compare, written literally with its name without quotation marks. As that is not treated as a string, it is faster to evaluate, but it means the code of each GML-OOP constructor now expects other constructors to be included in the project for each constructor index to be valid, otherwise calls of is_instanceof() can result in a crash. This is important while attempting to include only specific constructors in the project and not the entirety of GML-OOP.

Cross-platform compatibility and optimization are the themes of this upcoming version and will be gradually improved, tested and expanded along subsequent version releases:

• As long as Desktop and Mobile export targets remain free to use as per GameMaker licensing, GML-OOP releases will be tested on Ubuntu and Android export targets in addition to current Windows target. The same was considered for macOS and iOS, but closed development ecosystem of these operating systems ultimately prevented it from manifesting.
• A major step for optimization is the introduction of the new VertexBuffer constructor, with its subsidiary VertexBuffer.PrimitiveRenderData constructor and related VertexFormat constructor. They enable significant reduction of rendering times for static graphics, which can then be manipulated by Shaders. Most important of existing constructors rendering graphics now support them through their new toVertexBuffer() method, designed to allow for a mostly seamless change to the use of this method of rendering. The contents of a Vertex Buffers returned by toVertexBuffer() methods are formatted for use with either no active Shader or one with the same format as the default passthrough Shader automatically included by GameMaker upon creation of Shader assets. Information about systems these constructors are based on is present on GameMaker Manual here and here. Streamlined details about their use will be added to the Wiki at a later date.

Long-time considered changes to construction of every constructor were introduced:

• They now have a static constructor property, containing numerical index GameMaker assigned that constructor for that runtime.
  This change was ultimately postponed to promote the use of safe-to-execute instanceof() checks, but as its usefulness increased with time, it is finally included. Constructors can have their constructor property read to recognize their type and this is the fastest way to do so, as it done by evaluating a number that is already known and does not need to obtained through a function call. However, it can be only used while being absolutely sure that what is being evaluated is a GML-OOP constructor or any other object with a constructor property, as reading a property that does not exist will cause a runtime error, unlike calls of instanceof().
• They no longer have the argument_original property saved at the time of construction.
  This feature was included, as arguments have to be saved to an array upon construction to execute them through the construct() method, so that method can have access to the entirety of the constructor at the time of construction. However, it did not prove itself to be very useful over time and instead increased the amount of data saved in constructors. Cases, where original value was actually used, such as the value_original property of RangedValue constructor, were already resolved with an additional property and this has not changed.

A new Callback constructor is included in this release. It is a new handler storing a single or multiple methods and argument or sets of such, passed to said methods during execution. This is the same solution as one used in the Event system, as having a constructor to easily pass methods and arguments for later execution is useful in various contexts. The Event system has been overhauled to utilize the Callback constructor, requiring renaming of the callback property it used to ID.

Supporting Vertex Buffers means that enables possibility of rendering three-dimensional graphics, and so GML-OOP now supports constructors oriented around working with three-dimensional space and projections: the Camera resource, Vector3 and EulerAngle containers, as well as Plane and Cube shapes. However, it should be noted that GML-OOP still remains designed for applications with two-dimensional graphics and three-dimensional support is intended to be basic and used mainly within two-dimensional projection, since correctly displaying three-dimensional graphics without perspective in orthographic view produces same visual result as they would with any other two-dimensional graphic drawn in the same way. While intending to render three-dimensional with GML-OOP constructors, the following should be noted:

As a third axis, the Z axis, was added to be operated with above constructors, a decision had to be made what this axis represents. Calculations within GameMaker itself use reversed Z axis, which can be described that adding to a Z location of an object will visually move it away from a camera rotated towards negative Z, and subtracting from the Z location of the object will move it closer to it. Since other axes are not reversed, the code of GML-OOP was designed to instead use non-reversed Z axis, which means, in that situation, subtracting from Z location is the way to move the object away from the camera, since it already is pointing towards a negative Z, and vice versa, adding to it will move it towards it. This means that any previously existing code operating the Z axis will have to reverse the mathematical sign of operations related to that axis.

---

Note

Text in parentheses refers to changes to previous preview versions and will not be included in final release notes.

Release 2 Preview 1
Intended for monthly GameMaker Runtime version 2024.2.0.132 released around February 29th 2024.

Changes from Release 1:

Changes to existing content:
| Updated validity checks to comply with in-engine updates and replaced their reiterations with isFunctional() method calls.
| Replaced all simple instanceof() calls to use is_instanceof() instead.
| ParticleType: Made constructor properties be updated instead of replaced when setting new values when they already exist as constructors.
| Point.render(): Mirrored the scale of the the Sprite render to render to attempt mimicking positioning of draw_point().
| Vector2: Simplified value type checks for other Vector2.
| TextAlign.setActive(): Minor consistency change to the error text.

Additions:
+ VertexBuffer, VertexBuffer.PrimitiveRenderData and VertexFormat constructors.
+ Point/Line/Triangle/Rectangle/SpriteRenderer: toVertexBuffer() method.
+ TextRenderer: getPixelSize() method.
+ TextAlign: getMultiplier() method.

Fixes:
- PriorityQueue/Queue/Stack/Surface: Moved temporary data structure destruction in try statements to finally statements to prevent memory leaks in case of errors being caught.
- Surface.setSize(): Made size property be updated in a consistent way for both cases of the Surface already existing and being recreated with the target size.

Instructions for conversion from the previous version:
• Include missing GML-OOP constructors into the project if a code would execute an is_instanceof() call by a method to check for a constructor with no recognized function index.
• Point.render(): Confirm if rendering produces an unexpected offset by one pixel and adjust its location by that amount if necessary.

---

Release 2 Preview 2
Intended for monthly GameMaker Runtime version 2024.6.2.162 released around July ‎15th ‎2024.

Changes from Preview 1:

Changes to existing content:
| Overhauled equals() methods to support more data types.
| TextRenderer: Overhauled the constructor to support Scale and Angle.
| TextRenderer: Added Font point size calculation support to render() and getPixelSize() methods.
| TextRenderer: Prevented stringifying the value on construction.
| Surface: General minor consistency changes to ErrorReport detail descriptions.
| ParticleType: Made the number argument of setStep() and setDeath() methods optional, with 1 as the default value.
| ParticleType: Changed setter method descriptions to note whether they affect already existing particles.
| Point/Line/Triangle/Rectangle: Added property replacement argument support to the toVertexBuffer() method.
| VertexBuffer.PrimitiveRenderData: Added simplified Event support. (NOTE: This system is planned to be changed in the next Preview.)

Additions:
+ Static constructor property in every constructor.
+ Callback constructor.
+ TextRenderer/SurfaceRenderer: toVertexBuffer() method.
+ StringParser: capitalize(), toFile(), fromFile(), fromJSON() methods.
+ Vector4: isDegenerate() method.
+ Vector2/Vector4: exceeds() and subceeds() methods.
+ Range: sum(), difference(), product(), quotient() methods.
+ VertexBuffer.PrimitiveRenderData: (isFunctional() and toString() methods.)

Fixes:
- Font: Fixed wrong variable being used during constructor copy of a Font based on a Sprite.
- ErrorReport.report(): Fixed first report not being included in duplicate report check.
- ErrorReport.ReportData.equals(): Fixed the detail struct not being properly checked, causing multiple duplicate reports to be created when ErrorReport was configured to ignore duplicate reports.
- SpriteRenderer.toVertexBuffer(): (Fixed incorrect axis usage in location calculation.)
- Grid/Map: (Added missing isFunctional() calls to methods that should use them, but have not been updated yet.)
- Rectangle.toVertexBuffer(): (Fixed incorrect primitive type constant being used for outline.)
- VertexBuffer.PrimitiveRenderData: (Fixed optional construction arguments not supporting undefined.)

Instructions for conversion from the previous version:
• TextRenderer: Change every construction that used color or alpha argument to provide undefined as two arguments before them to supply newly added scale and angle construction arguments.
• TextRenderer: Change instances where code constructed with a non-string value and relied on it being stringifiied to manually stringify value specified as argument for that construction.

---

Release 2 Preview 3
Intended for monthly GameMaker Runtime version 2024.8.1.218 released around September‎ 10th ‎2024.

Changes from Preview 2:

| (VertexBuffer.setLocation(): Renamed to setLocation2D(), following the introduction of three-dimensional support.)
(| Callback: Added a scope property to configure the execution scope of function. The scope is now nested, first in other and then in one of the scope property.)
| Event system: Moved to use the Callback constructor, instead of a struct.
| Shader: Overhauled the use of sampler uniforms to remove the sampler struct and include its information in the uniform struct with the type property equaling the "sampler" string.
| Layer.destroyInstance(): Changed returned value to undefined to support inline assignment.
| Sprite.getTexel(): Removed the argument to simplify the method to always refer to the first frame of the Sprite.
| Minor general code and documentation changes and fixes.

Additions:
+ (VertexBuffer.PrimitiveRenderData: destroy() method.)
+ (Callback.execute(): Scope configuration argument support.)
+ Camera, Vector3, EulerAngle, Plane and Cube constructors.
+ Font: Signed Distance Field support.
+ Scale: add(), substract(), multiply() and divide() methods.
+ Vector4: roundToBorder() method.
+ PriorityQueue: getFirstPriority() and getLastPriority() methods.
+ TextRenderer: Scale argument support to methods calculating offsets.
+ Sprite: Added support for multiple frames being specified to getTexture() and getUV() methods.
+ Shader: Added Vector3 argument support to setUniformInt() and setUniformFloat() methods.
+ Color2/Color3/Color4/TextAlign/Rectangle/Font/Surface/SpriteRenderer/TextRenderer: equals() method.
+ TextRenderer.wrapText(): Replacement location and scale argument support.
+ StringParser.getPixelSize(): Replacement scale argument support.
+ StringParser.getSubstringPosition(): Argument support for finding multiple positions.

Fixes and removals:
- Removed the argument_original property from the construction of every constructor.
- Layer.destroyInstance(): Corrected the method name in Error Report.
- Layer.destroyInstance(): Added instance validation before reading its values.
- ErrorReport.ReportData.equals(): Fixed a crash in case detail property was a string.

Instructions for conversion from the previous version:
• (Callback: Adjust code to use the correct scope in functions that referred to the other keyword.)
• (VertexBuffer.setLocation(): Rename the uses of this method to its new name, setLocation2D().)
• All constructors: If the code relied on data saved in argument_original property, save that data manually and adjust the code to use it instead.
• All constructors with the event property: If the event system was used, change the name of the callback property in every case it was used in to ID. Confirm that events execute as intended.
• Shader: If the data from the sampler struct was used, adjust the code to use that data in the uniform struct instead.
• Layer.destroyInstance(): If the calls to this method were involved in chaining methods, adjust the code to not chain after it and confirm if the new returned value is intended.
• Sprite.getTexel(): Remove any arguments passed to this method.

---

Release 2 Preview 4
Intended for monthly GameMaker Runtime version 2024.11.0.179 released around December 19th ‎2024.

Warning

Be aware that the intended GameMaker Runtime version for this preview changed how the other scope works in the engine. Its previous behavior remains available as an option, enabled with Game Options → Main Options → General → Deprecated Behaviours → Legacy Other Behaviour. This option is enabled by default for projects imported from older engine versions, but is NOT enabled by default for new projects — do make sure to confirm which is actually used and how it behaves. Project-wide changes were conducted to ensure the other keyword is no longer used where possible, so the code of GML-OOP itself behaves the same, whenever this option is enabled or not. However, depending code might behave differently if it relied on entries of other provided by GML-OOP, as there are two places where this change has an effect: Data saved and output by the ErrorReport constructor and in functions executed by the Callback constructor. In case of the ErrorReport constructor, the first location part of an error being reported is always the other scope, so what it refers to will now differ, depending on how other behaves. Functions executed by the Callback constructor provide other scope to the executed function, which can be optionally accessed by the code of the function. This will now behave differently in the same way this setting changes its behavior. GML-OOP was designed for the legacy behavior, so enabling this option is recommended if possible.

Note

This is likely the final preview before the next Long-Term Stable release, unless there will be pressing issues or incompatibilities to fix. Expect that the full release might come with a delay of up to several months after the next Long-Term Stable release.

Changes from Preview 3:

| Project-wide changes to prevent the code from relying on the other scope whenever possible.
| Plane.toVertexBuffer(): Implemented argument configuration allowing for specifying how location of vertices is handled if used with a Sprite that is in a texture group with Tools → Texture Groups → Automatically Crop option enabled, to either stretch the cropped Sprite to the edges of the Plane or to reduce the size of resulting shape, according to space cropped during compilation.
| ParticleType: Changed ErrorReport text in setStep() and setDeath() methods to use simpler wording.
| ErrorReport.ReportData.formatLocation(): Added support for struct Room references.
| Minor general code and documentation changes and fixes.

Additions:
+ Sprite: getTextureTrim() method.
+ StringParser: formatStruct() method.

Fixes:
- ErrorReport.report(): Removed an unnecessary space from the report string, after the "Callstack:" text.

Instructions for conversion from the previous version:
• Ensure the code relying on other keyword behaves as intended and adjust it if necessary.
• Plane.toVertexBuffer(): If the code relied on the resulting shape not being made smaller when used with a cropped Sprite, adjust the code to specify so using the new last argument.
• ErrorReport/ParticleType: If code relied on parsing text output by the error reporting system, adjust the code to use its new text.