Logger Configuration - Grisgram/gml-raptor GitHub Wiki

You configure the logger for your game in the Logger_Configuration script, which can be found, like most other configuration scripts, in the _GAME_SETUP_ folder of the project template.

The script is very well documented, and its only a handful of settings you need to look at, to create the configuration, that is best for your game.

The default configuration is set in a way, that you have enough information in a crash log, have usable log-output in debug, release and beta configs, and chances are, that you don't want to change anything in your normal development cycles.

However, in every development project, there are points in time, where "something" does "something" wrong and you need a more detailled look. Then, this script will help you in receiving even raptor-internal logs, so you can see more clearly, what's going on.

But, let's start top-down with the configuration script:

This integer value is the number of log lines to keep in an internal RingBuffer. Those lines will be written to the crash log. For a normal usecase, the last 200 lines (which is default) should be more than enough. This is less a question of memory usage or performance (RingBuffer doesn't get faster or slower when you increase or decrease the line count), but more a help for you as the receiver of the crash log, because you don't want to study thousands of lines in the log of a crash report. It's the last few seconds before the game died, that matter.

But of course, you can set this to any value you see need for.

This is the formatter (appender) to be used when writing a log line. The default here is the RaptorFrameFormatter.
See Log Formatters for a list of all available formatters and which output they produce.

This value is very important!

It hold the minimum level a log line must have, to appear in the log.
Internally, the log levels are kept in an array, that's why the level here is a number, and not a string. Level 0 is the most detailled (verbose), and Fatal the highest index (5) that can be set.

When you open the script, you can see the LOG_LEVEL macro has different values for each configuration (Default, beta, release):

#macro LOG_LEVEL		0
#macro beta:LOG_LEVEL		2
#macro release:LOG_LEVEL	3

These values represent the ✔ and ❌ markers of the table you saw in the Logger page.

raptor has become a huge framework over time, with many subsystems and each of them has something to say in the log. However, turning them all on at the same time might result in a quite overwhelming log output, where you could easily miss your important information.

That's why, by default, the logging of all subsystems is turned off.

If you are hunting a bug, or don't understand, why something is happening, the macros at the bottom of the Logger_Configuration script can help you identify the source of the problem, when you turn specific modules on:

// Raptor module logs
// In addition to the LOG_LEVEL, you can turn off some modules entirely from logging anything.
// Some of them log lots of lines in verbose and debug mode and need to be turned on only if you hunt a bug
// that _might_ be located in one of raptor's modules
#macro DEBUG_LOG_BROADCASTS		false
#macro DEBUG_LOG_OBJECT_POOLS		false
#macro DEBUG_LOG_LIST_POOLS		false
#macro DEBUG_LOG_STATEMACHINE		false
#macro DEBUG_LOG_RACE			false
#macro DEBUG_LOG_PARTICLES		false

// To avoid, that you "forget" to turn a module off, by default there's a set of these macros, where every log
// is disabled for release mode
#macro release:DEBUG_LOG_BROADCASTS	false
#macro release:DEBUG_LOG_OBJECT_POOLS	false
#macro release:DEBUG_LOG_LIST_POOLS	false
#macro release:DEBUG_LOG_STATEMACHINE	false
#macro release:DEBUG_LOG_RACE		false
#macro release:DEBUG_LOG_PARTICLES	false

The second set of macros for the release configuration is kind of a security backup for you, if you forget to turn off a subsystem in your default configuration, that is still will be turned off in beta and release.

Next, you should take a look at the Log Formatters to choose the one, you like most.