Skip to main content

Introduction to QCMD

QCMD is an abbreviation for Quantum Command, a modular command console which comes included with the Quantum framework for GameMaker Studio. As previously stated, Quantum is built on a custom event/action structure which progresses linearly by default. This makes debugging a challenge, as testing one new event may require waiting through many others. But Quantum is designed for non-linear event execution as well, and harnessing this power with QCMD can make testing and debugging both fast and simple.

To access QCMD, run the sys_toggle_cmd command, or use the debug mode as outlined in the documentation for your specific Quantum-based product. A terminal will appear at the bottom of the screen, like this:

Here you can execute commands in-game which will be performed in real-time.

Structure#

QCMD is comprised of two parts: the console itself and one or more commands which are written and loaded into the console externally. Each command is a miniature program of its own, defining its own syntax and instructions. When complete, a command may also return a custom string to the console as feedback for the user.

As a development tool, QCMD is cleverly designed to remain outside of memory until called. This means keeping it in commercial projects won't occupy unnecessary resources on consumer devices, but it will still be there to debug compiled builds when needed.

Creating Custom Commands#

Using the built-in sys_cmd_add function, any script can be turned into a QCMD command. Simply define the string to listen for, and the script to execute when that string is input to the QCMD console.

It is not necessary to define arguments in the QCMD string, as arguments are parsed and passed into the script automatically.

Example#

sys_cmd_add("vngen_goto", vngen_goto);
note

QCMD stores commands in a database which occupies a small amount of memory once initialized.

Best Practices#

Although this function is all that's necessary to add new commands to QCMD, when writing scripts specifically to operate as commands, there are a few caveats and best practices to keep in mind:

  1. All arguments are passed into scripts as strings (because user input is obtained as a string). Other types of data must be converted. (e.g. real(argument0) or asset_get_index(argument0) to convert string input to a real number or asset index, respectively.)
  2. Commands are only executed once and will not continue being processed over time. They can, however, be used to trigger longer processes.
  3. All erroneous forms of input should return a string alerting the user of what went wrong. This is done simply by using the return command to return a string to the console. (e.g. if (argument_count == 0) { return "Error: this command requires X arguments."; })
  4. If a command is processed successfully, say so! Alert the user of what the command has done by using the return command. (e.g. if (argument0 == true) { window_set_fullscreen(true); return "Successfully set window mode to fullscreen."; })

While Quantum-based products include a host of built-in commands, effective use of your own custom commands in QCMD can radically improve workflow when testing and debugging projects in real-time.

Edit this page