Ace of Spades Protocol

From Ace of Spades Classic
Jump to: navigation, search

This page documents Ace of Spades 0.75, the last fully released version of Ace of Spades classic, and 0.76, the last publically available version of Ace of Spades Classic.

Contents

Overview

Ace of Spades uses the ENet networking library for all server-client communication. The only current source of protocol information is the pyspades source, which is being made a closed system at the release of Ace of Spades 1.0. The reason(s) for this is unknown, but it is speculated that Jagex has paid them off, as they now own AoS. An open-source Java server implementation, Jack of Spades, is currently being worked on.

Packets

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

Position Data

Brief description.

Packet ID Field Name Field Type Example Notes
0 x LE Float 0
y LE Float 0
z LE Float 0
Total Size: 13 bytes

Orientation Data

Brief description.

Packet ID Field Name Field Type Example Notes
1 x LE Float 0
y LE Float 0
z LE Float 0
Total Size: 13 bytes

World Update (0.75)

Updates position and orientation of all players. Always sends data for 32 players, with empty slots being all 0 (position: [0,0,0], orientation: [0,0,0]).

Packet ID Field Name Field Type Example Notes
2 players positions and orientations Array[32] of Player Position Data See below table for data
Total Size: 769 bytes

Player Position Data

Field Name Field Type Example Notes
x position LE Float 0 0 for non-players
y position LE Float 0 0 for non-players
z position LE Float 0 0 for non-players
x orientation LE Float 0 0 for non-players
y orientation LE Float 0 0 for non-players
z orientation LE Float 0 0 for non-players
Total Size: 24 bytes

World Update (0.76)

Updates position and orientation of all players. Unlike 0.75, this only sends information for the necessary players.

Packet ID Field Name Field Type Example Notes
2 players positions and orientations Array[] of Player Position Data, variable size See below table for data
Total Size: 1 + 25n bytes

Player Position Data

Field Name Field Type Example Notes
player ID UByte 0
x position LE Float 0
y position LE Float 0
z position LE Float 0
x orientation LE Float 0
y orientation LE Float 0
z orientation LE Float 0
Total Size: 25 bytes

Input Data

Contains the key-states of a player, packed into a byte.

Packet ID Field Name Field Type Example Notes
3 player ID UByte 0
key states UByte 0 Each bit in the byte represents a key, as defined in the table below.
Total Size: 3 bytes
Placement Key
1 up
2 down
3 left
4 right
5 jump
6 crouch
7 sneak
8 sprint

Weapon Input

Contains the weapon input state(?).

Packet ID Field Name Field Type Example Notes
4 player ID UByte 0
weapon input UByte 0 The lowest bit represents the primary fire, the second lowest represents the secondary fire.
Total Size: 3 bytes

Hit Packet

Client-to-Server

Sent by the client when a hit is registered. The server should verify that this is possible to prevent abuse (such as hitting without shooting, facing the wrong way, etc).

Packet ID Field Name Field Type Example Notes
5 player ID hit UByte 0
hit type UByte 0 See values in table below
Total Size: 3 bytes
Value Type
0 torso
1 head
2 arms
3 legs
4 melee

Set HP

Server-to-Client

Sent to the client when hurt.

Packet ID Field Name Field Type Example Notes
5 HP UByte 0
type UByte 0 0 = fall, 1 = weapon
source x position LE Float 0
source y position LE Float 0
source z position LE Float 0
Total Size: 15 bytes

Grenade Packet

Spawns a grenade with the given information.

Packet ID Field Name Field Type Example Notes
6 player ID UByte 0
fuse length LE Float 0
x position LE Float 0
y position LE Float 0
z position LE Float 0
x velocity LE Float 0
y velocity LE Float 0
z velocity LE Float 0
Total Size: 30 bytes

Set Tool

Sets a player's current;y equipped tool/weapon.

Packet ID Field Name Field Type Example Notes
7 player ID UByte 0
tool UByte 0 Tool values are listed below
Total Size: 3 bytes
Value Type
0 spade
1 block
2 gun
3 grenade

Set Colour

Set the colour of a player's held block.

Packet ID Field Name Field Type Example Notes
8 player ID UByte 0
blue UByte 0
green UByte 0
red UByte 0
Total Size: 5 bytes

Existing Player

Set player's team, weapon, etc.

Packet ID Field Name Field Type Example Notes
9 player ID UByte 0
team Byte 0
weapon UByte 0
held item UByte 0
kills LE UInt 0
blue UByte 0
green UByte 0
red UByte 0
name CP437 String
Total Size: . bytes

Short Player Data

Like Existing Player, but with less information.

Packet ID Field Name Field Type Example Notes
10 player ID UByte 0
team Byte 0
weapon UByte 0
Total Size: 4 bytes

Move Object

Brief description.

Packet ID Field Name Field Type Example Notes
11 object id UByte 0
team UByte 0 2 = neutral
x position LE Float 0
y position LE Float 0
z position LE Float 0
Total Size: 15 bytes

Create Player

Brief description.

