ai

Server

modkit.ai spawns AI creatures, counts them and gives them a brain of your own. Every spawn creates a pawn and a matching AI controller, lets the controller possess the pawn, fills its stats and registers it with the game's AI world spawner.

The first spawn of a class may load the blueprint from disk on the game thread. That can cause one short hitch. Later spawns of the same class are fast.

The first half of this page covers spawning and counting. The second half, from Brains on, covers custom AI. The custom AI guide walks through it step by step.

modkit.ai.species

modkit.ai.species()

Returns: array of the 39 keys that spawn accepts, all lower case. Dinosaurs such as "tyrannosaurus", "carnotaurus", "psittacosauruscoastal", animals such as "boar", "deer", "goat", "rabbit", "chicken", "crab", "bullfrog", "lizard", "seaturtle", and the fish schools "rainbowfish", "coalacanth", "muskelunge", "longear".

print(table.concat(modkit.ai.species(), ", "))

modkit.ai.spawn

modkit.ai.spawn(species, x, y, z [, options])

Returns: array of integer handles, or nil and a reason. Reasons are "unknown AI species", "unknown brain", "AI class could not be loaded", "too many script spawned AI alive (limit 500)", "spawn failed".

modkit.commands.add("boars", function(player)
  local x, y, z = player:pos()
  local ids, why = modkit.ai.spawn("boar", x + 800, y, z, { count = 3, behavior = "passive" })
  player:message(ids and (#ids .. " boars spawned") or why)
end, true)

modkit.ai.despawn

modkit.ai.despawn(handle)

Returns: true when the creature was still there and got destroyed. Fires aiDespawned with the reason "script".

modkit.ai.list, count

modkit.ai.list() returns the creatures with a handle that still exist, as tables with id, species, alive, x, y, z. These are the creatures your scripts and spawners put into the world, plus every wild animal a brain took over. A dead creature stays in the list until the game removes its body. modkit.ai.count() returns the length of that list.

for _, a in ipairs(modkit.ai.list()) do print(a.id, a.species, a.alive) end

modkit.ai.census

modkit.ai.census()

Counts every AI controlled character in the world, including the game's own AI.

Returns: a table species -> count and the total as second value.

This walks all game objects. Call it on demand, not in a timer that runs every second.

local counts, total = modkit.ai.census()
print("AI in the world: " .. total)

modkit.ai.wipe

modkit.ai.wipe()

Destroys every AI controlled character in the world, the game's own AI included. The game spawns new AI afterwards as usual.

Returns: number of destroyed creatures. Walks all game objects.

Brains

A brain describes how an animal senses, moves, picks targets, fights, flees, behaves in a group and when it disappears. An animal with a brain keeps its body, its pathfinding and its attacks from the game. The game's own decision making for that animal is switched off and the brain decides instead. Taking the brain away gives the animal back to the game.

There are three ways to put a brain to work.

Brains come from two places. The Server Tool writes data\ai\brains.json and data\ai\spawns.json under the server root. Scripts define brains with modkit.ai.defineBrain. A brain from a script replaces a file brain of the same name while the server runs. The file stays as it is. The plugin looks at both files every 5 seconds and loads them again when they changed.

Brain names and spawner ids have 1 to 32 characters from a-z, 0-9 and _.

Units

Distances are Unreal units, 100 units are 1 m. Times are seconds. Shares and chances go from 0 to 1. Angles are degrees. Species names are compared without regard to case and punctuation.

Brain fields

Every field is optional. A missing field has its default.

senses

movement

targets

temperament

attack

An entry of attack.abilities is { name = "bite", weight = 1, minRange = 0, maxRange = 0, cooldown = 0 }.

Before each attack the brain collects every ability whose distance window fits and whose cooldown is over, then picks one at random by weight.

pack

idle is a list of up to 16 entries { ability = "roar", minSeconds = 60, maxSeconds = 240, onlyAlone = false, whenBusy = true }. The animal uses the ability at a random moment between minSeconds and maxSeconds, again and again. onlyAlone waits until no player is in sight range. whenBusy = false limits it to the roam state. Defaults are 60, 240, false and true.

stats

despawn

States

An animal with a brain is in one of six states. The names are part of the API.

How often a brain thinks

The distance to the nearest player sets the pace.

In chase the interval is 0.1 s. In flee and scripted it is 0.5 s at most. The distance is checked once per second, so an animal far away picks up speed within a second when a player comes close.

All brains together get 2 ms per server tick. What does not fit waits for the next tick. At most 500 animals can have a brain at the same time. Beyond that setBrain returns false, spawners with a brain stop filling up and further wild animals stay with the game's AI.

modkit.ai.defineBrain

modkit.ai.defineBrain(name, definition)

Returns: true. An unknown field, a wrong type, a value outside its range or a bad name raises a Lua error that names the field.

Defining a name again replaces the brain. Animals that already run on it use the new values from their next think step.

modkit.ai.defineBrain("night_stalker", {
  label = "Night stalker",
  preset = "predator",
  senses = { sightRange = 9000, sightAngle = 200 },
  movement = { roamRadius = 12000, leash = 20000 },
  targets = { minGrowth = 0.3 },
  temperament = { aggression = 0.8, fleeFromBigger = false, activeAt = "night" },
  attack = { abilities = { { name = "bite", weight = 3 }, { name = "claw", weight = 1 } } },
  pack = { size = 2 },
})

modkit.ai.getBrain, brains

modkit.ai.getBrain(name) returns a table with every brain field filled in, defaults included, plus name and source ("lua" or "file"). It returns nil for an unknown name. Callbacks are not part of the table.

modkit.ai.brains() returns the names of all brains, sorted.

for _, name in ipairs(modkit.ai.brains()) do
  local brain = modkit.ai.getBrain(name)
  print(name, brain.source, brain.temperament.aggression)
end

modkit.ai.removeBrain

modkit.ai.removeBrain(name)

Removes a brain that a script defined. When brains.json holds a brain of the same name, that one takes over and the animals keep running. When only the file has the name, the file brain is dropped until the file is loaded the next time.

Animals left without a brain go back to the game's AI. Wild animals among them get a new brain when their species still has one assigned.

Returns: true when a brain of that name existed.

modkit.ai.reload

modkit.ai.reload()

Loads brains.json and spawns.json again right away. A file with broken JSON is skipped with a log line and the brains and spawners from before stay. A brain in the file with an unknown field or a bad value is loaded with the default for that field, and one log line names the problem.

Spawners that are no longer in the file lose their animals, with aiDespawned and the reason "spawner_removed".

Returns: true.

modkit.ai.setBrain

modkit.ai.setBrain(id, name)

Returns: true on success. false for an unknown handle, an unknown brain, or when 500 animals already have a brain.

The home point is the place where the animal stands at that moment. Change it with setHome.

local ids = modkit.ai.spawn("deer", x, y, z, { count = 4 })
for _, id in ipairs(ids or {}) do modkit.ai.setBrain(id, "shy_prey") end

modkit.ai.info

modkit.ai.info(id)

Returns: a table, or nil when the handle is unknown.

An animal without a brain gives a short table with id, species, health, maxHealth, x, y, z. Test info.brain to tell the two apart.

Targets in commands

Wherever a function takes a target, three forms work: a player table, a Steam ID as string, or the handle of another animal as number.

modkit.ai.moveTo

modkit.ai.moveTo(id, x, y, z [, gait])

Sends the animal to a point. The state is scripted until it arrives or 120 seconds passed. After that the brain decides again. gait is "walk", "trot" or "sprint", default is the brain's roamGait.

Returns: true, or false when the animal has no brain.

modkit.ai.follow

modkit.ai.follow(id, target [, distance])

The animal follows the target and keeps distance (default 600). It walks when it is close, trots when it falls behind and sprints when it is far behind. The state stays scripted until release, another command, or until the target is dead or gone.

Returns: true, or false when the animal has no brain or the target does not exist.

modkit.ai.attack

modkit.ai.attack(id, target)

Forces chase on this target, whatever the brain's targets and aggression say. A forced chase ignores the leash, memorySeconds and fleeHealth. It ends when the target is dead or gone. hold, moveTo, follow and flee end it earlier.

Returns: true, or false when the animal has no brain or the target is dead or does not exist.

modkit.ai.flee

modkit.ai.flee(id, target [, seconds]) modkit.ai.flee(id, x, y, z [, seconds])

The animal runs away from a target or from a point. seconds defaults to the brain's fleeSeconds.

Returns: true, or false when the animal has no brain or the target does not exist.

modkit.ai.hold

modkit.ai.hold(id [, seconds])

The animal stops and stands still, in the state scripted. Without seconds it holds until release or another command.

Returns: true, or false when the animal has no brain.

modkit.ai.release

modkit.ai.release(id)

Ends scripted. The brain decides again.

Returns: true, or false when the animal has no brain or is not in scripted.

modkit.commands.add("heel", function(player)
  for _, id in ipairs(myPets[player.steamId] or {}) do modkit.ai.follow(id, player, 800) end
end)

modkit.commands.add("stay", function(player)
  for _, id in ipairs(myPets[player.steamId] or {}) do modkit.ai.hold(id) end
end)

modkit.commands.add("free", function(player)
  for _, id in ipairs(myPets[player.steamId] or {}) do modkit.ai.release(id) end
end)

modkit.ai.setHome

modkit.ai.setHome(id, x, y, z [, roamRadius])

Moves the home point of one animal. roamRadius replaces the brain's movement.roamRadius for this animal.

Returns: true, or false when the animal has no brain.

modkit.ai.abilities, useAbility

modkit.ai.abilities(id) returns the class names of the abilities the species has, for example "GA_Bite_C". The list is empty for an unknown handle.

modkit.ai.useAbility(id, name) lets the animal use an ability right now. name is a piece of the class name, case is ignored. It returns true when the ability was found and started. Both functions work for every animal with a handle, with or without a brain.

modkit.commands.add("abilities", function(player, id)
  player:message(table.concat(modkit.ai.abilities(tonumber(id) or 0), ", "))
end, true)

Brain callbacks

Four optional functions in the definition table let a script take part in the decisions. They exist only for brains from defineBrain.

agent is the table from modkit.ai.info.

senses has these fields. Both lists are sorted by distance and hold 16 entries at most.

Decisions that think can return.

A callback runs inside the server tick. Keep it short, and do not start HTTP requests or storage writes from think.

An error in a callback is logged with the brain name. After 5 errors that callback is switched off for this brain, and the animals keep running on the built-in logic. Defining the brain again turns it back on.

modkit.ai.defineBrain("gate_guard", {
  preset = "guard",
  movement = { roamRadius = 1500, leash = 3000 },
  temperament = { aggression = 0, fightToDeath = true },
  think = function(agent, senses)
    for _, p in ipairs(senses.players) do
      local player = modkit.players.get(p.steamId)
      if player and not modkit.acl.allowed(player, "gate.pass") and p.distance < 2500 then
        return { state = "chase", target = p.steamId }
      end
    end
  end,
  pickAttack = function(agent, target, distance, abilities)
    if agent.health < agent.maxHealth * 0.5 then return abilities[1] end
  end,
  onStateChange = function(agent, from, to)
    if to == "chase" then modkit.log.info("guard " .. agent.id .. " attacks") end
  end,
})

modkit.ai.addSpawner, removeSpawner, spawners

modkit.ai.addSpawner(definition) adds a spawner for as long as the server runs. It is not written to spawns.json. A spawner with the same id as one from the file replaces it while the server runs. An unknown field, a bad value or a species that is not in modkit.ai.species() raises a Lua error.

A spawner fills up in groups of pack.size of its brain, one group per second. Each group spawns at a random point inside radius. That point is the home of the group, and its animals are one pack.

modkit.ai.removeSpawner(id) removes a spawner that a script added and despawns its animals. When spawns.json has a spawner of the same id, that one takes over and the animals stay. It returns true when the spawner existed.

modkit.ai.spawners() returns all spawners as tables with the fields above, plus alive (animals alive right now) and source ("lua" or "file").

modkit.events.add("serverStarted", function()
  modkit.ai.addSpawner({
    id = "lake_boars", species = "boar", brain = "shy_prey",
    x = -180000, y = 52000, z = 1500, radius = 6000,
    count = 6, respawnSeconds = 600, playersWithin = 60000,
  })
end)

modkit.ai.setSpeciesBrain, speciesBrains

modkit.ai.setSpeciesBrain(species, name) gives every animal of that species that the game itself spawns the brain name. An assignment from a script wins over the wild entry of the same species in spawns.json. nil as name ends the assignment from a script. The entry from the file applies again when there is one. Without one, the animals of that species that were taken over go back to the game's AI.

Returns: true. false for an unknown brain, and for nil when no script had assigned that species.

The plugin looks for new wild animals every 10 seconds. A wild animal that got a brain has a handle from then on and shows up in modkit.ai.list.

modkit.ai.speciesBrains() returns a table species -> brain name with the assignments from scripts and from the file.

modkit.ai.setSpeciesBrain("deer", "shy_prey")

AI events

target, attacker and killer have the form of info.target.

Reasons of aiDespawned.

modkit.events.add("aiDied", function(id, killer)
  if killer and killer.kind == "player" then
    local player = modkit.players.get(killer.steamId)
    if player then player:notify("You brought down a guarded animal.") end
  end
end)

Clients can not send these names.