qlpycon/README.md

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

# Requirements
pip install pyzmq

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

Usage

# 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