Pr3tz — Procedural Torus-Knot Animation for Blender

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

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
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
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)

Note: The single-file version (knot_animation.py) has no installation step — just open and run in the Text Editor.

Installation

Option A — Persistent Add-on (recommended)

Download or clone this repository.
In Blender, go to Edit → Preferences → Add-ons → Install…
Zip the knot_animation/ folder and select the zip (Blender 5 requires a zip for local installs).
Enable "Pr3tz" from the add-on list.
Open the 3D Viewport → N-panel → Pr3tz tab.

Option B — Run as a Script (no installation)

# From inside Blender's Text Editor:
#   File → Open → knot_animation/__init__.py   → Run Script (Alt+P)

# Or from the command line:
"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe" --python knot_animation/__init__.py

Option C — Single-file version

knot_animation_single_file.py is a self-contained copy of the entire add-on in one file, useful for quick testing without touching Blender's add-on directory.

blender.exe --python knot_animation_single_file.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.

Module Layout

knot_animation/
├── __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

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

Contributing

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

Development setup

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

# Run the syntax checker (no Blender needed)
python check_syntax.py

License

MIT — see LICENSE for details.

7.4 KiB Raw Blame History