NPC groups

For more detailed and technical information, check this page.

KAI NPCs have the optional ability to be put in groups, these groups can allow NPCs to behave as more coherent units. Groups are handled through the KAI_NPCGroup class and any of its' children. The library only handles the data management aspect of NPC groups (i.e cleaning up groups with no members, and firing group events). The NPCs have no built-in code on how to behave when actually in a groups. Allowing you to handle how your NPC groups should behave on your own, like if they should follow the group leader, what to do when a member dies, etc.

Below is a basic outline of most of the built-in features of NPC groups.

Accessing group data

There are three main methods that you can use to access data on groups:

1. For KAI NPCs, they have a Groups[] array that stores references to all the groups that NPC is currently a member of, allowing KAI NPCs to quickly access information like the the closest group member to them.
2. For non-KAI NPCs, they'll have a KAI_DataToken in their inventory (If they didn't have one before being assigned to a group), that also contains a Groups[] array that can be accessed to find what groups they're in.
3. For checking through all groups currently in the map, the NPCGroups map stored in KAI_EventHandler can be accessed directly to find any group on the map, the event handler also includes several search functions, such as finding all groups that share the same cosmetic name.

Custom NPC groups

Custom NPC groups can be made by inheriting from the base KAI_NPCGroup class. To customize the behavior of groups, KAI_NPCGroup has several virtuals that can be overridden to change behavior like how the group itself reacts to events, and what data is initialized while the group is being formed by CreateGroup(). CreateGroup() also has a GroupClass parameter you can use to have it create your own custom group class instead of the stock base class. And any groups can also be customized with no need for custom classes, by changing the groups' flags.

Group formation

Groups can be formed on the fly using the CreateGroup() function in ZScript, and the CreateGroupACS() function (Through ScriptCall()) for forming groups with ACS - such as for scripted sequences.

Group members

Any living NPC or player can be made a member of a group, non-KAI actors have group data stored and accessible through the KAI_DataToken item. However keep in mind that making non-KAI NPCs and players will require a hard dependency to the library. Members are also removed from the list automatically when they are destroyed (Erased from existence entirely).

Group events

NPC groups also have group events that are fired when a member joins, leaves, dies, is erased, is revived, or the leader is changed. The NPC group structure itself can react to those events through the HandleGroupEvent() virtual. Such as to make the group check any time a member joins, and assign whoever the current strongest member is as the leader. NPC groups by default also alert KAI NPCs of events through HandleNPCGroupEvent(), allowing NPCs to individually react to events like a member leaving.

Group icons

NPC groups show icons over the heads of members by default, these icons support graphics for non-leader members, the leader themselves, and an optional one if the member (Leader or not) is a player, along with dead variants of all those icons. The library also includes its own graphics for those icons as well. The icons also automatically update when any event occurs to the group, such as to change to the dead member icon if a member died.

The rendering of member icons can also be stopped entirely by passing the NPCGRP_NOICONS flag to the group.

CVARs and CCMDs

NPC groups also have a few commands for printing debug info about them. Such as a KAI_DebugPrintGroupEvents CVAR for making groups print info on every event that happened to them, i.e what member died, their pointer, and their class, and what group were affected. The library also has a KAI_GetTargetGroup CCMD that prints any groups that the actor in front of the player is in, if any, and all data about them.

See also

• KAI_NPCGroup