Documentation

Download PDF

Everything you need to install, configure, and use Light Wrangler.

Installation

Supported Blender versions: 4.0 to 5.1.

  1. 1. Download — Acquire the .zip file provided with your purchase. Do not extract the archive.
  2. 2. Install — Open Blender and go to Edit > Preferences > Add-ons > Install. Navigate to and select the downloaded .zip file.
  3. 3. Activate — Find the add-on in the list and check the box next to its name.
  4. 4. First run — On first activation, a welcome popup points you to the right-click Light Operations menu and the Light Data customization panel. Textures (gobos, HDRIs, IES profiles) are streamed on demand from the server — see Online Catalog & Cache.

Preferences

Access settings at Edit > Preferences > Add-ons, then select "Light Wrangler".

Light Wrangler addon preferences panel

Initial Light Settings

Initial Distance Default distance from surface for new lights.
Initial Size Default size for area lights.
Initial Power Default power for new lights (except Sun lights).
Initial Light Temperature Initial color temperature. Set to 0 to disable and use plain RGB emission.
Initial Spread Default spread angle for new area lights.
Use Scrim for New Area Lights When enabled, new area lights in Cycles use Scrim mode by default.
Enable Reflectors Show the Add Reflector option in the right-click menu.
Adaptive Initial Size Sets initial light distance and size based on the largest dimension of selected objects. Also applies to flags and reflectors. Hold Shift while adding a light to temporarily toggle this on or off.
Keep HDRI Spread Values When enabled, changing HDRIs won't reset your light's spread value.
Scrim Version Choose which Scrim Light node group to use (Blender 4.3+). Version 1: fully procedural, cloud render compatible. Version 2: procedural with additional EXR textures. Version 2.1: enhanced quality. Version 3: uses native Blender color temperature.

Light Behavior

Auto-Adjust Light Power Automatically adjusts power to maintain consistent illumination when changing size, distance, or spread (disabled in Gobo mode).
Light Visibility by Selection Light visibility to the camera toggles with selection: visible when selected, not visible when unselected. Only works when real-time compositor is off.
Enable Obstacle Avoidance Prevents lights from being placed inside or below obstacles. Disable for interior lighting scenarios where lights need to be placed inside models.
Organize Lights (Beta) Automatically place new lights into a 'Lights' collection and rename them to reflect their light mode.
Initial Positioning Mode Controls how lights behave when entering adjustment mode. "Remember Per Light" uses each light's previous state. "Always Start Paused" begins with positioning paused. Greyed out when Adjustment Method is set to Mouse Drag.
Orbit Axis Snap Mode Choose whether Ctrl snaps to view axes or world axes in orbit mode.
Orbit Method Choose from Trackball, Turntable, or Hybrid rotation modes in orbit.
Orbit Sensitivity Adjusts the sensitivity of orbit mode movement.
Adjustment Method Choose between Mouse Wheel (scroll-based discrete steps) and Mouse Drag (hold modifier keys and drag left/right for continuous adjustment). In Drag mode, positioning activates only while you hold 1/2/3, eliminating accidental position jumps.

Custom Light Assets

Configure paths to your personal texture libraries. Only set these if you want to use your own textures.

HDRI Folders Add multiple folders containing HDRI textures for area lights. Use the + button to add folders and the refresh button to rescan.
Gobo Folders Add multiple folders containing Gobo textures. Use the + button to add folders.
Include Blender Asset Libraries Optionally scan Blender's configured Asset Libraries for additional Gobo sources.
IES Folders Add paired folders for IES profiles and their preview images. Both paths must be set for each slot.
IES Library API Key Enter your ieslibrary.com API key to access the online IES browser with manufacturer/tag filtering, favorites, and search. A status icon shows whether the key is valid. Free keys expire in 15 minutes; Pro keys last 7 days.

Addon's Downloaded Textures

Downloaded gobos, HDRIs, and IES profiles are stored automatically in a per-platform cache directory. Override the location only if needed (e.g., to point at a NAS or external drive).

Cache Directory Custom directory for downloaded textures. Leave empty to use the default location. When changed, existing cache content is automatically copied to the new location.

Interface Settings

Hide Viewport Overlays Toggle viewport overlays during light manipulation.
Show Texture Labels Display filename labels below texture previews in the Light Customization panel.
Show Light Linking Feedback Show visual overlay feedback when adding/removing objects from light linking.
Scrim Preview (Experimental) Enable real-time scrim light preview rendering in the Light Customization panel.
HUD Text / Background Color Customize the color and background of floating text hints above the cursor during light manipulation.
Help Panel Position Display the keyboard shortcuts help panel in the bottom-right or bottom-left corner.
Texture Preview / Popup Size Size of texture thumbnails in the Light Customization panel and popup selection window.
Isolate Gizmo Row Position Which row the isolate gizmo appears in the viewport.

