Attention Modders!
With many major changes recently released in our 1.1.0.8 Experimental Update and more on the way, we wanted to provide modders with some important information about changes regarding our damage system.
The damage system is used in many aspects of Arma Reforger; it's an important pillar of the Arma equation, and its use is of high importance to modding. As such, it's crucial that the upcoming changes and additions to the damage system are well-known and understood, along with the reasoning behind them. The upcoming changes are, for the most part, performed on damage managers (and multi-phase destruction, by extension), leaving destructible entities and other types of entities unaffected by such changes.
In this modding update, you will understand the problems that were faced, what was done to resolve them, and the most important changes to consider.
Upcoming Changes
Removal of the HitZoneContainerComponent as a Standalone
As an initial goal, the HitZoneContainerComponent had a lightweight implementation (in comparison to damage managers) that could contain HitZone instances. The aforementioned HitZone instances would be dealt damage by the damage managers in the parents in the hierarchy. This created an extra complexity at the moment the entity was to be separated from its hierarchy. In order to understand more easily the problem, let's go with an example:
There is a vehicle with a DamageManagerComponent on it, and the wheels have a HitZoneContainer on them. If the wheels were to be detached from the vehicle, then no damage could be dealt to the wheels, given that no damage manager is present on the parent hierarchy of the wheels.
The memory saved by keeping the HitZoneContainerComponent was not enough to justify the increased complexity of the situations that could arise, so the support for standalone HitZoneContainerComponents was removed (i.e. you can no longer inherit from them), meaning that in order to use HitZones, it should be done through DamageManagerComponent.
Making every DamageManagerComponent independent from one other
Usually, the topmost DamageManagerComponent of a hierarchy would be the one applying the damage to all HitZones of the hierarchy. This was mainly to support HitZoneContainerComponents, but without them, this kind of logic has no reason to exist. As a result, HitZones can only take damage from the DamageManagerComponent that contains them.
Streamlining of Classes
Another common trend with the damage system was the abundance of classes and inheritance, which created confusion over which classes should be used and when, so some of them were removed to make getting started with the damage system easier.
Changed classes:
Merged ScriptedDamageManagerComponent and SCR_DamageManagerComponent
Some of the ScriptedHitZone functionality was moved to HitZone
HitZoneContainerComponent is now sealed
Renamed ScriptedHitZone to SCR_HitZone
Renamed SCR_DestructionBaseComponent to SCR_DestructionDamageManagerComponent
Removed classes:
SCR_HitZoneContainerComponent
SCR_HitZoneContainerComponentClass
BaseScriptedDamageManager
ScriptedDamageManagerComponent
Remember to update your prefabs and scripts to use the proper classes now!
Prevention of Incorrectly set up Prefabs
Measures to prevent issues caused by improperly set up prefabs were introduced:
The RplComponent is now a requirement for DamageManagers, otherwise the DamageManagerComponent will not be added to the entity.
Along with some warning messages, a visual indicator has been added for the most common setup errors:
A DamageManager has no HitZones.
A DamageManager has no HitZone marked as default.
If a DamageManager has no HitZones, the entity will not be spawned in the world.
A visual example of a wrong set-up prefab.
New Classes: BaseDamageContext and SCR_DamageContext
If you've been working with damage, you have probably realized that some functions take the same parameters over and over again: ComputeEffectiveDamage, OnDamage, HandleDamage. As a result, all of these parameters are grouped into one class now: DamageContext. The goal is to reduce the number of parameters that get passed around for those functions, and if the need for new parameters is met, then it can be done without breaking every mod.
SCR_DamageContext is just used for its constructor. Important things about this:
Now that classes are passed to functions like ComputeEffectiveDamage, the changes made to the variables of the class mean that it will no longer be made in copies, so extra care should be taken when changing the values.
There is currently no support for custom variables inside a DamageContext, as it was not developed with that feature in mind.
New Method: ShouldCountAsHit
Whenever we require randomness to be involved in the decision of whether something takes damage or not, the best place to do that before was in ComputeEffectiveDamage, but that meant that randomness would be involved in both the initial hit and consequent damage calculations. This function is designed to solve this problem.
New Method: SCR_HijackDamageHandling
ComputeEffectiveDamage is supposed only to be used to calculate how much damage has to be applied, but because of its versatility, it ended up being used for things like damage pass rules. HijackDamageHandling is intended to solve that problem. It gets called BEFORE damage handling even begins and gives the user almost total control over it. It's the safest place to modify the DamageContext. It also allows for the damage to be discarded, so things like redirection of damage can also be implemented here.
New Methods: GetHitZoneByColliderID and GetHitZonesByColliderIDs
Relatively self-explanatory methods that should help with finding HitZones attached to colliders.
Changes for Future Updates
Sadly, this first Experimental update doesn't contain all the changes that we would have liked. However, here are some things you might see in future updates:
Updating our own scripts to use ShouldCountAsHit and SCR_HijackDamageHandling
We tried to get these functions out as soon as possible, and as a result, we haven't yet been able to update our own scripts to use these functions.
Renaming SCR_HijackDamageHandling to HijackDamageHandling
Unfortunately, mistakes happen from time to time, and we gave the function the wrong name for this first Experimental update. In future Experimental updates, it will be called HijackDamageHandling.
GetAllHitZones and GetAllHitZonesInHierarchy
Until now, GetAllHitZones would return all HitZones in the hierarchy, but many times, we just wanted the HitZones contained inside of the DamageManager itself. Now that we are making DamageManagers independent from each other, there is very little reason to keep that as the default behavior.
So we are changing GetAllHitZones to return only the HitZones contained inside of the DamageManager it's being called. If you want to make sure it behaves exactly like before, use GetAllHitZonesInHierarchy instead.
New Function: ComputeStruckHitZones
This new function will fill an array with a list of the HitZones that should get damaged by a DamageContext. It's made to help when trying to deal damage to HitZones attached to a specific collider ID. While similar to GetHitZoneByColliderID and GetHitZonesByColliderIDs, this method will return the default HitZone if no HitZones were attached to those colliders.
Items on the Horizon
This is not the full extent of the things we have in mind for the damaged system's moddability, but we can still share some of the things that we plan to change.
Changes in Collisions
We plan to make some changes to the collision callbacks for DamageManagers and how they work.
Fall Damage
We want to make fall damage easier to modify with a fall damage callback.
Custom Damage Types
We understand this is something important, but currently, we are aiming for bigger systematic changes that, if delayed, would affect more mods.
As always, if you have any further questions or issues, we recommend you visit our forums and official Discord Arma Platform, where fellow community members and developers might be able to assist you.
Be sure to also read up on our last Modding Update regarding entity-class changes!
