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

A player's side of a `Cauldron2D.World`: join, send input, receive frames, leave.

Anything that runs in a process can be a player — a terminal session, a computer
player, a test.

    :ok = Cauldron2D.Player.join(world, :alice, %{username: "alice"})
    Cauldron2D.Player.input(world, :alice, Cauldron2D.Input.state(input))

    receive do
      {:cauldron_frame, %{tick: tick, view: view, events: events}} -> ...
    end

Frames arrive once per tick for as long as the player is joined, or as often as the
player asked with `join/4`'s `frames:` or `frames/3`, each carrying the events since
the one before. Leaving, or the process exiting, stops them.

# `frames`

```elixir
@spec frames(GenServer.server(), Cauldron2D.World.player_id(), boolean() | number()) ::
  :ok
```

Change how often the player is sent frames: `true`, a number a second, or `false`.

# `input`

```elixir
@spec input(
  GenServer.server(),
  Cauldron2D.World.player_id(),
  Cauldron2D.Input.state()
) :: :ok
```

Send what the player is doing now; applied before the next tick.

# `join`

```elixir
@spec join(GenServer.server(), Cauldron2D.World.player_id(), map(), keyword()) ::
  :ok | {:error, term()}
```

Join `world` as `id` from the calling process; `frames:` is how often it is sent
frames — `true` every tick, a number a second, `false` none, for a player that only
sends input (`Cauldron2D.World.join/4`). `{:error, :taken}` when
another process already plays as `id`.

# `leave`

```elixir
@spec leave(GenServer.server(), Cauldron2D.World.player_id()) :: :ok
```

Leave `world`.

---

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