Ad/Pr3tz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
31e464f5cd890da8c6868ae527da51aa105e9c64
Pr3tz/README.md
T
Stefan Cepko 31e464f5cd Release 0.1
2026-06-05 04:47:34 -04:00

9.6 KiB
Raw Blame History

Pr3tz — Procedural Torus-Knot Animation for Blender

Pr3tz cover

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)

  1. Download a release zip (or run package_addon.py to build one).
  2. In Blender, go to Edit → Preferences → Get Extensions → Add-ons (or Install from Disk... from the top right gear menu).
  3. Select the zip file (e.g. releases/pr3tz_v2.0.0.zip).
  4. Enable "Pr3tz" from the list.
  5. 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:

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

  2. 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"

  3. Enable "Pr3tz" in Blender's Preferences.

  4. 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:

  1. Open Blender.
  2. In the Text Editor, open run_script.py.
  3. 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

  1. Install and enable the add-on (see above).
  2. In the N-panel, click "Populate Default List" to load 10 example knots.
  3. Press Space to play the animation and watch the knots morph.
  4. Select any knot in the playlist to tweak its topology, shader, and animation rates in the panel below.
  5. 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:

  1. Set your frame range in the Timeline.
  2. Click Bake & Export for Render Farm and choose an output path.
  3. Optional: enable Split Export and set Frames Per File for multi-chunk jobs.
  4. 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:

  1. Parses the release version dynamically from pr3tz/__init__.py.
  2. Zips the pr3tz/ directory into releases/pr3tz_v<version>.zip.
  3. 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:

  1. Clone the repository: 
    git clone https://github.com/YOUR_USERNAME/pr3tz.git
  2. Symlink the addon to Blender's addons folder as shown in Option B of the installation instructions.
  3. Use run_script.py to quickly test code changes from the CLI or Text Editor.

License

MIT — see LICENSE for details.

Reference in New Issue View Git Blame Copy Permalink