Gearset User Guide

Here's the place to learn how to use Gearset, since it's a developing/debugging tool it has being designed to be easy to grab. Keep reading to understand how to squeeze every drop out of it.

Download Gearset
(It's free!)

• Upgrade to Gearset Pro
• General info
• Get Support

Contents

• Installation
• Settings
• Inspector (updated)
• Finder (new)
• Bender (new)
• Logger
• Plotter
• Actions
• Overlaid Geometry
• Overlaid Data View
• Alerter
• Labeler
• Changelog

Note: all examples assume that you're using the GS.cs file included.

Installation

Installing Gearset in your project is pretty easy and it just takes a minute. To do it, just follow these steps:

• Download the Gearset binary from here.
• Include Gearset.dll as a reference in your XNA 4.0 project.
• Copy the included GS.cs file to your project, it provides you with quick access to Gearset's methods and properties while allowing you to completely remove Gearset when your game is ready to be shipped.
• In Visual Studio,
  • Right click on your project
  • Properties
  • Application
  • Target Framework. Make sure the Target Framework is set to ".NET Framework 4" instead of ".NET Framework 4 Client Profile".
• In Visual Studio,
  • Right click on your project
  • Properties
  • Build
  • Append ";USE_GEARSET" to Conditional Compilation Symbols
  When you want to remove gearset, simply remove this symbol.
• At the beginning of your Game.Initialize method, add this to start Gearset components:

      Gearset.GS.Initialize(this);
  

• In your program's Main method (usually located either in Program.cs or your main Game code file) add the [STAThread] attribute:

      [STAThread]
      static void Main(string[] args)
  

• Press F5 and run your game!
• Aditionally for 3D, or 2D scrolling games your camera matrices must be passed to Gearset in order to render overlays correctly. At the end of your Game.Update method add:

      Gearset.GS.SetMatrices(ref World, ref View, 
                  ref Projection, ref Transform2D);
  

• Note: This installation instructions are only valid for version 2.0.0 and later. Previous version contain their own installation instructions.

Settings

Gearset settings are modified in the inspector. The first item will always be "Gearset Settings" and it will show tweakable parameters of all Gearset components.

It provides ways to clear a Gearset component that contain persistent data (e.g. the labeler) as well as a quick place to enable/disable any component.

Inspector

Features

• Inspect and modify all public and private fields and property of any object in real-time. This is very similar to a Watch Window but without having to stop your game.
• Inspect all objects referenced by the inspected object and modify them also.
• Most of XNA types have special controls to manipulate them better. Including:
  • Primitive types (int, float, char, bool, etc)
  • Strings (multiline is supported)
  • Enums
  • Vector2 and Vector3, can be scaled and manipulated in the XY, YZ and XZ planes
  • Quaternions
  • Color
  • Texture2D including RenderTarget2D objects
  • Collections can be expanded. (Simple Enumerables are not yet supported)
• Isolate modified fields/properties to know what things were actually tweaked in the current session.
• Call any parameterless method on any object in The Inspector and inspect the result.
• Inject a value to a field/property every frame.
• If you have a lot of inspected object at any given time, you can search by name or Type name.
• Everything is done in a very speedy window.

Usage exaples

• To add an object to the Inspector:

  GS.Inspect("Some name", instance);

• To remove an object from the Inspector:

  GS.RemoveInspect("Some name", instance);

• To change how a field/property is shown in The Inspector add the following Attribute:

  [Inspector("The World's Gravity")]
  public Vector3 Gravity;

• To change how a method is shown in The methods window add the following Attribute:

  [InspectorMethod("Reset game state")]
  public void Reset() { /* ... */ }

• If you have a lot of inspected objects, you can use the search field to find the one you're looking

Remarks

The Inspector will always show the Gearset Settings object and your Game as its first items for easy access.

Also, it is important to note that the inspector will create a reference to the objects being inspected, this will prevent them from being Garbage Collected; you can always clear the inspector, or explicitly call RemoveInspect to remove these references if you ever need to.

Finder

Features

• Find your game objects (i.e. characters, enemies, sprites, etc) by typing its name or Type.
• Send any object to the inspector with a click.
• Customizable search function to make it fit your object model.
• The default search function will go through your Game's Component collection and match objects by its Type name or whatever its ToString method returns.

Usage exaples

• To set a custom search function

  GS.SetFinderSearchFunction(MySearchFunction);

  Here's a template for your search function that will match game components that contain all search terms, you can customize it and make it, for example, search a hierarchy of objects of some sort (that's what we do to make it work on our engine):

  private FinderResult MySearchFunction(String searchTerms)
  {
      FinderResult result = new FinderResult();
      String[] searchParams = searchTerms.Split(new char[] { ' ' },
          StringSplitOptions.RemoveEmptyEntries);
  
      // Ignore Case
      for (int i = 0; i < searchParams.Length; i++)
          searchParams[i] = searchParams[i].ToUpper();
  
      foreach (IGameComponent component in Game.Components)
      {
          bool matches = true;
          String typeName = component.GetType().ToString();
  
          // Check if the object matches all search terms.
          for (int i = 0; i < searchTerms.Length; i++)
          {
              if (!(component.ToString().ToUpper().Contains(searchTerms[i]) ||
                  typeName.ToUpper().Contains(searchTerms[i])))
              {
                  matches = false;
                  break;
              }
          }
          if (matches)
              result.Add(new ObjectDescription(component, typeName));
      }
      return result;
  }
  

Bender

Features

