retro-alcoi/README.md

retro-alcoi

Tools for configuring PCs at a retro gaming fair.

Deployment

Build all utilities first (see each utility's Quick start below). All binaries land in a shared dist/ folder at the repo root:

dist/
  setup-network
  setup-quake
  config.ini        ← single unified config for all utilities

Copy the entire dist/ folder to a USB stick, then on each fair PC run the relevant binary:

sudo ./setup-network 4
sudo ./setup-quake

Configuration

Edit config.ini at the repo root before building (it gets copied to dist/ automatically by each build.sh):

[network]
subnet_root = 10.0.1
hostname_prefix = retro-alcoi-

[quake]
files_url = https://php.sustancia.synology.me/files/ioquake3-files.zip
install_dir = .q3a

Utilities

setup-network

Assigns a static IP address and hostname to a Debian 13 machine based on a machine number (1–254). Designed for an isolated local network with no gateway or DNS required.

sudo ./setup-network <machine_num>

Example:

sudo ./setup-network 4
# → IP: 10.0.1.4/24, hostname: retro-alcoi-4

See setup-network/ for source.

Quick start

cd setup-network/
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
bash build.sh
# Binary is at ../dist/setup-network

How it works

1. Detects the first wired Ethernet interface (skips WiFi, bridges, veth).
2. Sets the hostname via hostnamectl and updates /etc/hosts.
3. Configures the static IP via nmcli if available, otherwise falls back to /etc/network/interfaces.

Re-running with the same or a different machine number is safe (idempotent).

setup-quake

Installs ioquake3 from the Debian package manager and downloads/extracts the Quake 3 data files from a private server to the real user's home directory.

sudo ./setup-quake

See setup-quake/ for source.

Quick start

cd setup-quake/
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
bash build.sh
# Binary is at ../dist/setup-quake

How it works

1. Installs ioquake3 via apt-get.
2. Downloads the Quake 3 data files zip from the configured URL.
3. Extracts the data files to ~/.q3a (resolved via $SUDO_USER so the real user's home is used, not root's).
4. Fixes ownership of all extracted files to the real user (not root).
5. Locks baseq3/autoexec.cfg to read-only (444) — client mode.

Client mode (default)

After setup-quake all machines are clients. autoexec.cfg is read-only so the game always starts at desktop resolution, fullscreen, with name "Jugador" and auto-connects to the server at 10.0.1.200.

Use ~/.q3a/scripts/client.sh to launch the game.

Server mode

On the server machine (10.0.1.200), run after setup-quake:

~/.q3a/scripts/activate-server.sh

This restores write access to autoexec.cfg. Then use one of the server launch scripts:

scripts/server-ctf.sh          # CTF, no bots
scripts/server-ctf-bots.sh     # CTF, bots fill server
scripts/server-dm.sh           # Deathmatch, no bots
scripts/server-dm-bots.sh      # Deathmatch, bots fill server
scripts/server-tdm.sh          # Team Deathmatch, no bots
scripts/server-tdm-bots.sh     # Team Deathmatch, bots fill server

Q3A data files zip

The zip extracted by setup-quake is hosted at files_url in config.ini. Its source lives in setup-quake/q3a/ in this repo (pak files excluded — add them separately before zipping). Structure after extraction:

~/.q3a/
  baseq3/
    pak0–pak8.pk3
    autoexec.cfg          ← client config (read-only after setup-quake)
    autoexec_server.cfg   ← server base settings, exec'd by server scripts
    server_ctf.cfg / server_dm.cfg / server_tdm.cfg
    levels_ctf.cfg / levels_dm.cfg / levels_tdm.cfg
    bots.cfg / bots_easy.cfg / nobots.cfg
  missionpack/
    pak*.pk3
  scripts/
    client.sh
    server-{ctf,dm,tdm}.sh
    server-{ctf,dm,tdm}-bots.sh
    activate-server.sh