From dc71256457a7cd7d12fc487bc6a80fe7ab1771db Mon Sep 17 00:00:00 2001
From: FateJH <Jason_DiDonato@yahoo.com>
Date: Thu, 26 Jan 2017 19:02:54 -0500
Subject: [PATCH] comments and constructor param modifications

---
 .../game/OrbitalStrikeWaypointMessage.scala   | 66 ++++++++++++++-----
 common/src/test/scala/GamePacketTest.scala    |  2 +-
 2 files changed, 51 insertions(+), 17 deletions(-)

diff --git a/common/src/main/scala/net/psforever/packet/game/OrbitalStrikeWaypointMessage.scala b/common/src/main/scala/net/psforever/packet/game/OrbitalStrikeWaypointMessage.scala
index 7623d9c7..a631fdb5 100644
--- a/common/src/main/scala/net/psforever/packet/game/OrbitalStrikeWaypointMessage.scala
+++ b/common/src/main/scala/net/psforever/packet/game/OrbitalStrikeWaypointMessage.scala
@@ -7,11 +7,37 @@ import scodec.Codec
 import scodec.codecs._
 import shapeless.{::, HNil}
 
-final case class XY(x : Float,
-                    y : Float)
+/**
+  * The position of a waypoint in the game world.
+  * Only two coordinates are required as the beam travels from a specific height to ground level.
+  * @param x the x-coordinate of the waypoint
+  * @param y the y-coordinate of the waypoint
+  */
+final case class Waypoint(x : Float,
+                          y : Float)
 
-final case class OrbitalStrikeWaypointMessage(unk : PlanetSideGUID,
-                                              coords : Option[XY] = None)
+/**
+  * Dispatched by the server to tell the client to display an orbital strike waypoint somewhere in the game world.<br>
+  * <br>
+  * Waypoints are kept unique by the `guid` that is passed with them.
+  * To clear a waypoint is to pass the another packet to the client with the same GUID but with no coordinates.
+  * Passing new coordinates with that GUID will update the position of the indicated waypoint.
+  * If the GUID sent with the packet belongs to the client's avatar that player will be given text overlay instructions:<br>
+  * "Press the fire key or button to launch an orbital strike at the waypoint."<br>
+  * The text will fade shortly after the waypoint has been cleared.<br>
+  * <br>
+  * All `OrbitalStrikeWaypointMessage` packets sent to a client will create a waypoint that will be seen by that client.
+  * All rendered waypoints, regardless of the users who summoned them, will be seen in the faction color of the client's avatar.
+  * (Black OPs orbital strike waypoints are green, as expected.)
+  * The server should not notify the wrong clients about another faction's prepared orbital strikes;
+  * however, even if it did, those beams would be seen as a same-faction's marker.
+  * @param guid coordinates used to identify the waypoint;
+  *             ostensibly, the GUID of the player who placed the waypoint
+  * @param coords the coordinates of the waypoint;
+  *               `None` if clearing a waypoint (use the same `guid` as to create it)
+  */
+final case class OrbitalStrikeWaypointMessage(guid : PlanetSideGUID,
+                                              coords : Option[Waypoint] = None)
   extends PlanetSideGamePacket {
   type Packet = OrbitalStrikeWaypointMessage
   def opcode = GamePacketOpcode.OrbitalStrikeWaypointMessage
@@ -19,36 +45,44 @@ final case class OrbitalStrikeWaypointMessage(unk : PlanetSideGUID,
 }
 
 object OrbitalStrikeWaypointMessage extends Marshallable[OrbitalStrikeWaypointMessage] {
-  def apply(player_guid : PlanetSideGUID, coords : XY) : OrbitalStrikeWaypointMessage =
-    new OrbitalStrikeWaypointMessage(player_guid, Option(coords))
+  /**
+    * An abbreviated constructor for creating `OrbitalStrikeWaypointMessage`, assuming mandatory coordinates.
+    * @param guid na
+    * @param x the x-coordinate of the waypoint
+    * @param y the y-coordinate of the waypoint
+    * @return an `OrbitalStrikeWaypointMessage` object
+    */
+  def apply(guid : PlanetSideGUID, x : Float, y : Float) : OrbitalStrikeWaypointMessage =
+    new OrbitalStrikeWaypointMessage(guid, Option(Waypoint(x, y)))
 
-  private val coords_value : Codec[XY] = (
+  /**
+    * A `Codec` for recording the two coordinates of the waypoint map position, if they are present.
+    */
+  private val coords_value : Codec[Waypoint] = (
     ("x" | newcodecs.q_float(0.0, 8192.0, 20)) ::
       ("y" | newcodecs.q_float(0.0, 8192.0, 20))
-    ).xmap[XY] (
+    ).xmap[Waypoint] (
     {
       case x :: y :: HNil =>
-        XY(x, y)
+        Waypoint(x, y)
     },
     {
-      case XY(x, y) =>
+      case Waypoint(x, y) =>
         x :: y :: HNil
     }
   )
 
   implicit val codec : Codec[OrbitalStrikeWaypointMessage] = (
-    ("unk" | PlanetSideGUID.codec) ::
-      (bool >>:~ { test =>
-        conditional(test, coords_value).hlist
-      })
+    ("guid" | PlanetSideGUID.codec) ::
+      optional(bool, coords_value)
     ).xmap[OrbitalStrikeWaypointMessage] (
     {
-      case u :: _ :: coords :: HNil =>
+      case u :: coords :: HNil =>
         OrbitalStrikeWaypointMessage(u, coords)
     },
     {
       case OrbitalStrikeWaypointMessage(u, coords) =>
-        u :: coords.isDefined :: coords :: HNil
+        u :: coords :: HNil
     }
   )
 }
diff --git a/common/src/test/scala/GamePacketTest.scala b/common/src/test/scala/GamePacketTest.scala
index 3e33bd53..c5d847da 100644
--- a/common/src/test/scala/GamePacketTest.scala
+++ b/common/src/test/scala/GamePacketTest.scala
@@ -1498,7 +1498,7 @@ class GamePacketTest extends Specification {
       }
 
       "encode (on)" in {
-        val msg = OrbitalStrikeWaypointMessage(PlanetSideGUID(3142), XY(5518.664f, 2212.539f))
+        val msg = OrbitalStrikeWaypointMessage(PlanetSideGUID(3142), 5518.664f, 2212.539f)
         val pkt = PacketCoding.EncodePacket(msg).require.toByteVector
 
         pkt mustEqual string_on