- Downloading
- You can download the latest .dll from the Download section.
- Adding to XNA Project
- Open a pre-existing or new XNA project in Visual Studio. In Solution Explorer, right click on 'References' (from the root list not the one in the Content directory). Choose 'Add Reference' and click on the 'Browse' tab. Browse to where you downloaded the .dll, select it, and hit Ok. NOTE: Starting with version 2.0, you'll need to be sure that the Antlr3.Runtime.dll is in the same directory as the referenced DebugTerminal.dll
- How to Setup in Code
-
Add a using statement for the "DebugTerminal" namespace in your main cs file. Then make
these additions:
- In method LoadContent:
-
Terminal.Init and Terminal.SetSkin need to be called.
Terminal.Init needs a reference to the game object (i.e. "this"), a SpriteBatch object, SpriteFont object, GraphicsDevice for the game (i.e. graphics.GraphicsDevice or the device field if initialized), and the width and height in pixels of the game screen.
Terminal.SetSkin needs the color scheme you will be using. This can be custom or you can use a preset theme using the TerminalThemeType enum. If making your own, there are several overloaded methods. For the ones with an array for the bgColor, the Color elements represent the vertex colors of the top left, top right, bottom right, and bottom left vertices respectively. NOTE: In version 2.0, SetSkin may accept either a TerminalThemeType or a TerminalSkin. To use a TerminalSkin as the parameter, create it as follows:TerminalSkin skin = TerminalSkin.CreateFromTheme(TerminalThemeType.FIRE); skin.FgColor = Color.Cyan; skin.CursorColor = Color.Cyan;
TerminalSkin.CreateFromTheme(...) is only necessary when you want to create a new skin from an existing TerminalThemeType. Also, the TerminalSkin object can be created from scratch usingTerminalSkin skin = new TerminalSkin(/* pass appropriate args */);
- In method Update:
-
Terminal.CheckOpen needs to be called.
It needs a member of the Keys enum that will control which key will open/close the terminal. It also needs the state of the keyboard (i.e. Keyboard.GetState()). It returns a bool value which is true if terminal is opened, false otherwise. This is useful for deciding whether keystrokes should be sent only to the terminal or recognized by the game. - In method Draw:
-
Terminal.CheckDraw needs to be called.
It accepts a bool which is true only if you are drawing any 3D models or vectors. This method uses the spritebatch object sent when Init was called to draw the text and because of this, 3D models/vectors drawn will not look right unless the graphics device is restored to a proper state. Passing a value of true takes care of this. It is important that spritebatch.Begin() is not called beforehand. Begin and End are called inside the method instead. This method call should probably be the last part of the Draw method to ensure the terminal shows up on top of any other objects.
- How to Use During Runtime
-
Press the key you chose to pass to Terminal.CheckOpen, then type in any normal expression
to retrieve a value, invoke a method, or perform an assignment. Press enter when
done with expression. Expressions can not span more than one line (not yet), and
can not define new types, fields, properties, or methods. You may only use what
is already defined in your code, although you may create new objects of already
defined types. You may also start your expression with a '$' and enter one of the
Terminal commands followed by a ':' and an expression (if needed). For a list of Terminal
commands and their purpose, see below. Multiple expressions can be nested similar
to a regular C# line of code.
- Expressions That are Allowed:
L = lhs expression in assignment, R = rhs expression in assignment or non-assignment expression -
[R] Arithmetic (New in v 2.0)
[LR] Array indexing (New in v 2.0)
[R] Casting (Can only cast primitive struct types or any class that implements IConvertible)
[R] Enums
[LR] Identifiers (fields or properties)
[R] Literals (numeric, char, string, and boolean). May also suffix any numeric literal with chars associated with C# types (i.e. "m" for decimal, "ul" for unsigned long, etc.)
[R] Methods (void or single return)
[R] New operator
[R] Object chains (e.g. player.Position.X)
[R] Types (for calling static fields, properties, and methods)
- Expressions That are Not Yet Allowed:
-
Anonymous Types/Functions
Array initialization
Collection initialization
Conditional logic (including ternary statements)
Generics
Lambda Functions
LINQ
Logic Operators (&, |, ^, &&, ||)
Out and Ref operators
Property indexers
This pointer
Typeof, Default, As, and Is operators
- Special Key Commands
-
Ctrl+Backspace and Ctrl+Delete to delete words
Left and Right to navigate between characters
Ctrl+Left and Ctrl+Right to navigate between words
Home to go to beginning of terminal text
End to go to end of terminal text
Escape and Ctrl+U clear the terminal along with Tilde
Ctrl+V to paste text from the clipboard (read the download page for v 2.0 under "UI Improvements" for more information)
- Terminal Commands (not case sensitive and ignores all space between letters)
-
- "Add Watch" or "AW":
-
Adds expression given to the watch list. Expressions in the watch list are re-evaluated
each frame and the result is displayed next to it. Each watch has an id that appears
as the first part of the line. Use this id for the delete watch command.
- Example:
-
$Add Watch: count
Will add the identifier count to the list of watch expressions and
retrieve and display its value each frame.
- "Delete Watch", "Del Watch", or "DW":
-
Deletes the watch expression with the given id.
- Example:
-
$Delete Watch: 0
Will delete watch expression with id = 0
- "Delete All Watches", "Del All Watches", or "DAW":
-
Deletes all current watch expressions. This doesn't need an expression.
- Example:
- $Delete All Watches:
- "Evaluate" or "E":
-
Can give terminal a string variable containing custom terminal statement to evaluate.
Useful for setting up testing expressions in multiple strings in code, then simply using
those variables in terminal
- Example:
-
$Evaluate: playerPosX
If, say, playerPosX = "Player.Position.X", this would first look up the value of playerPosX, then evaluate the string "Player.Position.X" as an expression.
- "Add Evaluate Watch" or "AEW":
-
Preforms 'Evaluate' terminal command on expression then adds the result to the list of
watch expressions
- Example:
-
$Add Evaluate Watch: playerPosX
Runs an 'Evaluate' command on playerPosX and stores the resulting string in list of watches as an expression.
- Terminal Themes
-

*The number on the top right of each is the opacity
- Expressions That are Allowed:
- Examples:
-
Given this code:
public class One {
public Two Two { get; set; }}
public One() {
Two = new Two();}
public class Two {
public Three Three { get; set; }}
public Two() {
Three = new Three();}
public byte Num() {
return 230;}
public class Three {
public byte TheValue { get { return 100; } }}
- Some Terminal expressions could be:
-
new Vector3((float)new One().Two.Num(), (float)new One().Two.Three.TheValue, 3.5f)
someIdentifier = new Color((byte)new Random().Next(255), new One().Two.Num(), 100) - Some Other possible expressions:
-
TerminalSkin skin = TerminalSkin.CreateFromTheme(TerminalThemeType.FIRE);
skin.FgColor = Color.Cyan;
skin.CursorColor = Color.Cyan;
Terminal.SetSkin(skin);
Foo(Bar(new String('X', 5)))
- More information:
-
More information can be found in my two slideshow presentations:
- Sample:
- You can download this Box sample project to try out XNA Debug Terminal