# `Cauldron2D.Worlds`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_2d/lib/cauldron_2d/worlds.ex#L1)

The worlds 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.Worlds.register(:pit, game: MyGame, game_opts: [map: map], name: "The Pit", map: "pit")
    Cauldron2D.Worlds.list()
    Cauldron2D.Player.join(Cauldron2D.Worlds.world_name(:pit), "alice", %{username: "alice"})

`register/2` makes a world known; `world_name/1` names its process, and any call to
that name starts the world if it is not running. `Cauldron2D.Worlds.Sweeper` stops
worlds 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 `worlds/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 world. Default: the id as a string
  * `:map`, `:note`, `:kind`, `:teams` — shown in the lobby, as
    `Cauldron2D.Client.Game`'s world describes them. Default: none
  * `:children` — a function from `%{id: id, world: world_name, humans: count}` to
    child specs started under the world's supervisor beside its process: computer players, a
    `Cauldron2D.Ledger.Recorder`. Called when the world 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 world `id` and forget it.

# `humans`

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

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

# `ids`

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

The ids of every registered world.

# `list`

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

Every registered world, 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 world `id` and start it at once.

# `register`

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

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

# `reseat`

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

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

# `running`

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

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

# `running?`

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

Whether world `id` is running.

# `running_ids`

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

The ids of every world that is running.

# `start`

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

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

# `stop`

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

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

# `world_name`

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

The name world `id` runs under; using it starts the world when it is not running.

# `world_name`

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

The name world `id` of `node` runs under, for a node this one is connected to; using
it starts the world there when it is not running. A node that cannot be reached names
no process.

---

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