Overview

overview_rag Documentation
Contents | Index
Overview
Show All

Rag is a software application used to monitor and manipulate a secondary, Rage-based Application, typically a game or sample. It provides an interface to view TTY message spew and allows the user to view and alter game data via Widgets.

Send comments on this topic.
Copyright (c) 2003-2008 Rockstar San Diego. All rights reserved.


Menus

Menus
Topics
Show All
Topics
Topic | Description
File Menu |
Views Menu | The Views Menu contains menu items for creating Widget Views.
Windows Menu | Contains the following list of Output Windows, Application Windows, Bank Views, Find Views, and Favorites Views currently used by the application:
Plugins Menu | The Plugins Menu will contain all of the Plugins that were found and successfully loaded.
Help Menu |
Links
Topics


File Menu

File Menu
Menus
Show All
Menu Item | Description
Load Layout | Loads a layout file which contains, among other things, the position and size of the Main Window, as well as each Dockable Window inside it.
Load Shared Layout | Contains a list of layout files found in the shared layouts directory specified in the RAG Settings File. If no shared layouts directory is specified, this feature will be disabled. Clicking on any of these items will load the shared layouts file. When loaded, a local copy of the shared file is created in the user preferences directory to prevent unauthorized editting.
Save Layout | Saves the current layout.
Save Layout As... | Save the current layout with a new file name.
Recent Layouts | Contains a list of recently loaded layouts.
Preferences | See below.
Exit <Application> | Exits the Main Application.
Exit Rag | Exits the Main Application and the Rag tray application.

The Preferences menu item contains the following items on its drop-down menu:

Menu Item | Description
User Preferences Directory | Allows the user to view and change the default location where user preference and layout files are stored.
Dump Output in Real Time | When checked, a log file containing the text from the Output Window is created and continuously updated as the Application runs. This file is loaded in your User Preferences directory and named after the Application plus the IP Address (if -addr was specified on the command line. See Rag Command Line Options) and given the .txt extension. If performance is a factor, and real-time updates are not needed, check Dump Output on Exit.
Dump Output on Exit | When checked, the log file is created and saved only when Rag exits.
Append Timestamp to Output File Name | When checked, the name of the Output file will be changed to include a timestamp when Rag exits.
Zip Output on Exit | Zips up the output file when Rag is closed. Requires "zip.exe" in the same folder as rag.exe or in the folder above (which is the case if you are running Rag from the Perforce or Rage Tools Installation locations).
Suppress Assert/Crash/Quit Dialog on Exit | Oftentimes when something goes wrong with the game, such as hitting a breakpoint, and the game is terminated, Rag does not receive an appropriate quit message. Check this option to suppress the dialog that informs the user of this fact. Useful for automation.

A Note On Preferences Files

Layout files are named .raglayout.<Application Name>.<User Name>.xml.

Widget settings files are named .ragWidgets.<Application Name>.<User Name>.xml.

Group

Menus

Links
Menus


Views Menu

Views Menu
Topics | Menus
Show All

The Views Menu contains menu items for creating Widget Views.

Menu Item | Description
Disabled Widgets | See Disabled Widgets Dialog.
Add Widget View | Adds a Widget View.
Add Find View | Adds a Find View.
Add Favorites View | Adds a Favorites View.
Add Shared Favorites View | Contains a list of all shared favorites files found in the shared favorites directory specified in the RAG Settings File. Clicking on any of these items will load the shared favorites file. When loaded, a shared favorites view is locked to prevent unauthorized editing, Run Rag with the -admin command line argument to enable editing. See Rag Command Line Options.
Topics
Topic | Description
Disabled Widgets Dialog | Sometimes an Exception may occur when the game updates a Widget. When this happens, a dialog will appear giving the user the option to disable the Widget. After selecting 'Yes', the disabled Widget will appear on the Disabled Widgets Dialog. Highlight a Widget's name to display its path. Check or uncheck its Check Box as desired. Even after re-enabling the Widget, it will remain accessible via this dialog.
Group

Menus

Links
Topics, Menus


Disabled Widgets Dialog

Disabled Widgets Dialog
Views Menu
Show All

Sometimes an Exception may occur when the game updates a Widget. When this happens, a dialog will appear giving the user the option to disable the Widget.

After selecting 'Yes', the disabled Widget will appear on the Disabled Widgets Dialog.

Highlight a Widget's name to display its path. Check or uncheck its Check Box as desired. Even after re-enabling the Widget, it will remain accessible via this dialog.

Group

Views Menu

Links
Views Menu


Windows Menu

Windows Menu
Menus
Show All

Contains the following list of Output Windows, Application Windows, Bank Views, Find Views, and Favorites Views currently used by the application:

Window | Description
Output | Displays messages from all Output channels.
Display | Displays messages printed with Displayf().
Errors | Displays messages printed with Errorf() or prefixed with "Error:"
Warnings | Displays messages printed with Warningf() or prefixed with "Warning:".
Scripts | Displays messages printed with a prefix of "Script:".
<Custom> | In addition, all Custom Output Windows that have been created will appear at the end of this list.
<Application Window> | The display area of the application.
<All Views> | All Bank Views, Find Views, and Favorites Views.

Each window's drop-down menu item contains the following:

Menu Item | Description
Show | Shows the window and gives it focus.
Center | Centers the window over the Main Window.
Dock | If the window is floating, it returns to its last known docked position, if any.
Float | If the window is docked, it will float in its last known floating position or in its default floating position.

Custom Output Windows and all View Windows will also have the following drop-down menu items:

Menu Item | Description
Dispose when closed | When the window is closed, it is lost forever.
Hide when closed | When the window is closed, it is actually hidden.

In addition to these drop-down menu items, the following can be found in the Application Window's drop-down menu and its right-click context menu:

Menu Item | Description
Fill Window | When docked, the Display Area fills its Application Window. When floating, the window will expand to its maximum possible size.
Widscreen (16:9) | Locks the Display Area's aspect ratio at 16:9.
Standard (4:3) | Locks the Display Area's aspect ratio at 4:3.
PSP (480x272) | Locks the Display Area's aspect ratio at 480:272.
Game Resolution | Locks the Display Area's aspect ratio to match that of the game.
Group

Menus

Links
Menus


Plugins Menu

Plugins Menu
Topics | Menus
Show All

The Plugins Menu will contain all of the Plugins that were found and successfully loaded.

Menu Item | Description
Plugins... | See Plugins Dialog.
<Plugin> | Zero or more plugins will be listed. Some may be disabled. Click on an enabled Plugin to activate that plugin.

See Authoring Plugins.

Topics
Topic | Description
Plugins Dialog | The Loaded Plugins Dialog shows the user which Plugins were found. All items that are checked are currently loaded. Unchecking items and restarting Rag will cause that Plugin to be skipped and not loaded.
Group

Menus

Links
Topics, Menus


Plugins Dialog

Plugins Dialog
Plugins Menu
Show All

The Loaded Plugins Dialog shows the user which Plugins were found. All items that are checked are currently loaded. Unchecking items and restarting Rag will cause that Plugin to be skipped and not loaded.

Group

Plugins Menu

Links
Plugins Menu


Help Menu

Help Menu
Topics | Menus
Show All
Menu Item | Description
Help | Launches this help file.
Command Line... | See Command Line Dialog.
Throw Exception | Throws a test exception for Rag to catch. See Rag Crash Dialog. (Only enabled in Administrator Mode. See Rag Command Line Options.)
Submit Feedback... | Opens a form that allows the user to submit feedback, report bugs, request features, etc.
About | Displays a dialog with the Rag version number and the names of its developers.
Topics
Topic | Description
Command Line Dialog | This Dialog displays the command line that the Application was launched with. Check or uncheck "Arguments On Own Line" to adjust how it is displayed.
Rag Crash Dialog | Sometimes, Rag may crash or throw an unhandled exception unexpectedly and be forced to quit. When that happens, the user will see this dialog: It is important for the ongoing maintenance and improvement of the Rag application that the user make an attempt to describe what they were doing in order for the developers to track down and fix the bugs. Reporting the bug will ensure that this happens.
Submit Feedback Dialog | The Submit Feedback form allows the user to easily report bugs and request features. When the user sends feedback, it is emailed to Adam Dickinson, the primary developer of Rag, and the user receives a copy.
Group

Menus

Links
Topics, Menus


Command Line Dialog

Command Line Dialog
Help Menu
Show All

This Dialog displays the command line that the Application was launched with.

Check or uncheck "Arguments On Own Line" to adjust how it is displayed.

Group

Help Menu

Links
Help Menu


Rag Crash Dialog

Rag Crash Dialog
Help Menu
Show All

Sometimes, Rag may crash or throw an unhandled exception unexpectedly and be forced to quit. When that happens, the user will see this dialog:

It is important for the ongoing maintenance and improvement of the Rag application that the user make an attempt to describe what they were doing in order for the developers to track down and fix the bugs. Reporting the bug will ensure that this happens.

Group

Help Menu

Links
Help Menu


Submit Feedback Dialog

Submit Feedback Dialog
Help Menu
Show All

The Submit Feedback form allows the user to easily report bugs and request features. When the user sends feedback, it is emailed to Adam Dickinson, the primary developer of Rag, and the user receives a copy.

Group

Help Menu

Links
Help Menu


Windows

Windows
Topics
Show All
Topics
Topic | Description
Main Window | The Main Window hosts the many Views, Output and Application Windows of Rag. In addition, there is a status bar at the bottom of the Window.
Application Window | The Application Window is home to the Display Area of an Application. On a Win32 build, the Display Area is used to display the application itself. On other builds, it is gray as those applications display on the user's television or other monitor. In all cases, mouse input over the Display Area is transmitted to the game. These items can be found on the Application's Applications Menu menu item and on its right-click context menu located on the Application Window's title (its tab when docked or its title bar when floating):
Bank View Window | The Bank View is responsible for displaying the Widgets. By default, one is opened for you at startup, but new Windows can be created from the Widgets Menu. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Find View Window | Find Views are created from the Widgets Menu under each Application's menu item. It is used to search for Widgets that include a specific string anywhere in their full path name. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Favorites View Window | Favorites Views are created from the Widgets Menu under each Application's menu item. Widgets are added to a Favorites View via their right-click context menu on a Bank View Window or Find View Window . Removing Widgets is done from the same right-click context menu, but only from the Favorites View itself. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Output Windows | Output Windows house Text Boxes that display TTY messages received from the Application. Messages are parsed for colors or special prefixes and piped to certain windows. The messages can be colorized according to their type or displayed with the default Window Text color. Rag has a few default windows:
Links
Topics


Main Window

Main Window
Windows
Show All

The Main Window hosts the many Views, Output and Application Windows of Rag. In addition, there is a status bar at the bottom of the Window.

