GameMaker: Studio Runtime Module System

A solution for namespacing

Welcome to the Runtime Module System for GameMaker: Studio 2.3!

Have you ever wanted to use assets from multiple people only to find out they defined resources with the same names? Did you go through the hassle of cleaning up the resources manually or did you just abandon the thought of using both assets at the same time? If you cleaned up the assets manually, how did you update them afterwads? Hopefully you can see that the lack of proper namespacing in GameMaker often leads to a lot of messy situations! This is exactly what the Runtime Module System attempts to help with.

GameMaker: Studio 2.3 is still in beta testing. Therefore the features used in this library might not be final. An effort will be made to keep up with any updates of the beta version of GameMaker, however the API of this library might break unexpectedly until GameMaker itself reaches a stable release milestone. Due to this, any released version of this library with a version below 1.0 will not follow semantic versioning and breaking changes may be introduced at any version number change.
Table of Contents:

Quick Start

One of the goals of this library is to be as unobtrusive as possible so installing it is as simple as downloading the source file and placing it in your GameMaker project. You can then start using the module system as you see fit. For example, you can register a custom module: 


	// Fictional code as actual API is not yet implemented
	register_module({
		name: "Example Module",
		dependencies: [],
		is_loaded: false,
		on_load: function() {
			self.do_stuff = function() {
				show_debug_message("OMG I'm doing stuff!");
			};
			show_debug_message(name + " is loaded!");
		},
		on_unload: function() {
			self.do_stuff = undefined;
			show_debug_message(name + " is unloaded!");
		},
	});

And then to use it: 


	// Fictional code as actual API is not yet implemented
	var module = find_module("Example Module");
	module.do_stuff();

Just refer to this documentation file for guidance on how to use the library. You can also download it for offline usage.

Configuration Options

As previously stated this library attempts to be as unobtrusive as possible. This also means not impacting performance too much and allowing for different configurations to exist for fine tuning. This is accomplished by a set of supplied macros that control the configuration of the library at compile time (including whether certains features are even compiled into the resulting distribution or not). All of these macros have a name starting with GM_MODULE_SYSTEM__.

If a macro enables or disables a feature then you should always set it to a compile time boolean expression (for example, just using the true or false constants directly). This ensures that unused code is not compiled into the final distribution if a feature is disabled. Otherwise, the feature will still be disabled at runtime but all of the code that depends on it is still compiled (including any code that is checking for whether the feature is enabled or not, which depending on the feature at hand might be a lot of code).

GM_MODULE_SYSTEM__ENABLE_INTEGRITY_CHECKS

Enables or disables the inclusion of integrity checks for the module system's internal state. These checks are meant to detect any (involuntary) tampering that might have occurred and warn the user about it (by throwing a runtime exception). Therefore, they are run whenever there was a possibility of uncontrolled code being executed. Some potential occasions are: when an API method is invoked (since any amount of code might have executed beforehand), when an API method invoked a user supplied method (since there is no control over what executes as part of that method), etc.

Due to the complexity of the checks and the amount of times they are executed it is likely that these checks have a severe performance impact. It is recommended to disable them for production builds of the game. They should only be enabled either on debug builds or at the very least when dealing with code that uses the module system directly.

By default this feature is enabled in order to ensure proper usage of the module system.

GM_MODULE_SYSTEM__VALIDATE_MODULE_STRUCTURE

Enables or disables the inclusion of structural validation of the modules supplied by the user. Including these validations ensures that any supplied struct adheres to the format expected by the module system, alerting the user (by throwing a runtime exception) if that is not the case. Therefore, this validation is performed whenever the user hands in a module to the system and after loading/unloading of the module (as these operations can potentially mutate the module).

Due to the complexity of the checks and the amount of times they are executed it is likely that these checks have a severe performance impact. It is recommended to disable them for production builds of the game. They should only be enabled either on debug builds or at the very least when dealing with code that uses the module system directly.

By default this feature is enabled in order to ensure proper usage of the module system.