Okami AI Squads

Overview

Okami AI Squads automatically fills player squads with AI, keeps those AI attached to the squad command structure, and maintains follow behavior across deaths and respawns.

Core goals:

Keep squads combat-effective even on low-pop servers
Preserve commandability through the radial/command wheel flow
Scale down AI load as player count grows
Give server owners predictable JSON-based configuration

Typical behavior in-game:

A player spawns, receives AI up to configured limits, and can command them
On player respawn, living AI can teleport back and dead slots refill
If AI fall too far behind, stuck-teleport can recover them

Requirements

Arma Reforger 1.6+
Mod loaded on the server/session (server-authoritative behavior)

Configuration

On first run, the mod creates:

/profile/OkamiAISquads/Settings.json

If no file exists, defaults are generated and written to profile.

Default Config

{
  "squadSettings": {
    "desiredSquadSize": 4,
    "maxAIPerSquad": 3,
    "notifySquadLeadCommandHint": true,
    "squadLeadCommandHintMessage": "OKSQD-AI: You're squad lead of an AI team, by using the commanding wheel you can give orders to your team.",
    "aiFaction": "AUTO",
    "factionPrefabPools": [
      {
        "factionKey": "US",
        "randomizePerSpawn": false,
        "prefabs": [
          "{7A9E9F00710667C1}Prefabs/Characters/Factions/BLUFOR/USMC/Character_USMC_Rifleman.et"
        ]
      },
      {
        "factionKey": "USSR",
        "randomizePerSpawn": false,
        "prefabs": [
          "{B3C12E001A3400FF}Prefabs/Characters/Factions/OPFOR/USSR/Character_USSR_Rifleman.et"
        ]
      },
      {
        "factionKey": "FIA",
        "randomizePerSpawn": false,
        "prefabs": [
          "{A1D09B00567812DE}Prefabs/Characters/Factions/INDFOR/FIA/Character_FIA_Rifleman.et"
        ]
      }
    ]
  },
  "playerScalingSettings": {
    "enablePlayerScaling": true,
    "scalingMode": "REDUCE_AI",
    "playerThresholds": [
      { "playerCount": 1, "maxAIPerSquad": 3 },
      { "playerCount": 8, "maxAIPerSquad": 2 },
      { "playerCount": 16, "maxAIPerSquad": 1 },
      { "playerCount": 32, "maxAIPerSquad": 0 }
    ],
    "globalAICap": 128
  },
  "spawnSettings": {
    "spawnWithPlayer": true,
    "spawnOffsetRadius": 3,
    "initialFollowOrderDelayMs": 1500,
    "spawnOnRespawn": true,
    "teleportOnRespawn": true,
    "teleportOffsetRadius": 3,
    "waitForGroup": {
      "maxAttempts": 60,
      "intervalMs": 500,
      "allowCreatePlayableGroupIfNone": false
    },
    "aiAttach": {
      "initialDelayMs": 200,
      "staggerMsPerUnit": 100
    }
  },
  "respawnSettings": {
    "aiRespawnMode": "BEST_OF",
    "respawnDelaySeconds": 30,
    "maxRespawnsPerAI": -1,
    "nearObjectiveSettings": {
      "maxSearchRadiusMetres": 500,
      "mustBeOwned": true,
      "preferClosestToLeader": true
    },
    "nearMOBSettings": {
      "maxSearchRadiusMetres": 1000,
      "mustBeFriendly": true
    }
  },
  "followSettings": {
    "leaderRule": "SQUAD_LEADER",
    "forceOwnerAsGroupLeaderWhenSpawningAI": true,
    "followFormation": "WEDGE",
    "combatBehaviour": "FREE",
    "stuckTeleport": {
      "distanceMetres": 300,
      "checkIntervalSeconds": 10,
      "cooldownSeconds": 60
    }
  },
  "debugSettings": {
    "enableDebugLogging": false,
    "logSpawnEvents": true,
    "logTeleportEvents": true,
    "logRespawnEvents": true,
    "logScalingEvents": true
  }
}

