DD Poker Debugging Tools and Settings: A Complete Developer Guide

DD Poker provides a property-driven debugging framework centered around DebugConfig.TESTING() that lets developers toggle diagnostics via configuration files without recompiling, supplemented by shell scripts for thread dumps and load testing.

The dougdonohoe/ddpoker repository includes a lightweight, runtime-configurable debugging system designed for Java development. Developers can activate detailed diagnostics across the client, server, and web applications by modifying property files rather than changing source code or rebuilding. This guide covers the complete suite of debugging tools and settings available, from the central configuration evaluator to convenience scripts in tools/bin.

The DebugConfig Evaluation Framework

At the heart of DD Poker's debugging system is DebugConfig, located in code/common/src/main/java/com/donohoedigital/config/DebugConfig.java. This utility evaluates a global master flag, settings.debug.enabled, to determine whether any diagnostic code should execute.

When the JVM starts, DebugConfig.isTestingOn() checks this global flag. If disabled, every call to DebugConfig.TESTING(String) short-circuits to false with zero runtime overhead. When enabled, the framework fetches individual debug properties via PropertyConfig.getBooleanProperty() and caches the results in a Map<String, Boolean> to avoid repeated I/O operations.

Checking Debug Flags in Java Code

Modules reference debug constants to keep code self-documenting. For example, the poker engine checks repaint activity using constants defined in PokerConstants.java:

import com.donohoedigital.config.DebugConfig;
import com.donohoedigital.games.poker.engine.PokerConstants;

if (DebugConfig.TESTING(PokerConstants.TESTING_REPAINT)) {
    logger.debug("Repaint of component " + component.getName());
}

Configuration Properties and Override System

DD Poker loads a hierarchy of property files specific to each application type—client, server, webapp, or command-line. Debug flags reside under the settings.debug.* namespace, with defaults defined in code/pokerengine/src/main/resources/config/poker/common.properties.

Developers personalize settings by creating config/override/<username>.properties, which loads after the defaults. This allows local activation of debug features without affecting team members or committing changes to version control.

Key Debug Constants and Flags

The system defines specific boolean flags in PokerConstants.java and EngineConstants.java:

• settings.debug.repaint – Visualizes Swing repaint boundaries for UI optimization
• settings.debug.dougcontrolsai – Allows human control over AI players during testing
• settings.debug.pots – Prints detailed pot-level calculation information
• settings.debug.autopilot – Forces AI players to make automatic decisions immediately
• settings.debug.docmode – Enables static website generation mode for offline documentation

Enabling Debug Flags in Your Properties File

Create or edit your personal override file to activate diagnostics:

# config/override/jdoe.properties

settings.debug.enabled=true
settings.debug.repaint=true
settings.debug.dougcontrolsai=true
settings.debug.pots=true

Restart the application after editing; properties are read only at startup.

Development Utility Scripts

The tools/bin directory contains shell scripts that streamline common debugging tasks without manual JVM configuration.

Capturing Thread Dumps with threaddump

The threaddump script attaches the JDB debugger to a running JVM and outputs complete stack traces for all threads. This is essential for diagnosing deadlocks or performance bottlenecks in the poker server.

# Default JDI port is 5432

tools/bin/threaddump

Running Classes with runjava

The runjava wrapper launches any compiled class with the correct classpath derived from per-module classpath.txt files. This ensures consistent library loading across development environments.

# Launch the poker client

tools/bin/runjava poker PokerMain

# Launch the server

tools/bin/runjava pokerserver PokerServerMain

Load Testing with testmany

For concurrency testing, testmany spawns multiple parallel client instances against a target server. Each tester logs to log/test_testclientN.log, making it straightforward to identify race conditions.

# Launch 10 tester clients against local server

tools/bin/testmany http://localhost:8080 testclient 10

Static Site Generation with generate-website

When settings.debug.docmode is enabled, the generate-website script builds a static copy of the website for offline inspection and documentation review.

Summary

• DebugConfig.java provides zero-cost debug checks when disabled and efficient caching when enabled via settings.debug.enabled.
• Property overrides in config/override/<username>.properties allow per-developer configuration without recompilation.
• Specific debug flags like settings.debug.repaint and settings.debug.dougcontrolsai control UI visualization and AI behavior.
• Utility scripts including threaddump, runjava, and testmany support runtime introspection, proper classpath management, and load testing.

Frequently Asked Questions

How do I enable debugging without recompiling DD Poker?

Add settings.debug.enabled=true to your personal override file at config/override/<username>.properties, then restart the JVM. The DebugConfig class reads these properties at startup, allowing you to toggle any settings.debug.* flag without touching source code or build files.

Where are the debug flag constants defined?

Debug constants are centralized in code/pokerengine/src/main/java/com/donohoedigital/games/poker/engine/PokerConstants.java and code/gamecommon/src/main/java/com/donohoedigital/games/config/EngineConstants.java. These files define string keys like TESTING_REPAINT that map to property names such as settings.debug.repaint.

How can I capture a thread dump from a running DD Poker server?

Use the tools/bin/threaddump script, which automates JDB attachment to the JVM (default port 5432) and prints stack traces for all threads. This is the recommended method for diagnosing live server deadlocks or thread contention issues.

What is the performance impact of leaving debug checks in production code?

When settings.debug.enabled is false, DebugConfig.TESTING() returns immediately with no measurable overhead. The framework is designed for zero-cost abstractions in production, incurring I/O costs only when the global flag is explicitly enabled and properties are cached after first access.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}