Logger - Grisgram/gml-raptor GitHub Wiki

Raptor 3.0 adds a built-in Logger.

It gives you a set of easy-to-use shortcut macros to write things to the console log and offers formatters (they are also called appenders in some professional logging systems) to ensure, that necessary informations are formatted correctly in the log.

Logging through the Logger

The logger will initialize itself, when the game starts, according to its Logger Configuration.

In contrast to show_debug_message, the raptor logger supports Log Levels. These levels are used to filter log lines, that get written to the log (you do not want internal debug-messages to appear in the log when the game is released on steam).

These Log Levels are supported. The table also shows the default setting of the Logger Configuration for Default/release/beta configurations.

Level	Abbr	Default	beta	release	Description
Verbose	V	✔	❌	❌	The most detailled level. As an example, `raptor` logs mouse enter/leave/down/up events to the verbose level
Debug	D	✔	❌	❌	Debug information. This is your normal log level for output, that is only for your eyes, when you develop your game
Info	I	✔	✔	❌	Informational messages are things that can also be viewable in a beta release, like loading/saving a game, starting a room, player died, etc...
Warning	W	✔	✔	✔	Something went wrong, but it's not so bad, that you can't continue. Maybe something unexpected happened, like a locale file is not found, but it should be there. You can switch to the default language, but still leave the warning in the log, that the locale didn't exist, things like that
Error	E	✔	✔	✔	This is, what you would write to the log, when you fall into a `catch` or when you encounter file/network/display errors that you can't resolve. Very valuable information for crash dumps.
Fatal	F	✔	✔	✔	Use this level only if you crash. The final `catch` or the last point-in-time, before your game goes down. Fatal = crash
Master	!	✔	✔	✔	Kind of a special level, this can also be seen as the `force` level (but "f" was already used by "fatal", so I needed another word. Writing a log at this level will appear always in the log, no matter which configuration or filter is set. `raptor` only prints a handful of lines on this level, like the "Game starting" and "Game stopping" messages or the own game version string, which should be part of the log file, no matter in which configuration, so you can always see, which version of the game the player had, when you receive a crash report

Writing a log line

It's as easy as using show_debug_message, but instead of writing this long function name a thousand times in your game, you access the Logger through macros, which also set the Log Level in one go.

#macro	Description
vlog	Log a `verbose` line
dlog	Log a `debug` line
ilog	Log a `info` line
wlog	Log a `warning` line
elog	Log a `error` line
flog	Log a `fatal` line
mlog	Log a `master` line

Examples

Here are some examples from the source code of raptor, how it writes its logs:

// Example 1: during load process of a savegame file
ilog($"Restoring RaceController links...");
// ... do some stuff
// ... look for something critical, and if not found...
} else {
	elog($"*ERROR* Could not restore RaceController link: ID {cid} not found!");
}

// Example 2: The "mouse enter" event of a _baseControl
vlog($"{MY_NAME}: onMouseEnter");

// Example 3: Dumping a buffer in a loop
ilog($"-- [BUFFER_DUMP_START] ({buffer_get_size(buffer)} bytes) --");
//... do some stuff again ...	
	ilog($"{outline} {human}");
ilog($"{outline} {string_repeat(" ", length)} {human}");
ilog($"-- [BUFFER_DUMP_END] --");

Next, you should take a look at the Logger Configuration.