ROKKITZ

Projectile behaviour pack

Rokkitz is a package of weapon projectile behaviours. It allows you to create rockets, grenades, cluster bombs, seeker missiles and whatever else suits your fancy. It also includes simple but functional FPS weapons inventory; and if that is not enough, Rokkitz projectiles can be easily used with UFPS system.

Even though the Rokkitz demo uses FPS mechanics, the projectiles themselves can work with any game: you can fire them from spaceships, planes, tanks, magic wands, in first person, third person, or overview perspectives - basically anywhere.

Rokkitz Overview

ProjectileComponentBase

Rokkitz Overview

The most important component in Rokkitz is Projectile. This script handles movement and collision detection, and send important events: Launch, Collision and Explode.

A Projectile can have a ProjectileSteering component attached. Its task is calculating projectile velocity each frame, to create more interesting movement than flying in a straight line. Examples of ProjectileSteering components are GravityMovement and HomingMovement.

You can attach more than one steering component to a projectile, but only one can be active at any given time.

Another kind of Projectile component is derived from ProjectileComponentBase. These scripts can handle projectile launch, collisions and explosion (explosion is different from collision, because it might be triggered by some other mechanism - like timed fuse). There is a number of components defined in Rokkitz, like ProximityFuse, TimedFuse, etc; and you can easily add your own.

The TargetableObject script is used to mark enemies, so that seeker missiles and proximity fuses know where to find them. It works in tandem with EnemyTrackerBase, which is used to find all enemies in some area.

WeaponInventory handles FPS-style weapon switching, while Weapon takes care of individual weapon’s animations, ammo, aiming, firing and reloading. The Launcher script actually spawns a projectile; you can have multiple Launchers on a single Weapon to fire many projectiles at once.

Other scripts included in the package are mainly there to run the demo scene: some simple UI management, and spawning/moving dummy enemies for you to shoot at.

A more thorough explanation of all scripts is in this manual next; be sure to also check the source code - it has lots of comments to help you understand what’s going on.

Rokkitz Scripts

Projectile

Projectile script is the foundation of a projectile. It handles movement, collision detection, and all parts of projectile lifecycle. Other components can add to it, but it’s the Projectile that makes them work.

The projectile lifecycle looks like this:

First, the projectile is launched. Its velocity is set to start value, and OnProjectileLaunch message is sent, so that other components can do whatever initialization they need.
Every FixedUpdate, the projectile is moved forward; where “forward” may be defined by the active ProjectileSteering component.
Projectile uses sweep test to detect collisions. This is better than relying on built-in PhysX collision detection, as sweep test never misses even very thin walls. It can still miss fast-moving small objects, but that’s not much of an issue in practice.
If a collision is detected, OnProjectileCollision message is sent, allowing any components to handle it. After that, Projectile itself can use one of predefined collision responses: stop in place, turn on Rigidbody physics, or explode (this is the default)
At some time (either due to a collision, or called by another component) explosion happens - which is to say, OnExplode message is sent. By default, the projectile GameObject is destroyed on explosion, and an explosion effect prefab is instantiated.
If a projectile has not exploded for some predefined time, it is silently destroyed - to prevent stray projectiles from littering the scene.

More on projectile collision: a projectile has two ways to define its shape. If it has a Rigidbody attached, then its shape (with whatever colliders it has) is used for sweep tests. Note that the Rigidbody itself would be switched to kinematic, so no physics would affect it and interfere with projectile movement. If there’s no Rigidbody, the projectile is considered a sphere with predefined radius (can be 0). In both cases, projectiles basically ignore Unity physics while flying, and only obey their own steering.

Projectile class may send three kinds of messages: OnProjectileLaunch, OnProjectileCollision, and OnExplode. The usual way to use them is attach a component derived from ProjectileComponentBase, which has virtual method for all of those. However, since the methods are called with SendMessage, any component that has methods with these names defined will get called. Note that OnExplode (and only OnExplode) is also sent to children of projectile object.

Launching a projectile is normally handled by Launcher component (or UFPSAdapter). If you want to launch a projectile from your own code, you should do the following:

Create (instantiate) projectile object.
Point it where you want it to go, using transform.LookAt or something to that effect.
Call Launch()
Optionally, call SetAim(). This is only actually useful for homing projectiles.

