Quantum / Q-script

Intro to QCMD #

QCMD is an abbreviation for Quantum Command, the modular command console which comes hand-in-hand with Quantum, the core framework products such as VNgen are built on. Quantum is a framework by XGASOFT designed to assign numeric IDs to blocks of code itself and provide a set of common practical functions to manipulate them, allowing for the creation of entirely custom programming languages within the GameMaker Language (or GML).

 

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 specify a command as a string to listen for and the script resource to execute when that string is input to the QCMD console.

Example:

sys_cmd_add("q_goto", q_goto);

It is not necessary to define arguments when adding a new command to QCMD, as arguments are processed in real-time.

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

Although this function is all that is necessary to add new commands to QCMD, when designing functions 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 custom commands in QCMD can radically improve workflow when testing and debugging projects in real-time.

Last updated on January 27, 2018
Suggest Edit