artemis-nerds / protocol-docs Goto Github PK

Channel 6 is also used for Comms messages from GMs

v2.3 adds this packet which appears to be formatted as follows:
Series of entries, one per fighter slot, each entry containing:
Int: probably an object ID?
String: name of fighter, e.g. "TSN 71"
String: classname of ship type, e.g. "Fighter XA"
Int: probably refueling time remaining

The series of entries terminates with a trailer of Int 0 where the next Object ID would be

in v2.3 the "GameStartPacket" (0xf754c8fe:0x00) is used as a "destroy object packet" (rather than DestroyObjectPacket). That is, the format is:

Payload
Subtype (int)
Always 0x00.
Object type (int)
Indicates the type of object being destroyed.
Object ID (int)
The ID of the object being destroyed.

The (now mis-named) "GameStartPacket" has been observed destroying most of the object types (0x01, 0x05, 0x06, 0x07, 0x0b, 0x0f, 0x10). Suggest renaming it to DestroyObjectPacket2.

Doc says:

GameStartPacket
Type: 0xf754c8fe:0x00 [from server]
Sent when the simulation starts. This packet appears to have been discontinued as of v2.1.1.

It's back in v2.2.0, but doesn't seem to be related to Game Start, it seems to be:
0xf754c8fe:0x00 Object type (int) Object ID (int)
... and frequently happens right before DestroyObjectPacket, EG this torpedo:

0000000 ef be ad de 24 00 00 00 01 00 00 00 00 00 00 00
0000020 10 00 00 00 fe c8 54 f7 00 00 00 00 0b 00 00 00
0000040 95 06 00 00 ef be ad de 1d 00 00 00 01 00 00 00
0000060 00 00 00 00 09 00 00 00 30 3e 5a cc 0b 95 06 00
0000100 00

Or this drone:
0000000 ef be ad de 24 00 00 00 01 00 00 00 00 00 00 00
0000020 10 00 00 00 fe c8 54 f7 00 00 00 00 10 00 00 00
0000040 98 06 00 00 ef be ad de 1d 00 00 00 01 00 00 00
0000060 00 00 00 00 09 00 00 00 30 3e 5a cc 10 98 06 00
0000100 00

Or this more complicated set of NPC Ships:
0000000 ef be ad de 24 00 00 00 01 00 00 00 00 00 00 00
0000020 10 00 00 00 fe c8 54 f7 00 00 00 00 05 00 00 00
0000040 78 06 00 00 ef be ad de 24 00 00 00 01 00 00 00
0000060 00 00 00 00 10 00 00 00 fe c8 54 f7 00 00 00 00
0000100 05 00 00 00 7a 06 00 00 ef be ad de 1d 00 00 00
0000120 01 00 00 00 00 00 00 00 09 00 00 00 30 3e 5a cc
0000140 05 78 06 00 00 ef be ad de 1d 00 00 00 01 00 00
0000160 00 00 00 00 00 09 00 00 00 30 3e 5a cc 05 7a 06
0000200 00 00

For lack of any more detail, I'm going to call it PreDestroyPacket for the moment. It might be something like "remove from map" before we destroy it?

We are currently unsure of how the generic mesh packet works, specially regarding 8-byte-long fields and the bitmask for the mesh/texture filenames.

Captures of that packet will be appreciated.

