Awesome

rt-shell

rt-shell, or run-time shell an easy-to-use, customizable, and extensible cheat/debug console for GameMaker Studio 2.3+.

Table of Contents

• Setup
• Writing Your Own Shell Commands
• Adding Command Metadata
• Keyboard Shortcuts
• Configuring rt-shell
• Licensing
• Attribution

Setup

Integrating rt-shell into your project is simple: just download the latest release, and then in GameMaker Studio click on the Tools menu and select Import Local Package. Choose the .yymps file you downloaded, and import all assets.

Alternatively you can install rt-shell from the Game Maker Marketplace.

The obj_shell object is a persistent object, so you only need to include or create it once, though it is smart enough to automatically handle excess instances. The default way to open the shell is Ctrl + Shift + C, and it can be closed by pressing Esc.

Writing Your Own Shell Commands

rt-shell will execute any global scripts whose names start with sh_. You can see the example scripts included with the test project in scr_shell_scripts.gml.

Let's write a simple "Hello World" commands together. We first need a place to create the function, so create a Script asset in your project. The name of this asset isn't important, but we can call it scr_shell_scripts as I have done in the test project.

Now let's write our function! We want it to take an argument as input, and print "Hello [argument]!" to the console. Like so:

Our function needs to start with sh_, so let's call it sh_say_greeting. As you can see in the example screenshot above, you do not include the sh_ when calling the function.

rt-shell functions take an array called args as an argument, and any arguments passed to the function at the console are present in this array in GML. args[0] always contains the name of the function, as in typical shell programming, and args[1] and onwards are the real arguments passed in. Your input string is split into arguments on the space character, and you can use double-quotes to pass in an argument that contains spaces (i.e. say_greeting "Daikon Games")

rt-shell functions can optionally return a string, and if they do that string will be printed to the console.

With all that said, here's our final hello world function:

function sh_say_greeting (args) {
	return "Hello " + args[1] + "!";
}

Simple, right? With that function in place, you can call say_greeting from the shell as you saw in the screenshot above. I'm sure you can think of all sorts of commands that would come in handy for debugging and testing your game. How about a script that set's the player's max health, or money counter? A script that spawns an enemy or a treasure item? Experiment and have fun, happy developing!

Adding Command Metadata

rt-shell provides a way for you to add metadata to your commands. This will let you see possible arguments and autocomplete suggestions within the shell, as well as let you plug into the shell's built-in help commands to document your own functions!

Adding metadata works much the same way as adding your custom commands in the first place. You simply create a new function that begins with meta_ followed by the name of your function. For instance, if you had a function sh_create_balloon then you could add metadata by creating another function meta_create_balloon. The part of the name after sh_ and after meta_ must match exactly for them to be linked.

Let's say that sh_create_balloon looked like this:

function sh_create_balloon (args) {
	var mX = args[1];
	var mY = args[2];
	var balloon = instance_create_layer(mX, mY, "DemoInstances", obj_balloon);
	balloon.mType = args[3];
	balloon.mColor = args[4];
}

You can see that it takes four arguments: X/Y coordinates and two arguments defining a type and color. We can then make an associated metadata function. Every metadata function should return a struct with a specific format, as you can see:

function meta_create_balloon() {
	return {
		description: "create a balloon",
		arguments: ["x", "y", "type", "color"],
		suggestions: [
			mouseArgumentType.worldX,
			mouseArgumentType.worldY,
			["normal", "animal_dog", "animal_snake"],
			function() {
				var _colors = [];
				// some code that fetches a dynamic list of available colors here
				return _colors;
			}
		],
		argumentDescriptions: [
			"the X coordinate to create the balloon at",
			"the Y coordinate to create the balloon at",
			"the type of balloon to create",
			"the color of the balloon"
		],
		hidden: false,
		deferred: false
	}
}

When you go to type your script into the shell your argument hints will show up like so:

and so will your autocompletion suggestions:

The command will also display the arguments and description fields when running help create_balloon.

Some things to keep in mind:

1. The function names must match after the sh_ and meta_ prefixes.
2. The order of the array items in arguments, suggestions, and argumentDescriptions must line up
3. If suggestions aren't needed for an argument just input a blank array [] or undefined
4. Each of the items inside suggestions can be either a static array of possible suggestions, or a function that returns an array. If you use a function, it will be called at run-time, making the suggestions dynamic!
5. description and argumentDescriptions are optional, they're only used for the help output
6. hidden is optional, but if hidden is set to true, the function will not appear in the help output, or in autocomplete suggestions! This way you can add secret cheat codes. You will still be able to type help hidden_function_name and see help output, but only if you know that hidden function's name in the first place.
7. deferred is optional, but if deferred is set to true, the function will not execute directly when called. Instead it will be queued up, and all deferred functions in the queue will run in sequence when the shell is closed.

Here is a full reference of the properties that can appear in the struct returned by meta_ functions:

You may have noticed the mouseArgumentType enum as a possible value for the items in suggestions. If an argument's corresponding suggestions value is one of the following mouseArgumentType values, then at the console prompt while inputting that argument, a value will be hinted at based on the current position of the mouse cursor. If the left mouse button is pressed while hinting at a value, that value will be accepted and inserted into the console. The following values for that enum are possible:

By using these mouse argument types appropriately, you can make very user-friendly functions for yourself, like the ability to spawn an object at your mouse cursor by using the worldX and worldY values, as shown in the create_balloon example above, or performing actions on a specific instance by clicking on it. It's a powerful tool!

Keyboard Shortcuts

In the shell, there are a number of useful keyboard shortcuts. These are all triggered using the Meta-key which by default is Control, but can be altered (see Configuring rt-shell)

Configuring rt-shell

The following variables on the obj_shell object can be configured. They are defined on the object's Variable Definitions panel in the IDE. It is recommended that you instantiate obj_shell programatically and then set these parameters on the created instance via code. This way you can upgrade to a newer version of rt-shell without having to re-configure your shell object!

Appearance Configuration

You can see examples of various ways to customize the shell's appearance on the Theme Gallery page!

Other Configuration

Licensing

rt-shell is licensed under Creative Commons BY 4.0. Essentially, you may use it, change it, ship it, and share it, with attribution. Just make sure to somewhere mention the use of rt-shell by Daikon Games!

Attribution

Fonts

Default shell font, Consolas © 2018 Microsoft Corporation. All rights reserved. Demo font, Peaberry by emhuo