Troubleshooting and Debugging
Sooner or later - in most cases, sooner - any programmer will encounter problems with his script: it does not behave as it should, or even produces errors or crashes.
No reason to worry: most error messages occur during compiling the
script file and indicate simple syntax errors. Something is mistyped, or a non existing file or object was referred to. The script file and line
in question is given in the error message, allowing to easily correct the mistake.
Under error messages you'll find a list of error messages, and under bugs you'll find some general hints what to do in the case of a crash, plus
a complete list of Gamestudio bugs. However, how can you find script bugs that are not indicated through error messages?
- Use the SED debugger for single stepping through your code and observing variables.
If you are not using SED, you can use breakpoint comment tags (//!) for makeshift debugging.
For observing the content of global variable or pointer, add it to the SED Watch List.
For observing a certain local variable, make it global. If you are not familiar with using a debugger, read the tutorial - two workshops deal with debugging.
When your script crashes during debugging, the SED debugger can crash too - in that case, restart SED, and fix the crash before debugging further.
Strip down the problem to the bones. Remove all code that might distract you or that might affect any variables or objects that are related to the problem. In most cases this already reveals the source of the error. Under
Programming Trouble you'll find a list of the most common beginner's errors.
- If the error occurs randomly, check if it's an uninitialized local variable. Use PRAGMA_ZERO and check whether this changes the behavior.
- Set warn_level at its highest value.
This will issue error messages instead of just returning error codes when files are not found or engine functions fail due to wrong parameters.
For permanently observing the status of
local variables, pointers, or the content of bitmaps at certain positions in the code: make sure that acknex.h is included, and use the predefined DEBUG_VAR or DEBUG_BMAP macros in a loop.
- For observing the status of certain entities at runtime: Make sure that default.c is included. Press [Shift-F11]. The game freezes and a cursor appears on the
screen. Click onto the entity you want to observe. The watched pointer will be
set to that entity, causing it's status display to appear on the
screen. Pressing [Shift-F11] a second time will resume gameplay, but
the status display is permanently updated with the status of the last
clicked entity. If you want to get rid of the status display, click
an empty position while in frozen mode.
For reproducing an error that only happens in a certain situation in the game, use the record/replay feature for recording the required gameplay leading to that situation. This makes it much easier to check if the error still occurs.
For finding the circumstances under which a certain global variable is changed, place variable comparison expressions at all suspicious places inside your wait loops.
If your script terminates unexpectedly and you suspect some hardware problem, start it with the -diag command line option and check the acklog.txt afterwards. If the script behaves erratically and debugging does not help, place diag() or diag_var() calls in your functions. This way you can isolate problematic script lines. This also helps to find the reason of random crashes in your script.
If your script randomly
produces E1513 crash error messages
- even in different functions - look for typical reasons such as writing into a wrong memory area, f.i. by exceeding an array length, or using invalid pointers, f.i. pointers to already removed entities. Often this does not cause an immediate problem, but crashes some time later when the overwritten memory area or the invalid pointer is accessed by a totally different function.
You can use the sys_marker command to mark positions in the code and find the place where the crash happens.
Another possible crash reason is running out of memory. In such cases you'll often find a nexus overflow error in your acklog.
While the nexus overflow itself can not cause a crash, using up all memory on a target PC can because DirectX becomes unstable in low memory conditions. This happens especially when your game uses a lot of memory - like several 100 MB - and you have an old PC, a bad virtual memory setup, or many other programs running in the background. Commercial games therefore often use a mechanism like the nexus that already allocates all memory at the beginning, and thus prevents running out of memory at runtime. Set the nexus to a high enough value so that you don't get a nexus overflow, and try to save memory f.i. by using compressed textures. A typical beginner's mistake that produces an unplayable game due to memory overflows is using complex vertex animation instead of bones animation.
If your game crashes already at compiling, and you can't find the reason in the script, look for a faulty external file, such as a damaged model, image, or sound file.
Files that were damaged by a hard disk fault or other reasons can cause crashes at random places in the game. Fortunately they can often be fixed by just loading and saving them again in their editor. If you can't fix the problem this way,
check whether it only occurs with your own project, or also with the samples that come with Gamestudio. In the latter case some software or hardware problem of your PC might be the reason. Check the content of the acklog.txt - it often contains messages about problems that the engine encounters at runtime.
If no script runs at all, check the DEP settings of your PC.
If you are not able to find the reason of the problem yourself, you have two
options. Either subscribe a support ticket in the online store and let Gamestudio Support help you.
Or post a question in the User Forum and ask other users for help. You'll need to upload your project then so that they can
look into it.