MPP - Light Drain And Restore Script V1.8.1 - Documentation

A theatrical lighting effect for a lamp, a lantern, a crystal or any prop your visitors can pick up. While the object is held, its light slowly dims and a smooth rainbow runs through the light color and the glowing materials. When the object is released, the light comes back to its target intensity and the color returns to white, or stays on the color the visitor "picked" by letting go.

This script is standalone - it does not require any other MPP script to function.

New in V1.8: the light is written only when its value really changes (with the same anti-flicker thresholds as MPP - Day Night), at most 15 times per second, and never while the object rests: the "one write every 50 ms forever" of v1.7 is gone. The Debug Logging switch now works and tells you which light and materials are driven, each grab and release, and the write counts. A wrong setup (no scriptable light, no scriptable mesh, a name filter that matches nothing, no RigidBody) is reported in the script console instead of failing in silence. Settings are grouped by category in the Build panel. V1.8.1 only changes the version number. Your settings are kept when you update: see "Updating from v1.7".

Quick Start

1. After purchase, the script is in your Inventory in Build mode. Add it to an object that has a light and a glowing material: a lamp, a lantern, a crystal ball.
2. In the object's properties, make sure the object is grabbable (it needs a physics RigidBody with grab allowed), the light is set Scriptable, and the mesh that carries the glowing material is set Scriptable.
3. Build and visit. Pick the object up: the light dims slowly and cycles through the rainbow, together with the material tint. Let it go: the light comes back and the color fades to white.

That is all most objects need. The rest of this guide details every option.

How It Works

In the Build panel the settings are grouped by category: Start/, Light/, Intensity/, Emissive/, Material/, Rainbow/, Release Color/ and Debug/.

The intensity scale is the one of the light in the editor, from 0 to 100.

Start

• Start/Start After First Grab (On): nothing is written to the light or the materials until the first grab. A lamp that nobody touches keeps the look you gave it in the editor. With Force White At Init On, the light and the tint are still set to white at start (at the start intensity).
• Start/Start From Current Intensity (On): the script starts from the intensity the light has in the scene. Off: it starts from Intensity/Target On Release, so a light set to 40 in the editor jumps to 60 (the default target) as soon as the script writes it.
• Start/Force White At Init (On): the light color and the material tint are set to white when the script starts, so the rainbow always begins from a clean white. Off: the light keeps its scene color and the materials keep their tint until the script drives them.

With Force White At Init Off and Start After First Grab On, the object is untouched until the first grab: its editor color and intensity stay exactly as you set them.

Light

The script drives one light of the object, set Scriptable in the editor.

• Light/Light Name Filter empty (default): the first scriptable light of the object.
• A name: the scriptable light with that name (case and outer spaces ignored). If no scriptable light has that name, the first scriptable light is used and a warning says so in the script console.
• No scriptable light at all: only the materials are driven, with a warning at start.

While held, the intensity goes down by Intensity/Drain Per Second units every second, and stops at Intensity/Min While Held (default 0). The default drain of 0.02 per second is very slow: a light at 60 needs 50 minutes to go dark. Set 1 for one minute, 3 for twenty seconds.

After release, the intensity goes back up by Intensity/Restore Per Second units every second (default 2: from 0 to 60 in 30 seconds) until it reaches Intensity/Target On Release (default 60). Once the script runs, this target replaces the intensity set in the editor.

The light is written at most 15 times per second, only when its intensity or color moved enough to be visible, plus one exact write when the value stops moving. At rest, nothing is written.

Rainbow

With Rainbow/Enable On Grab On (default), the light color and the material tint cycle through the hue spectrum while the object is held:

• Rainbow/Hue Speed: hue units per second; 0.1 (default) is about one full color cycle every 10 seconds, 1 is a cycle per second.
• Rainbow/Saturation (1 = vivid colors, 0 = greys) and Rainbow/Value (Brightness) (brightness of the color itself; it does not change the light intensity).
• Rainbow/Smoothing Seconds (default 0.8): how softly the color follows the cycle. Higher = softer transitions. After release, the material tint also returns to white at this pace.

Release Color