Framerate

Displays the Fames Per Second, Update time, Draw time, and GPU time of the Main Application.

Error

Currently unused. At one time it displayed the last error received from the Standard Error Output.

Group

Windows

Links
Windows


Application Window

Application Window
Windows
Show All

The Application Window is home to the Display Area of an Application. On a Win32 build, the Display Area is used to display the application itself. On other builds, it is gray as those applications display on the user's television or other monitor. In all cases, mouse input over the Display Area is transmitted to the game.

These items can be found on the Application's Applications Menu menu item and on its right-click context menu located on the Application Window's title (its tab when docked or its title bar when floating):

Menu Item | Description
Fill Window | When docked, the Display Area fills its Application Window. When floating, the window will expand to its maximum possible size.
HDTV (1280x720) | Sets the Display Area to 1280x720.
HDTV (1920x1080) | Sets the Display Area to 1920x1080.
EDTV (852x480) | Sets the Display Area to 852x480.
640 x 480 | Sets the Display Area to 640x480.
PSP (480x272) | Sets the Display Area to 480x272.
Game Resolution | Sets the Display Area to the game's resolution.
Maintain Aspect Ratio | When checked, the current aspect ratio of the Display Area is maintained as the window is resized.
Lock Resolution | When checked, the current size of the Display Area will not change as the window is resized.
Fit to Window | Expands the Display Area to fill the window at the current aspect ratio.
Group

Windows

Links
Windows


Bank View Window

Bank View Window
Windows
Show All

The Bank View is responsible for displaying the Widgets. By default, one is opened for you at startup, but new Windows can be created from the Widgets Menu.

When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:

Menu Item | Description
Dispose when closed | When the window is closed, it is lost forever.
Hide when closed | When the window is closed, it is actually hidden.

Floating view:

Bank Pane

The pane on the left contains a tree representation of the banks and the groups they contain. Selecting an item in the Tree displays the bank or group's Widgets in the Widget Pane.

The Bank Pane contains a menu with the following items

Menu Item | Description
Display | Menu for changing how the banks are displayed in the Bank Pane. This includes menu items for showing/hiding banks.

Right-clicking anywhere in the Bank Pane reveals the following menu items:

  • Show Hidden Bank: Contains a list of hidden banks that, can be individually shown.
  • Show All Banks: Shows all hidden banks.
  • Sort Banks: This option sorts the tree alphabetically.
  • Unsort Banks: This options returns the tree to its original order.
  • Hide/Show Left Pane: Controls the visibility of the Bank Pane.
  • Hide/Show Help Pane: Controls the visibility of the Help Pane.

Additionally, right-clicking on an item in the Bank Pane reveals the following menu items:

  • Add To Favorites View: Adds the selected item to a Favorites View.
  • Hide Bank: Hides the selected bank. (Only applicable when right-clicking on a bank)

Widget Pane

The pane on the top right is where the Widgets are displayed. The top always contains an XPander to be able to expand and collapse the list.

Right-clicking anywhere in the Widget Pane reveals the following menu items:

  • Sort All Widgets: This option sorts all of the Widgets alphabetically.
  • Unsort All Widgets: This option returns the Widget order to their original states.
  • Hide/Show Left Pane: Controls the visibility of the Bank Pane.
  • Hide/Show Help Pane: Controls the visibility of the Help Pane.

Additionally, the right-click context menu over each XPander can be used to Sort and Unsort each group individually.

Help Pane

This pane, located below the Widget Pane, displays the name and associated help message when the mouse is scrolled over a Widget.

Right-clicking anywhere in the Help Pane reveals the following menu items:

  • Hide/Show Left Pane: Controls the visibility of the Bank Pane.
  • Hide/Show Help Pane: Controls the visibility of the Help Pane.
Group

Windows

Links
Windows


Find View Window

Find View Window
Windows
Show All

Find Views are created from the Widgets Menu under each Application's menu item. It is used to search for Widgets that include a specific string anywhere in their full path name.

When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:

Menu Item | Description
Dispose when closed | When the window is closed, it is lost forever.
Hide when closed | When the window is closed, it is actually hidden.

Floating view:

Find Pane

This pane contains the search parameters. Enter text in the Find What Combo Box, or select text from previous searches.

Match case

Match the case of the text.

Match whole word

Match the whole word of the text to a whole word in a Widget's full path.

Use regular expressions

Enable this to support regular expression searches

Search in help description

Search for the specified text in the help descriptions as well.

Include groups

Include the full path name of Groups in the search.

Find

Click this button to execute the search. Alternately, you may press Enter in Find What's Combo Box.

Display Path

Check this to display the full path name above each Widget in the Results Pane.

Results Pane

This pane contains the results of the search. When Display Path is selected, the full path name is displayed above each Widget.

Help Pane

Displays help for each Widget just like on the Bank View Window.

Right-clicking anywhere in the Find View reveals the following menu items:

  • Hide/Show Left Pane: Controls the visibility of the Find Pane.
  • Hide/Show Help Pane: Controls the visibility of the Help Pane.

Right-clicking on a widget in the Find View reveals the following menu items:

  • Show In Bank View: Navigates to the selected widget in the Bank View.
Group

Windows

Links
Windows


Favorites View Window

Favorites View Window
Windows
Show All

Favorites Views are created from the Widgets Menu under each Application's menu item. Widgets are added to a Favorites View via their right-click context menu on a Bank View Window or Find View Window . Removing Widgets is done from the same right-click context menu, but only from the Favorites View itself.

When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:

Menu Item | Description
Dispose when closed | When the window is closed, it is lost forever.
Hide when closed | When the window is closed, it is actually hidden.

Floating view:

Settings Pane

View Name

Provides a name for the Favorites View which appears in the Window's title bar (when floating) and tab (when docked).

File

Below the View Name is an area to display the name of the Favorites File that is currently loaded, or "<no file>" when there isn't one loaded.

Load Favorites

Click this button to load a Favorites File.

Save Favorites

Click this button to save the current set of favorites. You will be prompted to save unsaved favorites when the Application Exits.

Save Favorites As

Click this button to be prompted for a location to save the current set of favorites to.

Allow Drag & Drop

Allows the user to alter the order of the Widgets. Currently unused.

Lock this view

Disables any Widgets from being added, removed, or moved.

Display Path

Check this to display the full path name above each widget in the Favorites Pane.

Favorites Pane

This pane contains the list of Widgets that have been added.

Help Pane

Displays help for each Widget just like on the Bank View Window.

Right-clicking anywhere in the Favorites View reveals the following menu items:

  • Hide/Show Left Pane: Controls the visibility of the Settings Pane.
  • Hide/Show Help Pane: Controls the visibility of the Help Pane.

Right-clicking on a widget in the Favorites View reveals the following menu items:

  • Show In Bank View: Navigates to the selected widget in the Bank View.
Group

Windows

Links
Windows


Output Windows

Output Windows
Windows
Show All

Output Windows house Text Boxes that display TTY messages received from the Application. Messages are parsed for colors or special prefixes and piped to certain windows. The messages can be colorized according to their type or displayed with the default Window Text color. Rag has a few default windows:

Name | Description
Output | Displays messages from all Output channels.
Display | Displays messages printed with Displayf().
Errors | Displays messages printed with Errorf() or prefixed with "Error:". These will appear red.
Warnings | Displays messages printed with Warningf() or prefixed with "Warning:". These will appear yellow.
Scripts | Displays messages printed with a prefix of "Script:". These will appear brown.

In addition, Custom Output Windows can be created by game code. For these windows that are docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals a drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:

Menu Item | Description
Dispose when closed | When the window is closed, it is lost forever.
Hide when closed | When the window is closed, it is actually hidden.

Floating view:

Right-click context menu

Each Output Window has a right-click context menu.

Menu Item | Description
Pause/Continue | Used to temporarily halt new messages from being printed to that Output Window.
Copy | Copies the selected text to the Clipboard.
Clear All | Clears the Output Window.
Multi-Color | Toggles the colorization of message types on or off. Sometimes, a large number of messages that require colorization can impact performance. At these times, the user should disable this option.
Email Output... | Opens a dialog which allows you to send the output text file as as an email attachment.
Find | Opens a dialog on which you can search the window's text. Best results can be gained by first Pausing the window's messages.

Additional Shortcuts
  • Select All (Ctrl + A)
  • Search Again Down (F3)
  • Search Again Up (Shift + F3)
  • Search Highlighted Down (Ctrl + F3)
  • Search Highlighted Up (Ctrl + Shift + F3)
Group

Windows

Links
Windows


Widgets

Widgets
Topics
Show All

Widgets are the basic, yet most powerful component of Rag. They represent a connection with the Application, allowing the user to view and manipulate certain pieces of data. Widgets can be found on a Bank View Window, Find View Window, and Favorites View Window.

Each Widget has a right-click context menu that is dynamically created. Certain Widget types have different items available to them.

Menu Item | Description | Widget Types | Window Types
Sort All Widgets | Sorts all of the Widgets in the Bank View alphabetically. | All | Bank View Window
Unsort All Widgets | Restores all of the Widgets to their original order. | All | Bank View Window
Sort Group | Sorts the Widgets (and all sub-groups) in the Group alphabetically. | Groups (represented by XPanders) | Bank View Window
Unsort Group | Returns the Widgets in the Group to their original order | Groups | Bank View Window
Show/Hide Left Pane | Toggles the window's Left Pane on or off. | All | All
Show/Hide Help Pane | Toggles the window's Help Pane on or off. | All | All
Save Widget | Marks a Widget and its value to be saved in the Widget settings file when the Main Application exits. See File Menu. | Select Widgets | All
Show Widget/Group In Its Own View | Displays the Widget in its own Window. | All | All
Copy Widget/Group Name to Clipboard | Copies the full path of the Widget to the Clipboard. | All | All
Add To Favorites View | When one or more Favorites View Windows have been created, adds the Widget to the specified Favorites View. | All | Bank View Window, Find View Window
Remove | Removes the Widget from the Favorites View. | All | Favorites View Window
Undo | On certain Widgets, this item performs an Undo operation. | Select Widgets | All

Many Widgets also support Ctrl+Z to execute the Undo operation.

