Log inGet started
World

Frag Arena: First-Person Shooter Kit with Deathmatch, Bots and Scoreboards

Branchmain
Branchesmain
Commit499680811e

README.md

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:

PartKit
27+ guns, blades and spells, first-person viewmodel, ammo HUD, crosshair, pointer lock, phone fire buttons, host-judged hitsweaponsKit
Health, damage, death, respawn, kill feed, death screenSecondWind
Rounds, countdown, clock, results, hill zoneMatchFlow
Team lobby, ready check, team colours, team score barlobbyKit (+ 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 numbersmarkersKit
Recoil, shake, impactsjuiceKit
Music, footsteps, weapon soundssoundstage
Keyboard + mouse, gamepad, touchcontrolsKit
Bots that use the same weapons players doarenaBots (aiKit + navKit)
Health and ammo pickupspickupsKit

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:

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:

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)

idnamehow it plays
ffaFree-for-Alleveryone against everyone; most frags in 5 minutes wins
tdmTeam Deathmatchred vs blue; every frag scores for your team
gunGameGun Gameeach frag moves you to the next gun; a frag with the last one wins; a melee frag knocks the victim down a level
oneShotOne Shotevery hit kills; precision weapons; quick respawns
eliminationEliminationone life per round; last team (or player) standing wins the round
killConfirmedKill Confirmedfrags drop tags; grab enemy tags to score, your team's to deny
kingOfTheHillKing of the Hillhold the zone alone; first to 60 seconds wins
meleeOnlyMelee Onlyblades, hammers and fists
sniperOnlySniper Onlylong 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:

idlayout
courtyardplaza around a fountain monument, colonnades, raised walkways with ramps and stairs
warehousehall with stacked containers, catwalks, office block and a bridge over the middle
towersfour towers on stilts with ramps, bridges to a central platform
pitsunken floor with ramps, rim walkway, pillar ring, corner platforms
canyonthree lanes between tall rock walls, crossings, a central mesa
redVsBluemirror-symmetric two-base map with team decks and a raised middle

Loadouts (loadout)

idweapons
militaryassault rifle, shotgun, sniper, pistol, frag grenades (realistic)
scifipulse rifle, ion scattergun, railgun, laser beam, plasma pistol
fantasycrossbow, fireball, chain lightning, longbow, longsword
cartoonbubble rifle, confetti cannon, foam-dart blaster, pop-gun sniper, water balloons
arcadeboomstick, chaingun, pixel rockets, plasma pistol, railgun, buzzsaw (retro arcade HUD)
heavyminigun, rocket launcher, auto shotgun, flamethrower, frag grenades, anti-materiel rifle, sledgehammer (realistic)
mixeda mixed bag across looks: assault rifle, pump shotgun, longbow, plasma pistol, longsword (each in its own style, minimal HUD)
pistolspistols-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)

idfeel
classicfast arena: 6.4 m/s, sprint 8.6 m/s, snappy jump, strong air control, 100 HP
tacticalslow and weighty: 3.4 m/s, short hops, heavier head bob, 150 HP, longer respawns
party6.8 m/s, double jump, low gravity, wide view
lowgravmoon gravity: 5.6 m/s, quarter gravity, huge slow jumps, soft air control, big landing dip
retroboomer shooter: 11 m/s, no sprint, full air control, no head bob, 110 FOV, 1.5 s respawns
moderncontemporary 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 + mouseGamepadTouch
move / lookWASD / mouse (first click captures it)sticksleft stick / drag
fire / aim / reloadleft / right mouse / RRT / LT / YFire / Aim / Reload buttons
switch weaponQ / XbumpersSwap
scoreboardhold Tabhold ViewScores button
pause and settingsEscMenupause button
lobby1 / 2 team, R ready, F1 / F2 teams or free-for-allas lobbyKit showsbuttons

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")

calldoes
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.arenascatalogs with list, get/resolve, catalog and define for your own
Frag.rulesthe 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:

StateWhere it livesWho writes it
Frags, deaths, score, streaks, gun level, tags, teams, the round's boardthe synced state field of the FragGame entitythe machine in charge (the entity's owner), through the room
The round, clock, countdown and resultsMatchFlow's synced match entityits owner
Health, damage, deaths, the kill feedSecondWind's synced health and its eventseach body's owner and the room host
HitsweaponsKit's network messagesthe 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/careeryour 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).