# `Cauldron2D.Beacon`
[🔗](https://github.com/jaman/cauldron/blob/v0.3.3/cauldron_2d/lib/cauldron_2d/beacon.ex#L1)

How a server on the local network is found: the host says so every two seconds on a
UDP port — `port/0`, the `:beacon_port` in the `:cauldron_2d` config, 2299 unless
set — to the broadcast address and to this machine, and whoever listens
(`Cauldron2D.Beacon.Listener`) hears it.

    {:ok, beacon} = Cauldron2D.Beacon.start_link(game: :my_game, host: "arcade", http: "http://192.168.1.5:2280", node: :"my_game@arcade")

A call is one line, `cauldron 1 <game> <host> <http url or -> <node or ->`. A node is
joined with its cookie, which the host shows and the caller types; it never goes over
the air. A host started with `:fields` calls `cauldron 2 <game> <host> <http or ->
<node or -> <fields>` instead, the fields a map of strings, URL-encoded as a query
string. `put/2` changes them while it calls.

# `call`

```elixir
@type call() :: %{
  game: String.t(),
  host: String.t(),
  http: String.t() | nil,
  node: atom() | nil,
  fields: %{required(String.t()) =&gt; String.t()}
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `line`

```elixir
@spec line(
  atom() | String.t(),
  String.t(),
  String.t() | nil,
  atom() | nil,
  map() | nil
) :: String.t()
```

The line a host calls with: `fields` `nil` for the first form, a map for the second.

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, call()} | :error
```

A call heard, or `:error` for anything else.

# `port`

```elixir
@spec port() :: pos_integer()
```

The UDP port the calls go out on: `config :cauldron_2d, beacon_port: n`, else 2299.

# `put`

```elixir
@spec put(GenServer.server(), %{required(String.t()) =&gt; String.t()}) :: :ok
```

Change the fields `beacon` calls with, from its next call on.

# `start_link`

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

Start calling; `:game` the game's name, `:host` the name to call as, `:http` the web URL or `nil`, `:node` the node name or `nil`, `:fields` a map of strings or `nil` (default), `:port` the UDP port (default `port/0`).

---

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