From TDN

Simple FPS Tutorial for Torque3D

Back to Part One: level design

Part TWO

Custom Weapons Art Scripts - SemiAuto:

Weapons in stock Torque3D come with a certain terminology.

"Weapon Item" = this is an ITEM that can be picked up. You need a "Weapon Item" before you can fire "Ammo". I am using the phrase "weapon item" to differentiate between an item which is not a weapon (like a healthpack).
eg: "rifle" is an item that can be picked up as a weaponItem.

"Ammo" = this is also an ITEM which can be picked up. You need "Ammo" to combine with a "WeaponItem".
eg: "rifleAmmo" is an item that can be picked up as ammuntion for a weapon.

"Image" = this is the term for the "WeaponItem" when it is "Mounted" (being held) on a player. This is the object which does the work for the "WeaponItem", it is NOT an ITEM.
eg: "rifleImage" is the working gun which the player has picked up the "weapon" item called "rifle".

"Projectile" = this is the BULLET which comes out of an "Image" when the player has "Ammo" to use.

Using only available assets in stock T3D, we are going to create 2 new weapons. The first will be a semi-automatic weapon (fires once each time the trigger is pressed) and the second will be a fully-automatic weapon (continues to fire with the trigger pressed down).

Firstly, let's collect the assets. The "Full Project" template only comes with one, so we will "borrow" another model from "Torque3D Pro etc/Examples/FPS Example/game/art/shapes/weapons" and copy the entire folder called "ramrifle", and paste it into your "Simple_FPS_Tutorial/game/art/shapes/weapons" folder.

You'll also need the accompanying artwork for the player's HUD/screen display. From "Torque3D Pro etc/Examples/FPS Example/game/art/gui/weaponHud" copy "ramrifle.png" and "reticle_ramrifle.png" into your "Simple_FPS_Tutorial/game/art/gui/weaponHud". Now you've got everything for 2 new weapons. That's the last we'll see of the FPS Example - so all further directory addresses will be inside your "Simple_FPS_Tutorial" project.

You can check out "Simple_FPS_Tutorial/game/art/datablocks/weapons/rocketlauncher.cs" to see how the stock weapon is set up. We're going to make a simpler version with no checks for underwater firing, and we'll also "pool" some of our assets between our 2 new custom weapons, such as particles and audio.

Create a new file with your favourite text editor or IDE called "semiauto.cs" and place it in "game/art/datablocks/weapons". Time to start scripting.

The stock rockets are little "explosive" and we want 2 weapons that use more standard bullets. Add this to your new semiauto.cs file.

// ----------------------------------------------------------------------------
// Normal-fire Projectile Object
// ----------------------------------------------------------------------------

datablock ProjectileData(semiautoProjectile)
{
   projectileShapeName = "art/shapes/weapons/SwarmGun/rocket.dts";
   directDamage = 25;
   radiusDamage = 0;
   damageRadius = 0;
   areaImpulse = 0;

   explosion = bulletImpact;
   waterExplosion = bulletWaterImpact;

   decal = bulletHoleDecal;
   splash = bulletSplashRingEmitter;

   muzzleVelocity = 100;
   velInheritFactor = 0.3;

   armingDelay = 0;
   lifetime = 2000; //(200 units range)
   fadeDelay = 1000;

   bounceElasticity = 0;
   bounceFriction = 0;
   isBallistic = false;
   gravityMod = 0.80;

   damageType = "bulletDamage";
};

The player has a maximum damage of 100, and desiring fun action and not realism, set the directDamage to 25, meaning it will take 4 hits to kill the player. RadiusDamage, DamageRadius, and areaImpulse are set to 0 as there is no explosion.

The effect of a bullet hitting something is the "explosion" and it will leave a bullethole as a "decal". The "muzzleVelocity" is the speed that it travels at (in units per second), and the "lifetime" is how long before it is deleted if it doesn't impact on anything first (in milliseconds). So here is a projectile that has a range of ... muzzleVelocity * lifetime / 1 second (1000 m/s) ... 100 * 2000 / 1000 = 200 units.

datablock ItemData(semiautoAmmo)
{
   // Mission editor category
   category = "Ammo";

   // Add the Ammo namespace as a parent. The ammo namespace provides
   // common ammo related functions and hooks into the inventory system.
   className = "Ammo";

   // Basic Item properties
   shapeFile = "art/shapes/weapons/ramrifle/debris.dts";
   mass = 2;
   elasticity = 0.2;
   friction = 0.6;

   // Dynamic properties defined by the scripts
   pickUpName = "semiauto Ammo";
   maxInventory = 20;
};

For the "Ammo" ITEM which becomes the projectiles, we'll use the debris located in the copied "ramrifle" folder. The maxInventory is how many the player will pick up if they touch this item (and have space in their own inventory to store it).

datablock ItemData(semiauto)
{
   // Mission editor category
   category = "Weapon";

   // Hook into Item Weapon class hierarchy. The weapon namespace
   // provides common weapon handling functions in addition to hooks
   // into the inventory system.
   className = "Weapon";

   // Basic Item properties
   shapefile = "art/shapes/weapons/ramrifle/base.dts";
   mass = 5;
   elasticity = 0.2;
   friction = 0.6;
   emap = true;

   // Dynamic properties defined by the scripts
   pickUpName = "semiauto Rifle";
   description = "semiauto Rifle";
   image = semiautoImage;

   // weaponHUD
   previewImage = 'ramrifle.png';
   reticle = 'reticle_ramrifle';
};