Packet 0x4c821d3c subtype 0x17 DOES exist. Client to server (I'm going to GUESS Engineering, maybe Science console), no payload (apart from the type+subtype).
Have absolutely NO IDEA how to recreate it. Will hack around :-(

Write docs about the composite data types used by Artemis (as implemented by node-asbs-lib):

• Static structs
• Bitmapped structs
• Static arrays
• Byte-bound arrays

I've been reading the docs, and it strikes me that ObjectUpdatePacket is very unusual.

It's by far the largest and most complicated packet type, since it essentially covers 90% of what the server sends to clients. Like all other multiplexed packet types, it starts with a (depending on version) byte/int subtype code. The following data is then 100% dependent on the subtype.

I propose that ObjectUpdatePacket be split up into individual update packets, so UpdateAnomalyPacket, UpdateBasePacket, etc. (prefixed with Updated, so they are alphabetically close).

I'm not sure if the "Object Properties" should be merged into the "Packet Types" section (I think it would make sense), but at least I think the individual update packet types should be documented.

Would you accept a pull request for this?

When implementing or debugging the protocol, it's much more useful to be able to look up packet types by the supertype and subtype, rather than the name (which can even change in the future).

It makes perfect sense for the packet description list to be alphabetically sorted, but I think the index should be numerical - or, a second index should be included, which is numerically sorted. Since it's js-generated to begin with, this should be trivial to implement.

Will you accept a PR for this?

P.S: Can I join your group? ;-) I can't apply for membership, that function seems to be disabled.

I have a hypothesis that seems to be valid for now. I'm wondering if you guys have any comments?

The _unknown_1 field on VersionPacket seems to correspond to a count of how many server packets have been sent since the start of the server. At least, somewhat.

I've tried starting the server, and I get this exchange:

S: Welcome
S: Version (468)
S: ConsoleStatus
S: AllShipSettings

S: Welcome
S: Version (472)
S: ConsoleStatus
S: AllShipSettings

...

It seems to get incremented by 1, for every server message sent. This would make a lot of sense, and in that case is functions as a monotonic tick counter, to at least give a qualified guess as to whether a reconnect hits the same server instance, or a new one. Potentially this could be used to either re-use or discard the client-state view of the game world.

Comments?

When the client sends ReadyPacket2, the server seems to respond with a fully-populated EngGridUpdatePacket (AKA damConInfo in some libraries), enough to display the mini ship outline thingy with ALL the red damage dots on it, as seen in a corner of Main/Helm/Weapons/Data screens.

The "Unknown (byte) Values of 0 and 1 have been observed" first field in EngGridUpdatePacket then seems to correspond to 1="This is a fully-populated one you asked for with ReadyPacket2" vs 0="This is an unsolicited partial update" (0). The partial updates only indicate NEW/REPAIRED damage, MOVING damcon teams, etc.

Suggest ReadyPacket2 should then probably be renamed to "RequestFullEngGridUpdatePacket", or preferably something more catchy ;-)

The Perspective Packet (0xf754c8fe : 0x12) is now apparently always the same - I see this <ef be ad de 1c 00 00 00 01 00 00 00 00 00 00 00 08 00 00 00 fe c8 54 f7 12 00 00 00> every time I click the button.

The reason is that Artemis now just toggles the perspective between 1st and 3rd rather than explicitly setting it. Not sure when this changed, but definitely after 2.1.5.

Currently the doc says:
"Unknown (bit 5.7, byte)
-1 has been observed."

However, from all my observations with v2.1.1, v2.2, and v2.3, the field is 4 bytes long not 1 byte long.

I let my proxy run for a while to gather data, and test the parsing. I discovered 0x0351a5ac :0x07, which seems to be sent quite a lot in 2.4.0, in the right circumstances. Unfortunately, I wasn't looking at the game while this happened, so I don't know what the "right circumstances" are..

Below is a quoted sample of the attached file. They all seem to be the same length.

aca55103070000000000003fe903000000000000a50e43470000000088f342470000000000000000000000000000803f
aca55103070000000000003fe903000000000000640e4347000000004df442470000000000000000000000000000803f
aca55103070000000000003fe903000000000000280e434700000000fef442470000000000000000000000000000803f
aca55103070000000000003fe903000000000000e10d434700000000cef542470000000000000000000000000000803f
aca55103070000000000003fe9030000000000008c0d434700000000b6f642470000000000000000000000000000803f
aca55103070000000000003fe903000000000000090d43470000000036f842470000000000000000000000000000803f
aca55103070000000000003fe9030000000000009e0c4347000000006ff942470000000000000000000000000000803f
aca55103070000000000003fe903000000000000270c434700000000c8fa42470000000000000000000000000000803f
aca55103070000000000003fe903000000000000a50b43470000000042fc42470000000000000000000000000000803f
aca55103070000000000003fe903000000000000180b434700000000dcfd42470000000000000000000000000000803f
aca55103070000000000003fe9030000000000007f0a43470000000097ff42470000000000000000000000000000803f
aca55103070000000000003fe903000000000000db09434700000000740143470000000000000000000000000000803f
aca55103070000000000003fe9030000000000004a094347000000009a0343470000000000000000000000000000803f
aca55103070000000000003fe9030000000000008e08434700000000b90543470000000000000000000000000000803f
aca55103070000000000003fe903000000000000d007434700000000de0743470000000000000000000000000000803f
aca55103070000000000003fe9030000000000001107434700000000070a43470000000000000000000000000000803f
aca55103070000000000003fe9030000000000005206434700000000340c43470000000000000000000000000000803f
aca55103070000000000003fe9030000000000009b054347000000006f0e43470000000000000000000000000000803f
aca55103070000000000003fe903000000000000da04434700000000a61043470000000000000000000000000000803f
aca55103070000000000003fe9030000000000001a04434700000000e21243470000000000000000000000000000803f
aca55103070000000000003fe9030000000000005903434700000000231543470000000000000000000000000000803f
aca55103070000000000003fe903000000000000b202434700000000821743470000000000000000000000000000803f
aca55103070000000000003fe903000000000000f201434700000000cc1943470000000000000000000000000000803f
aca55103070000000000003fe90300000000000032014347000000001b1c43470000000000000000000000000000803f