• Release Color/Return To White (On): after release, the light color gradually returns to white. Release Color/Return Seconds (default 1) sets the pace of that return for the light; the material tint follows Rainbow/Smoothing Seconds.
• Release Color/Latch Color (Off): On, the color at the moment of release is kept, on the light and on the materials, and Return To White is ignored. Turn it On to let visitors "pick" a color by letting go at the right moment. The next grab starts the rainbow again from that color.

Emissive

With Emissive/Sync With Light On (default), the emissive intensity of the driven materials follows the light intensity:

• At the light's Intensity/Target On Release, the emissive is Emissive/Target On Release (default 4).
• When the light intensity is 0, the emissive is Emissive/Min While Held (default 0).
• Emissive/Gamma (default 0.8) shapes the curve in between: below 1 the glow stays bright longer while the light dims, above 1 it dims sooner.

Off: the emissive intensity is never written; only the tint is driven.

Materials

• Material/Name Filter empty (default): every material of the first scriptable mesh of the object.
• A name: only the materials with that name (case and outer spaces ignored), searched on every scriptable mesh of the object. A name that matches nothing gets a warning listing the material names found, so you can copy the right one.
• Only materials that accept a Tint or an Emissive Intensity are driven; each one receives only what it accepts.
• Material/Write Interval Seconds (default 0.2): minimum time between two material writes. Higher values = fewer writes and smoother transitions. Values under 0.067 behave like 0.067 (15 writes per second at most).
• Material/Lerp Seconds (default 0.01): fade applied by Sansar to each material write. Close to the write interval (never above) gives a continuous fade; much shorter gives small steps; 0 = instant.

A material that keeps refusing its writes is dropped, with a warning, so the script console is not flooded; the other materials go on. The same rule applies to the light.

Editor Properties Reference (24 total)

Start

Light and Intensity

Emissive

Material

Rainbow

Release Color

Debug

Version Notes

Updating from v1.7

• Your values carry over: the 24 settings of v1.7 keep their internal names, their defaults and their values. As with any update, take a screenshot of the Build panel first, update one object and check its panel before doing the others.
• Labels: the settings now have short names in eight groups. Same settings, same values:

• What behaves differently: nothing is written while the object rests (v1.7 wrote the light 20 times per second forever after the first grab). With Force White At Init Off and Start After First Grab On, nothing at all is written before the first grab (v1.7 wrote the light and the tint at start). An empty Material/Name Filter now takes the first scriptable mesh (v1.7 took the first mesh and did nothing if it was not scriptable), and a name is searched on every scriptable mesh. On an object without a light, with Force White At Init Off, all the driven materials take the tint of the first one as soon as the effect starts (v1.7 set them all to white at start). Debug Logging (the old "Debug Log") now really writes to the script console.

Recipes

A - The default lantern. Defaults: a slow drain, a 10-second rainbow while held, back to white and full light after release.

B - A color picker. Release Color/Latch Color On: the visitor lets go on the color they like, and the lamp keeps it. The next grab starts the rainbow from that color.

C - A candle that burns out. Intensity/Drain Per Second 1, Intensity/Min While Held 0, Rainbow/Enable On Grab Off: held for a minute, the light goes dark; released, it comes back in 30 seconds.

D - Glow only, no light. An object without a light: only the tint (and the emissive, with a light) is driven. Set Start/Force White At Init Off to start from the material's own tint.

E - Several glowing parts. Put the same material name on the parts that must glow together, on any of the object's scriptable meshes, and write that name in Material/Name Filter.

Troubleshooting

Limits

• One light per object. To drive several lights, put a copy of the script on each object, or use one object per light.
• The drain and the rainbow follow the object's grab and release events: an avatar who leaves the scene while holding the object may leave it in the "held" state until the next grab.
• The emissive intensity follows the light: on an object without a light, the emissive is not driven.

Related MPP Items

MPP - My Pretty Pixels. Light Drain And Restore Script V1.8.1 (script MPP - Light Drain And Restore). Store: https://www.sansar.com/store/listings/95238b17-f553-4656-88b6-6bf10e4070b9/light-drain-and-restore-script