Mystery Games

How I Actually Got Mystery Games Working Without Wasting Two Weeks

Mystery Games is a debugging and tracing framework for interactive entertainment projects. People keep asking me about it because the documentation is sparse and the examples are three years out of date. I spent about six months wrestling with it on a mid-budget mobile project before I stopped fighting it and started working with the actual architecture instead of against it. Here is what I learned. You do not need to install anything special first. Clone the repo, run the bootstrap script in the root directory, and it will pull the necessary dependencies automatically. That part is fine. The problem is the configuration file. Most people skip it or paste a config from a tutorial they found on GitHub. It does not work like that. The config file expects you to declare your tracing targets explicitly. If you are working in Unity, your path entries need to match the actual assembly structure, not the project folder structure. I spent a full day debugging a missing trace event before realizing my Assembly-CSharp.dll reference in the config had a trailing slash that shouldn't have been there. The parser is strict about that. Remove trailing slashes from all path entries and reload the session.

The Things Nobody Tells You About Mystery Games

First, the hot-reload feature is more useful than the logging feature. Yes, I said that out loud. Most people use Mystery Games to generate logs and stare at them. That is fine for small scenes but completely unmanageable once your project hits more than fifty active objects. Hot-reload lets you inject trace points while the build is running without restarting the editor. I use it constantly. Set your watch breakpoints early and often. A watchpoint on a single variable gives you more actionable data than a hundred log lines. Second, the garbage collection spike when you enable full tracing is real and it is not going away. The framework buffers all trace events in memory until you flush them. On a constrained platform like iOS, enabling every trace point can push your heap usage up by roughly 40 to 60 megabytes during a typical session. I learned this the hard way when a QA tester reported frame drops on iPhone 11 devices that we couldn't reproduce anywhere else. We turned off the buffer flush delay and set it to auto-flush every five seconds instead. That kept memory under control without losing data.

Common Pitfalls When Using Mystery Games

Thread safety is the biggest issue. The framework is not designed for multi-threaded environments out of the box. If you are tracing something that runs on a background thread without wrapping it in a lock, your trace output will have gaps. Missed events. Duplicated events. Order corruption. I had a network replication bug that only showed up when three players were connected simultaneously. The trace output looked random because two threads were writing to the same buffer without synchronization. I wrapped the trace calls in a simple mutex and the issue became immediately obvious. Another thing people miss is the profiling mode. Running Mystery Games in normal trace mode adds maybe eight to twelve percent overhead on a typical build. In profiling mode, it strips out the buffered output and only records call timings. That overhead drops to about two percent. If you are trying to measure performance impact or find a bottleneck, always use profiling mode. Normal trace mode is for functional debugging only. There are limitations you need to accept. Mystery Games does not track object lifecycle events by default. If you need to know when a MonoBehaviour is destroyed or a singleton is unloaded, you have to add that instrumentation yourself. It also has zero support for native code tracing on console platforms. If your game uses a lot of C++ plugins or native DLLs, the framework simply will not see inside them. You need a separate profiler for that. We ended up pairing Mystery Games with a lightweight native logger on our PS5 build and merged the outputs manually. Took about an hour to set up the merge script and saved us weeks of blind debugging later.

The download and setup process is straightforward. Grab the latest release from the official repository, read the configuration section carefully, and test it on a clean scene before integrating it into your main project. Do not skip the test scene step. It takes five minutes and will save you from a lot of headaches.