Mission Area Out-of-bounds Damage and/or Warning

This Resource will deal with making use of the Mission Area object within a game level. The Mission Area has no functionality on it's own, it simply defines a box like area that will make some script callbacks when an object crosses the boundary -- sort of like a trigger. You can add whatever type of functionality to these script callbacks as you wish: cause damage, flash a warning to the screen, strip the player of his weapons, teleport the player, stop the player in his tracks, strike the player with lightning, turn the player into a horse, etc, etc.

Some of you may recall that the FPS project included with the pre-release betas of T3D had a Mission Area that would display a warning graphic on the HUD, play a sound, and cause damage to the player that exited the Mission Area. This got stripped when simplifying the FPS example, but here I demonstrate how to re-enable this functionality.

I've the broken this into three sections, with the first detailing how to prepare the Mission Area boundary. Use the optional parts 2 and 3 at your own discretion.


PART 1 - PREPARE THE MISSION AREA

Create a MissionArea from within the Editor. For quick testing I used an area setting of "-50 -50 100 100" -- assuming a spawn point for the player at the origin. The Mission Area editor tooltip for area reads:

Quote:
Four corners (X1, X2, Y1, Y2) that makes up the level boundaries.

Take note that these are not absolute positions. They are instead a beginning point (X1 X2) and a length measurement (in Torque units) extending on the X & Y axes (Y1 Y2). With my testing settings of "-50 - 50 100 100" the Mission Area square will start at "-50 -50" (X Y) from the origin and extend 100 units in the X axis direction (Y1) and 100 units in the Y axis direction (Y2).

The flightCeiling is supposed to be a maximum height of the Mission Area that would limit the flying height of a flying vehicle, with the flightCeilingRange as a distance in which to start scaling the vehicle's vertical velocity to 0 -- but I'm not sure if these are actually working...

I also placed a few cubes as markers to give a visual representation in-game of the Mission Area boundaries:

new MissionArea() {
   area = "-50 -50 100 100";
   flightCeiling = "2000";
   flightCeilingRange = "50";
   canSave = "1";
   canSaveDynamicFields = "1";
};
new TSStatic() {
   shapeName = "art/shapes/cube/cube.dae";
   playAmbient = "1";
   meshCulling = "0";
   originSort = "0";
   collisionType = "Collision Mesh";
   decalType = "Collision Mesh";
   allowPlayerStep = "1";
   renderNormals = "0";
   forceDetail = "-1";
   position = "-50 -50 0";
   rotation = "1 0 0 0";
   scale = "1 1 1000";
   canSave = "1";
   canSaveDynamicFields = "1";
};
new TSStatic() {
   shapeName = "art/shapes/cube/cube.dae";
   playAmbient = "1";
   meshCulling = "0";
   originSort = "0";
   collisionType = "Collision Mesh";
   decalType = "Collision Mesh";
   allowPlayerStep = "1";
   renderNormals = "0";
   forceDetail = "-1";
   position = "50 -50 0";
   rotation = "1 0 0 0";
   scale = "1 1 1000";
   canSave = "1";
   canSaveDynamicFields = "1";
};
new TSStatic() {
   shapeName = "art/shapes/cube/cube.dae";
   playAmbient = "1";
   meshCulling = "0";
   originSort = "0";
   collisionType = "Collision Mesh";
   decalType = "Collision Mesh";
   allowPlayerStep = "1";
   renderNormals = "0";
   forceDetail = "-1";
   position = "-50 50 0";
   rotation = "1 0 0 0";
   scale = "1 1 1000";
   canSave = "1";
   canSaveDynamicFields = "1";
};
new TSStatic() {
   shapeName = "art/shapes/cube/cube.dae";
   playAmbient = "1";
   meshCulling = "0";
   originSort = "0";
   collisionType = "Collision Mesh";
   decalType = "Collision Mesh";
   allowPlayerStep = "1";
   renderNormals = "0";
   forceDetail = "-1";
   position = "50 50 0";
   rotation = "1 0 0 0";
   scale = "1 1 1000";
   canSave = "1";
   canSaveDynamicFields = "1";
};

Inside of the player.cs script file you'll find two callbacks: onLeaveMissionArea() and onEnterMissionArea(). Currently this does nothing more than pass things along to the GameConnection version of these callbacks which processes a client message - see game.cs for the message string.

Run around, back and forth crossing the Mission Area boundary and you'll be rewarded with a message appearing in the Chat Hud letting you know that you left or entered the Mission Area.


PART 2: DAMAGE

One thing that you may note in the PlayerData (or Armor) version of these callbacks are a couple of commented lines:

