Deploying Piqueserver

Introduction

Piqueserver is an open-source game server for Ace of Spades, the voxel-based first-person shooter that combines Minecraft-style building with team-based combat. As a Python-based fork of the original PySnip server, Piqueserver offers modern features, better stability, and an active development community.

The server supports various game modes, custom maps, player management, and an extensive scripting system for customization. Whether you’re running casual matches or competitive tournaments, Piqueserver provides the flexibility needed for any playstyle.

Key highlights of Piqueserver:

• Multiple Game Modes: Support for CTF, Team Deathmatch, and custom game modes
• Custom Maps: Load community maps or create your own voxel worlds
• Player Management: Built-in admin tools, bans, kicks, and moderation features
• Scripting System: Python-based scripts for game customization
• Anti-Cheat Features: Built-in protection against common cheats
• Statistics Tracking: Track player stats, kills, and achievements
• Discord Integration: Connect server events to Discord channels
• IRC Support: Bridge game chat with IRC channels
• Map Rotation: Automatic map cycling and voting systems
• Low Resource Usage: Efficient Python server with minimal requirements

This guide walks through deploying Piqueserver on Klutch.sh using Docker, configuring game settings, and managing your Ace of Spades server.

Why Deploy Piqueserver on Klutch.sh

Deploying Piqueserver on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Piqueserver without complex server setup. Push to GitHub, and your game server deploys automatically.

Persistent Storage: Attach persistent volumes for maps, configurations, and player data. Your server settings survive container restarts.

GitHub Integration: Connect your configuration repository directly from GitHub for version-controlled server management.

Scalable Resources: Allocate CPU and memory based on expected player count and server load.

Environment Variable Management: Configure server settings through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for web-based status pages and administration.

Always-On Availability: Your game server remains accessible 24/7 for players worldwide.

Prerequisites

Before deploying Piqueserver on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Piqueserver configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of game server administration
• (Optional) Custom maps in VXL format

Understanding Piqueserver Architecture

Piqueserver uses a modular Python architecture:

Core Server: Handles network communication, game state, and player connections. Built on Twisted for asynchronous networking.

Game Modes: Pluggable game mode system supporting CTF, TDM, and custom modes through Python scripts.

Map System: Loads VXL format maps and manages the voxel world state. Supports map rotation and dynamic loading.

Script System: Extensible through Python scripts for custom features, commands, and game modifications.

Protocol Handler: Implements the Ace of Spades protocol for client-server communication.

Preparing Your Repository

To deploy Piqueserver on Klutch.sh, create a GitHub repository with your Dockerfile and configuration.

Repository Structure

piqueserver-deploy/
├── Dockerfile
├── README.md
├── .dockerignore
├── config/
│   └── config.toml
└── maps/
    └── classicgen.vxl

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM piqueserver/piqueserver:latest

# Copy custom configuration
COPY config/config.toml /config/config.toml

# Copy custom maps
COPY maps/ /config/maps/

# Set environment variables
ENV PIQUE_CONFIG_DIR=/config
ENV PIQUE_SERVER_NAME=${PIQUE_SERVER_NAME:-Klutch Piqueserver}
ENV PIQUE_MAX_PLAYERS=${PIQUE_MAX_PLAYERS:-32}
ENV PIQUE_GAME_MODE=${PIQUE_GAME_MODE:-ctf}

# Expose game port
EXPOSE 32887/udp

# Health check (basic process check)
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD pgrep -f piqueserver || exit 1

CMD ["piqueserver", "-d", "/config"]

Creating the Configuration File

Create config/config.toml:

[server]
name = "Klutch Piqueserver"
max_players = 32
game_mode = "ctf"
cap_limit = 10
respawn_time = 5
friendly_fire = false
fall_damage = true
balanced_teams = true

[server.motd]
lines = [
    "Welcome to our Piqueserver!",
    "Have fun and play fair!"
]

[team]
1 = { name = "Blue", color = [0, 0, 255] }
2 = { name = "Green", color = [0, 255, 0] }

[maps]
rotation = ["classicgen", "pinpoint", "hallway"]
default = "classicgen"

[network]
max_connections = 20
port = 32887

[ban]
file = "/config/bans.txt"

[logging]
level = "info"
rotate = true

[scripts]
enabled = [
    "rollback",
    "antispam",
    "votekick",
    "protect"
]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
PIQUE_CONFIG_DIR	No	/config	Configuration directory path
PIQUE_SERVER_NAME	No	Piqueserver	Server name shown in server list
PIQUE_MAX_PLAYERS	No	32	Maximum players allowed
PIQUE_GAME_MODE	No	ctf	Default game mode

Deploying Piqueserver on Klutch.sh

Prepare Your Maps

Download or create custom maps in VXL format and add them to your maps/ directory.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore config/ maps/ README.md
git commit -m "Initial Piqueserver deployment configuration"
git remote add origin https://github.com/yourusername/piqueserver-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “piqueserver” or “aos-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Piqueserver Dockerfile.

Configure Traffic

Piqueserver uses UDP for game traffic. Configure accordingly:

• Note that game traffic uses UDP port 32887
• For status/web interfaces, configure HTTP traffic if needed

Set Environment Variables

In the environment variables section, add:

Variable	Value
PIQUE_SERVER_NAME	Your Server Name
PIQUE_MAX_PLAYERS	32
PIQUE_GAME_MODE	ctf

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/config	1 GB	Configuration, maps, and player data
/logs	1 GB	Server logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and deploy your Piqueserver instance.

Connect to Your Server

Once deployment completes, connect using an Ace of Spades client with your server’s address and port 32887.

Server Configuration

Game Modes

Configure different game modes:

Capture the Flag (CTF)

[server]
game_mode = "ctf"
cap_limit = 10

Team Deathmatch

[server]
game_mode = "tdm"
kill_limit = 100

Map Rotation

Set up automatic map cycling:

[maps]
rotation = ["classicgen", "pinpoint", "hallway", "nuketown"]
default = "classicgen"
advance_on_win = true

Admin Configuration

Set up server administrators:

[admin]
passwords = ["admin_password", "mod_password"]

Scripting and Customization

Enabling Scripts

Add scripts to enhance your server:

[scripts]
enabled = [
    "rollback",      # Undo griefing
    "antispam",      # Prevent chat spam
    "votekick",      # Player voting
    "ratio",         # Kill/death ratios
    "disco",         # Fun effects
    "analyze"        # Anti-cheat
]

Custom Scripts

Create custom scripts in /config/scripts/:

example.py

from piqueserver.commands import command

@command()
def hello(connection):
    connection.send_chat("Hello from the server!")

Troubleshooting Common Issues

Players Cannot Connect

• Verify UDP port 32887 is accessible
• Check firewall rules
• Ensure server is listed correctly

Server Crashes

• Review server logs for errors
• Check memory and CPU allocation
• Verify map files are valid

Map Loading Issues

• Ensure VXL files are valid format
• Check file permissions
• Verify map names in configuration

Additional Resources

• Official Piqueserver Website
• Piqueserver Documentation
• Piqueserver GitHub Repository
• Ace of Spades Maps
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Piqueserver on Klutch.sh provides a reliable foundation for hosting Ace of Spades matches. The combination of Piqueserver’s customization options and Klutch.sh’s deployment simplicity enables running game servers without managing physical infrastructure.

Whether you’re hosting casual games with friends or running competitive matches, Piqueserver on Klutch.sh delivers the flexibility and reliability needed for an engaging multiplayer experience.