Welcome to piqueserver’s documentation!¶

Piqueserver is an Ace of Spades 0.75 Server based on Pysnip.

Installation¶

Note

piqueserver only supports python 3.7 and above

All platforms¶

Installing with pip¶

pip3 install piqueserver # vanilla install
pip3 install piqueserver[ssh] # if you also want ssh server

Unix-like¶

Installing from source¶

# required for https, pillow, map compression etc.
# these are for ubuntu 16.04, find similar packages for your own distro/OSs
sudo apt-get install python3-dev libssl-dev libffi-dev libjpeg-dev zlib1g-dev
# get the source
git clone https://github.com/piqueserver/piqueserver
cd piqueserver
# we make git tags for every version so you can checkout out to specific version if you want
# git checkout v0.1.3
# create a new python3 venv
virtualenv -p python3 venv
source venv/bin/activate
# install deps.
pip install -r requirements.txt
# install piqueserver
python setup.py install

# don't forget to deactivate the venv when finished!
deactivate

Windows¶

Installation from source¶

Note

Most of the piqueserver team uses Linux and we aren’t experienced with Cython on windows. If you can help us improve windows support we’d greatly appreciate it.

Tricky bit for windows is to get Cython working.

Install Visual C++ compiler please follow this guide.
Don’t forget to upgrade setuptools
Install git or download sources from github and unzip
If you decided to use git: git clone https://github.com/piqueserver/piqueserver

Tip

If you see errors like “unable to find vcvarsall.bat” refer to this article.

cd piqueserver
pip3 install -r requirements.txt
python setup.py install

Configuring Piqueserver¶

Piqueserver is configured through a config file, usually named config.toml. Piqueserver uses the configuration language TOML (Tom’s Obvious Markup Language). A detailed description of TOML can be found in the TOML readme, but a short example is provided below.

Note

PySpades, PySnip and versions of piqueserver before 1.0.0 used a JSON file for settings. These files will still be read, if no config.toml is available. However, the structure piqueserver expects might differ.

TOML Syntax¶

TOML files are plaintext files. They can be edited with any plaintext editor of your choice, such as Notepad++ on windows, editor on mac and, nano or gedit on Linux.

Configuration is case-sensitive. This means that your settings will not apply correctly if you use the incorrect case.

The section header is followed by key-value pairs:

name = "best server ever"

If a # is encountered, the rest of the line will be ignored.

There are a number of types of values:

text = "text, surrounded by quotes"

motd = """
a longer text
that can stretch
over more lines
(useful for the MOTD!)"""

list = ["a", "list",
        "of", "values"]

a_number = 123.5
enable_thing = true  # or false

TOML supports sections similar to the Microsoft .ini file format. The beginning of a section is marked by the name of the section surrounded by square brackets:

[general]

Any key-value pairs that follow this are part of that section, until a new section is started.

Substitution¶

Some config options allow data about the server to be substituted. These options are enclosed in curly braces. This example uses all substitutions that are available when substitution is available for a config option:

motd = [
    "Welcome to {server_name}! See /help for commands.",
    "you are playing {game_mode}",
    "Map is {map_name} by {map_author}.",
    "Map description: {map_description}.",
    "(server powered by piqueserver)",
]

Individual config options might have additional substitutions available. This is noted in the documentation for the relevant option.

New in version 1.0.0: The {name} format was added. The older, %(name)s format is deprecated.

Config directory structure¶

The configuration directory follows a strict structure.

By default the configuration directory lives at $XDG_CONFIG_HOME/piqueserver/ with a fallback to $HOME/.config/piqueserver/, as specified by the XDG Base Directory Specification.

This can be overridden by the -d command line option.

.
├── bans.txt               # Player bans get stored in this file; it is created automatically.
├── config.toml            # The main configuration file. By default piqueserver will look for config.toml in the config directory.
│                          # This can be overridden by the -c command line option.
├── game_modes             # Scripts that are specifically game modes will be stored here.
│   └── buildandsplat.py   # Your custom game mode script
├── logs                   # This directory contains logs output by the server.
│   └── log.txt            # The main server logfile; If you disable daily rotation of log files all logs go here.
├── maps                   # Any map files should be stored in here. Where a map is specified by name in "rotation" config option
│   ├── classicgen.txt     # the server will look for  a .txt or .txt/.vxl file with that name.
│   └── random.txt
├── scripts                # You can add other scripts not included with piqueserver here.
│   │                      # The server will load any scripts listed in "scripts" config option by name from here.
│   └── showhp.py          # For example, if "showhp" is listed in the "scripts" config option, then scripts/showhp.py will be loaded.
│
└── data                   # Various other data files are stored here.
    └── GeoLiteCity.dat    # Currently it's only used for the geoip data file required by the /from command in-game.

Options¶

Base Configuration Options¶

These are the base configuration options available in piqueserver.

General¶

This section contains general information and configuration for the server