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.
For debugging scripts, see also Basic Script Debugging.
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 |
|---|---|
|
|
Studio Play
Play button in Studio.
| Pros | Cons |
|---|---|
|
|
Test -> Play Solo
This is the Test->Play Solo option in Studio. It creates a Solo game using current game in Studio.
| Pros | Cons |
|---|---|
|
|
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
Roblox contains a number of debugging tools that can help you analyze failing (or even working) scripts.
Output
The Output window is the most powerful tool of 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.
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.
Chat in Test modes
Currently, in Start Server->Start Player mode, SuperSafeChat is enabled by default. However, you can use the locked function SetSuperSafeChat is disable the mode for testing via the Server command-line.
You can also use command-line to directly call your chat function, thus emulating chat in Solo/Build or this mode.
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.