Next is the "Weapon" ITEM, the thing which the player will pickup so that they can use the weapon (if they have "Ammo" for it. We'll be using the ramrifle model, and also the accompanying weaponHUD images for it.

Finally, we have the "Image" for the weapon, the object that the player will actual hold and that fires the projectiles.

// ----------------------------------------------------------------------------
// Image which does all the work. Images do not normally exist in
// the world, they can only be mounted on ShapeBase objects.
// ----------------------------------------------------------------------------

datablock ShapeBaseImageData(semiautoImage)
{
   // Basic Item properties
   shapefile = "art/shapes/weapons/ramrifle/base.dts";
   emap = true;

   // Specify mount point & offset for 3rd person, and eye offset
   // for first person rendering.
   mountPoint = 0;
   offset = "0.0 0.0 0.1";//"0.0 0.085 0.09";
   //rotation = "1 0 0 -20";
   eyeOffset = "0.25 0.4 -0.4"; // 0.25=right/left 0.5=forward/backward, -0.5=up/down

   // When firing from a point offset from the eye, muzzle correction
   // will adjust the muzzle vector to point to the eye LOS point.
   // Since this weapon doesn't actually fire from the muzzle point,
   // we need to turn this off.
   correctMuzzleVector = false;

   // Add the WeaponImage namespace as a parent, WeaponImage namespace
   // provides some hooks into the inventory system.
   className = "WeaponImage";

   // Projectile && Ammo.
   item = semiauto;
   ammo = semiautoAmmo;
   projectile = semiautoProjectile;
   projectileType = Projectile;

   // Let there be light - NoLight, ConstantLight, PulsingLight, WeaponFireLight.
   lightType = "WeaponFireLight";
   lightColor = "1.0 1.0 0.9";
   lightDuration = 200;
   lightRadius = 10;

   // Images have a state system which controls how the animations
   // are run, which sounds are played, script callbacks, etc. This
   // state system is downloaded to the client so that clients can
   // predict state changes and animate accordingly. The following
   // system supports basic ready->fire->reload transitions as
   // well as a no-ammo->dryfire idle state.

   // Initial start up state
   stateName[0] = "Preactivate";
   stateTransitionOnLoaded[0] = "Activate";
   stateTransitionOnNoAmmo[0] = "NoAmmo";

   // Activating the gun.
   // Called when the weapon is first mounted and there is ammo.
   stateName[1] = "Activate";
   stateTransitionOnTimeout[1] = "Ready";
   stateTimeoutValue[1] = 0.6;
   stateSequence[1] = "Activate";

   // Ready to fire, just waiting for the trigger
   stateName[2] = "Ready";
   stateTransitionOnNoAmmo[2] = "NoAmmo";
   stateTransitionOnTriggerDown[2]  = "Fire";
   stateSequence[2] = "Ready";

   // Fire the weapon. Calls the fire script which does the actual work.
   stateName[3] = "Fire";
   stateTransitionOnTimeout[3] = "WaitForRelease";
   stateTimeoutValue[3] = 0.5;
   stateFire[3] = true;
   stateRecoil[3] = LightRecoil;
   stateAllowImageChange[3] = false;
   stateSequence[3] = "Fire";
   stateScript[3] = "onFire";
   stateSound[3] = bulletFireSound;

	// semi automatic - must release trigger
	stateName[4] = "WaitForRelease";
	stateTransitionOnTriggerUp[4] = "PostFire"; 

   // Check ammo
   stateName[5] = "PostFire";
   stateTransitionOnAmmo[5] = "Reload";
   stateTransitionOnNoAmmo[5] = "NoAmmo";

   // Play the reload animation, and transition into
   stateName[6] = "Reload";
   stateTransitionOnTimeout[6] = "Ready";
   stateTimeoutValue[6] = 0.5;
   stateAllowImageChange[6] = false;
   stateSequence[6] = "Reload";
   stateEjectShell[6] = false; // set to true to enable shell casing eject
   stateSound[6] = bulletReloadSound;

   // No ammo in the weapon, just idle until something shows up.
   // Play the dry fire sound if the trigger iS pulled.
   stateName[7] = "NoAmmo";
   stateTransitionOnAmmo[7] = "Reload";
   stateSequence[7] = "NoAmmo";
   stateTransitionOnTriggerDown[7] = "DryFire";

   // No ammo dry fire
   stateName[8] = "DryFire";
   stateTimeoutValue[8] = 1.0;
   stateTransitionOnTimeout[8] = "NoAmmo";
   stateSound[8] = bulletFireEmptySound;

};

Again we're using the "ramrifle" model, so the weapon in the player's hands will be the same as the one they pickup.

Here we link into the above datablocks of "ammo = semiautoAmmo", "item = semiauto" and "projectile = semiautoProjectile".

This FSM script basically checks for ammunition and then allows the player to fire the weapon if there is any, or does something else (dryfire) if there isn't. Note "state[4] WaitForRelease", the script will stop until the player lets go of the fire button. eg: it's semi-automatic.

Save all of this in your "semiauto.cs" file.



Part Three: Custom Weapon Art Scripts - Fullauto