Topics
Topic | Description
Angle Widget | The Angle Widget incorporates the functionality of the Slider Widget or Vector Widget to provide a method of editing an angle. This type of widget can be created in degrees, radians, fractions (where 0.0 is 0 degrees and 1.0 is 360 degrees), or using a Vector2 to represent the angle. In both flavors of the widget, the angle can be edited via the Slider or Vector Widget, or by clicking and dragging the mouse over the dial. The black line represents 0 degrees while the red line is the angle.
Button Widget | Clicking the button on a Button Widget activates the Application-side button.
Color Widget | A Color Widget is used to select a color. It can be an RGB or an ARGB color. Double-clicking the name of the color expands the Color Widget, providing RGB sliders and a gradient image that you can click to select a color. Single-clicking on the color swatch box opens a Color Picker Dialog as another method of selecting a color.
Combo Widget | Changing the selected item in a Combo Widget informs the Application of the new item. Additionally, the Application can change what items on on the list at any time.
Data Widget | A Data Widget represents a connection with the Application that is purely data. Special plug-ins can access the data associated with Data Widgets and send data back to the Application. Normally a Data Widget is not viewed, but a visual representation has been implemented for debugging purposes. Here, the user can view a textual representation of the current data. Subsequently, the Text Box may be editing and the data transmitted back to the Application when the "Send Data to Game" button is clicked.
List Widget | A List Widget represents a list of items with editable fields. When created by the Application, each row is assigned a unique identifier. In this example, this key is the memory address of the variable from the Name column. While all of the cells are editable, the displayed value does not change after an edit is made. Instead, the new value of the cell is sent to the Application, where it decides whether to accept or reject it. If the change is accepted, the Application tells Rag to change the value of that cell and then the display is updated. In the above example, only the Value column is editable.
Matrix Widget | A Matrix Widget is a complex visual representation of a matrix that allows editing of individual component values and has the ability to perform matrix operations. Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value. Left-click the name of the matrix (in this case, Matrix44) to access a drop-down menu with a large array of matrix operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:
Placeholder Widget | The Placeholder Widget is a special Widget that is inserted into Favorites Views (and Find Views after performing a search) to represent a Widget that was once added to a Favorites View but does not currently exist. A Placeholder Widget displays the full path name of the Widget, followed by "(not found)". At some point in the future, if the Application creates that Widget, all of it's Placeholder Widgets will be replaced with the actual one, and vice versa if a Widget is destroyed.
Separator Widget | The Separator Widget is merely used to provide a grouping without creating an expandable group.
Slider Widget | A Slider Widget provides a way to change a number value and keep it clamped between a specified minimum and maximum value. This Widget comes in two varieties: integer and floating point. Click and drag the name button to adjust the value, use the slider control, or use the NumericUpDown control. When typing a new value in the NumericUpDown, press Enter to commit it.
Text Widget | A Text Widget allows the user to view and change text. This Widget comes in 4 varieties: string, integer, floating point, and boolean. Change the text, then press Enter to commit the new value.
Title Widget | The Title Widget is a way to give a group of Widgets a name, but without creating an expandable group.
Toggle Widget | The Toggle Widget provides a check box.
Tree List Widget | The Tree List Widget is a more complex version of the List Widget. With a Tree List, the developer (and the user) have much more control over the structure, look, and behavior of each cell in the list. All rows are created hierarchically. The developer can specify certain types of Edit Controls for each column, or on a cell-by-cell basis, all from the Application code. In this example, m_treeListMyStruct is a structure, so its members are grouped under that node. The developer can decide how to represent vectors. The first vector is edited entirely in place, while the second vector can only be edited by its component sub-node rows. For all fields, the user can specify which are editable and which are not. Unlike the List Widget, this is determined when the developer creates the Tree List Widget (or later adds rows to it).
Vector Widget | A Vector Widget is a complex visual representation of a vector that allows editing of individual component values and has the ability to perform vector operations. Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value. Left-click the name of the vector (in this case, Vector4) to access a drop-down menu with a large array of vector operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:
Links
Topics


Angle Widget

Angle Widget
Widgets
Show All

The Angle Widget incorporates the functionality of the Slider Widget or Vector Widget to provide a method of editing an angle. This type of widget can be created in degrees, radians, fractions (where 0.0 is 0 degrees and 1.0 is 360 degrees), or using a Vector2 to represent the angle.

In both flavors of the widget, the angle can be edited via the Slider or Vector Widget, or by clicking and dragging the mouse over the dial. The black line represents 0 degrees while the red line is the angle.

Group

Widgets

Links
Widgets


Button Widget

Button Widget
Widgets
Show All

Clicking the button on a Button Widget activates the Application-side button.

Group

Widgets

Links
Widgets


Color Widget

Color Widget
Widgets
Show All

A Color Widget is used to select a color. It can be an RGB or an ARGB color.

Double-clicking the name of the color expands the Color Widget, providing RGB sliders and a gradient image that you can click to select a color.

Single-clicking on the color swatch box opens a Color Picker Dialog as another method of selecting a color.

Group

Widgets

Links
Widgets


Combo Widget

Combo Widget
Widgets
Show All

Changing the selected item in a Combo Widget informs the Application of the new item. Additionally, the Application can change what items on on the list at any time.

Group

Widgets

Links
Widgets


Data Widget

Data Widget
Widgets
Show All

A Data Widget represents a connection with the Application that is purely data. Special plug-ins can access the data associated with Data Widgets and send data back to the Application.

Normally a Data Widget is not viewed, but a visual representation has been implemented for debugging purposes.

Here, the user can view a textual representation of the current data. Subsequently, the Text Box may be editing and the data transmitted back to the Application when the "Send Data to Game" button is clicked.

Group

Widgets

Links
Widgets


List Widget

List Widget
Widgets
Show All

A List Widget represents a list of items with editable fields.

When created by the Application, each row is assigned a unique identifier. In this example, this key is the memory address of the variable from the Name column.

While all of the cells are editable, the displayed value does not change after an edit is made. Instead, the new value of the cell is sent to the Application, where it decides whether to accept or reject it. If the change is accepted, the Application tells Rag to change the value of that cell and then the display is updated. In the above example, only the Value column is editable.

Group

Widgets

Links
Widgets


Matrix Widget

Matrix Widget
Widgets
Show All

A Matrix Widget is a complex visual representation of a matrix that allows editing of individual component values and has the ability to perform matrix operations.

Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value.

Left-click the name of the matrix (in this case, Matrix44) to access a drop-down menu with a large array of matrix operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:

  • Basic Operations
  • Trigonometry
  • Advanced Operations

Basic Operations

This category includes Add, Subtract, Translate, and Scale.

Trigonometry

Included here are operations such as the Dot Product, Cross Product, Inverse and Rotations.

Advanced Operations

This category include more complex operations which typically involve a series of Basic and/or Trigonometry operations, but have been implemented for speed and efficiency in the Application.

Group

Widgets

Links
Widgets


Placeholder Widget

Placeholder Widget
Widgets
Show All

The Placeholder Widget is a special Widget that is inserted into Favorites Views (and Find Views after performing a search) to represent a Widget that was once added to a Favorites View but does not currently exist. A Placeholder Widget displays the full path name of the Widget, followed by "(not found)".

At some point in the future, if the Application creates that Widget, all of it's Placeholder Widgets will be replaced with the actual one, and vice versa if a Widget is destroyed.

Group

Widgets

Links
Widgets


Separator Widget

Separator Widget
Widgets
Show All

The Separator Widget is merely used to provide a grouping without creating an expandable group.

Group

Widgets

Links
Widgets


Slider Widget

Slider Widget
Widgets
Show All

A Slider Widget provides a way to change a number value and keep it clamped between a specified minimum and maximum value. This Widget comes in two varieties: integer and floating point.

Click and drag the name button to adjust the value, use the slider control, or use the NumericUpDown control. When typing a new value in the NumericUpDown, press Enter to commit it.

Group

Widgets

Links
Widgets


Text Widget

Text Widget
Widgets
Show All

A Text Widget allows the user to view and change text. This Widget comes in 4 varieties: string, integer, floating point, and boolean.

Change the text, then press Enter to commit the new value.

Group

Widgets

Links
Widgets


Title Widget

Title Widget
Widgets
Show All

The Title Widget is a way to give a group of Widgets a name, but without creating an expandable group.

Group

Widgets

Links
Widgets


Toggle Widget

Toggle Widget
Widgets
Show All

The Toggle Widget provides a check box.

Group

Widgets

Links
Widgets


Tree List Widget

Tree List Widget
Widgets
Show All

The Tree List Widget is a more complex version of the List Widget. With a Tree List, the developer (and the user) have much more control over the structure, look, and behavior of each cell in the list. All rows are created hierarchically. The developer can specify certain types of Edit Controls for each column, or on a cell-by-cell basis, all from the Application code.

In this example, m_treeListMyStruct is a structure, so its members are grouped under that node.

The developer can decide how to represent vectors. The first vector is edited entirely in place, while the second vector can only be edited by its component sub-node rows.

For all fields, the user can specify which are editable and which are not. Unlike the List Widget, this is determined when the developer creates the Tree List Widget (or later adds rows to it).

Group

Widgets

Links
Widgets


Vector Widget

Vector Widget
Widgets
Show All

A Vector Widget is a complex visual representation of a vector that allows editing of individual component values and has the ability to perform vector operations.

Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value.

Left-click the name of the vector (in this case, Vector4) to access a drop-down menu with a large array of vector operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:

  • Basic Operations
  • Trigonometry
  • Advanced Operations

Basic Operations

This category includes Add, Subtract, Translate, and Scale.

Trigonometry

Included here are operations such as the Dot Product, Cross Product, Normalize and Rotations.

Advanced Operations

This category include more complex operations which typically involve a series of Basic and/or Trigonometry operations, but have been implemented for speed and efficiency in the Application.

Group

Widgets

Links
Widgets


Command Line Options

Command Line Options
Topics
Show All
Topics
Topic | Description
Rag Command Line Options | A few command line parameters are support by Rag. When providing an argument, you must use '='.
Application Command Line Options | In order for your Rage-based Application to startup and communicate with Rag, you must specify one or more command line parameters when starting that Application.
Working With Multiple Instances of Rag | Currently, only one instance of Rag can run per IP address. To run multiple instances, multiple IP addresses are required. This can be accomplished by installing a second network adapter, or by setting up a second, virtual IP Address (talk to your local IT department about this). After the necessary setup, you run both Rag and the Main Applications with certain command line parameters. Main Application 1
Links
Topics


Rag Command Line Options

Rag Command Line Options
Command Line Options
Show All

A few command line parameters are support by Rag. When providing an argument, you must use '='.

