# A flat walled play area (world.arena)

## What it is for

`world.arena` gives a game a clean flat play area instead of a landscape: a level floor whose top is at height 0, an apron of
floor around it, and optional walls with openings (a goal mouth, a gate). Every piece is a static entity with a box
collider, so characters and cars stand on the floor and bump into the walls. Use it for a pitch, a ring, a party stage or a
training yard. It serves the ground other kits stand on; what happens inside the arena is the business of the other kits.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "world.arena" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "world.arena",
                              config: { "size": [40, 60], "gaps": [{ "side": "north", "width": 8, "height": 3 }] } }
```

It requires `game.engine` and `physics.port`.

## First example

<!-- test: kits/game_engine/host/tests/world_arena.rs::the_arena_serves_a_flat_ground -->
With `size` `[20, 30]`, `apron` 2 and one opening on the north wall:

```json
{ "size": [20, 30], "apron": 2, "gaps": [{ "side": "north", "width": 6, "height": 2 }] }
```

the arena creates one floor entity (tag `arena_floor`) and six wall pieces (tag `arena_wall`: the north wall is cut in three,
plus the south, east and west walls), and `world.arena` answers `size()` with `[20, 30]`.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `size` | `[width, length]` | `[34, 52]` | play area inside the walls in metres (each 4 to 400), centred on the origin; width along x, length along z |
| `apron` | number 0 to 100 | `8` | floor that goes on beyond the walls on every side |
| `walls` | boolean | `true` | walls around the play area; off gives an open field |
| `wallHeight` | number 0.2 to 50 | `3` | wall height in metres |
| `wallThickness` | number 0.1 to 10 | `1` | wall thickness in metres |
| `gaps` | list of up to 8 | `[]` | openings `{ side, width, height }` centred on a wall |
| `spawn` | `[x, y, z]` | `[0, 0, 0]` | where the player starts |
| `spawnYaw` | number | `0` | direction the player faces, in radians (0 faces +z) |

`side` is `north` (the +z end), `south` (the -z end), `east` (the +x side) or `west` (the -x side). An opening lower than the
wall leaves a lintel above it (a goal mouth with its crossbar); an opening as tall as the wall leaves none. An opening wider
than the wall removes the wall. All settings are moddable; the kit has no collection.

## Services, events

- `world.ground` (service): flat, height 0 everywhere; its bounds include the apron; also gives the spawn point.
- `world.arena` (service): `size()` returns `[width, length]`; `inside(p, margin?)` says whether a point is inside the walls,
  `margin` metres in; `walls()`, `gaps()` and `apron()` return the wall pieces, the openings and the apron width.
- `world.ready` (event): once at mount, after the floor and walls exist, with the `size` built.

## Hooks and modding

The hook `arena.build` is asked once per mount, right before the floor and walls are created, with
`{ width, length, walls, wallHeight }`. Every field is mutable; it is not cancellable, since a game always has its floor.
`world.ground`, `world.arena` and `world.ready` answer for what was built.

```json
{ "id": "open_field", "hook": "arena.build", "set": { "walls": false } }
```

A mod can override every setting, for example a bigger pitch for a final. Model slots `arena_floor` and `arena_wall` dress
the pieces; when unbound they show as plain boxes.

## Engines

The floor and walls are one shared implementation for the web and native players; each engine draws the entities with its own
renderer.

## When it does not do what you expect

- The play area is not the size set: an `arena.build` tap changed `width` or `length`.
- Things pass through a wall: a `gaps` entry opens it; what lies behind it belongs to another kit.
- Walls are plain boxes: bind models to the `arena_floor` and `arena_wall` slots.

## Limits

Flat only (height 0), one rectangular area centred on the origin, up to 8 openings.

## Versions

Kit `world.arena` 1.1.0 (the `arena.build` hook since 1.1.0), requires `game.engine@^1` and `physics.port@^1`.