A Blender add-on that generates a continuously morphing parade of procedural torus knots with configurable shaders, geometry transitions, and render-farm export — all driven by a non-destructive playlist inside Blender's N-panel.

Features

Playlist-based animation — add, remove, reorder any number of knots; each entry controls its own topology, geometry, material, and animation rates
Smooth transitions — configurable per-knot morph windows with Linear, Quadratic In/Out, or Smoothstep easing
Audio-reactive hooks — drive the global Reactivity factor from a sound driver to pulse spin, height, and scale rates in sync with audio
20 built-in shader presets — Gloss Blue, Neon Glow, Metallic, Glass, Hologram, Lava, Iridescent, Matte Clay, Ghost, Car Paint, Chrome, Ruby Glass, Frosted Ice, Lichen Rough, Copper Patina, Zebra Stripes, Wood Veneer, Carbon Fiber, Pearlescent, Plasma Glow
Random playlist generator — configure min/max ranges for every parameter and generate an entire playlist in one click
Bake & Export — bake the procedural animation to a standalone .blend with per-frame mesh visibility keyframes; no addon required at render time; supports split-file export for SheepIt / distributed render farms
Blender 5.0+ native — uses the layered Action API (action → layers → strips → channelbag → fcurves) and Blender 5 Principled BSDF input names directly

Requirements

Requirement	Version
Blender	5.0 or later
Blender built-in addon	Add Curve: Extra Objects (auto-enabled by the script)

Installation & Running

Option A — Persistent Add-on (Recommended for Users)

Download a release zip (or run package_addon.py to build one).
In Blender, go to Edit → Preferences → Get Extensions → Add-ons (or Install from Disk... from the top right gear menu).
Select the zip file (e.g. releases/pr3tz_v2.0.0.zip).
Enable "Pr3tz" from the list.
Access the controls in the 3D Viewport → N-panel (sidebar) → Pr3tz tab.

Option B — Symlink (Recommended for Developers)

To test and develop with live code updates without having to reinstall the addon:

Open your terminal as Administrator (on Windows) or with standard user permissions (on Linux/macOS).

Run the appropriate command for your OS/shell to link the pr3tz/ folder directly to Blender's local addons directory (replace path with your Blender version/path if needed):

PowerShell (Windows):

New-Item -ItemType SymbolicLink -Path "$env:APPDATA\Blender Foundation\Blender\5.0\scripts\addons\pr3tz" -Value "$PWD\pr3tz"

CMD (Windows):

mklink /d "%APPDATA%\Blender Foundation\Blender\5.0\scripts\addons\pr3tz" "%CD%\pr3tz"

Bash (Linux):

ln -s "$PWD/pr3tz" "$HOME/.config/blender/5.0/scripts/addons/pr3tz"

Bash (macOS):

ln -s "$PWD/pr3tz" "$HOME/Library/Application Support/Blender/5.0/scripts/addons/pr3tz"

Enable "Pr3tz" in Blender's Preferences.
Press F3 and search for "Reload Scripts" to reload changes instantly.

Option C — Bootstrap Loader (No Installation)

Since Python relative imports fail when running individual module files directly, you can run the bootstrap script from the repository root:

Open Blender.
In the Text Editor, open run_script.py.
Click Run Script (or press Alt+P).

Alternatively, load it directly from the terminal:

PowerShell (Windows):

& "C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python run_script.py

CMD (Windows):

"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python run_script.py

Bash (Linux):

blender --python run_script.py

Bash (macOS):

/Applications/Blender.app/Contents/MacOS/Blender --python run_script.py

Quick Start

Install and enable the add-on (see above).
In the N-panel, click "Populate Default List" to load 10 example knots.
Press Space to play the animation and watch the knots morph.
Select any knot in the playlist to tweak its topology, shader, and animation rates in the panel below.
Use "Generate Playlist" with the randomiser settings to create entirely new playlists procedurally.

Baking for Render Farms

The Bake & Export button (bottom of the Pr3tz panel) converts the procedural animation into a standalone .blend:

Set your frame range in the Timeline.
Click Bake & Export for Render Farm and choose an output path.
Optional: enable Split Export and set Frames Per File for multi-chunk jobs.
Submit the resulting .blend file(s) to your render farm — no addon needed on the farm.

Repository Layout