Command Line Parameter | Arguments | Description
-addr | ipAddress | Specifies the IP Address through which Rag will communicate with the Application. Multiple network cards are required to run multiple instances of Rag.
-exit |  | Exits Rag. When an IP Address is specified, that particular instance of Rag is terminated.
-version | [version file] | Displays the Rag version number to the user. When a file is specified, that number is written to the file.
-admin | [true|false] | Enables certain Administrator privileges such as the Throw Exception menu item on the Help Menu and editing Shared Favorites files.
-pluginPath | path | The path where Rag should look for Plugins. By default, the Plugin Path is located in a sub-directory of Rag's location, named "Plugins".
-noquitmsg | [true|false] | Enables or disables the Assert/Crash/Quit Dialog that may appear when exiting Rag. Overrides the same setting on the File -> Preferences menu. See File Menu.
-multiColor* | [true\false] | For each Output Window or any Custom Output Window, you can override it's Multi-Color setting via the command line. To disable Multi-Color for the Errors Output Window, you would use "-multiColorErrors=false".
-processToKill | processId | The process ID of the secondary Rage-based Application to kill when Rag exits. Used in conjunction with -processToWatch.
-processToWatch | processId | The process ID of Rag. Used in conjunction with -processToKill.
-pipeTimeout | seconds | Specifies the amount (in seconds) of time to wait to connect RAG's pipes to the RAGE application before timing out. The default is 5 seconds. To disable the timeout (ie. wait forever), use "-pipeTimeout=0".
Group

Command Line Options

Links
Command Line Options


Application Command Line Options

Application Command Line Options
Command Line Options
Show All

In order for your Rage-based Application to startup and communicate with Rag, you must specify one or more command line parameters when starting that Application.

Command Line Parameter | Argument | Description
-rag |  | Required. Tells the Application to use Rag. Rag must already be running, however it is ok if you launch Rag after starting the Application. Heretofore, this is known as the Main Application.
-ragAddr | ipAddress | Connect with Rag on a specific IP address.
-ragPS3TargetAddr | ipAddress | Instruct Rag which PS3 Target to communicate with. Uses the name of the Target as it appears in the Target Manager. This is not required to run Rag with a PS3 Application, but it is needed to run multiple instances of Rag and PS3 Applications.
-oPrintCommandLine |  | Suppresses the command line TTY message that prints at the top of the Output Window.

Command Line Parameter | Argument | Description
-waitforpipe |  |
-bankpipename | name | The name of the communication channel to use for Bank Views.
-socketbaseport | port | The port to use.
-remotebank |  | Attempt to connect to remote bank server.
-setHwndMain | handle | The handle of the Application Window's Display Area so the Viewer may draw into it.
-ragviewer |  |
-appname | name | Visible name of the Viewer.
Group

Command Line Options

Links
Command Line Options


Working With Multiple Instances of Rag

Working With Multiple Instances of Rag
Command Line Options
Show All

Currently, only one instance of Rag can run per IP address. To run multiple instances, multiple IP addresses are required. This can be accomplished by installing a second network adapter, or by setting up a second, virtual IP Address (talk to your local IT department about this). After the necessary setup, you run both Rag and the Main Applications with certain command line parameters.

Main Application 1

c:\>rag.exe -addr=<ip address #1>
c:\>app.exe -rag -ragAddr=<ip address #1>

Main Application 2

c:\>rag.exe -addr=<ip address #2>
c:\>app.exe -rag -ragAddr=<ip address #2>

PS3

The Playstation3 is a special case. Because of limitations in the PS3 Target Manager SDK, it is not possible to retrieve the IP Address of the Development Kit. Instead it must be specified on the Main Application's command line. The PS3 Target's IP Address is often a name, rather than a number. Specify the name as it appears in your Target Manager for best results. It is case-sensitive.

Main Application 1

c:\>rag.exe -addr=<ip address #1>
c:\>app.exe -rag -ragAddr=<ip address #1> -ragPS3TargetAddr=<ps3 target 1>

Main Application 2

c:\>rag.exe -addr=<ip address #2>
c:\>app.exe -rag -ragAddr=<ip address #2> -ragPS3TargetAddr=<ps3 target 2>

See Rag Command Line Options and Application Command Line Options for a list of all Rag-related command line parameters.

Group

Command Line Options

Links
Command Line Options


Authoring Plugins

Authoring Plugins
Topics
Show All

The DLL RagCore contains all of the interfaces necessary to write a Rag Plugin. Additionally, you may incorporate the controls and classes from ragUI.dll, ragWidgets.dll and ragWidgetPage.dll.

Topics
Topic | Description
Basic Plugins | A basic plugin, with no associated windows, can be created by implementing the IViewPlugIn interface.
Window Plugins | A plug-in with its own window is created by using the classes in ragWidgetPage.dll. To initialize the custom plug-in and create the window, derive from the WidgetPagePlugIn class. It implements the IViewPlugIn interface as well as the IDockableViewManager interface from ragCore.dll. Next, derive from WidgetPage to create the window for your plug-in. This class implements the IDockableView interface from ragCore.dll, and also derives itself from UserControl. It's up to the designer of the custom plug-in to decide how many instances of the WidgetPage can be created.
Widget Plugins | A plug-in that defines a brand new Widget type is created by implementing the IWidgetPlugIn interface.
Sensor Plugins | Sensor plug-ins monitor the console development hardware. Currently, Rage has implemented the Xenon and PS3 Sensors. Win32 does not use a Sensor. A Sensor's role is to detect hardware faults, exceptions, reboots, disconnects, and the like so that Rag may act appropriately. Additionally, they can print messages to any of the Output Windows to inform the user of certain events such as hardware thread creation, status, and termination. Derive from the Sensor class in ragCore.dll and be sure to override the virtual functions there.
Links
Topics


Basic Plugins

Basic Plugins
Topics | Authoring Plugins
Show All

A basic plugin, with no associated windows, can be created by implementing the IViewPlugIn interface.

namespace ragCore
{
    public interface IViewPlugIn
    {
        string Name {get;}

        /// <summary>
        /// Initialize the custom plugin
        /// 1) Add your menu item(s) to PlugInHostData.m_PlugInToolStripMenu.DropDownItems (the Plugins menu) and/or to
        ///    PlugInHostData.m_MenuToolStrip.Items.
        /// 2) If your Plugin menu item(s) should be disabled for any reason, add an event handler to
        ///    PlugInHostData.m_PlugInToolStripMenu.DropDownOpenning.
        /// 3) Do not perform any widget bindings here because none will exist when the function is called.  Use
        ///    the PlugInHostData.m_MainBankManager.InitFinished event instead.
        /// 4) Load relevant data from DllInfo.PluginDataHash
        /// </summary>
        /// <param name="data"></param>
        void InitPlugIn(PlugInHostData data);

        /// <summary>
        /// Shutdown the custom plugin
        /// 1) Remove any menu item that were created in InitPlugIn
        /// 2) Remove any event handlers that were added.
        /// 3) Save relevant data to DllInfo.PluginDataHash
        /// </summary>
        void RemovePlugIn();
    }
}

The PlugInHostData class provides the items necessary to integrate your plug-in into the Rag UI.

namespace ragCore
{
    public class PlugInHostData
    {
        /// <summary>
        /// Main Rage Application.
        /// </summary>
        public IRageApplication MainRageApplication { get; }

        /// <summary>
        /// The list of all running applications, including the Main App.
        /// </summary>
        public IRageApplication[] RageApplications{ get; }

        /// <summary>
        /// The main View Manager
        /// </summary>
        public IDockableViewManager ViewManager{ get; }

        /// <summary>
        /// The "Plugins" menu item.
        /// </summary>
        public ToolStripMenuItem PlugInToolStripMenu{ get; }

        /// <summary>
        /// The main tool strip.
        /// </summary>
        public ToolStrip MenuToolStrip{ get; }

        /// <summary>
        /// Information about this plugin, including any saved data
        /// </summary>
        public DllInfo DllInfo{ get; }

        /// <summary>
        /// A string representing the current platform: "Win32", "Xbox360", "PlayStation3", "PlayStationPortable" or "Unknown"
        /// </summary>
        public string Platform{ get; }
    }
}

The IRageApplication interface allows the user to retrieve specific information about an Application.

namespace ragCore
{
    public interface IRageApplication
    {
        /// <summary>
        /// The display name of the Application.  Typically displayed as the Application Window's title.
        /// </summary>
        string VisibleName { get; }

        /// <summary>
        /// A unique identifier for this Application.
        /// </summary>
        string Guid { get; }

        /// <summary>
        /// The path of the Application.
        /// </summary>
        string ExePath { get; }

        /// <summary>
        /// The name of the Application
        /// </summary>
        string ExeName { get; }

        /// <summary>
        /// The arguments pass to the Application.
        /// </summary>
        string Args { get; }

        /// <summary>
        /// Whether the Application (one that is not the Main Application) should start when the Main Application starts.
        /// </summary>
        bool ShouldStart { set; }

        /// <summary>
        /// Whether the Application is running or not.
        /// </summary>
        bool IsStarted { get; }

        /// <summary>
        /// The IBankManager associated with the Application.
        /// </summary>
        IBankManager BankMgr { get; }

        /// <summary>
        /// Indicates whether any of the Pipes were connected at one time.
        /// </summary>
        bool WasConnected { get; }

        /// <summary>
        /// Indicates if any pipes has lost connection with its Application.
        /// </summary>
        bool PipesDisconnected { get; }

        /// <summary>
        /// The BankPipe through which the Application communicates.
        /// </summary>
        BankPipe BankPipe { get; }

        /// <summary>
        /// The TTY Output Pipe
        /// </summary>
        INamedPipe TheOutputPipe { get; }

        /// <summary>
        /// The Bank (Widget) Pipe.
        /// </summary>
        INamedPipe TheBankPipe { get; }

        /// <summary>
        /// Get or set the image in the Application Window's RenderWindow for this application.  Typically used for non-Win32 Applications.
        /// </summary>
        string RenderWindowImageFilename { get; set; }

        /// <summary>
        /// Retrieves a PipeID with an IP address and an appropriate port number based on the offset provided.
        /// Typically used by IViewPlugIns to connect to an Application through auxiliary ports.
        /// </summary>
        /// <param name="offset">The port offset desired.</param>
        /// <returns>A PipeID.</returns>
        PipeID GetRagPipeSocket( int offset );
    }
}

Example

One example of a plug-in that uses this interface is Quick Screenshot, located in //rage/dev/rage/base/tools/ragQuickScreenshot.

This plug-in adds a set of menu items to the Plugins Menu and associates itself with a few Widgets. When a menu item is clicked, the associated Widget is triggered, which in turns tells the game to take a screen shot or perform some other related operation.

Topics
Topic | Description
Quick Screenshot | Located on the Plugins Menu is a menu item called Screenshots.
Group

Authoring Plugins

Links
Topics, Authoring Plugins


Quick Screenshot

Quick Screenshot
Basic Plugins
Show All

Located on the Plugins Menu is a menu item called Screenshots.

