> For the complete documentation index, see [llms.txt](https://motiongamesstudio.gitbook.io/magic-lightmap-switcher/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://motiongamesstudio.gitbook.io/magic-lightmap-switcher/using/api.md).

# API

Magic Lightmap Switcher provides a simple set of APIs for controlling scene lighting at runtime. 

## GetInstance()

Retrieves the active MagicLightmapSwitcher instance in the specified scene. If no scene is specified, the currently active scene is used. Searches for the component inside a GameObject named "Magic Tools" (and its children).

It has asynchronous overload, which returns a guaranteed fully initialized instance for the specified scene.

```
_magicLightmapSwitcher = MagicLightmapSwitcher.GetInstance();

StartCoroutine(MagicLightmapSwitcher.GetInstance("", (mls) =>
{
    _magicLightmapSwitcher = mls;
}));
```

## Switching/Blending

The **RuntimeAPI** class contains methods for switching and blending lightmaps. Each scene must have its own instance of this class. 

### BlendLightmapsCyclic()

Call **RuntimeAPI.BlendLightmapsCyclic()** to start blending lightmaps cyclic in real time. This triggers a sequential transition between all lightmaps in the Lighting Scenario from the first to the last and then jumps back to the first.

| Parameter                           | Description                              |
| ----------------------------------- | ---------------------------------------- |
| **float** cycleLength               | Cycle time in seconds.                   |
| **StoredLightingScenario** scenario | The Lighting Scenario used for blending. |

Below is an example of a simple method call that starts the cyclic blending of lightmaps.

```
using MLS = MagicLightmapSwitcher.MagicLightmapSwitcher;

public class CallLightmapBlending : MonoBehaviour
{
    public StoredLightingScenario lightingScenario;
    public float blendingLength;

    private RuntimeAPI _runtimeAPI;

    void Start()
    {
        StartCoroutine(MagicLightmapSwitcher.GetInstance("", (mls) =>
        {
            _runtimeAPI = mls.RuntimeAPI;
        }));
    }

    void Update()
    {
        if (_runtimeAPI != null)
        {
            _runtimeAPI.BlendLightmapsCyclic(blendingLength, lightingScenario);
        }
    }
}
```

### BlendLightmapsPingPong()

This method blend lightmaps in Lighting Scenario in a ping-pong style, i.e. from first to last and in reverse order. The parameters and calling code are exactly the same as those for **BlendLightmapsCyclic()**.

### SwitchLightmap()

To instantly switch lightmaps to a specific index in a scenario, call the **RuntimeAPI.SwitchLightmap()** method.

| Parameter                           | Description                                                                |
| ----------------------------------- | -------------------------------------------------------------------------- |
| **int** lightmapIndex               | The index of the lightmap in the blend queue of the scenario to switch to. |
| **StoredLightingScenario** scenario | The Lighting Scenario used for blending.                                   |

In the example below, the method is called on the **OnTriggerEnter()** event.

```
using MLS = MagicLightmapSwitcher.MagicLightmapSwitcher;

public class CallLightmapsSwitching : MonoBehaviour
{
    public StoredLightingScenario lightingScenario;
    public int lightmapIndex;

    private RuntimeAPI _runtimeAPI;

    void Start()
    {
        StartCoroutine(MLS.GetInstance("", (mls) =>
        {
            _runtimeAPI = mls.RuntimeAPI;
        }));
    }

    private void OnTriggerEnter(Collider other)
    {
        runtimeAPI.SwitchLightmap(lightmapIndex, lightingScenario);
    }
}
```