- 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. You will also 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, and GraphicsDevice for the game (i.e. graphics.GraphicsDevice or the device field if initialized)
Terminal.SetSkin has three overloads:
- SetSkin(TerminalThemeType)
- The TerminalThemeType sent is one of the ones discussed below (e.g. FIRE, SUNRISE, BLACK_ON_WHITE, etc.). This theme is used for both the basic background color, cursor width and color, and watch expression as well as the syntax color set.
- SetSkin(TerminalThemeType, TerminalThemeSHType)
- The TerminalThemeType is used as before although it is not used for syntax coloring. The TerminalThemeSHType represents the syntax color set the Terminal will use and can either be the same as the TerminalThemeType (e.g. FIRE, etc.), VS_DEFAULT (which uses Visual Studio's default color scheme), or VS_CURRENT (which uses your current Visual Studio settings). Documentation is given for every TerminalThemeSHType and will appear in intellisense.
- SetSkin(TerminalSkin)
-
This gives you the most control by allowing you to create your own TerminalSkin
object to send to the Terminal. There are 3 overloads to this:
- new TerminalSkin(TerminalThemeType)
- Creates a TerminalSkin using the basic settings and syntax colors from the given ThemeType. Can be customized from there before being sent to Terminal.SetSkin.
- new TerminalSkin(TerminalThemeType, TerminalThemeSHType)
- Creates a TerminalSkin using the basic settings from ThemeType and syntax colors from ThemeSHType. Can be customized from there before being sent to Terminal.SetSkin.
- new TerminalSkin(...)
- Accepts arguments that correspond to each basic and syntax color setting.
- 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 including a power operator (**)
[R] Arithmetic operator equals (+=, -=, /=, *=, %=, and **=)
[LR] Array indexing
[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
-
Alt+T to toggle the display of input as tokens
Ctrl+Backspace and Ctrl+Delete to delete words (Improved over previous versions)
Left and Right to navigate between characters
Ctrl+Left and Ctrl+Right to navigate between words (Improved over previous versions)
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)
Up/Down : Scroll through terminal history
Enter : Commit terminal statement
- Terminal Commands (not case sensitive)
-
- "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
- Terminal Constants
-
The following expressions are recognized as constants in the terminal.
- "#C": 299,792,458 (Speed of light)
- "#E": Shorthand for Math.E
- "#GAMMA": 0.5772156649 (Euler's constant)
- "#G": 9.8 (Gravity)
- "#GC": 6.673e-11 (Gravitational constant)
- "#H": 6.62606893e-34 (Planck's constant)
- "#PHI": (Math.sqrt(5)+1.0)/2 (Golden Ratio)
- "#PI": Shorthand for Math.PI
- 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