Preferences

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.
Per-object settings: Object Properties → SDF. Primitive parameters, bake direction. See Interface: Panels.
Modifiers: the Modifier tab. See Modifiers.

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.

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.

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 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 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
`CHISEL_VIEWPORT_MESH_SNAPSHOT`, `_NAV`, `_CHUNKS`	`1`	The cached mesh used for 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