Stealth-game style Light-Level detection

UPDATE: 29/4/2015
So I've made some advances to this resource and decided to rewriteit a bit to make the instructions a little clearer. The revised version is below.

I'm in the process of prototyping a game using the UAISK and Torque3D and stealth-like mechanics are central to my gameplay. After some searching and hacking together code I found there wasn't a simple solution to accurately measure the amount of light a player was subjected to using the rendered image (there may be a way to expose shadow volumes to script, but it was too elaborate for me to wrap my head around) so instead I decided to emulate the light volumes.

A video of the end result:

This resource requires a couple of simple engine changes in order to function well, but they can be skipped if you really don't want to alter the engine. We'll begin with those and as we go on, I'll note where it needs to be altered in script to negate the engine changes.

Engine Changes (optional):

Firstly, we're going to add a bool to light objects that will mark them as 'stealth-lights', so that we can pick and choose which lights will contribute to the light level calculations.

In T3D/lightBase.h add the following above "bool mIsEnabled":

bool mIsStealthLight;

Then in T3D/lightBase.cpp above 'mIsEnabled(true)':

mIsStealthLight( true ),

above the addField definition for isEnabled:

addField( "isStealthLight", TypeBool, Offset( mIsStealthLight, LightBase ), "Does this light contribute to the player light level used in stealth calculations?" );

above 'stream->writeFlag( mIsEnabled );'

stream->writeFlag( mIsStealthLight );

and above 'mIsEnabled = stream->readFlag();'

mIsStealthLight = stream->readFlag();

Now we'll have a nice flag on all our light objects that can be toggled in the world editor!

Next, we're going to expose the brightness level of lights accoridng to their animation state. This is so that if we place animated lights in the scene, we will have a brightness value that adjusts to the brightness of the light in its current frame of animation. This just allows us to be more crafty with our stealth designs; flickering lights that provide only moments of visibility to the AI, or pulsing lights players have to time their way past.

In T3D/lightAnimData.h add the following at about line 110:

F32 getBrightness( LightAnimState *state );

Then in T3D/lightAnimData.cpp at the very end of the file:

F32 LightAnimData::getBrightness( LightAnimState *state )
{
	//PROFILE_SCOPE( LightAnimData_animate );
	F32 time =  state->animationPhase + 
               ( (F32)Sim::getCurrentTime() * 0.001f ) / 
               state->animationPeriod;

	F32 brightness = state->brightness;
	mBrightness.animate( time, &brightness );
	return( brightness );
}

In T3D/lightBase.h around line 136:

F32 getTrueBrightness( void );

And finally at the end of T3D/lightBase.cpp:

DefineConsoleMethod( LightBase, getTrueBrightness, F32, (), , "Returns the brightness level of the light, taking into account its current animation state." )
{
    return( object->getTrueBrightness() );
}

F32 LightBase::getTrueBrightness( void )
{
    if ( mAnimState.active && mAnimationData )
    {
        return( mAnimationData->getBrightness( &mAnimState ) );
    }
	else
	{
		 return( mBrightness );
	}
}

Now we have a function, getTrueBrightness(), that when called on a light object will return the brightness of the current animation frame.

And that's it for the engine changes. Recompile and your lights will have an isStealthLight flag and a getTrueBrightness function, which we will be using shortly.

Script Additions:

Firstly, at the end of my GameConnection::onClientEnterGame() function I've created a ScriptTickObject. I originally used a schedule timer to perform the light checks, but found that the effect it produced wasn't as fluid as I would have liked. In previous versions of Torque the only way to have code execute between ticks (such as a moving object) was to use C++. It worked, but wasn't friendly to quick-and-dirty prototyping. ScriptTickObject rectifies this and from my limited experience, seems to work very well.

So, at the bottom of GameConnection::onClientEnterGame():

//Set up the tick object to perform stealth checks
   if(!isObject(stealthTicker))
   {
   	%tickObj = new ScriptTickObject(stealthTicker);
   	%tickObj.setProcessTicks(true);

	  MissionCleanup.add(%tickObj);
   }

(adapted lovingly from the kind Mr. Martin here)

Then I created a new file, but I suppose, really, it can go anywhere you please. This is the function which performs the light checks. Firstly, we reset the %currLightLevel var. Then we get the player object and start a ContainerRadiusSearch for light objects. If it is a stealth-light, we grab its range (if it's a directional light) or radius (if it's an omni light) and see if the player is within its reach.

If it is an omni light, a raycast is performed between the light and the player to see if the view between the player and light is obstructed. If it is a directional light (watch out for my hacky bad vector maths - please, if you can improve this at all let me know!) an array of raycasts is performed in the range of the light to see if the player is within its reach. This is far from a perfect solution, but it mostly works. If you want to visualise the raycasts, uncomment the DebugDraw call.

If the view between the light and the player is unobstructed, the distance between the light and the player has some crafty maths applied to it and is then assigned to the player object, and a command sent to the client to update their stealth meter. The value is a float between 0 and 1, so I'm sure you can come up with something cool to represent it.

