Log inGet started
Package

arenas.module

Newest version

README.md

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.

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

callreturns
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

{
  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

idnameboxes / colliderswhat it plays like
courtyardCourtyard169 / 142A 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.
warehouseWarehouse176 / 141A 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.
towersTowers132 / 104Four 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.
pitThe Pit123 / 91A 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.
canyonCanyon107 / 83Three 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.
redVsBlueRed vs Blue115 / 75Mirrored 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.