---
title: Preferences
order: 10
---

Chisel's addon preferences live in `Edit → Preferences → Add-ons → Chisel`. The panel is split into three tabs (*Info*, *Theme*, and *Debug*) covering library status and GPU memory, gizmo appearance, and troubleshooting tools.

## Where settings live

Chisel settings are spread across a few places. Knowing which is which saves time hunting for them.

- **Addon preferences** *(this page)*: `Edit → Preferences → Add-ons → Chisel`. Library status, GPU backend, brick pool, theme colors, debug tools.
- **Scene render settings**: *Render Properties* panel. Engine quality, performance, matcap, display, gizmo visibility, baking. See [Render Engine](render-engine/index.md).
- **Per-object settings**: *Object Properties → SDF*. Primitive parameters, bake direction. See [Interface: Panels](interface/panels.md).
- **Modifiers**: the *Modifier* tab. See [Modifiers](modifiers/index.md).

## Info

The *Info* tab surfaces the things most likely to bite a fresh install, plus the one memory setting worth knowing about.

### Native library

The *armesher* native library powers SDF evaluation, mesh conversion, and proxy baking. When it loads cleanly the tab shows `armesher 4.1.0` with a checkmark. If an update is pending or a version mismatch is detected, click **Update Native Libraries** and restart Blender.

### GPU Backend

A line reads the backend Blender itself is running on: `Vulkan`, `OpenGL`, or `Metal`. On Blender 4.5, OpenGL is the platform default and works, though Vulkan is 5–10× faster; switch it in `Edit → Preferences → System → Backend`.

On **Blender 5.x** the viewport defaults to Vulkan, so seeing OpenGL there usually means Blender's Vulkan start-up failed, and the same driver would take Chisel's renderer down with it. The tab turns red, *"Blender is on the OpenGL backend — Chisel requires Vulkan"*, and offers an **Open System Preferences** button that jumps straight to the backend setting.

### Brick Pool

The GPU memory reserved for the sparse detail bricks every shape bakes into.

- **Auto (recommended)** *(default)*: sized from the card's memory at startup: about 0.6 GiB on a 4 GB card, up to 1.9 GiB on large ones. The line beneath reports what Auto picked for this session.
- **0.6 GiB / 1 GiB / 1.5 GiB / 2 GiB**: fixed tiers; 1 GiB is what every earlier version used.

