Liberi Developer Guide: Hitter Component

From EQUIS Lab Wiki

Overview

The Hitter component is used to automate the application of "hits" to an object with a Vitals component upon physical collisions between the Hitter and the Vitals objects. All hits received by a Vitals from a Hitter will indicate the Hitter as the source object of the hit. Examples of objects that could have Hitters are: swords, claws, spikes, pools of acid, projectiles, lightning bolts, lasers, lava. Unusual use case: collision regions for invisible attacks (like a sonic scream or a sleep wave). Note that Hitters do not necessarily have to do anything "harmful" - they could just as well be used for healing spells.

Basic Properties

• HitValue

This is the value of all outgoing hits. See the Vitals page for how this value is used.

• IsContinuous

This specifies whether or not this Hitter will apply hits continuously for the duration of each physical contact, or just upon initial contact. Set this to true for things like acid pools or prolonged laser beams. Set this to false for things like swords and projectiles.

• HitInterval

This specifies the interval at which hits are applied to targets if using continuous hits. For example, if an acid pool has this property set to 0.25, and HitValue is set to 5, it means that the acid pool will deal 5 units of damage once every quarter of a second (4 times a second), to any target which is currently touching it. Be careful when the Vitals component of the intended recipient of the hits has a Vitals.HitTimeout value that is higher than this property, since that would mean that only a portion of hits will actually succeed. See the Vitals page for details about the Vitals.HitTimeout property.

• TriggerHitLocationMode

This specifies the way in which the hit location is determined when using trigger colliders. Unity does not provide specific collision points for trigger collisions, so we need to make a guess ourselves. You have the option to define the hit location as the location of the Hitter at the moment of the hit, or the location of the Vitals receiving the hit, or as the midpoint between these two points. See the TriggerHitLocationMode enumeration in Scripts/Core/TriggerHitLocationMode.cs for details.

• HitTag / HitDetails

These two properties give you two alternate ways of providing additional information about outgoing hits to the target Vitals. The former, HitTag is simply a string. The latter is a UJeli object. The former is better for simplicity, while the latter provides much more flexibility for complex scenarios.

• TargetVitalTags

A list of "vital tags" which acts as a filter for outgoing hits. If this list is empty (the default), then hits will be applied to all Vitals components indiscriminately. If non-empty, then hits will only be applied to Vitals components whose VitalTag property is contained within this list. For example, you can give all friendly avatars a "friendly" vital tag, while giving all hostile mobs a vital tag of "hostile". Next, you can make all your avatar Hitters exclusively target the "hostile" tag, while making all your hostile mob Hitters exclusively target the "friendly" tag.

Shooter Relationship

A common scenario for objects with Hitters is that they are spawned by another object as a projectile or a trap. In this case, the spawning object can be said to be the "shooter" of the spawned object. For this scenario, the Hitter component offers a few convenient features:

Shooter Identification

If a Hitter finds a "Shooter" node in its spawn details (see the Sync Framework page for more info), it will automatically extract this value as a reference to its "shooter". The following code demonstrates how to spawn a cannonball from a cannon script and set the cannon object as the shooter:

var cannonballDetails = new UJeli();
cannonballDetails.AddChild("Shooter", gameObject);
Sync.Spawn("cannonball", barrelPos, barrelDir, 0, cannonballDetails);

Once the shooter is determined, it can be accessed via the Hitter.Shooter property. This returns null if there was no shooter. This makes it very easy, for example, for an object to find the cannon which shot the cannonball that hit it.

Shooter Protection

Sometimes, it may be desirable for shooters to be invulnerable to their projectiles, either temporarily or permanently. For example, cannons will most likely spawn cannonballs inside their barrels before pushing them out. In this instant, it is likely that the cannon and cannonball are actually in contact. It would be unfortunate if the cannon were to be immediately destroyed by the cannonball that it spawned. To prevent this, we can simply make it so that all cannonballs are harmless to their shooters. However, we might want to allow for the scenario in which a cannonball that was shot straight up into the sky can fall down and destroy its shooter. In this case, we would give the shooter protection effect a finite duration. Each hitter has a ShooterProtectionDuration property. If set to zero, the shooter is not protected. If set to float.PositiveInfinity, the shooter is permanently protected. If set to a positive, finite value, it is treated as the duration of the protective effect.