# Textures

Every level has its own set of textures, stored on **texture pages** of 256×256 pixels. A
*texture* is a rectangle on one of those pages; faces of tiles and brushes refer to a texture by
its **number**. The editor lets you see all of them, import your own pictures, animate them and
paint them onto faces.

## Texture basics

* A level has up to **127 pages**. Each page has one *blend class* (opaque, cut-out,
  semi-transparent …); every texture on it should have the same class.
* Textures are numbered: `#221` is texture 221 of the level. In brush texture fields you can type
  `#221` or a name. The names (`grass`, `stone`, `bark` …) are those of the village textures.
  On another base level a name means the same picture wherever that level has it (Village 2 and 3
  have most of them); names the base level does not have are left out of the texture grid, and a
  brush that uses one is skipped with a warning.
* Brushes can also use flat colours (colour names, or `rgbRRGGBB`).
* The game shows textures in **15-bit colour** (5 bits per channel) with 1 bit of transparency,
  so gradients get coarser and soft edges become hard.
* Texture entries are never deleted, because faces and object models refer to them by number.
  An unused texture can be reused by moving its rectangle.

## Texture manager

Open it with the **Textures** tab of the bottom dock, **View → Panels → Texture manager**
(**Ctrl+Shift+T**), or the **Window** button for a large separate window.

![The texture manager](img/tex_manager.jpg)

### Pages

The left list shows every page with a thumbnail, its number and its blend class. Right-click a
page for:

