Liberi Developer Guide: Vitals Component
From EQUIS Lab Wiki
Contents |
Overview
The Vitals component should be added to any object which could potentially receive hits. If your object has anything which resembles "health" or "hitpoints", or if it needs to respond in a logical (not just superficial) manner to incoming collisions, then it probably needs a Vitals component. In brief, the Vitals component is responsible for the following important functions:
- Health tracking
- Hit response
Please see Scripts/Components/Vitals.cs for full details about the component.
Health
The Vitals component tracks its health at the current moment, and has a configurable maximum health value. You can access the health either as an absolute value or as a normalized ratio of the maximum health.
Life / Death
A Vitals component with zero health is considered to be "dead". You can subscribe to "death" events (health reaching zero), or "revival" events (health rising above zero again). You can also optionally automate the despawning of your object when it "dies".
Regeneration
A Vitals component can optionally regenerate its health automatically. This can enabled/disabled at any time, and the rate as well as granularity of regeneration are adjustable.
Hits
Hits can be applied to the Vitals component at any time. Hits are quite abstract, and can be used for anything - direct enemy attacks, environmental hazards, poison, artificial damage, harmless "bumps", suffocation, hunger, etc. By far, the most common type of hit is from direct physical contact, and the Hitter is used to automate this. In this case, you need simply have a foreign object with a Hitter that is able to hit your Vitals object - there is no need to invoke the API to apply damage. In all other cases, use one variation of Vitals.ApplyHit to apply hits. The VitalTag property is used in conjunction with Hitters to control precisely which Hitters affect which Vitals. See the Hitter page for more details.
Response
Incoming hits can be individually processed via the PreHit and OnHit messages. Any script on the same object as the Vitals can implement these methods to respond to hits. Each hit tells you: its "value" (the damage value which is subtracted from the target Vitals's health value if the hit is successful), where it happened, whether or not it is a fatal hit (will cause the target Vitals to lose all its health), the GameObject "responsible" for the hit, and other custom Jeli details. When responding to a hit in the PreHit handler, you can actually use the HitInfo.Cancel property to nullify the incoming hit before it happens. In this case, OnHit will never happen.
Redirection
Each Vitals component has the option to redirect all incoming hits to a different object. You can do this through the Vitals.RedirectHitsTo property. For example, if you have a boss character with individually moving body parts that are able to receive damage, instead of these body parts having their own health, you may wish to redirect all hits they receive to the central Vitals on the boss's root object. This can also be used to implement "proxy damage" battle mechanics found in many games.
Vulnerability
A Vitals component can be made invulnerable to all incoming damage at any time with the IsVulnerable property or the IsInvulnerable property. This is useful for things like shields, invincibility powerups, or cutscenes. Related to this is the HitTimeout property, which specifies a brief interval of temporary invulnerability after each hit received. Note that this does not affect the aforementioned vulnerability properties.
