CPLog

trait CPLog

Game logging interface.

As CosPlay games are terminal-based they require a different approach to logging since CosPlay cannot use the standard terminal output (it will conflict the game rendering). All the log that goes through this interface always ends up in two places:

  • Built-in GUI-based log viewer that can be opened in any game by pressing Ctrl-l at any time.
  • In *.txt log files under ${USER_HOME}/.cosplay/log/xxx directory, where xxx is the name of the game.

The instance of this logger is available to any scene object via CPSceneObjectContext.getLog. You can also get a root logger at any time outside the frame update pass via CPEngine.rootLog method. Note that additionally to the standard familiar logging APIs this interface supports log throttling that's important in games since most of the game logic gets "touched" up to 30 times a second and log throttling is essential for not overflowing logging.

Underneath the implementation is using latest Log4j2 library. You can supply your own log4j2.xml file on the classpath of your game. Here's the default Log4j2 configuration:

<Configuration status="INFO" strict="true">
   <Appenders>
       <RollingFile
           name="file"
           fileName="${sys:user.home}/.cosplay/log/${sys:COSPLAY_GAME_NAME}/log.txt"
           filePattern="${sys:user.home}/.cosplay/log/${sys:COSPLAY_GAME_NAME}/$${date:yyyy-MM}/log-%d{MM-dd-yyyy}-%i.gz">
           <PatternLayout>
               <Pattern>%d %p %c{1.} [%t] %m%n</Pattern>
           </PatternLayout>
           <Policies>
               <TimeBasedTriggeringPolicy />
               <SizeBasedTriggeringPolicy size="250 MB"/>
           </Policies>
       </RollingFile>
   </Appenders>
   <Loggers>
       <Root level="trace">
           <AppenderRef ref="file"/>
       </Root>
   </Loggers>
</Configuration>
See also:
Source:
CPLog.scala
class Object
trait Matchable
class Any

Value members

Abstract methods

def getCategory: String

Gets category for this logger.

Gets category for this logger.

Source:
CPLog.scala
def getLog(category: String): CPLog

Gets a new logger for given category. New logger will inherit log levels and throttle value.

Gets a new logger for given category. New logger will inherit log levels and throttle value.

Value parameters:
category

Category for new logger.

Source:
CPLog.scala
def log(nthFrame: Int, lvl: CPLogLevel, obj: Any, cat: String, ex: Exception): Unit

Logs given message with throttling and explicit category.

Logs given message with throttling and explicit category.

Value parameters:
cat

Explicit log category.

ex

Exception to log. Can be null.

lvl

Log level.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala

Concrete methods

def debug(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.DEBUG level.

Logs object with CPLogLevel.DEBUG level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def debugx(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.DEBUG level and throttling.

Logs object with CPLogLevel.DEBUG level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
def disable(lvls: CPLogLevel*): Unit

Disables given log level for logging.

Disables given log level for logging.

Value parameters:
lvls

Log levels to disable.

Source:
CPLog.scala
def enable(lvls: CPLogLevel*): Unit

Enables given log level for logging.

Enables given log level for logging.

Value parameters:
lvls

Log levels to enable.

Source:
CPLog.scala
def error(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.ERROR level.

Logs object with CPLogLevel.ERROR level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def errorx(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.ERROR level and throttling.

Logs object with CPLogLevel.ERROR level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
def fatal(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.FATAL level.

Logs object with CPLogLevel.FATAL level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def fatalx(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.FATAL level and throttling.

Logs object with CPLogLevel.FATAL level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
def getThrottle: Int

Gets current throttle value.

Gets current throttle value.

Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored. For example, setting throttling to 10 means that logging will happen only every 10th frame.

Source:
CPLog.scala
def info(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.INFO level.

Logs object with CPLogLevel.INFO level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def infox(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.INFO level and throttling.

Logs object with CPLogLevel.INFO level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
protected def inheritFrom(log: CPLog): Unit
def isEnabled(lvl: CPLogLevel): Boolean

Tests whether given log level is enabled.

Tests whether given log level is enabled.

Value parameters:
lvl

Log level to check.

Source:
CPLog.scala
def log(nthFrame: Int, lvl: CPLogLevel, obj: Any, ex: Exception): Unit

Logs given message with throttling. This method will use this log's category.

Logs given message with throttling. This method will use this log's category.

Value parameters:
ex

Optional exception to log. Default value is null.

lvl

Log level.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
def setThrottle(nthFrame: Int): Unit

Sets the throttling value.

Sets the throttling value.

Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored. For example, setting throttling to 10 means that logging will happen only every 10th frame.

Value parameters:
nthFrame

Throttle value.

Source:
CPLog.scala
def snapshot(): Unit

Logs rendering performance snapshot, if available from the game engine.

Logs rendering performance snapshot, if available from the game engine.

When debugging a performance issue with the game, it is often useful to periodically log game engine performance metrics like actual FPS, LOW 1%, etc. to analyze them later in log files in correlation with other game activity. This is a convenient method to quickly log a snapshot of the current game engine performance numbers.

Source:
CPLog.scala
def trace(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.TRACE level.

Logs object with CPLogLevel.TRACE level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def tracex(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.TRACE level and throttling.

Logs object with CPLogLevel.TRACE level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala
def warn(obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.WARN level.

Logs object with CPLogLevel.WARN level.

Value parameters:
ex

Optional exception to log. Default value is null.

obj

Object to log.

Source:
CPLog.scala
def warnx(nthFrame: Int, obj: Any, ex: Exception): Unit

Logs object with CPLogLevel.WARN level and throttling.

Logs object with CPLogLevel.WARN level and throttling.

Value parameters:
ex

Optional exception to log. Default value is null.

nthFrame

Throttle value. Throttle value N simply means that actual logging will only happen for each Nth frame. Logging for all other frames will be ignored.

obj

Object to log.

Source:
CPLog.scala