Also, I think I have figured the powerup packet layout out. I'll write more when I know more :)

Smells like a bug in the server / protocol, but worth noting, perhaps in https://artemis-nerds.github.io/protocol-docs/#string-format
The UTF16 strings can contain NULLs (0x0000) in the middle of the strings. When playing 'border war' I get a CommsIncoming message, priority 0, length 0x0d (=13), (16-bit) chars "TSNCOM\0eeeee\0". The 209-char message is "This is an official WAR WARNING! Enemy fleets are massing in the next sector. Expect an invasion soon.\0eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\0". I had previously naively been hoping I could skip the length int and start reading 16-bit chars until I hit 0x0000. It turns out this is USUALLY but not ALWAYS true :-(

Since the coordinate system seems to be rather confusing to folks who are unfamiliar with it, I propose that there be a section that explains it. Here's a quick brain dump:

POV of Artemis at first launch (oriented at a bearing of 0 degrees):

• X axis increases toward starboard ("right")
• Y axis increases toward the ventral side of the ship ("down")
• Z axis increases toward aft ("back")

Top-down view (as seen on most consoles):

• X axis increases toward the right (90 degrees or "east")
• Y axis increases "into" the screen
• Z axis increases toward the bottom (180 degrees or "south")

I believe the origin (0, 0, 0) is at the "upper northwestern" corner of the game world. The dimensions of the game world where Artemis is permitted to go are 100,000 × ??? × 100,000. (Not sure how "tall" it is off the top of my head.) However, certain objects (nebulae, for example) may lie outside these bounds.

I have seen a grand total of THREE packets 0x0351a5ac:0x06, client to server, I think from a Game Master
Payload seems to contain 3 floats which LOOK like they might be x/y/z coords?

0000000 ef be ad de 28 00 00 00 02 00 00 00 00 00 00 00
0000020 14 00 00 00 ac a5 51 03 06 00 00 00 00 00 7a 47
0000040 00 00 00 00 55 b9 69 47

0000000 ef be ad de 28 00 00 00 02 00 00 00 00 00 00 00
0000020 14 00 00 00 ac a5 51 03 06 00 00 00 00 0c 78 47
0000040 00 00 00 00 ab 62 32 47

0000000 ef be ad de 28 00 00 00 02 00 00 00 00 00 00 00
0000020 14 00 00 00 ac a5 51 03 06 00 00 00 00 0c 78 47
0000040 00 00 00 00 ab 62 32 47

Might be Game Master clicking on empty bits of the map? Will try to recreate

I propose that we list every observed packet type in the protocol docs, with as much information as we have.

At the same time, these subtypes should be clearly labeled as being wholly or partially unknown.

Packets with completely unknown function, will be prefixed with "_UNKNOWN" or similar prefix, to clearly distinguish them from the known packets.

Will you accept a PR for this?

I think that it would be beneficial to broaden the topic of the docs to cover other data sources such as vesselData.xml and .snt files, rather than just the protocol. I've already done some work on this which I can commit when I have time if we want to do this.

Additionally, I think a standardized property nameset (e.g. names of entities, properties, and property behaviour, as well as how packets/packet properties match to entities and entity properties) is required that works across all of these formats, which can be used by all Artemis libraries, guaranteeing compatability. This would also aid documenting these libraries, as the majority of documentation concering game-related I/O would already be available.

http://artemis-nerds.github.io/protocol-docs/#game-events under Player Ship says
"Scanning ID (bit 5.3, float)

A value from 0.0 to 1.0 inclusive indicating the current progress of the active science scan."

"Scanning ID" should say "Scanning progress"

I have packet captures with a bunch of undocumented packet 0xf754c8fe subtype 0x13 (int usuallySeven, int objID). Seems to happen immediately before DestroyObject(Mine, objID) or DestroyObject(Torpedo, objID). I'm not sure what "usuallySeven" is except that it's usually 0x07. Does NOT seem to correspond to ObjectType 'cos it's 0x07 for both Mines or Torpedos. Will see if I can recreate sometime. In the meantime I am calling it UnknownMaybeDetonatePacket. Anyone have better details?
[moving to separate issue]

As far as I can tell, it's not specifically stated anywhere?

Are we talking CC, GPLv2/3, BSD, PD?

http://artemis-nerds.github.io/protocol-docs/#consolestatuspacket says
"Ship number (int)
The number of the ship whose consoles are being described. This value is one-based, so by default the ship identified by 0x01 is named Artemis."

In Artemis v2.3, the value is zero-based, so by default the ship identified by 0x00 is named Artemis.

Guys, I need your help for an idea. Right now, we don't have a test suite for the protocol, nor do we have a complete and full understanding of every field. In fact, I suspect a small number of the rarely used field descriptions to be wrong in the current docs.

I've figured out a good way to solve several of these problems at once. If we had some raw data logs (I have some for my own use already), then first of all, we could test that our programs could parse all this data as is. But more interestingly, we could make a program that describes the range of values for each field. So we could see the min/max values (ints and floats) observed values (strings) converted values (enums) and so on. This would most certainly tell us almost straight away if we have any parsing problems.. and it would make it much easier to test a hypothesis against an existing corpus.

I've already implemented this for a few specific cases. However, I could really use some help in collecting more bulk data.

What I would really like, if you have it available, is a text file with a hex dumped packet per line, without the framing (deadbeef prefix and header)

Thoughts? :)

