ql-lg-server/README.md

# ql-lg-server

A **Quake Live lightning gun (LG) vampiric practice server** in Docker, set up with one command.

Players spawn with the LG only. Every hit heals you by the damage you deal (1:1 vampiric), there's no knockback and no items, and the server stays in warmup forever. Nobody has to ready up, there's no countdown, and you never get kicked back to a scoreboard. People join, pair off and duel on thunderstruck. This is how the popular LG duel servers (x76) run, rebuilt from scratch and documented so you can host your own.

- One command: `./setup.sh` downloads the game (SteamCMD), builds minqlx, generates an RCON password and starts the server.
- Public (listed in the in-game browser) or private (join by address, LAN/VPN): one setting.
- Three variants: antilag, no antilag, flat 100 HP.
- No warmup text on screen (small minqlx plugin), plus a welcome message.
- **lgbot**, a training bot that plays LG like a duelist: ground strafing with uneven rhythm and fakes, holds LG range, never jumps. Aim and movement each go 1–5 and you can fine-tune the movement. Set it up with `./lgbot`.
- Recovers on its own: Docker restarts it after a crash, a watchdog restarts it if it hangs, and it restarts daily while nobody is playing. It also takes nightly backups.
- The RCON password never shows up in logs (Quake Live normally prints it there, see [How it works](docs/HOW-IT-WORKS.md)).

## Quick start

You need a Linux machine (a small VPS is fine: the server idles at ~3% of one core and ~50 MB RAM), [Docker with the compose plugin](https://docs.docker.com/engine/install/), `python3`, git, and ~2 GB of disk.

```sh
git clone <this repo> ql-lg-server
cd ql-lg-server
./setup.sh                    # asks: server name, listed or not, join password, port
./scripts/install-cron.sh     # optional: watchdog, nightly backup, daily restart
```

Run it as a normal user in the `docker` group, not as root. Setup prints the `/connect` addresses when it's done. Players need Quake Live on Steam.

**Public server:** forward **UDP 27960** (your `QL_PORT`) on your router or firewall to this machine. Listed servers appear in the in-game browser after a few minutes.

## Settings

Everything per-server is in `.env` (created from [`.env.example`](.env.example) by setup). After editing it, apply the change with `docker compose up -d`.

| Setting | Default | |
|---|---|---|
| `QL_HOSTNAME` | `LG Vampiric FFA` | name in the browser (`^1`..`^7` colors work) |
| `QL_LISTED` | `yes` | `no` = unlisted, join by address only |
| `QL_PASSWORD` | empty | join password |
| `QL_MAXCLIENTS` | `16` | |
| `QL_FACTORY` | `lgvamp` | `lgvamp`, `lgvamp_nolag` or `lgvamp100`, see below |
| `QL_MAP` | `thunderstruck` | stock map; workshop maps need extra setup |
| `QL_WELCOME` | short rules text | sent to each player on join; empty = off |
| `QL_RECORD` | `0` | `2` = record movement whenever two humans fight (for the lgbot, see docs/ADMIN.md) |
| `QL_PORT` / `QL_RCON_PORT` | `27960` / `28960` | game UDP / RCON TCP (127.0.0.1 only) |
| `QL_NAME` | `ql-lg` | Docker container name |

### Game modes (factories)

Defined in [`home/baseq3/scripts/lgvamp.factories`](home/baseq3/scripts/lgvamp.factories):

| Factory | What | Seen on real servers |
|---|---|---|
| `lgvamp` | LG only, 1:1 vampiric, no knockback, antilag up to 240 ms, spawn 200 HP | x76 "Antilag LG Duel" |
| `lgvamp_nolag` | same, antilag off (you have to lead your shots by your ping) | x76 "LG Duel EU #3" |
| `lgvamp100` | same as `lgvamp` but spawn with 100 HP | no, our variant: health above 100 decays ~1 HP/s, so with 200 HP spawns you slowly lose health even when you aren't taking damage |

Shared values: `g_startingWeapons 33` (gauntlet + LG), infinite ammo, `g_knockback 0`, no items, no `/kill`, no votes, instant weapon switch, `dmflags 28` (no self/fall damage), permanent warmup (`sv_warmupReadyPercentage 2`). Every value and why: [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md).

## Running it

```sh
./rcon status                 # who's on (./rcon alone = interactive console)
./rcon addbot hunter 5        # a target to shoot at; ./rcon kick allbots
./lgbot                       # LG training bot: asks aim/movement; ./lgbot --last | show | off
./rcon say hello
python3 tools/qlq.py 127.0.0.1 27960 --status
docker compose restart        # restart;  docker compose stop / start
./setup.sh --update           # update the game from Steam
```

Admins, bans, mutes, multiple servers, backups: [docs/ADMIN.md](docs/ADMIN.md). Share [docs/PLAYERS.md](docs/PLAYERS.md) with your players (joining, LG client settings).

## Layout

```
setup.sh              install / re-run / --update
.env.example          settings template (.env is yours, not in git)
docker-compose.yml    the container; Dockerfile = Debian + 32-bit libs + Python 3.11 + SteamCMD
rcon                  server console
lgbot                 LG training bot setup (runs tools/lgbot_setup.py in the container)
home/baseq3/          server.cfg (shared), scripts/lgvamp.factories (game modes),
                      scripts/lgbot.bot + botfiles/bots/lgbot_*.c (training bot aim);
                      local.cfg, secrets.cfg, mappool_lg.txt are generated from .env on each start
home/minqlx-plugins/  nowarmuptext.py (hides warmup text), welcome.py, lgbot.py (training bot movement)
tools/                mkcfg.sh (.env -> cfg), qlrcon.py (RCON client), qlq.py (health check),
                      lgbot_setup.py (lgbot questions), tests (test_qlq, test_lgbot)
scripts/              watchdog.sh, daily-restart.sh, backup.sh, install-cron.sh
```

Not in git (setup creates them): `server/` (game files, ~1.1 GB), `minqlx-build/`, `steamcmd-home/`, `secrets/`, `logs/`, `backups/`.

## Credits

- [minqlx](https://github.com/MinoMino/minqlx) (GPL-3.0) by MinoMino: built from source by setup.sh, not included here.
- [x76.gg](https://x76.gg/) for the LG duel server format this copies (FFA in permanent warmup, vampiric, no knockback).
- [SEA LG Duels server](https://github.com/minhlong124/quake-lg-sea-server): the vampiric LG preset this started from.
- Quake Live is © id Software / Bethesda. The dedicated server is downloaded from Steam (app 349090); no game files are in this repo.

License: MIT (this repo's configs and scripts).