Projectile class has some properties to fine-tune its behaviour:

StartSpeed is the starting speed of the projectile. If no steering component is active, it will fly forward with this speed; and if a steering component IS active, it should use this value as the base speed of the projectile.
MaxLifeTime is the time in seconds until projectile is destroyed (see point 6 in lifecycle)
AutoRotateToVelocity - if true, projectile will orient itself so that it points where it’s flying. This is useful for homing rockets etc; if false, the projectile will not change its orientation (but another component is free to do so)
CollisionRadius. If there’s no Rigidbody attached, the projectile detects collisions as a sphere with this radius. This radius also determines the position of projectile on collision (i.e. it is offset by CollisionRadius from whatever it collided with) - this happens even when a projectile uses Rigidbody for collision.
CollisionMask is the layers that can collide with this projectile. The collision matrix that you define in Physics setting does NOT affect projectiles, because they don’t use PhysX collision.
CollisionBehaviour defines what to do when the projectile collides with something. It has four possible values:

Nothing. Ignore collision. Presumably, some other component will do something, otherwise such projectile just flies through everything.
Explode. Explode and destroy projectile on collision. This is the default value.
Stop. Disable the Projectile script but do nothing more. Some other component should probably react to collision too, otherwise the projectile would just hang there forever.
Rigidbody. The same as Stop, but also turns on attached Rigidbody component. Can be used for bombs/grenades that bounce from surfaces. Note that after first collision, Projectile script will be switched off, and no more OnProjectileCollision messages would be sent - any further collision would trigger OnCollisionEnter as normal. In essence, the projectile stops being a projectile, and just become a generic physics object.

DestroyOnExplosion. If true, the projectile gameobject is destroyed in OnExplode. Set this to false if you want one projectile to explode multiple times, but don’t forget to destroy it yourself.
ExplosionPrefab is instantiated when OnExplode is called. Use this for explosion effect.

ProjectileSteering

ProjectileSteering is the abstract base class for components that steer projectiles. Inheriting classes are meant to override CalculateVelocity method. This method is called each FixedUpdate to calculate projectile velocity for that frame.

Another useful method to override is SetAim. This one is called to set projectile target for homing behaviours.

Only one ProjectileSteering component can be active at any time; but you can change which one is at any time. One way to do that is integrated into ProjectileSteering itself: the ActivationDelay property defines time, in second, before this component is activated. Using it, you can create a timed “stack” of steering behaviours. For example, a projectile that flies forward for 0.3 seconds, then starts homing on target, and after 5 seconds falls down, running out of fuel.

Rokkitz contains three predefined ProjectileSteering classes: GravityMovement, HomingMovement and TumblingMovement.

GravityMovement

This is a steering component that adds gravity to projectiles, making for a parabolic trajectory. It has one property, which is the gravity force. The gravity force is always pointed along world down axis (Vector3.down) and does not depend on projectile mass (if it even has one)

HomingMovement

This component steers the projectile towards a target. It depends on having a target, that must be set by calling SetAim on the projectile when HomingMovement is active (or just directly on HomingMovement component) If the target is not set, the projectile just flies in a straight line.

HomingMovement has one property, AngularTrackingSpeed, which is maximum turning velocity when homing, in degrees per second.

TumblingMovement

TumblingMovement component makes a projectile go sideways in random direction, with optionally spinning, and then gradually righting itself. It looks cool when launching multiple projectiles at once. TumblingMovement is controlled by several properties:

TumbleAngularVelocity spinning speed in degrees per second
OnTargetAngularVelocity turning speed when righting the projectile back on target
LaunchSpeed the sideways movement speed (Projectile.StartSpeed is used for forward movement)
LaunchTumbleAngle angle (in degrees) to deviate from launch direction at start.
TumbleTime time in seconds to spent tumbling. Another TumbleTime is then spent on reorienting to launch direction, so after 2*TumbleTime seconds this projectile flies straight.

ProjectileComponentBase

This is an abstract base class for generic projectile components. It defines three virtual method to override in derived classes: OnProjectileLaunch, OnProjectileCollision and OnExplode.

EnemySeeker

This component looks for enemies in front of the projectile and aims at them (calling SetAim). It does not do any steering, and so requires HomingMovement or similar component that actually uses aim target. Enemies to look for are obtained using EnemyTrackerBase.