I have seen a few (very few) ClimbDivePacket Type: 0x4c821d3c:0x1b but Direction (int) is 5, 6, or 8, NOT +1 / -1. Will try to recreate, unless anyone has better details?
[moving to an issue of its own]

0x0351a5ac:0x04 is listed in the doc as both "EngSetEnergyPacket" and "HelmJumpPacket".
HelmJumpPacket seems to actually be subtype 0x05 (like the table at the top of that section, in fact)

From the docs:

  const int ELITE_ANTI_SHIELD          = 1024

Artemis v2.3 updates the Player Ship object as follows:

• Bit field increased from 5 bytes to 6 bytes
• Unknown (bit 5.8, byte): 0 has been observed
• Unknown (bit 6.1, int?): [ 71, 0, 49, 0 ] has been observed. This happens to be "G1" without null termination, but that may not be relevant.
  Bits 6.2 through 6.8 appear to be unused.

ObjectUpdate packets (0x80803df9), some further details...

I'm just about certain the length of the bitfield, in bytes, is (num_fields+1)/8 rounded up.
If there are 3 fields, the bitfield will take 1 byte, values 0x01 to 0x07
If there are 7 fields, the bitfield will take 1 bytes, values 0x01 to 0x7f
If there are 8 fields, the bitfield will take TWO bytes. The first byte 0x01 to 0xff, the second byte always 0.
Similarly if there are 24 fields (EngConsole) the "full update" will have a bitfield of 0xff 0xff 0xff 0x00. The "Unknown (byte) This value always seems to be 0x00" is a seemingly-superflous extra byte in the bitfield, you'll find the same on any other object which has a multiple of 8 fields.

The Object lists within the ObjectUpdate packet always seem to be terminated by not only "the object type byte is 0x00", but by "0x00 0x00 0x00 0x00". 4 zero-bytes. Even though you'd half-expect a 1-byte object type and a 4-byte objectID. Yeah. :-D

I've further studied how objects have changed between versions...
PlayerShip (type 0x00)...
[ Hang on, why is your Velocity apparently from pi to negative pi / heading of 0=north etc? Crossed wires? ]
I've had an opportunity to play with 2.6.204-beta, and it adds (after "Unknown (bit 6.3, 4 bytes, new as of v2.4.0)") 2 fields, both bytes, corresponding to the setting for the Biosignal Frequency (0-4) and Power (0-10) which are part of the new the tag ordnance functionality.

Weapons Console (type 0x02), 2.6.204-beta now has 8 Ordnance counts corresponding to Homing, Nuke, Mine, EMP, PShock, Beacon, Probe, Tag (all bytes, and yes, the Ordnance Type enumeration needs updating to match). There is no "Unknown (bit 1.6, byte)", it became Beacons I guess. The Load Times, Statuses, Types, all move up. 8+6+6+6 = 26 bits in the bitfield (4 bytes)

Engineering console (0x03), Pretty sure that's a 24-bit field taking 4 bytes, so the "Unknown (byte) [...] always seems to be 0x00 [...] might be a reserved bit field byte for future engineering settings" was kinda right, it's bit field, ffffff00 when fully-populated.

