artemis-nerds / protocol-docs

Unofficial documentation for the Artemis network and file protocols, written by the Artemis community
https://artemis-nerds.github.io/protocol-docs/
MIT License
8 stars 5 forks source link

Consider renaming the priority property of CommsIncomingPacket #10

Closed rjwut closed 9 years ago

rjwut commented 9 years ago

(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.

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?

UserMcUser commented 9 years ago

If the issue is that "priority" is too loaded of a word, then "channel" or "level" make as much sense as anything.

I also find it interesting that this value isn't exposed to the scripting interface (AFAICT) where it would be quite useful. That makes me curious as to what the value is intended to represent, since the only obvious effect is the message window background color change.

dthaler commented 9 years ago

Currently in Artemis DMX Tools, I expose a separate DMX event per "priority" (or channel, as I'd prefer to call it) and documented a set of things seen on each: 0: transmission from enemy 3: base destroyed 4: base under attack, refusal from neutral ships, docking complete 5: base accepting build orders or docking request 6: friendly ship accepting orders, status response from base, notice of ordnance built 7: mission available from ship or base, mission transfer complete 8: outgoing message such as a request to surrender, message between player ships

There's no clear prioritization among that order. There are some natural interesting channels useful to raise as alerts (e.g., DMX events) such as channel 7. Channel 4 overloads both critical events as well as relatively uninteresting events and so is a bit problematic to use to draw too much attention to but the false positives are often worth dealing with in order to notice the high priority distress call. For example, in my own bridge configuration, I have channel 4 mapped to an audio event to play Uhura's "I'm getting something on the distress channel" audio clip. When playing, we like to complain about those docking guys needing to stay off the distress channel!