Packet ID Field Name Field Type Example Notes
12 player id UByte 0
weapon UByte 0
team Byte 0
x position LE Float 0
y position LE Float 0
z position LE Float 0
name CP437 String
Total Size: . bytes

Block Action

Sent when a block is placed/destroyed.

Packet ID Field Name Field Type Example Notes
13 player id UByte 0
action type UByte 0 See table below
x position LE Int 0
y position LE Int 0
z position LE Int 0
Total Size: 15 bytes
Value Type
0 build
1 (bullet?) destroy
2 spade destroy
3 grenade destroy

Block Line

Create a line of blocks between 2 points.

Packet ID Field Name Field Type Example Notes
14 player id UByte 0
start x position LE Int 0
start y position LE Int 0
start z position LE Int 0
end x position LE Int 0
end y position LE Int 0
end z position LE Int 0
Total Size: 15 bytes

CTF State

Brief description.

Packet ID Field Name Field Type Example Notes
team 1 score UByte 0
team 2 score UByte 0
capture limit UByte 0
intel flags UByte 0 bits signal if teams have intel - bit 1 for team 1, bit 2 for team 2
team 1 intel location Location Data 0 see below
team 2 intel location Location Data 0 see below
team 1 base x position LE Float 0
team 1 base y position LE Float 0
team 1 base z position LE Float 0
team 2 base x position LE Float 0
team 2 base y position LE Float 0
team 2 base z position LE Float 0
Total Size: 15 bytes

The intel location data is 12 bytes long. If the intel is being held, the first byte is a UByte with the id of the holding player, then the rest are padding. If the intel is on the ground (not being held), the data will hold three LE Floats with its x, y and z position.

Intel State Field Name Field Type
Held holding player id UByte
padding 11 bytes
Dropped intel x position LE Float
intel y position LE Float
intel z position LE Float

This packet is not a complete packet, as it is only sent after the initial data, where the gamemode is sent. It could be considered as part of that initial data packet, but as what's sent varies greatly depending on the gamemode, it is documented separately.

Territory

Brief description.

Object Territory

Brief description.

TCState

Brief description.

State Data

Server->Client

Indicates that the map transfer is complete. Also informs the client of numerous game parameters. Be aware that CTFState or TCState may be appended to the packet after the gamemode id portion.

Packet ID Field Name Field Type Example Notes
15 fog (blue) UByte 0
fog (green) UByte 0
fog (red) UByte 0
team 1 color (blue) UByte 0
team 1 color (green) UByte 0
team 1 color (red) UByte 0
team 2 color (blue) UByte 0
team 2 color (green) UByte 0
team 2 color (red) UByte 0
team name 1 CP437 String
team name 2 CP437 String
gamemode id UByte 0 0 for CTF, 1 for TC
Total Size: 30 bytes

Kill Action

Server->Client

Notify the client of a player's death.

Packet ID Field Name Field Type Example Notes
18 player ID UByte 12 Player that died
killer ID UByte 8
kill type UByte 0 See table below
respawn time UByte 1 Seconds until respawn
Total Size: 5 bytes
Value Type
0 WEAPON (body, limbs)
1 HEADSHOT
2 MELEE (spade)
3 GRENADE
4 FALL
5 TEAM_CHANGE
6 CLASS_CHANGE

Chat Message

Two-way

Reasonable limits must placed on length and frequency of chat messages.

Packet ID Field Name Field Type Example Notes
17 player id UByte 0
Chat Type UByte 0 See table below
Chat Message CP437 String "join /squad 1"
Total Size: . bytes
Value Type
0 CHAT_ALL
1 CHAT_TEAM
2 CHAT_SYSTEM

Map Start (0.75)

Server->Client

Sent when a client connects, or a map is advanced for already existing connections.

Should be the first packet received when a client connects.

Packet ID Field Name Field Type Example Notes
18 Map size Uint32 4567
Total Size: 5 bytes

Map Start (0.76)

Server->Client

Sent when a client connects, or a map is advanced for already existing connections.

Should be the first packet received when a client connects.

Packet ID Field Name Field Type Example Notes
18 Map size Uint32 283839
CRC32 Uint32 0x4c7ebe43
Map name CP437 String "pinpoint2"
Total Size: 9+ bytes

Map Chunk

Server->Client

Sent just after Map Start, repeatedly until the entire map is sent.

Should always be the next sequence of packets after a Map Start.

Packet ID Field Name Field Type Example Notes
19 Map Data UByte 0 DEFLATE/zlib encoded AOS map data
Total Size: (varies) bytes

Player Left

Server->Protocol

Sent when a player disconnects.

Packet ID Field Name Field Type Example Notes
20 player ID UByte 0
Total Size: 2 bytes

Territory Capture

Server->Protocol

Sent when a player captures a Command Post in Territory Control mode.

Captures have affects on the client.

Packet ID Field Name Field Type Example Notes
21 player ID UByte 0
entity ID UByte 0 The ID of the CP being captured
winning UByte 0 (or losing)
state UByte 0 team id
Total Size: 5 bytes

Progress Bar

Server->Client

Display the TC progress bar.

