
Client packs are sets of data files that determine how a world looks;
in an (hypothetical) multiplayer environment, each player can have their own
set of client 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 Models

Description of the way every type of cell should be rendered

<details>
<summary>pack/PACK/cell_models.cfg</summary>

```ini
[NAME]
texture = path
texture.x = path
texture.y = path
texture.z = path
texture.l = path
texture.r = path
texture.d = path
texture.u = path
texture.b = path
texture.f = path
effects = 1
sound.step = Sound
sound.use = Sound
sound.fail = Sound
sound.place = Sound
sound.break = Sound
```
</details>

The file contains any number of `[NAME]` sections,
defining the model for the cell type named `PACK.NAME`
that should be defined at `PACK/cell_types.cfg`.

| key           | type      | default   | explanation   |
|---------------|-----------|-----------|---------------|
| texture       | path      | ""        | texture for all faces |
| texture.x     | path      | ""        | texture for left and right faces |
| texture.y     | path      | ""        | texture for down and up faces |
| texture.z     | path      | ""        | texture for front and back faces |
| texture.l     | path      | ""        | texture for left faces |
| texture.r     | path      | ""        | texture for right faces |
| texture.d     | path      | ""        | texture for down faces |
| texture.u     | path      | ""        | texture for up faces |
| texture.f     | path      | ""        | texture for front faces |
| texture.b     | path      | ""        | texture for back faces |
| effects       | int       | 1         | bitmask of render effects |
| sound.step    | Sound     | ""        | sound played when stepping on it |
| sound.use     | Sound     | ""        | sound played when succesfully using |
| sound.fail    | Sound     | ""        | sound played when failing to use |
| sound.place   | Sound     | ""        | sound played when placing |
| sound.break   | Sound     | ""        | sound played when breaking |

### Textures

Textures are the names of files in the `packs/PACK/textures/` directory
that are applied to each of the cell faces.

Textures can be specified in any order, but lines further down in the file
override lines further up. For example, if you first define `texture` and then
`texture.u`, every face in the cell will have the first value, *then* the top
face will be overriden to have the second.

All textures should be 16x16 pixels; for cells you can provide taller textures
whose height is a multiple of 16 and they will all be loaded into the atlas,
and every time that face of a cell of that type is rendered a random texture
will be selected from the range.

### Effects

Effects is a bitmask that is directly passed to the fragment renderer to enable
or not different layers when the corresponding face is rendered in the HD
region.

| value     | effect        |
|-----------|---------------|
| 1         | enables ambient occlusion |
| 2         | enables liquid waves |

As a bitmask you can add several numbers together, e.g: 3 = 1 + 2 enables both
ambient occlusion and waves; this example is used by the 'basic.water' cell.

### Sounds

Sounds are the full names of sounds defined in any `sounds.cfg` file.

Note that the `step`, `place`, and `break` sounds are associated with the
player, and do not have a position. On the other hand the `use` and `fail`
sounds are associated with the cell, and only one of them can play at once (the
second sound to be played stops the first, see the music box object for an
example that takes advantage of this)

## Mob Models

Description of the way every type of mob should be rendered

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

```ini
[NAME]
texture.f = path
texture.b = path
state = ...
sound.place = Sound
sound.break = Sound
sound.use = Sound
sound.fail = Sound
```
</details>

The file contains any number of `[NAME]` sections,
defining the model for the mob type named `PACK.NAME`
that should be defined at `PACK/mob_types.cfg`.

| key           | type      | default   | explanation   |
|---------------|-----------|-----------|---------------|
| texture.f     | path      | ""        | textures when facing the player |
| texture.b     | path      | ""        | textures when facing away from the player |
| state         | Frames    | n/a       | sequence of textures used for a state |
| sound.place   | Sound     | ""        | sound played when placing |
| sound.break   | Sound     | ""        | sound played when breaking |
| sound.use     | Sound     | ""        | sound played when succesfully using |
| sound.fail    | Sound     | ""        | sound played when failing to use |

### Textures

Textures are the names of files in the `packs/PACK/textures/` directory
that are applied to the billboard that represents the mob.

Textures represent the mob facing in a diagonal direction (towards or away from
the player, and always to the right); they are mirrored when the mob faces the
opposite direction.

All textures should be 16x16 pixels; for mobs you can provide taller textures
whose height is a multiple of 16 and in that case each 16x16 fragment will
become a separate texture and added to the list of textures for that side.

When loading a mob model, more than one texture can be provided for each side,
in that case, the animation entry is used to determine how and when these are
displayed.

### States

The state entries hold a space-separated list of frames; frames are pairs of
`TEXTURE:DURATION` that determine that the texture number `TEXTURE` is
displayed for `DURATION` frames before going on to the next. Texture numbers
are determined by the order they are loaded; animations should be declared in
state order (so the nth animation will be displayed when the mob is in the nth
state)

### Sounds

Sounds are the full names of sounds defined in a `sounds.cfg` file.

Note that the `place` and `break` sounds are associated with the player, and
do not have a position. On the other hand the `use` and `fail` sounds are
associated with the mob, and only one of them can play at once (the second
sound to be played stops the first, see the music box object for an example
that takes advantage of this)

## Item Models

Description of the way every type of item should be rendered

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

```ini
[NAME]
texture = path
```
</details>

The file contains any number of `[NAME]` sections,
defining the model for the item type named `PACK.NAME`
that should be defined at `PACK/item_types.cfg`.

| key       | type      | default   | explanation   |
|-----------|-----------|-----------|---------------|
| texture   | path      | ""        | texture for the item |

### Textures

Textures are the names of files in the `packs/PACK/textures/` directory
that are applied to the billboard that represents the item.

All textures should be 16x16 pixels; for items you can provide taller textures
whose height is a multiple of 16 and they will all be loaded into the atlas,
but only the top one will be used for the item.

## Strings

Actual strings used to print the names of objects in a specified language.

<details>
<summary>packs/PACK/strings/LANG.cfg</summary>

```ini
NAME = "Name"
```
</details>

## Sounds

Sound effects used mostly by model files and occasionally by the UI.

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

```ini
[NAME]
path = "path/to/sound.ogg"
path = "path/to/sound.flac"
path = "path/to/sound.wav"
```
</details>

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

| key       | type      | default   | explanation   |
|-----------|-----------|-----------|---------------|
| path      | Path      | ""        | relative path for a sound file |

Several `path` entries can be provided, and if so the sound will consist on
several different samples; the one played each time is chosen at random.

Paths are relative to the `packs/PACK/sounds/` directory.

