Log & Debugging

Logging

CosPlay games are terminal-based hence they require a different approach to logging. When developing a game in IDE you can technically use basic println(...) statements or logging library but when running the same game in the native terminal the standard console log output will conflict with the game rendering. You would need to remove these statements or comment them out making the whole process cumbersome and error-prone...

Because of these reasons, CosPlay provides special mechanism for logging. CosPlay logging is defined by CPLog trait. This trait provides standard logging API that is almost identical to Log4j or similar libraries. The instance of CPLog trait is available via two methods:

• CPSceneObjectContext.getLog - to obtain the current log for the scene object being updated.
• CPEngine.getRootLog - to obtain the root category log from the game engine.

Regardless of how the log instance has been obtained all the log output that goes through this interface always ends up in two places:

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

Note that additionally to the standard familiar logging APIs the CPLog trait supports log throttling. This is important in game development since most of the game logic gets touched up to 30 times a second and log throttling is essential for avoiding log overflow.

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/${sys:COSPLAY_GAME_ID}/log/log.txt"
                            filePattern="${sys:user.home}/.cosplay/${sys:COSPLAY_GAME_ID}/log/$${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>
        

NOTE:

• The COSPLAY_GAME_ID system property used by the Log4J configuration is set automatically by the game engine. You can use this system property in your own configuration.

FPS Overlay

By pressing Ctrl+Q in any game you can toggle in-game FPS overlay. FPS overlay shows up in the right top corner displaying essential rendering statistics like current FPS, average FPS, low 1% FPS, system and user time in milliseconds:

Debugging

By pressing keyboard shortcut Ctrl+L you can open GUI-based log viewer and debugger. Note that you can also open this log viewer and debugger programmatically via CPEngine.openLog() method:

In the log viewer and debugger you can perform various log and game related functions:

• Pause, resume, clear and close log viewer.
• Search paused log:
  • Log must be paused for searching.
• Show basic rendering metrics.
• Pause and resume game audio.
• Pause, resume and stop the game.
• Debug step through one frame at a time for the paused game:
  • Game must be paused for debugging.
  • You can also simulate a keyboard event on each frame during debugging.
• Change the UI themes.
• Toggle individual log levels to show on the log viewer.
  • Note that *.txt log files under ${USER_HOME}/.cosplay/${sys:COSPLAY_GAME_ID}/log/xxx directory will always contain all log level regardless of the selection made in the log viewer. This selection only affect the GUI-based log viewer itself.