├── pr3tz/               # Main add-on package folder
│   ├── __init__.py      # Add-on entry point, bl_info, register/unregister
│   ├── constants.py     # Default playlist configs, camera/light positions, name tags
│   ├── types.py         # KnotConfig TypedDict (shared data contract)
│   ├── compat.py        # Headless align_matrix fix and other Blender compat patches
│   ├── properties.py    # Blender PropertyGroups (KnotItem, KnotGlobalSettings, …)
│   ├── operators.py     # KNOT_OT_* operators (Add, Remove, Move, Generate, Fit…)
│   ├── ui.py            # N-panel, UILists, draw_knot_properties()
│   ├── geometry.py      # _make_torus_knot() — pure parametric NURBS, no bpy.context reads
│   ├── materials.py     # 20 shader builders, material cache, blend/transition system
│   ├── handler.py       # @persistent frame_change_post handler, easing, playlist timing
│   ├── scene_setup.py   # setup_scene() — camera, area light, world, render settings
│   └── bake_export.py   # KNOT_OT_BakeExport — bake to standalone .blend
├── run_script.py        # Bootstrap runner for Text Editor / CLI execution
└── package_addon.py     # Automated packaging tool to create release .zip files

Key Parameters (KnotItem)

Parameter	Description
p / q	Torus knot winding numbers — must be coprime for a true knot
Major / Minor radius	Size of the torus; switch to Ext/Int mode for exterior/interior control
Bevel Depth	Tube thickness of the curve
Multiple Links	Render all p link components separately
Transition Frames	Number of frames to morph into the next knot
Cycle Rate	Per-knot speed multiplier (>1 lingers, <1 advances faster)
Spin / Rev Phase Rate	Animate tube or orbital rotation over time
Height Pulse Rate	Oscillate the torus height — creates a breathing warp effect
Scale Rate / Amplitude	Per-knot scale oscillation frequency and amplitude
Shader Preset	One of 20 built-in material presets
Project Material	Use any material already in the .blend file

Global Settings

Setting	Description
Frames per Knot	Base display duration for each playlist entry
Curve Resolution	NURBS subdivision — higher = smoother curve
Bevel Resolution	Tube cross-section segments
Global Scale	Uniform scale applied to all knots
Global Speed	Multiplies the effective frame counter — keyframeable
Animation Phase	Frame offset before all calculations — keyframeable
Reactivity	Scales all per-knot animation rates; wire a driver here for audio-reactive animation

Shader Presets Reference

ID	Description
`GLOSS_BLUE`	Classic glossy blue dielectric
`NEON_GLOW`	Emissive neon with bloom-ready strength
`METALLIC`	Polished gold / copper metal
`GLASS`	Refractive clear glass
`HOLOGRAM`	Sci-fi translucent hologram
`LAVA`	Subsurface-scattered lava with emission
`IRIDESCENT`	Rainbow thin-film interference
`MATTE_CLAY`	Diffuse clay for concept previews
`GHOST`	Semi-transparent emission ghost
`CAR_PAINT`	Pearlescent automotive clearcoat
`CHROME`	Mirror-finish chrome
`RUBY_GLASS`	Deep red refractive glass
`FROSTED_ICE`	Rough refractive ice
`LICHEN_ROUGH`	Organic rough surface
`COPPER_PATINA`	Oxidised copper green
`ZEBRA_STRIPES`	Procedural stripe pattern
`WOOD_VENEER`	Procedural wood grain
`CARBON_FIBER`	Woven carbon fiber weave
`PEARLESCENT`	Angle-dependent pearl sheen
`PLASMA_GLOW`	High-energy plasma emission

Release Packaging

We provide an automated script to pack the addon for release:

PowerShell / CMD (Windows):

python package_addon.py

Bash (macOS/Linux):

python3 package_addon.py

This script:

Parses the release version dynamically from pr3tz/__init__.py.
Zips the pr3tz/ directory into releases/pr3tz_v<version>.zip.
Automatically excludes developer files (__pycache__, .git, .pyc, etc.) so that the release package remains clean.

Contributing

Pull requests are welcome. For major changes please open an issue first.

Development setup

To configure your workspace for active development:

Clone the repository:

git clone https://github.com/YOUR_USERNAME/pr3tz.git

Symlink the addon to Blender's addons folder as shown in Option B of the installation instructions.
Use run_script.py to quickly test code changes from the CLI or Text Editor.

License

MIT — see LICENSE for details.