refactor

2025-12-23 09:37:42 +01:00
parent 1dcd8941b5
commit a889898694
9 changed files with 1891 additions and 0 deletions
@@ -0,0 +1,144 @@
+# 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