Plastic Gem #26: Zapper Power Meters

Download Code File




Plastic Gem # 26: Zapper Power Meter

Difficulty: Easy

Before following this gem, you must follow the instructions in the previous gem,Gem #2, Gem #25, and optionally Gem #3 if you want ease, which you do.

The Zapper Power Meters go down as energy drains

Hi Paul Dana from Plastic Games again. As Jason promised I am here to explain how to turn this Zapper shape with it's animation threads into a functional game object using the animation improvements in Gem #2 (and optionally Gem #3).

1) Unzipping the files

Remember you must first follow the instructions in Gem #2, Gem #25 (and optionally Gem #3). This will give you the thread upgrade and the zapper shape itself. Next unzip the pg26_zapperPowerMeter.zip. In there you will find a script file called zapper.cs that defines the PlasticZapper as well as a file called zapper.max.

2) The .max file from the previous gem

As Jason promised we have also included the .max file that would not fit into the .zip file for Gem #25. After you unzip copy the zapper.max file to the zapper folder you copied in the previous gem. It will sit right next to zapper.dts and the rest of those files.

3) Executing the script

Edit the file ~/server/scripts/game.cs. Find the function called onServerCreated(). In there you will see lines of code that execute scripts. Here we need to execute the script we added. After these lines:

exec("./crossbow.cs");
   exec("./environment.cs");

add a line like this

// > pg zapper
   exec("./zapper.cs");
// < pg zapper

4) Testing it out

Edit a mission and place a PlasticZapper object using steps similar to those described in Gem #1 and Gem #2, etc on placing a shape. Also using instructions similar to those in Gem #1 and Gem #2 give the object the name Zapper.

Once you have a PlasticZapper object placed and named Zapper you can change the power level and see that reflected in the power meter gauages. Use the tilde key (~) to show the console. Type this:

Zapper.setPower(30).

See how the needle on both gauges jumps down to 30, as depicted below...




Now see how the gauges jump up to 75, as depicted above, when you type this:

Zapper.setPower(75);

5) Looking at the code

In the fan example from Gem #18, I just gave you a dump of ALL the code to make the fan work without describing how it all actaully worked. For the PlasticZapper object I am going to build up the functionality a bit at a time and try to explain a bit more what is going on as well. Let's take alook at the code in zapper.cs.

First we have the definition of the PlasticZapper shape and the ::onAdd() method. This should already make sense from the examples in Gem #1 and Gem #2.

datablock StaticShapeData(PlasticZapper)
{
    category		     = "Plastic";
    shape                             = "~/data/shapes/zapper/zapper.dts";
 	     
    maxEnergy                      = 100; // we use this to keep track of battery energy
    rechargeRate                   = 0; // we don't recharge at all...
};

function PlasticZapper::onAdd(%this,%obj)
{
  // make zapper 1/4 size...
  if (%obj.scale $= "1 1 1")
     %obj.setScale("0.25 0.25 0.25");
    
  // we use thread 0 for the mechanical arm...
  %obj.playThread(0,"activate");
  %obj.stopThread(0);
  
  // .. and thread 1 for the power meter gauge
  %obj.playThread(1,"ifl_gauge");
  %obj.pauseThread(1);
  
  // call top level method to set energy level & meter at once...
  %this.setPower(%obj, %this.maxEnergy);
}

The datablock defines the code is what you would expect. The gems from last week on energy described the maxEnergy field which we set to 100 and also the rechargeRage which we set to zero. The idea is a Zapper has so much power to give and when you drain it down then it is empty.

The code to run some threads should also make sense given the previous gem that explains the Zapper shape and the animation threads on it.

Finally we call a new method setPower() that sets a given amount of energy on the object and also updates the power meters to visually match.

// set the power for this zapper...this sets the energy level and then
// udpates the power meter IFL to match...
function PlasticZapper::setPower(%this,%obj, %power)
{
  %obj.setEnergyLevel(%power);
  %this.setPowerMeter(%obj, %power);
}

OK so the defintion of this new setPower() method is pretty straight forward as you can see.

// set power meter to a given value in range 0...maxEnergy
function PlasticZapper::setPowerMeter(%this,%obj, %power)
{
   %max = %this.maxEnergy;
   
   // update thread according to energy
   %obj.setThreadPos(1,1.0-(%power/%max));
}

// update the power meter to reflect the current energy
function PlasticZapper::updatePowerMeter(%this,%obj)
{
   %energy = %obj.getEnergyLevel();
   %this.setPowerMeter(%obj, %energy);
}

Similarly the methods to set the thread position based on a value should be familiar from the Clock example and the energy methods shoudl be familiar from last week gems.

// NOTES: 
// remember that util methods are a way to call the methods defined in the datablock namspace
// as if they were in the namespace of the object itself...they just redirect to the datablock
// they are useful but also dangerous in that if you change parameters in your method in the datablock
// namspace you must always keep the util methods up to date. Note also that util methods only
// expose the "top level" methods we intend to use from script...

// UTIL methods on object itself

function StaticShape::setPower(%this, %power)
{
   %this.getDataBlock().setPower(%this, %power);
}

Finally we have a util method of a type we have pointed out in previous gems. The idea here is we can call the setPower() method on the zapper object itself rather than the datablock. You were using this method in the previous step when issuing commands like Zapper.setPower(30).

The Next Gem

That's all for this gem. Tomorrow's gem will show how to add a classic "Tesla Coil" effect between the two knobs in the Zapper shape.