Debugging

Purpose

It's not always possible to write functional scripts the first time or even to figure out the problem by looking at them. Sometimes you need to "debug" the script by running it using techniques and tools that provide more information about what went wrong.

Run Modes

Normally, you play a game using "Online Play" mode. But this mode is the hardest to debug in. Other modes are available to provide better ways to build and test your place, but each also has limitations that you should be aware of. It's important to test out any new scripts or ideas online to be sure that they really work.

Build mode

Build mode (also called Play Solo in other peoples Unlocked places) can be useful for debugging.

Pros	Cons
Tools Output Window Command-line Explorer/Properties Player and Character Build Tools	Local Only 1 Player Beginning Output Lost

Studio Play

Play button in Studio.

Pros	Cons
Tools Output Window Command-line Explorer/Properties Fast and Simple No Output Lost	Server-side Only No Player or Character Repeated Resets can crash

Test -> Play Solo

This is the Test->Play Solo option in Studio. It creates a Solo game using current game in Studio.

Pros	Cons
Tools Output Window Command-line Explorer/Properties Launches fairly quickly Studio Edits not lost if crashed Player and Character	Local Only Player named Player

Test -> Start Server/Start Player

This is the started from Studio using:

• Test->Start Server then
• Test->Start Player (1 or more times)

It creates an game much like online mode using current game in Studio.

Pros	Cons
Tools (Server only) Output Window Command-line Explorer/Properties Most like online mode Studio Edits not lost if crashed Multiple Player(s) and Character(s)	All players named Player LocalScripts have no tools

Tools

Roblox contains a number of debugging tools that can help you analyze failing (or even working) scripts.

Output

Main article: Output

The Output window is the most powerful tool or all. It displays any errors captured from running scripts, messages from Roblox game code, and user-defined messages and errors. But it can't be used in every situation (see Limitations).

Command Line

The Command Line provides a powerful debug tool. It allows you to test out possible script commands and to make adjustments to the game while it is running.

Explorer/Properties

The explorer and properties windows can be used in a running game to see what objects exists at a given time. It can help you see what went wrong in a script or what additional checking is required for special situations.

Building Tools

The building tools available in Build mode, give a user the power to edit certain game properties using 3-D interface. They have limited debugging use.

Log Files

A hidden feature of Roblox that can be invaluable to debugging is the log files. Whenever a script running on your computer does a print or has an error, this message is recorded in a log file. These files are located in different places depending on the Operating System and usually in hidden folders, but find them.

Windows XP: C:\Documents and Settings\USERNAME\Local Settings\Application Data\Roblox\logs

Vista/Windows 7: C:\Users\USER\AppData\Local\Roblox\logs

Vista Alternate Location: C:\Program Files (x86)\Roblox\logs

Note that the "lost" output is catured in one log file and the rest of the output is in a different one.

File Descriptions

log_XXXXXX.txt - This is the first log file for the Roblox instance (you get 1 instance if playing online, solo, or directly in studio; 2 or more if using start starter/start player). It contains some Roblox startup debug and the "lost" messages from the first output window.

log_XXXXXX_Roblox_TaskScheduler_Thread Y_Z.txt - This created when character joins or at a similar point on the server. It contains all the rest of the log and error messages.

log_XXXXXX_G3D.txt - Debug messages for 3D engine.

log_XXXXXXgfx_d3d.txt - Debug messages for DirectX and Video driver.

log_XXXXXX_rbx_thread_YYYY.txt - Roblox built-in game script logs.

Modifying Scripts

While debugging tools can give you some information about what the script is doing, the best way to get information is to modify the script to generate it.

Print

The print() function is the simplest way to get information from a script. Use it to show what parts of the script are executing and what values are being used. This alone is the best debugging tool.

Error

The error() function can be used to generate user-defined error when something goes wrong in the script. This gives a message in the log and also stops the script execution.

A similar function assert() can quickly check if something is true and generate an error if not.

Messages

The print, error and assert functions are great if you have an output window to see them (or log file!). If not, you can still get the same information through to the user. Create a Hint, Message, or GUI item to display the message. You can even redefine the print function so that it uses one of these techniques. NOTE: that script errors do not use the error function (see Advanced below)

Limitations

Output

One of the most tricky limitations of Roblox debug is the second output window. During the beginning of the game in solo mode, compile errors and script prints go to an output window, but when the player is created a new output window replaces the original and all messages are "lost" (if you watch carefully, you can catch the red error message appear briefly). Use the log files to see these messages. In some cases, adding wait(2) to the beggining of your script will push the messages into the second window.

Local Only

Local Only testing mode are more forgiving than online play. In particular, they use a single environment for both server-side and local scripts. Some differences from online play:

• Shared _G table for all scripts
• Server Events are triggered for Local Scripts
• Local Events are triggered for Server Scripts
• Local Properties are visible to Server Scripts
• Player is usually created before Server scripts run
• There is no replication delay (or lag)
• HopperBin scripts run only once (normally they run on server AND local)

Server Only

Server Only testing mode (Studio Play) has several key limitations (aside from obvious ones).

• Local Scripts do not run at all
• Local Events do not fire

Although StarterGui option ShowDevelopmentGui allows the display of GUI objects in Studio, they cannot be tested that way.

Advanced

This section includes tips for advanced scripters to debug those extremely tricky problems.

Value Objects

In several of the modes, you can access only Server or only Local output. By creating a Value object, you can transfer data from the inaccessible script to one that can give you the information. Messages also work for this since they are replicated.

loadstring

The function loadstring returns 2 arguments. The second is the compile error if any.

coroutine/pcall/xpcall

The functions coroutine.resume(), pcall(), and xpcall() can return runtime error messages and prevent script errors from breaking the script.

See Also

Common Scripting Mistakes