AI ownership balancing internals

1. Scope

The CBA setting FF_horror_aiBalanceMode selects All AI groups, FF Horror units only or Disabled (default). aiBalanceStart installs or removes the handlers; disabling leaves existing ownership untouched.

2. Discovery and transfer

A server per-frame handler runs every two seconds. It combines a queue filled by EntityCreated with a full group scan, which catches editor units, Zeus placements and groups created by other mods. Each pass moves at most two groups, keeps whole groups together, and enforces a 30-second cooldown for ordinary rebalancing. HC join and leave events bypass the cooldown so work can move immediately.

3. Weighting

The server has weight FF_horror_aiBalanceServerWeight (default 0.5) and each headless client has weight 1. The balancer compares living AI counts already owned by each worker and moves groups toward the lighter workers.

4. Exclusions

• Groups containing players, HC/virtual characters, logic groups.
• Groups with a pending flying arrival.
• Units whose group or unit variable FF_horror_aiBalanceExclude is true.
• Group-less agents, unless Include agents is enabled.

5. Pursuit after transfer

Horde units are revealed to living players again on the new owner (aiBalanceReveal), so pursuit does not stall after a locality change. Horde groups also wait briefly for more arrivals to preserve eight-unit grouping.

6. Requirements

Headless clients need playable slots, permission in server.cfg and the same relevant AI mods. The addon moves AI computation, not another mod's server-only script state.

Related functions

• FF_utils_fnc_aiBalanceStart — Starts or stops the opt-in server AI ownership service.
• FF_utils_fnc_aiBalanceTick — Server-side ownership balancer for AI created by any mission script or mod.
• FF_utils_fnc_aiBalanceReveal — Reapply horde target knowledge after an AI group changes locality.

↑ Back to top