This page documents some ways of logging and outputting text in the game, both within the engine and scripts. This is useful to know for debugging and when the user should be notified of something.

= Engine =

The [wiki:Coding_Conventions#Errorreporting coding conventions] have some information regarding logging in the engine.

The engine is written in C++. Prefer the following functions for logging and outputting text:

 * `LOGMESSAGE(const char* format, ...)`
 * `LOGMESSAGERENDER(const char* format, ...)`

Use these functions to report possible misconfigurations or errors that can be caused by modding:

 * `LOGWARNING(const char* format, ...)`
 * `LOGERROR(const char* format, ...)`
 * `debug_printf(const char* format, ...)`

||= '''Function''' =||= '''Game console''' =||= '''Rendered message''' =||= '''Main log''' =||= '''Interesting log''' =||= '''stdout'''^[#footnote1 (1)]^ =||= '''stderr''' =||
||`LOGMESSAGE` ||  N  ||  N  ||  Y  ||  N  ||  N  ||  N  ||
||`LOGMESSAGERENDER` ||  Y  ||  Y - green text  ||  Y  ||  N  ||  N  ||  N  ||
||`LOGWARNING` ||  Y  ||  Y - yellow text  ||  Y  ||  Y  ||  Y  ||  N  ||
||`LOGERROR` ||  Y  ||  Y - red text  ||  Y  ||  Y  ||  Y  ||  N  ||
||`debug_printf` ||  N  ||  N  ||  N  ||  N  ||  Y  ||  N  ||

'''Note:''' to use the `LOG*` functions, you must include [source:/ps/trunk/source/ps/CLogger.h ps/CLogger.h].[[BR]]

= Scripts =

The game's scripts are written in JavaScript, but they won't necessarily have the same functions available as in a web browser. Use these functions for outputting text:

 * `print(message)`
 * `console.write(message)`
 * `log(message)`
 * `warn(message)`
 * `error(message)`

||= '''Function''' =||= '''Game console''' =||= '''Rendered message''' =||= '''Main log''' =||= '''Interesting log''' =||= '''stdout'''^[#footnote1 (1)]^ =||= '''stderr''' =||
||`print` ||  N  ||  N  ||  N  ||  N  ||  Y  ||  N  ||
||`console.write` ||  Y  ||  N  ||  N  ||  N  ||  N  ||  N  ||
||`log` ||  N  ||  N  ||  Y  ||  N  ||  N  ||  N  ||
||`warn` ||  Y  ||  Y - yellow text  ||  Y  ||  Y  ||  Y  ||  N  ||
||`error` ||  Y  ||  Y - red text  ||  Y  ||  Y  ||  Y  ||  N  ||
 
[[Debugging#Debuggingscripterrors|Debug]] by inserting logging functions.
{{{#!sh
# Most commonly used debug messages

# Print an unknown variable
warn(uneval(arg))

# Print a debug message with several arguments.
warn(uneval([arg1, arg2]))

# Similar to uneval, but it does not show functions in that object
warn(JSON.stringify(object))

# Create a stack trace of the JavaScript call stack at the moment that the Error object was created.
warn(new Error().stack)

# Petra AI: automatically uneval and include the player ID
API3.warn(arg)
}}}

= Atlas UI =

In Atlas UI, wxWidgets provides several [http://docs.wxwidgets.org/trunk/overview_log.html logging functions].
 * `wxLogDebug(const char* formatString, ...)` - Logs to terminal/debug output only.
'''Note:''' by default, the following functions only display a message box to the user:
 * `wxLogMessage(const char* formatString, ...)`
 * `wxLogWarning(const char* formatString, ...)`
 * `wxLogError(const char* formatString, ...)`

----

[=#footnote1 ^(1)^] On Windows, the game writes debug output instead of stdout. Run the game in a debugger or use [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx DebugView] to view it.[[BR]]