Utility_Apps/Blender/simple scripts/Bonsai Preferences Script/README.md

bonsai_prefs.py (startup script)

A Blender startup script that automatically applies your preferred Bonsai addon settings on every launch. Keeps the IfcOpenShell repo clean by storing machine-specific configuration outside the repo entirely.

---

How It Works

Blender loads all Python files in scripts/startup/ after addons are registered. This script uses a load_post handler (which fires after the startup .blend loads) to set Bonsai addon preferences once Bonsai has fully initialized.

Blender starts
  → addons registered
  → startup scripts executed (register() called, handler registered)
  → startup .blend loaded
  → load_post handler fires → preferences applied

---

Setup

1. Find your Blender user scripts path

In Blender → Scripting workspace, run:

for p in bpy.utils.script_paths(): print(p)

Look for a path under AppData\Roaming\Blender Foundation\Blender\ (Windows) or ~/.config/blender/ (Linux/macOS).

2. Copy the script

Place bonsai_prefs.py (or rename it) into:

<user scripts path>/startup/

3. Configure your settings

Open the script and edit the block at the top marked CONFIGURE YOUR SETTINGS HERE. Set any value to None to leave that preference unchanged.

4. Restart Blender

---

Configuration Reference

All settings live in the top section of the script:

Variable	Preference set	Default (this machine)
ASSETS_ROOT	Base path for all asset paths below	../../../../OD_Submodules
STYLESHEET_PATH	Default stylesheet	<ASSETS_ROOT>/assets/default.css
SCHEDULES_STYLESHEET	Schedules stylesheet	<ASSETS_ROOT>/assets/schedule.css
MARKERS_PATH	Markers SVG	<ASSETS_ROOT>/assets/markers.svg
SYMBOLS_PATH	Symbols SVG	<ASSETS_ROOT>/assets/symbols.svg
PATTERNS_PATH	Patterns SVG	<ASSETS_ROOT>/assets/patterns.svg
SHADING_STYLES_PATH	Shading styles JSON	<ASSETS_ROOT>/assets/shading_styles.json
PSET_DIR	Default psets directory	<ASSETS_ROOT>/psets/
DRAWING_FONT	Drawing font filename	CENTURY_GOTHIC.TTF
MAGIC_FONT_SCALE	Font scale factor	0.003
CLASSES_TO_WIREFRAME	Classes shown as wireframe on import	IfcVirtualElement, IfcSpace
LAYOUT_SVG_COMMAND	App to open layout SVGs	Inkscape
DECORATIONS_COLOUR	Decoration overlay colour (RGBA)	(1, 0, 0, 1) red

Relative paths (e.g. ../../../../OD_Submodules) are resolved relative to the open .blend file.

---

Debugging

View output: Window > Toggle System Console (Windows) after Blender starts.

Look for:

[bonsai_prefs] Applying prefs via addon key: 'bl_ext.user_default.bonsai'
[bonsai_prefs] Done.

Common issues:

Symptom	Cause	Fix
No output at all	Script not in the right startup/ folder	Run bpy.utils.script_paths() to find the correct path
Bonsai not found	Bonsai failed to load or key not matched	Check addon list in Blender preferences
prefs.doc not found	Bonsai version mismatch	Script will list available properties to help diagnose
Wrong Blender version launches	PATH finds a different blender.exe first	Use .\blender.exe in PowerShell, not blender.exe

---

Syncing to Multiple Blender Versions

If you have multiple Blender versions sharing the same user data folder, copy the script to each version's startup folder:

# PowerShell
foreach ($v in "4.4", "4.5", "5.1") {
    Copy-Item bonsai_prefs.py `
        "$env:APPDATA\Blender Foundation\Blender\$v\scripts\startup\bonsai_prefs.py"
}

# bash
for v in 4.4 4.5 5.1; do
  cp bonsai_prefs.py ~/.config/blender/$v/scripts/startup/
done

---

Why Not Edit the Repo?

The IfcOpenShell repo (ui.py) sets default values for new installs — changing them would affect all contributors and create noise in PRs. This script instead sets values at runtime, leaving the repo untouched.