Skip to main content

GNU Backgammon Setup

Configure GNU Backgammon (gnubg) for expert-level position analysis.

Overview​

GNU Backgammon is a world-class backgammon engine using neural networks for position evaluation. Integration enables professional-level move analysis.

The server Dockerfile includes gnubg automatically.

Build the Image​

docker build -t backgammon-server:latest -f Backgammon.Server/Dockerfile .

Verify Installation​

docker run --rm backgammon-server:latest gnubg --version

Expected output:

GNU Backgammon 1.x.xxx

Configuration​

Application Settings​

Update appsettings.json:

{
"Analysis": {
"EvaluatorType": "Gnubg",
"AllowUserSelection": false
},
"Gnubg": {
"ExecutablePath": "gnubg",
"TimeoutMs": 30000,
"VerboseLogging": false,
"EvaluationPlies": 2,
"UseNeuralNet": true
}
}

Configuration Options​

SettingDescriptionDefault
EvaluatorTypeGnubg or HeuristicHeuristic
ExecutablePathPath to gnubg binarygnubg
TimeoutMsMax operation time (ms)30000
VerboseLoggingEnable debug outputfalse
EvaluationPliesAnalysis depth (0-3+)2
UseNeuralNetUse neural networktrue

Evaluation Plies​

PlySpeedAccuracyUse Case
0Very fastLowerQuick hints
1FastGoodReal-time
2ModerateVery goodRecommended
3+SlowExcellentPost-game analysis

Environment Variables​

Alternative configuration via environment:

export Analysis__EvaluatorType=Gnubg
export Gnubg__ExecutablePath=gnubg
export Gnubg__TimeoutMs=30000
export Gnubg__EvaluationPlies=2

Local Development​

Ubuntu/Debian​

sudo apt-get update
sudo apt-get install gnubg

macOS​

brew install gnubg

Verify​

gnubg --version

Production Deployment​

Docker Deployment​

docker run -d \
-p 5000:5000 \
-e Analysis__EvaluatorType=Gnubg \
-e Gnubg__EvaluationPlies=2 \
--name backgammon-server \
backgammon-server:latest

EC2 Direct Installation​

sudo apt-get update
sudo apt-get install -y gnubg
gnubg --version

Verification​

Check Application Logs​

On startup, you should see:

info: Backgammon.Server.Services.AnalysisService[0]
Using Gnubg position evaluator

Test Analysis API​

curl -X POST https://api.doublecube.gg/api/analyze \
-H "Authorization: Bearer <token>" \
-d '{"gameId": "xxx"}'

Fallback Behavior​

If gnubg is unavailable:

  • Application falls back to heuristic evaluator
  • Warning logged
  • Games continue uninterrupted

Troubleshooting​

"gnubg not found"​

Cause: Binary not in PATH or not installed.

Solution:

  • Rebuild Docker image
  • Install via package manager
  • Check ExecutablePath setting

Timeout Errors​

Cause: Analysis taking too long.

Solution:

  • Reduce EvaluationPlies to 1 or 0
  • Increase TimeoutMs
  • Check server CPU load

High Memory Usage​

gnubg loads neural network weights into memory (~100-200 MB).

The GnubgProcessManager uses a semaphore to limit concurrent processes.

Performance Notes​

  • Higher ply = exponentially slower
  • 2-ply recommended for real-time analysis
  • 3+ ply for post-game deep analysis
  • Image size increases ~150 MB vs Alpine base