---
name: piqueserver
description: piqueserver recipe for open-forge. Server for OpenSpades / Ace of Spades 0.75, a first-person shooter in a destructible voxel world. Python + C++. pip / Docker. GPL-3.0. Source: https://github.com/piqueserver/piqueserver
---

# piqueserver

Game server for OpenSpades (and Ace of Spades 0.75), a free first-person shooter set in a destructible voxel world. Feature-rich server with admin tools, map rotation, scripting, gamemode support (deathmatch, CTF, running man), IRC integration, SSH remote console, JSON query API, and a ban subscribe service. Python 3.10+, C++ extension. pip-installable. GPL-3.0 licensed.

Clients: OpenSpades (https://openspades.yvt.jp/) is the recommended free client.

Upstream: https://github.com/piqueserver/piqueserver | Docs: https://piqueserver.readthedocs.io

## Compatible combos

| Infra | Runtime | Notes |
|---|---|---|
| Linux x86_64 | pip | Pre-built wheel available |
| Windows x86/x86_64 | pip | Pre-built wheel available |
| Any | Build from source | Requires C++ compiler |
| Arch Linux | AUR | piqueserver-git |

## Inputs to collect

| Phase | Prompt | Notes |
|---|---|---|
| config | Server name | Shown in server browser |
| config | Max players | Default: 32 |
| config | Port | Default UDP 32887 |
| config | Map | Initial map name |
| config | Game mode | Default: ctf; options: deathmatch, runningman, etc. |
| config (optional) | Admin password | For in-game admin commands |
| config (optional) | IRC settings | Host, channel, nick for IRC bridge |
| config (optional) | SSH settings | For remote console access |

## Software-layer concerns

- UDP port: piqueserver listens on UDP 32887 by default; open this port in your firewall
- Config file: generated by piqueserver --copy-config; edit config.toml before starting
- Maps: stored in the maps/ config directory (AOS .vxl format)
- Scripting: server behavior can be extended with Python scripts placed in the scripts/ config directory
- Python 3.10+ required

## Install -- pip (Linux)

```bash
pip3 install piqueserver

# Optional features:
# pip3 install piqueserver[ssh,from]
# ssh: SSH manhole remote console
# from: geolocate players by IP

# Copy default config
piqueserver --copy-config

# Edit config
nano ~/.config/piqueserver/config.toml

# Start server
piqueserver
```

## Install -- pip (venv, recommended)

```bash
python3 -m venv pique-env
source pique-env/bin/activate
pip install piqueserver
piqueserver --copy-config
piqueserver
```

## Install -- from source (bleeding edge)

```bash
git clone https://github.com/piqueserver/piqueserver
cd piqueserver
python3 -m venv venv
source venv/bin/activate
pip install .
piqueserver --copy-config
piqueserver
```

## Upgrade procedure

```bash
pip3 install --upgrade piqueserver
```

## Firewall

```bash
# Open UDP port 32887
ufw allow 32887/udp
```

## Gotchas

- UDP only: Ace of Spades / OpenSpades use UDP for game traffic. TCP firewall rules alone won't work; open the UDP port explicitly.
- C++ extension: piqueserver includes a C++ module for performance. On non-supported platforms (arm64, etc.) you need gcc/g++ and the full build toolchain.
- OpenSpades client required: players need the OpenSpades client (https://openspades.yvt.jp/) or the original Ace of Spades 0.75 client to connect. Regular web browsers cannot connect.
- Config location: piqueserver --copy-config writes config to ~/.config/piqueserver/ (Linux) or equivalent. Customize config.toml before starting.
- Maps format: maps must be in .vxl format compatible with Ace of Spades 0.75. A community map library exists at piqueserver.readthedocs.io.

## Links

- Source: https://github.com/piqueserver/piqueserver
- Documentation: https://piqueserver.readthedocs.io
- OpenSpades client: https://openspades.yvt.jp/
- PyPI: https://pypi.org/project/piqueserver/
- AUR: https://aur.archlinux.org/packages/piqueserver-git/
