# arenaLayoutKit.api
Arena layouts as pure data plans, and the builder that turns a plan into entities. Called from a scene's build or a game's start code.
- `plan(id, opts)` returns the pieces of a layout centred on 0,0: walls, pillars, bunkers, lanes, spawn gates and player starts, plus `shrink` or `lanes` settings for the two dynamic layouts.
- `build(id, opts)` spawns the root `<prefix>Arena` with a floor, a floor collider, a box collider on every wall, pillar and bunker side, spawnerKit spawn points on the gates (once `use({ spawner })` hands spawnerKit in) and named player starts.
- `use({ spawner, materials })` hands in optional kits; `defineTheme`, `defineLayout`, `propHook` and `withDefaults` extend it with your own art, layouts, props and naming.
Layouts: ring, pillars, cross, bunkers, shrinking, hazardLanes. Themes: plain, desertRuins.
# Arena Layout Kit
Six combat arenas for top-down shooters, twin-stick games, brawlers and wave survival, built in one call, each with a floor, colliders on every wall, enemy spawn gates and player starts.
```luau
local Arenas = require("arenaLayoutKit.api")
-- in a scene's content() or any time in edit or play
local root, plan = Arenas.build("pillars", { center = { 0, 0, 0 }, radius = 20, theme = "desertRuins" })
```
## The layouts (`Arenas.LAYOUTS`)
| id | what it plays like |
| --- | --- |
| `ring` | A wide open circle walled in. Pure dodging and kiting. |
| `pillars` | Two rings of columns to weave between and break line of fire (the default). |
| `cross` | Four wall blocks carve a plus-shaped set of corridors: choke points and corners. |
| `bunkers` | Four roofless houses, one per quarter, doorways facing the centre. |
| `shrinking` | An open ring that carries `plan.shrink` settings for a closing storm. |
| `hazardLanes` | Three lane strips that carry `plan.lanes` settings for burning in turn. |
Every layout has an outer ring wall of 24 segments with four openings, eight spawn gates just inside it (`<prefix>Gate1..8`, group `<prefix>Gates`) and four player starts near the centre (`<prefix>Start1..4`).
## API
- `Arenas.plan(id, { radius = 20, prefix = "", gates = 8, segments = 24 })` returns a plan: `{ id, radius, prefix, pieces, shrink?, lanes? }`. Pure data, no engine calls, so it is safe in tests, on a server and in tools.
- `Arenas.build(id, { center, radius, theme, parent, prefix, gates, spawnPoints = true })` spawns it and returns `root, plan`. The root is `<prefix>Arena`.
- `Arenas.ids()`, `Arenas.describe(id)`, `Arenas.count(plan)` list and inspect layouts.
- `Arenas.defineLayout(id, { label, description, tags }, fill)` adds a layout: `fill(pieces, plan, radius)` appends pieces.
- `Arenas.defineTheme(name, { label, floor, wall, pillar, bunker, lane, dressing })` registers a look; `Arenas.themeNames()` lists them.
- `Arenas.use({ spawner = require("spawnerKit.api"), materials = { sandPacked = ..., stoneAshlar = ..., tileGlazed = ..., mudBrick = ..., sandstonePale = ..., sandRed = ... } })` hands in optional kits: with a spawner the gates become spawn points; the materials dress the `desertRuins` theme. Nothing is looked up on its own, so the package works and publishes in any world.
- `Arenas.propHook = function(entity, kind, seed, scale) ... return true end` lets your own prop kit place ruins (`ruinWallStone`, `ruinColumn`, `ruinHouse`, `palmDate`, ...) in the `desertRuins` theme; return false to fall back to shapes.
- `Arenas.withDefaults({ prefix = "TS" })` returns a view whose `plan` and `build` use those defaults, which is how a game keeps its own entity names.
## Themes
- `plain`: engine cubes and a checkerboard floor, tinted stone colours. Works in any world.
- `desertRuins` (the default): sand, ashlar, glazed tile and mud brick surfaces handed in with `use({ materials = ... })` (desertMaterials has them; checkerboard otherwise), with props through `propHook`.
## Pairs well with
- **arenaHazardsKit** runs the storm of `shrinking` and the burning lanes of `hazardLanes`.
- **spawnerKit** turns the gates into spawn points for waves of enemies once handed in with `Arenas.use({ spawner = require("spawnerKit.api") })`.
The test suite `arenaLayoutKit` checks every layout's plan and builds each one in edit mode.