# DD Poker Debugging Tools and Settings: A Complete Developer Guide

> Explore DD Poker debugging tools and settings. Leverage property-driven diagnostics and shell scripts for efficient thread dumps and load testing. Master development with this comprehensive guide.

- Repository: [Doug Donohoe/ddpoker](https://github.com/dougdonohoe/ddpoker)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/dougdonohoe/ddpoker/blob/main/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`](https://github.com/dougdonohoe/ddpoker/blob/main/PokerConstants.java):

```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`](https://github.com/dougdonohoe/ddpoker/blob/main/PokerConstants.java) and [`EngineConstants.java`](https://github.com/dougdonohoe/ddpoker/blob/main/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:

```properties

# 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.

```bash

# 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`](https://github.com/dougdonohoe/ddpoker/blob/main/classpath.txt) files. This ensures consistent library loading across development environments.

```bash

# 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.

```bash

# 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`](https://github.com/dougdonohoe/ddpoker/blob/main/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`](https://github.com/dougdonohoe/ddpoker/blob/main/code/pokerengine/src/main/java/com/donohoedigital/games/poker/engine/PokerConstants.java) and [`code/gamecommon/src/main/java/com/donohoedigital/games/config/EngineConstants.java`](https://github.com/dougdonohoe/ddpoker/blob/main/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.