Custom Debugging Log File Generator in GML

/*** Custom Debugging Log File Generator ***
This set of scripts replaces show_debug_message() in GML and creates a custom log file that holds a lot more information than a simple show_debug_message(). Here's an example output of a log file:





********* THE LOG FILE *********/

-- SPECS START --

Logfile Name: Y:\Spaceslingers_Steam_Version_6AE9EECB_YYC\\Log\log_14112020133855.logfile
Log Time: 14-11-2020(13h-38m-55s)
Game Version: 0.95 // This is the game version you've entered under the Options settings in GMS
OS Version: 655360
OS Language: en
OS Region: AU
OS Data: // Read this page for info on the below numbers: http://127.0.0.1:51290/index.html?page=source%2f_build/3_scripting%2f4_gml_reference%2fmiscellaneous%2fos_get_info.html
838866018
bd496841-475e-4ff4-8ce2-da95a970930e
4318
072B1308
072B04FC
5121
2189754368
161
NVIDIA GeForce GTX 960
0
Working Dir: Y:\Spaceslingers_Steam_Version_6AE9EECB_YYC\
Steam User: euphoria_syndrome
Steam User ID: 111111111111111
Steam Account Cloud Enabled: 1
Steam Game Cloud Enabled: 1
Steam Cloud Quota Available: 4992948
Steam Available Languages: english
Steam Current Game Language: english
Steam User Logged On: 1

-- SPECS END --


--- LOG START ---

** Running Time 418 ** // 418 milliseconds since the game was booted
This is an info log. // INFO -- Callstack:
>>gml_Object_master_Create_0:159 // Called from an object called master, in the Create Event at line 159

** Running Time 423 **
This is an error log. // ERROR -- Callstack:
>>gml_Object_master_Create_0:160 // Called from an object called master, in the Create Event at line 160

** Running Time 428 **
This is an error log inside a script named load_steam_save(). // ERROR -- Callstack:
>>>>gml_Script_load_steam_save:5 // Called from inside a script called load_steam_save at line 5
>>gml_Object_master_Create_0:162 // load_steam_save script was called from an object called master, in the Create Event at line 162

** Running Time 591 **
This is a log in another object called obj_title. // ERROR -- Callstack:
>>gml_Object_obj_title_Create_0:4 // Called from an object called obj_title, in the Create Event at line 4

--- LOG END ---

/********* END OF LOG FILE *********





As you can see, it gathers information about the computer itself so you can see what specs the player is running, and it gives you the error/info message you were asking for alongside the callstack where it was generated. It requires 3 scripts to function properly, log_ini(), log() [which is the replacement for show_debug_message()] and log_quit() [this one is not entirely necessary, but it'll show you if the user quit the game on purpose or if the game completed crashed].

The log_ini() script takes a single argument, which is whether to turn a global boolean called global.debug on or off. If global.debug is set to true, then alongside the log file, GMS will also output a show_debug_message() with the same info to your console. If it's false, the only the log file will be created. Run log_ini in whatever object is first created in the game.





********* START OF log_ini() SCRIPT *********/

///@function log_ini(debug_mode);
///@description Initialises the log file
///@param {bool} debug_mode

global.debug = argument0;

var _time = string(current_day)+"-"+string(current_month)+"-"+string(current_year)+"("+string(current_hour)+"h-"+string(current_minute)+"m-"+string(current_second)+"s)"; // The time the log file was generated
var _filekey = string(current_day)+string(current_month)+string(current_year)+string(current_hour)+string(current_minute)+string(current_second);
var _fname = "log_"+string(_filekey)+".logfile"; // The logfile name is based off what time it was created.
global.logfile_name = working_directory+"\\Log\\"+_fname; // Change this if you want the logfile to be stored somewhere other than a folder called Log
var _game_version = global.version;
var _os_version = os_version;
var _os_lang = os_get_language();
var _os_region = os_get_region();
var _os_map = os_get_info();
var _map_data = [];
if (_os_map != -1) {
    var size, key, i;
    size = ds_map_size(_os_map);
    key = ds_map_find_first(_os_map);
   for (i = 0; i < size - 1; i++;) {
        _map_data[i] = ds_map_find_value(_os_map, key);
        key = ds_map_find_next(_os_map, key);
    }
    ds_map_destroy(_os_map);
}
var _str =  "-- SPECS START --\n\n"+
            "Logfile Name: "+string(global.logfile_name)+"\n"+
            "Log Time: "+string(_time)+"\n"+
            "Game Version: "+string(_game_version)+"\n"+
            "OS Version: "+string(_os_version)+"\n"+
            "OS Language: "+string(_os_lang)+"\n"+
            "OS Region: "+string(_os_region)+"\n"+
            "OS Data: \n";