Menu Item | Description
Take Screenshot | Takes a screen shot with the in-game screen shot utility.
Take Screenshot with Console | When available, takes a screen shot with the console's hardware utility.
Start Screenshots in Application Window | Begins taking screen shots at an interval and displaying them in the Application Window.
Stop Screenshots | Stops taking screen shots.
Group

Basic Plugins

Links
Basic Plugins


Window Plugins

Window Plugins
Topics | Authoring Plugins
Show All

A plug-in with its own window is created by using the classes in ragWidgetPage.dll.

To initialize the custom plug-in and create the window, derive from the WidgetPagePlugIn class. It implements the IViewPlugIn interface as well as the IDockableViewManager interface from ragCore.dll.

Next, derive from WidgetPage to create the window for your plug-in. This class implements the IDockableView interface from ragCore.dll, and also derives itself from UserControl.

It's up to the designer of the custom plug-in to decide how many instances of the WidgetPage can be created.

Example

//rage/dev/rage/base/tools/ragMultilineTextPlugin is an example of a this type of plug-in. It adds itself to the Plugins Menu. When that menu item is clicked, the Multi-line Text Window is displayed.

Topics
Topic | Description
Console Window Plugin | The Console Plugin provides a Command Prompt on which to execute Dos-like commands. Use the Load button to open a specially formatted file that contains definitions a list of commands, typically alias and bind commands. Alternatively, launch your game with -rag.Console.LoadCommandFile, providing a filename. At the prompt, use the Up and Down arrow keys to cycle through the history of commands.
Memory Tracker Window Plugin |
Multi-line Text Window Plugin | In the Widget Name text box, enter the full path name of the Text Widget and click the View button. The current value will appear in the window and can be edited freely.
Profiler Window Plugin | The Rag Profiler Plugin displays and manipulates the same data as the in-game profiler system. The Plugin provides more control than its in-game counterpart and you are able to view multiple pages at the same time (and the cost of system performance, unfortunately).
Group

Authoring Plugins

Links
Topics, Authoring Plugins


Console Window Plugin

Console Window Plugin
Window Plugins
Show All

The Console Plugin provides a Command Prompt on which to execute Dos-like commands.

Use the Load button to open a specially formatted file that contains definitions a list of commands, typically alias and bind commands. Alternatively, launch your game with -rag.Console.LoadCommandFile, providing a filename.

At the prompt, use the Up and Down arrow keys to cycle through the history of commands.

Group

Window Plugins

Links
Window Plugins


Memory Tracker Window Plugin

Memory Tracker Window Plugin
Topics | Window Plugins
Show All
Overview

The Memory Tracker is a Rag Plugin for the presentation of the state of memory usage at any given time. It is activated by adding -trackerrag to the command line of the game or sample.

Due to the enormous amount of data involved, this Plugin does not display information in real-time. Instead, certain points in time are tagged and can be viewed as Reports. A Report consists of every memory allocation that exists at that point in time since the beginning of the game. Additionally, deallocation information can only be tracked when Track Deallocations is enabled. See Top Bar to see how to change it.

It's important to note here that there are several items that are not getting tracked. These are the items that were created before the game-side memory tracker system was activated, including the tracker system itself.

Reports can be specified from the code with the RAGE_TRACK_REPORT, RAGE_TRACK_REPORT_FREES, RAGE_TRACK_REPORT_NAME, and RAGE_TRACK_REPORT_NAME_FREES macros, and they can be created by pressing any of the Generate Report buttons in the Plugin Window. To view a different report, simply select it from one of the many Report combo boxes and click Refresh. Similarly, many of the display options require the user to click the Refresh button after changing them. Again, this is due to the long amount of time it takes to examine the data in order to create a Report View.

In addition to a few items on the Top Bar, there are three tabs of information: Overview, Allocations, and Memory Layout. Each of these is outlined in the following sections.

Topics
Topic
Description
Top Bar

On the left, is the current status of the connection to the game, including the Ports it connected with.
Overview Tab
At the moment, the Overview Tab is the only tab that allows the user to compare Reports from two different moments in time. The total size of each line is displayed for both Reports, as well as the difference between them.

It contains a right-click context menu with Copy and Select All options, or the user can press Ctrl+C and Ctrl+A, respectively. Those can be used to copy the selected rows to the clipboard to past into a text file or email.

At the bottom is a status bar that shows basic information about what the report contains. These fields update when the Overview List is refreshed. Additionally, the Selected Size item will contain the total number of bytes for all highlighted rows.

Allocations Tab
By far the most complex and memory-intensive Report View, the Allocations Tab displays a Tree List view of each individual allocation. Please be aware that it is very easy to run out of system memory when viewing a Report on this Tab. You may be prompted to de-select Stacks, Data Types Memory Types, and/or change the Size Range to display a sub-set of the data within the bounds of system memory.

A right-click context menu exists over the Tree List that allows you to quickly collapse or expand all Stack Name nodes. Nodes that do not collapse are array nodes. For thoroughness, each item in an array has its own line in the Tree View. There is also a Copy menu item with Ctrl+C as its shortcut. No Select All exists due to memory restrictions, but Multi-Select can be enabled and the user can manually select what they want to copy. Be warned, that enabling Multi-Select may slow things down considerably and is not recommended.

Similar to the Overview Tab, a Status bar at the bottom of the window contains information pertinent to the current Report. Again, the Selected Size item will contain a total size of all of the item(s) selected. If a node is selected that contains sub-nodes, only the top node's size is added.

Memory Layout Tab
Unlike the other tabs, all of the options except for the Report Combo Box will update immediately after the option is changed. The Memory Layout Tab is useful for viewing where Allocations and blocks of Allocations are made and for seeing fragmented memory.

The Left Pane contains the view of memory and the Right Pane contains the color key. Holding the left mouse button and dragging the area of the Left Pane will allow you to see hidden areas of the memory view. Right-click and select Re-center to reset the view back to the top left.

Once again, the bottom of the window contains a list of Status items. These update according to the allocation that is underneath the mouse when it is hovering inside the Left Pane.

Performance Notes
The Memory Tracker is a complicated piece of software. It was written with speed in mind so it is a bit memory intensive, even on the game-side. However, the Memory Tracker will still affect the performance of your game.

Expect the startup of your game to take 3 to 4 times longer than usual. At times, the initial load may appear to have stopped. I believe this is due to thread priority and the speed at which the Tracker can process the network messages received from the game. This is unconfirmed, but opening the Memory Tracker Window and Generating or Refreshing a Report seems to help speed things along.

Once in the game, things should run pretty close to normal, with minor frame rate jitters during intense run-time loads.
Group

Window Plugins

Links
Topics, Window Plugins


Top Bar

Top Bar
Memory Tracker Window Plugin
Show All

On the left, is the current status of the connection to the game, including the Ports it connected with.

Progress Bar

Since refreshing a Report View takes a large amount time, this will indicate how far along the process is.

Generate Report (All) Button

Tags a new Report and Refreshes the View on all 3 tabs with the Report that was just tagged.

Main Options Drop Down Menu
Item | Description
Save Report Drop Down Menu | You can save any of the Reports that have been generated from here. Simply select it from Save Report's drop down menu. These reports can later be viewed in a text editor or passed to tracker.exe.
Show Errors Button | Unfortunately, errors still exist in the game-side code as far as tracking memory allocations goes. The user will be prompted when an inconsistency is detected and given an option on how to proceed. Every problem that occurs can be viewed on the Errors Window (not shown) that appears by clicking this button.
Track Deallocations Check Box | At times it may be useful to view the memory deallocations that occurred during a Report. Due to the large memory impact that tracking this information incurs, it must be turned on manually. When the state of this check box is changed, a new Report is generated. That way, a Report will always contain either all of it's deallocation information or none at all.

Refresh All Button

Refreshes all 3 tabs with their currently selected Report. If none is selected for a tab, the last Report that was tagged is used.

Group

Memory Tracker Window Plugin

Links
Memory Tracker Window Plugin


Overview Tab

Overview Tab
Memory Tracker Window Plugin
Show All

At the moment, the Overview Tab is the only tab that allows the user to compare Reports from two different moments in time. The total size of each line is displayed for both Reports, as well as the difference between them.

It contains a right-click context menu with Copy and Select All options, or the user can press Ctrl+C and Ctrl+A, respectively. Those can be used to copy the selected rows to the clipboard to past into a text file or email.

At the bottom is a status bar that shows basic information about what the report contains. These fields update when the Overview List is refreshed. Additionally, the Selected Size item will contain the total number of bytes for all highlighted rows.

Generate Report Button

Clicking this button will tag a new Report and Refresh the view with the new Report as the Left Report. If Left Report already contains a report, it is moved to the Right Report automatically.

Left and Right Report Combo Boxes

Select the more recent report in the Left Report Combo Box and the earlier report in the Right Report Combo Box and click Refresh. Report Names with an asterisk at the end indicate that the Report contains deallocation information.

Options Drop Drown Menu

This menu contains several filtering options to help the user choose what they want to display.

Item
Description
Show By Drop Down Menu
Contains 3 categories of items to display: Stack Name, Data Type and Memory Type.

  • Stack Names are specified by RAGE_TRACK, RAGE_TRACK_NAME, and RAGE_NEW_TRACK in the game code. These are typically used to denote blocks of memory allocation code pertaining to a specific event or subsystem of the game. Because the Stack Names are hierarchical, this particular Show By has a column for Inclusive size totals and Exclusive totals. Inclusive shows the totals for the current Stack Name and all Stacks underneath it. Exclusive shows only what was allocated at the level of that Stack.
  • Data Type shows you the total memory consumed by each data type in the game.
  • Memory Type (shown) displays the memory usage totals for each sysMemAllocator in use and the total memory consumption of the game.

Also contains 2 options that can be applied to any category. These items are only enabled if both the Left Report and Right Report match as far as if they did or did not track deallocation information:

  • Allocations: Displays what was allocated during the time of the Report.
  • Deallocations: Displays what was free'd during the time of the Report.

Stacks Drop Down Menu
There may be an overwhelming number of Stack Names created and sifting through a long list can be difficult. Only active when Show By is set to Stack Name, this option allows the user to select which Stack Names to display data for.
Datatypes Drop Down Menu
Similar to the Stacks Drop Down Menu, this option allows the user to choose which Datatypes to display when Show By is set to Data Type.
Show Empty Items Check Box
By default, this is unchecked so that items with 0 bytes are not displayed in the list.

Refresh Button

Active when the Left Report, Right Report, or one of the filtering Options has changed, this updates the contents of the Overview List for what has been selected. After the refresh, the information in the Status bar at the bottom of the window is updated.

Group

Memory Tracker Window Plugin

Links
Memory Tracker Window Plugin


Allocations Tab

Allocations Tab
Memory Tracker Window Plugin
Show All

