Ryan Schultz
348bd6b051
Adds bonsai_prefs.py — a Blender startup script that applies personal Bonsai addon settings on every launch via a load_post handler, keeping machine-specific config out of the IfcOpenShell repo. All user settings are in a single CONFIGURE block at the top of the file. Handles Blender extension-style addon keys (bl_ext.user_default.bonsai), ghost addon entries with None preferences, and the register() requirement introduced in Blender 4.2+. Generated with the assistance of an AI coding tool.
124 lines
3.9 KiB
Markdown
124 lines
3.9 KiB
Markdown
# 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:
|
|
```python
|
|
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
|
|
# 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
|
|
# 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.
|