Configuration Reference

`squadSettings`

`desiredSquadSize`

Total target squad size, including players + AI.
AI needed is based on this target minus current human members.

`maxAIPerSquad`

Hard cap of AI allowed per squad.
Final spawn count uses the lower of this and scaled AI cap.

`notifySquadLeadCommandHint`

Enables one-time private hint message after initial AI attach wave.

`squadLeadCommandHintMessage`

Custom message text for that hint.
If blank, fallback default message is used.

`aiFaction`

"AUTO": derive faction key from group/player faction.
Any other string: force that key for prefab pool lookup.

`factionPrefabPools`

List of faction-key -> prefab list mappings.
Entry fields:
- factionKey: must match Faction.GetFactionKey() (e.g. US, USSR, FIA)
- randomizePerSpawn: random pick when more than one prefab exists
- prefabs: array of .et prefab resource paths
If no matching pool is found, component AI Prefab Override is used.

Important behavior:

If this array is empty, the mod injects built-in US/USSR/FIA defaults.
As soon as at least one entry exists, your JSON effectively becomes authoritative.

`playerScalingSettings`

`enablePlayerScaling`

true: use threshold-driven cap logic.
false: use fixed maxAIPerSquad.

`scalingMode`

FIXED: always use squadSettings.maxAIPerSquad
REDUCE_AI: use threshold cap based on player count
RATIO: accepted as value, currently behaves with threshold pass logic; use playerThresholds to control outcome

`playerThresholds`

Ordered threshold list of player count to maxAIPerSquad.
Last matching threshold wins.
Empty list is auto-populated with defaults.

Default thresholds:

1+ players -> 3 AI
8+ players -> 2 AI
16+ players -> 1 AI
32+ players -> 0 AI

`globalAICap`

Maximum live AI tracked by the mod across all squads.
<= 0 disables cap enforcement.

`spawnSettings`

`spawnWithPlayer`

Present in config for behavior control compatibility; keep enabled unless testing custom flow.

`spawnOffsetRadius`

Radius around leader for new AI spawn scatter.

`initialFollowOrderDelayMs`

Delay after player spawn finalization before AI fill process starts.

`spawnOnRespawn`

Config field maintained for compatibility and future tuning; current refill logic is tied to spawn handling and respawn handler flow.

`teleportOnRespawn`

On player respawn, living AI warp near leader before refill.

`teleportOffsetRadius`

Radius used for respawn teleport placement around leader.

`waitForGroup`

maxAttempts: retries waiting for playable group assignment.
intervalMs: retry interval.
allowCreatePlayableGroupIfNone: create a playable group when none appears.

`aiAttach`

initialDelayMs: delay before first AddAIEntityToGroup.
staggerMsPerUnit: additional stagger delay per AI unit.

`respawnSettings`

`aiRespawnMode`

Supported values:

DISABLED: dead AI are not replaced
TIMED: replace after delay near leader
NEAR_OBJECTIVE: try objective spawn, then fallback to leader
NEAR_MOB: try MOB spawn, then fallback to leader
BEST_OF: objective -> MOB -> leader fallback chain

`respawnDelaySeconds`

Delay before replacement spawn.

`maxRespawnsPerAI`

-1: unlimited replacements
0+: cap per AI slot

`nearObjectiveSettings`

maxSearchRadiusMetres
mustBeOwned
preferClosestToLeader

`nearMOBSettings`

maxSearchRadiusMetres
mustBeFriendly

Current implementation note:

Objective/MOB search functions are currently stubs; these modes fall back to leader spawn in practice until query integration is added.

`followSettings`

`leaderRule`

SQUAD_LEADER: AI follow squad leader when valid
PLAYER_ONLY: AI follow spawning player entity

`forceOwnerAsGroupLeaderWhenSpawningAI`

Reasserts owner as leader during/after spawn window to preserve commandability.

`followFormation`

Formation preset requested for AI group.
Common values: WEDGE, LINE, COLUMN, STAGGERED_COLUMN, ECH_LEFT, ECH_RIGHT, VEE, DIAMOND.

