Skip to main content
skill CX Codex

blockbench-substance — Claude Code skill: Substance 3D pipeline

blockbench-substance connects Blockbench to Adobe Substance 3D: renders .sbsar materials into PBR maps, bakes AO and ID passes from the model, paints it in Painter and packs the maps into texture_set.json.

Apache-2.0 212 installs ★ 30 updated 2026-09-26

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-substance -a claude-code
Open on GitHub

What blockbench-substance does

This skill wires Blockbench to Adobe Substance 3D tools. Reach for it when a material already exists as .sbsar or .sbs, or when the model has to be painted in Painter. Plain texturing and derived normal maps belong to sibling skills, so most Blockbench jobs skip it.

scripts/sat_locate.py runs first and hunts for the binaries. Designer ships sbsrender, sbscooker, sbsupdater and substance3d_baker outside PATH; sbsmutator and the pysbs API arrive only with the standalone Substance Automation Toolkit. Find nothing and the skill stops there. After that sat_render.py turns a procedural material into PBR maps at a chosen pixel size, substance3d_baker bakes AO, curvature, position or ID passes from an exported model, and painter_remote.py drives Painter over its remote-scripting HTTP API. prep_maps.py packs MER, converts bit depth and writes texture_set.json.

A licensed Substance 3D install is required. Bake quality depends on UVs: per-face Auto UV on block formats stacks faces and ruins the result, so every face needs its own rectangle. Painter imports obj only, no glTF. Watch the bit depth too. AO and curvature PNGs often come out 16-bit, and a plain convert to 8-bit clips them to white; prep_maps.py convert handles that.

What it helps with

  • render a procedural .sbsar into 16 px block textures
  • bake an AO pass from an exported .glb
  • drive Painter over HTTP and pull the maps back
  • pack a Bedrock MER from separate metallic and roughness files
  • downsample 16-bit maps to 8-bit without clipping

Example prompts for the agent

  • Render material.sbsar at 32 px and apply the baseColor map to the model
  • Bake ambient occlusion from model.glb and multiply it into the colour texture
  • Pack a Bedrock MER from out/m_metallic.png and out/m_roughness.png into final/model_mer.png

How to install blockbench-substance

1Skills CLI (Vercel)

npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-substance -a claude-code

2Manually: put the files in place

~/.claude/skills/blockbench-substance/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/blockbench-substance/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about blockbench-substance

How to install blockbench-substance in Claude Code?

Run npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-substance -a claude-code. The skill file lands at ~/.claude/skills/blockbench-substance/SKILL.md.

What does blockbench-substance do?

It moves materials and maps between Blockbench and Substance 3D: .sbsar rendering, baked masks, painting in Painter, and packing into texture_set.json.

What do I need for blockbench-substance to work?

A licensed Substance 3D install. sbsmutator and the pysbs API come only with the standalone Substance Automation Toolkit, and Painter has to run with --enable-remote-scripting.

Source text

SKILL.md · Apache-2.0
---
name: blockbench-substance
description: Optional, advanced pipeline between Blockbench and Adobe Substance 3D (Designer, Painter and the Substance Automation Toolkit command lines). Use only when the user has Substance installed and asks for it — render .sbsar procedural materials to Blockbench-sized PBR maps with sbsrender, cook .sbs graphs with sbscooker, bake AO/curvature/normal/position/ID maps from a Blockbench export with substance3d_baker, drive Substance 3D Painter over its remote-scripting HTTP API to paint a Blockbench model and export Bedrock MER or glTF maps, and pack results into texture_set.json. Triggers on Substance, Substance 3D, Substance Designer, Substance Painter, SAT, Substance Automation Toolkit, sbsar, .sbs, sbsrender, sbscooker, sbsmutator, sbsupdater, sbsbaker, substance3d_baker, pysbs, bake AO for Blockbench, Painter export to Blockbench. Not needed for ordinary painting, generated textures or derived normal maps.
---

# Blockbench + Adobe Substance 3D

