145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# QLPyCon - Quake Live Python Console
|
|
|
|
A modular, refactored terminal-based client for monitoring Quake Live servers via ZMQ.
|
|
|
|
## Version 0.8.0 - Modular Architecture
|
|
|
|
### 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
|
|
|
|
### Key Improvements Over v0.7.0
|
|
|
|
1. **Modular Design** - Separated concerns into focused modules
|
|
2. **Clean Classes** - OOP design for state and connections
|
|
3. **Better Maintainability** - Each module has a single responsibility
|
|
4. **Easier Testing** - Components can be tested independently
|
|
5. **Clear Interfaces** - Well-defined APIs between modules
|
|
6. **Improved Comments** - Every module, class, and function documented
|
|
|
|
### 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)
|
|
|
|
### Development
|
|
|
|
To extend QLPyCon:
|
|
|
|
1. **Add new event types** - Edit `parser.py`, add handler method
|
|
2. **Change UI layout** - Edit `ui.py`, modify window creation
|
|
3. **Add new commands** - Edit `main.py`, handle in main loop
|
|
4. **Modify formatting** - Edit `formatter.py`, adjust color/timestamp logic
|
|
5. **Add configuration** - Edit `config.py`, add constants
|
|
|
|
### License
|
|
|
|
MIT License - See original qlpycon.py for details
|
|
|
|
### Credits
|
|
|
|
Refactored from qlpycon.py v0.7.0
|