# `Cauldron2D.Arenas`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d/lib/cauldron_2d/arenas.ex#L1)

The arenas a game offers: a `Cauldron2D.World` each, with whatever runs beside it,
started on the first use of its name and stopped again once no player has been in it
for a while.

    :ok = Cauldron2D.Arenas.register(:pit, game: MyGame, game_opts: [map: map], name: "The Pit", map: "pit")
    Cauldron2D.Arenas.list()
    Cauldron2D.Player.join(Cauldron2D.Arenas.world_name(:pit), "alice", %{username: "alice"})

`register/2` makes an arena known; `world_name/1` names its world, and any call to
that name starts the arena if it is not running. `Cauldron2D.Arenas.Sweeper` stops
arenas that have had no human in them for a while and seats missing children again.
`list/0` is what a lobby shows, running or not, in the shape
`Cauldron2D.Client.Game`'s `arenas/0` gives.

## Options

  * `:game`, `:game_opts`, `:hz`, `:tick`, `:record` — the world's, as
    `Cauldron2D.World.start_link/1` takes them. `:game` is required
  * `:name` — what the lobby calls the arena. Default: the id as a string
  * `:map`, `:note`, `:kind`, `:teams` — shown in the lobby, as
    `Cauldron2D.Client.Game`'s arena describes them. Default: none
  * `:children` — a function from `%{id: id, world: world_name, humans: count}` to
    child specs started under the arena beside its world: computer players, a
    `Cauldron2D.Ledger.Recorder`. Called when the arena starts and on every
    `reseat/1`; a spec whose id is already running is left alone, one that has
    stopped is started again. Default: none

A player whose id is `{:robot, n}` is not a human.

# `id`

```elixir
@type id() :: term()
```

# `close`

```elixir
@spec close(id()) :: :ok
```

Stop arena `id` and forget it.

# `humans`

```elixir
@spec humans(id()) :: [term()]
```

The players in arena `id` who are not robots; `[]` while it is not running.

# `ids`

```elixir
@spec ids() :: [id()]
```

The ids of every registered arena.

# `list`

```elixir
@spec list() :: [map()]
```

Every registered arena, as a lobby lists them, with the humans in each — their count as `players`, their ids as `humans` — by name.

# `open`

```elixir
@spec open(id(), keyword()) :: {:ok, pid()} | {:error, term()}
```

Register arena `id` and start it at once.

# `register`

```elixir
@spec register(id(), keyword()) :: :ok
```

Make arena `id` known without starting it; see the module documentation for the options.

# `reseat`

```elixir
@spec reseat(id()) :: :ok
```

Start the children arena `id` is missing, as its `:children` function gives them now.

# `running`

```elixir
@spec running(id()) :: pid() | nil
```

The pid of arena `id`'s world while it runs, else `nil`.

# `running?`

```elixir
@spec running?(id()) :: boolean()
```

Whether arena `id`'s world is running.

# `running_ids`

```elixir
@spec running_ids() :: [id()]
```

The ids of every arena whose world is running.

# `start`

```elixir
@spec start(id()) :: {:ok, pid()} | {:error, term()}
```

Start registered arena `id`; the running world's pid if it already is.

# `stop`

```elixir
@spec stop(id()) :: :ok
```

Stop arena `id`, its world and its children, keeping it registered.

# `world_name`

```elixir
@spec world_name(id()) :: GenServer.name()
```

The name of arena `id`'s world; using it starts the arena when it is not running.

---

*Consult [api-reference.md](api-reference.md) for complete listing*