salidu
This commit is contained in:
@@ -1,119 +1,81 @@
|
||||
# QLPyCon - Quake Live Python Console
|
||||
|
||||
A modular, refactored terminal-based client for monitoring and remote controlling Quake Live servers via ZMQ.
|
||||
Terminal-based client for monitoring and controlling Quake Live servers via ZMQ.
|
||||
|
||||
### Features
|
||||
## 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)
|
||||
- Real-time game monitoring (kills, deaths, medals, team switches)
|
||||
- Server info display (map, gametype, scores, player list)
|
||||
- Team-aware colorized chat with location tracking
|
||||
- Powerup pickup and carrier kill notifications
|
||||
- JSON event capture for analysis
|
||||
- Quake color code support (^0-^7)
|
||||
- **Autocomplete for cvars/commands** with fuzzy matching
|
||||
- **Intelligent argument suggestions** for 25+ commands (bot names, maps, gametypes)
|
||||
|
||||
### 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
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Requirements
|
||||
pip install pyzmq
|
||||
|
||||
# Run directly
|
||||
python -m qlpycon.main --host tcp://127.0.0.1:27961 --password YOUR_PASSWORD
|
||||
python main.py --host tcp://SERVER_IP:PORT --password RCON_PASSWORD
|
||||
```
|
||||
|
||||
### Usage
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Basic connection
|
||||
# Basic
|
||||
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
|
||||
# Verbose logging
|
||||
python main.py --host tcp://SERVER_IP:PORT --password RCON_PASSWORD -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
|
||||
# Capture JSON events
|
||||
python main.py --host tcp://SERVER_IP:PORT --password RCON_PASSWORD --json events.log
|
||||
```
|
||||
|
||||
### Command Line Options
|
||||
**Options:**
|
||||
- `--host URI` - ZMQ RCON endpoint (default: tcp://127.0.0.1:27961)
|
||||
- `--password PASS` - RCON password (required)
|
||||
- `-v` / `-vv` - Verbose (INFO) or debug (DEBUG) logging
|
||||
- `--json FILE` - Log all events as JSON
|
||||
- `--unknown-log FILE` - Log unparsed events (default: unknown_events.log)
|
||||
|
||||
- `--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)
|
||||
**Configuration File (Optional):**
|
||||
Create `~/.qlpycon.conf` or `./qlpycon.conf`:
|
||||
```ini
|
||||
[connection]
|
||||
host = tcp://SERVER_IP:PORT
|
||||
password = your_password
|
||||
|
||||
### Architecture Overview
|
||||
[logging]
|
||||
level = INFO
|
||||
```
|
||||
|
||||
#### 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
|
||||
**Input Features:**
|
||||
- **Smart autocomplete** - Type commands and see arguments highlighted in real-time
|
||||
- **Argument value suggestions** - Intelligent suggestions for bot names, maps, gametypes, teams, etc.
|
||||
- **Tab** - Cycle through autocomplete suggestions
|
||||
- **↑/↓** - Command history navigation
|
||||
- **Argument highlighting** - Current argument position shown in reverse video
|
||||
- **Command signatures** - Automatic display (e.g., `addbot <botname> [skill 1-5] [team]`)
|
||||
|
||||
#### Network Layer (`network.py`)
|
||||
- **RconConnection** - Handles DEALER socket for RCON commands
|
||||
- **StatsConnection** - Handles SUB socket for game event stream
|
||||
See [AUTOCOMPLETE.md](AUTOCOMPLETE.md) for details.
|
||||
|
||||
#### Event Parsing (`parser.py`)
|
||||
- **EventParser** - Parses JSON game events into formatted messages
|
||||
- Modular handlers for each event type (deaths, medals, team switches, etc)
|
||||
## Architecture
|
||||
|
||||
#### Message Formatting (`formatter.py`)
|
||||
- Color code handling (Quake's ^N system)
|
||||
- Team prefix generation
|
||||
- Timestamp logic
|
||||
- Chat message formatting
|
||||
```
|
||||
main.py - Main loop, argument parsing, signal handling
|
||||
config.py - Constants (weapons, teams, colors, limits)
|
||||
state.py - Game state (ServerInfo, PlayerTracker, EventDeduplicator)
|
||||
network.py - ZMQ connections (RCON DEALER, Stats SUB sockets)
|
||||
parser.py - JSON event parsing (deaths, medals, switches, stats)
|
||||
formatter.py - Message formatting, color codes, team prefixes
|
||||
ui.py - Curses interface (3-panel: info, output, input)
|
||||
```
|
||||
|
||||
#### 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
|
||||
**Supported Events:**
|
||||
PLAYER_SWITCHTEAM, PLAYER_DEATH/KILL, PLAYER_MEDAL, PLAYER_STATS, MATCH_STARTED/REPORT, PLAYER_CONNECT/DISCONNECT, ROUND_OVER
|
||||
|
||||
### 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
|
||||
## License
|
||||
|
||||
WTFPL
|
||||
|
||||
Reference in New Issue
Block a user