added proper comments; changed name of case class

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

@@ -8,23 +8,50 @@ import scodec.codecs._
 import shapeless.{::, HNil}
 
 /**
-  * na
+  * Instructs an avatar to be stood, to look, and to move, in a certain way.<br>
-  * @param pos the position to move the character to in the world environment (in three coordinates)
+  * <br>
+  * The position defines a coordinate location in the avatar's current zone to which the avatar is immediately moved
+  * This movement is instantaneous and has no associated animation.
+  * If velocity is defined, the avatar is provided an "external force" that "pushes" the avatar in a given direction.
+  * This external force is not accumulative.
+  * Also, the external force is only applied once the avatar is set to the provided position.<br>
+  * <br>
+  * `viewYawLim` defines a "range of angles" that the avatar may look centered on the supplied angle.
+  * The avatar must be facing within 60-degrees of that direction, subjectively his left or his right.
+  * The avatar's view is immediately set to the closest 60-degree mark if it is outside of that range.
+  * The absolute angular displacement of the avatar is considered before applying this corrective behavior.
+  * After rotating any number of times:
+  * stopping in a valid part of the range is acceptable;
+  * stopping in an invalid part of the range will cause the avatar to align to the __earliest__ still-valid 60-degree mark.
+  * For that reason, even if the avatar's final angle is closest to the "left mark," it may re-align to the "right mark."
+  * This also resets the avatar's angular displacement.
+  * @param pos the position to move the character to in the world environment
   * @param viewYawLim an angle with respect to the horizon towards which the avatar is looking (to some respect)
-  * @param vel the velocity to apply to to the character at the given position (in three coordinates)
+  * @param vel if defined, the velocity to apply to to the character at the given position
   */
