Chess for Logos Basecamp

Play chess against Stockfish, inside Logos Basecamp.

Chess is a ui_qml Logos module: a QML board rendered by Basecamp, with a process-isolated C++ backend that drives the Stockfish engine over UCI. The engine is also the referee: legal moves come from Stockfish's go perft 1, board state and check detection from its d command, so the module ships no hand-written move generator that could disagree with the rules.

What it does

Three ways to play, switchable from the top-left mode tabs:

• Engine — vs Stockfish: difficulty 0 to 20 (adjustable mid-game from Settings), live clocks, evaluation bar and readout, engine commentary stream, full-strength hints, undo, typed SAN/UCI move input
• Table — two humans passing one machine: editable names, both clocks live, material tracker, resign and agree-a-draw, board turns after every move
• Online — two humans on different machines over Logos Delivery, World Chess Network style: share a game code, host and join, play in real time with chat; moves and messages travel peer to peer on a content topic (/logos-chess/1/game-<code>/json), no game server anywhere

Everywhere: click-to-move with legal-move markers, last-move / check / hint highlights, SAN move list, promotion picker, and full game-end detection (checkmate, stalemate, fifty-move rule, threefold repetition, insufficient material, time forfeit). Stockfish referees all modes, and engine auto-discovery has an in-app path override in Settings.

Online mode needs the delivery_module loaded in Basecamp (bundled automatically in the dev runner). Note that game topics are unencrypted: use a hard-to-guess code and keep the trash talk friendly.

Install

1. Install Stockfish

The chess engine is not bundled. Get an official build:

# macOS
brew install stockfish

# Debian / Ubuntu
sudo apt install stockfish

Or download from the official releases.

2. Install the module

Download the .lgx for your platform from the latest release (macOS Apple Silicon, Linux x86_64, Linux ARM64), then in Basecamp open Modules, click Install LGX Package, and select the file. Load it from the Modules view and Chess appears with the pawn icon.

CLI alternative:

# macOS
BASECAMP_DIR="$HOME/Library/Application Support/Logos/LogosBasecamp"
# Linux
# BASECAMP_DIR="$HOME/.config/Logos/LogosBasecamp"

lgpm --modules-dir "$BASECAMP_DIR/modules" install --file chess_ui-darwin-arm64.lgx

Release assets are portable builds (self-contained, bundled support libraries). If your platform has no prebuilt asset yet, build from source below.

Build from source

Requires Nix with flakes (install). Stockfish is pulled in automatically for Nix builds.

git clone https://github.com/IP3-Studio/chess-basecamp
cd chess-basecamp
nix build                      # compile the plugin
nix run .                      # play it in logos-standalone-app
nix build .#lgx-portable       # package a shareable .lgx for your platform

DEV_QML_PATH=$PWD/src/qml nix run .   # live-reload QML while hacking
nix build .#integration-test -L       # run the UI tests

How the engine is located

First match wins:

1. Path saved from the in-app "Use engine path" field (QSettings Logos/chess_ui)
2. LOGOS_CHESS_STOCKFISH environment variable
3. stockfish on PATH
4. Path baked in at build time (the Nix store path, for Nix-built installs)
5. Common locations: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /usr/games, ~/.nix-profile/bin, /run/current-system/sw/bin

If nothing is found, the app shows install guidance and a path field.

How it works

Basecamp (or logos-standalone-app)
  ├─ renders src/qml/Main.qml (the board)
  └─ spawns ui-host with chess_ui_plugin
        └─ ChessUiBackend ── UCI over stdin/stdout ──> stockfish
             position/d ......... board state, FEN, checkers
             go perft 1 ......... legal move list
             go movetime N ...... engine moves and hints

QML and backend talk over Qt Remote Objects; the contract lives in src/chess_ui.rep. Engine replies are matched to a FIFO queue of pending requests, with generation counters so a new game invalidates in-flight replies. A backend crash cannot take Basecamp down.

Layout

├── metadata.json                  # module manifest (type: ui_qml, universal)
├── flake.nix                      # builds via logos-module-builder
├── src/
│   ├── chess_ui.rep               # QtRO view contract
│   ├── chess_ui_backend.{h,cpp}   # UCI driver + game state (the only C++)
│   └── qml/Main.qml               # board UI
├── icons/chess.png                # generated by scripts/make_icon.py
└── tests/ui-tests.mjs             # integration tests

Known limitations

• Move list uses UCI notation (e2e4), not SAN; no PGN export yet
• Threefold repetition is declared automatically at the third occurrence (no claim step), and only the simple insufficient-material cases (K vs K, K+B vs K, K+N vs K) are recognised

License

Licensed under either of Apache License 2.0 or MIT license at your option, matching the Logos ecosystem convention.

Stockfish is a separate GPLv3 program. This module does not bundle or link it; it runs your locally installed copy as a subprocess and talks UCI over stdin/stdout.