function light_test(){
   %currLightLevel = 0;
   if(%clientConn = clientGroup.getObject(0)){ 
      //Get the player's position
      %player = %clientConn.getControlObject(); 
      %camPos = %player.getPosition();
   
      //Set a search radius - vary this on difficuty?
      %searchRadius = 30;
   
      //Do a radius search for light objects
      initContainerRadiusSearch(%camPos, %searchRadius, $TypeMasks::LightObjectType, false);
   
      //See if we found anything
      while((%light = containerSearchNext()) != 0){
         
         //If we did, we check to see if this light has checks enabled
         //If you did't make the engine changes, comment out the below line and uncomment the one below that.
         if(%light.IsStealthLight && %light.IsEnabled){
         //if(%light.IsEnabled){
         
            //Now check to see if we're in range of light, and by how much
            if(%light.radius){
               %lightSize = %light.radius;
            } else if(%light.range) {
               %lightSize = 0;
               %addVec = VectorScale(%light.getForwardVector(), %light.range);
               %newPos = VectorAdd(%light.getPosition(), %addVec);
               %vecTypemasks = $TypeMasks::StaticObjectType | $TypeMasks::ShapeBaseObjectType;
               
               %lightSpread = mTan(mDegToRad(%light.outerAngle / 2)) * %light.range;
               
               //Centre Vector
               %vecList[0] = %newPos;
               
               //Outside Vectors
               %vecList[1] = VectorAdd(%newPos, "0 0 " @ %lightSpread);
               %vecList[2] = VectorAdd(%newPos, "0 0 -" @ %lightSpread);
               %vecList[3] = VectorAdd(%newPos, "0 " @ %lightSpread @ " 0");
               %vecList[4] = VectorAdd(%newPos, "0 -" @ %lightSpread @ " 0");
               %vecList[5] = VectorAdd(%newPos, "0 " @ (%lightSpread / 1.5) @ " " @ (%lightSpread / 1.5));
               %vecList[6] = VectorAdd(%newPos, "0 " @ (%lightSpread / 1.5) @ " -" @ (%lightSpread / 1.5));
               %vecList[7] = VectorAdd(%newPos, "0 -" @ (%lightSpread / 1.5) @ " -" @ (%lightSpread / 1.5));
               %vecList[8] = VectorAdd(%newPos, "0 -" @ (%lightSpread / 1.5) @ " " @ (%lightSpread / 1.5));
               
               //Inside Vectors
               %vecList[9] = VectorAdd(%newPos, "0 0 " @ (%lightSpread / 2));
               %vecList[10] = VectorAdd(%newPos, "0 0 -" @ (%lightSpread / 2));
               %vecList[11] = VectorAdd(%newPos, "0 " @ (%lightSpread / 2) @ " 0");
               %vecList[12] = VectorAdd(%newPos, "0 -" @ (%lightSpread / 2) @ " 0");
               %vecList[13] = VectorAdd(%newPos, "0 " @ (%lightSpread / 3) @ " " @ (%lightSpread / 3));
               %vecList[14] = VectorAdd(%newPos, "0 " @ (%lightSpread / 3) @ " -" @ (%lightSpread / 3));
               %vecList[15] = VectorAdd(%newPos, "0 -" @ (%lightSpread / 3) @ " -" @ (%lightSpread / 3));
               %vecList[16] = VectorAdd(%newPos, "0 -" @ (%lightSpread / 3) @ " " @ (%lightSpread / 3));
               
               %vecCount = 0;
               %tmpLightSize = 0;
               for(%vecCount = 0; %vecCount <= 17; %vecCount++)
               {
                  %vecCheck = containerRayCast(%light.getPosition(), %vecList[%vecCount], %vecTypemasks);
                  //DebugDraw.drawLine(%light.getPosition(), %vecList[%vecCount]);
                  
                  %obj = getWords(%vecCheck, 0, 0);
                  if(%obj){
                     if(%obj.getClassName() $= "Player"){
                        %lightSize = %light.range;
                     }
                  }  
               }
            } else {
               //We don't know how far this light shines, so let's ignore it
               %lightSize = 0;
            }

            if(containerSearchCurrDist() < %lightSize){
               //Now check to see if anything is blocking our line of sight.
               //If it is, we're in shadow and can ignore the light
               %losTypemasks = $TypeMasks::StaticObjectType | $TypeMasks::ShapeBaseObjectType;
               %losCheck = containerRayCast(%camPos, %light.getPosition(), %losTypemasks, %player);
            
               if(!%losCheck){
                  //If you did't make the engine changes, comment out the below line and uncomment the one below that.
                  %lightAmount = (1 - (1 / %lightSize * containerSearchCurrDist())) * %light.getTrueBrightness(); //mRound((1 - (1 / %lightSize * containerSearchCurrDist())) * 10);
                  //%lightAmount = (1 - (1 / %lightSize * containerSearchCurrDist())) * %light.brightness; //mRound((1 - (1 / %lightSize * containerSearchCurrDist())) * 10);
                  if(%lightAmount > %currLightLevel){
                     %currLightLevel = %lightAmount;
                  }
               }
            }
         }
      }
      //Send the light level to the player
      %player.lightLevel = mRound(%currLightLevel * 10);
      commandToClient(%clientConn, 'setLightMeter', %currLightLevel);
   }
}

Then we set our ticker to run a light_test();

function stealthTicker::onInterpolateTick(%this, %timeDelta){
   light_test();
}

And add a function on the client to receive the server's command:

function clientCmdSetLightMeter(%val)
{
   lightMeter.setValue(%val);
}

And that's it! This has been a great exercise to get me back into game programming after a hiatus and I hope some of you find this useful in your own projects.

Thanks,
Ben