Chapter 2: Debugging

Built in Debugging!

Debug Information

The easiest way to debug in Activerse is by enabling the debug button in activerse.properties (by default it should be disabled. Once this is enabled, whenever you start a new instance of Activerse (by running Main as seen in Chapter 1), a "debug" button will appear.

Figure 1: The debug button in Activerse.

When you click this button, the following information should show up:

• Current FPS w/target FPS
• Memory Per Second (MPS or in v1.1.0, MUPS)
• Any non-static actors w/collision state & location
• Loaded images
• Current playing sounds
• Current keys pressed

You can use this information to debug anything in the program that may be causing issues. The debug menu will not show error messages if you have syntax errors; these should be caught at compile time or run time (depending on the error) and will display on the terminal you run the program in.

Figure 2: Debug information displayed in Activerse.

Using different debug information

Using FPS

If you have many objects loaded into the screen, lots of audio playing, loops or other situations where you think frames may be dropping, you can check the current FPS in-game via the debug menu. You can see my FPS is low because I have hundreds of images loaded in.

Using MPS

Introduced in v1.1, MPS or Memory Per Second shows you the state of RAM being used every second in megabytes. If you wish, via the activerse.properties file, you may enable the logging feature which will write the MPS with the time before it.

You may see negative numbers sometimes in MPS and this is due to the JVM automatic garbage collector, helping manage your memory.

Your MPS can be used with FPS to diagnose memory leaks in the program, unstable or inefficient code, and other things related.

Using loaded Actors w/Collision States

You can check if your actor has indeed loaded into the world via the loaded actor information, which shows the actor's location (pixel-wise) and if they are colliding with another actor or not. This can be useful in game sense when your actors may not be performing the actions you wish.

Using loaded images & video

This information is really only useful when you don't see your image or hear your audio and want to make sure the file has been loaded in and playing. If you have multiple of the same image loaded, it will shown [imagename].png x [number of times loaded].

Note: As of v1.4.0, static Actors (ex World tiles) are no longer shown on the debug menu to prevent overfilling of the debug menu.

Using current keys pressed

This information is only useful if you're tinkering with the KeyboardInfo.java class inside the ActiverseEngine package (not recommended). If you're pressing a key and it's not being detected, something has gone wrong inside that class.

Logging

How can I enable logging?

Your logging file should look like this by default.

Figure 2: Default activerse.properties file.

To enable logging, just change the false value beside logging to true.

What information is displayed?

When you start, logs.log should look like this (v1.3.x Logging Reform):

Figure 3: Sample logs.log output.

Lot's of information is logged for your convinience. As shown above, during each new log session, the session info will be denoted followed by the actual logs. The format is as shown below:

(LOG ENTRIES IN SESSION) | (TIME HH/MM/SS) | MPS (x MB/s) | Heap: (x MB) | Non-Heap: (x MB) | GC Time: (x ms) | FPS: (x) targeting (y) | Sys Time (x long) | Interval (x)
    

The information shown here is calculated the same way as the debug menu, but is logged to a file for your convinience. We also have a lot more information here that cannot be found in debug menu; however, the logs do NOT show loaded images, sounds, or actor collision states.

It is NOT recommended for you to share your logs file with people you don't know. While Activerse doesn't log any sensitive information, there are plans for Activerse to log system-specific information in the future.