arenaBots.package
README.md
arenaBots 1.0.6
First-person-shooter bots for any multiplayer Zero game that fight with exactly the same weaponsKit weapons players use. A bot sees with an aiKit sight cone that walls block, remembers where it last saw you, moves with navKit, turns to aim with its skill's reaction time, aim error and tracking speed, picks the loadout weapon that suits the distance, reloads, and fires through weaponsKit's own network path. So the room's host judges every bot shot with the players' rules (fire rate, magazine, range, walls), SecondWind deals the damage, and the kill feed reads "Viper took down you".
Version 1.0.6 (Bots.VERSION).
Guide
How to add bots that shoot back to a shooter (guide path arenaBots.package/how-to-add-bots-that-shoot-back-to-a-shooter, file how-to-add-bots-that-shoot-back-to-a-shooter.guide/guide.md): from a scene with a player and a gun to a free-for-all or team match against bots, how skills, weapons, teams, objectives and multiplayer fit together.
First example
arenaBots needs weaponsKit and aiKit (aiKit brings navKit and SecondWind). Your scene needs the player with health and a weapon (weaponsKit's first example) and a navKit map. In scenes/main.scene/build.luau, at the end of content():
local NK = require("navKit.api")
local Weapons = require("weaponsKit.api")
-- the floor the bots walk on (baked when play starts)
entity.spawn("NavMap").component.add(NK.MAP, { kind = "grid", size = { x = 40, y = 6, z = 40 } })
-- the player: health and a rifle (body is the PlayerPrototype's body)
Weapons.health(body, { maxHealth = 150, deathStyle = "timed", respawnDelay = 3 })
body.component.add(Weapons.WEAPON, { def = "rifle", loadout = "rifle,shotgun" })
and in scenes/main.scene/entrypoint.luau:
local Bots = require("arenaBots.api")
local Net = require("weaponsKit.net")
function onLoad()
if not Net.isHost() then return end -- bots are shared: the host spawns them once
Bots.setSpawnPoints({ { -12, 0, -12 }, { 12, 0, -12 }, { -12, 0, 12 }, { 12, 0, 12 } })
Bots.spawn({ name = "Viper", skill = "normal", loadout = "rifle", position = { -10, 0, -10 } })
Bots.spawn({ name = "Rook", skill = "hard", loadout = "rifle,shotgun,sniper", position = { 10, 0, -10 } })
end
Press Play. Two soldiers in their own colours walk the map, spot each other and you, close to their weapon's range, strafe, and open fire with real weaponsKit rifles: muzzle flash, tracers, bullet holes and hit markers, the same as yours. Kill one and it comes back at a spawn point 3 s later; let one kill you and the kill feed names it.
This world's scenes/botTest.scene is this example in a walled box with cover.
Skills
| skill | reaction | aim error at 15 m | tracking | bursts | sight | moves | what it does |
|---|---|---|---|---|---|---|---|
dummy | never | - | 30°/s | - | 20 m, 90° | 2.0 m/s | Wanders (or holds an objective). Never fires. A target for practice. |
easy | 0.85 s | 6.5° | 110°/s | 4 rounds, 0.7 s pause | 30 m, 110° | 3.4 m/s | Slow to react, sprays, barely strafes, never falls back. |
normal | 0.45 s | 3.0° | 220°/s | 7 rounds, 0.35 s pause | 45 m, 140° | 4.2 m/s | Strafes, falls back below 30% health, chases a lost target a few seconds. |
hard | 0.2 s | 1.3° | 420°/s | full auto | 70 m, 170° | 5.0 m/s | Snaps on, strafes constantly, pushes in, falls back below 35%, hunts you down. |
Measured in botTest (one rifle bot against a stationary 100 HP target 15 m away, clear line, four runs each): dummy never fired; easy 4.7 / 8.3 / 5.6 / 6.5 s to kill; normal 3.5 / 1.7 / 2.3 / 2.4 s; hard 1.6 / 1.8 / 0.7 / 1.6 s. The host refused none of their shots.
Every field (see skills.module): reaction, aimError (degrees at falloffRange), falloff, falloffRange, tracking (degrees a second), burst, burstPause, sightRange, fov, spotTime, strafe (0..1), strafeTime, moveSpeed, walkSpeed, aggression (0..1), retreatBelow (health share), switchDelay, shoots, label.
local Skills = require("arenaBots.skills")
Skills.define("veteran", { base = "hard", reaction = 0.12, aimError = 0.8, label = "Veteran" })
Skills.tune("easy", { aimError = 9 }) -- every easy bot, now
Bots.setSkill(bot, "veteran")
Run define and tune on every peer (the scene's entrypoint), like weaponsKit's define.
Personalities
A personality is HOW a bot plays, independent of its skill (how WELL it plays): a hard camper and an easy camper hold the same spot, one just aims better. Plain data in personalities.module, read by the brain on every decision.
| personality | wants to stand | moves | in a fight | when it sees nobody |
|---|---|---|---|---|
balanced (default) | its weapon's good range, closer the more aggressive its skill | skill speed | strafes, falls back when hurt | wanders 16 m, hunts what it lost |
rusher | point-blank (closer than the weapon's near end) | 1.25x | charges straight in, barely strafes, never falls back | wanders wide, chases 2.5x longer |
camper | the far end of its range, accepts 14 m off | 0.85x | holds its spot 14 s at a time, almost no strafe | takes the highest spot near it and holds it, never chases |
flanker | a third into its range | 1.15x | orbits the target 55 degrees a step, swinging to its side and back | roams 24 m, chases 1.5x |
sniper | beyond the far end of its range | 0.9x | stands still to shoot, slips back if pushed, relocates every 8 s | high ground, rarely chases |
support | mid range | skill speed | strafes, falls back early | sticks within 5 m of its nearest teammate |
Fields: rangeFrac, tolerance, strafeScale, speedScale, flankAngle, holdTime, roamRadius, roamWait, chase, highGround, retreatScale, followTeam, label, description.
Bots.spawn({ skill = "hard", personality = "flanker" })
Bots.setPersonality(bot, "camper")
local P = require("arenaBots.personalities")
P.define("berserker", { base = "rusher", speedScale = 1.4, label = "Berserker" })
for _, p in Bots.personalities() do print(p.id, p.description) end
Weapons
Any weaponsKit weapon works: hitscan guns (pistol, SMG, rifle, shotgun pellets, sniper, railgun, pulse rifle, chain lightning), projectiles and throwables (rocket launcher, plasma pistol, fireball, ice shard, grenade, crossbow, bow with a full draw, thrown spear, toy blaster, water balloon), beams (laser, flamethrower) and melee (dagger, fists, sword with its combo, hammer, spear, squeaky hammer, foam sword). A bot leads moving targets with projectiles (better skills lead better) and lofts for gravity.
With a loadout of several weapons it picks the one whose good range fits the distance (melee up close, shotgun under ~12 m, rifle and SMG at mid range, sniper and railgun at 18-60 m, explosives kept beyond 9 m so it does not blow itself up), re-checked a few times a second while it fights. lockWeapon (or Bots.setWeapon(bot, id, true)) keeps the weapon you give it: gun game.
Bots have endless spare rounds but real magazines: they reload when empty (Net.reload, which the host counts like a player's) and top up between fights.
API (local Bots = require("arenaBots.api"))
| call | what it does |
|---|---|
Bots.spawn(spec) -> entity | On the host, in play. spec: { name, skill = "normal", team = "", loadout = "rifle", weapon (first of loadout), lockWeapon = false, look = "", position, yaw (radians), active = true, health = { maxHealth = 100, deathStyle = "timed", respawnDelay = 3, ... } }. A synced entity with SecondWind health (Weapons.health) and a Bot. |
Bots.remove(e) -> boolean | Despawn a bot. |
Bots.all() -> { row } | Every bot on this peer: { id, name, skill, team, weapon, mode, target, alive, authority, active }. |
Bots.get(e) -> Bot? | A bot's Bot component (:info() gives aim, ammo, gun and more). |
Bots.setSkill(e, skill) | Change skill. |
Bots.setPersonality(e, name) | Change how it plays: balanced, rusher, camper, flanker, sniper, support (spawn spec field personality). |
Bots.personalities() -> { personality } | Every personality with all its fields, in order. |
Bots.setWeapon(e, id, lock?) | Put a weapon in its hands; lock = true keeps it, false lets it choose again. |
Bots.setLoadout(e, "rifle,shotgun") | What it chooses from. |
Bots.setTeam(e, team) | "" = free-for-all. Writes its SecondWind team. |
Bots.setActive(e, on) | Off: stands still, never fires (lobby, results). |
Bots.setObjective(e, pos | nil) | A point it heads for and holds while it sees nobody (king of the hill, a pickup); it still fights what it sees. |
Bots.teleport(e, pos, yaw?) | Move it at once (navKit's crowd, transform and brain together). |
Bots.setSpawnPoints(points | nil) | Where bots come back after dying: a random one, away from the killer, and the bot is moved there as it comes back. A point is {x,y,z} or { pos = {x,y,z}, yaw, team }: a bot on a team uses its own team's points when there are any, a bot on no team the points with no team. nil = where each was spawned. |
Bots.skills() -> { skill } | Every skill with all its fields. Also Bots.skills module: require("arenaBots.skills"). |
Bots.on(event, fn) -> handle, Bots.off(handle) | Events below. |
Bots.stats(), Bots.frameStats() | Event counters; frame cost since the last call (botMs, fireMs, botTicks, and aiKit's ai numbers). |
Every call but spawn works from any peer: it is carried to the peer that runs the bot (aiKit's command channel).
Events
They fire on the peer that runs the bot.
| event | payload |
|---|---|
fired | { bot, weapon, kind (hit, proj, melee, beam), origin, dir, target } |
targeted | { bot, target }: it picked a new enemy |
died | { bot, by } |
respawned | { bot } |
reloaded | { bot, weapon } |
weapon | { bot, weapon }: it switched |
For kills and scores, listen to SecondWind's killed (killer is the bot's entity id) and weaponsKit's hit, as you do for players.
Bot component
Settable (synced): skill, team, loadout, weapon, lockWeapon, look (weaponsKit look family), displayName, active, objective + hasObjective. Read-only (synced): mode (roam, objective, fight, retreat, hunt, dead, inactive), target, ammo, reloading. A Bot added by hand to a synced entity gives itself 100 HP and a Brain.
Teams and hostility
Hostility is read live from SecondWind teams (the team on each body's Vitals): a bot with team "" fights everyone; a bot on a team fights anyone on another team or on no team, players included. Change a player's team with SecondWind (Vitals.team) and bots follow at once; Bots.setTeam writes the bot's. Bodies are tinted in their team's colour (red, blue, green, yellow, orange, purple, pink, cyan, white, black, alpha, bravo by name; other team names and free-for-all bots get a colour from their name).
How it works
- aiKit runs one
Brainper bot with arenaBots' brainarenaBotand presetarenaBot_<skill>(combat.kind = "none": aiKit never deals damage for a bot). It gives sight (cone, range, walls, awareness building overspotTime), memory, hearing and navKit movement. The brain only decides who to fight and where to stand. - The Bot component (after the brain each frame) tracks the target, turns the aim at
trackingdegrees a second toward the target plus a drifting error, and fires when the reaction time has passed and the aim is on:Sim.hitscan/Sim.melee/Sim.beamandNet.firewith the same claims a player'sWeaponsends, or a projectile from the gun's muzzle. - The host judges each shot exactly as a player's. The bot registers its held weapon with
Net.registeron every peer, reloads throughNet.reload, and keeps its magazine across a death so the host's count matches. - The body is the engine's humanoid avatar with Locomotion (idle, walk, run and strafe clips from its real speed), turned to where it aims, tinted, with its name over its head, and the gun seated in its right hand by
weaponsKit.holdand pointed along its aim.
Multiplayer
- One peer thinks. Each bot runs on the peer that owns its synced entity, or the room host while nobody owns it: aiKit's rule, shared with navKit. That peer senses, decides, aims and fires. Spawn bots with
Bots.spawnon the host. - Every screen sees the same bot. Movement travels in navKit's crowd line (the turn too: the bot's yaw is the crowd's). Every peer builds the same body from the synced fields and seats the gun with
weaponsKit.hold, and draws every shot from the bot's muzzle as it draws another player's: muzzle flash, tracer, projectile, impact, marks and sound. - Damage and deaths are SecondWind's, as for players: the host's verdict reaches every peer, the bot's owner (or the host) applies it, kills are credited to the bot. A bot nobody owns is brought back by the host (
aiKit.compat). - Commands from anyone.
Bots.set*andteleportgo over aiKit'saiKit:cmdchannel to the peer that runs the bot.
Frame rate
Measured in botTest on the desktop app with the editor open, 6 bots fighting with mixed loadouts (8 s, 293 frames): the Bot components took 2.4 ms a frame in all, of which 2.0 ms was weaponsKit drawing and sending the ~15 shots a second they fired (the work a player's Weapon does per shot) and 0.45 ms the bots' own logic (about 0.08 ms per bot). aiKit's brains took 0.55 ms a frame (senses at 10 Hz, thinking at 15 Hz, about 176 sight raycasts a second for 6 bots). The engine's own skinned-avatar animation is on top of that, as for every player body.
Known limits
Open engine issues that affect the kit:
- #14448: two engines on one account collide as one player. The bots were checked with one player; a second screen was not checked by the agent that made the kit. Test with two accounts.
- #20750: how long sending changes takes. Each bot shot is one weaponsKit message, each position update one navKit crowd-line entry; busy rooms pay this in the engine's sending step.
- #20946: an in-engine agent can't check the web build. Checked in the desktop app only.
- #21420: installs with several dependencies are slow. arenaBots brings weaponsKit and aiKit, which bring seven more kits. Let it finish.
- #19258: the ZeroMind listing description can lag a release behind. The README and
package.yamlin the install are current. - #18597 and #18596: the relay has no per-player rate limits and trusts the sender stamp. Bot shots go through the same weaponsKit messages as players' and the host judges them, but a modified client can flood or forge messages; the kit is not cheat-proof.
Limits of the design:
- On a screen that does not run a bot, the engine may refuse parts added under a synced entity another peer owns; the body is then built beside the bot and follows it (as aiKit does), and the gun sits in that body's hand, but weaponsKit draws that bot's muzzle flashes and tracers from its head height instead of the gun's muzzle.
- Bots have no collider. They are hit as weaponsKit's upright capsule (1.8 m by 0.4 m); players walk through them.
- The arm doesn't aim. The gun is held in the right hand and pointed where the bot aims; the arm plays the walk and run clips.
- No pickups, no jumping, no crouching. Bots use what they are given and walk where navKit's map goes.
- Grenades and lobbed weapons are aimed with a simple lead and loft and miss more than hitscan.
Version history
-
1.0.6: On the engine's current built-in library (@builtin a2f2883), so the world and the kit stay visible to players. Known limits name the relay issues (#18597, #18596). No behaviour change in the bots.
-
1.0.5: Runs on weaponsKit 1.2.12, whose weapons controls reach the controlsKit copy that runs them (controlsKit 1.2.6), so a game holding several controlsKit releases, such as one with menusKit 1.3.7, no longer logs "no scheme 'weapons'" every frame. No other change.
-
1.0.4: Runs on weaponsKit 1.2.11, the published release (with soundstage 2.1.3, SecondWind 1.4.4 and juiceKit 1.2.8), so a game that installs arenaBots beside weaponsKit has one weaponsKit, not the old 1.2.9 next to the current one. No behaviour change in the bots. The world moved to the engine's current built-in library (@builtin e89b9db).
-
1.0.3: Personalities, independent of skill:
balanced(default),rusher,camper,flanker,sniperandsupportchange preferred range, strafing, flank angle, hold time, roam radius and chasing (Bots.setPersonality,Bots.personalities(), spawnpersonality). A chase that makes no progress for 1.5 s is dropped. Runs on weaponsKit 1.2.10, so bot deaths reach every kit that listens for them. -
1.0.2: Team-aware respawns: spawn points can carry a
team(and ayaw), a bot comes back at one of its own team's points, and it is moved to the point it picked when it comes back. -
1.0.1: Bots wear their colour fully (tint blend 1) in deeper, saturated team and free-for-all colours, so they stand out against bright stylized arenas and toon lighting instead of reading as pale pastels.
-
1.0.0: First release.
Botcomponent,api,skills,brain,body; four skills; every weaponsKit attack kind; free-for-all and teams following SecondWind teams live; objectives; inactive bots; spawn points; teleport; events; the guide.