Debugging Client Errors
From Multiverse
| Using the Multiverse Client |
|
Install & Run • Supported Graphics Cards • Release Notes • Client FAQ • Troubleshooting • Connecting to a World • Client Metering • Using the Client Log File • Debugging Client Errors |
| Reference |
|
Command Line Syntax • World Settings File • Patcher Page Reference • Client Logging |
Much of the work in creating user interfaces and Client scripting involves editing and creating XML and Python files that the Multiverse Client reads. The Client can be somewhat unforgiving of errors, and something as simple as a missing quotation mark or bad indentation in a Python script can cause the user interface to not display or even completely crash the client.
This article explains how to identify errors and how to check for common error conditions before even running the client. For more general information on the contents of the MultiverseClient.log file, see Using the Client Log File.
Contents |
Types of errors and how they appear
There are essentially two types of errors that can occur with the Multiverse client: load time errors and runtime errors. Load time errors are those that occur as the client is first loading up the user interface XML files and client scripting Python files. Runtime errors occur when some kind of fault happens while a script is executing during the game.
Some errors are very obvious with the Multiverse client because they are fatal. That is, the client quits suddenly perhaps without any kind of warning message. Others are more subtle, and might be recognized because a user interface element does not appear on the screen or behaves incorrectly. Irrespective of how the error shows itself, you will probably be able to see
The most common causes of errors
Errors usually always occur because of four different things: syntax errors in user interface XML files, syntax errors in Python scripts, logic errors in Python scripts and missing assets. XML must be carefully formatted so that all tags are balanced and properly placed. Python is notoriously picky about indentation of lines, and of course logic errors happen just because some piece of code is syntactically correct, but doesn't actually perform as intended. Missing assets are files such as textures, materials or meshes which are not found in the asset repository.
Finding errors
When most errors occur in the Multiverse client, some kind of error message will show up in the trace file created by Multiverse. The trace file is located inside of the “Multiverse Client\Logs” folder and is named trace.txt. It can grow rather large if the Multiverse client has run for a while, however each time the client is started, the trace file is erased and a new trace created. Typically, finding errors in the trace file can be difficult just because of the sheer volume of information present in the file. The next lesson (Lesson 6) goes into depth about the format and structure of the trace file and can be a helpful reference to know where to look in the file for errors. What follows is a list of some different errors you may encounter in the trace file that you should pay attention to. They may not necessarily be fatal, but they do indicate some kind of error that might be worth noting or fixing. And you may find error messages in the trace file which are not actually the source of the error you are trying to track down.
Finding load time Python errors
This type of error indicates you have some kind of syntax or other load time error with a Python script. These usually occur as the user interface is first being loaded, or scripts in the asset repository Scripts folder. Depending on the severity of the error, the Multiverse client may continue to run without crashing, however there may be missing or incorrect user interface behavior.
Here is an example from a trace file of a Python syntax error...
[10/18/07 09:19:59.301] MultiverseClient.exe Information: 0 : Executing script file '../Worlds/LUNARQUEST/\Interface\FrameXML\RetroEquipment.py' [10/18/07 09:19:59.301] MultiverseClient.exe Warning: 0 : Failed to run script file '../Worlds/LUNARQUEST/\Interface\FrameXML\RetroEquipment.py' in module '' [10/18/07 09:19:59.301] MultiverseClient.exe Warning: 0 : PythonSyntaxErrorException at ../Worlds/LUNARQUEST/\Interface\FrameXML\RetroEquipment.py:8: invalid syntax [10/18/07 09:19:59.301] MultiverseClient.exe Warning: 0 : Failed to run script file: RetroEquipment.py
Note that the client in this case the client continued to run and there was no obvious error at first.
Finding XML errors
These errors occur when there is some kind of error in a user interface XML file. They occur only as the client is first loading the user interface XML files and don't occur at runtime. The exact nature of these errors can be hard to determine with just the trace file, but are relatively easy to find if you examine the XML file outside of the client.
Here is an example of how an XML syntax error may show up in the trace file. In this case, there was a missing </FRAME> tag to close off a Frame declaration.
[10/18/07 09:23:31.060] MultiverseClient.exe Warning: 0 : Failed to handle message UiTheme: System.Xml.XmlException: The 'Frame' start tag on line 146 does not match the end tag of 'Ui'. Line 290, position 3. at System.Xml.XmlTextReaderImpl.Throw(Exception e) at System.Xml.XmlTextReaderImpl.Throw(String res, String[] args) at System.Xml.XmlTextReaderImpl.ThrowTagMismatch(NodeData startTag) at System.Xml.XmlTextReaderImpl.ParseEndElement() at System.Xml.XmlTextReaderImpl.ParseElementContent() at System.Xml.XmlTextReaderImpl.Read() at System.Xml.XmlLoader.LoadNode(Boolean skipOverWhitespace) at System.Xml.XmlLoader.LoadDocSequence(XmlDocument parentDoc) at System.Xml.XmlLoader.Load(XmlDocument doc, XmlReader reader, Boolean preserveWhitespace) at System.Xml.XmlDocument.Load(XmlReader reader) at System.Xml.XmlDocument.Load(Stream inStream) at Multiverse.Interface.UiSystem.LoadInterfaceFile(String file) at Multiverse.Base.Client.ReloadUiElements() at Multiverse.Base.Client.HandleUiTheme(BaseWorldMessage message) at Multiverse.Network.MessageDispatcher.HandleMessage(BaseWorldMessage message)
The interesting thing in this case is that the message is just labeled as a warning, yet the error caused the entire client application to crash. The crash occurred because the client was unable to parse the XML and could not then define one of the user interface elements. When it tried later to actually reference the missing user interface element (the broken frame), it caused a crash.
Finding Python runtime errors
Runtime errors typically create a long set of traceback information from the Multiverse IronPython runtime system. IronPython is a java system that allows Python scripts to be executed from inside of Java. Here is a sample of just part of a runtime error trace from this kind of error...
[10/14/07 10:19:49.671] MultiverseClient.exe Error: 0 : FMOD result: The specified channel has been reused to play another sound. at Multiverse.Base.SoundManager.LogResults(RESULT result) at Multiverse.Base.SoundSource.Stop() at Multiverse.Base.SoundManager.Release(SoundSource source) at Multiverse.Base.ObjectNode.DetachSound(SoundSource source) at DetachSound##970(Object , Object ) at IronPython.Runtime.Calls.FastCallable2.CallInstance(ICallerContext context, Object arg0, Object arg1) at IronPython.Runtime.Calls.BoundBuiltinFunction.Call(ICallerContext context, Object arg0)
These types of errors can often be extremely difficult to debug, as there is little information given in the trace file. Sometimes the best approach to debugging these kinds of errors is to make a guess at which script has the error, then add lines to the Python code which will print out information to the trace file. By identifying the last of these messages you see, you can get an idea of where the error is happening.
Here is an example of some Python code with a call to the Trace.TraceInformation method, which writes the given text to the trace file.
def ReleaseButton_OnEnter(name, button):
Trace.TraceInformation("In ActionBarButton_OnEnter slot")
MenuBarTooltip.SetPoint("BOTTOMRIGHT", button.Name, "TOPLEFT")
MenuBarTooltipTextLeft1.SetText(name)
MenuBarTooltip.Show()
Finding missing asset errors
Missing assets are files that your world files or client side scripts refer to, which can't be found by the client. This includes sound files, model meshes, materials, textures and other such assets.
Mesh errors
If a mesh file (model) is used in your world file but not present in the asset repository, you will get an error message in the trace.txt file indicating the file is missing. However the client will still run and will not crash, and only by realizing that a model is not in the world will you know it is missing.
Below is an example from the trace.txt file of a typical error message for a missing mesh file. In this case, the missing mesh is named 'solar_panel.mesh'.
[11/02/07 11:07:38.877] MultiverseClient.exe Error: 0 : Unable to create entity; Exception: Axiom.Core.AxiomException: Resource 'solar_panel.mesh' could not be found. Be sure it is located in a known directory or that it is not qualified by a directory name unless that directory is located inside a zip archive. at Axiom.Core.ResourceManager.FindResourceData(String fileName) at Axiom.Core.Mesh.LoadImpl() at Axiom.Core.Resource.Load() at Axiom.Core.Mesh.Load() at Axiom.Core.ResourceManager.Load(Resource resource, Int32 priority) at Axiom.Core.MeshManager.Load(String name, BufferUsage vertexBufferUsage, BufferUsage indexBufferUsage, Boolean vertexBufferShadowed, Boolean indexBufferShadowed, Int32 priority) at Axiom.Core.MeshManager.Load(String name) at Multiverse.Base.WorldManager.LoadPreloadEntry() [11/02/07 11:07:38.893] MultiverseClient.exe Warning: 0 : Exception setting model for node oid 323459, name PowerArea_solarPanel_5, error message 'Axiom.Core.AxiomException: Resource 'solar_panel.mesh' could not be found. Be sure it is located in a known directory or that it is not qualified by a directory name unless that directory is located inside a zip archive. at Axiom.Core.ResourceManager.FindResourceData(String fileName) at Axiom.Core.Mesh.LoadImpl() at Axiom.Core.Resource.Load() at Axiom.Core.Mesh.Load() at Axiom.Core.ResourceManager.Load(Resource resource, Int32 priority) at Axiom.Core.MeshManager.Load(String name, BufferUsage vertexBufferUsage, BufferUsage indexBufferUsage, Boolean vertexBufferShadowed, Boolean indexBufferShadowed, Int32 priority) at Axiom.Core.MeshManager.Load(String name) at Axiom.Core.SceneManager.CreateEntity(String name, String meshName) at Multiverse.Base.WorldManager.ApplyModelWithoutPreload(ObjectNode node, String name, String meshName, List`1 submeshList) at Multiverse.Base.WorldManager.ApplyModel(ObjectNode node)'
Image errors
There are two errors you may see now and then in a trace file that are caused by problems with missing or incorrectly named textures. They are not fatal, but can cause parts of the user interface to not be rendered properly. They can be identified by the strings that are quoted below...
“Using transparent texture instead of”
If you see this text in the trace file, it means that the Multiverse client was not able to find a specific texture, icon or image, and it is replacing it with a transparent (blank) texture. Here is an example of some output from the trace file where this is happening...
[10/14/07 10:17:51.375] Using transparent texture instead of Interface\Icons\INV_Pushed for widget [10/14/07 10:17:51.375] Using transparent texture instead of Interface\Icons\INV_Highlight for widget This can mean you are missing an image declaration in a file in the Interface\Imagesets folder, or that you have mis-typed a texture name inside of an interface XML file.
“Invalid imageset”
This indicates you are missing a declaration of an imageset file, or that you have mis-typed the name of an imageset inside of a user interface XML file. Here is an example of this error...
[10/14/07 10:17:51.796] MultiverseClient.exe Warning: 0 : Invalid imageset: Common
Like with the “Using transparent texture instead of” error, this error isn't fatal but can lead to incorrect user interface displays.
Errors to ignore
The trace file often will also contain warning and error messages that can be ignored as they do not cause the client to crash or fail. Below are a list of a few of these messages that you might see but can ignore. Some of them are actually caused by bugs or problems with the Multiverse client itself.
login_settings.xml error
As of version 1.0 of the client, there will always be an error message about being unable to read or load the file login_settings.xml. This error can be ignored and is of no consequence. Here is what the error message will look like...
[10/14/07 10:16:49.734] MultiverseClient.exe Information: 0 : Unable to load login settings: System.IO.FileNotFoundException:
Could not find file 'C:\Program Files\Multiverse Client\login_settings.xml'.
File name: 'C:\Program Files\Multiverse Client\login_settings.xml'
at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share,
Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath,
Boolean bFromProxy)
at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share)
at System.IO.File.OpenRead(String path)
at Multiverse.Base.LoginHelper.ParseConfig(String configFile)
“Unknown tag: xml”
This warning occurs in various places in the trace file and can be ignored. The line will look like this...
[10/14/07 10:17:32.296] MultiverseClient.exe Information: 0 : Unknown tag: xml
“Unhandled element” or “Unhandled attribute” warnings
You may see some errors indicating unhandled elements or attributes. These errors come from XML tags or tag attributes which are not recognized by the Multiverse client. These warnings can look like this...
[10/14/07 10:17:50.046] MultiverseClient.exe Warning: 0 : Unhandled element: Script [10/14/07 10:17:50.046] MultiverseClient.exe Warning: 0 : Unhandled attribute: maxLine
They are not actually fatal, but can possibly indicate an error in your XML structure. These errors show up multiple times when loading some of the Multiverse user interface XML files that are part of the default asset repository.
Debugging Python errors
If you do see some kind of error message in the trace file related to a Python script, it can be difficult at best to debug the errors simply by viewing the trace file. To quickly identify errors in a Python script, try just running the script from the command line using a Python interpreter. If there are any errors you will see more information from the Python interpreter than you will in the trace file. For example, here is a sample output when trying to execute from the command line a Python script that has an indentation error...
$ python MvChat.py
File "MvChat.py", line 22
MvChatFrame.Show()
^
SyntaxError: invalid syntax
If the Python error actually occurs at runtime, it can be a bit harder to find them. A very simple approach is to just put statements in your code to print text into the log file. By looking for these statements in the trace file after the script has run, you can tell how far the code has gone. If your trace message doesn't show up then you know the code has failed before this point.
Here is an example of some Python code with a call to the Trace.TraceInformation method, which writes the given text to the trace file.
def ReleaseButton_OnEnter(name, button):
Trace.TraceInformation("In ActionBarButton_OnEnter slot")
MenuBarTooltip.SetPoint("BOTTOMRIGHT", button.Name, "TOPLEFT")
MenuBarTooltipTextLeft1.SetText(name)
MenuBarTooltip.Show()
Identifying which XML file has an error
If you have an error in one of the XML files, it can be difficult to discover exactly which of the files has the error. This is because the trace file does not give the name of each XML file as it is loaded. Instead, it identifies the name of each frame as it is created. Here is a bit of a trace file showing what these creation messages look like...
[10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Added frame: RobotProgrammingTemplate [10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Added frame: AirlockControlTemplate [10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Adding to FrameMap: AirlockControl [10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Added frame: AirlockControl [10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Adding to FrameMap: RobotProgramming [10/14/07 10:18:11.156] MultiverseClient.exe Information: 0 : Added frame: RobotProgramming
You can see how the trace file gives the name of each frame that has been defined but only after the frame has been successfully constructed. What this means is that if you have an error in the declaration of a frame, you will not see the actual “Added frame:” message for the frame with the error, but only the name of the last frame successfully created. This can make it tricky to identify just what frame has the error.
To find the frame that has the error, look at the name of last frame successfully created just before the error, and then find out which frame is defined in XML just after that frame. For example in the above bit of client trace data, you can see that the AirlockControlTemplate is created after the RobotProgrammingTemplate. If there was an error in the AirlockControlTemplate definition, then the last “Added frame” message seen would be the one for the RobotProgrammingTemplate.
Debugging XML errors
Once you have identified which XML file has an error, identifying the actual XML error can difficult just by looking at the trace.txt file. An easy way to check your XML to see if it is correct is to just load up the XML file in either the Mozilla or Internet Explorer web browser. The browser will give some kind of error message if there are any unbalanced tags or other problems with the XML.
For example here is the output from Mozilla for an XML file that is missing a closing <FRAME> tag...
XML Parsing Error: mismatched tag. Expected: </Frame>.
Location: file:///C:/Multiverse%20Client/Worlds/UCF_PHYSICS/Interface/FrameXML/MvChat.xml
Line Number 280, Column 3:</Ui>
--^
