Introduction

Serverlist

The semi-official server list can be browsed on build & shoot.

The data can be parsed in the JSON format from http://services.buildandshoot.com/serverlist.json. It does not directly contain IP addresses. They have to be decoded by following the algorithm first.

AoS URLs

AoS uses urls like "aos://1124169524:43887" to encode the ip and port of a server. This is a guide on how to parse them.

Parsing Algorithm

strip protocol prefix (e.g. "aos://" -> "1124169524:43887")
search for colon (e.g. ":" -> "1124169524" ":" "43887")
1. if none found
  1. port is default port (32887)
2. if found
  1. split at colon (e.g. ":" -> "1124169524" ":" "43887")
  2. port is second part
  3. continue with first part
search for dot (e.g. "." -> none found in "1124169524")
1. if at least one (or better, exactly four) found (e.g. "192.168.1.1")
  1. URL is IP
2. if none found
  1. URL is an integer address, parse it as explained here

Decoding integer addresses

The integer address is a 32-bit integer that represents the IP address. The IP address is encoded in big-endian. It can be decoded by using the following algorithm:

to get the four IP parts:
1. apply bitwise AND with 255 (e.g., "1124169524" & 255 -> 52)
2. right-shift the URL by 8 bits and then apply bitwise AND with 255 (e.g., ("1124169524" >> 8) & 255 -> 119)
3. right-shift the URL by 16 bits and then apply bitwise AND with 255 (e.g., ("1124169524" >> 16) & 255 -> 1)
4. right-shift the URL by 24 bits and apply bitwise AND with 255 (e.g., ("1124169524" >> 24) & 255 -> 67)
the four IP parts are 52, 119, 1, 67
join the parts with dots (e.g. "52.119.1.67")

Example JS code:

let ip = ${url & 255}.${(url >> 8) & 255}.${(url >> 16) & 255}.${(url >> 24) & 255}

Protocol

The Ace of Spades (AoS) protocol documentation. This page is based on protocol documentation from piqueserver and heavily modified. The modifications are made to reflect the protocol supported by rspades. In general, rspades aims to support the same protocol as OpenSpades does.

The protocol documented here supports:

AoS version 0.75, the last fully released version of Ace of Spades Classic
AoS version 0.76, the last publically available version of Ace of Spades Classic
Extra packets (EP): Extra packets that were added by the community and are supported by OpenSpades and BetterSpades

The 0.76 protocol is based on 0.75, but with some changes. The main features of 0.76 are:

Flexible player count
Map caching

Additionally, we provide documentation for the following protocols, which are currently not supported by rspades:

powerthirst.md Powerthirst Edition protocol, which is used by the Powerthirst Edition mod for AoS 0.75
extension.md: The extension negotiation protocol, that allows for custom packets to be sent between the server and the client

Primer

The AoS protocol is based on UDP and builds on top of the ENet library for networking. Generally, all fields in the Protocol are Low Endian if not specified.

The following shorthands for data types are used in this document:

Shorthand	details
SByte	8 bits of arbitrary data. Usually accompanied by a note
UByte	Unisgned 8 bit number
SInt	32bit singed integer (little endian)
UInt	32bit unsigned integer (little endian)
Float	32bit IEEE float (little endian)
CP437 String	String encoded with CP437. Usually fixed-length.

Connection

When you connect, you must send a version number as the initial data. Following that a client needs to send an Existing Player data packet to send its own name, team, etc. If the client does not send an Existing Player packet first, but any other packet, then the server closes the connection and seems to temporarily ban the player.

Number	AoS version
3	0.75
4	0.76

Send this magic number as part of the enet_host_connect(ENetHost, ENetAddress, channels, int) function

Disconnect Reasons

Whenever the connection is closed by the server, there is a reason supplied to the client in the event's data (event.data).

Number	Reason
1	Banned
2	IP connection limit exceded?
3	Wrong protocol version
4	Server full
10	Kicked

About Coordinates

In AoS the up-down axis is Z and it is inverted. This means 63 is the water level and 0 is the highest point on a map.

Packets

All packets start with an unsigned SByte to specify their type, followed by the data for that type of packet. The size given for each packet below includes this SByte.

Position Data

Client <-> Server

This packet is used to set the player's position.


Packet ID:	0
Total Size:	13 Bytes

Field Name	Field Type	Example
x	Float	`0`
y	Float	`0`
z	Float	`0`

Field Name	Field Type	Example
x	Float	`0`
y	Float	`0`
z	Float	`0`

Field Name	Field Type	Example	Notes
x position	Float	`0`	0 for non-players
y position	Float	`0`	0 for non-players
z position	Float	`0`	0 for non-players
x orientation	Float	`0`	0 for non-players
y orientation	Float	`0`	0 for non-players
z orientation	Float	`0`	0 for non-players

Field Name	Field Type	Example
player ID	UByte	`0`
x position	Float	`0`
y position	Float	`0`
z position	Float	`0`
x orientation	Float	`0`
y orientation	Float	`0`
z orientation	Float	`0`