• Edit curves in real time.
• Save any curve back to disk, in the XML format to be used directly in the Content Pipeline.
• Assign curves to objects by dragging them to the Inspector window.
• Group curves together using the dot syntax in the name (E.g. "Sprite1.PosX").
• Drag a slider in the bottom of the editor and use this value to evaluate curves for testing/tweaking purposes.
• Intuitive interface.

Usage exaples

• To add a curve to Bender for editing, click the "Edit in Bender" button in the Inspector or use:

  GS.AddCurve("Group.Curve1", myCurve);

• To remove a Curve:

  GS.RemoveCurve(myCurve);

• To remove a Curve or group of curves:

  GS.RemoveCurveOrGroup("Group.Curve1");

Logger

Features

• Log interesting events from your code.
• Separate logged messages into streams so you know which component of your game generated what.
• Easily differentiate things that happened in the same or different frames.
• Save the streamed log to a file for later inspection. (A must-have for bug reporting).
• Remember which streams were enabled in the last session so the output is relevant to the current problem.
• Everything is done in a very speedy window.

Usage exaples

• To log a message into a stream:

  GS.Log("Stream name", "Some event");

• To log a message into the default stream (Pro tip: use streams as it will help you know where each message was generated):

  GS.Log("Something cool happened");

• To save the log to a file (showing a "Save as dialog"). This can also be done from the Logger window.

  GS.SaveLogToFile();

• To save the log to a file giving a filename:

  GS.SaveLogToFile("C:\BugReport04.log");

Plotter

Features

• Plot floats on the screen for easy visualization.
• Specify how many samples are going to be plotted (60 by default)
• Resize the plots for a more detailed view.
• Selectively chose which plots you need shown.
• Remember which plots were enabled in the last session so the output is relevant to the current problem.
• Everything is done in very speedy overlays on top of you game.

Usage exaples

• To add a sample to a plot (and create the plot if it doesn't exists):

  GS.Plot("SomePosition", Position.X);

• To set the amount of samples to show (60 by default), use this overload instead:

  GS.Plot("SomePosition", Position.X, 30);

Actions

Features

• Bind an Action delegate to a button on top of your game window.

Usage exaples

• To add an action button:

  GS.AddAction("Reset game",
     ()=>{MyGameInstance.Reset()});

Overlaid Geometry

Features

• Draw debugging geometry on top of your game to help you visualize what's going on.
  • Lines, both 2D and 3D
  • Vectors, both 2D and 3D
  • 3D Transforms (Matrices) as 3 orthogonal vectors
  • Bounding Boxes (Axis aligned, oriented are not yet supported)
  • Spheres
• Everything can be drawn persistent or single-frame:
  • Persistent: draw it once, and Gearset will keep drawing it in the next frames. You give it a name so you can later move it or delete it. This is useful when you have some data to draw but the data is not available on every frame.
  • Single-frame: You have to make the call every frame to keep the geometry on-screen. This is most appropriate for data that is available every frame since you don't have to come up with a name for the geometry and it will dissapear automatically when you stop drawing it.

Usage exaples

• To draw persistent geometry:

  GS.Show______("SomeGeometry", geometry)

  But substitute ______ with either:
  • Vector2
  • Vector3
  • Line
  • Transform
  • Sphere
  • Box
  And the provided geometry must be of the corresponding type.
• To draw single-frame geometry:

  GS.Show______Once(geometry)

  Use the same replace scheme as above. Note that you don't need to provide a name because the geometry will only be draw in the current frame, these methods must be called every frame (i.e. from Update or Draw) to be useful.

Remarks

You may be wondering why the methods are called "Show" instead of "Draw". This decision was taken for two reasons:

• These methods will not perform any draw calls by themselves; instead, Gearset components in charge of handling these calls will make batched draw calls when the frame ends.
• To state that special handling is being done with the geometry: persistent geometry data is being held for persistent rendering across frames.

Overlaid Data View

Features

• Show read-only data as text overlaid over your game.
• Expand and collapse the tree structure to show only relevant data.
• Filter the nodes by name to show only relevant data.

Usage exaples

• To add a node with relevant data to the Overlaid Data View (suppose we're on an AI class and want to show some AI properties):

  GS.Show("AI.IsSleeping", IsSleeping);
  GS.Show("AI.State", State);
  GS.Show("AI.WrongCount", WrongCount);

Alerter

Features

• Sometimes you just can't take the eyes from the game maybe because you're pursuing a bug that manifests visually, alerter will show you a big text on the middle of the screen whenever you need it.

Usage exaples

• To show an alert on the screen:

  GS.Alert("Somethin' bad");

Labeler

Features

• Show text labels on whatever positions in 2D or 3D space.

Usage exaples

• To show a label on the screen with a fixed text:

  GS.ShowLabel("A label on something", 
      something.Position);

• To show a label on the screen with a dynamic text:

  GS.ShowLabel("guy's position", guy.Position,
      o.Position.ToString());

Guide Changelog

Feb-15-2012

• Added Bender documentation. Inspector can now inspect private members.

Sep-13-2011

• Fixed an error in the Finder search function template. (Thanks to Luis Vieira for the report)

Sep-11-2011

• Fixed some typos.

Sep-10-2011

• Updated to reflect changes in v1.1.4270.27766: Added the Finder documentation, some minor updates in Inspector, Logger and Plotter.

Aug-05-2011

• Added the InternalsVisibleToAttribute requirement to the installation instructions. (Thanks to Luis Vieira for the report).