Documentation

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

Installation

  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.

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.
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) and Mouse Drag (hold modifier keys and drag left/right).

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.

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. Warning: overrides Blender's collection visibility shortcuts.

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 & 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.

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
Alt + Right Mouse Drag Rotate world HDRIs and dome objects

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.

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.

HDRI Scene Rendering

Located in the World tab. Renders a 360° HDRI image of the current scene with a single click. Supports emissive mesh objects (including these increases render time).

Keyboard Shortcuts

All shortcuts are customizable in addon preferences.

Global

F7 Add Light
Tab Adjust Light
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
1 / 2 / 3 Reflect / Orbit / Direct mode
Space Toggle Precise mode
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