Packet ID Field Name Field Type Example Notes
22 entity ID UByte 0 The ID of the tent entity(?)
capturing team ID UByte 1
rate Byte 2 Used by the client for interpolation(?)

One per team member capturing (minus enemy team members)

progress LE Float 0.5 In range [0,1]
Total Size: 8 bytes

Intel Capture

Server->Protocol

Sent when a player captures the intel, which is determined by the server.

Winning captures have affects on the client.

Packet ID Field Name Field Type Example Notes
23 player ID UByte 0
winning UByte 0 Was the winning capture
Total Size: 3 bytes

Intel Pickup

Server->Protocol

Sent when a player collects the intel, which is determined by the server.

Packet ID Field Name Field Type Example Notes
24 player ID UByte 0
Total Size: 2 bytes

Intel Drop

Server->Protocol

Sent when a player dropped the intel. This will update the intel position on the client.

Packet ID Field Name Field Type Example Notes
25 player ID UByte 0 ID of the player who dropped intel
x position LE Int 32.0
y position LE Int 32.0
z position LE Int 32.0
Total Size: 13 bytes

Restock

Server->Protocol

Id of the player who has been restocked.

Packet ID Field Name Field Type Example Notes
26 player ID UByte 0 ID of the player who restocked
Total Size: 2 bytes

Fog Colour

Server->Client

Set the colour of a player's fog.

Packet ID Field Name Field Type Example Notes
27
fog color UInt32 0h00fefefe BGRA encoded
Total Size: 5 bytes

Weapon Reload

Client-->Server->Protocol

Sent by the client when the player reloads their weapon, and relayed to other clients after protocol logic applied.

This has no affect on animation, but is used to trigger sound effects on the other clients.

Packet ID Field Name Field Type Example Notes
28 player ID UByte 0 Player who reloaded
clip ammo UByte 0
reserve ammo UByte 0
Total Size: 4 bytes

Change Team

Client-->Server-->Protocol-->Kill Action & Create Player

Sent by the client when the player changes team. Is not relayed to all clients directly, but instead uses Kill Action then Create Player to inform other clients of the team change.

Packet ID Field Name Field Type Example Notes
29 player ID UByte 0 Player who changed team
Team ID Byte 0 See values in table below
Total Size: 3 bytes
Value Type
-1 spectator
0 blue
1 green

Change Weapon

Client-->Server-->Protocol-->Kill Action & Change Weapon

Sent by the client when player changes weapon, and relayed to clients by server after filter_visibility logic applied.

Receiving clients will also be sent a preceding Kill Action to inform them the player has died both of which are sent as reliable packets.

Packet ID Field Name Field Type Example Notes
30 player ID UByte 0 Player who's changed weapon
Weapon ID UByte 0 See values in table below
Total Size: 3 bytes
Value Type
0 rifle
1 smg
2 shotgun

Map Cached

Client->Server

TODO.

Powerthirst Edition

This version adds 4 new packets, extends 2 packets, and duplicately maps 1 packet over another.

The World Update packet has up to 64 fields now instead of 32.

Map Start (PT)

Server->Client

Sent when a client connects, or a map is advanced for already existing connections.

Should be the first packet received when a client connects.

The version must exist and be >= 1 (and <= the client's Powerthirst proto version or otherwise the client will refuse to connect) to enable certain Powerthirst features such as long-name support.

Packet ID Field Name Field Type Example Notes
18 Map size Uint32 4567
PT version UInt32 4
Total Size: 9 bytes

Map Chunk (PT)

Server->Client

This is just a remapping of the Map Chunk packet to 2 packets back to stop vanilla clients from connecting.

Packet ID Field Name Field Type Example Notes
17 Map Data UByte 0 DEFLATE/zlib encoded AOS map data
Total Size: (varies) bytes

Script Begin (PT)

Server->Client

Packet ID Field Name Field Type Example Notes
31 Script size Uint32 4567
Module name CP437 String
Total Size: (varies) bytes

Script Chunk (PT)

Server->Client

This is just a remapping of the Map Chunk packet to 2 packets back to stop vanilla clients from connecting.

Packet ID Field Name Field Type Example Notes
32 Script Data UByte 0 DEFLATE/zlib encoded AngelScript source code
Total Size: (varies) bytes


Script End (PT)

Server->Client

Once this is sent, the script is loaded.

Packet ID Field Name Field Type Example Notes
33 Module name CP437 String
Total Size: (varies) bytes

Script Call (PT)

Server->Client

Packet ID Field Name Field Type Example Notes
34 Function name 0-terminated CP437 String void main() Must be an AngelScript prototype, not just the name itself
Parameters See below
Total Size: (varies) bytes

Script Parameters

Start from after the 0-byte in the Function name string. Then, loop through these IDs:

  • 0: ASP_TERM: End of parameter list.
  • 1: ASP_INT: Read a 32-bit little-endian int. AngelScript type: "int"
  • 2: ASP_FLOAT: Read a 32-bit little-endian single-precision float. AngelScript type: "float"
  • 3: ASP_PSTRING: Read an 8-bit uint, then read that many bytes as a string (do NOT add in a terminating NUL). AngelScript type: "const string &in"
Personal tools