NPC Ship (0x05) adds one new unknown 4-byte float after the "Beam frequency resistance (bit 6.3 - 6.7, float array)". You'll notice this would correspond to bit 6.8, which (according to the rules above) does indeed add another "always 0" byte to the bitfield. It's 48 bits, yet needs 7 bytes, see? "full object" bit mask is ffffffffffff00.

Anomaly (0x08) Has had a 6-bit (1-byte) field since 2.3.0 (yes I do mean 2.3.0). You already have X/Y/Z (floats) and Upgrade(int). bits 1.5 and 1.6 correspond to two 4-byte fields, unknown purpose, not even sure if they're integers or floats, I'm trying to work out if I've ever seen anything that's not 0x00000000

Nebula (0x0a) I see no evidence for "Unused? (bit 1.7, int) Unused? (bit 1.8, int)" at all, in any of my captures.

Torpedo (0x0b) Starts with X,Y,Z. "Unknown (byte)" is because an 8-bit field takes 2 bytes as above. There are no corresponding bits 2.1 to 2.8, the max value of this 8-bit field is "0xff 0x00".

Creature (0x0f) After Creature type (int32 enum) come the unknown fields. I THINK they are int, int, float, float, float, float, but I'll admit I haven't dug deeply. More importantly, 2.3.0+ added 4 more 4-byte fields which I guess we can call "Unknown (bit 2.7, 4 bytes, v2.3.0+)" up to "(bit 3.2, 4 bytes, v2.3.0+)", and yes that increases the bitfield to 3 bytes