EnemySeeker has the following properties:

Delay in seconds before seeking starts.
Radius - maximum distance to look for targets
MaxAngle - maximum angle to target. Combined with Radius, defines a cone in front of the projectile where EnemySeeker looks for targets.
CheckPeriod - delay in seconds between target checks. Used to improve performance by not looking for possible targets every frame.
LoseIfAngleMoreThanMax. If true, target can be lost if it ever moves out of seeking cone.

ProjectileSplit

Creates a number of secondary projectiles on explosion. Use this for cluster bombs etc.

Split is controlled by following properties:

ProjectilePrefab is the projectile to spawn
MinCount and MaxCount define how many projectiles to spawn
SplitDirection defines principal direction for split. Spawned projectiles will deviate for some angle from this direction (see image)
MinSplitAngle and MaxSplitAngle define minimum and maximum split angle - i.e. how much to deviate from principal direction.
SpreadEvenly. When true, spawned projectiles will spread evenly in a circle around principal direction. If false, they’ll fly out randomly.

ProximityFuse

ProximityFuse keeps track of enemies nearby and explodes when the projectile is closest to one. (Or, alternatively, the moment an enemy appears close enough.) It uses EnemyTrackerBase to track nearby enemies.

ProximityFuse is controlled by following properties:

ArmOnCollision. Whether to start tracking enemies immediately or only after collision (the latter would turn the projectile into some sort of thrown mine).
ArmingDelay. Delay in seconds before starting enemy tracking.
TrackingRadius. Only enemies closer than this are tracked.
ExplodeImmediately. If true, the projectile would explode immediately when an enemy is detected; otherwise, it waits until the enemy is closest.
UpdateTargetDelay. Delay in seconds between new target checks. Used to improve performance by not checking every frame.

TimedFuse

This component explodes the projectile after a set delay. It has two properties:

ArmOnCollision. If true, timer only starts on collision.
Delay in seconds before exploding.

UFPSAdapter

This component should be used with UFPS package. If you want to fire a Rokkitz projectile from a UFPS gun, just add this script and use projectile as usual with vp_WeaponShooter. The adapter will “pretend” that the projectile was launched from Rokkitz Launcher and call all necessary methods.

DamagingExplosion

This component damages all DamageableObjects in radius when the projectile explodes. It’s quite basic, and should be used as a template for your own one, rather than directly (although it may be enough for a simple game). DamagingExplosion uses EnemyTrackerBase to find objects to damage, meaning it will only affect objects that also have TargetableObject attached.

DamagingExplosion has the following properties:

Damage is the damage to deal.
PushImpulse is the physics impulse to add to a ragdoll, if one is spawned
ExplosionRadius is max distance to enemy to be affected (their centers must fall within the radius)
AffectedLayers is the obstacles layer mask: if an obstacle is detected by raycast between explosion and target, that target is not affected.

DetachOnDestroy

This is a simple script that detaches its GameObject from parent when OnExplode is called. It’s used for rocket trails, so that they don’t disappear immediately when a rocket explodes, but linger for some time.

TargetableObject

Marks an object as a possible target for projectiles. Marking is achieved by registering in EnemyTrackerBase object that must exist in the scene (one gets created automatically if none is found). TargetableObject has a single property (not visible in inspector) that defines its center - i.e. the point where the projectile should aim. By default, it’s the center of first attached collider; or simply transform position if no collider exists (though that’s strange for a TargetableObject to have no collider - you wouldn’t be able to hit it without one! - it’s still allowed).

EnemyTrackerBase

This script keeps track of all TargetableObjects in the scene, and can find all of them in a giver radius. It’s meant to be a singleton, and is automatically created if none is found.

You can inherit from EnemyTrackerBase and create your own tracker in the scene, if you need some advanced tracking algorithms. The default one would work OK as long as you don’t have too many (over a hundred) enemies in the scene at the same time.

DamageableObject

This script handles being damaged and destroyed. It only has the most basic functionality: a hit points counter that is decreased when damage is dealt. when HPs reach 0, the object is destroyed, and optionally replaced with a ragdoll prefab.

DamageableObject is too basic for any but the most simple games, and should be used as a template for your own, more advanced component.

Weapon

