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

A way from where something stands to where it was sent, and walking it a step at a time.

    {:ok, route} = Cauldron2D.Route.to(&MyGame.open?/1, {x, y}, aim, size: {width, height})
    {{x, y}, route} = Cauldron2D.Route.advance(route, {x, y}, speed * dt)

This is what a game needs behind a click on the ground: the terminal client already
reports where the pointer is in the world as an input's `:aim`, `to/4` turns that into a
way across the grid with `Cauldron2D.Grid.Path`, and `advance/3` walks it.

A route is the tile centres still to walk through, in order, so it is a plain list of
points: it saves, replays and pattern matches like any other list, and `[]` means there
is nowhere left to go. Dropping a route is how a game cancels one — a key press, a
shove, a door closing.

`advance/3` passes through as many points as the distance covers, so a small tile and a
fast mover do not lose steps. `heading/2` is the way to the next point, for posing a
mover or aiming what it carries.

# `point`

```elixir
@type point() :: {number(), number()}
```

# `t`

```elixir
@type t() :: [point()]
```

# `advance`

```elixir
@spec advance(t(), point(), number()) :: {point(), t()}
```

`from` moved `step` along `route`, and what is left of the route.

A point the step reaches or passes is dropped and the rest of the step carries on
towards the next one. An empty route, or a step of nothing, leaves both alone.

# `arrived?`

```elixir
@spec arrived?(t()) :: boolean()
```

Whether there is nowhere left to go.

# `goal`

```elixir
@spec goal(t()) :: point() | nil
```

Where the route ends, or `nil` when there is nowhere left to go.

# `heading`

```elixir
@spec heading(t(), point()) :: float() | nil
```

The heading from `from` towards the next point of `route`, in radians with `0` along
`+x`, or `nil` for a route with nothing left.

# `to`

```elixir
@spec to(Cauldron2D.Grid.Path.passable(), point(), point(), keyword()) ::
  {:ok, t()} | :none
```

The way from `from` to `to`: the tile centres to walk through, and `to` itself at the end.

Both points are in tiles and may be fractional; the tiles they fall in are what the way
is found between, but the last step is the point asked for rather than the middle of the
tile it falls in, so a mover arrives where it was sent. `passable?` and `opts` are
`Cauldron2D.Grid.Path.find/4`'s, so `:size` is required. `:none` when there is no way.

Standing already where it was sent gives `{:ok, []}`; standing elsewhere in the same tile
gives the one step across it.

---

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