BorrowedTorch.Animations
1.1.0
Prefix Reserved
dotnet add package BorrowedTorch.Animations --version 1.1.0
NuGet\Install-Package BorrowedTorch.Animations -Version 1.1.0
<PackageReference Include="BorrowedTorch.Animations" Version="1.1.0" />
<PackageVersion Include="BorrowedTorch.Animations" Version="1.1.0" />
<PackageReference Include="BorrowedTorch.Animations" />
paket add BorrowedTorch.Animations --version 1.1.0
#r "nuget: BorrowedTorch.Animations, 1.1.0"
#:package BorrowedTorch.Animations@1.1.0
#addin nuget:?package=BorrowedTorch.Animations&version=1.1.0
#tool nuget:?package=BorrowedTorch.Animations&version=1.1.0
BorrowedTorch.Animations
Animations for MonoGame: a time line that runs once, loops, ping-pongs or accumulates, and keys that a value is blended or switched between, eased by shaping functions. One model for everything in a game that moves by time - a UI's properties, a camera along its path, an entity's properties in the engine.
Install
dotnet add package BorrowedTorch.Animations
Targets net10.0. Depends on BorrowedTorch.ShapingFunctions (the easing curves). It is compiled against MonoGame
3.8.1.303 without depending on it: the game brings its own MonoGame - DesktopGL, WindowsDX or BorrowedTorch's compute
fork, 3.8.1.303 or newer - whose vector, colour and rotation types it blends.
Quick start
using BorrowedTorch.Animations;
// A lamp's intensity: up to 3 over a second, down to 0.5 by the second after, there and back for ever.
var clip = new AnimationClip<float>
{
Type = AnimationType.Smooth,
Repeat = RepeatMode.PingPong,
Keys = [new(1.0, 3.0f, new CubicEaseOut()), new(2.0, 0.5f)]
};
var timeline = clip.CreateTimeline();
var start = lamp.Intensity; // where it starts from: the value at 0, unless a key lies there
timeline.Play();
// Update, once per frame:
timeline.Advance(elapsedSeconds);
lamp.Intensity = clip.ValueAt(timeline, start);
The time line
AnimationTimeline is where an animation is in its time, and whether that moves. It knows nothing of values, so one
time line can drive anything: a property, a camera along a path (a run of 1, advanced by the share of the run each
frame),
several properties together.
Play()runs it - on from where it was paused, from the start when it was stopped or has completed.Pause()holds it,Stop()puts it back at the start,Seek(seconds)shows a moment of it (pausing one that isn't running there).Reverse()runs it back toward the start from where it is, completing there - a loop through the run it is in, a ping-pong back along the way it came, an accumulating one unwinding its time;Forward()runs it on from where it is, never from the start again (one completed at its end stays there). Run forward and back in turn - a door opened and closed - it never jumps.IsBackwardsays which way it runs.Advance(seconds)moves it on while it runs. A long step is walked boundary by boundary: it turns round where it should, counts its runs, completes on its exact end, and skips the whole runs that fit in it at once.Repeat:Once(completes at its end),Loop(back to the start),PingPong(there and back, completing at the start) - both forRepeatsruns, 0 for ever - andAccumulate, which never completes.Positionis where it is in the run, 0 toDuration, going back on a ping-pong's way back;Elapsedis the time it has run since it was played from the start, the time it stood still not counted.State:Stopped,Running,PausedorCompleted.
The clip
AnimationClip<T> is an animation as data - immutable, so it can be shared, compared and swapped whole while it runs.
- Keys (
AnimationKey<T>(time, value, easing)) are kept sorted by time; of keys of one time, the last given holds. The animation starts from a value of the caller's - typically the property's own value as it was started - which is its value at 0 unless a key lies there. After its last key it keeps that key's value.Durationis its last key's time. Type:Discretechanges only on a key's time, to its value;Smoothblends from one key to the next, eased by the later key's shaping function (linearly without one).- Accumulating (
Repeat = RepeatMode.Accumulate) it has no keys:Stepis added everyPeriodseconds, for as long as it runs - all at once on each period (Discrete), or a share of it every moment, so that a period adds the step on average (Smooth). The value is worked out from the time run, never summed up a frame at a time: it neither drifts nor depends on the frame rate. Configure(timeline)hands a time line the clip's run and repeats, leaving its state alone - after the clip is edited mid-run, say.
Values
AnimationValues blends, adds and scales values: int, long, float, double, Vector2, Vector3, Vector4,
Color (channel by channel, within a byte), Point, Rectangle and Quaternion (a slerp; added, turned on by the
step's turn; scaled, its turn taken as many times about its axis). AnimationValues.Use<T>(blend, add, scale) makes any
other type known. Of a type it does not know, a blend switches from the one value to the other at the end of the way.
The operations of each type are made once as typed delegates, so nothing is boxed however often values are blended.
Changelog
1.1.0
- Compiled against MonoGame 3.8.1.303 instead of 3.8.0.1641, as every BorrowedTorch library that does not need the compute fork now is. A game needs MonoGame 3.8.1.303 or newer - DesktopGL, WindowsDX or BorrowedTorch's compute fork; 3.8.0 no longer loads it.
AnimationTimeline.Reverse()andForward(): run back toward the start, or on toward the end, from where it is;IsBackward.Play()turns round one running back. Nothing else changes for callers that never reverse.
1.0.0
AnimationTimeline,AnimationClip<T>,AnimationKey<T>andAnimationValues: once, loop, ping-pong and accumulate, discrete and smooth.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- BorrowedTorch.ShapingFunctions (>= 1.6.1)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on BorrowedTorch.Animations:
| Package | Downloads |
|---|---|
|
BorrowedTorch.UI
UI framework for MonoGame games on Windows (DesktopGL and WindowsDX): WPF-style measure and arrange layout with margins, alignments and fit-to-content sizes; dependency properties that are set by hand, by styles or bound to view models; and ready-made controls such as buttons, check boxes, sliders, list and combo boxes, tree views, context menus, tooltips, windows and rich text boxes, all drawn with one SpriteBatch. |
|
|
BorrowedTorch.Camera
Camera functionality. |
|
|
BorrowedTorch.Drivers
Drivers: a value worked out every frame by a graph of nodes - inputs, logic, maths, memory, timers and animations started and reversed by pulses - for a property driven by others, by triggers and by time. |
|
|
BorrowedTorch.Engine
Kindling, Borrowed Torch's game engine: what a game's own code builds against - its features registering components, systems, keys and UI handlers - for the Kindling editor and player to run |
GitHub repositories
This package is not used by any popular GitHub repositories.