function Armor::onLeaveMissionArea(%this, %obj)
{
   //echo("\c4Leaving Mission Area at POS:"@ %obj.getPosition());

   // Inform the client
   %obj.client.onLeaveMissionArea();

   // Damage over time and kill the coward!
   //%obj.setDamageDt(0.2, "MissionAreaDamage"); // <-- this line turns on out-of-bounds damage
}

function Armor::onEnterMissionArea(%this, %obj)
{
   //echo("\c4Entering Mission Area at POS:"@ %obj.getPosition());

   // Inform the client
   %obj.client.onEnterMissionArea();

   // Stop the punishment
   //%obj.clearDamageDt(); // <-- this line turns off out-of-bounds damage
}

Specifically what we're looking at are the lines preceded by the comments "damage over time and kill the coward!" and "stop the punishment". This is something I left in for the observant developer to notice and make use of if they wished. Uncommenting these lines will turn on recurring damage when a player leaves the mission area, and turn off the out-of-bounds damage once they return back to the mission area.

Small note about setDamageDt(): this was used back in TGE/TGEa to gradually (supposedly) apply damage to the player when entering lava, but the functionality was bugged and worked incorrectly insta-killing the player. I fixed it for Torque 3D but since the Lava watertype was removed there was nothing using it -- thus the inclusion of Mission Area out-of-bounds damage to the FPS project!


PART 3: GUI INDICATOR

Take a look at the playGui.gui file, in it you will find a GuiBitmapCtrl named OOBSign. This got accidently left behind when stripping the old FPS project down prior to T3D 1.0 release. Since it's still in place let's go ahead and use it as is.

You'll need an image to use for the out-of-bounds indicator. I included one with those from my previous Resource, Directional Hit Indicators. If you haven't applied it then get the archive at eb's Unofficial Torque Public File System. Extract the zip file such that the images are located in the YOURGAME: "art/gui/playHud/" directory.

Inside of game.cs (a server-side script) change the GameConnection Mission Area callbacks:

function GameConnection::onLeaveMissionArea(%this)
{
   // The control objects invoke this method when they
   // move out of the mission area.

   messageClient(%this, 'MsgClientJoin', 'c2Now leaving the mission area!');
   %this.player.OOB = true;
   commandToClient(%this, 'OutOfBounds', %this.player);
}

function GameConnection::onEnterMissionArea(%this)
{
   // The control objects invoke this method when they
   // move back into the mission area.

   messageClient(%this, 'MsgClientJoin', 'c2Now entering the mission area.');
   %this.player.OOB = false;
   commandToClient(%this, 'OutOfBounds', %this.player);
}

Now inside of client.cs (a client-side script) add the following:

// ----------------------------------------------------------------------------
// Out of Mission Area
// ----------------------------------------------------------------------------

// Here I show how to set up a "toggle" method that switches the GUI indicator
// on and off at a timed increment.  The warning sound is turned off by
// re-sending the OutOfBounds clienCmd, but with a false condition assigned to
// the player.OOB property.

function clientCmdOutOfBounds(%player)
{
   if (%player.OOB == true)
   {
      messageClient(%player.client, 'MsgClientJoin', 'c2Return to the mission area!');
      OOBSign.setVisible(true);
      $OOBSound = sfxPlay(OOBWarningSnd);
      $OOBWarn = schedule(1000, 0, "OOBToggle", 0, %player);
   }
   else
   {
      cancel($OOBWarn);
      sfxStop($OOBSound);
      OOBSign.setVisible(false);
   }
}

function OOBToggle(%val, %player)
{
   if (%val == 0)
   {
      %val = 1;
      OOBSign.setVisible(false);
   }
   else
   {
      %val = 0;
      OOBSign.setVisible(true);
      messageClient(%player.client, 'MsgClientJoin', 'c2Return to the mission area!');
   }
   $OOBWarn = schedule(1000, 0, "OOBToggle", %val, %player);
}

The OOBWarningSnd datablock was also left behind inside of "art/datablocks/audioProfiles.cs", so we're making use of it here -- if using TGE/TGEa you'll need to create this datablock. It uses the orc pain sound as a placeholder, but feel free to modify the datablock to use your own preferred warning sound.

In case of player death while outside the Mission Area we need some way of turning off the GUI indicator and warning sound. Inside gameCore.cs (a server-side script) find function GameCore::onDeath() and add the following:

// Check for and cancel possible OOB warning
if (%client.player.OOB == true)
{
   %client.player.OOB = false;
   commandToClient(%client, 'OutOfBounds', %client.player);
}