Keyboard Shortcuts (Preferences)

These shortcuts can be customized in the preferences panel.

Add Light Default F7
Adjust Light Default Tab
Rotate HDRI Default Alt + Right Mouse
Light Pie Menu Default Ctrl + Shift + A
Direct Mode Entry Keys 1 2 3 — skip Tab and jump directly to positioning modes. Also used to switch modes during active positioning. Caution: overrides Blender's collection visibility shortcuts and may discard any custom keymaps assigned to these keys.

Online Catalog & Cache

Light Wrangler streams textures (gobos, HDRIs, IES profiles) from a server on demand instead of bundling them with the addon. This keeps the install lean and lets the library grow over time without addon updates.

Allow Online Access

A single "Allow Online Access" button enables downloads of gobos, HDRIs, and IES previews together. Selecting any texture pulls the asset to your local cache on first use; subsequent uses are instant.

Cache Location

By default, cached textures live in a per-platform user directory. Override with the Cache Directory preference if you want them on a NAS, external drive, or shared location. Changing the path automatically copies existing cache content to the new location.

Auto-Repair on Load

When you open a file with broken Light Wrangler texture paths — for example, after sharing a .blend across machines or moving your cache — Light Wrangler relinks references to your current cache and quietly downloads any missing assets in the background.

Externalized Scrim Textures

Scrim packed images are stored in the cache directory rather than inside the .blend file, keeping scene files small.

Adding & Adjusting Lights

Adding a Light

Adjust Existing Lights

Duplicate & Copy/Paste

Track to Target

Right-click → Light Operations > Track to Target. Choose to create a new empty for tracking or use an existing object. If multiple lights are selected, all will target the chosen point. Flags and reflectors also support tracking.

Flags & Reflectors

Flags and reflectors use the same interactive positioning system as lights — Reflect, Direct, and Orbit modes all work identically.

Real-Time Adjustments

All adjustments work during interactive mode. Mouse Wheel can be replaced with two-finger trackpad scroll. When no geometry is under the cursor, lights, flags, and reflectors place at the cursor position along the view ray instead of failing.

Mouse Wheel Power
Shift + Mouse Wheel Size
Alt + Mouse Wheel Distance to surface
Ctrl + Mouse Wheel Spread
Shift + Alt + Wheel Size X (rectangular/elliptical area lights)
Shift + Ctrl + Wheel Size Y (rectangular/elliptical area lights)
Z + Mouse Wheel Rotate on Z axis (disabled for Sun lights)
W + Mouse Wheel Power (alternate hold-modifier form). For flags and reflectors, adjusts opacity / color value.
S Toggle light shape (Area: square ↔ disk; flag: rectangle ↔ ellipse)
Shift + Space Toggle Area ↔ Spot light (preserves energy, color, and position)
Alt + Right Mouse Drag Rotate world HDRIs and dome objects

Mouse Drag Mode

When Adjustment Method is set to Mouse Drag in preferences, hold a modifier key and drag the mouse left/right to adjust continuously instead of scrolling in discrete steps. Positioning activates only while you hold 1, 2, or 3 — eliminating accidental position jumps between adjustments.

Positioning Modes

When Direct Mode Entry Keys is enabled in preferences:

1 Reflect mode — light mirrors the cursor across the surface normal
2 Orbit mode — light orbits around the target point
3 Direct mode — light points straight at the surface under the cursor

Additional Controls

Space Toggle Precise mode — disables normal averaging for exact placement
U Toggle Keep Upright for flags, reflectors, and EEVEE gobo stencils
Ctrl Snap to axes in orbit mode (view or world axes, configurable in preferences)

Visibility & Isolation

H Toggle hiding the current light
I Toggle isolating the current light (all other lights go dark)
V Toggle camera visibility for Cycles area lights, flags, and reflectors
F Toggle False Color on/off
Shift + F Cycle between False Color, Zone System, and ARRI False Color
Q Show or hide the keyboard shortcuts help panel

Light & Shadow Linking

During interactive mode, aim at any object to manage linking:

L Add object to the light's linking collection
L Press again to exclude it
L Press a third time to remove it entirely
Shift + L Same sequence for shadow linking

