Release 1

In between now and the time of the inception of this project, GameMaker set on a path of rapid change. These changes start to deter from what this project was designed for. At the time, that used to mean the latest version of GameMaker for a life-time Desktop license user. GameMaker, as an application, now refers to several branches of a similar application with different experiences, be it offered for a subscription user, lifetime license user, free user, a Long-Term Stable user and so on. For a project such as this, one of these experiences has to be chosen as a priority and others will inevitably lose something as a result, as each version provides increasingly differing set of features. The release of Long-Term Stable version of GameMaker, based on the September 2022 version of GameMaker presents new opportunities for the identity of GML-OOP. This version of GML-OOP and the ones released in close future after it will primarily target the Long-Term Stable version of GameMaker, which remains accessible and officially supported for the period of two years since its release on October 31 2022, for both subscription and lifetime license users. Further updates to GML-OOP will attempt to implement forward compatibility to functions implemented in later versions of GameMaker to features that realistically can be supported by implementing them as constructor methods. Several examples of this were added in this version. These implementations are currently version-agnostic and can be used on any version of Long-Term Stable. The decision of the direction for GML-OOP will then be taken after that time, as the future situation becomes more clear.

That does not necessarily mean that using this version of GML-OOP on the newest version of GameMaker will limit the user to a lesser experience. This release introduces a feature providing the user with precise control over what constructors can do. It comes in form of a static prototype property, containing a struct from which constructors will have properties added or methods replaced and added to them. This means that features not originally supported by GML-OOP can be added to it from each project that uses it. Properties of the ErrorReport constructor can also be configured during the runtime that way. Detailed information about this system are available here.

The error-handling system went through a major rework. In majority of cases, checks for errors in methods are not done preemptively anymore, but handled through the try/catch/finally keywords, added to every method that is expected to have any possibility of crashing the application. In such case, the produced error message will be based on the error message of the catch exception. This should result in non-trivial difference in performance, with less performance loss from error-checking system if no errors are caught, although catching an error is now much slower on performance. Previous system was even in both cases, but detected less errors and always took more resources in cases of complicated error checking. This new system promotes performance in cases where everything works as intended, at cost of performance in edge cases of errors. Methods where both systems are in place still exist if the likelihood of issues arising is much higher, particularly in methods related to rendering graphics, which are the reason for this system to begin with. Please note that this system is not designed to avoid errors caused by using variable_struct_remove() on default constructor properties. Lastly, the ErrorReport constructor received an overhaul. Reporting errors with it has been standardized into a single report() method, rather than several methods for various kinds of errors. Static configuration variables have been changed and work with new default values. They intend on avoiding reporting the same error in a row and set a limit on number of reports created to remove the possibility of memory leaks in edge cases of continuous error reports being made.

This release makes changes to the documentation format to make use of the new IntelliSense system built into GameMaker, Feather. Unfortunately, as of this release, that system has a strong tendency of enforcing its rules and providing incorrect information, so the design process of this change was focused on gaining the most benefit from it by losing the least possible amount of quality that the current documentation format already had. The documentation is now less standard to be able to use interface tool-tips, but if the situation improves, these changes will be reverted to bring them back to standards expected by the documentation based around JSDoc this project used to abide. The tool-tip support has been introduced for convenience, but please prioritize the GML-OOP documentation in its source when accuracy of the information matters.

A new Wiki has be released and now contains over 700 pages. It will be automatically updated for the latest release, thanks to a Documentation Generator created specifically for GML-OOP. That information is then supplemented with additional information not present in code documentation, more of which will appear over time. Complex and non-standard methods are to be prioritized with addition of explanations and code examples.

---

Changes from Version Gold:

