Artemis Protocols

Introduction

This is unoffical documentation of the network and file protocols used by Artemis Spaceship Bridge Simulator. No official documentation exists, so the information in this document has been obtained through community reverse-engineering efforts. There will be parts of the protocols that are not completely documented because their purpose has not been determined, and some parts may not be accurate. Contributions to this documentation are welcome.

Data Types

The Artemis protocols use the following data types:

byte
short (2 bytes)
int (4 bytes)
float (4 bytes)
bit field (variable length)
boolean (variable length)
string (variable length)

These types can be combined in structs or arrays.

Endianness

All multi-byte data types are represented in little-endian order (least-significant byte first). Numeric literals in this documentation, in order to follow the existing convention for many programming languages, are prefixed with 0x and are written in big-endian order. For example, the four bytes that begin every Artemis packet are ef be ad de; represented as an int, this is 0xdeadbeef.

Numeric Format

Integral types (byte, short, int) use two's complement representation in binary. Floats use IEEE 754 binary32 format.

Bit Field Format

A bit field is one or more bytes that encodes a series of on/off switches. Each bit in the binary representation of each byte in the field represents a single switch. In this documentation, an individual bit in a bit field is represented with the notation “bit {byte}.{bit}”, where the byte and bit values are one-based, and the bits are counted in little-endian order (least-significant bits first).

The most common use for a bit field is to declare which properties are defined in a struct. Each bit represents a property, with 1 indicating that the property is defined, and 0 meaning it is undefined. When sending updates to clients, the Artemis server typically omits properties which are unchanged since the last update; these properties will be undefined when the updated struct is transmitted.

Example

A single-byte bit field with the value 0x42 is represented in little-endian binary as 01000010. Bits 1.2 and 1.7 are on, the rest are off.

Boolean Format

Boolean values are simply expressed as an integer value 0 (false) or 1 (true). This value may be transmitted as a byte, short or int. In this documentation, a field is considered to be a boolean if all the following conditions are met:

