Wave

The Wave class significantly streamlines the process of creating periodic animations.

Be aware it is a valid AutoParameterBundle.

Defining a wave

Waves are defined by, and created using, eight different parameters, which are as follows:

Upward Curve: Defines the "shape" of the half of the curve that moves up
Downward Curve: Defines the "shape" of the half of the curve that moves down
Up Period: Defines the amount of time it takes to travel the upward curve
Down Period: Defines the amount of time it takes to travel the downward curve
Amplitude: Defines the maximum value the wave reaches; this is 1 by default
Crest Wait: Defines the amount of time the wave maintains its peak
Trough Wait: Defines the amount of time the wave maintains its minimum

The following diagram illustrates the first five parameters. On the left you see the upward curve, on the right the downward curve.

The second diagram illustrates crest and trough wait.
Both essentially insert a period of time during which the wave's value does not change.

Wave offsets

In addition to the time value, Wave's evaluation methods (see below) accept an offset parameter. This allows you to easily apply the wave non-uniformly across an animated segment of text. In almost all cases, you will want to get this offset using an OffsetProvider.

To visualise, below you see the same animation with the exact same wave, all using the same index-based offset but different uniformities (the uniformity is essentially a simple scalar of the offset). The first animation uses uniformity = 0, the second uniformity = 0.25, the third uniformity = 1.

Evaluating a wave

You can evaluate Waves using a time value and an offset value: (float value, int direction) Evaluate(float time, float offset).
As you can tell by the signature, Evaluate returns two values. value is the actual evaluated value of the curve for the given time and offset. directionindicates whether the curve is currently travelling up or down; if it is negative, the curve is moving down, if it is positive, the curve is moving up. This value is useful for when you want to switch the behavior of your animation depending on what curve the wave is currently travelling.
For example, the built-in fade animation can use different anchors depending on whether the character is fading in or out. The animation below visualizes how fade uses both values of the Evaluate method.

Checking wave extrema

You can check if the wave passed an extrema (so either the crest or the trough) during the last update, using the int PassedExtrema(float time, float deltaTime, float offset) method. Once again, you need the time value and the offset, and additionally here you need the deltaTime since you last checked. Essentially, the method checks whether the wave passed an extrema during the time interval of [timeValue - deltaTime, timeValue]. A positive return value indicates that a maximum was passed, a negative return value indicates that a minimum was passed, and 0 indicates neither was.

An additional, optional parameter is PulseExtrema. If the checked wave has a crest or trough wait, this parameter defines whether an extremum is passed once the wait time begins, or once it ends. PulseExtrema can also consider both to be an extrema, but of course be aware that it will then notify you of each extremum twice.

If multiple extrema were passed during the specified interval, it will notify you of the latest one.

Bundle parameters

As mentioned above, waves are AutoParameter bundles. The parameters defined by it are (Type name - aliases):