# hudStyles
How a fragKit match looks on screen, as one word: `military`, `scifi`, `fantasy`, `cartoon` or `arcade` (or `auto`, which follows the loadout). A style picks the look of every screen the installed kits draw (menusKit menus, lobbyKit's lobby and team scoreboard, MatchFlow's countdown and results, SecondWind's kill feed) plus the palette, fonts and kill wording of fragKit's own HUD, so the whole match reads as one game. `HudStyles.define(id, { base = "scifi", ... })` adds your own.
# arenaBots.personalities
How a bot plays, independent of how well it fights (its skill). Plain data like the skills: `balanced` (the default, the original behaviour), `rusher` (charges in to point-blank, barely strafes, chases hard), `camper` (takes the highest spot near it, holds it for long stretches, fights from the far end of its weapon's range, never chases), `flanker` (circles around its target to the side and back while fighting), `sniper` (keeps the longest distance, slow and still, relocates now and then) and `support` (stays close to teammates, mid range). `Personalities.define(id, { base = "rusher", ... })` adds one. Read by arenaBots.brain; reached as `require("arenaBots.personalities")` or `Bots.personalities()`.
# loadouts
The weapon sets a fragKit match hands out, one per art style: `military`, `scifi`, `fantasy` and `cartoon`. Each names the weaponsKit weapons players spawn with (`primary`), the ones melee-only, sniper-only and one-shot matches use, and the gun game ladder. A few extra weapons (Ion Scattergun, Void Lance, Arc Blade, Bubble Rifle, Confetti Cannon, Pop-Gun Sniper, Boing Bazooka) are defined on top of weaponsKit built-ins so every style has a full set. fragKit's Game and HUD components require it on every peer; call `Loadouts.define(id, spec)` to add your own.
# modes
The match types fragKit plays, as data: `ffa` (free-for-all), `tdm` (team deathmatch), `gunGame`, `oneShot`, `elimination`, `killConfirmed`, `kingOfTheHill`, `meleeOnly` and `sniperOnly`. Each names the MatchFlow format and clock, how a kill scores, which weapons are allowed, the death style, whether it plays in teams by default and whether the lobby may switch it between teams and free-for-all. The Game component reads it; `Modes.define(id, { base = "ffa", ... })` adds your own.
# fragKit.career
Each player's lifetime record in fragKit: frags, deaths, best streak, matches, wins and XP, with a level and a rank title worked out from the XP. It is kept in the local player's own saved data (`runtime_data.player(runtime_data.localId())`), the one store every player may write whether or not they edit the world, so a visiting friend's record saves the same as the owner's.
fragKit's Game component calls `recordMatch` on each machine for its own player when a match reaches its results, and the HUD shows the record on the scoreboard and the results. Game code can read it with `require("fragKit.career").mine()`.
# rules
The pure rules of a fragKit match, with no engine calls: the K/D board (frags, deaths, score, streaks, gun-game level per player and bot), what one frag is worth under a mode (`R.frag`: points, suicides, team kills, gun-game steps and the melee knock-down, kill-confirmed tag drops, streak callouts), whether a grabbed tag confirms or denies, and `R.pickSpawn`, which chooses the spawn farthest from living enemies and away from anyone standing there. The Game component calls it on the machine in charge; the test suite checks it on its own.
# fragKit 1.0.14: first-person arena shooter kit
**A complete first-person arena shooter in one call.** Add `Frag.setup { ... }` to a scene build and the default player becomes a first-person shooter in a finished match loop:
- you land in a lobby and pick **Teams or Free-for-all**;
- a countdown runs, then a **5-minute round** with a live kill feed and frag banners with streak callouts;
- you **respawn at the spawn farthest from living enemies**, with full ammo;
- a **scoreboard** with everyone's frags, deaths, best streak and score (lobbyKit's scoreboard) opens on held Tab, the pad's View button, or a **Scores** button on phones;
- a **results screen** ends the round, listing everyone, bots included, ranked by score with the winner (or winning team) named, and the next round starts by itself;
- every match adds to **your career**: lifetime frags, deaths, best streak, matches, wins and XP, with a level and a rank title (Recruit to Legend), kept in your own saved data and shown in the lobby and on the results.
It plays alone with bots or with friends joining from other computers or browsers.
fragKit is the shooter *glue* only: match types, arenas, the rules for frags, respawns, rounds and the scoreboard, and the HUD that ties it together. Everything else comes from kits other people published, and one install brings them all:
| Part | Kit |
|---|---|
| 27+ guns, blades and spells, first-person viewmodel, ammo HUD, crosshair, pointer lock, phone fire buttons, host-judged hits | weaponsKit |
| Health, damage, death, respawn, kill feed, death screen | SecondWind |
| Rounds, countdown, clock, results, hill zone | MatchFlow |
| Team lobby, ready check, team colours, team score bar | lobbyKit (+ scoreKit, menusKit, pickupsKit) |
| Pause and settings menus (the number beside each choice picks it) | menusKit 1.3.11, from its own world, Press Start Studio |
| Hit markers, damage numbers | markersKit |
| Recoil, shake, impacts | juiceKit |
| Music, footsteps, weapon sounds | soundstage |
| Keyboard + mouse, gamepad, touch | controlsKit |
| Bots that use the same weapons players do | arenaBots (aiKit + navKit) |
| Health and ammo pickups | pickupsKit |
## Guides
Two guides ship inside the package:
- **How to make a first-person shooter with fragKit (deathmatch with a scoreboard)**: `fragKit.package/how-to-make-a-first-person-shooter-deathmatch-with-a-scoreboard`
- **How to make a second arena map for my deathmatch shooter**: `fragKit.package/how-to-make-a-second-arena-map-for-my-deathmatch-shooter`. A step-by-step example from an empty world: install fragKit, design your own arena ("Crossfire") with `Arenas.define`, and switch between it and a built-in arena with one setting.
- **Workflow: make a second arena map** (`fragKit.package/workflows/makeSecondArenaMap.workflow`, `zero workflow list` shows it): the same steps as a workflow you or an agent can run one phase at a time.
## Install
```
zeromind_install guid=0455dc37-4c28-4ccd-beda-0cb6a9984c1f
```
Or search ZeroMind for "fragKit first person shooter kit". The install is big because it brings every kit above, so expect a minute or more (#21420).
## Example (paste into a new world)
A brand-new world has no scene yet. Ask your agent to create and open one, or run this Luau in it:
```lua
asset.create("scene", "main", { folder = "scenes" })
layers.load("scenes.main")
```
(A world that already has `scenes/main.scene` skips this.) Then open `scenes/main.scene/build.luau` and replace the whole `content()` function with:
```lua
function content()
local sun = entity.spawn("sun")
sun.component.add("Light", { kind = "directional", colorR = 1, colorG = 0.95, colorB = 0.88, intensity = 2.2,
directionX = -0.35, directionY = -0.8, directionZ = -0.3, castsShadows = true })
local ambient = entity.spawn("ambient")
ambient.component.add("Light", { kind = "ambient", colorR = 0.8, colorG = 0.82, colorB = 0.9, intensity = 0.7 })
entity.spawn("sky").component.add("ProceduralSky", { timeOfDay = 15.0 })
local setups = entity.spawn("PlayerSetups")
local prototype = entity.spawn("DefaultSocialPlayer", { parent = setups })
prototype:setParticipation("PrototypeOnly")
local body = entity.spawn("body", { parent = prototype })
body.component.add("Asset", { source = asset.resolve("@builtin::avatars.humanoid", "avatar") })
local rig = entity.spawn("CameraRig", { parent = prototype })
rig:setNetworkScope("OwnerOnly")
rig.component.add("Camera", { behavior = asset.resolve("@builtin::controller.first_person", "component") })
prototype.component.add("PlayerPrototype", { body = body, camera = rig })
local spawns = entity.spawn("Spawns")
local lobbySpawn = entity.spawn("LobbySpawn", { parent = spawns })
lobbySpawn.component.add("PlayerSpawn", { prototype = prototype })
require("fragKit.api").setup {
body = body, camera = rig, prototype = prototype, spawn = lobbySpawn,
mode = "ffa", arena = "courtyard", loadout = "military",
hud = "auto", feel = "classic", bots = 5, botSkill = "normal", minPlayers = 1,
}
end
```
Press Play. You start on the lobby balcony; after the lobby countdown you are in the courtyard with an assault rifle, against five bots.
## Every style
Each is one word in `setup`; change it and save.
**Match types (`mode`)**
| id | name | how it plays |
|---|---|---|
| `ffa` | Free-for-All | everyone against everyone; most frags in 5 minutes wins |
| `tdm` | Team Deathmatch | red vs blue; every frag scores for your team |
| `gunGame` | Gun Game | each frag moves you to the next gun; a frag with the last one wins; a melee frag knocks the victim down a level |
| `oneShot` | One Shot | every hit kills; precision weapons; quick respawns |
| `elimination` | Elimination | one life per round; last team (or player) standing wins the round |
| `killConfirmed` | Kill Confirmed | frags drop tags; grab enemy tags to score, your team's to deny |
| `kingOfTheHill` | King of the Hill | hold the zone alone; first to 60 seconds wins |
| `meleeOnly` | Melee Only | blades, hammers and fists |
| `sniperOnly` | Sniper Only | long guns only |
Modes that allow both can be switched between teams and free-for-all in the lobby (`teams = "auto" | "on" | "off"`, `lobbyChoice = true`).
**Arenas (`arena`)**, blockout maps 50 × 50 m inside a 64 m square, each with a lobby balcony, 12 free-for-all and 6 + 6 team spawns, a hill, pickups and a bot navigation box:
| id | layout |
|---|---|
| `courtyard` | plaza around a fountain monument, colonnades, raised walkways with ramps and stairs |
| `warehouse` | hall with stacked containers, catwalks, office block and a bridge over the middle |
| `towers` | four towers on stilts with ramps, bridges to a central platform |
| `pit` | sunken floor with ramps, rim walkway, pillar ring, corner platforms |
| `canyon` | three lanes between tall rock walls, crossings, a central mesa |
| `redVsBlue` | mirror-symmetric two-base map with team decks and a raised middle |
**Loadouts (`loadout`)**
| id | weapons |
|---|---|
| `military` | assault rifle, shotgun, sniper, pistol, frag grenades (realistic) |
| `scifi` | pulse rifle, ion scattergun, railgun, laser beam, plasma pistol |
| `fantasy` | crossbow, fireball, chain lightning, longbow, longsword |
| `cartoon` | bubble rifle, confetti cannon, foam-dart blaster, pop-gun sniper, water balloons |
| `arcade` | boomstick, chaingun, pixel rockets, plasma pistol, railgun, buzzsaw (retro arcade HUD) |
| `heavy` | minigun, rocket launcher, auto shotgun, flamethrower, frag grenades, anti-materiel rifle, sledgehammer (realistic) |
| `mixed` | a mixed bag across looks: assault rifle, pump shotgun, longbow, plasma pistol, longsword (each in its own style, minimal HUD) |
| `pistols` | pistols-only starter: service pistol, heavy revolver, machine pistol, marksman pistol (the sniper-only pick), knife and fists |
Each also names its melee-only, sniper-only and one-shot weapons and a gun game ladder.
**HUD styles (`hud`)**: `auto` (follows the loadout), `military`, `scifi`, `fantasy`, `cartoon`, `arcade`, `heavy`, `minimal` (hairline white type on smoked glass, a dot crosshair), `pixel` (four-shade handheld green, pixel frames and markers, chiptune). A style restyles fragKit's HUD and the kits' own screens to match: menusKit menus, the lobbyKit lobby and score bar, the MatchFlow countdown and results, the SecondWind kill feed, and the soundstage music set.
**Movement feels (`feel`)**
| id | feel |
|---|---|
| `classic` | fast arena: 6.4 m/s, sprint 8.6 m/s, snappy jump, strong air control, 100 HP |
| `tactical` | slow and weighty: 3.4 m/s, short hops, heavier head bob, 150 HP, longer respawns |
| `party` | 6.8 m/s, double jump, low gravity, wide view |
| `lowgrav` | moon gravity: 5.6 m/s, quarter gravity, huge slow jumps, soft air control, big landing dip |
| `retro` | boomer shooter: 11 m/s, no sprint, full air control, no head bob, 110 FOV, 1.5 s respawns |
| `modern` | contemporary blockbuster: 5.5 m/s, sprint x1.45 (8 m/s), modest jump, gravity -20, no slide or double jump, 95 FOV, light bob, 100 HP, 3 s respawns |
Every feel also moves the first-person view: a head bob while walking, a dip on landing from a fall and a wider view while sprinting (`bob`, `landDip`, `sprintFov` in `Frag.feels`). They run on each player's own machine and send nothing over the network.
**Bot skills (`botSkill`)**: `dummy` (walks, never shoots), `easy`, `normal` and `hard`, from arenaBots. `bots` sets how many join (0 to 16). `fighters` sets how many fighters the arena holds instead, people and bots together: bots fill every seat people leave empty (`fighters = 8` is 7 bots alone and 6 with a friend), up to 16 bots.
**Bot personalities (`botPersonality`)**: how bots play, independent of their skill. `mixed` (the default) deals a mix round the bots; or one for all: `balanced` (the classic behaviour: good range, strafes, falls back when hurt), `rusher` (charges to point-blank, barely strafes, chases hard), `camper` (takes high ground, holds it, fights from far, never chases), `flanker` (circles to its target's side and back), `sniper` (keeps the longest distance, stands still to shoot) and `support` (sticks with a teammate at mid range). From arenaBots (`Bots.setPersonality`).
Other settings: `teams`, `lobbyChoice`, `minutes` (0 = the mode's own), `minPlayers`, `origin` (where the arena is built), `pickups = false`.
## Controls
| | Keyboard + mouse | Gamepad | Touch |
|---|---|---|---|
| move / look | WASD / mouse (first click captures it) | sticks | left stick / drag |
| fire / aim / reload | left / right mouse / R | RT / LT / Y | Fire / Aim / Reload buttons |
| switch weapon | Q / X | bumpers | Swap |
| scoreboard | hold Tab | hold View | Scores button |
| pause and settings | Esc | Menu | pause button |
| lobby | 1 / 2 team, R ready, F1 / F2 teams or free-for-all | as lobbyKit shows | buttons |
**The cursor, exactly.** On desktop the cursor follows one rule, the same every time:
1. While a round is being played and nothing is open, fragKit's ask for the cursor stands the whole time, so the first click in the game captures it and the mouse looks around. That click does not fire.
2. The moment the pause menu, the settings menu, the scoreboard (held or pinned), the lobby or the results come up, the cursor is free, so you can click them. Clicks on them never count against the weapon's pointer-lock check, so they never switch you to "hold right mouse to look".
3. One Esc in play opens the pause menu. The browser and the desktop app let go of the cursor on that Esc before the game sees the key, so fragKit opens the pause menu whenever the captured cursor is let go during play (the same happens when the window loses focus).
4. When the menu, scoreboard or results go away (closed with Esc, Start, a click on Resume or Close, or Tab let go), the ask stands again at once: the cursor is taken back straight away where the platform allows it (after the scoreboard, or a menu the game freed the cursor for), and otherwise on your next click in the game, which does not fire. A button press that began while the cursor was free (the click on Resume, a press held while a menu closes) never fires either.
5. If the platform refused the cursor several times (weaponsKit then falls back to "hold right mouse to look"), your next click in the game asks for it again. After three such tries in one session, right-mouse look stays.
In the pause menu, the number each choice is drawn with picks it: 1 Resume, 2 Settings, and so on; arrows and Enter, or a click, work too. Touch play has no cursor; a gamepad never needs it.
## API
`local Frag = require("fragKit.api")`
| call | does |
|---|---|
| `Frag.setup(opts)` / `Frag(opts)` | builds the shooter into the scene being built (see the example) |
| `Frag.styles()` | every choice: `{ modes, arenas, loadouts, huds, feels, botSkills, botPersonalities }` |
| `Frag.find()` | the running `fragKit.Game` component |
| `Frag.modes`, `Frag.loadouts`, `Frag.hudStyles`, `Frag.feels`, `Frag.arenas` | catalogs with `list`, `get`/`resolve`, `catalog` and `define` for your own |
| `Frag.rules` | the pure rules: `entry`, `frag`, `sorted`, `ratio`, `tagScores`, `pickSpawn`, `balanceTeams` |
The Game component: `getState()`, `getBoard()` (rows `{ key, name, team, bot, k, d, s, streak, best, lvl }`), `myKey()`, `chooseTeams("on"|"off"|"auto")`, `teamsOn()`, `config()`, `ladder()`.
## Multiplayer
- Every player gets their own body, first-person camera, weapons and HUD from the scene's player prototype.
- The owner of the synced `FragGame` entity is in charge. It keeps the K/D board in synced state, scores frags into the MatchFlow match (or the lobbyKit team), runs gun game, tags, hill bots and elimination, and runs the bots. MatchFlow and lobbyKit hand the match over when the host leaves.
- The room host judges every shot from players and bots with weaponsKit's rules (fire rate, magazine, range, walls). The victim's machine applies the damage, and SecondWind's kill feed reaches everyone.
- Checked with two peers in one room: both showed the same board, health and feed. One peer's rifle shots landed on a host-owned bot (100 → 46) and on the other player's body (82 → 10).
- **Friendly fire is off.** In team modes your shots, blades and splash do not hurt your teammates, bots included (SecondWind's `friendlyFire` rule, off by default; fragKit leaves it off). Your own splash still hurts you. To turn it on: `require("SecondWind.api").setRules({ friendlyFire = true })`.
- **Team spawns.** In team modes everyone, bots included, starts and respawns at their own team's spawns; in free-for-all at the free-for-all spawns farthest from living enemies.
- **Not cheat-proof.** The host checks what a shot could have done, but a modified client can still lie about its aim.
### What a player's game writes, and where
A friend who joins your world without being one of its editors can play the whole match, because nothing fragKit or the kits it drives write during a match goes anywhere a player may not write:
| State | Where it lives | Who writes it |
|---|---|---|
| Frags, deaths, score, streaks, gun level, tags, teams, the round's board | the synced `state` field of the `FragGame` entity | the machine in charge (the entity's owner), through the room |
| The round, clock, countdown and results | MatchFlow's synced match entity | its owner |
| Health, damage, deaths, the kill feed | SecondWind's synced health and its events | each body's owner and the room host |
| Hits | weaponsKit's network messages | the shooter's machine asks, the room host judges |
| Music (set and intensity) | each machine on its own, from the synced HUD style and match phase (soundstage with `shared = false`) | nobody else |
| Your career (lifetime frags, deaths, best streak, matches, wins, XP) | your own saved data: `runtime_data.player(runtime_data.localId())`, key `fragKit/career` | your machine only |
The world's shared store (`runtime_data.world`) is never written: a visitor who is not an editor of the world is refused there. Each player's saved data is the store every player may write, and only their own. Read a career with `require("fragKit.career").mine()`; another player's with `runtime_data.player(id).get("fragKit/career")`. A session with no account (anonymous) keeps its career for that session only.
## Known limits
Every limit here is an open issue.
- **#14448**: two games signed in with one account collide as one player; test two players with two accounts.
- **#20750**: sending changes between engines costs frame time; every shot, verdict, health reading and board update goes through it.
- **#20946**: the web build was not checked by the agent that made this release. The desktop app was.
- **#21420**: installs with several dependencies are slow; fragKit brings many.
- **#19258**: the ZeroMind description can lag a release behind this README.
- **#22751**: models load slowly on the web, so weapon and bot models may pop in a moment after joining.
- **#18597** and **#18596**: the relay has no per-player rate limits and trusts the sender stamp a message carries, so a modified client can flood or forge messages. fragKit is not cheat-proof.
- **#23636**: running the test suites in an edit room other editors share changes the scene for them while the tests run; run them when you are alone in the world.
- If the browser will not capture the cursor, weaponsKit falls back to "hold right mouse to look".
## Design notes
- The host checks hits against where targets are now, with no lag compensation (weaponsKit's rule).
- Bots don't pick up pickups.
- Two editor windows in play on one scene share one room, so whichever joined first runs the match.
- The README example builds the arena and nothing around it; put ground or a finished environment around it (the showcase uses forestKit's beech forest).
## Tests
Four suites, 65 tests, all pure rules that run in edit mode (tests are refused while any client is in play):
- `fragKit`: frags, streaks, gun-game levels, kill-confirmed tags, spawn choice, every catalog id resolving, loadout weapons, arenas, this README naming every id, swapping a loadout, HUD or feel while a match runs, the career record (adding a match, levels and ranks, a broken save, one record per match in the player's own data), and that no fragKit script writes the world's shared store.
- `fragKitModes`: each of the nine match types keeps the rule that makes it that mode.
- `fragKitMatch`: who gets credit for a kill (frag, self, world, team, none), player and bot respawn spawns by team, the scoreboard and its order, and the winner.
- `fragKitCursor`: the cursor and menu rule, every cycle run several times in a row.
Run them together, in an `execute` call: `tools.use("tests", "run", { suites = { "fragKit", "fragKitModes", "fragKitMatch", "fragKitCursor" } })`. `zero tests run fragKit` in bash runs only the first.
## Version
- **1.0.14**: Installs into a brand-new world again, checked by installing it into one and running the example above as written. 1.0.10 to 1.0.13 could not be installed anywhere new: menusKit 1.3.7, which lobbyKit brought, was published pinned to a copy of controlsKit's `controls` module that ZeroMind does not hold, and every install stopped with "ZeroMind holds no version of it by that checksum". Now on lobbyKit 1.0.11 and menusKit 1.3.11 (controlsKit 1.2.8). Worlds that already had fragKit were not affected. 65 tests.
- **1.0.13**: Runs on arenaBots 1.0.6. (Its note that new installs worked again was wrong; see 1.0.14.)
- **1.0.12**: Polish after a full two-player round. While the scoreboard is open, its own clock replaces the match bar instead of drawing over it. The showcase forest no longer fails every frame on the second player's machine (forestKit's body follow skipped bodies the other machine despawned mid-scan; fix kept here and reported to forestKit). Both guides read against this release: the career and where a player's game writes are in the deathmatch guide. Updated to the engine library a2f2883. 65 tests.
- **1.0.11**: A friend who is not an editor of your world can play the whole match: nothing a player's game writes goes to the world's shared store any more (see "What a player's game writes, and where"); the music was the one thing that did, and each machine now plays it from the synced HUD style and phase. New career record in each player's own saved data, with levels and rank titles in the lobby and on the results. The pause menu's numbered choices come from menusKit 1.3.7, released from menusKit's own world (no patched copy any more), through lobbyKit 1.0.8. Runs on weaponsKit 1.2.12 (the weapons control scheme switches on again: X / Q switch weapons, with menusKit's controlsKit 1.2.6) and arenaBots 1.0.5. With two players in a room the joining machine no longer starts a second match (whose clock drew over the HUD): fragKit configures the match the scene holds. 65 tests.
- **1.0.10**: No dark shapes when you die: your own body's toon outline is hidden with your body through the death and the respawn (toonBlocks 1.1.26). The showcase forest's footsteps and ambience start again: every kit uses one soundstage copy (weaponsKit 1.2.11). Updated to the current engine library and the latest SecondWind, toonBlocks, style kits, Lifeline and juiceKit; all 60 tests pass and a full match was played after the update.
- **1.0.9**: Mouse and menus: one click captures the cursor, one Esc frees it and opens the pause menu, menus free it and give it back every time, and the numbered keys pick menu choices (menusKit 1.3.5). Bot kills and deaths count on the scoreboard and in the kill feed like a player's: weaponsKit 1.2.10 runs on the same SecondWind as every other kit, which also ends the screen-shake error on every shot. The world clock no longer writes from a peer that does not own it. The dark shape across the first-person view (your own body's toon outline) is gone (toonBlocks 1.1.24), and outline rescans and the HUD rebuild far less often, so 8-fighter matches run smoother. New loadouts `mixed` and `pistols`, HUD styles `minimal` and `pixel`, feel `modern`, and bot personalities (`botPersonality`, arenaBots 1.0.3). A labelled gallery scene of every variant family. Three new test suites (modes, kill credit and respawns, cursor). The second-arena guide was followed word for word from an empty world and corrected.
- **1.0.8**: Bots really respawn at their own team's spawns in team modes: the machine in charge watches every bot's health and moves a bot that has just come back to a spawn of its team, away from enemies (checked in a red vs blue round: every respawned bot stood within 1.2 m of one of its own team's spawns). In 1.0.7 the spawns reached arenaBots only at the countdown, before team play applied.
- **1.0.7**: The results screen lists everyone, bots included, ranked by score, with the real winner (or winning team) named: it is MatchFlow's results screen filled from fragKit's board. The kill feed and nameplates show player names, not engine peer ids. The scoreboard is lobbyKit's (1.0.7, with frags, deaths and best-streak columns). One cursor rule for every menu, the scoreboard and the results (see "The cursor, exactly"). Bots respawn at their own team's spawns in team modes (arenaBots 1.0.2). New loadouts `arcade` and `heavy`, a `heavy` HUD style and new feels `lowgrav` and `retro`. `fighters` keeps the arena at a set number of fighters. The example guide is now "How to make a second arena map for my deathmatch shooter", with a matching workflow.
- **1.0.6**: Polish. Esc / Start / the touch pause button open menusKit's pause menu (which frees the cursor). Before, Esc did nothing and weaponsKit's watchdog could turn mouse capture off for the session. Arena-speed movement feels with head bob, landing dip and a sprint field-of-view kick. Ranged weapons punch harder (weaponsKit's recoil shake ×1.8, from the shipped values). Crosshair, hit markers, damage numbers and the hurt-direction ring follow the HUD style's markersKit theme; your frags play a confirm sound that rises with the streak.
- **1.0.5**: The example starts from a truly empty world: it creates and opens `scenes/main.scene` first (a brand-new world has no scene). Checked by installing fragKit into a new world and pasting the example as written: lobby, countdown, bots and the round all run. The example guide starts the same way.
- **1.0.4**: Holding the scoreboard over the results hides the results screens on that player's machine and brings them back on release. Team balancing and team-mode titles are pure, tested rules (`Frag.rules.balanceTeams`, `Frag.modes.shown`). 13 tests, including one that checks this README names every choice.
- **1.0.3**: Team rounds run back to back: after the results, everyone who played is readied for the next round after 4 seconds (R un-readies). Bots even out the teams around the players before each round. A free-for-all mode played in teams is titled as its team version ("Team Deathmatch"). arenaBots 1.0.1 (bots in deeper, fully applied colours).
- **1.0.2**: Full ammo on every respawn and at the start of every match; arenaBots 1.0.1 (bots in deeper, fully applied colours).
- **1.0.1**: README and guides carry the real install id.
- **1.0.0**: first release: 9 match types, 6 arenas, 4 loadouts, 5 HUD styles, 3 movement feels, arenaBots at 4 skills, K/D scoreboard, Teams / Free-for-all lobby choice, two guides and a test suite (`zero tests run fragKit`).
# 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()`:
```lua
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`:
```lua
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`.
```lua
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`.
```lua
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 `Brain` per bot with arenaBots' brain `arenaBot` and preset `arenaBot_<skill>` (`combat.kind = "none"`: aiKit never deals damage for a bot). It gives sight (cone, range, walls, awareness building over `spotTime`), 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 `tracking` degrees 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.beam` and `Net.fire` with the same claims a player's `Weapon` sends, 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.register` on every peer, reloads through `Net.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.hold` and 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.spawn` on 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*` and `teleport` go over aiKit's `aiKit:cmd` channel 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](https://github.com/OrigoZero/zero/issues/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](https://github.com/OrigoZero/zero/issues/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](https://github.com/OrigoZero/zero/issues/20946): an in-engine agent can't check the web build.** Checked in the desktop app only.
- **[#21420](https://github.com/OrigoZero/zero/issues/21420): installs with several dependencies are slow.** arenaBots brings weaponsKit and aiKit, which bring seven more kits. Let it finish.
- **[#19258](https://github.com/OrigoZero/zero/issues/19258): the ZeroMind listing description can lag a release behind.** The README and `package.yaml` in the install are current.
- **[#18597](https://github.com/OrigoZero/zero/issues/18597) and [#18596](https://github.com/OrigoZero/zero/issues/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`, `sniper` and `support` change preferred range, strafing, flank angle, hold time, roam radius and chasing (`Bots.setPersonality`, `Bots.personalities()`, spawn `personality`). 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 a `yaw`), 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. `Bot` component, `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.
# fragKit.arenas
Six hand-designed blockout deathmatch arenas for fragKit, each one returned as plain, deterministic layout data: the boxes, FFA and team spawns, a lobby balcony, the king-of-the-hill zone, pickup spots, a navKit bake box and a material theme. A builder then spawns that data as scenery. fragKit's `Game` component reads `Arenas.layout(id)` for spawns, the hill and pickups. A scene's `build.luau` calls `Arenas.build(id)` to put the geometry into the world. Anything else (bots, minimaps, editors) can read the same data without touching the engine.
```lua
local Arenas = require("fragKit.arenas") -- inside fragKit: require("~.arenas")
-- in a scene build.luau content():
local L = Arenas.build("towers", { origin = { 0, 0, 0 } })
-- navigation for bots (navKit), placed for you:
entity.spawn("NavMap", { position = L.nav.navMap.position })
.component.add("navKit.NavMap", { kind = "multiLevel", size = L.nav.navMap.size })
```
## API
| call | returns |
|---|---|
| `Arenas.list()` | `{ id }` in display order: `courtyard, warehouse, towers, pit, canyon, redVsBlue`, then any custom arenas |
| `Arenas.info(id)` | `{ id, name, description, tags = {..}, size = {x, z} }`, where size is the play area in metres (50 x 50) |
| `Arenas.layout(id, opts?)` | a **Layout** (pure data, no engine calls, the same every call). `opts.origin = {x,y,z}` shifts all of it |
| `Arenas.build(id, opts?)` | spawns the geometry under `opts.parent` (positions are local to it) or under a new root `Arena_<id>`, and returns the Layout. Each box becomes local scenery: a `Model` (cube) plus a `BoxCollider` when `collide` |
| `Arenas.define(id, spec)` | registers a custom arena. `spec = { name, description?, tags?, size?, layout = function(opts) -> Layout }` |
| `Arenas.resolveMaterial(ref)` | the material asset for a theme entry (an asset ref table is passed through) |
### Layout
```lua
{
id, name, origin = {x,y,z},
boxes = { { pos = {x,y,z}, size = {x,y,z}, yaw = deg?, pitch = deg?, material = role, collide = bool, visible = false? } },
spawns = { { pos = {x,y,z}, yaw = deg, team = "red" | "blue" | nil } }, -- 12 FFA + 6 red + 6 blue
lobby = { pos = {x,y,z}, yaw = deg, size = {x, z} }, -- floor centre of the balcony
hill = { pos = {x,y,z}, radius = m },
pickups = { { pos = {x,y,z}, kind = "health" | "ammo" | "armor" } }, -- 5-6 per arena
nav = { center = {x,y,z}, size = {x,y,z}, -- box over every walkable floor
navMap = { position = {x,y,z}, size = {x=,y=,z=} } }, -- the same box as navKit's NavMap wants it
bounds = { min = {x,y,z}, max = {x,y,z} }, -- everything, lobby included
theme = { <role> = <material asset>, ..., tints = { <role> = {r,g,b} } },
}
```
**Conventions**
- **Yaw** is degrees about +Y. Yaw 0 faces **-Z** (the engine camera's forward) and yaw 90 faces -X, so the forward vector is `(-sin yaw, 0, -cos yaw)`. Use `Transform.quatFromAxisAngle(0, 1, 0, math.rad(yaw))`.
- **Box rotation** is yaw, then `pitch` (degrees about the box's own X axis, applied first; ramps only): `q = quatYaw * quatPitch`.
- **Positions**: a box's `pos` is its centre and `size` its full extents. A spawn or pickup `pos` is the point on the floor (feet). The floor top of every arena is y = 0. The Pit's sunken floor is at y = -3.
- **Spawns** face the arena centre (FFA) or the enemy side (team). Red spawns are always on the -Z side and blue on +Z. Each one has a flat coloured pad (drawn only, no collider).
- **Lobby**: a walled balcony 9 m up, outside the boundary wall (beyond -Z, or beyond +X in redVsBlue). It has a parapet with a top rail 1.55 m high, which cannot be jumped, and nothing in the arena reaches it on foot. Its boxes are in `boxes`.
- **Stairs** are solid steps of 0.25 m or less, plus an invisible ramp collider (`visible = false`) laid 8 cm over the nosings, so the CharacterController (step 0.3 m, slope 45°) and navKit glide up them. Plain ramps are 21 to 25°.
- **Materials**: `material` is a role (`floor`, `boundary`, `wall`, `trim`, `cover`, `ramp`, `red`, `blue`, `rock`, ...). The theme maps each role to a material asset and, for flat colours, a tint, which is applied with `tintBlend = 1`. The textured materials project at real scale on any box: groundMaterials (`clay`, `desertCrust`, `drySand`, `dirt`, `gravel`, `ash`) and stoneMaterials `cliffRockTriplanar`. All of them are resolved by literal reference, so the dependency is pinned at publish time. A custom theme can name one of these or put an asset ref table in the theme.
## The arenas
| id | name | boxes / colliders | what it plays like |
|---|---|---|---|
| `courtyard` | Courtyard | 169 / 142 | A cracked-earth plaza around a fountain monument (the hill). Colonnades close north and south. Raised walkways east and west each have two end ramps and a central stair, with a covered gallery underneath. L-shaped low walls stand at the diagonals. |
| `warehouse` | Warehouse | 176 / 141 | A bright hall under open roof girders. Container stacks (some two high) make the lanes. Catwalks run along north and south with stairs at the east end and join over the office roof in the west. A 43 m bridge spans the hall above the hill. The office block has doors, a window and an outside stair. |
| `towers` | Towers | 132 / 104 | Four corner towers on stilts, each with its own ramp. Diagonal bridges lead to a central platform (the hill) that has two more ramps. The ground level has crates, low walls and tall blocks, and you can walk under every tower. |
| `pit` | The Pit | 123 / 91 | A sunken floor 3 m down (the hill), reached by four ramps along its walls, with a bridge straight across at rim height. A ring of eight pillars stands on the rim and four raised corner platforms have ramps. |
| `canyon` | Canyon | 107 / 83 | Three lanes between 6.5 to 7.5 m rock walls. The west wall has three crossings and the east wall one. The centre lane has a rock mesa (the hill), the east lane a long ledge 2.5 m up, and the west lane a low shelf and a ruined hut. Open end zones join the lanes. |
| `redVsBlue` | Red vs Blue | 115 / 75 | Mirrored exactly about z = 0. Each base is a 3 m deck with three ramps, team stripes, banners and spawn pads. The centre platform with an obelisk is the hill. An east walkway, a west shelter, line-of-sight walls and lane cover complete it. |
Every arena is a 50 x 50 m play area inside a boundary wall 4 m high (7 m in the warehouse, 5 m in the canyon). The lobby sits outside it, and everything fits a 64 x 64 m square.
## Checks that were run (gallery scene `scenes.arenaGallery`)
- Every spawn of every arena (144) and every pickup (31) has no collider within 0.32 m at 0.45, 0.95 and 1.45 m above it, and has floor within 8 cm under it. Every team spawn is on its own side. FFA spawns are at least 5.1 m apart (courtyard 12.3 m).
- The default player walked up, with simulated input: the courtyard deck ramp (0 to 3.01 m), the towers corner ramp (0 to 4.01 m) and the warehouse catwalk stairs (0 to 3.51 m).
- A navKit `multiLevel` NavMap over Towers baked 11,780 cells from 0 to 5 m. Paths from the ground to a tower top, from the ground to the hill and from a tower to the far ground corner all come back `ok`. A path from the ground to the lobby stops at the boundary wall.
# feels
How players move in a fragKit match, as one word: `classic` (fast arena strafing, strong air control), `tactical` (slow, weighty, more health) or `party` (double jump, low gravity, wide view). A feel sets the body's CharacterController (speed, sprint, jump, gravity, air control, jumps), the camera's field of view, health, respawn delay and how fast bots run. `Feels.apply(body, id)` sets a body; `Feels.define` adds your own.
# weaponsKit.api
The one module a game talks to: `local Weapons = require("weaponsKit.api")`. The weapon catalogue (`list`, `get`, `has`, `styles` with tags, `vocabulary`), defining weapons (`define`, `tweak`, `remove`), look families (`looks`, `setLook`, `lookFor`, `crosshairFor`), equipping (`equip`, `weaponOf`, `localWeapon`), health for targets (`health`), events (`on`, `off`) and `stats`. See the package README for every call.