RL2048

RL2048 is a compact Deep Q-Network implementation for the game 2048. It includes both a training script for producing PyTorch checkpoints and a small Flask viewer for watching a trained policy play in the browser.

The project is intentionally small enough to read end to end, while still covering the core pieces of a reinforcement learning workflow: environment dynamics, experience replay, policy training, checkpoint loading, and interactive playback.

Features

• 2048 environment with move validation, rewards, terminal-state handling, and observations for learning
• Deep Q-Learning agent implemented in PyTorch
• Automatic device selection for training (cuda, mps, xpu, or cpu)
• Browser viewer with autoplay, pause/resume, single-step agent control, and manual moves while paused
• Bundled dqn_2048.pth checkpoint so the viewer can run immediately after setup
• Unit tests covering the game logic, agent behavior, and server/controller flows

Quick start

git clone https://github.com/rexmhall09/RL2048.git
cd RL2048
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

Open http://127.0.0.1:5000 in your browser.

Run the viewer

The viewer loads dqn_2048.pth from the project root by default.

python server.py

Viewer controls include:

• pause and resume autoplay
• step the agent one move at a time
• play manually with the on-screen arrows or keyboard arrow keys while paused
• reset the board
• adjust autoplay speed

Train a model

Train a new checkpoint with:

python train.py --episodes 30000 --device auto

Options:

• --episodes: number of training episodes
• --device: auto, cuda, mps, xpu, or cpu

Training writes:

• dqn_2048.pth: best checkpoint seen during the run
• dqn_2048_final.pth: final checkpoint at the end of training

Run tests

python -m unittest discover -s tests -v

Project layout

• game_2048.py — 2048 environment and game rules
• dqn_agent.py — replay buffer, network, and action-selection logic
• train.py — training entry point
• server.py — Flask app and viewer controller
• templates/index.html — browser UI for the viewer
• tests/ — unit tests
• dqn_2048.pth — bundled checkpoint for the viewer

Getting help

If you find a bug, have a question, or want to suggest an improvement, open an issue on GitHub.

License

This project is licensed under the MIT License. See LICENSE for the full text.