2048 Nexus Documentation — Installation, Pre-built Packages, Mechanics & AI Solver

2048 Nexus Technical Overview

2048 Nexus is an open-source, hardware-accelerated desktop puzzle game implementation engineered in Python using PyQt6 and Qt Graphics View. It supports custom grid geometry from 3x3 to 8x8, unlimited move undo history, real-time expectimax AI calculation, and standalone installer packaging.

GUI FrameworkPyQt6 / QGraphicsView / Native Qt GUI

AI SolverExpectimax Search Tree (Depth 4-6)

Audio SystemPygame Sound Mixer Subsystem

LeaderboardLocal SQLite / JSON encrypted high scores

Installation & Pre-built Packages

2048 Nexus is distributed both as standalone pre-built executable binaries for major operating systems and as an open-source Python application. Choose your preferred installation method below:

Pre-built Binary Installers (Recommended)

Windows v1.0.0

Windows Setup (.exe) Standalone setup wizard for Windows 10 & 11 (64-bit). No Python runtime required. Download .exe (x64)

Debian / Ubuntu v1.0.0

Debian Package (.deb) Native package for Debian, Ubuntu, Linux Mint, Pop!_OS, Zorin OS, and Kali Linux. Download .deb

Fedora / RHEL v1.0.0

RPM Package (.rpm) Native package for Fedora 35+, RHEL 8+, CentOS Stream, Rocky Linux, and AlmaLinux. Download .rpm

Package Manager Installation

# --- Debian / Ubuntu / Linux Mint (.deb) ---
# 1. Download the package
wget https://github.com/dev-hints/2048-Nexus/releases/download/1.0.0/2048-nexus.deb

# 2. Install using dpkg
sudo dpkg -i 2048-nexus.deb

# 3. Resolve any missing dependencies (if required)
sudo apt-get install -f

# --- Fedora / RHEL / CentOS Stream (.rpm) ---
# Install directly via DNF:
sudo dnf install https://github.com/dev-hints/2048-Nexus/releases/download/1.0.0/2048-nexus-1.0.noarch.rpm

# Or install downloaded RPM:
sudo rpm -ivh 2048-nexus-1.0.noarch.rpm

Build & Run from Python Source

If you prefer running from source or developing custom AI heuristics, clone the repository and run with Python 3.10+:

# Clone the repository
git clone https://github.com/dev-hints/2048-Nexus.git
cd 2048-Nexus

# Optional: Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install PyQt6 pygame numpy

# Launch with default 4x4 grid
python main.py

# Launch 5x5 board with AI auto-solver enabled
python main.py --mode 4x4 --ai-enabled

System Compatibility & Requirements

Platform	Supported Versions	Installer Format	Architecture
Windows	Windows 10, Windows 11	`.exe` Installer / Standalone Binary	x86_64
Debian / Ubuntu	Ubuntu 20.04+, Debian 11+, Mint 20+, Pop!_OS	`.deb` Package	x86_64 / noarch
Fedora / RHEL	Fedora 35+, RHEL 8+, CentOS Stream 9+, Rocky, Alma	`.rpm` Package	x86_64 / noarch
Source (Python)	macOS 11+, FreeBSD, Any Linux distro	`pip` / Git Source	Universal (Python 3.10+)

Tile Probability & Scoring Matrix

Every valid swipe shifts non-zero matrix elements towards the vector edge. Consecutive matching pairs merge into their power of two sum:

Score_Add = Tile_A + Tile_B = 2^(k+1)

Event	Probability	Conditions
Spawn Tile '2'	`90.0%`	Random empty grid coordinate
Spawn Tile '4'	`10.0%`	Random empty grid coordinate
Game Over	`Deterministic`	0 empty cells & 0 adjacent merge pairs

Expectimax AI Heuristic Solver

The auto-solver searches game tree states up to depth 5 using an Expectimax model with four weighted evaluation heuristics:

1. Corner Weight Matrix (w = 3.5) Favors placing the highest value tile in the top-left corner.

2. Monotonicity (w = 2.2) Ensures values strictly increase or decrease along columns and rows.

3. Smoothness (w = 1.0) Minimizes numerical value differences between adjacent cells.

4. Free Tiles Count (w = 2.8) Rewards maintaining maximum open board real estate.

# Expectimax node evaluation score
Total_Score = (3.5 * corner_score) + (2.2 * monotonicity) + (1.0 * smoothness) + (2.8 * empty_cells)

PyQt6 Architecture & Subsystems

2048 Nexus is engineered with a modular separation of concerns designed for maximum frame rendering performance and testable AI integration:

1. Presentation Layer (PyQt6 & QGraphicsView) Implements smooth 60 FPS non-blocking hardware-accelerated tile transitions, particle explosions, and dynamic theme stylesheets.

2. Core Board Model (NumPy Matrix Engine) High-speed N-dimensional vector shift operations, cell merge collision resolution, and undo history tree restoration.

3. AI Search Worker (Multi-threaded Expectimax) Runs heuristic game tree calculations on a background QThread to maintain seamless GUI responsiveness during deep searches.

4. Audio & FX Mixer (Pygame Sound Engine) Low-latency sound effect mixer triggering synthwave retro audio cues on tile combinations, combos, and game milestones.

Keyboard Controls Reference

Key Binding	Action
`Arrow Keys` / `W A S D`	Move tiles in direction
`U` / `Ctrl + Z`	Undo last move
`Spacebar`	Execute single AI suggested step
`A`	Toggle continuous AI auto-play mode
`R`	Restart game session