-final case class PlayerState(pos : Vector3,
+final case class ShiftState(pos : Vector3,
                              viewYawLim : Int,
                              vel : Option[Vector3])
 
 /**
-  * Force the client's character to adhere to the influence of specific external stimulus.
+  * Push specific motion-based stimuli on a specific character.<br>
-  * @param unk1 na
+  * <br>
-  * @param state the state to influence the character with respect to his environment in the current zone
+  * `PlayerStateMessageUpstream` involves data transmitted from a client to the server regarding its avatar.
-
+  * `PlayerStateMessage` involves data transmitted from the server to the clients regarding characters other than that client's avatar.
+  * `PlayerStateShiftMessage` involves data transmitted from the server to a client about that client's avatar.
+  * It temporarily asserts itself before normal player movement and asserts specific placement and motion.
+  * An application of this packet is being `/warp`ed within a zone via a non-triggering agent (like a teleporter).
+  * Another, more common, application of this packet is being thrown about when the target of an attempted roadkill.<br>
+  * <br>
+  * Exploration:<br>
+  * What do the leading and trailing values do?
+  * @param unk1 na;
+  *             seems to have different purposes depending on whether `state` is defined
+  * @param state if defined, the behaviors to influence the character
+  * @param unk2 na
   */
 final case class PlayerStateShiftMessage(unk1 : Int,
-                                         state : Option[PlayerState],
+                                         state : Option[ShiftState],
                                          unk2 : Boolean)
   extends PlanetSideGamePacket {
   type Packet = TimeOfDayMessage
@@ -32,60 +59,58 @@ final case class PlayerStateShiftMessage(unk1 : Int,
   def encode = PlayerStateShiftMessage.encode(this)
 }
 
-object PlayerState extends Marshallable[PlayerState] {
+object ShiftState extends Marshallable[ShiftState] {
   /**
-    * An abbreviated constructor for creating `PlayerState`, assuming velocity is not applied.
+    * An abbreviated constructor for creating `ShiftState`, assuming velocity is not applied.
-    * @param pos the position of the character in the world environment (in three coordinates)
+    * @param pos the position of the character in the world environment
     * @param viewYawLim an angle with respect to the horizon towards which the avatar is looking (to some respect)
-    * @param vel the velocity to apply to to the character at the given position (in three coordinates)
+    * @param vel the velocity to apply to to the character at the given position
-    * @return a `PlayerState` object
+    * @return a `ShiftState` object
     */
-  def apply(pos : Vector3, viewYawLim : Int, vel : Vector3) : PlayerState =
+  def apply(pos : Vector3, viewYawLim : Int, vel : Vector3) : ShiftState =
-    PlayerState(pos, viewYawLim, Some(vel))
+    ShiftState(pos, viewYawLim, Some(vel))
 
   /**
-    * An abbreviated constructor for creating `PlayerState`, removing the optional condition of all parameters.
+    * An abbreviated constructor for creating `ShiftState`, removing the optional condition of all parameters.
-    * @param pos the position of the character in the world environment (in three coordinates)
+    * @param pos the position of the character in the world environment
     * @param viewYawLim an angle with respect to the horizon towards which the avatar is looking (to some respect)
-    * @return a `PlayerState` object
+    * @return a `ShiftState` object
     */
-  def apply(pos : Vector3, viewYawLim : Int) : PlayerState =
+  def apply(pos : Vector3, viewYawLim : Int) : ShiftState =
-    PlayerState(pos, viewYawLim, None)
+    ShiftState(pos, viewYawLim, None)
 
-  implicit val codec : Codec[PlayerState] = (
+  implicit val codec : Codec[ShiftState] = (
       ("pos" | Vector3.codec_pos) ::
-      ("unk2" | uint8L) ::
+        ("unk2" | uint8L) ::
-      (bool >>:~ { test =>
+        (bool >>:~ { test =>
-        ignore(0) ::
+          ignore(0) ::
-          conditional(test, "pos" | Vector3.codec_vel)
+            conditional(test, "pos" | Vector3.codec_vel)
-      })
+        })
-    ).xmap[PlayerState] (
+    ).xmap[ShiftState] (
       {
         case a :: b :: false :: _ :: None :: HNil =>
-          PlayerState(a, b, None)
+          ShiftState(a, b, None)
         case a :: b :: true :: _ :: Some(vel) :: HNil =>
-          PlayerState(a, b, Some(vel))
+          ShiftState(a, b, Some(vel))
       },
       {
-        case PlayerState(a, b, None) =>
+        case ShiftState(a, b, None) =>
           a :: b :: false :: () :: None :: HNil
-        case PlayerState(a, b, Some(vel)) =>
+        case ShiftState(a, b, Some(vel)) =>
           a :: b :: true :: () :: Some(vel) :: HNil
       }
-    ).as[PlayerState]
+    ).as[ShiftState]
 }
 
 object PlayerStateShiftMessage extends Marshallable[PlayerStateShiftMessage] {
-  private type pattern = Int :: Option[PlayerState] :: Boolean :: HNil
-
   /**
     * An abbreviated constructor for creating `PlayerStateShiftMessage`, removing the optional condition of `state`.
     * @param unk1 na
-    * @param state the state to which to influence the character with respect to his environment in the current zone
+    * @param state the behaviors to influence the character
     * @param unk2 na
     * @return a `PlayerStateShiftMessage` packet
     */
-  def apply(unk1 : Int, state : PlayerState, unk2 : Boolean) : PlayerStateShiftMessage =
+  def apply(unk1 : Int, state : ShiftState, unk2 : Boolean) : PlayerStateShiftMessage =
     PlayerStateShiftMessage(unk1, Some(state), unk2)
 
   /**
@@ -98,9 +123,9 @@ object PlayerStateShiftMessage extends Marshallable[PlayerStateShiftMessage] {
     PlayerStateShiftMessage(unk1, None, unk2)
 
   implicit val codec : Codec[PlayerStateShiftMessage] = (
-    bool >>:~ { test1 =>
+    bool >>:~ { test =>
       ("unk1" | uintL(3)) ::
-        conditional(test1, "pos" | PlayerState.codec) ::
+        conditional(test, "state" | ShiftState.codec) ::
         ("unk2" | bool)
     }).xmap[PlayerStateShiftMessage] (
       {

common/src/test/scala/GamePacketTest.scala

@@ -587,7 +587,7 @@ class GamePacketTest extends Specification {
 
       "encode (pos)" in {
         val msg = PlayerStateShiftMessage(1,
-          PlayerState(Vector3(4624.703f, 5922.1484f, 46.171875f), 255),
+          ShiftState(Vector3(4624.703f, 5922.1484f, 46.171875f), 255),
           false)
         val pkt = PacketCoding.EncodePacket(msg).require.toByteVector
 
@@ -596,7 +596,7 @@ class GamePacketTest extends Specification {
 
       "encode (pos and vel)" in {
         val msg = PlayerStateShiftMessage(2,
-          PlayerState(Vector3(4645.75f, 5811.6016f, 50.3125f), 14, Vector3(2.8125f, -8.0f, 0.375f)),
+          ShiftState(Vector3(4645.75f, 5811.6016f, 50.3125f), 14, Vector3(2.8125f, -8.0f, 0.375f)),
           false)
         val pkt = PacketCoding.EncodePacket(msg).require.toByteVector