* **Export page as PNG…** – saves the whole page,
* **Replace page from PNG…** – loads a picture into the whole page (scaled to 256×256 and reduced
  to the page's blend class).

### Atlas

The middle shows the selected page with every texture rectangle:

| Colour | Meaning |
|---|---|
| white | used texture |
| red | unused texture |
| cyan | animated texture |
| orange | the current texture, with 8 handles |

* Click a rectangle to make it the current texture (the smallest one under the cursor wins).
* Drag inside the current rectangle to **move** it, drag a handle to **resize** it. Every face
  using the texture follows; each drag is one undo step.
* The mouse wheel zooms; tooltips show size and usage.
* Double-click starts the **Paint texture** tool with that texture.

### Texture table

The table lists **#**, a preview, **Name** (editable), **Page**, **Rectangle**, **Blend**,
**Faces** (faces of tile models plus brushes using it), **Models** (tile models using it) and
**Anim** (its animation, or "frame" if it is a frame of another texture's animation).

The **Show** box filters the list:

| Filter | Lists |
|---|---|
| **All textures** | everything |
| **On this page** | textures of the selected page |
| **Used** | textures on faces, brushes or in animations |
| **Unused** | the others |
| **Animated** | textures with an animation |
| **Imported** | textures you imported |

**Name or #** searches by name or number. Double-click a row to paint with that texture.

> **Note:** Object models (characters, pickups) also use textures from this table, but they are not
> counted. "Unused" means *not used by tiles, brushes or animations*.

### Toolbar

| Button | Action |
|---|---|
| **Import…** | import PNG/JPG images as new textures (see below) |
| **Replace pixels…** | put a new picture into the selected texture's rectangle |
| **Export PNG…** | save the selected texture as a PNG file |
| **Paint** | start the Paint texture tool with the selected texture |
| **Window** | open the texture manager in its own large window |

### Texture tab

Details of the current texture:

| Field | Meaning |
|---|---|
| **Name** | name shown in the editor, also usable in brush texture fields |
| **X / Y** | top-left corner of the rectangle on the page (pixels) |
| **W × H** | size in pixels – the engine maps the whole rectangle onto a quad |
| **Blend** | blend class (the texture flags); the page's class should match |
| flags | the raw flag value |

Below it a usage line (faces, models, brushes, animations) and two buttons:

* **Duplicate** – a new texture entry with the same rectangle, e.g. as the starting point for an
  animation frame,
* **Select users** – selects the tiles whose models use the texture.

## Texture animations

The **Animation** tab animates the current texture. The game supports two kinds:

* **Flip-book** – the texture is replaced by a sequence of frame textures in turn (torches,
  flags, water in the original levels).
* **Scroll** – the picture moves vertically inside a band of the page (rivers, lava).

![The Animation tab with a flip-book](img/tex_anim.jpg)

**Create animation** starts one (a flip-book begins with the texture itself; add frames with
**+**), **Remove animation** removes it.

| Field | Meaning |
|---|---|
| **Type** | **Flip-book**, **Scroll up** or **Scroll down** |
| **Frame delay** | game frames each flip-book frame stays (0 = change every frame; the game runs at about 30 frames per second – the label shows the resulting frames/s) |
| **Back and forth** | play forwards then backwards instead of looping |
| **Band height** | scroll: height of the page area the picture wraps in (usually the texture height) |
| **Speed (px/frame)** | scroll: pixels per game frame |
| **Top row (v0)** | scroll: first page row of the band (usually the texture's top edge) |
| **Frames** | flip-book frames: **+** adds a texture by number (the current texture is suggested), **−** removes, **◀ ▶** move the selected frame |

A live preview runs at game speed. The 3D viewport does not animate textures; the preview and the
game do.

> **Tip:** To make a new flip-book: import all frames as textures, select the first one, **Create
> animation**, then add the others with **+** by their numbers.

## Importing textures

**File → Import texture…** or **Import…** in the texture manager opens the **Import textures**
dialog for one or more images (PNG, JPG, BMP, GIF). The two previews show the picture as it is
(**Original**) and as the game will show it (**In the game (15-bit)**).

![The Import textures dialog](img/tex_import.jpg)

| Option | Meaning |
|---|---|
| **Size (longest side)** | 16, 32, **64**, 128, 256 or **Original** (up to 256); the aspect ratio is kept, rectangles need not be powers of two |
| **Blend class** | how the texture is drawn (table below); the description appears below the box |
| **Transparent below alpha** | pixels less opaque than this become fully transparent (default 64) |
| **Keep half-transparent pixels** | pixels between the cut and 75 % opacity stay half transparent instead of solid |
| **Transparent colour** | **None**, **Magenta (FF00FF)** or **Top-left pixel**: a colour that becomes transparent, for images without an alpha channel |
| **Dither (smoother gradients in 15-bit colour)** | ordered dithering against colour banding |
| **Pack into free space of existing pages** | use unused areas of pages of the same blend class before adding new pages |
| **1-pixel border (against seams)** | repeats the edge pixels around the texture, so filtering never shows the neighbour's pixels |

### Blend classes

| Class | Use for | What it does |
|---|---|---|
| **Opaque** | walls, floors, most things | solid; transparent pixels become black |
| **Cut-out** | leaves, fences, grids | fully transparent pixels, everything else solid |
| **Semi-transparent** | glass, water, smoke | half-transparent pixels blend 50 % |
| **Additive glow** | light, fire, sparkles | adds its colour to what is behind it |
| **Darken (mode 3)** | shadows | darkens what is behind it |

The editor guesses the class from the image (alpha channel or not). Imported textures are new
texture numbers; the status bar names them. The whole import is one undo step.

> **Engine limit:** at most 127 texture pages. The **Check** reports more pages as an error.

### Replacing pixels

**Edit → Replace texture pixels…** or **Replace pixels…** puts a new picture into the current
texture's rectangle – every face using the texture changes at once. The dialog is the same, with
the size fixed to the texture's rectangle. Useful to repaint an original texture (a sign, a
poster) without touching any faces.

## Paint texture tool (M)

The **Paint texture** tool (**M**, toolbar, or double-click a texture in the manager) puts the
current texture onto faces.

![Painting a texture onto a tile face](img/tex_paint.jpg)

* **Hover**: the face under the cursor gets a white outline; the status bar shows the model, face
  number, current texture and face flags (and "model shared by n tiles").
* **Click**: gives the face the current texture. The clicked face stays selected (orange) for
  the buttons below.
* **Shift+click** picks the texture of a face (eyedropper). **I** or **Edit → Texture
  eyedropper** does the same for the next click.

Options bar:

| Control | Meaning |
|---|---|
| swatch | the current texture – choose one in the texture manager or pick it from a face |
| eyedropper button | the next click picks a texture (**I**) |
| scope | **Face** (only the clicked triangle), **Same texture in model** (all faces of the model that had the same texture), **Whole model** |
| rotate button | turns the texture on the selected face (cycles its corners; on brushes: the brush's texture rotation) |
| mirror button | mirrors the texture on the selected face |
| half button | shows the other half of the texture rectangle on the selected triangle |
| **Unique** | if the clicked tile shares its model with other tiles, give it its own copy first |

> **Note:** Original tiles often share one model – a hundred grass tiles may use the same one.
> Without **Unique**, painting one of them changes all of them. With **Unique** only the clicked
> tile changes (it gets its own copy of the model, which adds data to the level).

**Brushes**: clicking a brush sets the texture of the side you click – the **top** texture when
you click the top, **bottom** for the underside, otherwise the **side** texture (for fences,
trees and pillars the first texture parameter, such as the post or trunk). The rotate button
then turns the texture of the last painted brush.

> **Engine limit:** each triangle shows one half of its texture rectangle – that is why "other
> half", rotate and mirror exist instead of free UV editing. Object models cannot be painted.

## Textures in the game

![An imported texture in the game](img/tex_game.jpg)

## Limits

* Texture entries are never deleted; reuse unused ones by moving their rectangle.
* Object models' textures are not counted as "used" and their faces cannot be painted.
* The importer does not change the class of an existing page; it never packs into a page of
  another class.
* Imported meshes create their textures automatically (see
  [Importing meshes](07-meshes.md)).