# Pr3tz — Architecture Overview

This document describes the internal design of the add-on for contributors and developers who want to extend or debug it.

---

## High-Level Flow

```
Blender Timeline scrub / playback
        │
        ▼
frame_change_post handler  ──  handler.py :: knot_frame_handler()
        │
        ├── compute playlist position  (which knot is active, transition blend weight)
        │
        ├── geometry.py :: _make_torus_knot(config)
        │       └── writes NURBS control points into the shared "AnimKnot" object
        │
        └── materials.py :: apply shader / blend material to "AnimKnot"
```

**Key design choice:** The handler never calls `bpy.ops` and never touches `bpy.context.space_data`. This makes it safe to run headlessly (command-line renders, bake loops) without crashes.

---

## Module Descriptions

### `compat.py`
Applied once at addon load. Monkey-patches `align_matrix` in `add_curve_torus_knots` so it doesn't crash when there is no `space_data` (headless / baked renders).

### `constants.py`
Pure Python — no `bpy` imports. Contains:
- `KNOT_CONFIGS` — the default 10-entry demo playlist.
- Scene defaults (camera position, light energy).
- String constants for well-known object/material names.

### `types.py`
A `TypedDict` called `KnotConfig` that documents every key the geometry and materials systems expect. Used for type-checking; not enforced at runtime.

### `properties.py`
All Blender `PropertyGroup` subclasses:
- `KnotAllowedMaterial` — an item in the generator's allowed-material list.
- `KnotGlobalSettings` — scene-level animation controls.
- `KnotItem` — one entry in the knot playlist. Includes `to_dict()` to serialize to a plain Python dict.
- `KnotGeneratorSettings` — the random playlist generator's configuration.

### `geometry.py`
`_make_torus_knot(config)` — the core parametric geometry function.
- Accepts a `KnotConfig` dict.
- Finds or creates the `AnimKnot` NURBS curve object.
- Writes control points directly into `curve.splines[0].points`, bypassing `bpy.ops.curve.torus_knot_plus` for headless safety.
- Returns immediately if the config would produce a degenerate knot.

### `materials.py`
- 20 shader builder functions, each returning a `bpy.types.Material`.
- A material **cache** (`KnotShader_<id>`) avoids rebuilding identical materials every frame.
- **Preset materials per KnotItem** (`KnotItem_Preset_<uid>`) allow per-item color/roughness overrides without polluting the global cache.
- **Blend materials** (`KnotBlend_<uid_a>_<uid_b>`) mix two adjacent presets during transition windows using a `MixShader` node driven by a `Value` node that the handler updates each frame.
- `prewarm_materials_and_blends(scene)` — builds all materials upfront so the first frame has no stutter.
- `prebuild_playlist_blend_materials(scene)` — called whenever the playlist changes (add/remove/reorder) to keep blend materials in sync.

### `handler.py`
`knot_frame_handler(scene)` — the `@persistent` callback registered to `frame_change_post`.

Timeline math:
```
effective_frame = (current_frame × global_speed) + animation_phase

for each knot_i in playlist:
    duration_i = frames_per_knot × cycle_rate_i
    cumulative_start_i = sum(duration_j for j < i) + transition_frames_i/2

active_knot, blend_weight = resolve(effective_frame, playlist)
```

During a transition window the handler interpolates geometry config dicts and sets the blend material's mix factor.

### `operators.py`
All `KNOT_OT_*` operator classes:
- `Add / Remove / Move` — playlist CRUD.
- `Populate` — loads `KNOT_CONFIGS` into the playlist.
- `BakePreview` — runs `_make_torus_knot` once for the selected item (useful while scrubbing).
- `SyncGeneratorMaterials` — rebuilds the generator's allowed-materials list from live `bpy.data.materials`.
- `GenerateRandom` — fills the playlist with randomly configured knots.
- `FitTimeline / FitPlaylist` — synchronise frame range and `frames_per_knot`.

### `ui.py`
- `KNOT_UL_List` — the playlist UIList.
- `KNOT_UL_AllowedMaterialsList` — the generator's material filter UIList.
- `draw_knot_properties(layout, item)` — renders the full KnotItem editor (topology, animation, material).
- `KNOT_PT_Panel` — the root N-panel.

### `scene_setup.py`
`setup_scene()` — called once when the add-on runs as a script. Creates or repositions the camera, area light, and sets sensible render defaults (Cycles, HDRI world, denoising).

### `bake_export.py`
`KNOT_OT_BakeExport` — seven-phase bake operator. See [PARAMETERS.md](PARAMETERS.md#bake--export-options) for user-facing options.

`_get_action_fcurves(obj)` — walks the Blender 5 layered Action tree
(`action → layers → strips → channelbag(slot) → fcurves`) to return an
iterable of FCurves without touching the removed `action.fcurves` attribute.

Phases:
1. **Bake geometry** — iterate every frame, convert NURBS → mesh, fingerprint for deduplication.
2. **Visibility keyframes** — insert `hide_render` / `hide_viewport` with CONSTANT interpolation.
3. **Camera shake bake** — convert procedural camera shake to explicit `delta_location` keyframes.
4. **Cleanup** — remove the live `AnimKnot` NURBS object.
5. **Pack** — make paths relative, pack external textures, purge zero-user data blocks (first chunk only).
6. **Save copy** — `wm.save_as_mainfile(copy=True, compress=True)`.
7. **Restore session** — remove all baked objects, re-register the handler, trigger one handler call to rebuild the live knot.

---

## Data Flow Diagram

```
Scene properties (knot_list, knot_globals)
        │
        │  read by
        ▼
handler.py  ──────────────────────────────────────────────────────────────────┐
  │                                                                            │
  │  _make_torus_knot(config)         apply_material(knot_obj, material)      │
  ▼                                   ▼                                        │
geometry.py                        materials.py                                │
  │                                   │                                        │
  └── writes into ──► "AnimKnot"  ◄───┘                                       │
        (NURBS curve object in scene)                                          │
                                                                               │
                        bake_export.py  ◄──────────────────────────────────────┘
                          (iterates frames, calls frame_set which triggers handler,
                           then converts knot_obj to mesh)
```

---

## Adding a New Shader Preset

1. Open `materials.py`.
2. Add a builder function following the pattern of existing builders (e.g. `_build_gloss_blue`). The function receives `color`, `roughness`, `metallic`, `emission_strength` keyword arguments.
3. Add the new ID string to `SHADER_IDS` in `constants.py` **and** `materials.py`'s dispatch dict.
4. The EnumProperty in `KnotItem` is auto-generated from `SHADER_IDS`, so the UI will pick it up automatically.

## Adding a New KnotItem Property

1. Add the `bpy.props.*` declaration to `KnotItem` in `properties.py`.
2. Add the corresponding key to `KnotItem.to_dict()`.
3. If the property should affect geometry, read it in `geometry.py :: _make_torus_knot()`.
4. If it should be randomisable, add `r_<name>`, `min_<name>`, `max_<name>` entries to `KnotGeneratorSettings` in `properties.py` and wire them in `operators.py :: KNOT_OT_GenerateRandom.execute()`.
5. Add UI for it in `ui.py :: draw_knot_properties()`.