✨ RollLux

Perceptive Full-Auto Metering Lighting

Procedural presets · LuxPro direction · viewport auto exposure · live tuning · viewport overlay

English · 中文 · 日本語

RollLux is a Blender 5.0+ extension that analyzes a reference photo and builds a ready-to-tune light rig — key, fill, rim, accent, and world ambient — so you can replicate cinematic, portrait, product, and stylized looks without hand-placing every light.

Every strategy thumbnail and library reference is procedurally generated in code — shaded spheres, gradient maps, and light blobs — not hand-picked stock photos. Roll Random anytime for a fresh combo, or step through named starting points that share the same generative pipeline.

Drop in a reference, hit Generate, and refine with real-time sliders. Works with Cycles and Eevee, fully offline, zero pip installs.

Reference → Result Portrait split-light reference matched to a 3D head	Dual-tone gel lighting Separate key + accent colors from saturated references
N-panel workflow Strategy presets, tuning sliders, LuxPro read-out	Animated workflow Load reference → Generate → Tune

_{📁 Add your own captures to ./assets/ — filenames above are the expected paths.}

1. Download rolllux-5.5.5.zip from Releases.
2. Blender → Edit → Preferences → Get Extensions → ▼ → Install from Disk…
3. Select the zip → enable RollLux.

See CHANGELOG.md for changes since 5.0.

cd rolllux
py dev/gen_assets_main.py   # optional: regenerate thumbnails & reference PNGs
py build.py                 # -> ../dist/rolllux-<version>.zip
py build_marketplace.py     # -> ../dist/rolllux-<version>-marketplace.zip (Extension Platform)

1. 3D Viewport → N → RollLux tab.
2. Load a reference image (a procedurally generated default is applied on first open).
3. Pick a Strategy preset or tap 🔄 Random for a freshly generated style.
4. Optionally change Lighting Distribution (procedural library) or use your own photo.
5. Select your subject → Generate Lighting.
6. Tune Intensity, Contrast, Shadows, Highlights, Saturation — updates apply live.
7. Switch the 3D View to Rendered shading and enable Auto Exposure (on by default) — see Auto Exposure below.
8. Use Quick for a compact panel, or Pro for full AE and rig controls.

RollLux 5.0 ships a viewport-based auto exposure (AE) system that reads live pixels from the 3D View and keeps your scene at a stable luminance target — without leaving Blender or rendering to disk.

1. While AE is on, RollLux samples the viewport framebuffer on a timer (requires Material or Rendered shading; Rendered is preferred).
2. A 10×10 sample grid is collected over the metering region, with optional center weighting and per-frame grid jitter to reduce moiré misreads.
3. Samples are converted to luminance and aggregated with your chosen metering mode.
4. The plugin computes the EV gap to the target and applies it either to Color Management exposure or light rig energy (via intensity × 2^EV).
5. Tap Apply (✓) to bake the current AE offset into permanent settings and turn AE off.

Tip: If the viewport is not in Rendered mode, use the panel’s Set Rendered control or switch shading manually before expecting AE to react.

Switch UI Mode at the top of the panel between Quick and Pro.

All modes blend full-frame and center samples according to Center Weight (0–100%).

Light Rig mode includes Cycles-aware safeguards: luminance must settle between steps, adaptation is rate-limited, and timing scales with render engine noise — reducing flicker when Cycles is still converging.

In camera view without Subject Frame, the plugin can also crop to the camera frame automatically.

Drive RollLux from chat: 「给 Suzanne 打 portrait 光」, Light the Cube with golden hour, or Apply Arcane-style lighting.

Full release only — install rolllux-*.zip from GitHub Releases. The Extension Platform build (-marketplace.zip) does not include the MCP bridge.

Cursor / Codex  ──stdio──►  rolllux_mcp  ──TCP :9886──►  Blender (RollLux panel ▶ Start MCP)

1. Blender — enable RollLux → N panel → ▶ Start MCP (port 9886).
2. Python — cd rolllux/mcp && py -m pip install -e .
3. AI client — configure once (below).

Detailed guide: mcp/README.md

Create or edit .cursor/mcp.json in your workspace root:

{
  "mcpServers": {
    "rolllux": {
      "command": "cmd",
      "args": ["/c", "py", "-m", "rolllux_mcp"],
      "cwd": "rolllux/mcp",
      "env": {
        "PYTHONPATH": "rolllux/mcp",
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9886"
      }
    }
  }
}

If you cloned only the rolllux repo, copy .cursor/mcp.json.example and set cwd to the absolute path of rolllux/mcp.
Then Cursor Settings → MCP → enable rolllux and restart Cursor.

Add to ~/.codex/config.toml (or trust the project and use rolllux/.codex/config.toml):

[mcp_servers.rolllux]
command = "py"
args = ["-m", "rolllux_mcp"]
cwd = "C:/path/to/your/clone/rolllux/mcp"
enabled = true
tool_timeout_sec = 180

[mcp_servers.rolllux.env]
PYTHONPATH = "."
BLENDER_HOST = "localhost"
BLENDER_PORT = "9886"

Or: codex mcp add rolllux -- py -m rolllux_mcp (then set cwd and env).
In a Codex session, run /mcp to confirm tools are listed.
Template: .codex/config.toml.example

check_blender()
list_scene_objects(limit=20)
light_object(object_name="Suzanne", preset="portrait", light_count=4, auto_exposure=true)

clear_rolllux_lighting()
light_selection(reference_preset="golden_hour", preset="cinematic")

list_scene_objects()
light_arcane(intensity=0.22, light_count=4)

• Viewport comparison overlay (reference vs render)
• Preset export / import from current rig
• Batch generate for shot lists
• Optional AI reference tagging (offline heuristics first)

Run py test_offline.py (no Blender required). Optional: blender --background --python test_blender.py. UI or lighting changes should include screenshots.

GNU General Public License v3.0 or later