Mirror.SnapshotInterpolation Class Reference

Static Public Member Functions
static double	Timescale (double drift, double catchupSpeed, double slowdownSpeed, double catchupNegativeThreshold, double catchupPositiveThreshold)
static double	DynamicAdjustment (double sendInterval, double jitterStandardDeviation, double dynamicAdjustmentTolerance)
static void	Insert< T > (SortedList< double, T > buffer, T snapshot, ref double localTimeline, ref double localTimescale, float sendInterval, double bufferTime, double catchupSpeed, double slowdownSpeed, ref ExponentialMovingAverage driftEma, float catchupNegativeThreshold, float catchupPositiveThreshold, ref ExponentialMovingAverage deliveryTimeEma)
static void	Sample< T > (SortedList< double, T > buffer, double localTimeline, out int from, out int to, out double t)
static bool	Step< T > (SortedList< double, T > buffer, double deltaTime, ref double localTimeline, double localTimescale, Func< T, T, double, T > Interpolate, out T computed)

Detailed Description

Definition at line 28 of file SnapshotInterpolation.cs.

Member Function Documentation

DynamicAdjustment()

static double Mirror.SnapshotInterpolation.DynamicAdjustment ( double  sendInterval, double  jitterStandardDeviation, double  dynamicAdjustmentTolerance  )

static

Definition at line 65 of file SnapshotInterpolation.cs.

        {
            // jitter is equal to delivery time standard variation.
            // delivery time is made up of 'sendInterval+jitter'.
            //   .Average would be dampened by the constant sendInterval
            //   .StandardDeviation is the changes in 'jitter' that we want
            // so add it to send interval again.
            double intervalWithJitter = sendInterval + jitterStandardDeviation;
 
            // how many multiples of sendInterval is that?
            // we want to convert to bufferTimeMultiplier later.
            double multiples = intervalWithJitter / sendInterval;
 
            // add the tolerance
            double safezone = multiples + dynamicAdjustmentTolerance;
            // UnityEngine.Debug.Log($"sendInterval={sendInterval:F3} jitter std={jitterStandardDeviation:F3} => that is ~{multiples:F1} x sendInterval + {dynamicAdjustmentTolerance} => dynamic bufferTimeMultiplier={safezone}");
            return safezone;
        }

Insert< T >()

static void Mirror.SnapshotInterpolation.Insert< T > ( SortedList< double, T >  buffer, T  snapshot, ref double  localTimeline, ref double  localTimescale, float  sendInterval, double  bufferTime, double  catchupSpeed, double  slowdownSpeed, ref ExponentialMovingAverage  driftEma, float  catchupNegativeThreshold, float  catchupPositiveThreshold, ref ExponentialMovingAverage  deliveryTimeEma  )

static

Type Constraints

T

:

Snapshot

Definition at line 89 of file SnapshotInterpolation.cs.

                    : Snapshot
        {
            // first snapshot?
            // initialize local timeline.
            // we want it to be behind by 'offset'.
            //
            // note that the first snapshot may be a lagging packet.
            // so we would always be behind by that lag.
            // this requires catchup later.
            if (buffer.Count == 0)
                localTimeline = snapshot.remoteTime - bufferTime;
 
            // insert into the buffer.
            //
            // note that we might insert it between our current interpolation
            // which is fine, it adds another data point for accuracy.
            //
            // note that insert may be called twice for the same key.
            // by default, this would throw.
            // need to handle it silently.
            if (!buffer.ContainsKey(snapshot.remoteTime))
            {
                buffer.Add(snapshot.remoteTime, snapshot);
 
                // dynamic buffer adjustment needs delivery interval jitter
                if (buffer.Count >= 2)
                {
                    // note that this is not entirely accurate for scrambled inserts.
                    //
                    // we always use the last two, not what we just inserted
                    // even if we were to use the diff for what we just inserted,
                    // a scrambled insert would still not be 100% accurate:
                    // => assume a buffer of AC, with delivery time C-A
                    // => we then insert B, with delivery time B-A
                    // => but then technically the first C-A wasn't correct,
                    //    as it would have to be C-B
                    //
                    // in practice, scramble is rare and won't make much difference
                    double previousLocalTime = buffer.Values[buffer.Count - 2].localTime;
                    double lastestLocalTime  = buffer.Values[buffer.Count - 1].localTime;
 
                    // this is the delivery time since last snapshot
                    double localDeliveryTime = lastestLocalTime - previousLocalTime;
 
                    // feed the local delivery time to the EMA.
                    // this is what the original stream did too.
                    // our final dynamic buffer adjustment is different though.
                    // we use standard deviation instead of average.
                    deliveryTimeEma.Add(localDeliveryTime);
                }
 
                // adjust timescale to catch up / slow down after each insertion
                // because that is when we add new values to our EMA.
 
                // we want localTimeline to be about 'bufferTime' behind.
                // for that, we need the delivery time EMA.
                // snapshots may arrive out of order, we can not use last-timeline.
                // we need to use the inserted snapshot's time - timeline.
                double latestRemoteTime = snapshot.remoteTime;
                double timeDiff         = latestRemoteTime - localTimeline;
 
                // next, calculate average of a few seconds worth of timediffs.
                // this gives smoother results.
                //
                // to calculate the average, we could simply loop through the
                // last 'n' seconds worth of timediffs, but:
                // - our buffer may only store a few snapshots (bufferTime)
                // - looping through seconds worth of snapshots every time is
                //   expensive
                //
                // to solve this, we use an exponential moving average.
                // https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average
                // which is basically fancy math to do the same but faster.
                // additionally, it allows us to look at more timeDiff values
                // than we sould have access to in our buffer :)
                driftEma.Add(timeDiff);
 
                // next up, calculate how far we are currently away from bufferTime
                double drift = driftEma.Value - bufferTime;
 
                // convert relative thresholds to absolute values based on sendInterval
                double absoluteNegativeThreshold = sendInterval * catchupNegativeThreshold;
                double absolutePositiveThreshold = sendInterval * catchupPositiveThreshold;
 
                // next, set localTimescale to catchup consistently in Update().
                // we quantize between default/catchup/slowdown,
                // this way we have 'default' speed most of the time(!).
                // and only catch up / slow down for a little bit occasionally.
                // a consistent multiplier would never be exactly 1.0.
                localTimescale = Timescale(drift, catchupSpeed, slowdownSpeed, absoluteNegativeThreshold, absolutePositiveThreshold);
 
                // debug logging
                // UnityEngine.Debug.Log($"sendInterval={sendInterval:F3} bufferTime={bufferTime:F3} drift={drift:F3} driftEma={driftEma.Value:F3} timescale={localTimescale:F3} deliveryIntervalEma={deliveryTimeEma.Value:F3}");
            }
        }