By far the most complex and memory-intensive Report View, the Allocations Tab displays a Tree List view of each individual allocation. Please be aware that it is very easy to run out of system memory when viewing a Report on this Tab. You may be prompted to de-select Stacks, Data Types Memory Types, and/or change the Size Range to display a sub-set of the data within the bounds of system memory.

A right-click context menu exists over the Tree List that allows you to quickly collapse or expand all Stack Name nodes. Nodes that do not collapse are array nodes. For thoroughness, each item in an array has its own line in the Tree View. There is also a Copy menu item with Ctrl+C as its shortcut. No Select All exists due to memory restrictions, but Multi-Select can be enabled and the user can manually select what they want to copy. Be warned, that enabling Multi-Select may slow things down considerably and is not recommended.

Similar to the Overview Tab, a Status bar at the bottom of the window contains information pertinent to the current Report. Again, the Selected Size item will contain a total size of all of the item(s) selected. If a node is selected that contains sub-nodes, only the top node's size is added.

Generate Report Button

Functions just as it does on the Overview Tab.

Report Combo Box

Used to select the Report to view, similar to the Overview Tab's Left Report Combo Box.

Min and Max Size Text Boxes

Only Allocations whose size in bytes fits between the Min and Max size are displayed.

Options Drop Down Menu

Contains options that are very similar to the Overview Tab.

Item
Description
Group By Drop Down Menu
Two settings govern how the nodes are organized hierarchically.

  • Allocation Order displays each Allocation in the order it was made.
  • Stack Name groups all Allocations by the full path of their Stack Name regardless of when the item was allocated.

Also contains 2 options that can be applied to either of the above settings:

  • Allocations: Displays what was allocated during the time of the Report.
  • Deallocations: Displays what was free'd during the time of the Report.

Stacks Drop Down Menu
Behaves the same as the like-named Drop Down Menu on the Overview Tab.
Datatypes DropDown Menu
Also behaves like its Overview Tab counterpart of the same name.
Memory Types Drop Down Menu
View Allocations that were made with certain sysMemAllocators.
Multi-Select Combo Box
By default, this is unchecked. The TreeList control's performance suffers greatly with Multi-Select enabled. It is recommended that this option is only enabled when trying to select nodes for copying, and that it should be disabled immediately afterwards.

Refresh Button

Similar to the Refresh Button on the Overview Tab.

Group

Memory Tracker Window Plugin

Links
Memory Tracker Window Plugin


Memory Layout Tab

Memory Layout Tab
Memory Tracker Window Plugin
Show All

Unlike the other tabs, all of the options except for the Report Combo Box will update immediately after the option is changed. The Memory Layout Tab is useful for viewing where Allocations and blocks of Allocations are made and for seeing fragmented memory.

The Left Pane contains the view of memory and the Right Pane contains the color key. Holding the left mouse button and dragging the area of the Left Pane will allow you to see hidden areas of the memory view. Right-click and select Re-center to reset the view back to the top left.

Once again, the bottom of the window contains a list of Status items. These update according to the allocation that is underneath the mouse when it is hovering inside the Left Pane.

Generate Report Button

Just like the ones on the Overview Tab and Allocations Tab.

Report Combo Box

Select which Report to view, just like on the Overview Tab and Allocations Tab.

Refresh Button

Refreshes the view for the current Report.

Bytes / Pixel Combo Box

Select how many bytes each pixel in the Left Panel represents. Ranges from 4 to 1024 bytes.

Width / Address Range Combo Box

Specifies how many pixels across to display. The smaller the number, the taller the display area needed to see all of memory. Conversely, the larger the number the wider the Left Pane will need to be to see everything. Ranges from 32 to 1024 pixels.

Colorize By Combo Box

To help differentiate different areas of the view, things are colorized by Stack Name, the Full Stack Path, Allocation Size, or Data Type. There is an upper limit to the colors provided, and when that occurs, the items are truncated or consolidated into one color. For example, when we run out of colors for Colorize By Data Type, each of the native types (char, int, etc.) receives a color, while all Structs get one color and all Classes get another.

Size Scale Combo Box

When Colorizing by Allocation Size, you can select the granularity of the colorization, ranging from Coarse to Very Fine.

Group

Memory Tracker Window Plugin

Links
Memory Tracker Window Plugin


Performance Notes

Performance Notes
Memory Tracker Window Plugin
Show All

The Memory Tracker is a complicated piece of software. It was written with speed in mind so it is a bit memory intensive, even on the game-side. However, the Memory Tracker will still affect the performance of your game.

Expect the startup of your game to take 3 to 4 times longer than usual. At times, the initial load may appear to have stopped. I believe this is due to thread priority and the speed at which the Tracker can process the network messages received from the game. This is unconfirmed, but opening the Memory Tracker Window and Generating or Refreshing a Report seems to help speed things along.

Once in the game, things should run pretty close to normal, with minor frame rate jitters during intense run-time loads.

Group

Memory Tracker Window Plugin

Links
Memory Tracker Window Plugin


Multi-line Text Window Plugin

Multi-line Text Window Plugin
Window Plugins
Show All

In the Widget Name text box, enter the full path name of the Text Widget and click the View button. The current value will appear in the window and can be edited freely.

Group

Window Plugins

Links
Window Plugins


Profiler Window Plugin

Profiler Window Plugin
Window Plugins
Show All

The Rag Profiler Plugin displays and manipulates the same data as the in-game profiler system. The Plugin provides more control than its in-game counterpart and you are able to view multiple pages at the same time (and the cost of system performance, unfortunately).

Top Toolbar

Use the Combo Box to select which Page to view. Use the Options Menu to change how the stats are viewed.

Menu Item | Description
Next Page | View the next Page in the list.
Previous Page | View the previous Page in the list.
Show Time Type | Frame Time, Average Time, Peak Time, Frame Calls Average Calls, Peak Calls
Time Display Mode | Elapsed Time, Counter0, Counter1
Show Value Type | Current, Average, Peak, Value Default
Auto Scale | When enabled, the minimum and maximum values will always be in view.
Scale Up | Zooms out, disabling Auto Scale.
Scale Down | Zooms in, disabling Auto Scale.
Scroll Up | Scrolls the view up, disabling Auto Scale.
Scroll Down | Scrolls the view down, disabling Auto Scale.

EKG Pane

The EKG Pane displays a visual representation of the current and recent values of the stats being profiled in the Page. Use the buttons and check box on the right side to control the view just like on the Options Menu.

Color Key Pane

The Color Key Pane displays the current value for each profiled stat according to the display settings from the Options menu. Use the check box next to each item to toggle it on and off.

Group

Window Plugins

Links
Window Plugins


Widget Plugins

Widget Plugins
Topics | Authoring Plugins
Show All

A plug-in that defines a brand new Widget type is created by implementing the IWidgetPlugIn interface.

    public interface IWidgetPlugIn
    {
        void AddStaticHandlers();
        void RemoveStaticHandlers();
    }

Open the //rage/dev/rage/base/tools/ragWidgets project to see how Widgets and WidgetVisibles are written.

In the Application code, the equivalent Widget must be implemented and registered with the Bank system via bkRemotePacket::AddType(...). This code will be responsible for receiving messages from Rag that alter the actual values associated with the Widget.

Example

//rage/dev/rage/base/tools/ragEventEditor

Topics
Topic | Description
Color Gradient Editor Widget | The Color Gradient Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times. Requires \\rage\dev\rage\suite\src\rmptfx See also Keyframe Editor Widget.
Event Editor Widget | Requires \\rage\dev\rage\suite\src\event
Input Widget | Provides the ability to simulate input from an Xbox 360 or PS3 controller. Useful for running a game remotely. Click the images of a button to activate it. Shift+Click a button to toggle it on. For the analog sticks, click and drag in the appropriate direction. When the Send Inputs button is toggled, all user input is send to the game. Press the Clear button to unpress all held buttons. Requires \\rage\dev\rage\base\src\input
Keyframe Editor Widget | The Keyframe Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times. Requires \\rage\dev\rage\suite\src\rmptfx See also Color Gradient Editor Widget.
Script Debugger Widget | Scripts that are run by the Application can be debugged with a Script Debugger Widget. This Widget displays a striped-down, read-only version of the Script Editor. Requires \\rage\dev\rage\script\src\scriptgui A Script Debugger Bank is created for each running script. The Editor portion contains most of the functionality that is important to the user. It contains a set of ToolStrips and an Editor window that comes straight from the Script Editor, albeit in read-only mode. Here the user can view the location of the current program counter, toggle breakpoints, pause a script, and start it up again. In the box that says "Script Editor:", a right-click context menu provides the standard Widget options such as "Hide/Show Help Pane" and "Show Widget in its Own View". In addition to several useful ToolStrip buttons such as Open, Print, Copy, Find, along with Bookmark and Outlining buttons, there is a special Debugger ToolStrip. Debugger ToolStrip
VCR Widget | Provides a compact set of playback controls. It has two modes:
Group

Authoring Plugins

Links
Topics, Authoring Plugins


Color Gradient Editor Widget

Color Gradient Editor Widget
Widget Plugins
Show All

The Color Gradient Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times.

Requires \\rage\dev\rage\suite\src\rmptfx

See also Keyframe Editor Widget.

Group

Widget Plugins

Links
Widget Plugins


Event Editor Widget

Event Editor Widget
Widget Plugins
Show All

Requires \\rage\dev\rage\suite\src\event

Group

Widget Plugins

Links
Widget Plugins


Input Widget

Input Widget
Widget Plugins
Show All

Provides the ability to simulate input from an Xbox 360 or PS3 controller. Useful for running a game remotely.

Click the images of a button to activate it. Shift+Click a button to toggle it on. For the analog sticks, click and drag in the appropriate direction.

When the Send Inputs button is toggled, all user input is send to the game.

Press the Clear button to unpress all held buttons.

Requires \\rage\dev\rage\base\src\input

Group

Widget Plugins

Links
Widget Plugins


Keyframe Editor Widget

Keyframe Editor Widget
Widget Plugins
Show All

The Keyframe Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times.

Requires \\rage\dev\rage\suite\src\rmptfx

See also Color Gradient Editor Widget.

Group

Widget Plugins

Links
Widget Plugins


Script Debugger Widget

Script Debugger Widget
Widget Plugins
Show All

Scripts that are run by the Application can be debugged with a Script Debugger Widget. This Widget displays a striped-down, read-only version of the Script Editor.

Requires \\rage\dev\rage\script\src\scriptgui

A Script Debugger Bank is created for each running script. The Editor portion contains most of the functionality that is important to the user. It contains a set of ToolStrips and an Editor window that comes straight from the Script Editor, albeit in read-only mode. Here the user can view the location of the current program counter, toggle breakpoints, pause a script, and start it up again.

