ql-lg-server/docs/ADMIN.md

# Running the server

Everything below is run from the repo folder on the server machine.

## Console (RCON)

`./rcon <command>` runs one server command; `./rcon` alone opens a `ql>` prompt (Ctrl+D quits). It runs inside the container and reads `secrets/rcon-password.txt` itself, so you never type the password. RCON listens on 127.0.0.1 only, so nobody can reach it from outside the machine.

| Command | |
|---|---|
| `status` | players with their slot number (`num`), ping, address (`bot` = bot) |
| `say <text>` | message to everyone |
| `addbot hunter 5` | add a bot (names: hunter, anarki, hossman, …; skill 1–5) |
| `kick allbots` | remove all bots (prints a harmless "Player allbots is not on the server") |
| `clientkick <num>` | kick a player |
| `mute <num>` / `unmute <num>` | chat mute |
| `tempban <num>` | kick + ban until the map changes |
| `ban <num>` / `unban <num>` | permanent ban (stored in `access.txt`) |
| `addadmin <num>` / `addmod <num>` | give a connected player admin / mod rights |
| `reload_access` | re-read `access.txt` |
| `map thunderstruck lgvamp` | reload the map (or switch factory: `lgvamp_nolag`, `lgvamp100`) |

**Careful:** `cvarlist` prints the RCON password into the server log. `./rcon` hides it from you, but avoid running it anyway.

## LG training bot: `./lgbot`

A bot that only plays LG, built to practise against: it strafes on the ground like a duelist (uneven left/right holds, fake direction changes), keeps LG range, pushes in when it's ahead on health and backs off when it's low, and never jumps or crouches. It shoots back. Aim and movement are separate, so "poor aim, best movement" is fine.

```
$ ./lgbot
Aim level 1-5 [3]: 1
Movement level 1-5 [3]: 5
Customize movement details? (y/N): y
  Strafe hold min ms 50-2000 [120]:
  Strafe hold max ms 50-2000 [350]: 300
  ...
lgbot in: aim 1, movement 5 (custom: strafe_max 300)
```

Enter keeps the value in brackets; anything invalid asks again; Ctrl+C changes nothing. The setup is saved in `home/lgbot.json`.

| Command | |
|---|---|
| `./lgbot` | the questions above, then (re)adds the bot |
| `./lgbot --last` | put the saved setup back, e.g. after a restart (bots don't survive one) |
| `./lgbot show` | saved setup and whether the bot is in |
| `./lgbot off` | remove the bot (setup stays saved) |

Movement levels (the details override one part, `-1` = use the level's value):

| Level | Strafe hold (ms) | Fake chance | Range | Push in / back off | Speed | Lane |
|---|---|---|---|---|---|---|
| 1 | 600–1000 | 0% | 450 | no | 80% | 600 |
| 2 | 400–800 | 10% | 450 | no | 90% | 500 |
| 3 | 250–600 | 25% | 400 | yes | 100% | 400 |
| 4 | 180–450 | 35% | 380 | yes | 100% | 350 |
| 5 | 120–350 | 50% | 350 | yes | 100% | 300 |

Range is the distance it tries to keep (LG reaches 768). Lane is how far it may drift sideways before it turns back, so it does ADAD in front of you instead of circling (0 = no limit). With push in / back off off, it always holds its range.

Underneath it's plain console settings, if you'd rather: `./rcon addbot lgbot <aim>`, `./rcon set lgbot_move <1-5>`, and `lgbot_strafe_min`, `lgbot_strafe_max`, `lgbot_fake`, `lgbot_range`, `lgbot_range_play`, `lgbot_speed`, `lgbot_lane`. The plugin rereads them every second. `set lgbot_debug 1` writes one line a second about its movement to `home/minqlx.log`.

The bot fights the nearest human. Its own movement only takes over when you're within LG reach (900 units) on about the same floor; farther away, the normal bot AI walks it over to you. If a wall blocks its strafing for half a second, it lets the AI walk around for 1.5 s. One lgbot at a time.

## Admins and bans: `home/baseq3/access.txt`

One line per player: their 64-bit Steam ID, a `|`, and `admin`, `mod` or `ban`:

```
76561198000000000|admin
76561198000000001|ban
```

Quake Live writes this file back from memory on every map load and on shutdown, so a hand edit can be overwritten. Either use the console commands above (`addadmin`, `ban`, `unban`), or edit the file and run `./rcon reload_access` right away. To unban someone who isn't connected, delete their line and run `reload_access`.

## Settings changes

- `.env` (name, password, listed, factory, welcome text, ports): edit it, then run `docker compose up -d`.
- Gameplay: edit `home/baseq3/scripts/lgvamp.factories` (must stay valid JSON: `python3 -m json.tool home/baseq3/scripts/lgvamp.factories`), then run `docker compose restart`.
- A cvar changed over RCON (e.g. `./rcon timelimit 1`) lasts until the next restart, map changes included.

## Self-healing (`./scripts/install-cron.sh`)

| What | When | Log |
|---|---|---|
| crash restart | Docker (`restart: unless-stopped`) | `docker inspect -f '{{.RestartCount}}' ql-lg` |
| hang watchdog: 3 failed checks in a row → restart | every 5 min | `logs/watchdog.log` |
| backup of `.env`, secrets, access.txt, cfgs, plugins (14 days) | 04:40 | `backups/` |
| daily restart, skipped while a human is on | 05:00 | `logs/watchdog.log` |

`./scripts/install-cron.sh --remove` removes those cron lines. A `docker compose stop` is respected: the watchdog leaves a stopped server alone.

## Updates

- Game: `./setup.sh --update`, then `docker compose restart`. If a game update ever removes `server/run_server_x64_minqlx.sh`, plain `./setup.sh` copies it back.
- This repo: `git pull`, then `./setup.sh` (re-running it is safe: it keeps your `.env`, password and game files).

## More than one server

Clone the repo into a second folder. Before running `./setup.sh`, create `.env` there from `.env.example` with a different `QL_PORT`, `QL_RCON_PORT` and `QL_NAME` (e.g. `27961`, `28961`, `ql-lg-2`). Each folder downloads its own game files (~1.1 GB). Each server costs about 3% of a CPU core while idle.

## Logs

`docker logs --tail 50 ql-lg` (your `QL_NAME`). minqlx log: `home/minqlx.log`. Lines with the RCON password are filtered out before they reach `docker logs`, but treat logs as private anyway.

## Without minqlx

If minqlx ever breaks after a game update, change `run_server_x64_minqlx.sh` to `run_server_x64.sh` in `docker-compose.yml` and run `docker compose up -d`. Everything still works except that the warmup text ("The match will begin when more players join") comes back and there's no welcome message.