**Optional and advanced.** Most Blockbench work never needs this: paint with [blockbench-texturing](../blockbench-texturing/SKILL.md), generate with [blockbench-gpt-image-textures](../blockbench-gpt-image-textures/SKILL.md), derive normal/MER with [blockbench-albedo-to-pbr](../blockbench-albedo-to-pbr/SKILL.md). Use this skill only when the user asks for Substance or already has `.sbsar`/`.sbs`/Painter assets. It needs a licensed Adobe Substance 3D install. Load [blockbench-use](../blockbench-use/SKILL.md) first and [blockbench-pbr-materials](../blockbench-pbr-materials/SKILL.md) to assign results.

Substance produces **image files**. Blockbench stays the source of geometry and UVs. Every path ends with files imported through `create_texture` (`data`, `pbr_channel`) or `import_texture_set`.

## 0. Locate the tools

```bash
python scripts/sat_locate.py
```

Designer bundles `sbsrender`, `sbscooker`, `sbsupdater` and `substance3d_baker`, off PATH, in `C:\Program Files\Adobe\Adobe Substance 3D Designer\`. `sbsmutator` and the `pysbs` Python API come only with the standalone Substance Automation Toolkit. Painter is a GUI app driven over HTTP. If nothing is found, stop and tell the user; do not install Adobe software.

## Pick the path

| Goal | Tool | Reference |
|---|---|---|
| Procedural material (bricks, rust, leaves) as Blockbench textures | `sat_render.py` → `sbsrender` | [sat-cli.md](references/sat-cli.md) |
| Have a `.sbs` graph, need an `.sbsar` | `sbscooker` (`sbsupdater` first if old) | [sat-cli.md](references/sat-cli.md) |
| Edit/specialise a `.sbs` headlessly | `sbsmutator` (SAT only) | [sat-cli.md](references/sat-cli.md#sbsmutator) |
| AO / curvature / ID / position masks from the model | `substance3d_baker` | [baker.md](references/baker.md) |
| Hand-paint the model with smart materials | Painter + `painter_remote.py` | [painter.md](references/painter.md) |
| Pack Bedrock MER, convert bit depth, flip normal green, shrink | `prep_maps.py` | below |

## Workflow A: procedural material → Blockbench

```bash
python scripts/sat_render.py material.sbsar --out out --size 16 --seed 7 \
  --set Season=0.8 --normal-format directx