There are only two possible values.
The values are exact opposites (true/false, on/off, etc.).
They are represented by 0 and 1.
It does not seem that other values could be added in the future. (If other values are deemed possible, the field's value is documented as an enumeration instead.)

String Format

Strings are represented by an int giving the length of the string in characters, followed by the string itself encoded in UTF-16LE. Because UTF-16 encodes each character in two bytes, the number of bytes to read after the length value is the number of characters times two. Strings are null-terminated (0x0000), and the length value includes the null. Under normal circumstances, the null character would be the last two bytes read for the string; if the null character occurs earlier, the remaining bytes are meaningless and should be discarded. Zero-length strings are not allowed. For brevity's sake, all values denoted as strings in this documentation are presumed to follow this format, and the string length value will not be documented separately.

Example

To interpret the byte sequence 04 00 00 00 48 00 69 00 21 00 00 00 as a string, you would first read an int (4 bytes) to learn the string's length: 04 00 00 00, which is four characters. In UTF-16, this is eight bytes, so you'd then read eight bytes from the stream: 48 00 69 00 21 00 00 00. Decoded, this is H, i, ! and null, which terminates the string. Thus, the byte sequence represents the string "Hi!"

Array Format

Arrays consist of an ordered list of values. These values can be primitive types, strings, structs or other arrays. There are two basic kinds of arrays: delimited and undelimited. Delimited arrays are typically used in circumstances where the exact number of elements in the array is not known in advance. Elements are transmitted one after the other until a particular byte is encountered instead of more data. With undelimited arrays, either the exact size or exact number of elements is known, so no delimiter is needed. Instead, parsing continues until the desired number of elements is read, or all the bytes that make up the array are consumed.

Structs

Structs are complex types composed of primitive types, strings, arrays or other structs. These properties are always specified in a particular defined order, so that it is unneccessary to declare each property's name when reading or writing a struct. There are two type of structs: static structs and bit field structs. A static struct always transmits all of its properties. A bit field struct has a bit field as its first property. Each bit in the field corresponds to one of the remaining properties in the struct. If a bit is 1, that property is defined; if it's 0, it is undefined and is omitted from the struct. When the Artemis server sends game object updates, it will typically use bit field structs to only send properties which have changed and leave the rest undefined; this reduces the payload size for update packets.

Enumerations

When Artemis needs to refer to an item from a static list (enumeration), it will use a predefined numeric value to represent it. This section documents these enumerations.

Alert Status

`0x00`	Normal
`0x01`	Red Alert

Audio Command

`0x00`	Play
`0x01`	Dismiss

Audio Mode

`0x00`	unused
`0x01`	playing
`0x02`	incoming

Beam Frequency

`0x00`	A
`0x01`	B
`0x02`	C
`0x03`	D
`0x04`	E

COMM Message

To players:

`0x00`	Yes.
`0x01`	No.
`0x02`	Help!
`0x03`	Greetings.
`0x04`	Die!
`0x05`	We're leaving the sector. Bye.
`0x06`	Ready to go.
`0x07`	Please follow us.
`0x08`	We'll follow you.
`0x09`	We're badly damaged.
`0x0a`	We're headed back to the station.
`0x0b`	Sorry, please disregard.

To enemies:

`0x00`	Will you surrender?
`0x01`	Taunt #1 (varies by race)
`0x02`	Taunt #2 (varies by race)
`0x03`	Taunt #3 (varies by race)

Comm Station Message

`0x00`	Prepare Docking
`0x01`	Report Status
`0x02`	Build Homing
`0x03`	Build Nukes
`0x04`	Build Mines
`0x05`	Build Emps
`0x06`	Build Pshocks

To other ships:

`0x00`	Report status
`0x01`	Turn to heading 0
`0x02`	Turn to heading 90
`0x03`	Turn to heading 180
`0x04`	Turn to heading 270
`0x05`	Turn 10 degrees to port
`0x06`	Turn 10 degrees to starboard
`0x07`	Attack nearest enemy
`0x08`	Proceed to your destination
`0x09`	Go defend [target]
`0x0a`	unused
`0x0b`	unused
`0x0c`	unused
`0x0d`	unused
`0x0e`	unused
`0x0f`	Turn 25 degrees to port
`0x10`	Turn 25 degrees to starboard

Comm Target Type

`0x00`	Player
`0x01`	Enemy
`0x02`	Station
`0x03`	Other

Connection Type

`0x01`	Server
`0x02`	Client

Console Status

`0x00`	Available
`0x01`	Yours
`0x02`	Unavailable

Console Type

	< v2.1	≥ v2.1, < v2.3	≥ v2.3
`0x00`	main screen	main screen	main screen
`0x01`	helm	helm	helm
`0x02`	weapons	weapons	weapons
`0x03`	engineering	engineering	engineering
`0x04`	science	science	science
`0x05`	communications	communications	communications
`0x06`	observer	data	fighter
`0x07`	captain's map	observer	data
`0x08`	game master	captain's map	observer
`0x09`	unused	game master	captain's map
`0x0a`	unused	unused	game master

Creature Type

`0x00`	Classic Monster
`0x01`	Whale
`0x02`	Shark
`0x03`	Dragon
`0x04`	Piranha
`0x05`	Charybdis
`0x06`	Insect
`0x07`	Wreck

Drive Type

`0x00`	Warp
`0x01`	Jump

Special Ability

Note: Special abilities can stack, in which case the values are ORed together. For example, cloak and warp would be 0x14. A ship with no special abilities would have a special ability value of 0x00. Special abilities used to be called elite abilities in earlier versions of the game.

Flag	Internal name	Alt name	Description
`0x0001`	ELITE_INVIS_TO_MAIN_SCREEN	Stealth	Cannot be seen on main screen
`0x0002`	ELITE_INVIS_TO_TACTICAL	LowVis	Cannot be seen on tactical map
`0x0004`	ELITE_CLOAKING	Cloak	Can become completely invisible
`0x0008`	ELITE_HET	HET	?
`0x0010`	ELITE_WARP	Warp	?
`0x0020`	ELITE_TELEPORT	Teleport	?
`0x0040`	ELITE_TRACTOR_BEAM	Tractor	Can lock player ships in, preventing them from escaping
`0x0080`	ELITE_DRONE_LAUNCHER	Drones	Can launch drones
`0x0100`	ELITE_ANTI_MINE_BEAMS	Anti-mines	?
`0x0200`	ELITE_ANTI_TORP_BEAMS	Anti-torp	?
`0x0400`	ELITE_ANTI_SHIELD	Shield-drain	Can drain the energy of player ship shields
`0x0800`	ELITE_?	ShldVamp	Can steal energy from player ship shields (unconfirmed)

Game Type

	< v2.1	≥ v2.1
`0x00`	siege	siege
`0x01`	single front	single front
`0x02`	double front	double front
`0x03`	unused	deep strike
`0x04`	unused	peacetime
`0x05`	unused	border war

Main Screen View

`0x00`	Forward
`0x01`	Port
`0x02`	Starboard
`0x03`	Aft
`0x04`	Tactical
`0x05`	Long Range
`0x06`	Status

Object Type

	< v2.1.5	≥ v2.1.5
`0x00`	end of ObjectUpdatePacket	end of ObjectUpdatePacket
`0x01`	player ship	player ship
`0x02`	weapons console	weapons console
`0x03`	engineering console	engineering console
`0x04`	NPC ship (enemy or civilian)	player ship upgrades
`0x05`	base	NPC ship (enemy or civilian)
`0x06`	mine	base
`0x07`	anomaly	mine
`0x08`	unused	anomaly
`0x09`	nebula	unused
`0x0a`	torpedo	nebula
`0x0b`	black hole	torpedo
`0x0c`	asteroid	black hole
`0x0d`	generic mesh	asteroid
`0x0e`	creature	generic mesh
`0x0f`	whale	creature
`0x10`	drone	drone

Ordnance Type

	< v2.1.5	≥ v2.1.5
`0x00`	homing missile	homing missile
`0x01`	nuke	nuke
`0x02`	mine	mine
`0x03`	EMP	EMP
`0x04`	unused	plasma shock

Perspective

`0x00`	First Person
`0x01`	Third Person

Ship System

`0x00`	Beams
`0x01`	Torpedoes
`0x02`	Sensors
`0x03`	Maneuvering
`0x04`	Impulse
`0x05`	Warp Drive
`0x06`	Fore Shields
`0x07`	Aft Shields

Targeting Mode

`0x00`	Auto
`0x01`	Manual

Tube Status

`0x00`	Unloaded
`0x01`	Loaded
`0x02`	Loading
`0x03`	Unloading

Upgrades

New as of v2.1.5. Upgrades marked with (*) can be activated by client consoles, meaning they can occur in the ActivateUpgrade packet.

Index	In-game name	Type	Description
`0x00`*	Infusion P-Coils	Engine Boost	5 Minute 10% Impulse and Warp Speed Boost
`0x01`*	Hydrogen Ram	Maneuver Boost	5 Minute 10% Turn Speed Boost
`0x02`*	Tauron Focusers	Weapons Boost	5 Minute 10% Beam and Reload Speed Boost
`0x03`*	Carapaction Coils	Shield Boost	5 Minute 10% Shield Recharge Boost
`0x04`*	Polyphasic Capacitors	Energy Boost	5 Minute 10% Energy Recharge Boost
`0x05`*	Coolant Reserves	Heat Reduction	5 Minute 10% Faster Heat Reduction
`0x06`*	Lateral Array	Scanner Boost	5 Minute Target Scan Triple Speed
`0x07`*	ECM Starpulse	Jammer Boost	5 Minute Enemy Cannot Lock
`0x08`*	Double Agent	Auto-Surrender	Can force one ship to auto surrender
`0x09`	Wartime Production	Prod Boost	10% (min +1) boost to all starting base munitions
`0x0a`	Infusion P-Coils PERM	Engine Refit	Permanent 10% Impulse and Warp Speed Boost
`0x0b`	Protonic Verniers	Maneuver Refit	Permanent 10% Turn Speed Boost
`0x0c`	Tauron Focusers PERM	Weapons Refit	Permanent 10% Reload and Beam Speed
`0x0d`	Regenerative Pau-Grids	Shield Refit	Permanent 10% Shield Recharge Speed
`0x0e`	Veteran DamCon Teams	Faster DamCon	Damcon teams move/repair 10% faster
`0x0f`	Cetrocite Heatsinks	Heatsink Refit	Heat builds 10% slower
`0x10`	Tachyon Scanners	Scanner Refit	Permanent 10% Scan Speed Boost
`0x11`	Gridscan Overload	Sensor Refit	Permanent 10% Range Booster
`0x12`	Override Authorization	Improved Prod	All bases produce 10% faster
`0x13`	Resupply Imperatives	Mission Enhance	10% More missions
`0x14`	Patrol Group	Allied Combat	Additional TSN Escort Ship in-sector
`0x15`	Fast Supply	Allied Supply	Additional TSN Cargo Ship in-sector
`0x16`	Vanguard Refit	Improved Console	Perm 10% Boost to Impulse, Warp, and Turn Speed
`0x17`	Vanguard Refit	Improved Console	Perm 10% Boost to Beam, Shield and Reload Speeds
`0x18`	Vanguard Refit	Improved Console	Perm 10% Boost to Scan speed and Sensor Range
`0x19`	Vanguard Refit	Improved Console	Perm 10% Boost to Station production
`0x1a`	Vanguard Refit	Improved Console	Perm 10% Boost to all Engineering Systems
`0x1b`	Vanguard Refit	Systems Overhaul	Permanent 10% Boost to all Ship Systems

Game world upgrades

New as of v2.1.5.

Index	Internal name	Known names
`0x00`	ITEMTYPE_ENERGY	Anomaly / HiDens Power Cell
`0x01`	ITEMTYPE_RESTORE_DAMCON	Vigoranium Nodule
`0x02`	ITEMTYPE_HEAT_BUFF	Cetrocite Crystal
`0x03`	ITEMTYPE_SCAN_BUFF	Lateral Array
`0x04`	ITEMTYPE_WEAP_BUFF	Tauron Focusers
`0x05`	ITEMTYPE_SPEED_BUFF	Infusion P-Coils
`0x06`	ITEMTYPE_SHIELD_BUFF	Carapaction Coils
`0x07`	ITEMTYPE_COMM_BUFF	Secret code case / Double agent

Packet Structure

Artemis packets have two parts: the preamble and the payload.

Preamble

The preamble consists of metadata that describes what kind packet it is and how long it is. The information in the preamble is needed in order to interpret the payload. The preamble consists of the following parts:

Header (int)

The first four bytes constitute a header which identifies the packet as an Artemis packet. This value should always be 0xdeadbeef.

Packet length (int)

Gives the total length of the packet in bytes, including both the preamble and the payload.

Origin (int)

A connection type enumeration value indicating whether the packet originates from the server or the client.

Padding (int)

This value is always 0x00.

Remaining bytes (int)

The number of bytes following this field in the packet. This is the length of the packet type field (4) plus the length of the payload, or the length of the entire packet minus 20.

Packet type (int)

This value identifies the type of this packet. Refer to the packet types table to find the values that correspond to the various packet types. Note that many packets also have a subtype value; for those packets, the subtype will be the first value transmitted in the payload.

Payload

The remaining bytes in the packet after the preamble constitute the payload. Its format will vary depending on the packet type. Refer to the next section to see what packet types exist and the formats of their payloads.

Packet Types

The table below lists the known packet types. The type names are derived from the class names for the packets in ArtClientLib.

Name	Origin	Type	Subtype(s)