QuakeWorld streambot

Setup for automated QuakeWorld client accepting commands via Twitch chat.

Visit twitch.tv/QuakeWorld to see it in action.

How does it work? (TLDR version)

ezQuake reads from a pipe located at /tmp/ezquake_[username] on posix systems, where username is the username of the user who started the ezQuake process.

So basically all you have to do is to write commands to /tmp/ezquake_[username].

Most of the code in this project is related to making sure that the client always is connected to the "best" server available (check ezQuake process, current server, available servers, handling commands from Twitch etc).

Stack

Written in Go (Golang)
ZeroMQ - Communication/messages (single proxy and multiple subscribers/publishers)
serverstat - Get info from QuakeWorld servers

Overview

Message Proxy: Central point for communication.
Quake Manager: Interaction with ezQuake
- Server monitor (thread): Server events (map change etc)
- Process monitor (thread): ezQuake events (started, stopped)
Twitch Manager: Interaction with Twitch channel (e.g. set title).
Twitch Bot: Interaction with Twitch chat.

Quake Manager - evaluation loop

An evaluation is run to make sure that the client is connected to the "best" server available (auto mode enabled) unless commanded to join a specific server (auto mode disabled).

Run every 10 seconds
Join "best server" available. Servers are ranked using a custom scoring algorithm.
Only change server in between matches or if current server has enabled a custom game mode (e.g. race).

Chatbot commands

Example, find XantoM and join that server.

Command	Description
`!auto`	Enable auto-mode (join best server)
`!autotrack`	Toggle autotrack
`!cfg_load`	Re-load config
`!cmd [x]`	Run command `x` (mod only)
`!console`	Toggle console
`!find [name]`	Find `[name]` and join server
`!lastscores`	Show list of last scores
`!restart`	Restart ezQuake client
`!showscores`	Show scoreboard
`!track [x]`	Track player `x`
`!attack`	Toggle between free float spectator mode and player pov
`!jump`	Track next player

See internal/app/twitchbot/twitchbot.go for all commands.

Requirements

ezQuake (unix) - QuakeWorld client
Twitch account for the channel
Twitch account for the chatbot
Add Twitch access tokens to .env. (see .env.example)
- Channel access token to update title, scope: channel:manage:broadcast
```
https://id.twitch.tv/oauth2/authorize
?response_type=token
&client_id=CLIENT_ID
&redirect_uri=http://localhost:3000
&scope=channel%3Amanage%3Abroadcast
```
- Chatbot access token to read and write to chat, scopes: chat:read and chat:edit.
ZeroMQ: apt-get install libzmq3-dev

For streaming I highly recommend Open Broadcaster Sofware (OBS), see Stream Setup for details on the setup used on twitch.tv/quakeworld.

Development

Directory structure

Uses the Standard Go Project Layout.

cmd/       # Main applications
internal/  # Private application and library code
scripts/   # Various build, install operations

Build

Build specific app

Example: build proxy

cd cmd/proxy
go build

Build all apps

./scripts/build.sh

Run

Single app

Example: start the proxy.

./cmd/proxy/proxy

App controller scripts

Runs app forever (restarts on error/sigint with short timeout in between).

bash scripts/controllers/proxy.sh
bash scripts/controllers/quake_manager.sh
bash scripts/controllers/twitch_manager.sh
bash scripts/controllers/twitchbot.sh
bash scripts/controllers/ezquake.sh

Test

go test ./... --cover

Production

Build all apps and run all app controller scripts.

./scripts/build.sh && ./scripts/start.sh

Credits

Thanks to everyone that has provided feedback and improvement suggestions (andeh, bps, circle, hangtime, milton, splash, wimpeeh) among others.

Related projects

ezQuake - QuakeWorld client
qw-streambot-ezquake - ezQuake setup used by twitch.tv/QuakeWorld
serverstat - Get info from QuakeWorld servers.
masterstat - Get server addresses from QuakeWorld master servers.
QuakeWorld Server Browser
carmack - QuakeWorld utility bot for Discord

vikpe / qw-streambot