> For the complete documentation index, see [llms.txt](https://axongenesis.gitbook.io/timeflow/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/settings.md).

# Settings

Additional configuration options for Timeflow

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FZfAecVLVFWmTnsiJyFtb%2Fimage.png?alt=media&amp;token=f9ae6547-43cf-4b30-8e7c-637172a0e7ce" alt=""><figcaption></figcaption></figure>

## Parent

This shows the containing Timeflow of the current object or instance if applicable. This reference is assigned automatically based on its placement in the hierarchy. A parent is only displayed when a Timeflow instance is nested within another, otherwise it shows None.

{% hint style="info" %}
The Parent reference is assigned automatically and cannot be changed directly except by moving the game object in the hierarchy.
{% endhint %}

## Display Color

Timeflow may be assigned a display color to differentiate it from other instances in the scene. This color is also displayed as a thin horizontal line above the timeline in the Timeflow view.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FVwyyaS4vWE8NItu7B9kF%2Fimage.png?alt=media&amp;token=8180904e-531d-4e97-8bc4-0413334f34c4" alt=""><figcaption><p>When working with multiple Timeflow instances, the thin line of color can be a helpful aid to see which instance is active.</p></figcaption></figure>

## Sync Timeline Director

Enable this option to synchronize Unity [Timeline](https://docs.unity3d.com/Manual/com.unity.timeline.html) with Timeflow. This is covered further in the [Timeline Integration](/timeflow/reference/extensions/unity-timeline.md) documentation. Only enable this feature if using Unity Timeline.

## Options

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FYPEir66wRITociQ1Sfv1%2Fimage.png?alt=media&amp;token=dfbccca7-02f9-4d39-a30a-402a234fa465" alt=""><figcaption><p>Note that these features are disabled by default but enabled here to demonstrate. Only enable them if used.</p></figcaption></figure>

### Set Shader Time

Enabled this update shader values with the current time to drive effects and material animations. This provides the current time in shaders (such as when using ShaderGraph) to synchronize with Timeflow.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FxZQZC3YrWrSwrhhQf20I%2Fimage.png?alt=media&amp;token=0f323d58-e900-4f1b-a8c8-9177473a7332" alt=""><figcaption><p>Sample shaders are included for URP and HDRP.</p></figcaption></figure>

{% hint style="info" %}
The parameter name defaults to "\_TimeflowTime" but can be renamed as needed. This can be used with Shader Graph by creating a property with the same name (\_TimeflowTime).&#x20;
{% endhint %}

{% hint style="warning" %}
Be sure to uncheck the **Exposed** checkbox on the property value so that it is hidden in the inspector, otherwise it will not work.
{% endhint %}

At runtime this value is set with the following call each frame:

```
Shader.SetGlobalFloat(ShaderTimeName, CurrentTime);
```

### Set Shader Frame

Similar to setting the time, this sets the current frame number, based on the [FPS ](/timeflow/user-guide/timeflow-editor/time.md#fps)in the Timeflow settings. This feature is rarely used and is only relevant for frame-based shaders, such as creating stop motion or flipbook style effects.

## Focus / Background Synchronization

Timeflow uses a real-time `Stopwatch` to drive playback, while Unity's gameplay systems (Game Creator, Unity Splines, `Time.deltaTime`-based movement, etc.) are governed by `Time.timeScale` and Unity's internal update loop. When the application loses focus—or when **Run In Background** is disabled—these two clocks can drift apart, causing cameras to jump, characters to freeze, or animations to fall out of sync on focus return.

The four settings below give you precise control over how Timeflow behaves during focus loss and recovery.

***

### Settings

All four settings are exposed on the `Timeflow` component under **Settings → Options → Focus / Background** in the Inspector.

***

#### Pause On Focus Lost

|             |                    |
| ----------- | ------------------ |
| **Type**    | `bool`             |
| **Default** | `false`            |
| **Field**   | `PauseOnFocusLost` |

When enabled, every root-level `Timeflow` instance that is currently playing is stopped the moment the application loses OS focus. Only root instances are affected; nested precomps inherit their timing from a parent and are therefore excluded.

The instances that were stopped are recorded internally so that only *those* instances are resumed later—not every Timeflow in the scene.

> **Tip:** Enable this alongside **Resume On Focus Return** for a clean pause-and-resume cycle that requires no scripting.

***

#### Sync Run In Background

|             |                           |
| ----------- | ------------------------- |
| **Type**    | `bool`                    |
| **Default** | `true`                    |
| **Field**   | `SyncWithRunInBackground` |

When enabled, Timeflow respects Unity's own **Run In Background** player setting (`Application.runInBackground`).

* If **Run In Background** is **disabled** in Unity (the default for most desktop games), Timeflow automatically pauses when focus is lost—even if **Pause On Focus Lost** is off.
* If **Run In Background** is **enabled**, this setting has no additional effect beyond what **Pause On Focus Lost** already controls.

This setting exists so that Timeflow's behaviour stays consistent with the rest of the engine without requiring you to duplicate the intent across two separate toggles.

***

#### Resume On Focus Return

|             |                       |
| ----------- | --------------------- |
| **Type**    | `bool`                |
| **Default** | `true`                |
| **Field**   | `ResumeOnFocusReturn` |

When enabled, any Timeflow instance that was stopped by a focus-loss event is automatically resumed when the application regains focus.

Resuming is delayed by two frames to allow Unity to finish its own internal focus-return setup (input systems, physics warm-up, etc.) before Timeflow restarts its `Stopwatch`. This prevents a large artificial `DeltaTime` spike on the first resumed frame.

If this setting is disabled, Timeflow stays paused after focus returns and must be resumed manually (e.g., by calling `Play()` from a script or UI button).

> **Note:** Only the instances that were paused by the focus-loss event are resumed. Timeflows that were already stopped before focus was lost are left unchanged.

***

#### Pause Time Scale

|             |                                  |
| ----------- | -------------------------------- |
| **Type**    | `bool`                           |
| **Default** | `false`                          |
| **Field**   | `PauseUnityTimeScaleOnFocusLost` |

When enabled, `Time.timeScale` is set to `0` at the moment focus is lost, and the original value is restored when focus returns.

This is the key setting for synchronizing Timeflow with external gameplay systems that rely on `Time.deltaTime`—such as character controllers, physics, Game Creator actions, or Unity Splines path followers. Without it, those systems continue to accumulate time (or are suspended unpredictably by the OS) independently of Timeflow's `Stopwatch`, which causes desynchronization on focus return.

**On focus loss:**

1. The current `Time.timeScale` is saved.
2. `Time.timeScale` is set to `0`, freezing all `deltaTime`-based systems.
3. Playing root Timeflow instances are stopped (if **Pause On Focus Lost** or **Sync Run In Background** requires it).
4. The active Timeflow's `Stopwatch` is stopped.

**On focus return (after the two-frame delay):**

1. The saved `Time.timeScale` is restored (never forced to `1`).
2. The `Stopwatch` is restarted with a clean elapsed time.
3. Previously playing instances are resumed.

{% hint style="warning" %}
**Warning:** Setting this to `true` while **Global Time Scale** is also enabled may produce unexpected interactions if `CanSetGlobalTimeScale` writes to `Time.timeScale` on the same frame focus is restored. In that case, the saved time-scale value takes precedence during the focus-return path.
{% endhint %}

***

### How the Settings Interact

The pause trigger fires when **either** of these conditions is true at focus loss:

Both `OnApplicationFocus` and `OnApplicationPause` are handled. Timeflow remains paused as long as either Unity callback indicates a suspended state, so a sequence of focus-lost → minimize → restore → focus-gained does not prematurely resume playback.

Only the first Timeflow instance to detect a focus-loss event performs the work. Subsequent instances in the same frame are ignored, preventing duplicate stops or conflicting time-scale writes.

Static focus state is reset each time Play Mode is entered in the Editor, ensuring that stale state from a previous session cannot carry over.

***

### Recommended Configurations

| Scenario                                                | Pause On Focus Lost | Sync Run In Background | Resume On Focus Return | Pause Time Scale |
| ------------------------------------------------------- | :-----------------: | :--------------------: | :--------------------: | :--------------: |
| Timeflow-only scene, no gameplay systems                |       `false`       |         `true`         |         `true`         |      `false`     |
| Camera driven by Timeflow + character using `deltaTime` |        `true`       |         `true`         |         `true`         |      `true`      |
| Interactive kiosk / always-on display                   |       `false`       |         `false`        |         `false`        |      `false`     |
| Mobile game (strict lifecycle)                          |        `true`       |         `true`         |         `true`         |      `true`      |
| Manual resume via UI button                             |        `true`       |         `true`         |         `false`        |      `true`      |