How to report a crash
I'm not trying to single out anybody here; I'm just trying to save everybody some frustration. Let's consider the following two hypothetical forum posts:
1) "After I call hkpWorld::initMtStep, I get a message that says "hkpWorld.cpp(123): [0x12345678] Warning : I'm about to crash". Right after that I get a assert with the message "hkpWorld.cpp(234): [0x00001337] Assert : foo != HK_NULL" and this callstack:
MyCoolPhysicsGame.exe!main(int argc=1, char** argvIn=0x003c39f8)
2) "When I try stepping the world, I get an access violation: 0xC0000005: Access violation reading location 0x00000008. Here's my Havok setup code (...[blah blah blah]...) What's going on? Please help!"
There are two very useful pieces of information in the first one: the callstack (which tells us exactly where the crash is happening), and the warning/asserts IDs that appear near the problem. The ID might not be very useful to you, but it lets us search the full codebase and see what condition is causing the warning or assert. The second post gives almost no useful information, except that there's probably a NULL pointer somewhere.
Why does this matter? Well, if you post a message like the first one, it's more likely that we can give you a answer quickly so that you can go back to coding your game. If you post message like the second, we'll probably ask you for the callstack and any warning message, which means it'll take longer to get your problem resolved. So please, at a bare minimum, when reporting a Havok problem, ALWAYS include the following:
- assert or warning IDs (if any)
Here are some other things that can help us diagnose problems more quickly:
Use the debug libraries
Despite the name, Havok's "debug" libraries are still quite fast. They have almost all optimizations turned on, but they're also built with asserts enabled so that important errors can be caught before they crash the program. For day-to-day usage, you should be linking against these libraries, and only use the release libraries for final versions or profiling.
On a side note, Mick West had a good article in Game Developer a few years ago regarding debug vs. release builds:
Havok's "debug" libs are essentially his "develop" libs.
Debugging multithreading problems can be hard. Like, really hard. If you can, try turning off multithreading to see if that makes the problem go away. Hopefully, it the problem will still be there, so that you can fix it in single-threaded mode first.
As a corollary, make sure the system (physics, animation, raycasting, etc.) works well single-threaded first before trying to multithread it.
If you do get a crash or assert during a multithreaded part of Havok, see if any other threads are doing Havok stuff at the same time. You can do this in the Threads tab in the Visual Studio debugger (Debug > Windows > Threads).
Reproduce the problem in Havok's demos.
Trying to reproduce a vaguely-described bug takes a long time, and even if we spend a long time, we might not have the exact combination of settings that reproduces your problem. If you can modify an existing Havok demo so that the same problem happens there (or make a whole new demo, if you're ambitious), and send us the new demo code, that makes things A LOT easier.
Take a picture, it'll last longer
The hkpHavokSnapshot utility lets you save your world exactly as the game sees it, so that we can load it up later and see what you were doing. There are two possible ways of saving the snapshot; in binary or XML. Personally, I prefer seeing an XML snapshot since I can look at some values (like rigid body properties) without running any code. But binary snapshots are smaller, and reproduce the data EXACTLY (there's a small bit of error in XML snapshots because of ascii-to-float conversion).
A snapshot combined with a modified demo is probably our favorite kind of bug report to get :)
If you're worried about other people seeing your game assets, you can try reproducing the problem with a simpler asset (e.g. a simple cube, or a tesselated sphere), or send a private message to a Havok forum member.
The Visual Debugger is a great tool for diagnosing physics problems, and you should add support for it in your game as soon as you can. It's not very useful for debugging crashes, but it's perfect for illustrating weird behavior ("Why does my car bounce when it drive over that one mesh?"), or investigating performace slowdowns ("Why does my game run at 2fps when my ragoll lands in the corner?"). VDB movies (hkm files) can be rather large, but they zip very well.