Debugger Plugin

In artemis-odb-contrib 2.5.0-SNAPSHOT, release planned for artemis-odb 2.3.0. Desktop only

Introduction

The debugging plugin helps you diagnose common mistakes by accessing entities at the wrong moment in their lifecycle. It can report illegal access, and the line of code that caused it.

*********************
SunnySalamander(1) ERROR_ATTEMPT_TO_DELETE_DELETED_ENTITY @ ..DebugSystem.onEntityDeleteIssued(DebugSystem.java:53)
Cause (Already deleted at):
SunnySalamander(1) DELETE @ net.mostlyoriginal.plugin.DebugSystem.onEntityDeleteIssued(DebugSystem.java:59)
*********************

Entities are given a lifetime unique name to easily identify them. There is a significant performance cost when the plugin is active due to stack trace generation (and logging).

Artifact

    <parent>
        <groupId>net.mostlyoriginal.artemis-odb</groupId>
        <artifactId>contrib-plugin-debug</artifactId>
        <version>2.5.0-SNAPSHOT</version>
    </parent>

Usage

Pick one of these to enable this plugin

   // Only reports errors in systems under package net.mostlyoriginal. Logs to stdout.
   WorldConfigurationBuilder.with(DebugPlugin.thatLogsErrorsIn("net.mostlyoriginal"))

   // Reports all system events in systems under package net.mostlyoriginal. Logs to stdout.
   WorldConfigurationBuilder.with(DebugPlugin.thatLogsEverythingIn("net.mostlyoriginal"))

   // turn it off during runtime. Logs to stdout.
   WorldConfigurationBuilder.with(DebugPlugin.thatLogsEverythingIn("net.mostlyoriginal").enable(false)) 

   // For advanced users. You can provide your own logging strategies.
   WorldConfigurationBuilder.with(new DebugPlugin(new MyDebugLogStrategy()));

Can I access debug information in game?

Yes. When the debugger is active all entities have a DebugComponent.

public class DebugComponent extends Component {

    // stacktrace of the creation callsite for this entity.
    public DebugEventStacktrace creationStacktrace;

    // stacktrace of the deletion callsite for this entity (or NULL if none).
    public DebugEventStacktrace deletionStacktrace;

    /** Generated lifecycle name. */
    public String name = AnimalNameGenerator.random();

    /** tracks if deletion has been finalized by the engine. */
    public boolean entityDeletionFinalized =false;

    public boolean isEntityDeleted() {
        return deletionStacktrace != null;
    }
}