# QLPyCon - Quake Live Python Console

A modular, refactored terminal-based client for monitoring and remote controlling Quake Live servers via ZMQ.

### Features

- **Real-time game monitoring** - Watch kills, deaths, team switches, medals, and more
- **Server info display** - Shows hostname, map, gametype, limits, and player count
- **Team-aware chat** - Color-coded messages with team prefixes
- **Powerup tracking** - Formatted pickup and carrier kill messages
- **JSON event logging** - Capture all game events to file for analysis
- **Colorized output** - Quake color code support (^0-^7)

### Module Structure

```
qlpycon/
├── __init__.py          # Package initialization
├── main.py              # Entry point and main loop
├── config.py            # Constants and configuration
├── state.py             # Game state management (ServerInfo, PlayerTracker, etc)
├── network.py           # ZMQ connections (RCON and stats stream)
├── parser.py            # JSON event parsing
├── formatter.py         # Message formatting and colorization
└── ui.py                # Curses interface (windows, display, input)
```

### Installation

```bash
# Requirements
pip install pyzmq

# Run directly
python -m qlpycon.main --host tcp://127.0.0.1:27961 --password YOUR_PASSWORD
```

### Usage

```bash
# Basic connection
python main.py --host tcp://SERVER_IP:PORT --password RCON_PASSWORD

# Verbose mode (show all communications)
python main.py --host tcp://SERVER_IP:PORT --password PASS -v

# Debug mode (detailed logging)
python main.py --host tcp://SERVER_IP:PORT --password PASS -vv

# Capture all JSON events to file
python main.py --host tcp://SERVER_IP:PORT --password PASS --json events.log

# Custom unknown events log
python main.py --unknown-log my_unknown.log
```

### Command Line Options

- `--host` - ZMQ URI (default: tcp://127.0.0.1:27961)
- `--password` - RCON password
- `--identity` - Socket identity (random UUID by default)
- `-v, --verbose` - Increase verbosity (use -v for INFO, -vv for DEBUG)
- `--json FILE` - Log all JSON events to FILE
- `--unknown-log FILE` - Log unknown JSON events (default: unknown_events.log)

### Architecture Overview

#### State Management (`state.py`)
- **ServerInfo** - Tracks server configuration and metadata
- **PlayerTracker** - Manages player teams and information
- **EventDeduplicator** - Prevents duplicate kill/death events
- **GameState** - Main container for all state

#### Network Layer (`network.py`)
- **RconConnection** - Handles DEALER socket for RCON commands
- **StatsConnection** - Handles SUB socket for game event stream

#### Event Parsing (`parser.py`)
- **EventParser** - Parses JSON game events into formatted messages
- Modular handlers for each event type (deaths, medals, team switches, etc)

#### Message Formatting (`formatter.py`)
- Color code handling (Quake's ^N system)
- Team prefix generation
- Timestamp logic
- Chat message formatting

#### UI Layer (`ui.py`)
- **UIManager** - Manages all curses windows
- Three-panel layout: server info, output, input
- Threaded input queue for non-blocking commands
- Color rendering with curses

### Event Types Supported

- `PLAYER_SWITCHTEAM` - Team changes
- `PLAYER_DEATH` / `PLAYER_KILL` - Frag events (deduplicated)
- `PLAYER_MEDAL` - Medal awards
- `PLAYER_STATS` - End-game statistics with weapon accuracy
- `MATCH_STARTED` - Match initialization
- `MATCH_REPORT` - Final scores
- `PLAYER_CONNECT` / `PLAYER_DISCONNECT` - Connection events
- `ROUND_OVER` - Round completion

### Color Codes

Quake Live uses `^N` color codes where N is 0-7:
- `^0` - Black
- `^1` - Red
- `^2` - Green
- `^3` - Yellow
- `^4` - Blue
- `^5` - Cyan
- `^6` - Magenta
- `^7` - White (default)

### License

WTFPL