Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vikpe/qw-streambot
Setup for automated QuakeWorld client accepting commands via Twitch chat.
https://github.com/vikpe/qw-streambot
go golang quakeworld twitch
Last synced: 27 days ago
JSON representation
Setup for automated QuakeWorld client accepting commands via Twitch chat.
- Host: GitHub
- URL: https://github.com/vikpe/qw-streambot
- Owner: vikpe
- License: mit
- Created: 2022-06-22T08:02:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-04T13:31:45.000Z (7 months ago)
- Last Synced: 2024-04-15T01:43:55.130Z (7 months ago)
- Topics: go, golang, quakeworld, twitch
- Language: Go
- Homepage: https://twitch.tv/QuakeWorld
- Size: 472 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# QuakeWorld streambot [](https://github.com/vikpe/qw-streambot/actions/workflows/test.yml) [](https://codecov.io/gh/vikpe/qw-streambot) [](https://goreportcard.com/report/github.com/vikpe/qw-streambot)
> Setup for automated QuakeWorld client accepting commands via Twitch chat.
* **Visit [twitch.tv/QuakeWorld](https://www.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)](https://github.com/golang/go)
* [ZeroMQ](https://zeromq.org/) - Communication/messages (single proxy and multiple subscribers/publishers)
* [serverstat](https://github.com/vikpe/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](https://github.com/vikpe/serverstat/blob/main/qserver/mvdsv/qscore/qscore.go).
* 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`](https://github.com/vikpe/qw-streambot/blob/main/internal/app/twitchbot/twitchbot.go) for all commands.
## Requirements
* [ezQuake](https://github.com/ezQuake/ezquake-source/releases) (unix) - QuakeWorld client
* Twitch account for the channel
* Twitch account for the chatbot
* Add [Twitch access tokens](https://twitchtokengenerator.com/) to `.env.` (see [.env.example](./.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)](https://obsproject.com/), see [Stream Setup](./stream_setup/) for details on the setup used on twitch.tv/quakeworld.
## Development
### Directory structure
Uses the [Standard Go Project Layout](https://github.com/golang-standards/project-layout).
```bash
cmd/ # Main applications
internal/ # Private application and library code
scripts/ # Various build, install operations
```
### Build
**Build specific app**
Example: build proxy
```shell
cd cmd/proxy
go build
```
**Build all apps**
```shell
./scripts/build.sh
```
### Run
**Single app**
Example: start the proxy.
```shell
./cmd/proxy/proxy
```
**App controller scripts**
Runs app forever (restarts on error/sigint with short timeout in between).
```shell
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
```shell
go test ./... --cover
```
## Production
Build all apps and run all app controller scripts.
```shell
./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](https://github.com/ezQuake/ezquake-source) - QuakeWorld client
* [qw-streambot-ezquake](https://github.com/vikpe/qw-streambot-ezquake) - ezQuake setup used
by [twitch.tv/QuakeWorld](https://twitch.tv/QuakeWorld)
* [serverstat](https://github.com/vikpe/serverstat) - Get info from QuakeWorld servers.
* [masterstat](https://github.com/vikpe/masterstat) - Get server addresses from QuakeWorld master servers.
* [QuakeWorld Server Browser](https://github.com/vikpe/qw-server-browser)
* [carmack](https://github.com/vikpe/carmack) - QuakeWorld utility bot for Discord