Minus Games

Minus Games is a self‑hosted suite that orchestrates the distribution, execution and state synchronization of games between a central server and multiple clients. At its core, the system exposes a lightweight HTTP API for discovery (/finder/rerun-finder), asset retrieval, and save‑file exchange. The server side scans a designated “games” directory, builds an inventory of executable packages (native binaries, Unity bundles, etc.), and exposes them to clients via a RESTful interface. Clients pull the latest binaries or delta updates, launch the games locally, and optionally stream or cache save files back to the server. The GUI component offers a web‑based dashboard for managing game lists, monitoring sync status, and configuring per‑client policies.

Technical Stack

• Language & Runtime: The core services are written in Go (1.20+), chosen for its static binaries, concurrency primitives, and minimal runtime footprint—ideal for a home‑server deployment. The GUI is built with React (18) and served as a single‑page application, communicating over HTTPS to the Go backend.
• Web Framework: gin-gonic powers the REST API, providing middleware for authentication (JWT) and rate‑limiting. The GUI uses vite for fast development builds.
• Database: A lightweight embedded SQLite database stores metadata (game manifests, client registrations, sync timestamps). For larger deployments, a PostgreSQL backend can be swapped via the existing repository‑abstraction layer.
• File Storage: Game binaries are stored in a flat directory hierarchy; the server calculates SHA‑256 checksums and exposes them through signed URLs to prevent tampering. Save files are uploaded via multipart form data, with optional compression.
• Containerization: Docker images are available for each component (minus_games_server, client, gui). The server image includes a pre‑configured docker-entrypoint.sh that initializes the SQLite schema on first run.

Core Capabilities

• Discovery API: /finder/rerun-finder triggers a full directory scan, returning JSON with game metadata (name, version, checksum).
• Asset Distribution: /download/{gameId} streams the binary; clients can request delta updates via a PATCH endpoint.
• Save‑File Sync: Clients detect engine types (e.g., Unity, Unreal) and automatically locate save directories; the /save/upload endpoint receives files, while /save/download/{clientId} allows retrieval.
• Webhooks: External systems can subscribe to game_added, client_connected, and save_synced events, enabling CI pipelines or home‑automation scripts.
• Plugin Hook: A simple Go interface (GameHandler) lets developers inject custom logic for pre‑launch hooks, analytics, or DRM checks.

Deployment & Infrastructure

• Self‑Hosting: A single Docker Compose file can spin up the server, GUI, and optional reverse proxy (Traefik). For non‑container environments, binary releases are available for Linux, macOS, and Windows.
• Scalability: The stateless API layer can be replicated behind a load balancer. The SQLite backend is suitable for up to ~10 k games; larger catalogs should migrate to PostgreSQL, which the codebase already supports via an ORM layer.
• Security: All endpoints require TLS; JWT tokens are issued by the server and validated client‑side. The GUI enforces CSRF protection via double submit cookies.

Integration & Extensibility

• SDK: A Go client library (minusgames/sdk) exposes typed wrappers around the REST API, simplifying integration into custom launchers or automation scripts.
• Webhooks: External services (e.g., Home Assistant, Node‑RED) can listen to events and trigger actions such as “notify when a new game is available.”
• Custom Renderers: The GUI accepts theme overrides and custom CSS, allowing developers to brand the interface for internal use.
• CLI: The minus_games_client can be invoked from shell scripts, making it straightforward to integrate into existing game launch workflows.

Developer Experience

• Documentation: The project hosts a comprehensive user guide and API reference on GitHub Pages, with example payloads and curl snippets. The README provides a quick‑start flow that can be followed in under 10 minutes.
• Community: Issues and pull requests are actively managed; the repo includes a CONTRIBUTING.md with guidelines for extending the plugin system.
• Testing: The codebase ships with unit tests and integration tests that run against a mock server; developers can run go test ./... to validate changes locally.

Use Cases

1. Home‑Server Game Sync – A family shares a collection of non‑Steam titles across multiple devices (desktop, Steam Deck, Raspberry Pi) with automatic save‑file synchronization.
2. Custom Launchers – Developers building a bespoke game launcher can embed the Go SDK to query available titles and launch binaries directly.
3. Enterprise Training – A small business can host proprietary simulation software on a central server, distributing updates and collecting usage metrics via webhooks.
4. Retro Gaming – Emulators and ROMs can be served from the server, with save states automatically synced across devices.

Advantages

• Zero‑Config Binary Distribution – No need for third‑party launchers; the server handles delta updates and checksum validation.
• Open Licensing – MIT‑licensed source code allows unrestricted modification, ideal for closed‑source corporate environments.
• Lightweight Footprint – Go binaries are under 10 MB, making the suite suitable