The BYOND Debug Messenger

#include <airmapster/debugmessenger>

• DEBUGFILE

  The Debug Messenger works by saving all of your debugging output to a text file on the player's machine. This is the name of that file. You must define this! Best to make it something unique so it doesn't overwrite anything else that may be in the game directory. Example:

  #define DEBUGFILE "mygamedebug.log"

• DEBUGHREF

  This is the BYOND address of your debug server that you determined above. Example:

  #define DEBUGHREF "byond://123.45.678.9:4321"

• DebugMsg(T)

  T: the text of the debug message

  This proc logs a debug message. As long as DEBUGFILE is defined above, that message will be appended to the debug file. Additionally, if debugging is turned on for the project (#define DEBUG), the debug message will be sent to world.log. Any time you need to output a debugging message, use this proc.

  Debug messages are always prepended with the world.time value.

• BugMsg(T)

  T: the text of the bug message

  This proc is the same as DebugMsg (in fact, it calls DebugMsg(T)) except that it also increments a global "bugs" counter. Additionally, it prepends the text "BUG: " to the message. Use this proc when you encounter a situation in your code that you know for sure is a bug.

The Debug Messenger keeps a global var called bugs which counts the total number of known bugs that occur in the game. It is incremented any time you call BugMsg(). When the world shuts down, it checks to see if there were any bugs encountered during the game. If so, the entire debug log (all DebugMsg() and BugMsg() calls) will be sent over the network to your debug server.

This example world illustrates usage of the Debug Messenger:

#define DEBUGFILE "myworld.debug"
#define DEBUGHREF "byond://123.45.678.9:4321"

#include <airmapster/debugmessenger>

mob
    var/playing = FALSE
    Login()
        . = ..()
        DebugMsg("[src] logged in, playing is [src.playing]")
    Logout()
        DebugMsg("[src] about to logout, playing is [src.playing]")
        . = ..()
    Stat()
        if (!src.playing) // playing should always be TRUE
            BugMsg("[src] is not playing!")
        else
            stat("You are in the game")


In the above example, we expect the mob variable "playing" to always be true when the player is in the game. Thus if it's false in a Stat() operation, that must be a bug, so we call BugMsg(). We also call DebugMsg() in mob/Login() and mob/Logout() to show the value of the mob's playing var. This should give us enough information to figure out why the bug (playing not true) is showing up: we never set it to TRUE!

When run, every call to BugMsg() will increment the bugs count, ensuring that the entire debug log is sent to our Debug Server. When we check the server directory for new log files, we'll see this and fix the problem by setting the mob's playing var to TRUE in mob/Login(). When we distribute the fixed game to players, we won't get any more log files because that BugMsg() will never be called, even though DebugMsg() is still being called. In this case, the game will automatically delete any log file on the player's machine when the world shuts down.

Finally, if you wish to receive debug logs even when no known bugs are encountered, simply set the global variable "bugs" to a nonzero value in world/New().