# `Cauldron2D.Net.Link.World`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d_net/lib/cauldron_2d/net/link/world.ex#L1)

A server's arena spoken for in this VM: a process a client joins, sends input to and
leaves exactly as it would a `Cauldron2D.World` (`Cauldron2D.Player`), which opens a
WebSocket to the server for each player (`Cauldron2D.Net.Link.Socket`) and turns what
comes back into frames, and plays the sound that comes with them through this
machine's speaker.

    {:ok, world} = Cauldron2D.Net.Link.World.start(url: url, token: token, arena: "pit")
    :ok = Cauldron2D.Player.join(world, "alice", %{username: "alice"})

The view a player receives is `%{wire: frame, map: map, sheet: sheet, arena: name}`,
the frame and map in the shapes `Cauldron2D.Net.Wire` gives and the sheet its index;
when the connection ends, one last view with `wire: nil` and `closed: reason`. A
game's `Cauldron2D.Client.Game` draws such views through `scene/2`, `hud/1`,
`outcome/1` and `labels/1` here:

    def scene(%{wire: _} = view), do: Cauldron2D.Net.Link.World.scene(view, :my_game)
    def scene(view), do: ...

The arts are matched to the local atlas by name, so both sides must draw from the
same atlas.

## Options

  * `:url`, `:token` — the server and the token from `Cauldron2D.Net.Remote.login/4`. Required
  * `:arena` — the arena's id as it writes. Required
  * `:topic` — the channel's topic prefix. Default `"world"`
  * `:sound` — `false` for silence. Default `true`
  * `:name` — a GenServer name. Default none

# `hud`

```elixir
@spec hud(map()) :: Cauldron2D.Client.Hud.t()
```

The hud of a wire view, rows of runs.

# `labels`

```elixir
@spec labels(map()) :: list()
```

The labels of a wire view, as a surface takes them.

# `outcome`

```elixir
@spec outcome(map()) :: map() | nil
```

The outcome a wire view carries, `nil` while play goes on.

# `scene`

```elixir
@spec scene(map(), Cauldron2D.Atlas.name()) :: Cauldron2D.Client.Game.scene()
```

The scene of a wire view for a surface drawing from `atlas`: focus, bounds, a cell function over the map, movers, labels, and the subject when the frame carries one.

# `start`

```elixir
@spec start(keyword()) :: DynamicSupervisor.on_start_child()
```

Start the world under the package's supervisor, so it outlives the caller.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start the world linked to the caller.

---

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