Debug Logging Guide¶

This document explains how to enable and disable the debug logging built into Ansible Crafting.

Overview¶

The mod uses two SLF4J loggers (backed by Minecraft's Log4j2):

By default, Minecraft's Log4j2 configuration sets the root level to INFO, so all LOGGER.debug(...) calls are suppressed. To see them, you need to lower the log level to DEBUG for the relevant logger names.

Enabling Debug Logging¶

Method 1: Custom Log4j2 Config File (Recommended)¶

1. Create a file called log4j2-debug.xml in the project root:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="SysOut" target="SYSTEM_OUT">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level] [%logger]: %msg%n"/>
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="ansiblecrafting" level="DEBUG" additivity="false">
            <AppenderRef ref="SysOut"/>
        </Logger>
        <Logger name="com.ansiblecrafting.client.HighlightRenderer" level="DEBUG" additivity="false">
            <AppenderRef ref="SysOut"/>
        </Logger>
        <Root level="INFO">
            <AppenderRef ref="SysOut"/>
        </Root>
    </Loggers>
</Configuration>

1. Add the JVM argument to your Fabric Loom run configuration in build.gradle:

loom {
    runs {
        client {
            vmArgs "-Dlog4j2.configurationFile=log4j2-debug.xml"
        }
        server {
            vmArgs "-Dlog4j2.configurationFile=log4j2-debug.xml"
        }
    }
}

1. Run the game normally via ./gradlew runClient or ./gradlew runServer.

Method 2: Quick One-Off via Command Line¶

Pass the system property directly without modifying build.gradle:

./gradlew runClient --jvm-args="-Dlog4j2.configurationFile=log4j2-debug.xml"

Method 3: Programmatic (Runtime Toggle)¶

If you need to toggle debug logging at runtime without restarting:

import org.apache.logging.log4j.Level;
import org.apache.logging.log4j.core.config.Configurator;

// Enable debug
Configurator.setLevel("ansiblecrafting", Level.DEBUG);

// Disable debug (back to INFO)
Configurator.setLevel("ansiblecrafting", Level.INFO);

This could be wired to a command or config option if needed.

Disabling Debug Logging¶

• If using Method 1: Remove the vmArgs line from build.gradle (or delete/rename log4j2-debug.xml).
• If using Method 2: Simply omit the --jvm-args flag.
• If using Method 3: Call Configurator.setLevel("ansiblecrafting", Level.INFO).

No code changes are needed — all debug logging is already guarded by LOGGER.isDebugEnabled() checks or uses LOGGER.debug() which is a no-op at INFO level.

What Gets Logged¶

When debug is enabled, you'll see output for:

• Inventory scanning — which inventories were found, how many stacks collected
• Network sync — packets sent/received for inventory data and state
• Crafting sessions — grid slot sources, item extraction/insertion from nearby containers
• Toggle events — inventory enable/disable with validation details
• Recipe integration — EMI/REI recipe handler decisions, virtual inventory population
• Container detection — how the mod identifies which container the player is looking at
• Item return on close — detailed slot-by-slot return of items to source containers
• Highlight rendering — highlight group creation and expiry