2048 CLI Debug

Learning to interact with running programs through TTY, screen, expect, and eventually GDB/LLDB. Using 2048-cli as a test case for real-time program control and state inspection.

The score doesn’t matter - the interaction does! 🎮

This project documents the journey from failed Python abstractions to successful expect scripts, with the ultimate goal of debugger-based program control.

🎮 Game Screenshots

Starting Position

Score: 28 (+12)
   Hi: 932
-----------------------------
|    2 |      |    4 |    8 |
|      |      |      |    8 |
|      |      |      |      |
|      |      |      |      |
-----------------------------

High Score Achievement

Score: 800 (High Score!)
-----------------------------
|      |      |      |    4 |
|      |      |      |    8 |
|      |      |    4 |   16 |
|      |    8 |   16 |    8 |
-----------------------------

Achieved using the Down-Right Strategy™

🚀 Features

• LLDB Debug Scripts: Automated board state dumps, memory inspection, and gameplay analysis
• Emacs Integration: Custom mode with compilation, debugging, and visualization support
• Memory Analysis: Tools for inspecting game state and board memory layout
• AI Analysis: Observe and analyze AI gameplay patterns
• Build Automation: Enhanced Makefile with debugging and source management targets
• TTY Controller: Automated gameplay with complexity detection and manual inspection points
• Board Analyzer: Real-time complexity scoring and strategy suggestions
• Scientific Experiments: Rigorous experimental framework in experiments/

📋 Requirements

Tool	Version	Required	Notes
C Compiler	C99+	✅	gcc/clang
LLDB	14.0+	✅	Primary debugger
Emacs	25.1+	⭕	For IDE features
Make	3.81+	✅	Build system
etags	Any	⭕	Code navigation
screen	4.0+	⭕	TTY capture
tmux	3.0+	✅	TTY interaction
Python	3.8+	✅	Analysis scripts
uv	0.1+	✅	Python environment

🛠️ Installation

# Clone the repository
git clone https://github.com/jwalsh/2048-cli-debug.git
cd 2048-cli-debug

# Build the game
cd 2048-cli-0.9.1
make

# Build with debug symbols
make CFLAGS="-g -O0"

# Generate tags for navigation
make etags

🎯 Quick Start

Running the Game

# Play interactively
./2048

# Watch AI play
./2048 --ai

# Custom board size
./2048 --size 5

Simple Board State Display

To quickly see what a 2048 board looks like:

# One-liner to show board state
echo -e "Score: 0\n   Hi: 0\n$(printf '%s\n' -{1..29} | tr -d ' ')\n|    2 |      |      |      |\n|      |      |      |      |\n|      |      |      |      |\n|      |      |      |    2 |\n$(printf '%s\n' -{1..29} | tr -d ' ')"

Output:

Score: 0
   Hi: 0
-----------------------------
|    2 |      |      |      |
|      |      |      |      |
|      |      |      |      |
|      |      |      |    2 |
-----------------------------

TTY Controller

# Set up Python environment
uv sync

# Run automated test with manual inspection points
uv run python -m tty_manual.manual_test_runner \
  --spam-moves 50 \
  --check-interval 10 \
  --threshold 60

# Analyze a board snapshot
uv run python -m tty_manual.board_analyzer board_test.txt

# Interactive TTY reader
uv run python -m tty_manual.tty_reader --interactive

Debugging

# Basic debugging session
lldb ./2048 -s debug.lldb

# Interactive debugging with custom commands
lldb ./2048 -s debug-interactive.lldb

# Automated analysis
lldb ./2048 -s debug-automated.lldb

Emacs Integration

Add to your Emacs configuration:

(add-to-list 'load-path "/path/to/2048-cli-debug/2048-cli-0.9.1/")
(require '2048-mode)

Key bindings:

• C-c C-c - Compile
• C-c C-d - Debug with LLDB
• C-c C-r - Run game
• C-c C-a - Run with AI

📁 Project Structure

2048-cli-debug/
├── 2048-cli-0.9.1/         # Game source code
│   ├── src/                # C source files
│   ├── debug*.lldb         # LLDB scripts
│   ├── 2048-mode.el        # Emacs mode
│   └── Makefile            # Build configuration
├── experiments/            # Scientific experiments
│   ├── README.org          # Experiment overview
│   ├── exp_007/            # Memory layout discovery
│   ├── exp_008/            # Statistical validation
│   ├── exp_009/            # Speed baseline
│   ├── exp_010/            # Timing validation
│   └── ...                 # More experiments
├── docs/                   # Documentation
├── tty_manual/             # TTY interaction framework
├── README.org              # This file
├── CONTRIBUTING.org        # Contribution guidelines
├── ARCHITECTURE.org        # System architecture
└── LICENSE                 # MIT License

🔬 Scientific Experiments

The experiments/ directory contains rigorous scientific investigations:

Completed Experiments

• Exp 007: Memory Layout Proof - Discovered grid[col][row] indexing
• Exp 008: Statistical Validation - Down-right spam distribution
• Exp 009: Speed Baseline - Found built-in 160ms/move delay
• Exp 010: Timing Validation - Non-linear timing behavior

Ongoing Research

• Exp 011: Timing Curve Analysis - Board locking effects
• Exp 012-016: AI Players - Claude playing strategies
• Exp 017-020: LLDB Framework - Advanced debugging
• Exp 021-025: Pattern Analysis - Board representations

See experiments/README.org for detailed results and methodologies.

🔍 Debug Features

LLDB Scripts

• debug.lldb: Basic breakpoints with automatic board dumps
• debug-interactive.lldb: Custom commands (board, raw, state)
• debug-automated.lldb: AI gameplay analysis
• debug-symbols.lldb: Symbol and type information

Memory Layout

The game uses a clever memory layout:

• Single contiguous array for board data
• 2D pointer array for column access (grid[col][row])
• Efficient for both cache and iteration

🤝 Contributing

See CONTRIBUTING.org for detailed guidelines on:

• Understanding the codebase
• Debugging techniques
• Emacs workflow
• Submitting changes

📚 Documentation

• Architecture Overview
• Debug Tools Guide
• Original Game Documentation
• Experiments Overview
• Additional Documentation

🙏 Acknowledgments

• Original 2048-cli by Marc Tiehuis
• 2048 game concept by Gabriele Cirulli

📄 License

This project maintains the MIT License from the original 2048-cli. See LICENSE for details.