In the box that says "Script Editor:", a right-click context menu provides the standard Widget options such as "Hide/Show Help Pane" and "Show Widget in its Own View".

In addition to several useful ToolStrip buttons such as Open, Print, Copy, Find, along with Bookmark and Outlining buttons, there is a special Debugger ToolStrip.

Debugger ToolStrip

  • Toggle Breakpoint (F9)
  • Toggle Breakpoint (Stops Game) (Ctrl + F9)
  • Toggle Breakpoint All Threads (Shift + F9)
  • Toggle Breakpoint All Threads (Stops Game (Ctrl + Shift + F9)
  • Continue (F5)
  • Pause (F12)
  • Step Into (F11)
  • Step Over (F10)
  • Step Out (Shift + F11)
  • Options Dropdown Menu:
    • Show Line Numbers
    • Highlight Enums (currently non-functional)
    • Highlight QuickInfo Popups
    • Start Automatic Outlining
    • Start Manual Outlining
    • Stop Outlining
    • Change Includes

The Change Includes menu item will launch a dialog where the user can view and change the Include File and/or Include Path. This is especially useful if the last project the user had open in the Script Editor is not the same project that the current script is a part of. After changing one of the Includes, the current Script Debugger will be refreshed to reflect the changes. All other Debuggers will need to be refreshed manually by clicking the Refresh Intellisense button. Any new Debuggers will assume the current settings.

Other Features

  • Breakpoints can also be toggled by clicking the mouse in the left-hand margin of the document.
  • Ctrl+F will bring up the Find/Replace dialog box (with Replace functionality disabled).
  • Ctrl+G will bring up the Go To Line dialog box.
  • Alt+G will attempt to find the definition of a keyword, or open a USING file.
Group

Widget Plugins

Links
Widget Plugins


VCR Widget

VCR Widget
Widget Plugins
Show All

Provides a compact set of playback controls. It has two modes:

VCR

  1. Rewind
  2. Go To Previous
  3. Play Backwards
  4. Pause
  5. Play Forwards
  6. Go To Next
  7. Fast Forward

Animation

  1. Go To Start
  2. Step Backward
  3. Play Backwards
  4. Pause
  5. Play Forwards
  6. Step Forward
  7. Go To End

Requires \\rage\dev\rage\base\src\cranimation

Group

Widget Plugins

Links
Widget Plugins


Sensor Plugins

Sensor Plugins
Authoring Plugins
Show All

Sensor plug-ins monitor the console development hardware. Currently, Rage has implemented the Xenon and PS3 Sensors. Win32 does not use a Sensor.

A Sensor's role is to detect hardware faults, exceptions, reboots, disconnects, and the like so that Rag may act appropriately. Additionally, they can print messages to any of the Output Windows to inform the user of certain events such as hardware thread creation, status, and termination.

Derive from the Sensor class in ragCore.dll and be sure to override the virtual functions there.

Example

//rage/dev/rage/base/tools/ragSensors

Group

Authoring Plugins

Links
Authoring Plugins


Settings File

Settings File
Show All

The RAG settings file contains various project settings for RAG. The file is named "ragSettings.xml" and should be located in the same directory as the RAG executable. It is an XML based file that has the following format:

<?xml version="1.0" encoding="utf-8"?>
<RagSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <SettingName1>Value1</SettingName1>
  <SettingName2>Value2</SettingName2>
  <SettingName3>Value3</SettingName3>
  ...
</RagSettings>

The following table contains a list of currently supported RAG settings:

Setting Name | Description
SharedLayoutsDir | The directory that contains shared layout files.
SharedFavoritesDir | The directory that contains shared favorites files.


Topics

Topics
Basic Plugins
Topics
Topic | Description
Quick Screenshot | Located on the Plugins Menu is a menu item called Screenshots.


Topics

Topics
Authoring Plugins
Topics
Topic | Description
Basic Plugins | A basic plugin, with no associated windows, can be created by implementing the IViewPlugIn interface.
Window Plugins | A plug-in with its own window is created by using the classes in ragWidgetPage.dll. To initialize the custom plug-in and create the window, derive from the WidgetPagePlugIn class. It implements the IViewPlugIn interface as well as the IDockableViewManager interface from ragCore.dll. Next, derive from WidgetPage to create the window for your plug-in. This class implements the IDockableView interface from ragCore.dll, and also derives itself from UserControl. It's up to the designer of the custom plug-in to decide how many instances of the WidgetPage can be created.
Widget Plugins | A plug-in that defines a brand new Widget type is created by implementing the IWidgetPlugIn interface.
Sensor Plugins | Sensor plug-ins monitor the console development hardware. Currently, Rage has implemented the Xenon and PS3 Sensors. Win32 does not use a Sensor. A Sensor's role is to detect hardware faults, exceptions, reboots, disconnects, and the like so that Rag may act appropriately. Additionally, they can print messages to any of the Output Windows to inform the user of certain events such as hardware thread creation, status, and termination. Derive from the Sensor class in ragCore.dll and be sure to override the virtual functions there.


Topics

Topics
Widget Plugins
Topics
Topic | Description
Color Gradient Editor Widget | The Color Gradient Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times. Requires \\rage\dev\rage\suite\src\rmptfx See also Keyframe Editor Widget.
Event Editor Widget | Requires \\rage\dev\rage\suite\src\event
Input Widget | Provides the ability to simulate input from an Xbox 360 or PS3 controller. Useful for running a game remotely. Click the images of a button to activate it. Shift+Click a button to toggle it on. For the analog sticks, click and drag in the appropriate direction. When the Send Inputs button is toggled, all user input is send to the game. Press the Clear button to unpress all held buttons. Requires \\rage\dev\rage\base\src\input
Keyframe Editor Widget | The Keyframe Editor Widget was created for the Rag Particle Editor Window Plugin, which was a Window Plugin. The Particle Editor has been re-written as a separate application so the Particle Editor Window Plugin is obsolete. At some point in the future, this Widget may be moved into the ragCore.dll and made available at all times. Requires \\rage\dev\rage\suite\src\rmptfx See also Color Gradient Editor Widget.
Script Debugger Widget | Scripts that are run by the Application can be debugged with a Script Debugger Widget. This Widget displays a striped-down, read-only version of the Script Editor. Requires \\rage\dev\rage\script\src\scriptgui A Script Debugger Bank is created for each running script. The Editor portion contains most of the functionality that is important to the user. It contains a set of ToolStrips and an Editor window that comes straight from the Script Editor, albeit in read-only mode. Here the user can view the location of the current program counter, toggle breakpoints, pause a script, and start it up again. In the box that says "Script Editor:", a right-click context menu provides the standard Widget options such as "Hide/Show Help Pane" and "Show Widget in its Own View". In addition to several useful ToolStrip buttons such as Open, Print, Copy, Find, along with Bookmark and Outlining buttons, there is a special Debugger ToolStrip. Debugger ToolStrip
VCR Widget | Provides a compact set of playback controls. It has two modes:


Topics

Topics
Window Plugins
Topics
Topic | Description
Console Window Plugin | The Console Plugin provides a Command Prompt on which to execute Dos-like commands. Use the Load button to open a specially formatted file that contains definitions a list of commands, typically alias and bind commands. Alternatively, launch your game with -rag.Console.LoadCommandFile, providing a filename. At the prompt, use the Up and Down arrow keys to cycle through the history of commands.
Memory Tracker Window Plugin |
Multi-line Text Window Plugin | In the Widget Name text box, enter the full path name of the Text Widget and click the View button. The current value will appear in the window and can be edited freely.
Profiler Window Plugin | The Rag Profiler Plugin displays and manipulates the same data as the in-game profiler system. The Plugin provides more control than its in-game counterpart and you are able to view multiple pages at the same time (and the cost of system performance, unfortunately).


Topics

Topics
Command Line Options
Topics
Topic | Description
Rag Command Line Options | A few command line parameters are support by Rag. When providing an argument, you must use '='.
Application Command Line Options | In order for your Rage-based Application to startup and communicate with Rag, you must specify one or more command line parameters when starting that Application.
Working With Multiple Instances of Rag | Currently, only one instance of Rag can run per IP address. To run multiple instances, multiple IP addresses are required. This can be accomplished by installing a second network adapter, or by setting up a second, virtual IP Address (talk to your local IT department about this). After the necessary setup, you run both Rag and the Main Applications with certain command line parameters. Main Application 1


Topics

Topics
Help Menu
Topics
Topic | Description
Command Line Dialog | This Dialog displays the command line that the Application was launched with. Check or uncheck "Arguments On Own Line" to adjust how it is displayed.
Rag Crash Dialog | Sometimes, Rag may crash or throw an unhandled exception unexpectedly and be forced to quit. When that happens, the user will see this dialog: It is important for the ongoing maintenance and improvement of the Rag application that the user make an attempt to describe what they were doing in order for the developers to track down and fix the bugs. Reporting the bug will ensure that this happens.
Submit Feedback Dialog | The Submit Feedback form allows the user to easily report bugs and request features. When the user sends feedback, it is emailed to Adam Dickinson, the primary developer of Rag, and the user receives a copy.


Topics

Topics
Memory Tracker Window Plugin
Topics
Topic
Description
Top Bar

On the left, is the current status of the connection to the game, including the Ports it connected with.
Overview Tab
At the moment, the Overview Tab is the only tab that allows the user to compare Reports from two different moments in time. The total size of each line is displayed for both Reports, as well as the difference between them.

It contains a right-click context menu with Copy and Select All options, or the user can press Ctrl+C and Ctrl+A, respectively. Those can be used to copy the selected rows to the clipboard to past into a text file or email.

At the bottom is a status bar that shows basic information about what the report contains. These fields update when the Overview List is refreshed. Additionally, the Selected Size item will contain the total number of bytes for all highlighted rows.

Allocations Tab
By far the most complex and memory-intensive Report View, the Allocations Tab displays a Tree List view of each individual allocation. Please be aware that it is very easy to run out of system memory when viewing a Report on this Tab. You may be prompted to de-select Stacks, Data Types Memory Types, and/or change the Size Range to display a sub-set of the data within the bounds of system memory.

A right-click context menu exists over the Tree List that allows you to quickly collapse or expand all Stack Name nodes. Nodes that do not collapse are array nodes. For thoroughness, each item in an array has its own line in the Tree View. There is also a Copy menu item with Ctrl+C as its shortcut. No Select All exists due to memory restrictions, but Multi-Select can be enabled and the user can manually select what they want to copy. Be warned, that enabling Multi-Select may slow things down considerably and is not recommended.

Similar to the Overview Tab, a Status bar at the bottom of the window contains information pertinent to the current Report. Again, the Selected Size item will contain a total size of all of the item(s) selected. If a node is selected that contains sub-nodes, only the top node's size is added.

Memory Layout Tab
Unlike the other tabs, all of the options except for the Report Combo Box will update immediately after the option is changed. The Memory Layout Tab is useful for viewing where Allocations and blocks of Allocations are made and for seeing fragmented memory.

The Left Pane contains the view of memory and the Right Pane contains the color key. Holding the left mouse button and dragging the area of the Left Pane will allow you to see hidden areas of the memory view. Right-click and select Re-center to reset the view back to the top left.

Once again, the bottom of the window contains a list of Status items. These update according to the allocation that is underneath the mouse when it is hovering inside the Left Pane.

Performance Notes
The Memory Tracker is a complicated piece of software. It was written with speed in mind so it is a bit memory intensive, even on the game-side. However, the Memory Tracker will still affect the performance of your game.

Expect the startup of your game to take 3 to 4 times longer than usual. At times, the initial load may appear to have stopped. I believe this is due to thread priority and the speed at which the Tracker can process the network messages received from the game. This is unconfirmed, but opening the Memory Tracker Window and Generating or Refreshing a Report seems to help speed things along.

Once in the game, things should run pretty close to normal, with minor frame rate jitters during intense run-time loads.


Topics

Topics
Menus
Topics
Topic | Description
File Menu |
Views Menu | The Views Menu contains menu items for creating Widget Views.
Windows Menu | Contains the following list of Output Windows, Application Windows, Bank Views, Find Views, and Favorites Views currently used by the application:
Plugins Menu | The Plugins Menu will contain all of the Plugins that were found and successfully loaded.
Help Menu |


Topics

Topics
Plugins Menu
Topics
Topic | Description
Plugins Dialog | The Loaded Plugins Dialog shows the user which Plugins were found. All items that are checked are currently loaded. Unchecking items and restarting Rag will cause that Plugin to be skipped and not loaded.


Topics

Topics
Views Menu
Topics
Topic | Description
Disabled Widgets Dialog | Sometimes an Exception may occur when the game updates a Widget. When this happens, a dialog will appear giving the user the option to disable the Widget. After selecting 'Yes', the disabled Widget will appear on the Disabled Widgets Dialog. Highlight a Widget's name to display its path. Check or uncheck its Check Box as desired. Even after re-enabling the Widget, it will remain accessible via this dialog.


Topics

Topics
Widgets
Topics
Topic | Description
Angle Widget | The Angle Widget incorporates the functionality of the Slider Widget or Vector Widget to provide a method of editing an angle. This type of widget can be created in degrees, radians, fractions (where 0.0 is 0 degrees and 1.0 is 360 degrees), or using a Vector2 to represent the angle. In both flavors of the widget, the angle can be edited via the Slider or Vector Widget, or by clicking and dragging the mouse over the dial. The black line represents 0 degrees while the red line is the angle.
Button Widget | Clicking the button on a Button Widget activates the Application-side button.
Color Widget | A Color Widget is used to select a color. It can be an RGB or an ARGB color. Double-clicking the name of the color expands the Color Widget, providing RGB sliders and a gradient image that you can click to select a color. Single-clicking on the color swatch box opens a Color Picker Dialog as another method of selecting a color.
Combo Widget | Changing the selected item in a Combo Widget informs the Application of the new item. Additionally, the Application can change what items on on the list at any time.
Data Widget | A Data Widget represents a connection with the Application that is purely data. Special plug-ins can access the data associated with Data Widgets and send data back to the Application. Normally a Data Widget is not viewed, but a visual representation has been implemented for debugging purposes. Here, the user can view a textual representation of the current data. Subsequently, the Text Box may be editing and the data transmitted back to the Application when the "Send Data to Game" button is clicked.
List Widget | A List Widget represents a list of items with editable fields. When created by the Application, each row is assigned a unique identifier. In this example, this key is the memory address of the variable from the Name column. While all of the cells are editable, the displayed value does not change after an edit is made. Instead, the new value of the cell is sent to the Application, where it decides whether to accept or reject it. If the change is accepted, the Application tells Rag to change the value of that cell and then the display is updated. In the above example, only the Value column is editable.
Matrix Widget | A Matrix Widget is a complex visual representation of a matrix that allows editing of individual component values and has the ability to perform matrix operations. Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value. Left-click the name of the matrix (in this case, Matrix44) to access a drop-down menu with a large array of matrix operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:
Placeholder Widget | The Placeholder Widget is a special Widget that is inserted into Favorites Views (and Find Views after performing a search) to represent a Widget that was once added to a Favorites View but does not currently exist. A Placeholder Widget displays the full path name of the Widget, followed by "(not found)". At some point in the future, if the Application creates that Widget, all of it's Placeholder Widgets will be replaced with the actual one, and vice versa if a Widget is destroyed.
Separator Widget | The Separator Widget is merely used to provide a grouping without creating an expandable group.
Slider Widget | A Slider Widget provides a way to change a number value and keep it clamped between a specified minimum and maximum value. This Widget comes in two varieties: integer and floating point. Click and drag the name button to adjust the value, use the slider control, or use the NumericUpDown control. When typing a new value in the NumericUpDown, press Enter to commit it.
Text Widget | A Text Widget allows the user to view and change text. This Widget comes in 4 varieties: string, integer, floating point, and boolean. Change the text, then press Enter to commit the new value.
Title Widget | The Title Widget is a way to give a group of Widgets a name, but without creating an expandable group.
Toggle Widget | The Toggle Widget provides a check box.
Tree List Widget | The Tree List Widget is a more complex version of the List Widget. With a Tree List, the developer (and the user) have much more control over the structure, look, and behavior of each cell in the list. All rows are created hierarchically. The developer can specify certain types of Edit Controls for each column, or on a cell-by-cell basis, all from the Application code. In this example, m_treeListMyStruct is a structure, so its members are grouped under that node. The developer can decide how to represent vectors. The first vector is edited entirely in place, while the second vector can only be edited by its component sub-node rows. For all fields, the user can specify which are editable and which are not. Unlike the List Widget, this is determined when the developer creates the Tree List Widget (or later adds rows to it).
Vector Widget | A Vector Widget is a complex visual representation of a vector that allows editing of individual component values and has the ability to perform vector operations. Click and drag the named component button (x, y, z, w) to change its value, or use the NumericUpDown control. When typing a value into the NumericUpDown, press Enter to commit the new value. Left-click the name of the vector (in this case, Vector4) to access a drop-down menu with a large array of vector operations. Selecting an operation may bring up one or more dialogs prompting for values before messaging the Application which performs the actual calculation and informs Rag of the new value. The operations are broken down into 3 categories:


Topics

Topics
Windows
Topics
Topic | Description
Main Window | The Main Window hosts the many Views, Output and Application Windows of Rag. In addition, there is a status bar at the bottom of the Window.
Application Window | The Application Window is home to the Display Area of an Application. On a Win32 build, the Display Area is used to display the application itself. On other builds, it is gray as those applications display on the user's television or other monitor. In all cases, mouse input over the Display Area is transmitted to the game. These items can be found on the Application's Applications Menu menu item and on its right-click context menu located on the Application Window's title (its tab when docked or its title bar when floating):
Bank View Window | The Bank View is responsible for displaying the Widgets. By default, one is opened for you at startup, but new Windows can be created from the Widgets Menu. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Find View Window | Find Views are created from the Widgets Menu under each Application's menu item. It is used to search for Widgets that include a specific string anywhere in their full path name. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Favorites View Window | Favorites Views are created from the Widgets Menu under each Application's menu item. Widgets are added to a Favorites View via their right-click context menu on a Bank View Window or Find View Window . Removing Widgets is done from the same right-click context menu, but only from the Favorites View itself. When docked, the user will see a small triangle to the right of the pin icon. Clicking this reveals the drop-down menu shown below. When the window is floating, right-click on its title bar to reveal the following:
Output Windows | Output Windows house Text Boxes that display TTY messages received from the Application. Messages are parsed for colors or special prefixes and piped to certain windows. The messages can be colorized according to their type or displayed with the default Window Text color. Rag has a few default windows:


Contents

Contents
Overview
Menus
File Menu
Views Menu
Disabled Widgets Dialog
Windows Menu
Plugins Menu
Plugins Dialog
Help Menu
Command Line Dialog
Rag Crash Dialog
Submit Feedback Dialog
Windows
Main Window
Application Window
Bank View Window
Find View Window
Favorites View Window
Output Windows
Widgets
Angle Widget
Button Widget
Color Widget
Combo Widget
Data Widget
List Widget
Matrix Widget
Placeholder Widget
Separator Widget
Slider Widget
Text Widget
Title Widget
Toggle Widget
Tree List Widget
Vector Widget
Command Line Options
Rag Command Line Options
Application Command Line Options
Working With Multiple Instances of Rag
Authoring Plugins
Basic Plugins
Quick Screenshot
Window Plugins
Console Window Plugin
Memory Tracker Window Plugin
Top Bar
Overview Tab
Allocations Tab
Memory Layout Tab
Performance Notes
Multi-line Text Window Plugin
Profiler Window Plugin
Widget Plugins
Color Gradient Editor Widget
Event Editor Widget
Input Widget
Keyframe Editor Widget
Script Debugger Widget
VCR Widget
Sensor Plugins
Settings File


Index

Index
A | B | C | D | E | F | H | I | K | L | M | O | P | Q | R | S | T | V | W
A
Allocations Tab
Angle Widget
Application Command Line Options
Application Window
Authoring Plugins
B
Bank View Window
Basic Plugins
Button Widget
C
Color Gradient Editor Widget
Color Widget
Combo Widget
Command Line Dialog
Command Line Options
Console Window Plugin
D
Data Widget
Disabled Widgets Dialog
E
Event Editor Widget
F
Favorites View Window
File Menu
Find View Window
H
Help Menu
I
Input Widget
K
Keyframe Editor Widget
L
List Widget
M
Main Window
Matrix Widget
Memory Layout Tab
Memory Tracker Window Plugin
Menus
Multi-line Text Window Plugin
O
Output Windows
Overview
Overview Tab
P
Performance Notes
Placeholder Widget
Plugins Dialog
Plugins Menu
Profiler Window Plugin
Q
Quick Screenshot
R
Rag Command Line Options
Rag Crash Dialog
S
Script Debugger Widget
Sensor Plugins
Separator Widget
Settings File
Slider Widget
Submit Feedback Dialog
T
Text Widget
Title Widget
Toggle Widget
Top Bar
Tree List Widget
V
VCR Widget
Vector Widget
Views Menu
W
Widget
Widget Plugins
Widgets
Window Plugins
Windows
Windows Menu
Working With Multiple Instances of Rag