code documentation and tests

common/src/main/scala/net/psforever/objects/serverobject/CommonMessages.scala

@@ -5,6 +5,8 @@ import net.psforever.objects.Player
 
 //temporary location for these messages
 object CommonMessages {
+  final case class Use(player : Player)
+  final case class Unuse(player : Player)
   final case class Hack(player : Player)
   final case class ClearHack()
 }

common/src/main/scala/net/psforever/objects/serverobject/terminals/MedicalTerminalDefinition.scala

@@ -4,6 +4,14 @@ package net.psforever.objects.serverobject.terminals
 import net.psforever.objects.Player
 import net.psforever.packet.game.ItemTransactionMessage
 
+/**
+  * The definition for any `Terminal` that is of a type "medical_terminal".
+  * This includes the limited proximity-based functionality of the formal medical terminals
+  * and the actual proximity-based functionality of the cavern crystals.<br>
+  * <br>
+  * Do not confuse the "medical_terminal" category and the actual `medical_terminal` object (529).
+  * Objects created by this definition being linked by their use of `ProximityTerminalUseMessage` is more accurate.
+  */
 class MedicalTerminalDefinition(objectId : Int) extends TerminalDefinition(objectId) {
   Name = if(objectId == 38) {
     "adv_med_terminal"
@@ -21,7 +29,7 @@ class MedicalTerminalDefinition(objectId : Int) extends TerminalDefinition(objec
     "portable_med_terminal"
   }
   else {
-    throw new IllegalArgumentException("terminal must be either object id 38, object id 529, or object id 689")
+    throw new IllegalArgumentException("medical terminal must be either object id 38, 225, 226, 529, or 689")
   }
 
   def Buy(player : Player, msg : ItemTransactionMessage) : Terminal.Exchange = Terminal.NoDeal()

common/src/main/scala/net/psforever/objects/serverobject/terminals/ProximityTerminal.scala

@@ -1,10 +1,17 @@
 // Copyright (c) 2017 PSForever
 package net.psforever.objects.serverobject.terminals
 
-import net.psforever.objects.Player
 import net.psforever.packet.game.PlanetSideGUID
 
-class ProximityTerminal(tdef : TerminalDefinition) extends Terminal(tdef) {
+/**
+  * A server object that is a "terminal" that can be accessed for amenities and services,
+  * triggered when a certain distance from the unit itself (proximity-based).<br>
+  * <br>
+  * Unlike conventional terminals, this structure is not necessarily structure-owned.
+  * For example, the cavern crystals are considered owner-neutral elements that are not attached to a `Building` object.
+  * @param tdef the `ObjectDefinition` that constructs this object and maintains some of its immutable fields
+  */
+class ProximityTerminal(tdef : MedicalTerminalDefinition) extends Terminal(tdef) {
   private var users : Set[PlanetSideGUID] = Set.empty
 
   def NumberUsers : Int = users.size
@@ -21,14 +28,11 @@ class ProximityTerminal(tdef : TerminalDefinition) extends Terminal(tdef) {
 }
 
 object ProximityTerminal {
-  final case class Use(player : Player)
-  final case class Unuse(player : Player)
-
   /**
     * Overloaded constructor.
     * @param tdef the `ObjectDefinition` that constructs this object and maintains some of its immutable fields
     */
-  def apply(tdef : TerminalDefinition) : ProximityTerminal = {
+  def apply(tdef : MedicalTerminalDefinition) : ProximityTerminal = {
     new ProximityTerminal(tdef)
   }
 
@@ -41,7 +45,7 @@ object ProximityTerminal {
     * @param context a context to allow the object to properly set up `ActorSystem` functionality
     * @return the `Terminal` object
     */
-  def Constructor(tdef : TerminalDefinition)(id : Int, context : ActorContext) : Terminal = {
+  def Constructor(tdef : MedicalTerminalDefinition)(id : Int, context : ActorContext) : Terminal = {
     import akka.actor.Props
     val obj = ProximityTerminal(tdef)
     obj.Actor = context.actorOf(Props(classOf[ProximityTerminalControl], obj), s"${tdef.Name}_$id")

common/src/main/scala/net/psforever/objects/serverobject/terminals/ProximityTerminalControl.scala

@@ -2,20 +2,28 @@
 package net.psforever.objects.serverobject.terminals
 
 import akka.actor.Actor
+import net.psforever.objects.serverobject.CommonMessages
 import net.psforever.objects.serverobject.affinity.{FactionAffinity, FactionAffinityBehavior}
 import net.psforever.objects.serverobject.terminals.Terminal.TerminalMessage
 
+/**
+  *
+  * An `Actor` that handles messages being dispatched to a specific `ProximityTerminal`.
+  * Although this "terminal" itself does not accept the same messages as a normal `Terminal` object,
+  * it returns the same type of messages - wrapped in a `TerminalMessage` - to the `sender`.
+  * @param term the proximity unit (terminal)
+  */
 class ProximityTerminalControl(term : ProximityTerminal) extends Actor with FactionAffinityBehavior.Check {
   def FactionObject : FactionAffinity = term
 
   def receive : Receive = checkBehavior.orElse {
-    case ProximityTerminal.Use(player) =>
+    case CommonMessages.Use(player) =>
       val hadNoUsers = term.NumberUsers == 0
       if(term.AddUser(player.GUID) == 1 && hadNoUsers) {
         sender ! TerminalMessage(player, null, Terminal.StartProximityEffect(term))
       }
 
-    case ProximityTerminal.Unuse(player) =>
+    case CommonMessages.Unuse(player) =>
       val hadUsers = term.NumberUsers > 0
       if(term.RemoveUser(player.GUID) == 0 && hadUsers) {
         sender ! TerminalMessage(player, null, Terminal.StopProximityEffect(term))

common/src/main/scala/net/psforever/objects/serverobject/terminals/Terminal.scala

@@ -190,8 +190,16 @@ object Terminal {
     */
   final case class InfantryLoadout(exosuit : ExoSuitType.Value, subtype : Int = 0, holsters : List[InventoryItem], inventory : List[InventoryItem]) extends Exchange
 
+  /**
+    * Start the special effects caused by a proximity-base service.
+    * @param terminal the proximity-based unit
+    */
   final case class StartProximityEffect(terminal : ProximityTerminal) extends Exchange
 
+  /**
+    * Stop the special effects caused by a proximity-base service.
+    * @param terminal the proximity-based unit
+    */
   final case class StopProximityEffect(terminal : ProximityTerminal) extends Exchange
 
   /**

common/src/test/scala/objects/ServerObjectBuilderTest.scala

@@ -6,6 +6,7 @@ import net.psforever.objects.guid.NumberPoolHub
 import net.psforever.packet.game.PlanetSideGUID
 import net.psforever.objects.serverobject.ServerObjectBuilder
 import net.psforever.objects.serverobject.structures.{Building, FoundationBuilder, StructureType, WarpGate}
+import net.psforever.objects.serverobject.terminals.ProximityTerminal
 import net.psforever.objects.zones.Zone
 import net.psforever.types.Vector3
 
@@ -130,6 +131,24 @@ class TerminalObjectBuilderTest extends ActorTest {
   }
 }
 
+class ProximityTerminalObjectBuilderTest extends ActorTest {
+  import net.psforever.objects.GlobalDefinitions.medical_terminal
+  import net.psforever.objects.serverobject.terminals.Terminal
+  "Terminal object" should {
+    "build" in {
+      val hub = ServerObjectBuilderTest.NumberPoolHub
+      val actor = system.actorOf(Props(classOf[ServerObjectBuilderTest.BuilderTestActor], ServerObjectBuilder(1, ProximityTerminal.Constructor(medical_terminal)), hub), "term")
+      actor ! "!"
+
+      val reply = receiveOne(Duration.create(1000, "ms"))
+      assert(reply.isInstanceOf[Terminal])
+      assert(reply.asInstanceOf[Terminal].HasGUID)
+      assert(reply.asInstanceOf[Terminal].GUID == PlanetSideGUID(1))
+      assert(reply == hub(1).get)
+    }
+  }
+}
+
 class VehicleSpawnPadObjectBuilderTest extends ActorTest {
   import net.psforever.objects.serverobject.pad.VehicleSpawnPad
   "Vehicle spawn pad object" should {

common/src/test/scala/objects/terminal/MedicalTerminalTest.scala

@@ -0,0 +1,90 @@
+// Copyright (c) 2017 PSForever
+package objects.terminal
+
+import akka.actor.ActorRef
+import net.psforever.objects.serverobject.terminals.{MedicalTerminalDefinition, ProximityTerminal, Terminal}
+import net.psforever.objects.{GlobalDefinitions, Player}
+import net.psforever.packet.game.{ItemTransactionMessage, PlanetSideGUID}
+import net.psforever.types.{CharacterGender, PlanetSideEmpire, TransactionType}
+import org.specs2.mutable.Specification
+
+class MedicalTerminalTest extends Specification {
+  "MedicalTerminal" should {
+    "define (a)" in {
+      val a = new MedicalTerminalDefinition(38)
+      a.ObjectId mustEqual 38
+      a.Name mustEqual "adv_med_terminal"
+    }
+
+    "define (b)" in {
+      val b = new MedicalTerminalDefinition(225)
+      b.ObjectId mustEqual 225
+      b.Name mustEqual "crystals_health_a"
+    }
+
+    "define (c)" in {
+      val c = new MedicalTerminalDefinition(226)
+      c.ObjectId mustEqual 226
+      c.Name mustEqual "crystals_health_b"
+    }
+
+    "define (d)" in {
+      val d = new MedicalTerminalDefinition(529)
+      d.ObjectId mustEqual 529
+      d.Name mustEqual "medical_terminal"
+    }
+
+    "define (e)" in {
+      val e = new MedicalTerminalDefinition(689)
+      e.ObjectId mustEqual 689
+      e.Name mustEqual "portable_med_terminal"
+    }
+
+    "define (invalid)" in {
+      var id : Int = (math.random * Int.MaxValue).toInt
+      if(id == 224) {
+        id += 2
+      }
+      else if(id == 37) {
+        id += 1
+      }
+      else if(id == 528) {
+        id += 1
+      }
+      else if(id == 688) {
+        id += 1
+      }
+
+      new MedicalTerminalDefinition(id) must throwA[IllegalArgumentException]
+    }
+  }
+
+  "Medical_Terminal" should {
+    "construct" in {
+      ProximityTerminal(GlobalDefinitions.medical_terminal).Actor mustEqual ActorRef.noSender
+    }
+
+    "can add a a player to a list of users" in {
+      val terminal = ProximityTerminal(GlobalDefinitions.medical_terminal)
+      terminal.NumberUsers mustEqual 0
+      terminal.AddUser(PlanetSideGUID(10))
+      terminal.NumberUsers mustEqual 1
+    }
+
+    "can remove a a player to a list of users" in {
+      val terminal = ProximityTerminal(GlobalDefinitions.medical_terminal)
+      terminal.AddUser(PlanetSideGUID(10))
+      terminal.NumberUsers mustEqual 1
+      terminal.RemoveUser(PlanetSideGUID(10))
+      terminal.NumberUsers mustEqual 0
+    }
+
+    "player can not interact with the proximity terminal normally (buy)" in {
+      val terminal = ProximityTerminal(GlobalDefinitions.medical_terminal)
+      val player = Player("test", PlanetSideEmpire.TR, CharacterGender.Male, 0, 0)
+      val msg = ItemTransactionMessage(PlanetSideGUID(1), TransactionType.Buy, 1, "lite_armor", 0, PlanetSideGUID(0))
+
+      terminal.Request(player, msg) mustEqual Terminal.NoDeal()
+    }
+  }
+}

common/src/test/scala/objects/terminal/ProximityTerminalControlTest.scala

@@ -0,0 +1,121 @@
+// Copyright (c) 2017 PSForever
+package objects.terminal
+
+import akka.actor.{ActorSystem, Props}
+import net.psforever.objects.serverobject.CommonMessages
+import net.psforever.objects.{GlobalDefinitions, Player}
+import net.psforever.objects.serverobject.terminals._
+import net.psforever.packet.game.PlanetSideGUID
+import net.psforever.types.{CharacterGender, PlanetSideEmpire}
+import objects.ActorTest
+
+import scala.concurrent.duration.Duration
+
+class ProximityTerminalControl1Test extends ActorTest() {
+  "ProximityTerminalControl" should {
+    "construct (medical terminal)" in {
+      val terminal = ProximityTerminal(GlobalDefinitions.medical_terminal)
+      terminal.Actor = system.actorOf(Props(classOf[ProximityTerminalControl], terminal), "test-term")
+    }
+  }
+}
+
+class ProximityTerminalControl2Test extends ActorTest() {
+  "ProximityTerminalControl can not process wrong messages" in {
+    val (_, terminal) = TerminalControlTest.SetUpAgents(GlobalDefinitions.medical_terminal, PlanetSideEmpire.TR)
+
+    terminal.Actor !"hello"
+    val reply = receiveOne(Duration.create(500, "ms"))
+    assert(reply.isInstanceOf[Terminal.NoDeal])
+  }
+}
+
+//terminal control is mostly a pass-through actor for Terminal.Exchange messages, wrapped in Terminal.TerminalMessage protocol
+class MedicalTerminalControl1Test extends ActorTest() {
+  "ProximityTerminalControl sends a message to the first new user only" in {
+    val (player, terminal) = ProximityTerminalControlTest.SetUpAgents(GlobalDefinitions.medical_terminal, PlanetSideEmpire.TR)
+    player.GUID = PlanetSideGUID(10)
+    val player2 = Player("someothertest", PlanetSideEmpire.TR, CharacterGender.Male, 0, 0)
+    player2.GUID = PlanetSideGUID(11)
+
+    terminal.Actor ! CommonMessages.Use(player)
+    val reply = receiveOne(Duration.create(500, "ms"))
+    assert(reply.isInstanceOf[Terminal.TerminalMessage])
+    val reply2 = reply.asInstanceOf[Terminal.TerminalMessage]
+    assert(reply2.player == player)
+    assert(reply2.msg == null)
+    assert(reply2.response.isInstanceOf[Terminal.StartProximityEffect])
+    assert(reply2.response.asInstanceOf[Terminal.StartProximityEffect].terminal == terminal)
+    assert(terminal.NumberUsers == 1)
+
+    terminal.Actor ! CommonMessages.Use(player2)
+    expectNoMsg(Duration.create(500, "ms"))
+    assert(terminal.NumberUsers == 2)
+  }
+}
+
+class MedicalTerminalControl2Test extends ActorTest() {
+  "ProximityTerminalControl sends a message to the last user only" in {
+    val (player, terminal) : (Player, ProximityTerminal) = ProximityTerminalControlTest.SetUpAgents(GlobalDefinitions.medical_terminal, PlanetSideEmpire.TR)
+    player.GUID = PlanetSideGUID(10)
+    val player2 = Player("someothertest", PlanetSideEmpire.TR, CharacterGender.Male, 0, 0)
+    player2.GUID = PlanetSideGUID(11)
+
+    terminal.Actor ! CommonMessages.Use(player)
+    receiveOne(Duration.create(500, "ms"))
+    terminal.Actor ! CommonMessages.Use(player2)
+    expectNoMsg(Duration.create(500, "ms"))
+    assert(terminal.NumberUsers == 2)
+
+    terminal.Actor ! CommonMessages.Unuse(player)
+    expectNoMsg(Duration.create(500, "ms"))
+    assert(terminal.NumberUsers == 1)
+
+    terminal.Actor ! CommonMessages.Unuse(player2)
+    val reply = receiveOne(Duration.create(500, "ms"))
+    assert(reply.isInstanceOf[Terminal.TerminalMessage])
+    val reply2 = reply.asInstanceOf[Terminal.TerminalMessage]
+    assert(reply2.player == player2)
+    assert(reply2.msg == null)
+    assert(reply2.response.isInstanceOf[Terminal.StopProximityEffect])
+    assert(reply2.response.asInstanceOf[Terminal.StopProximityEffect].terminal == terminal)
+    assert(terminal.NumberUsers == 0)
+  }
+}
+
+class MedicalTerminalControl3Test extends ActorTest() {
+  "ProximityTerminalControl sends a message to the last user only (confirmation of test #2)" in {
+    val (player, terminal) : (Player, ProximityTerminal) = ProximityTerminalControlTest.SetUpAgents(GlobalDefinitions.medical_terminal, PlanetSideEmpire.TR)
+    player.GUID = PlanetSideGUID(10)
+    val player2 = Player("someothertest", PlanetSideEmpire.TR, CharacterGender.Male, 0, 0)
+    player2.GUID = PlanetSideGUID(11)
+
+    terminal.Actor ! CommonMessages.Use(player)
+    receiveOne(Duration.create(500, "ms"))
+    terminal.Actor ! CommonMessages.Use(player2)
+    expectNoMsg(Duration.create(500, "ms"))
+    assert(terminal.NumberUsers == 2)
+
+    terminal.Actor ! CommonMessages.Unuse(player2)
+    expectNoMsg(Duration.create(500, "ms"))
+    assert(terminal.NumberUsers == 1)
+
+    terminal.Actor ! CommonMessages.Unuse(player)
+    val reply = receiveOne(Duration.create(500, "ms"))
+    assert(reply.isInstanceOf[Terminal.TerminalMessage])
+    val reply2 = reply.asInstanceOf[Terminal.TerminalMessage]
+    assert(reply2.player == player) //important!
+    assert(reply2.msg == null)
+    assert(reply2.response.isInstanceOf[Terminal.StopProximityEffect])
+    assert(reply2.response.asInstanceOf[Terminal.StopProximityEffect].terminal == terminal)
+    assert(terminal.NumberUsers == 0)
+  }
+}
+
+object ProximityTerminalControlTest {
+  def SetUpAgents(tdef : MedicalTerminalDefinition, faction : PlanetSideEmpire.Value)(implicit system : ActorSystem) : (Player, ProximityTerminal) = {
+    val terminal = ProximityTerminal(tdef)
+    terminal.Actor = system.actorOf(Props(classOf[ProximityTerminalControl], terminal), "test-term")
+    (Player("test", faction, CharacterGender.Male, 0, 0), terminal)
+  }
+}