Local Time Scale Scripting

v1.0

Check the LocalTimeScale class to view all of the methods available.

Getting the Time Values

The LocalTimeScale will have its own time values similar to the Time class. You can get these using DeltaTime, UnscaledDeltaTime, and FixedDeltaTime.

LocalTimeScale localTimeScale;
float _counter = 0f;
float _fixedDeltaTime;

_counter += localTimeScale.DeltaTime;
_fixedCounter += localTimeScale.FixedDeltaTime;

Getting & Setting the Value

The "Value" is a float representing the percent of "real time". 1f is essentially 100% of Time.deltaTime. The Value property will return the current value, and you can also specifically set this value as well using SetValue(float newValue).

If you're using the MagicTimeUser or IHaveLocalTime interface, often you'll want to know the value of the combined time scales affecting that object. In that case, use the TimeScale property.

// Get the value
LocalTimeScale localTimeScale;
var currentValue = localTimeScale.Value;

// Set the value
float newValue = 0.5f;
localTimeScale.SetValue(newValue);

When the value is changed, the UnityEvent OnTimeScaleChangedUnityEvent and Event OnTimeScaleChanged will be triggered for any subscribers.

If the value is changed to 0f (with or without using the Pause() method), the OnPaused and OnPausedUnityEvent events will be called.

Similarly, if the value changes from 0f to something else, even without using the Resume() method, the OnResumed and OnResumedUnityEvent will be called.

Pausing and Resuming

The Pause() and Resume() methods will set value to 0f, and then return the value to the last cached value. If you know the resumed value should be the same as what it was prior to the "pause" action, then this is often a simpler way of handling this logic. Otherwise, you can always just SetValue(0f) manually.

// Pause this specific localTimeScale
localTimeScale.Pause(); // Will cache the current Value before setting it to 0f.

// Resume this specific localTimeScale
localTimeScale.Resume(); // This will reset to the value when Pause() was called.

Subscribing

Any IHaveLocalTime object can subscribe to a LocalTimeScale object. This will ensure the object gets event notifications from the LocalTimeScale.

Remember, the actual calculations for combined time scale will be handled by the IHaveLocalTime object.

// This is from the "SubscribeToLocalTimeScale(LocalTimeScale myTimeScale)" 
// method on MagicTimeUser.cs

// Can't subscribe to the same timeScale twice.
if (SubscribedTimeScales.Contains(myTimeScale)) return;

SubscribedTimeScales.Add(myTimeScale);
myTimeScale.Subscribe(this);
myTimeScale.OnTimeScaleChanged += OnTimeScaleChanged;

// In this example, we keep track of the timeScales we're subscribed to, and subscribe
// to them at the same time.

When subscribing, the OnSubscribed and OnSubscribedUnityEvent will be called.=

Information About Subscribers

Subscribers are stored in a HashSet<IHaveLocalTime> so there is no index available. There are a few helpful properties that provide more information about subscribers to a specific Local Time Scale.

LocalTimeScale localTimeScale;

// Check the number of subscribers
if (localTimeScale.SubscriberCount == 0)
    return;

// Get the string name of those subscribed
foreach(var subscriberName in localTimeScale.SubscriberNames)
{
    Debug.Log($"{subscriberName} is subscribed");
}

// Get the GameObject of those subscribed
foreach(var subscriberObject in SubscriberGameObjects)
{
    DoSomethingWithSubscriber(subscriberObject);
}

Unsubscribing

You can use the UnsubscribeAll() method to call Unsubscribe() on all current subscribers.

The Unsubscribe(IHaveLocalTime subscriber) method does a few things, if the subscriber passed in is actually subscribed.

First, it will remove the subscriber from the Subscribers list, as you might expect. But it also will call subscriber.UnsubscribeFromLocalTimeScale(this), which allows the subscriber to take any actions as needed.

// This is the method from MagicTimeUser.cs
public virtual void UnsubscribeFromLocalTimeScale(LocalTimeScale timeScale)
{
    if (timeScale == null)
        return;

    // If it is in our list, then unsubscribe and remove it.
    if (SubscribedTimeScales.Contains(timeScale))
    {
        timeScale.Unsubscribe(this);
        SubscribedTimeScales.Remove(timeScale);
    }
            
    // This can be called from the LocalTimeScale, so we may need to reset the desired timeScale, 
    // even if the timeScale is not in our list.
    ResetDesiredTimeScale();
}

Next, the OnUnsubscribed and OnUnsubscribedUnityEvent will be called as well, on the Local Time Scale object. Both of these will pass the subscriber (IHaveLocalTime) object in as a parameter.

Finally, if AutoRemoveWhenEmpty is true, the time scale will be removed. See details below.

Automatically Removing the LocalTimeScale

In some cases, you may wish to automatically remove a LocalTimeScale when there are no subscribers.

localTimeScale.AutoRemoveWhenEmpty = true;

Set AutoRemoveWhenEmpty to true, and then whenever subscribers Unsubscribe() from the Local Time Scale, if there are no subscribers left, then the MagicTimeManager method RemoveTimeScale() method will be called, removing this object.

The check only happens when the Unsubscribe() method is called, so you can safely set this value to true before any subscribers are active.

Subscribing to Events

Classes can subscribe to individual events on the LocalTimeScale class. This is useful to perform actions based on changes to the Local Time Scale.

In the example below, from ZoneColorChanger.cs in the demo, we subscribe and unsubscribe to events on the LocalTimeScale attached to a specific time zone.

In this case, the LocalTimeScale instance is created at runtime, so it will not be availalbe immediately. To handle this, we can subscribe via a Coroutine, which is started OnEnable().

private void OnEnable() => StartCoroutine(SubscribeToTimeScale());

private void OnDisable()
{
    timeZone.TimeScale.OnSubscribed -= OnSubscribed;
    timeZone.TimeScale.OnUnsubscribed -= OnUnsubscribed;
}

private IEnumerator SubscribeToTimeScale()
{
    yield return new WaitUntil(() => timeZone.TimeScale != null);
    timeZone.TimeScale.OnSubscribed += OnSubscribed;
    timeZone.TimeScale.OnUnsubscribed += OnUnsubscribed;
}

// Handle the events -- make sure the object passed is the right type
private void OnSubscribed(object go)
{
    var newObject = (IHaveLocalTime)go;
    if (newObject == null) return;
            
    var newGameObject = newObject.GameObject;
    if (newGameObject == null) return;
            
    AddColor(newGameObject);
}

private void OnUnsubscribed(object go)
{
    var newObject = (IHaveLocalTime)go;
    if (newObject == null) return;
            
    var newGameObject = newObject.GameObject;
    if (newGameObject == null) return;
            
    RemoveColor(newGameObject);
}