
Server packs are sets of data files that determine how a world behaves;
in an (hypothetical) multiplayer environment, all players must share the same
set of server files.

Data is split into packs, each one being a folder under `packs/PACK`;
objects defined inside them have names automatically prefixed by `PACK.`.

[[_TOC_]]

## Cell Types

Description of every type of cell that can be used in a world.

<details>
<summary>packs/PACK/cell_types.cfg</summary>

```ini
[NAME]
collision = full
opacity = full
interact = none
drop = PACK.NAME
capacity = 0
light = 0
```
</details>

The file contains any number of `[NAME]` sections,
defining the cell type named `PACK.NAME`

| key       | type          | default   | explanation                           |
|-----------|---------------|-----------|---------------------------------------|
| collision | Cell_collision| solid     | determines collision for the cell |
| opacity   | Cell_opacity  | opaque    | determines visibility of cells behind |
| interact  | Snippet       | none      | what happens when a player interacts |
| drop      | Item          | -         | item dropped by the cell |
| capacity  | int           | 0         | size of the attached inventory |
| light     | int           | 0         | amount of spot light emitted |
| offset    | ivec3         | 8,8,8     | offset of billboard box, in pixels |
| radius    | ivec3         | 8,8,8     | radius of billboard box, in pixels |

### Cell_collision

Determines the cell properties for the physics engine

| name      | explanation           |
|-----------|-----------------------|
| solid     | is solid for mobs; interrupts raycasting |
| slow      | slows down mobs inside it; interrupts raycasting |
| buoy      | makes mob inside float; interrupts raycasting |
| raycast   | does not interact with mobs; interrupts raycasting |
| empty     | has no physics whatsoever |

In general, every cell that has *some* physics behavior will interrupt
raycasting so it can be selected for interaction

### Cell_opacity

Determines if the faces of adjacent cells might be prevented from
rendering; in general there are three options:

* opaque: the cell is rendered, prevents rendering of neighbor faces
* partial: the cell is rendered in *some* way, prevents rendering of neighbor
  faces *only* if they have the same cell id
* clear: the cell is not rendered and doesn't affect neighbor faces

The actual values given for opacity provide values for HD and LD regions (close
regions with high detailing, and far regions with low detailing respectively)

| name          | HD region | LD region |
|---------------|-----------|-----------|
| opaque        | opaque    | opaque    |
| semiopaque    | partial   | opaque    |
| semiclear     | partial   | clear     |
| billboard     | flat      | clear     |
| clear         | clear     | clear     |

Note that cells in LD regions will not be rendered with partial opacity; they
will either be fully opaque or clear. Textures at that distance would stop
providing adequate transparency because mipmapping anyway.

### Interaction

Interaction determines how the cell responds to the player attempting to
interact with it. It can be provided in the form of an one-line code snippet or
through `interact.fun` as the relative path of a function containing more code.

The interaction code is passed the positions of the cells that would be erased
and placed on if the player would use those controls as first and second
argument respectively (`@0` and `@1`).

If interaction is specified the crosshairs will change shape when hovering over
the cell.

## Mob Types

Description of every type of mob that can be used in a world.

<details>
<summary>packs/PACK/mob_types.cfg</summary>

```ini
[NAME]
size = 0.5 0.5
drop = PACK.NAME
solid = false
persistent = false
items = 0
interact = none
state = ...
signal = ...
```
</details>

The file contains any number of `[NAME]` sections,
defining the mob type named `PACK.NAME`

| key       | type      | default   | explanation   |
|-----------|-----------|-----------|---------------|
| size      | float float | 0 0     | half size (horizontal vertical) |
| drop      | Item      | none      | item dropped/picked |
| solid     | bool      | false     | if true, other solid mobs collide with it |
| persistent| bool      | false     | if true, the mob is saved to disk |
| items     | int       | 0         | size of the mob inventory |
| interact  | Snippet   | ""        | code run when a player interacts |
| update    | Snippet   | ""        | code run when the mob updates |

### Interaction

Interaction determines how the mob responds to the player attempting to
interact with it. It can be provided in the form of an one-line code snippet or
through `interact.fun` as the relative path of a function containing more code.

The interaction code is passed the mob being interacted with as first argument
(`@0`).

If interaction is specified the crosshairs will change shape when hovering over
the cell.

### Update

The update snippet is run periodically to update tho mob state. It can be
provided in the form of an one-line code snippet or through `update.fun` as the
relative path of a function containing more code.

It is passed the mob being updated as first argument (`@0`).

If the update snippet wants to be called again later, it must invoke
`mob_wait(@0, ticks)`; otherwise, the mob will not be updated again unless
something else triggers a call to the update snippet.

## Item Types

Description of every type of item that can be used in a world.

<details>
<summary>packs/PACK/item_types.cfg</summary>

```ini
[NAME]
place = ...
spawn = ...
paint = ...
```
</details>

The file contains any number of `[NAME]` sections,
defining the item type named `PACK.NAME`

| key       | type      | default   | explanation   |
|-----------|-----------|-----------|---------------|
| place     | Cell      | none      | cell placed when using the item |
| spawn     | Mob       | none      | mob spawned when using the item |
| paint     | Cell      | none      | cell painted when using the item |

## Recipes

Description of the ways items can be crafted into different items

<details>
<summary>packs/PACK/recipes.cfg</summary>

```ini
[BENCH]
result = item amount
from = item amount
from = item amount
```
</details>

The section name is not the name of the recipe (recipes do not have names),
but the name of the bench block (full name of a cell declared on a
`cell_types.cfg` file).

The bench block determines which cell (if any) must be interacted with to use
the recipe. If the value is empty (`[]`) the recipe can be used from the
default inventory.

Section names can and will repeat in the recipes file, each one defining a
different recipe with the same bench.

| key       | type      | default   | explanation   |
|-----------|-----------|-----------|---------------|
| result    | Item [count]| -       | result of crafing the recipe |
| from      | Item [count]| -       | ingredient required for crafting. Multiple from lines can be added and each one counts as a separate ingredient.|

Both `result` and `from` entries have values consisting on an item type name of the
form `PACK.NAME` that must correspond to the section `[NAME]` at 
`packs/PACK/item_types.cfg`, and an optional integer that determines the amount
of items of that type, and defaults to `1` if not specified.

