# PETAFAB texture and skybox converter

Convert source images into the DDS textures a PETAFAB level uses. The converter generates mipmaps, packs ambient occlusion and emission, compresses materials, and convolves HDR environment lighting. Maps using built-in materials and skies do not need it.

## Downloads and setup

- [Windows x64 converter — AVX2/FMA CPU](https://sebastianaaltonen.com/assets/modding/PETAFAB-Level-Tools-Windows-x64.zip)
- [Mac converter — Apple silicon, macOS 26 or newer](https://sebastianaaltonen.com/assets/modding/PETAFAB-Level-Tools-macOS-arm64.zip)
- [Sandstone example and source images](https://sebastianaaltonen.com/assets/modding/PETAFAB-Cooker-Example.zip)
- [Complete level specification](https://sebastianaaltonen.com/assets/modding/petafab-level-format.md)

Each download includes `petafab-cook`, this guide and license notices.

Extract the ZIP and open a terminal in the extracted folder. On Windows, run `.\bin\petafab-cook.exe --help` in PowerShell. The Windows executable requires an x64 CPU with AVX2/FMA. On Apple silicon with macOS 26 or newer, extract with Finder/Archive Utility and run `./bin/petafab-cook --help`. The Mac executable is signed and notarized. Both platforms cook assets on the CPU.

The commands below use the Mac executable name. Substitute `.\bin\petafab-cook.exe` in PowerShell.

## Source images

| Input | Format and interpretation |
| --- | --- |
| Albedo | Tileable 1024 × 1024 PNG, 8-bit or 16-bit RGB in sRGB. Alpha is ignored; supply AO and emission separately. |
| Normal | Tileable 1024 × 1024 PNG, 8-bit or 16-bit RGB, linear tangent-space **DirectX (Y−)** normals with positive Z. |
| AO | Tileable 1024 × 1024 PNG, 8-bit or 16-bit linear grayscale: black = fully occluded, white = unoccluded. |
| Emissive mask | Tileable 1024 × 1024 PNG, 8-bit or 16-bit linear grayscale: black = no emission, white = full emission. |
| Height | Optional tileable 1024 × 1024 PNG, 8-bit or 16-bit linear grayscale displacement. White is higher than black. |
| Sky panorama | EXR or Radiance HDR, native 2:1 equirectangular image, from 4096 × 2048 up to 32768 × 16384. Scene-linear RGB with linear sRGB primaries; finite nonnegative radiance up to 64512. |

Material sources must already be 1024 × 1024; the converter rejects other sizes. Each tile covers one metre in the game. Export normal maps, masks and height as data, without an sRGB transfer function. Export skies without a display/view transform or tone mapping. Use PNG for the documented material workflow; EXR/HDR are sky inputs.

EXR input supports scanline and tiled images with full-resolution `R`, `G` and `B` channels in the first image part. Deep EXR images are not supported.

### DirectX versus OpenGL normals

**Use DirectX (Y−), not OpenGL (Y+).** Red and green store tangent X and Y, encoded from −1…+1 into 0…1; blue must encode positive Z. The converter preserves the imported green-channel direction. For an OpenGL normal map, invert **only green** before cooking: `G = 255 - G` for an 8-bit PNG, or `G = 65535 - G` for 16-bit. Do not flip the image vertically. Normals generated from height already use the required convention.

## Materials from albedo, AO and emission

Supply the source images explicitly:

```sh
./bin/petafab-cook material --name panel --albedo panel.png --normal panel_normal.png --ao panel_ao.png --emission panel_emissive.png --out MyLevel/textures
```

This writes `panel_color.dds` (BC7 sRGB) and `panel_normal.dds` (BC5 linear), both 1024 × 1024 with all 11 mip levels down to 1 × 1. Albedo is filtered in linear light; normal mips are renormalized. AO and emission are filtered separately, then packed into color alpha at each mip. The surface preparation also blends opposite albedo and mask edges for tiling; provide tileable source images and normals.

All inputs except albedo are optional. Without normal or height, the surface gets flat normals. Without AO or height, it is unoccluded. Without an emission mask, it does not emit.

Add an entry to the level's `materials` array:

```json
{
  "id": "panel",
  "color": "textures/panel_color.dds",
  "normal": "textures/panel_normal.dds",
  "roughness": 0.45,
  "metallic": 0.8,
  "emission": 4
}
```

Brushes refer to `"material": "panel"`. Roughness and metallic are uniform numbers from 0 to 1. The emissive mask multiplies the material's HDR emissive color: surface RGB × `emission` strength (0…64, default 0). Set a positive strength for the mask to glow. There are no separate runtime AO, emission, roughness, metallic or ORM texture paths in `level.json`.

### Optional height workflow

If you have a displacement/height map, the converter can derive both normals and AO from it:

```sh
./bin/petafab-cook material --name stone --albedo stone.png --height stone_height.png --relief 0.008 --out MyLevel/textures
```

`--relief` is the black-to-white height difference in metres: `0.008` means 8 mm (default 0.01; allowed range 0…1). Height adds surface shading detail; it does not change the level's brush geometry. Do not pass `--normal` and `--height` together. Add `--ao stone_ao.png` to override height-derived AO, or `--emission stone_emissive.png` to add emission. A height map is not needed when supplying your own normal and AO maps.

### Packed color alpha

Color alpha contains ambient occlusion in **[0, 0.5]**: 0 = fully occluded, 0.5 or above = unoccluded. Emission uses **[0.5, 1]**: 0.5 or below = none, 1 = full emission. Emissive texels are unoccluded. The converter handles this packing from separate input maps.

The exact 8-bit encoding before BC7 compression is AO × 127 for non-emitting texels, or 128 + emission × 127 for emitting texels. Alpha 127 and 128 are both neutral. Emission takes precedence where both masks are present; independent AO and emission cannot occupy the same texel. The shader combines texture AO with runtime ambient occlusion.

## HDR skyboxes and lighting

Supply your own EXR or Radiance HDR panorama:

```sh
./bin/petafab-cook sky --name dusk --panorama dusk.exr --out MyLevel/sky
```

The cooker bakes lighting on the CPU. The converter resamples the panorama to cubemap faces, convolves diffuse lighting, prefilters GGX reflections for increasing roughness, and compresses all three cubemaps as unsigned BC6H:

| Output | Face size | Mip levels | Purpose |
| --- | --- | --- | --- |
| `dusk_sky.dds` | 1024 × 1024 | 11 | Visible sky |
| `dusk_diffuse.dds` | 16 × 16 | 1 | Convolved diffuse environment lighting |
| `dusk_specular.dds` | 256 × 256 | 7 (down to 4 × 4) | GGX reflections, roughness 0 through 1 |

Add this top-level field to `level.json`:

```json
"skybox": {
  "sky": "sky/dusk_sky.dds",
  "diffuse": "sky/dusk_diffuse.dds",
  "specular": "sky/dusk_specular.dds"
}
```

All three paths are required. The converter writes DDS files; it does not edit `level.json`. Use the level's `sun` fields for direct sunlight. The environment supplies the sky, indirect illumination and reflections.

## Batch recipes

Keep source images under `MyLevel/source/` with a `cook.json` recipe. Image paths are relative to the recipe; output paths are relative to the `--out` level folder.

```json
{
  "version": 1,
  "materials": [
    {"name": "panel", "albedo": "panel.png", "normal": "panel_normal.png", "ao": "panel_ao.png", "emission": "panel_emissive.png"},
    {"name": "stone", "albedo": "stone.png", "height": "stone_height.png", "relief": 0.008}
  ],
  "sky": {"name": "dusk", "panorama": "dusk.exr"}
}
```

```sh
./bin/petafab-cook build MyLevel/source/cook.json --out MyLevel
```

Omit `sky` for a material-only recipe or `materials` for a sky-only recipe. A recipe accepts up to 32 materials with unique names of 1–64 ASCII letters, digits, underscores or hyphens. Materials require `name` and `albedo`; optional fields are `normal`, `height`, `relief`, `ao` and `emission`, with the same rules as the CLI. The sky entry requires `name` and `panorama`. Recipe version 1 describes the converter job; the game's `level.json` uses version 2.

## Try the example and iterate

Extract the sandstone example download and copy its `example/` folder beside the converter's `bin/` folder. It contains the albedo and height PNGs, recipes, a modified Spillway map, schema and thumbnail.

```sh
./bin/petafab-cook build example/source/cook.json --out example
./bin/petafab-cook package example/level.json --output MyLevel.zip
```

In PETAFAB, choose **Workshop → My Levels → Play Folder** and select `example/`, or use **Play Local ZIP**. After editing and recooking, press **F5** (or **Fn + F5** on Mac keyboards) to reload the local map, textures and sky. For ZIP testing, rebuild the selected archive before reloading.

The optional `example/source/sky.json` recipe expects your own `dusk.exr` beside it. Run `build example/source/sky.json --out example`, then add the `skybox` field shown above to the example level. Package again to include the new files.

The `package` command includes `level.json`, referenced runtime assets and `preview.jpg` (JPEG under 1 MiB). Editable source images are excluded. Keep the source folder yourself and distribute it separately if you want others to edit your assets. A developer build of PETAFAB can validate the finished folder with `petafab --check-level MyLevel/level.json`.
