Skip to content

Console Guide

Jump to bottom
Peter Robinson edited this page Aug 18, 2026 · 3 revisions

Introduction

The console is a command line into your running game. You type TorqueScript at it and the engine runs it, immediately, against the game as it stands — you can look at an object, move it, call one of its methods, or change a global, without stopping and rebuilding anything.

It is also where the engine talks back. Every echo your script makes, every warning, and every error appears here, which makes it the first place to look when something does not work.

This guide covers version 4.0 Early Access 4.

If you are new to Torque2D: this is the tool that will save you the most time. There is no step-through script debugger you are likely to use (see Remote access for the one that exists and why it is awkward), so printing a value and looking at an object are how you find out what your game is doing.

Opening it

Press Ctrl + Tilde (~) anywhere in the engine, then pick the Console tab.

The bottom of the screen is a text box you type into. Everything above it is the log.

Running things

Type an expression and press Enter. The console echoes what it ran, prefixed with ==>, then anything the line printed:

==>echo(1 + 1);
2

Wrap what you want to see in echo(). The console runs your line but throws the result away, so a bare expression prints nothing at all:

==>MyHero.getName();

That is the whole output — no error, no value, just the echo of what you typed. It ran fine; nobody asked for the answer. echo(MyHero.getName()); prints it.

Two conveniences worth knowing, because they make the console feel unlike a script file:

  • Parentheses are added for you. If what you type has no (, =, space, { or } in it, the console assumes it is a function and appends (). So typing myFunction runs myFunction().
  • The semicolon is added for you if you leave it off.

Up and down arrows walk back through what you have typed, so re-running a command with a small change does not mean retyping it.

There is a 255 character limit on one line. If you need more than that, put it in a script file and exec it.

cls clears the log.

Printing things

Three functions, told apart in the log by color, which comes from your theme's console profile:

echo("the plain one");
warn("something looks off");
error("something is wrong");

echo is the one you will use constantly. Dropping an echo into a function to find out whether it runs, and what it received, is the fundamental debugging move in TorqueScript:

function Hero::onCollision(%this, %other)
{
    echo("hit " @ %other.getClassName() @ " named " @ %other.getName());
}

Everything printed also goes to console.log in your Torque2D folder, so you can read back what happened after the game has closed — useful when the interesting part scrolled past, or when the game crashed.

Looking at an object

Every object has an id, a number the engine assigns it. Named objects can also be reached by name. Either works in the console:

echo(GameScene.getCount());     // by name
echo(1043.getClassName());      // by id

dump() is the one to remember. It prints an object's class, its methods, and all of its fields with their current values:

MyHero.dump();

When a sprite is not appearing, or is the wrong size, or will not move, dump() tells you what the engine actually thinks is true about it — which is often not what you thought you set.

Other useful ones:

Call Tells you
%obj.getId() its id number
%obj.getName() its name, if it has one
%obj.getClassName() what kind of object it is
%obj.getFieldValue("Size") one field, by name
%obj.isMethod("onCollision") whether a method exists before you call it
%obj.dumpClassHierarchy() what it inherits from, all the way up
%obj.getDynamicFieldCount() how many fields your script added to it

Objects made while an editor is open may not have names. The editor turns off name registration so that editing a screen does not clutter the global namespace, so if a lookup by name comes back empty and you have an editor open, use the id.

Tracing

trace(true) makes the engine print every function call as it happens — the name, the arguments it received, and what it returned. trace(false) turns it off.

It is loud. A single frame of a running game can produce hundreds of lines, so turn it on immediately before the thing you are investigating and off immediately after:

trace(true); MyHero.jump(); trace(false);

backtrace() prints how execution got to where it currently is, which is more useful from inside a script than from the console prompt.

Finding out what exists

The console can list its own API:

  • dumpConsoleFunctions() — every global function the engine exposes, with its arguments.
  • dumpConsoleClasses() — every class script can create, with its methods and fields.

Both produce a great deal of output, and both go to console.log where you can search them. This is the most reliable reference there is, because it is generated from the engine you are actually running rather than from documentation that may have drifted.

Remote access

Two features let something outside the engine connect to it. Both are compiled in and started at boot, and both are switched on from script by giving them a port.

A remote console:

telnetSetParameters( 4000, "writePassword", "readPassword" );

Anything that speaks telnet can then connect on that port and use the console as though it were typing into the box. Pass a port of 0 to stop listening. The third password grants read-only access, so someone can watch the log without being able to run anything.

A remote debugger:

dbgSetParameters( 4001, "password" );

This is a real script debugger — breakpoints, stepping, inspecting variables — but it speaks a protocol rather than presenting a user interface, so it needs a client at the other end. The IDE that provided one is no longer available, which is why the in-engine console remains what most people use. dbgIsConnected() and dbgDisconnect() manage the connection.

Both open a network port with a password of your choosing. Do not leave either enabled in a game you ship.

Where to go next

Clone this wiki locally