Castaway Isle: Island Survival and Crafting Kit
- ..
- .metadata142 B
- AIDebug.component
- Brain.component
- NoiseMaker.component
- README.md54.7 KB
- actions.module
- aiDebug.renderFeature
- aiKit.testSuite
- api.module
- brains.module
- bt.module
- compat.module
- debug.module
- fsm.module
- fx.module
- how-to-give-npcs-a-brain.guide
- how-to-make-enemies-that-patrol-chase-and-attack.guide
- looks.module
- memory.module
- navlink.module
- package.yaml1.8 KB
- presets.module
- registry.module
- senses.module
README.md
aiKit 1.3.16
Brains and senses for the non-player characters of any multiplayer Zero world. Put a Brain on a character, pick a preset, and it walks, looks, listens, remembers, fights and gives up like the character it is meant to be: a guard on its rounds, a sniper on a perch, a swarm, a boss that changes tactics. Change the preset while the game runs and it behaves differently at once. Presets are plain data, so a designer can make "a guard that hears better but gives up later" without touching code.
Version 1.3.16 (AI.VERSION). The version in this README, package.yaml and AI.VERSION move together, and a test checks that they do.
aiKit moves characters with navKit (the Pathwise world) and gives them health, damage, death and healing with SecondWind (the Second Wind world), which itself runs on Lifeline and MatchFlow. An install brings the versions those worlds publish at the time; aiKit 1.2.6 is tested against navKit 1.3.2, SecondWind 1.4.6, Lifeline 1.0.4 and MatchFlow 1.3.2. It adds the parts neither has: senses, memory, decisions and the debug view.
Guides
Two guides ship inside this package, so every install has them:
- How to give NPCs a brain: enemy AI that sees, hears and remembers (guide path
aiKit.package/how-to-give-npcs-a-brain, filehow-to-give-npcs-a-brain.guide/guide.md): what the kit is and how its parts fit, giving a character a brain, picking a behaviour from the presets and finding them by their tags, sight, hearing, light and memory and how a player gets past each, targets and teams, tuning a preset without code, patrol routes, and who runs the brains in a multiplayer game. - How to make enemies that patrol, chase and attack the player (guide path
aiKit.package/how-to-make-enemies-that-patrol-chase-and-attack, filehow-to-make-enemies-that-patrol-chase-and-attack.guide/guide.md): from an empty world to a small arena with guards, a chaser and shooters that notice you and attack, up close and from range, with SecondWind health and weaponsKit weapons so you can fight back.
Open one by its guide path or its short name: zero guides read aiKit.package/how-to-give-npcs-a-brain (or zero guides read how-to-give-npcs-a-brain) in the shell, the guides tool with that path, or the Docs panel (select the guide in the asset browser and press Open in Docs in its Inspector). Both guides also come up in a ZeroMind search worded the way you would ask, such as "how to make enemies that patrol, chase and attack the player" or "how to give NPCs a brain".
Quick start
1. Install aiKit into /source. One call brings everything it builds on with it: navKit (movement), SecondWind (health and damage), and the Lifeline and MatchFlow packages SecondWind uses. They land under /source/deps/, and require("navKit.api") and require("SecondWind.api") reach them from your own scripts too.
zeromind_install guid=549ff927-79bc-4db2-b5b2-35d5f3fd59cb at=/source
(or search ZeroMind for "aiKit" and install aiKit.package). If your world already has navKit or SecondWind installed, aiKit uses those; keep them at the versions above.
If you want SecondWind installed on its own too (to configure it, or for weaponsKit and other kits built on it):
- aiKit not installed yet: install SecondWind first, then aiKit (then weaponsKit, if you want it). aiKit uses that SecondWind where it is, nothing moves, and no restart is needed.
- aiKit already installed: install SecondWind, then weaponsKit (or the other kit) beside it, then restart the engine once (quit Zero and start it again, or in a browser reload the tab, then open your world) before you press play or run the tests. Switching to another world and back is not a restart. Installing SecondWind on its own moves aiKit's copy out of its
depsfolder to/source/SecondWind.package, and until the engine restarts it runs the code it already loaded from the old place beside the moved code: two copies of health that don't see each other (see Known limits). One restart settles it.
2. Add to scenes/main.scene/build.luau. At the very top of the file:
local AI = require("aiKit.api")
local NK = require("navKit.api")
and at the end of function content(), just before its end (a new world's scene already has the ground, the light and the player):
-- the ground the characters can walk on (baked when play starts)
entity.spawn("NavMap").component.add(NK.MAP, { kind = "grid", size = { x = 40, y = 6, z = 40 } })
-- a wall to hide behind (wide enough to hide the spawn point from the guard)
local wall = entity.spawn("Wall", { position = { 0, 1, 9 }, scale = { 16, 2, 0.5 } })
wall.component.add("Model", { model = "cube" })
wall.component.add("BoxCollider", {})
-- a guard walking a square behind it
local guard = entity.spawnSynced("Guard", { position = { -6, 0, 12 } })
guard.component.add("aiKit.Brain", {
preset = "guard",
route = { { -6, 0, 12 }, { 6, 0, 12 }, { 6, 0, 18 }, { -6, 0, 18 } },
})
-- V (or the button in the bottom-right corner) shows what it sees, hears and remembers
AI.addDebugToggle()
3. Press play. The blue guard walks its square behind the wall. Walk around the wall into its view: it stops, stares ("Suspicious?"), then runs at you ("Chase!"). Duck back behind the wall and it runs to where it last saw you, searches around there, gives up and goes back to its route. Press V to see its vision cone, the ring it would hear your footsteps in, and a red marker where it remembers you; press B to switch between the full view, state labels only and cones only. Walk slowly and it does not hear you at all.
Change preset = "guard" to "nightwatch" and it only sees you where it is lit; to "turret" and it stands and sweeps; to "chaser" and it hunts anything it sees or hears. From code, while playing: AI.setPreset(guard, "listener").
What you get
| piece | what it is |
|---|---|
aiKit.api | the one interface: local AI = require("aiKit.api") |
Brain component | senses, memory and a brain on one character; preset picks which |
AIDebug component | the debug view's switches: on/off (V and a button) and its style (B and a button) |
NoiseMaker component | bottles thrown on a timer, and keys that let a player throw a bottle (G) or fire a shot (F) |
aiKit.presets | every character type as plain data, and the perception styles |
aiKit.fsm | a small state machine |
aiKit.bt | a small behaviour tree |
aiKit.brains | the built-in brains, written with those two |
aiKit.senses, aiKit.memory | sight, hearing, light and touch; the fading memory of where others were |
aiKit.actions | the verbs brains are written in: move, face, attack, shoot, heal, slam, shout |
aiKit.debug + aiDebug render feature | the debug view, drawn in the game view |
aiKit.compat | health for characters nobody owns (see Multiplayer) |
aiKit test suite | a test for everything a game can call |
Presets
| preset | brain | kind | team | what it does |
|---|---|---|---|---|
guard | guard | state machine | guards | Walks its patrol route. Spots you only when it can really see you, chases, loses you when you break line of sight, searches where it last saw you, gives up and goes back. Shouts so other guards come. |
wanderer | wanderer | state machine | neutral | Strolls about where it was placed; stops to watch anyone who comes close. Harmless. |
chaser | chaser | state machine | monsters | Roams; runs at anything it sees or hears and hits it up close; gives up a few seconds after losing it. |
ranged | ranged | behaviour tree | bandits | Shoots and keeps its distance: when you come closer than 6 m it backs away to the middle of its 6-11 m band (round to the side when a wall is behind it), keeping its eyes on you, and fights from there; steps forward when you are farther than 11 m; strafes between shots. When it loses you it goes only as far as the edge of that band and watches the spot. |
coward | coward | state machine | bandits | Fights while healthy, flees and hides when hurt, heals, comes back. |
ambusher | ambusher | state machine | monsters | Crouches out of sight at its post, springs when prey comes close, returns to hiding afterwards. |
sniper | sniper | behaviour tree | bandits | Holds a perch, watches a long narrow cone, aims with a visible laser and fires one heavy shot. Break line of sight and the aim is lost. |
healer | healer | behaviour tree | monsters | Goes to whichever ally is most hurt and heals it with a beam; backs away from enemies. |
swarm | swarm | behaviour tree | swarm | Small and many: moves with its group, shares what any of them sees, mobs a target together. |
turret | turret | state machine | machines | Fixed gun: sweeps its arc, locks on, fires bursts, keeps aiming at the last spot for a moment. |
companion | companion | behaviour tree | players | Waits at its post until a player comes close, then follows that player, fights what threatens them and patches them up when they are badly hurt. |
boss | boss | behaviour tree | monsters | Brawler at full health, gunner that keeps its distance below 60%, berserker that charges and slams the ground below 30%. |
sentry | sentry | state machine | guards | Sight cone. Stands its post sweeping its gaze; sees only inside the cone and only what walls do not hide; tracks and shouts for help. |
listener | listener | state machine | monsters | Hearing. Blind, hears all round; noises are fainter with distance and through walls; it goes to where the noise was and swings at anything it bumps into. |
nightwatch | guard | state machine | guards | Light-sensitive sight. A guard whose eyes need light: stand in a lamp's pool and it spots you at once; keep to the dark and you slip past. |
dummy | wanderer | state machine | players | A harmless stand-in for a player that walks a route and makes footstep noises, so demos run with nobody playing. |
AI.find({ family = "perception" }), AI.find({ tag = "stealth" }), AI.find({ brainKind = "bt" }) filter them.
Perception styles
The three ways a character can take the world in have a list of their own, asked for the way presets are:
AI.perceptionStyles() -- { "sight", "hearing", "light" }
AI.perceptionStyle("light") -- { id, label, description, preset = "nightwatch", senses = { ... } }
| style | label | shown by preset | what it means |
|---|---|---|---|
sight | Sight cone | sentry | Sees only inside a cone in front of it, up to its range, and only what walls do not hide. |
hearing | All-around hearing | listener | Blind; hears noises all round, fainter with distance and through walls, and goes to where the noise was. |
light | Light-sensitive sight | nightwatch | Sees only where there is light: spots you at once in a lamp's pool, misses you in the dark. |
senses in the answer is that preset's own sense settings (a copy), so a style can be put on any preset: AI.definePreset("darkGuard", { base = "guard", senses = AI.perceptionStyle("light").senses }).
Picking a style by its tags
AI.styles() lists the three styles with tags, so you can pick one by what it senses with, what it suits, or how a player beats it. Each entry is AI.perceptionStyle(name)'s answer plus perceives, suits, beatenBy and tags (all of them in one list). Pass a tag to keep only the styles that carry it, or a list of tags to keep those that carry every one:
AI.styles() -- all three, in order, each with its tags
AI.styles("stealth") -- sight, hearing and light
AI.styles("night-levels") -- light
AI.styles("stay-quiet") -- hearing
AI.styles({ "sight", "stealth" }) -- sight and light (both see; light needs a lamp)
local pick = AI.styles("guard-posts")[1]
AI.definePreset("postGuard", { base = "guard", senses = pick.senses })
| style | perceives (senses with) | suits | beaten by |
|---|---|---|---|
sight | sight | stealth, guard-posts | hide-behind-walls |
hearing | hearing | horror, stealth | stay-quiet |
light | sight, light | stealth, night-levels | stay-in-the-dark |
Tags are lower case with hyphens; "Guard posts" and "night_levels" find the same tags. A tag no style carries answers an empty list.
Making your own presets
Presets are tables. AI.definePreset adds one, starting from a base; AI.tunePreset changes one for the whole game. Tables merge key by key, so you only write what differs. Call either on every peer (the scene's entrypoint.luau, or a module your components require) before the characters that use it start; a running character picks up the change at once.
local AI = require("aiKit.api")
-- a guard that hears better but is slower to give up
AI.definePreset("eagleGuard", {
base = "guard",
label = "Eagle-eared guard",
senses = { hearing = { sensitivity = 2 } }, -- hears every noise twice as far
search = { time = 25, spots = 8 }, -- searches longer before it goes back
chase = { giveUp = 5 },
})
AI.tunePreset("guard", { move = { walk = 1.6 } }) -- every guard in the game strolls slower
Then Brain { preset = "eagleGuard" }. false switches a sense off (senses = { sight = false } is a blind character).
Preset reference
| key | default | meaning |
|---|---|---|
base | none | preset this one starts from |
label, description, family, tags | names for menus, the debug label and AI.find | |
brain | chaser | the state machine or behaviour tree it runs (built-in or AI.defineBrain) |
team | monsters | its team; players is the players' team |
hostile | others | who it fights: others (every team but its own and neutral), none, or a list of teams |
mobile | true | false = never moves (turrets, perched snipers); no NavAgent is added |
move | walker, 2.0 / 4.0 | style (any navKit movement style), walk and run speeds, turnRate |
look | humanoid | shape (humanoid, brute, bug, turret, none), color, accent, size, head (cap, helmet, hood, horns, hat, blind, target, none), gear (baton, rifle, longRifle, sword, staff, claws, spear, lantern, cannon, none) |
health | 100 HP, timed | SecondWind settings it is given when it has no health: maxHealth, deathStyle, respawnDelay, regenRate; false = none |
senses.sight | 15 m, 110° | range, fov (whole cone, degrees), eyeHeight, spotTime (seconds of clear close view to be sure), closeRange (felt whatever the cone), needsLight, lightThreshold (0 dark .. 1 daylight), darkRange |
senses.hearing | ×1 | sensitivity (multiplies every noise's reach), threshold (weakest noise it reacts to, 0..1), wallDamp (share of a noise that gets through a wall) |
memory | 10 s / 7 s | forget (a seen spot fades over this), forgetSound, share (radius it tells allies what it saw), shareWith (team or group) |
combat | melee 1.7 m | kind (melee, ranged, sniper, none), range, damage, cooldown, type (SecondWind damage type), accuracy, noise (how far its attacks are heard), windup (sniper), volley |
patrol | wait 1.5 s | wait at each route point (the route itself is on the Brain: a list of points or a spline) |
wander | 7 m | radius, waitMin, waitMax |
search | 10 s, 5 m | time, radius, spots, lookTime |
chase | 2 s | giveUp: seconds without sight before it goes to look |
suspicion | 2 s | how long it stares at a glimpse or a noise before going to look |
flee | 35% → 80% | below, recoverAbove, distance (coward) |
keepDistance | 6-11 m | min, max (ranged, healer) |
ambush | 6 m | springRange, chaseTime |
heal | 12 HP | amount, range, cooldown, below (healer) |
follow | 2.5 m | distance, recruitRadius, guardRadius, healBelow, healAmount, healCooldown (companion) |
turret | turnSpeed, sweep, sweepSpeed (turret, sentry, sniper) | |
phases | none | boss phases: { name, above, tactic = melee/ranged/berserk, run, combat, keepDistance, tint } |
footsteps | 0 | how far its own footsteps carry, metres (dummies) |
shout | false | shouts when it starts a chase (guard) |
leash | 0 | territory radius; 0 = no limit |
Senses
Each sense writes a spot into the character's memory: where someone was, when, and how it knows (sight, glimpse, told by an ally, or sound). Brains only ever act on those spots, never on where a player really is: lose them and they go to where you were.
- Sight. Inside
range, inside the cone around where the body faces, and with a clear ray from its eyes to your chest or head (any collider in between hides you). Awareness fills while it can see you, faster up close and in good light, and drains while it cannot: a glimpse makes it suspicious, a full bar is a sighting. - Light-sensitive sight (
needsLight). It reads the light level where you stand from the scene's own lights (sun unless shadowed, ambient, point and spot lights unless blocked) and cannot see you belowlightThreshold, except withindarkRange.AI.lightAt(pos)tells you what it sees. - Hearing. Every noise reaches
radius × sensitivitymetres and fades linearly with distance; a wall in between letswallDampof it through. Noises from its own team are ignored unless they are alarming (shots, shouts, explosions). It hears where the noise was: a thrown bottle draws it to the bottle. - Touch. Anything within about a metre is noticed, eyes or not, in front of and beside the character (
AI.config.touchArc, 220 degrees centred on where it faces). Someone who creeps up right behind it is not felt; settouchArc = 360for the old all-round touch. - Memory. Spots fade over
forget/forgetSoundseconds. Withmemory.share, a character tells nearby allies what it saw. - Territory. With
leash(on the preset or the Brain), it ignores everything further than that from its territory centre.
Noises
Players' footsteps are heard without any setup: walking is heard within 5 m, running within 11 m, moving slowly is silent (AI.config.quietSpeed, walkNoise, runNoise, runSpeed). Make any other noise from any peer with AI.noise(position, loudness, madeBy, kind):
position: where it happened;loudness: how far it carries in metres, or the name of one of the noises below for its loudness;madeBy: who made it (an entity, id or name). Leave it out when the noise gives nobody away: a thrown bottle draws listeners to the bottle, not to the thrower;kind(optional): what it was, shown in the debug view and in theheardevent. It defaults to the noise's name, or"noise".
AI.noise(position, "gunshot", shooter) -- the shooter gives itself away
AI.noise(bottlePos, "bottle") -- listeners go to the bottle
AI.noise(position, 6, nil, "creak") -- your own noise, heard within 6 m
| kind | reach | alarms its own team |
|---|---|---|
footstep | 5 m | no |
run | 11 m | no |
impact | 10 m | yes |
bottle | 16 m | yes |
shout | 22 m | yes |
gunshot | 35 m | yes |
alarm | 40 m | yes |
explosion | 50 m | yes |
The NoiseMaker component throws bottles on a timer (interval, scatter), and with playerKeys = true lets the local player throw a bottle where they look (G) or fire a shot (F) that hurts the character it hits.
State machines and behaviour trees
Half the built-in brains are state machines, half behaviour trees, so both styles have worked examples in aiKit.brains. Write your own with the same pieces and give it to a preset:
local AI = require("aiKit.api")
local A, H = AI.actions, AI.helpers
-- a state machine: a lookout that runs to the bell when it sees someone
AI.defineBrain("bellRinger", {
initial = "watch",
states = {
watch = {
label = "Watch",
update = function(b, dt)
if H.enemy(b) then return "ring", "saw someone" end
A.faceYaw(b, b.homeYaw + math.sin(b.machine.time) * 0.8)
end,
},
ring = {
label = "Ring the bell!",
enter = function(b) A.shout(b, 40) end,
update = function(b, dt) if b.machine.time > 3 then return "watch" end end,
},
},
})
-- a behaviour tree: attack what you see, else wander
local BT = AI.bt
AI.defineBrain("simpleHunter", BT.selector("hunter", {
BT.sequence("fight", {
BT.condition("sees an enemy", function(b) b.target = H.enemy(b); return b.target ~= nil end),
BT.action("Attack", function(b, dt)
if A.inReach(b, b.target) then A.attack(b, b.target) else A.moveTo(b, b.target.pos, "run") end
return "running"
end),
}),
BT.action("Wander", function(b, dt)
if A.arrived(b) then A.moveTo(b, A.randomPoint(b, b.home, 6)) end
return "running"
end),
}))
AI.definePreset("bellRinger", { base = "sentry", brain = "bellRinger" })
Every state and node receives the brain record b: b.pos, b.facing, b.home, b.homeYaw, b.route, b.mem (its memory), b.preset, b.combat, b.machine / b.tree, b.st (scratch), b.focus. Helpers: H.enemy(b) (nearest enemy it sees now), H.lead(b) (best lead it has not dealt with), H.handle(b, spot), H.allies(b, radius). Actions: A.moveTo(b, pos, "walk"|"run"), A.follow(b, id, distance), A.stop(b), A.arrived(b), A.faceTo(b, pos), A.faceYaw(b, yaw), A.attack(b, spot), A.inReach(b, spot), A.heal(b, allyId, amount), A.slam(b, radius, damage), A.shout(b, radius), A.randomPoint(b, center, radius), A.fleePoint(b, from, distance).
aiKit.fsm: FSM.define(name, { initial, states = { name = { enter, update, exit, label } }, transitions = { { from, to, when, reason } } }), FSM.new(def, ctx), machine:update(dt), machine:go(state, reason), machine.state, machine.time, machine:label(). A state's update returns the next state's name to switch.
aiKit.bt: sequence, selector (both with { memory = true } to resume a running child), parallel, condition, action (returns "success", "failure" or "running"), wait, invert, succeed, cooldown, timeout, repeatUntilFail; BT.new(root), tree:tick(ctx, dt), tree.active (the leaf that ran). Node definitions are shared; what a node remembers lives on each tree instance.
The debug view
AI.addDebugToggle() (or an AIDebug component) adds two switches in the bottom-right corner of the game view: on/off (key V, or the "AI debug view" button) and style (key B, or the "Style" button). From code: AI.debug(true) / AI.debug(false) switches it, AI.debugStyle(name) picks a style.
It has three styles:
| style | draws |
|---|---|
full (default) | everything below |
minimal | only the state labels over each character's head |
cones | only the vision cones, filled on the ground |
AI.debugStyle("cones") -- pick a style (the view stays on or off as it was)
AI.debug("minimal") -- switch the view on in a style
AI.debugStyles() -- { "full", "minimal", "cones" }, the order the B key cycles
What the full view shows, for every character within 70 m of your camera (so a whole level is readable from where you stand):
- its state over its head (and its preset), coloured by how alert it is, on a dark plate; labels grow with distance so a character 40-odd metres away is still readable;
- its vision cone, filled on the ground: green calm, yellow suspicious, red sure, violet when its eyes need light;
- a blue ring: how far it would hear a walking footstep;
- blue lines to the noises it heard, fading;
- the spots it remembers: red seen, yellow glimpsed, orange told by an ally, blue heard, fading as it forgets, with a line from its head;
- its patrol route, and every noise on the bus as a ring as far as it carries.
Each player switches their own view and style. Other players' characters are drawn too: the peer running them sends what they remember only while somebody has the view on.
Events
Each Brain fires these on the peer that runs it. Subscribe with brain.events.<name>:connect(fn):
| event | when | payload |
|---|---|---|
spotted | it starts seeing someone it treats as an enemy | who (entity id), x, y, z (where they are) |
lost | it stops seeing them | who, x, y, z (where it last saw them) |
heard | a noise reaches it | kind, who (who made it, or ""), x, y, z (where the noise was), strength (how loud it was there, 0..1) |
died | its health runs out | by (who dealt the last hit, or "") |
stateChanged | its state changes | state, from, reason |
acted | it does something every screen draws | kind (melee, shot, snipe, heal, slam, shout), fx, fy, fz from, tx, ty, tz to |
local guard = AI.brain(entity.find("Guard"))
guard.events.spotted:connect(function(e) print("guard spotted", e.who) end)
guard.events.lost:connect(function(e) print("lost them at", e.x, e.z) end)
guard.events.heard:connect(function(e) print("heard a", e.kind) end)
guard.events.died:connect(function(e) print("guard down, by", e.by) end)
Patrol routes and splines
A Brain's route is a list of points, or a spline from the engine's spline library (@builtin::modules.spline). A spline becomes evenly spaced patrol points, 1.5 m apart by default, that the character walks through without stopping; it pauses (the preset's patrol.wait) only at the points you placed on the spline, or nowhere with pause = false. A closed spline loops like any route. A list of points pauses at every point, as before.
local spline = require("@builtin::modules.spline")
local path = spline.new({ { x = -6, y = 0, z = 12 }, { x = 6, y = 0, z = 12 }, { x = 6, y = 0, z = 18 }, { x = -6, y = 0, z = 18 } }, { mode = "catmullRom", closed = true })
guard.component.add("aiKit.Brain", { preset = "guard", route = path }) -- on the Brain: pauses at the 4 placed points
AI.setRoute(guard, path) -- or while it runs
AI.setRoute(guard, { spline = path, pause = false }) -- one smooth loop, never stopping
AI.setRoute(guard, { spline = path, spacing = 3 }) -- points 3 m apart
Health and damage
Characters get SecondWind health from their preset when they have none (addHealth = false on the Brain to give them your own with HK.attach). Every hit goes through SecondWind, so damage types, teams, friendly fire, death styles, respawns, the kill feed and hit effects follow the game's SecondWind rules. Players need SecondWind health of their own to be hurt (HK.attach(body, { team = "players" }) in the player setup).
To see health on screen, add one SecondWind.HUD to the scene: entity.spawn("HUD").component.add("SecondWind.HUD", {}). It draws each player's own health bar (bottom-left), bars over the characters, damage numbers, the death screen with its respawn countdown and the kill feed. Without it health still changes, but nothing draws it. The example guide adds it.
Multiplayer
- The host thinks. The peer that owns a character's synced entity (or the room host while nobody owns it, the same rule navKit uses) senses, remembers and decides for it, and moves it through navKit. Put characters on synced entities (
entity.spawnSynced). - Home is where it stands when a peer starts running it. A character's home (where it returns, wanders round and respawns) is taken from where it really stands the first time a peer runs it, after that peer has the room's positions. A player who joins and takes over characters keeps them where they are; they do not walk off to the middle of the world.
- Every screen sees the same thing. The preset, state, alertness, boss phase, pose, facing of characters that do not walk, and a sniper's laser are synced fields; every peer builds the same body from the preset. Shots, hits, heals and slams reach other screens as one small
aiKit:fxmessage each (sent only when someone else is in the room). Positions travel in navKit's crowd line. - Bodies on the other screens. The peer that runs a character hangs its body under the character. Every other peer builds the body as a local entity of its own that copies the character's position and turn each frame, because the engine refuses parts added under a synced entity another peer owns. When a peer starts or stops running a character, the body is rebuilt the right way at once.
- Any player can be the target. Players come from the scene's normal player setup (
layers.active.players); every player's body is a candidate for every character's senses, and each player's own footsteps are reported by that player's peer. - Commands from anyone.
AI.setPreset,setRoute,setTeam,setActive,setLeader,forgetandalertwork from any peer: they are sent to the peer running the character (aiKit:cmd).AI.noisefrom any peer reaches the brains. - Debug data only on demand. What a character remembers is sent (
debugData, a few hundred bytes, three times a second) only while some player has the debug view on. - Hits and heals reach the right peer. A hit or heal aiKit makes (a character's attack, a player's
NoiseMakershot, a healer's beam) on something this peer may not change goes to the peer that may (its owner, or the room host while nobody owns it) onaiKit:hit, and is applied there through SecondWind's own damage pipeline, capped by SecondWind'smaxRemoteDamagerule. aiKit uses its own channel for this because it re-subscribes every play session (below). - Characters nobody owns. SecondWind (through Lifeline) only lets an entity's owner change its health. The relay can leave synced entities with no owner; in a brand-new editor world that is every character. Then
aiKit.compatapplies aiKit's hits and heals on the room host through SecondWind's own pipeline, and brings its characters back after death. For the length of each such call, Lifeline counts that one entity as the host's (Compat.asOwner); nothing else about Lifeline's rule changes. An owned entity is only ever changed by its owner. A SecondWindTrap, a Lifeline damage zone or a game's ownHK.damagecall goes through SecondWind's ownership check and does not reach an unowned character; from a game's own code, userequire("aiKit.compat").damage(target, amount, opts)and.heal(target, amount, opts), which take SecondWind's arguments. - One peer per character. Every peer that runs characters says which ones every 2 s (
aiKit:runs, only while someone else is in the room). A peer that is only standing in for a character nobody owns steps back when another peer runs it as its owner, or stands in for it with a lower peer id. So a peer whose view of the room is wrong does not end up driving characters another peer also drives. - Messages survive play sessions. aiKit subscribes its channels (
aiKit:cmd,aiKit:noise,aiKit:fx,aiKit:hit,aiKit:debug,aiKit:runs,aiKit:throw) again whenever a peer's mode or rooms change, and a reload of the module silences the older subscriptions, so no message is lost or handled twice.
API reference (local AI = require("aiKit.api"))
| call | what it does |
|---|---|
AI.addBrain(e, preset?, opts?) -> Brain | Add (or update) a Brain; opts sets any Brain field. |
AI.brain(e) -> Brain? | The Brain of an entity, name, id or component. |
AI.brains() -> { {id, name, preset, state, team, authority, alive} } | Every Brain on this peer. |
AI.info(e) -> table | preset, state, alert, phase, team, authority, alive, memory, heard, position, facing, home, brain, brainKind. |
AI.isAuthority(e) -> boolean | Whether this peer runs that character. |
AI.setPreset(e, preset) | Switch preset while it runs (any peer). |
AI.setRoute(e, route) | New patrol route: a list of points, a spline, or { spline = path, spacing = m, pause = false }. |
AI.setTeam(e, team), AI.teamOf(e) | Put a character or a player on a team. |
AI.setActive(e, on) | Switch a brain off and on. |
AI.setLeader(e, player) | Companions: follow this player. |
AI.forget(e) | Forget everything it saw and heard. |
AI.alert(e, pos) | Tell it someone was seen at a spot. |
AI.presets(), AI.preset(name) | Preset names; one preset's full settings (a copy). |
AI.perceptionStyles(), AI.perceptionStyle(name) | Perception style names (sight, hearing, light); one style's label, description, preset and senses (a copy). |
AI.styles(tag?) | The perception styles with their tags (perceives, suits, beatenBy, tags); a tag or a list of tags keeps only the styles carrying them. |
AI.definePreset(name, def), AI.tunePreset(name, changes) | Add a preset; change one. |
AI.find(query?), AI.catalog() | Presets with labels, filtered by family, tag, brainKind, brain, id; everything labelled. |
AI.defineBrain(name, def) | Register a state machine table or behaviour tree root as a brain. |
AI.noise(pos, loudness, madeBy?, kind?), AI.recentNoises() | Make a noise (loudness in metres or a noise name; madeBy = who gives themselves away); the noises still on the bus. |
AI.lightAt(pos, exclude?) -> number | Light level at a spot, 0 dark .. ~1 daylight. |
AI.canSee(e, target) -> boolean | Could it see that entity right now (cone, range, walls, light)? |
AI.debug(on), AI.debugOn() | The debug view on this screen: true, false, or a style name to switch it on in that style. |
AI.debugStyle(name?) -> string, AI.debugStyles() | Pick the view's style (full, minimal, cones) and answer the current one; the style names. |
AI.addDebugToggle(opts?) | Add the on-screen switches and keys (an AIDebug component). |
AI.stats(keep?) -> table | Brains, sense ticks, raycasts and script milliseconds by section since the last call. |
Also: AI.VERSION, AI.BRAIN / AI.DEBUG (component names), AI.NOISES, AI.config (footstep speeds and reaches, light scales, senseRate, thinkRate, noiseLife), and the modules AI.fsm, AI.bt, AI.memory, AI.senses, AI.actions, AI.helpers, AI.brainLib.
Brain component
Settings: preset, team (empty = the preset's), group (swarms that move and share together), route (a list of points or a spline), leader (companions), active, addHealth, leash and leashCenter (territory). Read-only, synced: state, alert (0 calm .. 1 sure), phase, facing, pose, aiming, aimPoint, debugData. Methods: brain:info(), brain:record(). Events (on the peer that runs it; see Events): spotted, lost, heard, died, stateChanged, acted.
AIDebug component
key (KeyV, on/off), styleKey (KeyB, next style), button (true: the two on-screen buttons), style (full, minimal or cones; set it to pick one, read it for the current one), startOn, hint (a line of help text above the buttons, wrapped to fit), on (read-only); :toggle(), :setStyle(name).
NoiseMaker component
interval (0 = off), scatter, kind, radius, playerKeys, throwKey (KeyG), shootKey (KeyF), shotDamage; :throwAt(pos).
Performance
Measured on the native desktop engine in this world's showcase, with 30 characters running at once (every preset, the showcase minus its six swarm members). Per frame:
| per frame, 30 characters | |
|---|---|
| aiKit, debug view off | about 2.0 ms of its own script time (AI.stats()); about 3.1 ms counting every engine call its Brains make (the profiler) |
aiKit, debug view on (full) | about 2.9 ms (AI.stats()); minimal and cones cost about the same |
| navKit, moving the 27 that walk | about 3.8 ms |
| SecondWind + Lifeline, health for all 30 | about 3.6 ms |
So 30 characters with their movement and health come to roughly 10-11 ms a frame on that machine, about 0.35 ms per character all in.
Each character senses 10 times a second (AI.config.senseRate) and decides 15 times a second (thinkRate), staggered so they do not all think on the same frame; navKit keeps the bodies moving smoothly in between. Lower senseRate and thinkRate to trade reaction time for frame time. The debug view rebuilds its lines 8 times a second for characters within 70 m of your camera. Its state labels are 3D text on a dark plate; aiKit rewrites a label at most twice a second and only when its text changes. The costliest single things are SecondWind's hit pipeline (about 1 ms per hit) and navKit planning; see their READMEs.
Tests
The aiKit test suite (73 tests) covers every public call:
- constants and versions, and this README's one Known limits and one Version history section;
- presets: the built-ins,
definePreset,tunePreset,find,catalog; - the perception styles:
perceptionStyles,perceptionStyle, andstyleswith its tags and tag filter; - the state machine, the behaviour tree and memory;
- sight through and around walls, cones, hearing and wall damping, light-sensitive sight;
- every Brain command; patrol routes from point lists and splines, and a smooth spline walked without stopping;
- the noise call;
- the debug view, its styles and its on-screen switch;
- the
spotted,lost,heardanddiedevents; - the guard's whole loop, and the ranged attacker keeping its distance;
- a character's home taken where it stands when a peer starts running it, and its body following it on a screen that does not run it;
NoiseMaker, custom brains, damage and healing through SecondWind;- the multiplayer wiring;
- this README's first example, run in a new world's scene.
Run it with:
tools.use("tests", "run", { suite = "aiKit" })
It runs the same way in any world that installed aiKit.
What to expect on the current engine (@builtin 0c1a80c), seen on 1.2.6 with SecondWind 1.4.6 and Lifeline 1.0.4: 72 of the 73 pass. The one that failed in that run is "ranged attacker keeps its distance" (the archer stood 4.0 m off while backing away), a timing test that depends on how fast the test runner steps the scene; on 1.2.5 it was the README example test instead, which passes here. The example guide plays as described.
If SecondWind was installed after aiKit and the engine has not restarted since, it is running two copies of SecondWind (see Known limits), and tests that go through health can fail. Which ones varies: seen were the re-exported modules test (aiKit's SecondWind is not the one the test loads), the "died" test (health reaches 0, no died event), the healer test (the hurt ally is never healed) and "ranged attacker keeps its distance" ("target never hurt" or "target has no health"). Running the suite again does not fix it; restarting the engine once does. The engine can hold a new component's registration until a test's scene has loaded; "ranged attacker keeps its distance" waits up to 15 s for its target's health because of that, and if it still reports "target has no health", that wait ran out. The suite plays for several minutes, so a call that waits on it may be handed back as a background task to wait on.
Known limits
Open engine issues aiKit is affected by:
- No engine debug drawing in play cameras (OrigoZero/zero#19540). aiKit draws its debug view with its own render feature (
aiKit.aiDebug), as navKit does; a headless engine draws nothing. - Tops of 3D text clipped (OrigoZero/zero#19525). The debug view's state labels and the showcase's signs lose the top edge of tall letters.
- Late registration in a browser tab (OrigoZero/zero#19309). Components of installed kits can register after a scene's first frame in a browser; a character spawned before its Brain registers starts thinking a moment later.
- Two copies of SecondWind after it moves (OrigoZero/zero#22328). Installing SecondWind on its own after aiKit moves it from aiKit's
depsfolder to/source; the engine keeps the code it had loaded from the old place running beside the moved code, so a death, a heal or a hit can be counted in one copy and missed by the other, and tests that go through health fail until the engine restarts. A re-run does not help; one restart does. Install SecondWind before aiKit and it never moves; if aiKit is already in, install SecondWind and weaponsKit, then restart once (the example guide's step 2). - Frame rate of a busy scene in a browser (OrigoZero/zero#20750). The Performance numbers are from the desktop app; a scene with dozens of characters runs slower in a browser tab.
- Browser builds are not checked by an agent (OrigoZero/zero#20946). aiKit's tests and guides were run in the desktop app; an agent cannot open its own world in a browser build to check it there.
- Testing two players from one account (OrigoZero/zero#14448). Two engines signed in to the same account collide as one player. To see what a second player sees (the same enemies, in the same places, doing the same things), join with a second account.
- Slow installs (OrigoZero/zero#21420). Installing aiKit brings navKit, SecondWind, Lifeline and MatchFlow with it; an install with several dependencies takes a while, and "waiting for content" lines while it lands settle by themselves.
- ZeroMind description one release behind (OrigoZero/zero#19258). The description ZeroMind shows for the package can lag one release behind
package.yaml; the package itself is current.
Limits of aiKit's own design:
- Characters have no colliders. navKit moves them along its map, so walls and other characters block them but physics does not; a shot hits a character when its line passes close enough to the body. Players walk through characters.
- Light reading is an estimate. It sums the scene's lights with shadow rays; it does not read emissive surfaces, baked lighting or light colour.
- Territory is a circle.
leashis a radius around a centre, not an area shape. - Hearing does not path around corners. A wall between halves a noise; the noise does not travel around the wall.
- Unowned characters and SecondWind's own calls. aiKit's hits and heals reach characters nobody owns (see Multiplayer); SecondWind traps, Lifeline zones and direct
HK.damagecalls do not.
Version history
- 1.3.16: the old
aiKit.navmodule is gone (1.3.15 addedaiKit.navlinkbut the merge keptaiKit.navbeside it). @builtin 2eb6418. - 1.3.15: navKit is named in a new module,
aiKit.navlink, in place ofaiKit.nav; Brain, actions, api, registry and the test suite require it. Known limit, not fixed by this: an install of aiKit still places two older navKit copies beside navKit 1.5.0 underdeps/<navKit>/versions/(the api module at 1.4.1 and the package at 1.3.3), because the references recorded at publish foraiKit.navlinkand for navKit 1.5.0's own components still name those releases. Games get navKit throughAI.navKit, so a map baked there and the agents aiKit drives use the same copy. - 1.3.14: built against navKit 1.5.0 (bounded path searches) and SecondWind 1.4.7, Lifeline 1.0.4, MatchFlow 1.4.0, the releases weaponsKit, comboKit and arpgKit ship with, so a world holds one navKit and one SecondWind; every file naming them is recorded again; current engine library. No brain behaviour changed.
- 1.3.13:
aiKit.navnames navKit as~navKit.api/~navKit.crowdagain, written fresh so both record navKit 1.4.9. 1.3.12 spelled themnavKit.api/navKit.crowd, which resolve by name, and in this packagenavKit.apistill carried a record of navKit's api from before 1.4, so a fresh install of a game on aiKit got two navKit copies and was refused. No behaviour changes. - 1.3.12: Built against navKit 1.4.9, whose own modules no longer ask for an unpublished map-module version (in a fresh world 1.4.8's pathfinding never finished loading, so every brain's path read "unreachable").
aiKit.nav's two requires are spelled again so they record 1.4.9. No behaviour changes. - 1.3.11: aiKit names navKit in one place only, the new
aiKit.navmodule; Brain, actions, api, registry and the test suite take navKit from it. Built against navKit 1.4.8, whose release and main are one commit. 1.3.10 recorded some navKit references against navKit 1.4.7's release and others against the merge after it (the same files under two commits), so a game built on aiKit was still refused on a fresh install. No behaviour changes. - 1.3.10: Every
requireof navKit is written~navKit.api/~navKit.crowd(the installed-package spelling). A reference keeps the module version it was first recorded with, and the old spelling had recorded navKit's api module at a version from before 1.4.x, which republishing never refreshed (1.3.6 to 1.3.9 all carried it): a fresh world then got that old module beside the current navKit, and a game built on aiKit was refused on install ("runs two releases"). The new spelling is recorded fresh against navKit 1.4.7. No behaviour changes. - 1.3.9: Built against navKit 1.4.7, the first navKit released from its world's main. Every navKit-using source is published again with that one release: 1.3.8 recorded the 1.4.6 release, while content installed from navKit's world recorded the merge that followed it, so a game holding both (Castaway Isle's survivalCraftKit) was refused on a fresh install. Also on the current @builtin. No behaviour changes.
- 1.3.8: Every aiKit source that uses navKit is published again from this world, where navKit 1.4.6 is the only release, so each records that one release. A source keeps the versions it was last published with, and the brain, actions and API had not changed since navKit 1.3.3, so 1.3.7 still brought old navKit pieces into a fresh world. No behaviour changes.
- 1.3.7: Republished from aiKit's own world, where navKit runs as one install (1.4.6), so every navKit module aiKit names is recorded from that single release. 1.3.5 and 1.3.6 were sent from a world holding several navKit copies and recorded a mix, so installing aiKit (or anything built on it) into a fresh world was refused. No behaviour changes.
- 1.3.6: Republished from a world running navKit 1.4.6 as one release, so every navKit module aiKit names is recorded from that release (1.3.5 recorded two, and a fresh install refused to run it). No behaviour changes.
- 1.3.5: Touch covers the front and sides of a character, not straight behind it (
AI.config.touchArc, default 220 degrees; 360 restores all-round touch). Before, anyone within about 1.5 m of a guard's eyes was certain to be noticed whichever way he faced, so a player creeping up behind a guard to knock him out (concealKit, takedownKit) was always caught at arm's length. Found while building takedownKit. - 1.3.4: Republished from a freshly loaded world running navKit 1.4.6 alone, so every navKit module aiKit names is recorded from that one release. No behaviour changes.
- 1.3.3: The version test expects the current version (it still expected 1.2.6, so it failed on 1.3.0 to 1.3.2). No behaviour changes.
- 1.3.2: Built against one navKit release (1.4.6) throughout. 1.3.1 was published from a world that still ran navKit 1.4.1 beside it, so it recorded
navKit.apiandnavKit.crowdfrom two different releases and a fresh install of anything carrying it was refused. No behaviour changes. - 1.3.1:
AI.canSee(brain, target)agrees with concealment: a target concealed with exposure 0 is never seen, the same answer the brain's own senses give. A guard attacking a target that has no health (no SecondWind Vitals) no longer warns "damage failed" on every hit; real damage failures still warn. - 1.3.0:
AI.setConcealed(entity, exposure)andAI.exposure(entity): a way to hide an entity from every brain's senses, for a game where a player can slip out of sight (behind a prop, under cover, in tall grass) rather than just staying unseen by distance and line of sight.exposureis 0 (fully concealed: no brain's sight check runs against it, and the close-range touch certainty never fires) to 1 (normal, the default for anything never concealed), with partial values in between read as a share of normal certainty gain, for a player peeking out of concealment to be a little more findable than one fully hidden. Senses and the registry carry the lookup; nothing else changes, so a world that never calls it behaves exactly as 1.2.6 did. Built to support a hiding-and-body-carrying stealth kit (hideKit) that found no such mechanism in aiKit. - 1.2.6: Bodies of a character another peer owns follow it as a root of their own instead of being refused as its children, so a second player sees every aiKit body (the fix the Loadout world carried in its copy). Tested against the current releases: SecondWind 1.4.6, Lifeline 1.0.4, MatchFlow 1.3.2 and navKit 1.3.2, so an install of aiKit beside them places one Lifeline. @builtin 0c1a80c.
- 1.2.5: Text only; no changes to how characters behave. The example guide's step 2 and the README's install advice now say what to do when aiKit is already installed (the usual case for a reader of a guide that ships inside aiKit): install SecondWind, then weaponsKit beside it, then restart the engine once (quit Zero and start it again) before pressing play or running the tests. The advice to install SecondWind first stays for a world without aiKit. The guides show up in ZeroMind search and open by their short name, so the Known limits about that are gone. The Tests section says what the suite gives on the current engine (@builtin e8a470f, which this world now runs): 72 of 73, the README example test failing in its own setup while the example works. The version number moves to 1.2.5 in
AI.VERSIONand the version test. - 1.2.4: The example guide's gunfire step works: weaponsKit names the shooter by its body's entity id (plain text), so the old check (
shooter:isLocal()inside apcall) failed silently and no shot was ever heard; the guide now compares the id withWeapons.localWeapon()'s body, and nine shots from the spawn were heard by all five enemies. The guide installs SecondWind first, then aiKit, then weaponsKit, so SecondWind never moves. The README, both guides and the world's description now say what really happens when SecondWind is installed after aiKit (two copies run until the engine restarts; health tests fail; a re-run does not help, a restart does) instead of advising a re-run. The "ranged attacker keeps its distance" test waits up to 15 s (was 5 s) for its target's health to register, which the engine can hold until the test's scene has loaded. No changes to how characters behave. - 1.2.3: The example guide now shows your health on screen: one
SecondWind.HUDline gives the health bar in the bottom-left that drops as enemies hit you, the death screen with its respawn countdown and the kill feed. The arena's debug-view switch no longer covers weaponsKit's ammo counter (AI.addDebugToggle({ button = false }), V and B still work). The README and both guides say what to expect from the test suite in a new world (engine issue #22328). Built on the current @builtin. No changes to how characters behave. - 1.2.2: Looking a character up through its
Braincomponent (AI.brain(comp), and every call that takes an entity) no longer writes an engine error ("has no field 'id'"); the lookup reads the field the handle actually has. Test extended. - 1.2.1: The example guide corrected after following it step by step in a brand-new world: what each install puts where (one SecondWind and one Lifeline; MatchFlow can land in two versions), the enemies' real colours, gunfire muffled by walls, and the numbers measured in that check. No code changes.
- 1.2.0: Two guides in the package: how to give NPCs a brain (enemy AI that sees, hears and remembers), and an example that builds an arena of enemies that patrol, chase and attack the player with SecondWind and weaponsKit. A second player now sees the walking characters: on a screen that does not run a character, its body is a local entity that follows it (the engine refused parts added under a character another player owns). Tested against navKit 1.3.2, SecondWind 1.3.1, Lifeline 1.0.1 and MatchFlow 1.2.1, the versions an install brings today. The test suite (73 tests) waits for the scene to be ready before a test plays, which fixes "ranged attacker keeps its distance" failing right after a world switch.
- 1.1.0: First published release. Adds
AI.styles(tag?): the three perception styles with tags for what each senses with (sight, hearing, light), what it suits (stealth, horror, guard posts, night levels) and how a player beats it (hide behind walls, stay quiet, stay in the dark), filtered by one tag or a list.AI.perceptionStyles()andAI.perceptionStyle(name)answer exactly as in 1.0.0. Looking a character up by its name no longer writes an engine error. The test suite (72 tests) now runs in any world that installs aiKit. Built against navKit 1.2.1 and SecondWind 1.2.0, as 1.0.0 was. - 1.0.0: Pushed, never released. 16 presets (12 behaviours, 3 perception styles, a training dummy), with the perception styles also listed on their own (
AI.perceptionStyles); state machine and behaviour tree brains; sight, hearing, light and touch senses; fading memory shared between allies; territory; patrol routes from points or splines, smooth splines walked without stopping; a debug view in the game view with three styles (full,minimal,cones) and on-screen switches, readable across a whole level;spotted,lost,heard,died,stateChangedandactedevents;AI.noise(position, loudness, madeBy, kind); NoiseMaker; health through SecondWind 1.2.0 and movement through navKit 1.2.1; multiplayer (hits overaiKit:hit, one peer per character viaaiKit:runs, subscriptions renewed every session, home taken where a character stands when a peer starts running it); a 68-test suite.