for (var i=0;i<array_length_1d(_map_data);i++) {
    _str += string(_map_data[i])+"\n";
}

_str += "Working Dir: "+string(working_directory)+"\n";

// This next section is only necessary if you are using Steam and need info on the Steam player

if (steam_initialised()) {
    _str +=     "Steam User: "+string(steam_get_persona_name())+"\n"+
                "Steam User ID: "+string(steam_get_user_steam_id())+"\n"+
                "Steam Account Cloud Enabled: "+string(steam_is_cloud_enabled_for_account())+"\n"+
                "Steam Game Cloud Enabled: "+string(steam_is_cloud_enabled_for_app())+"\n"+
                "Steam Cloud Quota Available: "+string(steam_get_quota_free())+"\n"+
                "Steam Available Languages: "+string(steam_available_languages())+"\n"+
                "Steam Current Game Language: "+string(steam_current_game_language())+"\n"+
                "Steam User Logged On: "+string(steam_is_user_logged_on());
}

// Steam info section ended

_str += "\n\n-- SPECS END --\n\n\n--- LOG START ---\n";

var file = file_text_open_write(global.logfile_name);
file_text_write_string(file,_str);
file_text_writeln(file);
file_text_close(file);

/********* END OF log_ini(debug_mode) SCRIPT *********





The next script is the log(text,log_type) script, which is the meat and potatoes of the script set. Use it in place of show_debug_message(). It takes two arguments, text, which is the text you want displayed for this log line and log_type, which is an enum and lets you differentiate between actual errors and things you want to keep track of. By default the enum has two values: log_type.INFO and log_type.ERROR but you could add more to the enum if you wanted. Call it like this: log("This is the text you want saved to the log",log_type.INFO) from anywhere you want after log_ini(debug_mode) has been called. If debug_mode is true, this will also trigger a show_debug_message() with the contents, but if not it won't.





********* START OF log(text,log_type) SCRIPT *********/

///@function log(msg,type);
///@description Logs an entry into the debug list
///@param {string} msg The message to log
///@param {enum} type The type of entry

enum log_type { // Add enums below if you want to have different log_types
    INFO,
    ERROR
}

var msg = argument0;
var type = argument1;
var type_str = "";
var log_str = "";
var _ctime = string(current_time);

switch (type) { // If you've added enums, then also add a case for the enum with what text to call it
    case log_type.INFO:
        type_str = "INFO";
    break;
    case log_type.ERROR:
        type_str = "ERROR";
    break;
}

log_str = "** Running Time "+string(_ctime)+" **\n"+msg+"
log_str += " -- Callstack:";
var _stack = debug_get_callstack();
var _stacklen = array_length_1d(_stack)-1;
for (var i=1;i<_stacklen;i++) {
    log_str += "\n";
    repeat ((_stacklen)-i) {
        log_str += ">>";
    }
    log_str += string(_stack[i]);
}

log_str += "\n";
var file = file_text_open_append(global.logfile_name);
if (file_exists(global.logfile_name)) {
    file_text_write_string(file,log_str);
    file_text_writeln(file);
    file_text_close(file);
    if (global.debug) {
        show_debug_message(log_str);
    }
}
else { // This only triggers if the log file is not writeable for some reason. Never happened to me
    file = file_text_open_write(working_directory+"\\Logfile_not_found.logfile");
    if (file_exists(working_directory+"\\Logfile_not_found.logfile")) {
        file_text_write_string(file,"Tried to write to "+string(global.logfile_name)+" and file was not accessible. Original log error was:\n\n"+log_str);
    }
    file_text_close(file);
}

/********* END OF log(text,log_type) SCRIPT *********





Then finally we have the log_quit() script, which is simply a closer to the log file so that you know if the game ended naturally through the Game End Event or if it crashed to desktop. Call it from a persistent object in the Game End Event.





********* START OF log_quit() SCRIPT *********/

///@function log_quit();
///@description Adds a closer to the log file

var _str = "--- LOG END ---";

var file = file_text_open_append(global.logfile_name);
file_text_write_string(file,_str);
file_text_writeln(file);
file_text_close(file);

/********* END OF log_quit() SCRIPT *********




That's it. Add these files as scripts named appropriately and start using log() instead of show_debug_message() and you'll be able to store much more information about anything potentially going wrong that you're checking for. */