# `Cauldron3D.Formats.Bsp`
[🔗](https://github.com/jaman/cauldron/blob/v0.3.3/cauldron_3d_formats/lib/cauldron_3d/formats/bsp.ex#L1)

A map file of the Quake family read into a `Cauldron3D.Bsp`, with its entity text: the
`BSP29` and `BSP2` layouts, and `BSP30` with its textures' own palettes and lighting in
red, green and blue.

    {:ok, %{bsp: bsp, entities: text}} =
      Cauldron3D.Formats.Bsp.parse(bytes,
        hulls: [{{-16.0, -16.0, -24.0}, {16.0, 16.0, 32.0}}],
        texture: &MyGame.texture/2
      )

## Options

  * `:hulls` — the boxes of hulls 1 and up, as `{mins, maxs}`, in the order the map
    was compiled with; hull 0, the point hull, is built from the nodes. Default `[]`
  * `:texture` — `fun(name, mips)` returning the texture entry for `Cauldron3D.Bsp`'s
    `textures` (`%{name:, kind:, mips:}` and whatever else the game keeps), given the
    lower-case name and the four mips; the mips are `[]` for a texture the map names but
    does not hold, which the game finds elsewhere (a `BSP30` map's WAD3 files, say).
    Default: every texture `:solid`, a missing one a placeholder

A face has a lightmap only when its texture's kind is `:solid`. Each model's bounds are
the file's spread by one unit on every side, as Quake engines load them.

# `miptex`

```elixir
@spec miptex(binary(), boolean()) :: {String.t(), [Cauldron3D.Texture.t()]} | :error
```

The name and four mips of a `miptex` record, as a map file or a WAD3 holds one; the mips
are `[]` when the record names a texture without its pixels. With `palettes?`, the
palette that follows the smallest mip is given to each.

# `missing`

```elixir
@spec missing() :: map()
```

A placeholder texture entry: a checked square of colours 15 and 0.

# `parse`

```elixir
@spec parse(binary(), keyword()) ::
  {:ok, %{bsp: Cauldron3D.Bsp.t(), entities: String.t()}} | {:error, :not_a_map}
```

The world and entity text of a map file's bytes.

# `solid`

```elixir
@spec solid(String.t(), [Cauldron3D.Texture.t()]) :: map()
```

A texture entry of kind `:solid`, the default for `:texture`; a placeholder when `mips` is `[]`.

---

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