Search public documentation:
- Gameplay Debugging
- Remote Control
- Property Inspection and Manipulation
- Gameplay Code Profiling
- STAT Commands
This is a quick guide to using some of UE3's runtime gameplay debugging features. When implementing new features, actors, or gameplay elements, things seldom work exactly as intended the first time through. Being able to quickly adjust property values on the fly or easily view property values, Actor states, or other information while the game is running is imperative to an efficient process. Unreal Engine 3 contains several features, in the form of console commands and applications, which make this debugging process as painless and as efficient as possible. These features can be quite useful for making tweaks, inspecting variables, and tracking down issues without needing to rebuild the engine, rebuild scripts, or restart the game; each of which is a time-consuming process.
The RemoteControl is a special window that can be opened while the game is running to provide information and control over certain aspects of the game. As this window is external to the game window and is created using wxWindows, it is unavailable if wxWindows is disabled, which it is by default except when running a Play In Editor game session from within UnrealEd. To enable wxWindows and the RemoteControl, the game must be run with the
-wxwindowscommand line argument. For more information and a complete guide to using this feature, see the Remote Control page.
Inspecting properties of Actors in the game and being able to modify them on the fly is a huge benefit not only when debugging, but also for tweaking and tuning the behavior of gameplay elements. The ability to view and adjust Actor properties is provided through the use of a special set of console commands. console commands allow you to open a property window for an in-game object or even for the class default object, which can then be viewed or modified at runtime. Note that there is a
Nonecategory that contains all the variables that have not been declared with
var(), giving you complete access to all of the object's data. As these commands rely on property windows external to the game window which are created using wxWindows, these commands are unavailable if wxWindows is disabled, which it is by default. To enable wxWindows and thus these console commands, the game must be run with the
-wxwindowscommand line argument. Note: This will also enable the Remote Control. You can also add the
-norccommand line argument to disable the Remote Control window if you like.
editactorconsole command makes the properties of an actor in the game available in the property window. This command only works for classes extending from
Actor.This command can take a name or a class as an argument. Optionally, the
traceargument can be passed in place of the name or class causing the
Actorthe player's camera is currently aiming at to be used. If a name of an
Actoris specified, either with the
name=prefix or not, the properties of that Object will be displayed.
editactor name=UTPawn_0This will open a property window for the object
UTPawn_0. If a class is specified, the properties of the first
Actorof that class, or a subclass thereof, are displayed.
editactor class=UTPawnThis will choose the first
UTPawn. In this case, it would most likely open the properties for the current player's
UTPawn. If the
traceargument is specified, the properties of the
Actorbeing aimed at are displayed.
editactor traceThis will open a property window for the object at which the camera is aiming. Example Usage: In the case of creating a new vehicle, the need to fine-tune the properties of the vehicle to make driving feel right will no doubt arise. Setting the property values in the defaultproperties or even in an .ini file would require starting the game up, testing out the current values, shutting the game down, tweaking the values, starting the game up again, testing the values, etc. This is obviously less than ideal and not very efficient by any means. Using the
editactorcommand allows any and all of the properties of the vehicle to be tweaked while the game is running, even while the player is sitting in the vehicle ready to test it out. This is a much more efficient and intuitive method of tuning gameplay. The simplest method here is probably to use the
traceargument and just aim at the vehicle in question, but specifying the class is easy enough as well. For vehicles, it may be unlikely you will know the exact name of the vehicle as they are usually spawned dynamically from factories and not placed directly in a map.
editobjectconsole command makes the properties of a specific object in the game available in the property window. This command is functionally identical to the
editactorcommand without the limitation that the class must extend from
Actorand it has no optional
traceargument. Note: This command may not work for certain classes or objects when running a map from within UnrealEd through a Play In Editor session. If a name of an
Objectis specified, either with the
name=prefix or not, the properties of that Object will be displayed.
editobject GameThirdPersonCamera_0 editobject name=GameThirdPersonCamera_0Both of these are functionally identical, and will display the properties for the
GameThirdPersonCamera_0object. If a class is specified, the properties of the first
Objectof that class, or a subclass thereof, are displayed.
editobject class=GameThirdPersonCameraThis will choose the first
GameThirdPersonCamera. In this case, it would most likely open the properties for the current player's
GameThirdPersonCamera. Example Usage: Implementing a camera other than first person usually requires having the camera offset from the player mesh, among other aspects that may need tuning. Of course, getting the camera offset the proper distance to get the desired look and feel can be tricky. You certainly do not want to be constantly going back and forth between code and testing needing to compile with each tweak. If you are also working with a system similar to the modular system that is part of the
GameFrameworkexamples that means you are dealing with objects and not actors. The
editobjectcommand enables you to easily view and modify the properties of those modules with the game running to make the process of tweaking your camera extremely simple and incredibly intuitive. By using the
editobjectcommand and passing it the class of the camera module, the properties for the module will be displayed and tuned to get the offset just right.
editobject class=UDNCameraModuleThis will open the property window for the camera module currently in use.
editdefaultconsole command makes the properties of a class default object available, similar to specifying a class with the
editobjectconsole command. The class can be specified using the
class=prefix, but it is not necessary. This command is extremely useful for classes that are frequently spawned, such as projectiles or units in a real-time strategy game. Note: This command is not allowed when running a map from within UnrealEd through a Play In Editor session. Example Usage: Tweaking the behavior of projectiles can be tedious if you are constantly going between code and testing. By editing the default values directly inside the game while you are testing, the process becomes extremely streamlined. Simply use the
editdefaultcommand and pass it the name of a projectile class:
editdefault UTProj_LinkPlasma editdefault class=UTProj_LinkPlasmaBoth of these are functionally identical and will display the default properties of the
UTProj_LinkPlasmaclass which can then be modified allowing you to adjust the behavior of all future instances of that class.
editarchetypeconsole command makes the properties of an archetype available. The archetype to edit is specified by passing the path (Package.Group.Name) to the archetype following the command. Like the
editdefaultcommand, this command is also extremely useful for archetypes that are used as templates for objects that are frequently spawned, such as projectiles or units in a real-time strategy game, or for archetypes used as data definitions or content holders. In addition to being able to edit the properties of the archetype, the settings can be saved to the archetype in the package using the button in the properties window so they are not lost. Note: This command is not allowed when running a map from within UnrealEd through a Play In Editor session. Example Usage: Say you have a weapon class set up to use archetypes as templates for its projectiles. This allows the look and behavior of the projectiles to easily be tweaked without having to modify and recompile the scripts. However, it would also usually require running the game and testing, closing the game and making changes, running the game and testing, etc. By using the
editarchetypecommand, the modifications can be made while the game is running for an easy and efficient workflow. The projectile using the current settings of the archetype: Simply use the
editarchetypecommand and pass it the path of the archetype:
editarchetype UDNProjectiles.RedPlasmaBy modifying the proeprties, the look and behavior of the projectiles is changed in realtime: Once you are satisfied with the settings, press the button in the proeperties window to save the current settings to the archetype. console commands are useful for inspecting a static snapshot of object data while the game is running. They will capture the values of the specified data at the time the command is executed and display that data in the console and output it to the log as well.
getallconsole command returns the value of a particular variable for all objects of a particular class and displays them in the console in-game, visible by pressing the '~' key, and outputs them to the log. The command is followed by the name of the class and variable within that class to access. Example usage: When implementing a new custom camera system, it can be frustrating to run the game to test out the new camera only to find it not working as expected. It is possible the camera is not functioning correctly, but it could be something more simple such as the camera is not getting created and assigned correctly in the first place. Adding log statements to the code and then running the game and then closing the game to check the logs to see the results is one method to see if the camera is getting assigned. However, it would be so much easier and efficient if you could check right there in the game while it is running. The
getallcommand makes this possible. By using this command and passing it your custom
PlayerControllerclass and the name of the camera variable contained within it, the current value of that variable will be displayed right there in the console, immediately letting you know if the camera is not being assigned properly or if the problem lies elsewhere.
getall UDNPlayerController PlayerCameraThis will list out the
UDNPlayerControlleractor in memory in the console in-game. Since the
PlayerCamerahas a value and not
None, you know the camera is being assigned properly. Additional Parameters: This command can also be used to obtain the value of a particular variable for a single instance of a particular class by specifying some optional parameters.
- Name= - Displays the particular variable's value for the
- Outer= - Displays the particular variable's value for all instances of the specified class having this
- SHOWDEFAULTS - Displays the default value for the particular variable in addition to the current value.
- SHOWPENDINGKILLS - Displays instances even if they are orphaned and pending deletion.
- DETAILED - Displays detailed information about the instance(s) via the
getallstateconsole command returns the current state of all objects of a particular class and displays them in the console in-game, visible by pressing the '~' key, and outputs them to the log. The command is followed by the name of the class to access. Example usage:
getallstate UTPawnThis will list the current state of every
UTPawnin memory in the console in-game. This gives you a quick overview of what the
UTPawnsin the game are doing. It can quickly point out an anomaly, such as you see in the screenshot as this snapshot was taken at the time the bots were spawning and yet one
UTPawnis in the
Dyingstate. console commands are useful for inspecting object data as it changes over time. They will display a set of data which dynamically updates each frame directly on the screen overlaying the game as part of the HUD.
displayallconsole command returns the value of a particular variable for all objects of a particular class and displays them on the screen. The command is followed by the name of the class and the variable within that class to access. Example usage:
displayall UTPawn LocationThis will list the
UTPawnon the screen, updated every frame.
displayallstateconsole command returns the current state of all objects of a particular class and displays them on the screen. The command is followed by the name of the class to access. Example usage: Creating believable AI in a game is a difficult task to begin with, but without a way to keep an eye on all the AI as they interact it would become even more so. The
displayallstatecommand makes one aspect of this quick and easy. You can have the current state of every AI entity displayed right on the screen, updating every frame as they make new decisions. By using this command and passing it the class of the AI entities, you can have an overview of your AI at the ready.
displayallstate UTBotThis will list the current state of every
UTBotin memory on the screen, updated every frame, making it extremely easy to see exactly what each bot is doing.
displayclearconsole command clears all object data currently being displayed on the screen. This command takes no arguments. Example usage:
displayclearThis will clear the object data being displayed on the screen from a previous DisplayAll or DisplayAllState command.
setconsole command will set the value of a variable for all instances of a particular class, as well as the class default object. The command is followed by the name of the class, the variable within the class to modify, and the value to set the variable to. This can be very useful for tweaking weapons, projectiles, bots, units in an RTS, etc. Note: This command is not allowed when running a map from within UnrealEd through a Play In Editor session. Example usage: Balancing weapons can be a tricky feat, constantly tweaking properties to get just the right combination so that no one weapon is overpowering the others. No one in their right mind would want to try to do this by resorting to changing properties in code and compiling and testing. And since you really want to affect all instances of the weapons at once, the
editactorcommand just will not cut it. The
setcommand, however, is perfectly suited for such a task. By this command and passing it a class name, a variable name, and a value for that variable, it is easy to modify the value of that variable for all instances of that class that currently exist and any instances that may be spawned subsequently.
set utweap_linkgun maxammocount 150This will increase the maximum ammo count that all link guns can hold.
The Gameplay Profiler is a tool that provides a detailed breakdown of where time is being spent when executing UnrealScript gameplay code. For a detailed overview, see the Gameplay Profiler page. For more information on the command line arguments useful for profiling gameplay, see the Gameplay Profiling page.
The STAT commands can be useful in getting a quick look at how much time certain aspects of your code are taking to execute. The
STAT GAMEcommand is especially useful as it shows the cumulative time your scripts are taking to update each tick. For more information on this and other STAT commands, see the Stats Description page.