From Mods Repository Wiki
Threat Bias Groups, as the name would imply, exist to create a rough order of threat for different groups in the level. This could be used to have the player take less fire in a massive line battle, in order to create a threatened group for a rescue/protect mission, or virtually anything else where you will want AI to favor one target over another in a non-hardcoded manner.
Creating A Thread Bias Group
To create a Threat Bias Group, just use the following line in gsc:
CreateThreatBiasGroup( "groupName" );
replacing groupName with whatever you would like to name your bias group.
Adding An Entity To A Threat Bias Group
To add an entity to a Threat Bias Group use the following line in gsc:
myEnt SetThreatBiasGroup( "groupName" );
with my ent corresponding to the entity you wish to add and the groupName a group created using the above listed function call.
Managing Your Groups
In order to get all of the entities in a Threat Bias Group, the following function can be used:
myArray = get_ai_group_ai( "groupName" );
Setting A Group Vs. Group Bias
Now that you have your groups and they are populated by the desired entities, you can set the bias of one group against another group. This is done with the following line:
SetThreatBias( "group1", "group2", #amount# );
Where #amount# is a value in the range [-2147483647, 2147483648]. This is the base threat of group1 against group2, which translates to how much entities in group2 will favor entities in group1. This is not communicative, in the sense that it is not necessarily the threat of group2 against group1. That value would have to be set using another call of SetThreatBias with "group2" as the first argument and "group1" as the second.
Now For The Fun Part
The amount specified in SetThreatBias is a base threat for an entire group of AI. Consider this a starting point for threat. From there, the game adds in several other factors to create the final threat value for a given AI. The factors that affect this base value are listed below, along with the min/max contributions of each.
- This is a value that can be set on an individual entity via script. This would be done in the following manner
myEnt.threatbias = #amount#;
- where #amount# is in the range [-2147483648, 2147483648]. These values are also, obviously the min/max amount for this factor.
- This measures how aware an AI is of the enemy in question. The value comes in four flavors: visible, fully aware, friendlyTimingOut (indicating that the enemy is the current target, but no longer visible) and not aware. The values assigned to each are visible = 1000, fully aware = 500, friendlyTimingOut = 250, not aware = 0. It is worth noting here that awareness is based on either the enemy being an entity's currently targetted enemy or a last known position, which is populated by either vision data or when the entity is attacked by the enemy.
- This is a comparative measure of accuracies between the weapons wielded by the entity and the enemy. The entity first adds an amount of threat based on the accuracy graph of the weapon at the current distance between the entities, then subtracts an amount of threat based on the entity's own weapon accuracy at the distance. The final value is clamped to an amount in the range of [-500, 1000].
- This value is separate from the Scariness. If the enemy is within 2500 units an amount of threat is linearly applied based on the actual distance compared to the max distance of 2500. This value will evaluate to a threat level in the range of [0, 5000].
- This value is based on the number of friendlies, not including the evaluating entity, that are attacking the enemy. The more friendlies that are attacking the enemy in question, the more of a negative threat is applied to the entity. It is statically applied at a rate of -150 threat per extra attacking friendly, capping at -1000. This gives a final range for this value of [-1000, 0].
- This is a static threat value added to an enemy based on whether it is the currently targeted enemy for the evaluating entity. The values for this evaluation are as follows: damaged player(fully aware) = 1000, current enemy (fully aware) = 500, current timing out enemy = 200, current enemy(not fully aware) = 100, not current enemy = 0.
- This is a threat value based on how suppressed an enemy is. If the enemy is dying, playing a pain animation or fully suppressed (and not in motion) this value is set statically to -3000. Otherwise, it will be 0. This is only added in if the enemy is within 256 units of the evaluating entity.
- Though not terribly relevant in our game at the moment, this is a value that is added based on whether the enemy is currently experiencing the effects of a flashbang. If the enemy is flashbanged, it adds a threat of 200, otherwise adds 0.
- Hopefully, understanding the mechanics of how threat is generated will help to coax the behavior out of your AI. If you need more information at runtime, debug threat data can be shown at runtime by setting the devgui Main->Entities->Entity Info to 2, 3 or 5 and entering the following command line option:
- This will display the following output. The selected enemy for the evaluating entity can be identified by the large green 'enemy' line at the bottom of the threat data.
- Finally, the base threat level, based on the output seems to be aimed at 7000 (Check the parenthesized values next to total threat to get an idea of an entity's threat vs this base value. If you find your values wildly divergent from this amount, it is likely that you are getting very specific behavior, so you may want to make certain that this is what you wanted from the feel of your level.
Sources: Treyarch's Wiki