Changes to existing content:
| All constructors: Overhauled the error detection system to focus on catching errors, rather than detecting them preemptively in most cases, as well as to handle and report more errors.
| All constructors: Reintroduced consistent file end whitespace.
| All shape constructors: No longer using rounded location values for rendering.
| All forEach() methods: Made the methods provide data from an immutable copy of the data, allowing for modifying the iterated data structure without unexpected behavior.
| Event system: Added support for single-level array argument groups.
| ErrorReport: Merged the reportError() and reportConstructorError() methods into a new report() method.
| ErrorReport: Moved part of functionality into new subsidiary constructor, ErrorReport.ReportData.
| ErrorReport: Overhauled static properties responsible for configuration.
| Vector2/Vector4/Scale: Changed set() method name to setAll() and added a new set() method in its place.
| Circle: Introduced default construction values used if each is not specified. Can now be constructed without radius, which will default its value into 0. Drawing such shape will work, but will not produce visible results.
| Surface: Made the Surface be automatically cleared on creation.
| Buffer.read(): Standardized numeric value returns to real number type.
| Layer.createInstance(): Added instance variable struct support.
| Map.getValue(): Added support for key lookup in nested Map constructors.
| Sprite.generateAlphaMap(): Overhauled the method to return a separate sprite and support non-constructor sprite argument.
| StringParser.replace(): Made the substitute argument optional.
| StringParser.charIsWhitespace(): Included invisible characters without the whitespace property, as they are now treated as whitespace by the engine.
| StringParser.trim(): Added argument support for skipping trimming of either end of the string.
| StringParser.split(): Changed the returnAsParser argument into parse_part argument, which accepts the StringParser constructor to work as it did previously or a function for parsing each split string before returning it.
| StringParser.fromArray(): Added argument support for adding a connector string in between of strings.
| ArrayParser: Changed the construction to allow constructing from non-array values, which then will be placed in an array.
| ArrayParser.copy(): Added argument support for backwards copying. Added argument support for function conditions deciding if a particular entry should be copied or if copying should stop.
| ArrayParser.setSize(): Added argument support for specifying the default value if the array is enlarged and made {undefined} the default value if unspecified.

Documentation changes:
+ Added Feather directives at the top of constructor code to have it to ignore suggestions for GML-OOP code.
| Changed number of comment-tagging slash marks to control whether Feather displays it.
| Swapped position of argument names and arguments to enable Feather displaying argument types as descriptions.
| Numerous changes and fixes to existing documentation.

Additions:
+ All constructors: Added a static prototype property on construction, from which properties and and copies of method will be added or methods will be replaced upon further construction.
+ Added non-functional empty construction on a single argument being specified as {undefined} for every constructor that did not have this functionality already.
+ Color2/Color3/Color4: set() and setAll() methods.
+ Vector4: combine() method.
+ SpriteRenderer: toArray() method.
+ Map: toStruct()/fromStruct() methods.
+ ArrayParser/StringParser: setParser()/containsAll() methods.
+ StringParser: getFirst()/getLast()/startsWith()/endsWith()/getBetween() methods.
+ ArrayParser: merge()/containsCondition()/getUniqueValues()/getSharedValues()/getFirstPosition()/getLastPosition()/getPositions()/getPositionsCondition() methods.
+ ArrayParser/Grid: getColumn() method.
+ Grid: getRow() method.

Fixes:
- Layer: Added missing check for element ID being numerical in their isFunctional() methods.
- Vector2.clampTo()/Vector4.clampTo()/Vector4.sort(): Added missing self return.
- Grid.set(): Fixed variables used by the method not being declared as local variables.
- List.fromArray(): Can now be used even if the List is non-functional.
- StringParser.split(): Fixed an issue where it would randomly return glitched text.
- Sprite.replace()/Sprite.merge(): Fixed a crash when sprite index was used as an argument.
- Layer.BackgroundElement.destroy(): Fixed the validation checking for Layer.spriteList instead of Layer.backgroundList.

Instructions for conversion from the previous version:
• All shape constructors: Adjust the code to call setRound() of the properties related to location before rendering.
• All forEach() methods: If the code relied on the data being modifiable during the time of the function execution, adjust it with regards of it being performed on a copy of that data instead.
• Vector2/Vector4/Scale: Change all calls of the set() method to setAll().
• Buffer.read(): If the code relied on returned numerical values not being of real type, adjust the code to either work with the real type or convert the result to the supported type.
• Sprite.generateAlphaMap(): Adjust the code to use the constructor that is the result of this function, instead of the constructor that called the method.
• StringParser.charIsWhitespace(): If the code relied on whitespace characters without whitespace property, adjust the code to detect either them or whitespace characters with charEquals() instead.
• StringParser.split(): Adjust the code to specify StringParser instead of true as the second argument.
• ArrayParser: Adjust the code that relied on ArrayParser being able to store non-array values as its property.
• ArrayParser.setSize(): Adjust the code to specify 0 as the second argument.
• Grid.set(): Remove code that worked around the issue of it erroneously setting variables in the scope that executed this method.
• ErrorReport: Adjust the code that relied on reportError() and reportConstructorError() methods to use the report() method instead. The callstack argument no longer needs to be provided and the errorLocation/methodName arguments have been replaced by the error_location argument, to which the constructor argument can be also provided by having it occupy a position in array before methodName. The errorText argument is now called error_detail. The report() method can also be used without any arguments specified to provide generic error information instead.