Weapon behaviour is a generic FPS weapon. It’s meant to be a part of WeaponInventory, but can be used without it. The behaviour handles animations, state changes, ammo spending and reloading, aiming and firing.

A Weapon can be in one of these states:

None: Weapon is not equipped. In this state weapon’s GameObject is supposed to be deactivated, so the script cannot do anything.
Equipping: Weapon is playing equipping animation. It is not yet ready to fire.
Idle: Weapon is equipped and ready to fire or reload
Firing: The trigger is pressed. It does not necessarily mean that the weapon is firing - it might be waiting to achieve preset firing rate.
Reloading: Weapon is playing reload animation, and ammo is added to clip.
Unequipping: Weapon is playing unequip animation

Current state is given by State property. It cannot be set directly, only through use of methods like Equip, Unequip, StartFiring and Reload - they take care of starting necessary animations and keeping everything consistent.

Weapon can animate both the weapon object itself (if it has an Animator component) and the player (i.e. player’s hands) - this requires setting up PlayerAnimator reference on the Weapon object.

Animations use triggers: EquipAnimTrigger, UnequipAnimTrigger, ReloadAnimTrigger and FireAnimTrigger. When respective state starts, this trigger is set on both the weapon’s and the player’s Animators - provided Animator exists and trigger name is not empty. For (un)equipping and reloading, the state ends when animation event OnEquipFinished (or similar for other states) is called by weapon Animator. Alternatively, you can set an EquipAnimDelay to automatically end the state after this delay passes.

Firing does not have FireAnimDelay, because this state ends when shot is fired (or for full-auto, when fire button is released). But there is FireAnimBool property that defines name for a bool parameter. It will be set to true in both animators whenever the weapon is in firing state - this is useful for full-auto weapons that shake or rotate barrels continuously while firing.

When aiming, weapon uses a raycast from player’s eyes - i.e. Camera - position. This camera can be set using PlayerCamera property; if not set, main camera would be used. You can also set crosshair position in case you don’t want aim at screen center.

AimRaycastLayers controls which layers this raycast would hit, and MaxAimDistance is raycast distance. The point where raycast hits an obstacle is the point where the weapon aims. Aiming does not rotate the weapon object in any way - instead, it just determines where the projectile would be facing at launch.

To simulate weapon inaccuracy, this firing direction can also be changed randomly whenever a projectile is fired. This sway is defined by AimSpread property. Its value is maximum distance that a projectile will deviate from target, if it travels 100 units from launch. In other words, when AimSpread is 1, and you fire at a target 100 units away, the projectile would hit some spot within 1 unit from the target.

When the fire button is pressed, Weapon switches to Firing state and launches projectile(s). Every weapon must have some Launcher objects attached to it; when firing, every Launcher spawns and shoots one projectile. The FireRate property limits firing rate to no more than FireRate shots per second.

ContinuousFire defines auto behaviour: when true, the weapon would fire continuously (obeying FireRate) as long as fire button is pressed; when false, the weapon would fire only once, and wait for the button to be released and pressed again.

Every shot spends AmmoPerShot ammo from the clip (it’s technically called magazine, but who cares.) Current ammo in clip is defined by CurrentAmmoInClip property, and CurrentAmmo give ammo reserves (excluding clip). MaxAmmo and ClipSize define maximum counts for reserves and clip, respectively.

Whenever reload is finished, Weapon takes ammo from CurrentAmmo and adds to CurrentAmmoInClip, up to ClipSize. Reloading can be triggered externally (via Reload method), or automatically when trying to fire with empty clip.

There are also two flags: InfiniteAmmo and InfiniteClip, to “cheat” and make a weapon that does not spend ammo or does not even need reloading.

WeaponInventory

WeaponInventory is a collection of Weapons that can be switched around. It’s meant to be attached to the player object, with Weapons as different s attached lower in hierarchy. Weapon switching is controlled by Next and Previous methods, which equip next and previous weapons respectively (in transform order). The list is cyclic, i.e. Next will switch last weapon to first.

WeaponInventory has two read-only properties, CurrentWeaponIndex and CurrentWeapon. Note that CurrentWeapon is not necessarily already equipped and ready to fire - it might be equipping, or even just waiting for previous weapon to unequip.

Launcher

Launcher script is responsible for actually creating and launching a projectile. It has a ProjectilePrefab property that defines what actually gets launched.