Skip to content

Releases: cainky/QuakeLiveInterface

v0.2.0

02 Feb 19:01
@cainky cainky
v0.2.0
c35b122

Choose a tag to compare

View all tags
v0.2.0 Latest
Latest

What's New

RL Training Support

  • Add Python gym interface with combat-focused rewards
  • Add agent plugin with game state events and training support
  • Add minqlx C extensions for RL agent control
  • Add parallel environment support for faster training
  • Add AfterFrameDispatcher hook for view angle override
  • Make reward function optional

Infrastructure

  • Add Docker configuration for bot training
  • Add GitHub Pages landing page

Bug Fixes

  • Fix memory leak in get_entity_info via proper Py_DECREF
  • Fix memory leak in state publishing
  • Fix reward asymmetry and prevent degenerate behaviors
  • Fix view angle control and add frame synchronization
  • Add stable state checks and reduce reset loop sensitivity
  • Harden redis connection handling

Other

  • Robustness fixes and server config improvements
  • Update README with parallel training and new state fields
Assets 2
Loading

QuakeLiveInterface v0.1.0

08 Dec 03:34
@cainky cainky
v0.1.0
399cb27

Choose a tag to compare

View all tags
QuakeLiveInterface v0.1.0

QuakeLiveInterface is a Python library and Docker stack that turns a Quake Live server into a real-time, programmatic environment for agents, analytics, and bots.

With this release you can:

  • Run a Quake Live server + Redis via Docker
  • Stream game state at ~60 Hz into Python
  • Send movement and attack commands back into the game
  • Use a Gymnasium-compatible RL environment
  • Visualize matches in 2D in real time

🌟 Highlights

🔁 Real-time Game State via Redis

  • Subscribe to ql:game:state for JSON game snapshots at ~60 Hz
  • Access:
    • Player position, velocity, health, armor, weapons
    • View angles and alive/dead state
    • Opponent info
    • Item spawn states, positions, and timers
    • Game metadata (map, game type, in-progress flag)
// Example snippet from ql:game:state
{
  "agent": {
    "steam_id": 72561195012232678,
    "name": "Snap",
    "health": 100,
    "armor": 50,
    "position": {"x": -328.37, "y": 1615.47, "z": 1276.33},
    "velocity": {"x": -419.45, "y": 65.81, "z": -133.0},
    "view_angles": {"pitch": 0.0, "yaw": 90.0, "roll": 0.0},
    "is_alive": true,
    "team": "free"
  },
  ...
}

🧠 Custom minqlx Fork with C-Level Introspection

  • New C API: get_entity_info(entity_id)
  • Reliable item/powerup tracking:
    • Availability flags
    • Spawn times
    • Positions
  • Integrated into a custom minqlx fork + plugin (ql_agent_plugin.py)

🐳 Docker-based Full Stack

One command to spin up everything:

git clone https://github.com/cainky/QuakeLiveInterface.git
cd QuakeLiveInterface
poetry install

# Start Quake Live server + Redis + plugin stack
docker-compose up -d

Then connect to localhost:27960 in Quake Live and you’re ready to stream state.

🎮 Command & Control

Send agent inputs by publishing to ql:agent:command:

import redis, json

r = redis.Redis('localhost', 6379)

r.publish('ql:agent:command', json.dumps({
    "command": "input",
    "forward": 1,
    "right": 1,       # strafe right
    "jump": 1,
    "attack": 1,
    "pitch_delta": 0,
    "yaw_delta": 5    # turn right
}))

Redis channels:

Channel Direction Description
ql:game:state Server → Client Game state at ~60 Hz
ql:agent:command Client → Server Movement and action commands
ql:admin:command Client → Server Admin commands (restart, record, …)

🤖 RL, Bots, and Tools

Gymnasium Environment

Out-of-the-box RL integration:

from stable_baselines3 import PPO
from QuakeLiveInterface.env import QuakeLiveEnv

env = QuakeLiveEnv(redis_host="localhost")
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=100000)

Example Agents

  • agents/random_agent.py – simple random policy
  • agents/rules_based_agent.py – basic hand-crafted behavior

2D Visualizer

Real-time map viewer for debugging agents and behavior:

poetry run python visualizer.py

Analytics / Recording

Stream and log all game events:

with open("game_log.jsonl", "a") as f:
    for msg in ps.listen():
        if msg["type"] == "message":
            f.write(msg["data"] + "\n")

⚙️ Configuration

Key environment variables in docker-compose.yml:

Variable Description
QLX_AGENTSTEAMID Steam ID of the controlled account
QLX_REDISADDRESS Redis hostname (default: redis)
MAP_POOL Map + game type, e.g. `toxicity

Supported modes include FFA, Duel, TDM, CTF.

🧪 Testing

poetry run pytest

🐞 Known Issues / Limitations

  • Requires a valid Quake Live setup compatible with the Docker image
  • Only one primary “agent” Steam ID is supported per stack instance
  • Linux/Docker is the primary target environment; other setups may require tweaks

Full Changelog: https://github.com/cainky/QuakeLiveInterface/commits/v0.1.0

Loading