`combatBehaviour`

Configured field for compatibility/expansion. Keep as default unless your downstream logic uses it.

`stuckTeleport`

distanceMetres: distance threshold (0 disables stuck teleport)
checkIntervalSeconds: follow tick interval
cooldownSeconds: min delay between teleports per AI

`debugSettings`

`enableDebugLogging`

Master debug output switch.

`logSpawnEvents`, `logTeleportEvents`, `logRespawnEvents`, `logScalingEvents`

Fine-grained log categories.
Useful during tuning or game-mode integration.

Data Validation and Auto-Correction

Missing nested config blocks are auto-created on load.
Empty threshold list is auto-filled with defaults.
Empty factionPrefabPools gets default US/USSR/FIA entries.
Bool serialization is normalized to true/false when writing profile config (avoids 0/1 output noise).

Gameplay Notes

AI attach is done through the playable group’s command slave when available (for commanding wheel compatibility).
If slave linking delays due to replication timing, retries run automatically.
If player/group ownership changes shortly after spawn (other systems/mods), ownership is reasserted briefly.
Group attach failures often indicate wrong prefab family (use playable squad AI-compatible character prefabs).

Recommended Tuning Profiles

Low-pop PvE / Co-op

desiredSquadSize: 4
maxAIPerSquad: 3
globalAICap: 128+
stuckTeleport.distanceMetres: 250-350

Mid-pop mixed servers

Keep defaults; tune thresholds to reduce AI faster after 12-20 players.

High-pop PvP-heavy

Lower globalAICap (for example 64)
Set threshold to reach 0 AI earlier (for example at 24 players)
Consider respawnSettings.aiRespawnMode: DISABLED if performance is priority

Troubleshooting

Issue	Things to check
Spawn waits forever for group	Increase `spawnSettings.waitForGroup.maxAttempts` or enable `allowCreatePlayableGroupIfNone`.
AI spawn but cannot be commanded	Check logs for slave-link warnings.
AddAIEntityToGroup fails	Use AI-compatible prefab family (Conflict/Campaign recruit-like prefabs).
Wrong faction prefab used	Verify `factionKey` matches exact runtime faction key and `aiFaction` override behavior.
Too many AI on busy server	Tune `playerThresholds`, reduce `maxAIPerSquad`, and/or lower `globalAICap`.
AI teleport too often / not enough	Tune `stuckTeleport.distanceMetres`, `checkIntervalSeconds`, and `cooldownSeconds`.
Config edits not applying	Edit while server stopped, keep strict JSON, restart session.
Config file not created	Ensure profile path is writable and run once with mod enabled.

Known Limitations

Objective and MOB spawn lookup is placeholder logic in current build.
Vehicle-follow behavior depends on vanilla AI pathing reliability.
Some fields are included for compatibility/future extension and may not fully alter runtime yet (combatBehaviour, parts of spawn behavior toggles).

Compatibility

Arma Reforger 1.6+
Designed to work across scenarios/game modes, with best results when group + commanding components are present

Links

Download Arma Reforger Workshop Join Support Discord

Overview

Requirements

Configuration

Default Config

Configuration Reference

squadSettings

desiredSquadSize

maxAIPerSquad

notifySquadLeadCommandHint

squadLeadCommandHintMessage

aiFaction

factionPrefabPools

playerScalingSettings

enablePlayerScaling

scalingMode

playerThresholds

globalAICap

spawnSettings

spawnWithPlayer

spawnOffsetRadius

initialFollowOrderDelayMs

spawnOnRespawn

teleportOnRespawn

teleportOffsetRadius

waitForGroup

aiAttach

respawnSettings

aiRespawnMode

respawnDelaySeconds

maxRespawnsPerAI

nearObjectiveSettings

nearMOBSettings

followSettings

leaderRule

forceOwnerAsGroupLeaderWhenSpawningAI

followFormation

combatBehaviour

stuckTeleport

debugSettings

enableDebugLogging

logSpawnEvents, logTeleportEvents, logRespawnEvents, logScalingEvents