Light Customization (Cycles)

Located in the Light Data panel. Each light type has dedicated customization modes:

Area Light Default, Scrim, HDRI, or Gobo modes
Spot Light Default, HDRI, or Gobo (Cycles). Default or Gobo in EEVEE.
Point Light Default or IES profile modes

Customization Features

Procedural Scrim. Transform an area light into a light scrim with adjustable Feathering, Horizontal Tilt, Vertical Tilt, Imperfection, and Edge Sharpness controls.

HDRI Textures. Apply textures like Octabox, Parabolic Reflector, Umbrella, Fresnel, LED panel, and more. Includes Contrast, Hue Shift, Saturation, and Playback Speed controls.

Gobos. Dynamic shadow patterns with static and animated versions. Compatible with area lights, spotlights, and EEVEE spotlights.

IES Profiles. Real-world lighting patterns for point lights. Includes Scale, Rotation (X/Y/Z), Exposure, and Color Temperature Presets. Strength is auto-adjusted from the profile's metadata so different fixtures appear at consistent intensities.

IES Library Browser. With an ieslibrary.com API key, browse the online IES collection directly inside the panel — filter by manufacturer or tag, search, mark favorites, and download on selection.

Diffuse/Glossy Balance. Available in all modes — control a light's contribution to diffuse and glossy material components.

Separate Glossy Color. Set a different color for glossy (specular) reflections independent of diffuse color.

Flicker Effect. Available in Default, HDRI, IES, and Scrim modes — add animated flickering to lights.

Interactive Scrim Preview. Real-time preview rendering in the customization panel (experimental, enable in preferences).

Export Scrim as HDR. Export Scrim lights as HDR images at 1K/2K/3K/4K resolution from the Light Data panel.

Custom Textures. Add your own HDRI, Gobo, and IES folders in addon preferences.

False Color Setup

During interactive mode, F toggles False Color and Shift + F cycles between False Color, Zone System, and ARRI False Color. The two additional view transforms require a one-time OCIO installation step.

What They Are

Both include the same Look options as Blender's built-in False Color: Punchy, Greyscale, and contrast controls.

Installation

Requires Blender 5.0 or later. The installer is in Edit > Preferences > Add-ons > Light Wrangler > False Color View Transforms.

  1. 1. Click Prepare False Color to create a patched OCIO config folder.
  2. 2. Click Open Blender Folder to reveal the target color management folder.
  3. 3. Replace the contents of the Blender folder with the prepared folder.
  4. 4. Restart Blender.

HDRI Scene Rendering

Located in the World tab. Renders a 360° equirectangular HDRI image of the current scene with a single click — useful for capturing a finished lighting setup as a reusable environment, or for compositing reference. Emissive mesh objects are supported (including these increases render time).

Texture Recovery

Two recovery paths handle missing or broken texture references:

Automatic (v4 files)

When you open a v4 file with dead gobo, HDRI, or IES paths — for example, after sharing across machines or moving your cache — Light Wrangler automatically relinks references to your current cache and downloads any missing assets in the background. No action required.

Manual (pre-v4 files)

For files created with Light Wrangler 3 or earlier whose bundled texture paths no longer resolve, use the manual recovery tool:

  1. 1. Open Edit > Preferences > Add-ons > Light Wrangler > Texture Recovery.
  2. 2. Click Recover Textures.
  3. 3. Light Wrangler scans the scene for broken v3 paths, downloads originals from the server, and relinks the references. Progress is shown next to the button.

Keyboard Shortcuts

All shortcuts are customizable in addon preferences.

Global

F7 Add Light
Tab Adjust Light (or Shift + Tab if Tab is occupied)
Alt + Right Mouse Drag Rotate HDRI
Ctrl + Shift + A Light Pie Menu

During Interactive Mode

Mouse Wheel Power
Shift + Mouse Wheel Size
Alt + Mouse Wheel Distance
Ctrl + Mouse Wheel Spread
Z + Mouse Wheel Z-axis rotation
W + Mouse Wheel Power (alternate; flag/reflector opacity or color value)
1 / 2 / 3 Reflect / Orbit / Direct mode
S Toggle light shape
Space Toggle Precise mode
Shift + Space Toggle Area ↔ Spot light
H Hide current light
I Isolate current light
V Camera visibility
F False Color toggle
Shift + F Cycle False Color modes
L Light linking (cycle: add → exclude → remove)
Shift + L Shadow linking
U Keep Upright toggle
Q Help panel toggle

Need help?

· Discord community · Changelog