# 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

| Moment | Settings | What happens |
|---|---|---|
| **Scene start** | `Start/...` | The light and the tint are set to white (default), or left as they are until the first grab |
| **Held** | `Intensity/Drain Per Second`, `Intensity/Min While Held`, `Rainbow/...` | The intensity drains, the rainbow runs on the light color and the material tint |
| **Emissive** | `Emissive/...` | The emissive intensity of the materials follows the light intensity |
| **Released** | `Intensity/Restore Per Second`, `Intensity/Target On Release`, `Release Color/...` | The intensity comes back; the color returns to white or stays as it was |

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
| Property | Type | Default | Description |
|---|---|---|---|
| Start/Start After First Grab | bool | On | Nothing changes until the first grab |
| Start/Start From Current Intensity | bool | On | Start from the light's intensity in the scene; Off = from Target On Release |
| Start/Force White At Init | bool | On | Light color and material tint set to white at start |

### Light and Intensity
| Property | Type | Default | Description |
|---|---|---|---|
| Light/Light Name Filter | string | (empty) | Name of the light to drive; empty or not found = first scriptable light |
| Intensity/Target On Release | number, 0-100 | 60 | Intensity reached after release |
| Intensity/Drain Per Second | number, 0-100 | 0.02 | Intensity removed per second while held |
| Intensity/Restore Per Second | number, 0-100 | 2 | Intensity added per second after release |
| Intensity/Min While Held | number, 0-100 | 0 | Lowest intensity while held |

### Emissive
| Property | Type | Default | Description |
|---|---|---|---|
| Emissive/Sync With Light | bool | On | Emissive intensity follows the light |
| Emissive/Target On Release | number, 0-100 | 4 | Emissive when the light is at Target On Release |
| Emissive/Min While Held | number, 0-100 | 0 | Emissive when the light intensity is 0 |
| Emissive/Gamma | number, 0.2-3 | 0.8 | Curve between the two; below 1 stays bright longer |

### Material
| Property | Type | Default | Description |
|---|---|---|---|
| Material/Name Filter | string | (empty) | Empty = every material of the first scriptable mesh; a name = that material on every scriptable mesh |
| Material/Lerp Seconds | number, 0-1 | 0.01 | Fade of each material write; 0 = instant |
| Material/Write Interval Seconds | number, 0.02-1 | 0.2 | Minimum time between two material writes |

### Rainbow
| Property | Type | Default | Description |
|---|---|---|---|
| Rainbow/Enable On Grab | bool | On | Rainbow on the light color and the tint while held |
| Rainbow/Hue Speed | number, 0-4 | 0.1 | Hue units per second (0.1 = one cycle every 10 s) |
| Rainbow/Saturation | number, 0-1 | 1 | 0 = greys, 1 = vivid |
| Rainbow/Value (Brightness) | number, 0-1 | 1 | Brightness of the rainbow color (not the light intensity) |
| Rainbow/Smoothing Seconds | number, 0-3 | 0.8 | Softness of the color changes; also the tint's return to white |

### Release Color
| Property | Type | Default | Description |
|---|---|---|---|
| Release Color/Return To White | bool | On | Light color returns to white after release (unless Latch Color) |
| Release Color/Return Seconds | number, 0-5 | 1 | Pace of the light's return to white |
| Release Color/Latch Color | bool | Off | Keep the color of the moment of release |

### Debug
| Property | Type | Default | Description |
|---|---|---|---|
| Debug/Debug Logging | bool | Off | Writes the chosen light and materials, each grab and release, and the writes per minute to the script console |

---

## Version Notes

| Version | What changed |
|---|---|
| v1.0 - v1.6 | First releases: drain while held, restore on release, rainbow, emissive sync |
| v1.7 | Smooth rainbow (temporal smoothing), emissive sync with gamma, color latch on release, start after first grab, throttled material writes. Sold until V1.8.1 |
| V1.8.0 | Anti-flicker light writes (at most 15 per second, none at rest), working Debug Logging, warnings for a wrong setup, guarded writes (a failing material or light is dropped, the rest goes on), effects following the real elapsed time, name filters searched on every scriptable mesh, settings grouped by category |
| **V1.8.1** (this version) | Version number only |

