liChess - Native Ubuntu Touch Chess Client

A pure QML-based Lichess client for Ubuntu Touch, featuring touch-optimized board interaction and OAuth authentication.

Features

• Native Lomiri UI: Built with Lomiri.Components for seamless Ubuntu Touch integration
• OAuth Login: Secure Lichess OAuth authentication
• Touch Chess Board: Multi-touch enabled chess board with piece selection and move validation
• Real-time Updates: Live game streaming via Lichess API
• Game Management: Create and join games with customizable time controls
• Move Validation: Full chess move validation logic
• Settings Persistence: Save user credentials locally

Architecture

QML UI Layer

• Main.qml: Main application view with page navigation
• ChessBoard.qml: Interactive chess board component with canvas rendering

JavaScript Logic Layer

• GameStateManager.js: Chess game state, board representation, move validation
• LichessAPI.js: Lichess API integration, game streaming, move updates
• AuthManager.js: OAuth authentication flow

Key Technologies

• QML 2.7: UI markup language
• Lomiri Components 1.3: Ubuntu Touch UI controls
• QtQuick Canvas: Hardware-accelerated chess board rendering
• XMLHttpRequest: API communication
• Qt.labs.Settings: Persistent settings storage

Building

Prerequisites

sudo apt install clickable ubuntu-sdk-tools

Build & Run

# Build the click package
clickable build

# Run in emulator
clickable run

# Build for device
clickable build --arch armhf
clickable install --device

Project Structure

lichess/
├── qml/
│   ├── Main.qml              # Application root, page navigation
│   └── ChessBoard.qml        # Interactive chess board
├── js/
│   ├── AuthManager.js        # OAuth authentication
│   ├── LichessAPI.js         # API client and streaming
│   └── GameStateManager.js   # Game logic and move validation
├── assets/                   # Images and resources
├── CMakeLists.txt            # Build configuration
├── manifest.json.in          # Click package manifest
├── lichess.apparmor          # AppArmor security policy
├── lichess.desktop.in        # Desktop launcher file
└── README.md                 # This file

API Integration

Lichess OAuth Flow

1. User initiates login → Authorization request
2. Lichess OAuth endpoint → Authorization code
3. Backend exchanges code for access token
4. App stores token in Settings
5. Token used for authenticated API calls

Game Streaming

• Uses /api/board/game/stream/{gameId} endpoint
• NDJSON format (newline-delimited JSON)
• Real-time game state and move updates
• Automatic reconnection with exponential backoff

Move Submission

• POST to /api/board/game/{gameId}/move?move={uci}
• Validated before sending to prevent invalid moves
• Immediate feedback on move acceptance

Chess Logic

Move Generation

• Pawn: Single/double advances, captures with en passant support
• Knight: All 8 possible L-shaped moves
• Bishop: Diagonal sliding moves
• Rook: Horizontal/vertical sliding moves
• Queen: Combined bishop + rook moves
• King: Single square in any direction

Move Validation

• Legal move checking (doesn't leave king in check)
• Captures vs non-captures
• Piece-specific movement rules

Board Representation

• Square notation: a1-h8 (algebraic notation)
• Pieces: uppercase (white), lowercase (black)
• Internal board dictionary for O(1) piece lookup

Configuration

OAuth Setup

To enable real OAuth:

1. Register app at https://lichess.org/oauth
2. Set OAUTH_CLIENT_ID in AuthManager.js
3. Configure redirect URI in manifest
4. Set up backend service for token exchange

Customize Time Controls

Edit timeControl.model in Main.qml CreateGamePage:

model: ["1+0", "2+1", "3+0", "5+3", "10+0", "30+0"]

Performance Notes

• Canvas-based board rendering (~60 FPS)
• Lazy move validation on selection
• Streaming updates processed line-by-line
• Settings cached in memory
• Connection pooling for API requests

Future Enhancements

• Offline mode with board editor
• Game analysis with engine
• Chat integration
• Puzzle training
• Tournament support
• Custom themes
• Multiple accounts
• Notification support

License

GNU General Public License v3.0 - See LICENSE file

Contributing

Contributions welcome! Please ensure:

• Code follows existing style
• QML components are modular
• JS modules remain pure (no global state)
• All features are Ubuntu Touch compatible

Support

• Lichess API: https://lichess.org/api
• Ubuntu Touch Docs: https://ubuntu.com/phone
• Clickable: https://clickable-ut.dev/ Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranties of MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.