Changes take effect after restarting Blender. Raise the tier if *Render → Quality* shows *Brick memory full* at a high [Subdivision Level](render-engine/quality.md#brick-detail).

### Schema hash

Chisel checks that the loaded native wheel matches the addon via a build-hash handshake. A match shows `Schema hash: … (matched)`. A mismatch shows a "rebuild wheels" notice instead of failing silently. Reinstall the extension or rebuild the wheels, then restart Blender.

### Links

Buttons for the **Documentation** site and the **Discord** community.

## Theme

Modal guides, gizmo dots, and arc rings all read from the theme. Each operation has its own color so you can identify a modifier at a glance.

### Modal + arc colours

- **Rounding**: primitive edge fillets
- **Bevel**: vertical edges on prism / trapezoid / oblong
- **Blend**: boolean blend radius
- **Carve**: carve offset guide, arc and dot
- **Emboss** / **Engrave**: emboss and engrave seam guides

### Modifier dots

- **Boolean Difference** / **Union** / **Intersect**
- **Push / Pull**: emboss / engrave
- **Modifier (Other)**: fallback for other modifier types

### Sizing

- **Dot Radius**: gizmo dot size (default `0.05`, range `0.01–0.5`). The point editors (Ngon, Sweep, Lattice, Bisect) scale from it too.
- **Arc Inner Radius**: inner radius of the arc gizmo (default `1.60`, range `0.5–5.0`)
- **Arc Width**: gizmo arc thickness (default `0.03`, range `0.005–0.5`)
- **Arc Gap**: gap between concentric arc rings (default `0.15`, range `0.0–1.0`)

## Debug

Developer and troubleshooting tools. You only need this tab when chasing a problem or filing a bug report.

- **Verbose Logging**: off by default, so the console stays quiet during normal use. Turn it on to print pipeline cache hits, render progress, and GPU init timings to Blender's console. Errors and real warnings always show regardless.
- **Lattice Fold Guard**: on by default. Stops a [Lattice](modifiers/lattice.md) cage point at the position where the deformation would fold over itself; past a fold the surface breaks into speckled holes and the render slows to a crawl. Turn it off only to reproduce that state deliberately.
- **Performance Profiler**: prints one frame breakdown to the System Console about every 60 frames: frame time, where the CPU and GPU spent it, and the native render phases. **Export Profile** writes the current window to a text report and JSON (the path is copied to the clipboard); **Reset** clears the window before a timed run. Diagnostic only.
- **Dump Diagnostics**: writes a report (adapter, version, cache state, GPU memory budget, every `CHISEL_*` environment switch) to a temp file and copies the path to the clipboard. Attach it to bug reports.
- **Clear Pipeline Cache**: deletes the saved shader cache so the next session compiles cold. It also re-enables the cache if Chisel switched it off after a driver crashed inside it (see below).
- **Restart Renderer**: drops the live renderer so the next frame rebuilds it, reusing the GPU device. Does not reload the native library.

> First viewport use after a fresh install or driver swap will pause briefly while shaders compile. See the [shader compilation note](index.md#first-run-shader-compilation) on the home page for the full picture.

### The shader cache and driver crashes

Chisel saves the driver's compiled shaders so the next session starts warm. Some drivers (Intel's Vulkan driver in particular) crash inside that cache. If that happens, Chisel notices on the next launch, turns the cache off and deletes it, so you get a slower first session instead of a Blender that cannot start. *Clear Pipeline Cache* turns it back on when you want to try again.

## Environment switches

A handful of settings are read from environment variables, either from your shell or from the `chisel.env` file next to the add-on's `__init__.py`. The file takes only `CHISEL_*` switches set to `0` or `1`; every line in it is commented out and shows the built-in default, so it doubles as the reference. A variable set in the shell wins over the file, and numeric values (budgets, sizes) go in the shell only. Restart Blender after changing one.

| Variable | Default | What it does |
|---|---|---|
| `CHISEL_BACKEND` | auto | Graphics backend for Chisel's renderer: `vulkan`, `metal`, `dx12`, `gl`. Independent of Blender's own backend setting |
| `CHISEL_BRICK_POOL_PZ` | from the Brick Pool preference | Brick pool size; an explicit value overrides the preference |
| `CHISEL_BRICK_POOL_F16` | auto | Half-precision brick pool. Auto turns it on below a 6 GiB budget |
| `CHISEL_MESH_GRID_CACHE_MB` | `512` | System-memory cap for cached mesh-SDF grids |
| `CHISEL_PIPELINE_CACHE` | `1` | Save compiled shaders across sessions. `0` only for a driver that crashes inside its own cache |
| `CHISEL_SCREEN_SPACE_NORMALS` | `0` | A faster approximate normal for Rendered shading. Off because it saved nothing on real scenes |
| `CHISEL_AUTO_CELL` | `1` | The native side of [Auto Cell Size](render-engine/performance.md#auto-cell-size) |
| `CHISEL_VIEWPORT_MESH_SNAPSHOT`, `_NAV`, `_CHUNKS` | `1` | The cached mesh used for [camera navigation](render-engine/performance.md#camera-navigation). Set to `0` to march every frame instead |
| `CHISEL_LATTICE_FOLD_GUARD` | from the preference | Overrides the Lattice Fold Guard preference when set |
| `CHISEL_VERBOSE` | off | Same as *Verbose Logging* |

## See also

- [Render Engine](render-engine/index.md): per-scene render settings
- [Interface: Gizmos](interface/gizmos.md): where the gizmo theme is visible
- [Keymap](keymap.md): tool-local and global shortcuts