### 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:

| v1.7 | V1.8.1 |
|---|---|
| Start After First Grab, Start From Current Intensity, Force White At Init | Start/Start After First Grab, Start From Current Intensity, Force White At Init |
| Light Name Filter | Light/Light Name Filter |
| Target Intensity On Release, Drain Per Second While Held, Restore Per Second On Release, Min Intensity While Held | Intensity/Target On Release, Drain Per Second, Restore Per Second, Min While Held |
| Sync Emissive With Light, Emissive Target On Release, Min Emissive While Held, Emissive Gamma | Emissive/Sync With Light, Target On Release, Min While Held, Gamma |
| Material Name Filter, Material Lerp Seconds, Material Write Interval Seconds | Material/Name Filter, Lerp Seconds, Write Interval Seconds |
| Enable Rainbow On Grab, Rainbow Hue Speed, Rainbow Saturation, Rainbow Value (Light Brightness), Rainbow Smoothing Seconds | Rainbow/Enable On Grab, Hue Speed, Saturation, Value (Brightness), Smoothing Seconds |
| Return To White On Release, Color Return Seconds, Latch Color On Release | Release Color/Return To White, Return Seconds, Latch Color |
| Debug Log | Debug/Debug Logging |

- **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

| Symptom | Check |
|---|---|
| Nothing happens when I grab the object | The object must be grabbable (a physics RigidBody with grab allowed); a warning "No RigidBodyComponent..." is written at start otherwise. With `Start/Start After First Grab` On, the effect only begins at the first grab |
| The light does not change, only the glow | The light must be set **Scriptable** (warning "No scriptable light..." at start), or `Light/Light Name Filter` names a light that does not exist (warning "matches no scriptable light. Using '...'") |
| The glow does not change, only the light | The mesh must be set **Scriptable** (warning "No scriptable mesh..."), or `Material/Name Filter` matches nothing (the warning lists the names found), or the material accepts neither Tint nor Emissive Intensity |
| The light jumps to 60 at start | `Start/Start From Current Intensity` Off starts from `Intensity/Target On Release`. Turn it On, or set the target to your editor value |
| The lamp changed color at start although nobody touched it | `Start/Force White At Init` On sets it to white at start. Turn it Off (with `Start After First Grab` On) to leave the object untouched until the first grab |
| The rainbow is too fast or too slow | `Rainbow/Hue Speed`: 0.1 = one cycle every 10 seconds |
| The color does not come back to white | `Release Color/Latch Color` On keeps the color; or `Return To White` is Off |
| The transitions look stepped | Raise `Rainbow/Smoothing Seconds`, and keep `Material/Lerp Seconds` close to `Material/Write Interval Seconds` |
| I want to know what the script does | Turn `Debug/Debug Logging` On: the script console shows the light and materials chosen, each grab and release, and once a minute the number of light and material writes |

---

## 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

| Item | What it adds |
|---|---|
| **Light Switch Script** | Turn lamps on and off with fades, by click, chat command or group. Store: https://www.sansar.com/store/listings/7379d48c-2b6f-45f6-b6f1-205ce95aec1c/light-switch-script |
| **Emissive Color Cycle Script** | A three-color cycle on the glow of your materials, without any interaction. Store: https://www.sansar.com/store/listings/23b8b34f-c12a-47ac-930f-5765b1cbcaf9/emissive-color-cycle-script |
| **Gravity Drift On Grab Script** | Makes the same prop float up like a balloon once released. Store: https://www.sansar.com/store/listings/d74417ad-2b75-41b2-9bd7-7a96cf12eef9/gravity-drift-on-grab-script |

---

*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*