Sample< T >()

static void Mirror.SnapshotInterpolation.Sample< T > ( SortedList< double, T >  buffer, double  localTimeline, out int  from, out int  to, out double  t  )

static

Type Constraints

T

:

Snapshot

Definition at line 202 of file SnapshotInterpolation.cs.

                    : Snapshot
        {
            from = -1;
            to = -1;
            t = 0;
 
            // sample from [0,count-1] so we always have two at 'i' and 'i+1'.
            for (int i = 0; i < buffer.Count - 1; ++i)
            {
                // is local time between these two?
                T first  = buffer.Values[i];
                T second = buffer.Values[i + 1];
                if (localTimeline >= first.remoteTime &&
                    localTimeline <= second.remoteTime)
                {
                    // use these two snapshots
                    from = i;
                    to = i + 1;
                    t = Mathd.InverseLerp(first.remoteTime, second.remoteTime, localTimeline);
                    return;
                }
            }
 
            // didn't find two snapshots around local time.
            // so pick either the first or last, depending on which is closer.
 
            // oldest snapshot ahead of local time?
            if (buffer.Values[0].remoteTime > localTimeline)
            {
                from = to = 0;
                t = 0;
            }
            // otherwise initialize both to the last one
            else
            {
                from = to = buffer.Count - 1;
                t = 0;
            }
        }

Step< T >()

static bool Mirror.SnapshotInterpolation.Step< T > ( SortedList< double, T >  buffer, double  deltaTime, ref double  localTimeline, double  localTimescale, Func< T, T, double, T >  Interpolate, out T  computed  )

static

Type Constraints

T

:

Snapshot

Definition at line 251 of file SnapshotInterpolation.cs.

                    : Snapshot
        {
            computed = default;
 
            // nothing to do if there are no snapshots at all yet
            if (buffer.Count == 0)
                return false;
 
            // move local forward in time, scaled with catchup / slowdown applied
            localTimeline += deltaTime * localTimescale;
 
            // sample snapshot buffer at local interpolation time
            Sample(buffer, localTimeline, out int from, out int to, out double t);
 
            // now interpolate between from & to (clamped)
            T fromSnap = buffer.Values[from];
            T toSnap   = buffer.Values[to];
            computed = Interpolate(fromSnap, toSnap, t);
            // UnityEngine.Debug.Log($"step from: {from} to {to}");
 
            // remove older snapshots that we definitely don't need anymore.
            // after(!) using the indices.
            //
            // if we have 3 snapshots and we are between 2nd and 3rd:
            //   from = 1, to = 2
            // then we need to remove the first one, which is exactly 'from'.
            // because 'from-1' = 0 would remove none.
            buffer.RemoveRange(from);
 
            // return the interpolated snapshot
            return true;
        }

Timescale()

static double Mirror.SnapshotInterpolation.Timescale ( double  drift, double  catchupSpeed, double  slowdownSpeed, double  catchupNegativeThreshold, double  catchupPositiveThreshold  )

static

Definition at line 34 of file SnapshotInterpolation.cs.

        {
            // if the drift time is too large, it means we are behind more time.
            // so we need to speed up the timescale.
            // note the threshold should be sendInterval * catchupThreshold.
            if (drift > catchupPositiveThreshold)
            {
                // localTimeline += 0.001; // too simple, this would ping pong
                return 1 + catchupSpeed; // n% faster
            }
 
            // if the drift time is too small, it means we are ahead of time.
            // so we need to slow down the timescale.
            // note the threshold should be sendInterval * catchupThreshold.
            if (drift < catchupNegativeThreshold)
            {
                // localTimeline -= 0.001; // too simple, this would ping pong
                return 1 - slowdownSpeed; // n% slower
            }
 
            // keep constant timescale while within threshold.
            // this way we have perfectly smooth speed most of the time.
            return 1;
        }