making the comments in ObjectAttach less Infantry-centric

common/src/main/scala/net/psforever/packet/game/ObjectAttachMessage.scala

@@ -6,39 +6,39 @@ import scodec.Codec
 import scodec.codecs._
 
 /**
-  * Change the location of an item within the game's inventory system.<br>
+  * Change the location of an object - the child - within the inventory system for another object - the parent.
+  * (Where the child object was before it was moved is not specified or important.)<br>
   * <br>
-  * The data portion of this packet defines a player, an item, and a destination.
-  * After the packet is received by the client, the item will be guaranteed to be within the player's inventory in the codified location.
-  * The "inventory" in this case includes both the player's literal grid inventory and their available equipment slots.
-  * Where the item was before it was moved is not specified.<br>
+  * The data portion of this packet defines a parent object, a child object to-be, and a destination.
+  * After the packet is delivered, the child object will be expected to be a possession of the parent object in the codified inventory location.
+  * The "inventory" of the parent object is a generalization of that object's containment or installation positions.
+  * The inventory is has different referral words for these positions depending on the target parent;
+  * but, it is generally "seats" or "mounting points" for vehicles;
+  * and, it is generally "holsters" or "grid inventory positions" for players.
+  * For players, "holsters" and "grid inventory positions" have 1:1 numerical mapping.
+  * For vehicles, however, "seats" and "mounting points" are not consistently mapped and are much more context sensitive.
+  * For that reason, this installation position will hitherto be referred to as a generic "slot."<br>
   * <br>
-  * This packet is a complementary packet that simulates a lazy TCP-like approach to coordinating item manipulation.
-  * In some cases, the client will (appear to) proceed with what it intended to do without waiting for the server to confirm.
-  * For example, grabbing an item from an inventory position will generate a `MoveItemMessage` that defines "the player's cursor" as a destination.
-  * The client will "attach to the player's cursor" without waiting for an `ObjectAttachMessage` from the server which echoes the destination.
-  * The change is observable.
-  * Inversely, the client is blocked from detaching the item from "the player's cursor" and putting it back into the inventory on its own.
-  * It waits until it receives an `ObjectAttachMessage` in confirmation.<br>
+  * Both the client and the server can send and receive this packet.
+  * Its interplay with other packets simulate a lazy TCP-like approach to object manipulation.
+  * If the client sends this packet, it will generally have already done what it was going to do.
+  * If the server sends this packet, the client will have been waiting on confirmation of an action it previously requested.<br>
   * <br>
-  *  Destination codes:<br>
-  * `0x80` - pistol slot 1<br>
-  * `0x81` - pistol slot 2<br>
-  * `0x82` - rifle slot 1<br>
-  * `0x83` - rifle slot 2<br>
-  * `0x84` - melee/knife slot<br>
-  * `0x85` - mystery slot<br>
-  * `0x86` - grid inventory (1,1)<br>
-  * `0x00FA` is a special dest/extra code that "attaches the item to the player's cursor"
-  * @param player_guid the player
-  * @param item_guid the item
-  * @param slot a codified location within an inventory, and overlapping the player's holsters if need be;
-  *             8u (0 - 127 or `0x80 - 0xFF`) or
-  *             16u (128 - 32767 or `0x0080 - 0x7FFF`)
-  * @see `MoveItemMessage`, `objectcreate\ObjectClass.SLOT_BLOCKER`
+  * Player inventory slots:<br>
+  * `0x80` - 0 - pistol holster 1<br>
+  * `0x81` - 1 - pistol holster 2<br>
+  * `0x82` - 2 - rifle holster 1<br>
+  * `0x83` - 3 - rifle holster 2<br>
+  * `0x84` - 4 - knife holster<br>
+  * `0x86` - 6 - grid (1,1)<br>
+  * `0x00FA` - 250 - is a special dest/extra code that "attaches the item to the player's cursor"
+  * @param parent_guid the parent object
+  * @param child_guid the child object
+  * @param slot a codified location within the parent object's inventory;
+  *             8u (0 - 127 or `0x80 - 0xFF`) or 16u (128 - 32767 or `0x0080 - 0x7FFF`)
   */
-final case class ObjectAttachMessage(player_guid : PlanetSideGUID,
-                                     item_guid : PlanetSideGUID,
+final case class ObjectAttachMessage(parent_guid : PlanetSideGUID,
+                                     child_guid : PlanetSideGUID,
                                      slot : Int)
   extends PlanetSideGamePacket {
   type Packet = ObjectAttachMessage
@@ -48,8 +48,8 @@ final case class ObjectAttachMessage(player_guid : PlanetSideGUID,
 
 object ObjectAttachMessage extends Marshallable[ObjectAttachMessage] {
   implicit val codec : Codec[ObjectAttachMessage] = (
-    ("player_guid" | PlanetSideGUID.codec) ::
-      ("item_guid" | PlanetSideGUID.codec) ::
+    ("parent_guid" | PlanetSideGUID.codec) ::
+      ("child_guid" | PlanetSideGUID.codec) ::
       ("slot" | PacketHelpers.encodedStringSize)
     ).as[ObjectAttachMessage]
 }