```

- `--size` is pixels; the script converts to log2 `$outputsize` (raw `sbsrender` needs `'$outputsize@4,4'` for 16 px). It creates `--out`; raw `sbsrender` exits 47 if the folder is missing.
- Read `inputs` from the JSON report, then set parameters by identifier. Unknown identifiers come back as `warnings`, because `sbsrender` ignores them silently.
- Match outputs to channels by `usages`: `baseColor`/`diffuse` → color; `normal`; `height`; `metallic` + `roughness` (or `glossiness`, inverted) + `emissive` → MER.
- Output is 8-bit by default. Tiling block textures render straight at 16/32 px. For atlases, render at the atlas size or larger and shrink.

## Workflow B: bake masks from the Blockbench model

1. **Fix UVs**: every face needs its own UV rectangle. Default per-face Auto UV on block formats stacks faces on top of each other and ruins the bake. See [baker.md § Prepare](references/baker.md#prepare-the-blockbench-mesh).
2. `export_model` → `codec_id: "gltf"`, `options: {"encoding": "binary"}`, `path: <abs>.glb` (or `obj`).
3. Bake at 8–16× density with **underscore** flags (the online docs show hyphens, which fail):
   ```bash
   substance3d_baker AmbientOcclusion.Raytraced model.glb --use_lowdef_as_highdef true --output_size 512,512 --output_path bake
   ```
4. `python scripts/prep_maps.py convert bake/*.png --out bake/64 --size 64` (16-bit → 8-bit, box downsample).
5. Use the maps as masks: multiply AO into the colour texture, or feed them to `sbsrender --set-entry` / Painter.

## Workflow C: paint in Painter, bring maps back

1. Fix UVs, then `export_model` with `codec_id: "obj"`. Painter cannot import glTF.
2. Start Painter with `--enable-remote-scripting` (never `--help`: it opens the app), then:
   ```bash
   python scripts/painter_remote.py --ping --wait 240
   python scripts/painter_remote.py --python-file scripts/painter_new_project.py --result \
     --set MESH=C:/work/model.obj --set NORMAL=DirectX --set RESOLUTION=1024 --set BAKE=1
   ```
3. The user paints in Painter (or you script layers after reading the local API docs).
4. Export and shrink:
   ```bash
   python scripts/painter_remote.py --python-file scripts/painter_bedrock_export.py --result \
     --set OUT=C:/work/painter_out --set NAME=model --set PRESET=bedrock --set SIZE_LOG2=9
   python scripts/prep_maps.py convert C:/work/painter_out/model*.png --out final --size 64
   ```
   `bedrock` gives `NAME.png`, `NAME_mer.png`, `NAME_normal.png` (DirectX). `gltf` gives ORM + OpenGL normal. Painter never exports below 128 px, and skips maps whose channel is absent. Trust the `files` list in the result.

## Pack and import

```bash
python scripts/prep_maps.py pack-mer --metallic out/m_metallic.png --emissive 0 --roughness out/m_roughness.png --out final/model_mer.png
python scripts/prep_maps.py texture-set --color model --mer model_mer --normal model_normal --out final/model.texture_set.json
```

Constants are 0–255; `--glossiness` replaces `--roughness` and is inverted. Then `import_texture_set` with the JSON path, or `create_texture` per file (`pbr_channel`: `color`/`normal`/`height`/`mer`) + `create_pbr_material`. Normal **or** height, never both.

## Conventions and verification

- **Normals**: Bedrock → DirectX (green-down), glTF/Java labPBR → OpenGL. Baker default is `directx`. A graph's `$normalformat` is graph-defined (one tested graph flipped red, not green), so compare renders or use `prep_maps.py convert --flip-green`. After import, raised features must read as raised in the Blockbench preview.
- **16-bit trap**: AO/curvature/height PNGs are often 16-bit; `PIL.Image.convert("L")` clips them to white. Use `prep_maps.py convert` or `--output-bit-depth 8`.
- **Paths**: pass `C:/...` paths to the executables; `/c/...` from Git Bash breaks `--alias`. Quote `'$outputsize@...'`.
- **Blockbench project safety**: note the project UUID before export and import, and confirm it before writing textures back.
- Check each imported map with `list_textures`/`get_texture` and a `capture_screenshot`. A blank-white or uniformly gray map means the bit depth, UV overlap or parameter was wrong. It is not a stylistic result.

© jasonjgardner · Apache-2.0 · jasonjgardner/blockbench-mcp-project

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set15

The whole set →
blockbench-hytale The blockbench-hytale skill walks an agent through Blockbench MCP tools for Hytale: formats, UVs, cube stretch, shading, attachments and animation. The Hytale Models plugin is required. CX Codex +1 930installs blockbench-plugins blockbench-plugins guides JavaScript plugin development for the Blockbench 3D editor, covering custom actions, UI dialogs, Vue panels, and undoable model edits. CX Codex +1 737installs blockbench-gpt-image-textures blockbench-gpt-image-textures generates Blockbench texture sheets, skins, and atlases with OpenAI GPT Image 2.5 on fal.ai using explicit UV layout prompts. CX Codex +1 294installs blockbench-new-model The blockbench-new-model skill turns a short brief into a Blockbench model, a render-ready Blender scene, and render files for stills or video. CX Codex +1 286installs blockbench-flipbook-textures blockbench-flipbook-textures is a Claude Code skill that plans and packs animated flipbook textures for Blockbench and Minecraft, turning sprite grids into vertical PNG strips. CX Codex +1 281installs blockbench-vanilla-textures blockbench-vanilla-textures pulls original Minecraft textures from Mojang's repository and applies them to Blockbench models. CX Codex +1 273installs blockbench-particles blockbench-particles adds Bedrock particle effects and bone locators to Blockbench models via MCP tools. Useful for fire, smoke, and magic VFX in Minecraft Bedrock and GeckoLib. CX Codex +1 259installs blockbench-albedo-to-pbr blockbench-albedo-to-pbr derives height, tangent-space normal, and packed MER maps from albedo textures for Blockbench PBR materials. CX Codex +1 248installs

Project sponsors

Companies that keep this analytics open