Drone (0x10) Is, and has "always been", on any version I've ever logged (2.2.0 to 2,6,204 incl), an 8-bit field (which according to the above rules takes 2 bytes, a fully-populated bitfield being 0xff 0x00). I see no evidence for the "Unknown (bit 2.1, float?, v2.1.5+)", but confess I don't seem to have v2.1.5 itself. That and the "Unused? (bits 2.2-2.8)" seem to be explained by the 8-bit field taking 2 bytes. Wish I could help with the number of Unknowns that still exist in this object :-(

To clarify bit counts in Version 2.6.204-beta:

• ObjType 0x01 45-bit field (6 bytes) PlayerShip
• ObjType 0x02 26-bit field (4 bytes) WeaponsConsole
• ObjType 0x03 24-bit field (4 bytes) EngConsole
• ObjType 0x04 84-bit field (11 bytes) Upgrades - there's no new upgrades? :-/
• ObjType 0x05 48-bit field (7 bytes) NPCShip
• ObjType 0x06 14-bit field (2 bytes) Base
• ObjType 0x07 3-bit field (1 byte) Mine
• ObjType 0x08 6-bit field (1 byte) Anomaly
• ObjType 0x0a 6-bit field (1 byte) Nebula
• ObjType 0x0b 8-bit field (2 bytes) Torpedo
• ObjType 0x0c 3-bit field (1 byte) BlackHole
• ObjType 0x0d 3-bit field (1 byte) Asteroid
• ObjType 0x0f 16-bit field (3 bytes) Creature
• ObjType 0x10 8-bit field (2 bytes) Drone
  Not tested Meshes.

FighterLaunchPacket
TYPE: 0x4c821d3c : 0x1d [FROM CLIENT]
Notifies the server that a fighter is being launched. In response, the server will send a FighterLaunchedPacket.
Payload
Subtype (int)
Always 0x1d.
Object ID (int)
The fighter's object ID that appeared in a FighterBayStatusPacket.

FighterLaunchedPacket
TYPE: 0xf754c8fe : 0x17 [FROM SERVER]
Notifies the client that a fighter was just launched.
Payload
Subtype (int)
Always 0x17.
Object ID (int)
The fighter's object ID that appeared in a FighterBayStatusPacket.

I have seen 18 instances in 2 games of undocumented packet 0x4c821d3c subtype 0x05, payload 4 bytes, all zeroes, No idea if that's a 0 int, float, boolean, or enumerated something. :-(
Also half a dozen packet 0x4c821d3c subtype 0x06, payload 4 bytes all zeroes too. :-(
Every example I have seen was sent from Helm Client to Server. Will try to recreate, unless anyone has better details?
[moving to an issue of its own]

According to the forums, 2.2.0 is out. This means:

• New monsters
  • Investigate whether new packet, or reuses the "ZZ" monster packet
  • Whales and monsters are combined into a new creature object type. Wrecks are also considered creatures. Fields documented in the 5 July 2015 comment below.
  • Investigate whether the space whale packet has changed to accommodate non-hostile monsters
  • See above
  • Document the NSECT monster
  • Same as all other creatures
• Anomalies are now "pickups"
  • Investigate new fields
  • Documented in 5 July 2015 comment below
• Working upgrade system (apparently some consoles can "activate" the pickups/upgrades)
  • Investigate now the upgrades packet works
  • Investigate how to trigger abilities from clients
  • Check whether the popup when a pickup is picked up comes from the upgrades packets, or from a separate (and already known) game server message.
• One new type of torpedo (plasma shock)
  • One more enum
  • Changes in the structure of the WeaponsUpdate packet

V2.5.1 introduced 0x06 = "Infestation" into Game Type ENUM

So I'm investigating the protocol changes for supporting the new GM buttons functionality in Artemis 2.4. I'm presuming that the following new packets must exist:

• (server > client) Creating a button to display on the GM console (set_gm_button)
• (server > client) Removing a button that was on the GM's console (clear_gm_button)
• (client > server) GM console button clicked (if_gm_button)

I've started by running the script from this thread and capturing all the unknown packets received when the game starts. This lead to the discovery of packet type 0x26faacb9, which I'm presume is the one that corresponds to the new button commands, or at least set_gm_button. I'm digging into the payloads now, but I thought I'd share what I captured below. For brevity, I'm only including the payloads and not the preambles, but they're all 0x26faacb9 packets. Each line is one packet.

64

011c000000430072006500610074006500200045006e0065006d0079002f0053006d0061006c006c0020005300740061006e0064006100720064000000

011d000000430072006500610074006500200045006e0065006d0079002f004d0065006400690075006d0020005300740061006e0064006100720064000000

011c000000430072006500610074006500200045006e0065006d0079002f004c00610072006700650020005300740061006e0064006100720064000000

011b000000430072006500610074006500200045006e0065006d0079002f0053006d0061006c006c00200053006b0061007200610061006e000000

011c000000430072006500610074006500200045006e0065006d0079002f004d0065006400690075006d00200053006b0061007200610061006e000000

011b000000430072006500610074006500200045006e0065006d0079002f004c006100720067006500200053006b0061007200610061006e000000

0115000000440065006c006500740065005c00530065006c0065006300740065006400200073006800690070000000

0116000000440065006c006500740065005c006e006f006e002d007300680069007000730020006e006500610072000000

0122000000430072006500610074006500200045006e0065006d0079002f004500780074007200610073002f004d0069006e0065006600690065006c00640020006100720063000000

011c000000430072006500610074006500200045006e0065006d0079002f004500780074007200610073002f004e006500620075006c00610073000000

011e000000430072006500610074006500200045006e0065006d0079002f004500780074007200610073002f00410073007400650072006f006900640073000000

011d00000043007200650061007400650020005400720061006e00730070006f00720074002f0067006f0069006e00670020006e006f007200740068000000

011c00000043007200650061007400650020005400720061006e00730070006f00720074002f0067006f0069006e006700200065006100730074000000

012200000043007200650061007400650020005400720061006e00730070006f00720074002f0061006c00690065006e00200067006f0069006e006700200065006100730074000000

0213000000540065006c00650070006f00720074002000530065006c0065006300740069006f006e000000c80000001e0000001e000000c8000000

011b00000045006e0065006d007900200042007200610069006e002f00630068006100730065002000730074006100740069006f006e0073000000

011900000045006e0065006d007900200042007200610069006e002f0063006800610073006500200070006c0061007900650072000000

631700000054006800720065006500200042006100730065007300000065006500650065006500650065006500650065000000c50200005400680069007300200047004d0020006d0069007300730069006f006e0020007300630072006900700074002000690073002000640065007300690067006e0065006400200074006f00200070006c0061006300650020006f006e006500200070006c00610079006500720020007300680069007000200061006e00640020003300200062006100730065007300200069006e0020006100200073006500630074006f0072002c00200061006e00640020007400680065006e0020006c00650074002000740068006500200047004d00200061006400640020006300650072007400610069006e00200065006e0065006d00690065007300200061006e00640020007400650072007200610069006e002e005e005e002000520065006d0065006d006200650072002c0020006c006500660074002d0063006c00690063006b00200074006f002000730065006c00650063007400200061002000730068006900700020006f0072002000730074006100740069006f006e002c002000720069006700680074002d0063006c00690063006b00200074006f002000730065006c006500630074002000610020006c006f0063006100740069006f006e00200069006e002000730070006100630065002e0020006d0061006e00790020006f006600200074006800650020006d0065006e007500200063006f006d006d0061006e006400730020007200650071007500690072006500200079006f007500200074006f002000730065006c00650063007400200061006e0020006f0062006a0065006300740020006f00720020006c006f0063006100740069006f006e002000660069007200730074002e005e005e00200054006800690073002000730063007200690070007400200077006100730020007700720069007400740065006e002000620079002000540068006f006d00200052006f00620065007200740073006f006e002e000000650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065006500650065000000

From a 2.6.0 game, which did have at least one Jump-Ship in it (specifically, a Warp Dreadnought and a Jump Ximni Missile Cruiser):
fec854f70e00000000000000e0d8fc3d # 2.6.0 payload
fec854f70e0000000000000064a2da3e # 2.6.0 payload
fec854f70e0000000000000084451d3f # 2.6.0 payload
fec854f70e00000000000000843f453f # 2.6.0 payload
0xf754c8fe is of course officially "simpleEvent" (#52), not sure what this subtype 0x0e is.

Entity types changed in Artemis v2.1.0 with the introduction of ship upgrades (https://artemis-nerds.github.io/protocol-docs/#enum-object-type) but the packet subtypes for most entities (e.g. https://artemis-nerds.github.io/protocol-docs/#baseupdatepacket) are outdated and need to be fixed and updated.

MainPlayerUpdatePacket says:
"The payload consists of an array of ship entries. Parsing continues in a loop until the end of the packet is reached, or the object type byte is 0x00."

The same is true for EngPlayerUpdatePacket and WeapPlayerUpdatePacket.

Verified the following on 2.4:

1. Bit field is 3 bytes
2. The "creature type" is 32 bits (previously not specified)
3. There are 10 unknown 4-byte fields after creature_type_id. I think they make most sense as u32 for now.

I'll see if I can find the time to make some PRs for this (and the other recent issues)

Going with @IvanSanchez's idea, I was able to build an intelligent brute-forcing script to search strings and substrings for matching hashes. The results can be seen below. These matches are quite obviously not random :)

0351a5ac: valueFloat
077e9f3c: shipSystemSync
19c6e2d4: clientConsoles
26faacb9: gmButton
3de66711: startGame
4c821d3c: valueInt
574c4c4b: commsMessage
69cc01d9: valueFourInts
6aadc57f: controlMessage
6d04b3da: plainTextGreeting
80803df9: objectBitStream
809305a7: gmText
9ad1f23b: carrierRecord
ae88e058: incomingMessage
b83fd2c4: attack
c2bee72e: beamRequest
cc5a3e30: objectDelete
d672c35f: commText
e548e74a: connected
ee665279: objectText
f5821226: heartbeat
f754c8fe: simpleEvent

To me, this explains quite a few things! For example, why are the major types sometimes related in terms of function, and sometimes not at all? For example, 0x0351a5ac covers both Helm, Eng and Game Master. Now we know it's simply because of convenience, since 0x0351a5ac is a packet with a single float. This also tells us that we can always expect 0x0351a5ac to have a single float, unless the name is incredibly misleading ;-)

My personal favorite: Packet f5821226, which we suspected to be a heartbeat packet, is now known for sure to be a heartbeat packet. Also, packets like "valueInt" and "valueFourInts" tell us quite a great deal about the expected format, and how unlikely it is to change in the future.

To be honest, I like the existing names better than these ones, but it's certainly very interesting to have found the source of the packet IDs :)

(Split from #9)

The priority property of CommsIncomingPacket is currently described as follows:

Priority (int)

Values appear to range from 0x00 (high priority) to 0x08 (low priority). In the stock client, this affects the message's background color.

@dthaler noted that priority does not seem to accurately reflect this property's purpose. Below are some example comms messages next to the value for this property.

• 0x00: Enemy taunt
• 0x04: Base is under attack
• 0x04: Docking complete
• 0x05: Ready for docking
• 0x07: Transfer complete

Of the messages listed, a base being under attack is clearly the most important one, but under the current definition it is considered equal priority to "Docking complete." Enemy taunts are the least important messages, but they are given the highest priority here.

The only clear correlation between this value and anything we see in the stock client that we've determined is the message's background color. The closer to 0x00 the value gets, the more red the message becomes. With red traditionally being considered a color denoting urgency in user interfaces, it was natural for the original author of ArtClientLib (from whence this documentation originated) to presume that this value indicated priority.

@dthaler suggested that this value could be called "channel" rather than "priority," although this also has issues, as that would still put "Base is under attack" in the same channel as "Docking complete" which are very different types of messages. Sure, both messages come from bases, but so does "Ready for docking," which you would think would belong to the same channel as "Docking complete."

@UserMcUser suggested that this property should simply be called "background color." I have some issues with that: 1) That is a UI-specific term, so I'd rather not use it unless no other meaning can be determined. 2) If the intention of this property really was "background color," why would its value not simply be an actual ARGB color value? It seems that would provide greater flexibility. The fact that it isn't indicates to me that a different meaning was intended than simply color.

I think what we need to ask in order to be able to determine what the best course of action here is to try to answer these questions: What meaning did Thom intend to convey with the colors he used in the comms console? If it is priority, why do the contents of the messages not seem to correlate?

[moving to its own issue]

Player Ship Upgrades object appears to be...
Bit field (11 bytes)
UpgradeInUse (bits 1.1-4.4 = 28 byte array)
UpgradeQuantity? (bits 4.5-7.8 = 28 byte array)
... perhaps in the order that you've already hacked at, EG bit 5.3=LateralArray?
UpgradeCountdown (bits 8.1-11.4 = 28 short array)

I quite frequently see sequences like:
ObjUpgrades(id=1025, .... LateralArray5_3=3 ...)
ObjUpgrades(id=1025,Unknown1_7=1,Unknown8_7=299)
... Unknown8_7 counts down 299 .. 0
ObjUpgrades(1025,Unknown1_7=0,LateralArray5_3=2),

Or a similar sequence with...
...CetrociteCrystal5_1=1...
Unknown16=1,Unknown8_6=299
Unknown8_6=298 ... and down to...
Unknown86=0
Unknown16=0,CetrociteCrystal5_1=>0

Same pattern with Unknown21 vs SecretCodeCase5_5 vs Unknown91
We have 28 bytes for upgrades "in use", 28 bytes for upgrade "quantities", 28 shorts for upgrade countdowns whilst in use, total 84 bits of the 11-byte bitfield.

Running "strings Artemis.exe" and looking for "likely" strings, I believe the complete list of upgrades, in order, is:

http://artemis-nerds.github.io/protocol-docs/#enum-console-type needs to be updated for v2.3.
Fighter was inserted at value 6 and the rest shifted down (Data=7, Observer=8, Captain's map-9, Game master=10)

As pointed out in artemis-nerds/node-asbs-lib#15, the generic mesh packet specifies a 'long' type for bit 1.6, but this type isn't in the data types in the documentation.

Seeing as property is an unknown in the generic mesh packet, and is the only instance of 'long' anywhere in the docs, could it be a mistake? Should we add it as a type?

I have created a pull request with the (simple) change if we decide we want it: #6

Partially in response to #9 (comment), where @dthaler wrote

Just in case you're keeping track of Artemis network libraries in other languages, I have one in C++ that is used by Artemis DMX Tools. This documentation project has been extremely valuable.

Both @NoseyNick and @dthaler have said that they are working on Artemis clients, and I think it'd be awesome if we could keep track of a list of libraries made by the community, by-language, with links to where they can be found. So, we need a list of projects, and also need to decide if this list should go in this documentation, or in a separate repository. If in this documentation, it might be worth re-structuring the document a little bit to allow us to add different types of Artemis-related content in the future, rather than just protocol documentation.

http://artemis-nerds.github.io/protocol-docs/#packet-types says
"SciScanPacket client 0x4c821d3c 0x13
SciSelectPacket client 0x4c821d3c 0x10
SciScanPacket client 0x4c821d3c 0x13"

The second occurrence of SciScanPacket should be removed.

So, it turns out subtype 0x17 is actually like SetShipSettings, but for versions greater than 2.1.1. I have confirmed that it's valid for 2.4.0:

[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 12, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 11, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 10, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 9, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 8, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 7, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)
[*] Read client frame: Client::SetShipSettings_v240 { ship: Ship { drive_type: Warp, ship_type: 6, accent_color: 0, _unknown_1: 1, name: "Artemis\u{0}" } } (0 bytes)

This happens when the helm player presses "Configure ship" while in the station selector.

However, issue #14 has some (confirmed) sightings of this packet with just 0x00000000 as the payload.

I don't have a good explanation for the weird special case, but this explains all non-zero sightings of this packet.

I'd like to see the documentation written in markdown - right now it is messy to edit tables.

This would require moving index.html to index.md and start cleaning out the tables and lists that need attention.

Could use a better description of "Accent Color". Is it RGB? I think there is some sort of HSV thing going on here?