Material Importer API

# Material Importer API

Generate s&box VMAT or TMAT material files with PBR texture maps from a single source image.

> **Queue API**: For queue position tracking and estimated wait times, use the [unified Queue API](/wiki/tools-api/queue-api) with `tool=material`.

## Endpoint

```
POST /api/tools/material
```

## Parameters

Send as `multipart/form-data`.

| Field | Required | Description |
|---|---|---|
| `image` | Yes | Source texture file (PNG, JPEG, WebP). Max 20MB. Generated textures preserve the uploaded image's original resolution and aspect ratio. |
| `mode` | No | `vmat` (default) or `tmat` |
| `name` | No | Texture name, used in filenames. Default: `texture` |
| `normalStrength` | No | Normal map intensity. 0.5 - 4.0, default 1.5 |
| `roughnessBase` | No | Base roughness value. 100 - 240, default 180 |
| `aoStrength` | No | Ambient occlusion strength. 0 - 1.0, default 0.3 |
| `metalness` | No | Metalness value. 0 - 1.0, default 0 |
| `uvScale` | No | Texture tiling scale. 0.25 - 50, default 1.0. Controls how many times the texture repeats. Sets TMAT `UVScale` or VMAT `g_vTexCoordScale`. |
| `transparent` | No | `true` to enable transparency. Extracts the alpha channel into a translucency map and adds `F_TRANSLUCENT 1` + `TextureTranslucency` to the VMAT. |
| `assetDir` | No | Asset directory path used inside the material file. Default: `materials/{name}/`. The ZIP is structured with this path so you can extract directly into your s&box project's `assets` folder. |

## Response

```json
{
  "ok": true,
  "downloadUrl": "/uploads/temp/123/rock_vmat.zip",
  "files": [
    "rock_color.png",
    "rock_rough.png",
    "rock_normal.png",
    "rock_height.png",
    "rock_ao.png",
    "rock.vmat"
  ]
}
```

When `transparent=true`, the files list also includes `rock_trans.png`.

The ZIP contains all files nested under the asset directory path (e.g. `materials/rock/rock_color.png`), so you can extract it directly into your s&box project's `assets` folder.

## Generated Textures

From a single source image, five PBR texture maps are generated:

- **Color (Albedo)** -- The original image, preserved at the uploaded dimensions
- **Normal** -- Sobel-filtered edge detection normal map
- **Roughness** -- Luminance-weighted grayscale with configurable base
- **Height** -- Grayscale luminance conversion
- **AO (Ambient Occlusion)** -- Brightness-based with adjustable strength
- **Translucency** (optional) -- Alpha channel extracted as grayscale, for transparent materials

## VMAT Format

Generated `.vmat` files use the `complex.vfx` shader with `F_SPECULAR 1`. When `transparent=true`, `F_TRANSLUCENT 1` and `TextureTranslucency` are added.

The `uvScale` parameter sets `g_vTexCoordScale` in the VMAT, controlling how many times the texture tiles across a surface.

## TMAT Format

Generated `.tmat` files include `UVScale` which controls terrain texture tiling. Higher values (e.g. 50) make the texture repeat more across the terrain surface.

## Presets

Use these parameter combinations for common material types:

| Preset | normalStrength | roughnessBase | aoStrength | metalness |
|---|---|---|---|---|
| Default | 1.5 | 180 | 0.3 | 0 |
| Shiny | 1.0 | 100 | 0.2 | 0 |
| Metal | 2.0 | 130 | 0.4 | 1.0 |
| Rough | 2.5 | 230 | 0.5 | 0 |
| Plastic | 0.8 | 140 | 0.15 | 0 |
| Glass | 0.5 | 100 | 0.1 | 0.05 |
| Fabric | 3.0 | 220 | 0.6 | 0 |
| Flat | 0.5 | 180 | 0 | 0 |

## Example: cURL

```bash
# Generate a metal material with transparency
curl -X POST https://api.sboxcool.com/tools/material \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@glass_panel.png" \
  -F "mode=vmat" \
  -F "name=glass_panel" \
  -F "metalness=0.05" \
  -F "roughnessBase=100" \
  -F "uvScale=2" \
  -F "transparent=true"

# Download the ZIP (use downloadUrl from response)
curl -o glass_panel_vmat.zip https://sboxcool.com/uploads/temp/123/glass_panel_vmat.zip
```

## Example: Python

```python
import requests

resp = requests.post("https://api.sboxcool.com/tools/material",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"image": open("rock_diffuse.png", "rb")},
    data={"mode": "vmat", "name": "rock", "normalStrength": "2.0",
          "uvScale": "4", "assetDir": "materials/rocks/granite/"})

data = resp.json()
zip_resp = requests.get(f"https://sboxcool.com{data['downloadUrl']}")
with open("rock_vmat.zip", "wb") as f:
    f.write(zip_resp.content)
```

## Example: Terrain Material (TMAT)

```bash
curl -X POST https://api.sboxcool.com/tools/material \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "mode=tmat" \
  -F "name=grass" \
  -F "uvScale=50" \
  -F "normalStrength=3.0" \
  -F "roughnessBase=220"
```