TS Tween System

A full featured typescript tweening system that supports both simple on-off tweens of Entity properties as well as complex sequential, parallel, nested timeline based, and spline path animations.

Comment 1

Inspiration

When we moved from CodeBlocks to TypeScript, we lost the built-in linear tweening support we had with the "overTime" codeblock commands. Now that we have TypeScript, we can make much more exciting tweening operations, including a variety of complex easing functions other than 'linear'.

What it does

Provides a timeline based tweening library for typescript scripters. Virtually any WriteableHorizonProperty can be animated, as the system uses sophisticated typescript features to strongly type Entity property access, while still being flexible. The library includes both a simple public function:

tweenTo<T>(property: HorizonProperty<T>, end: T, duration: number, easing: EasingFunction)

that will tween, with easing, a horizon property from its current value to the end value over some number of seconds, as well as a sophisticated TweenTimeline API that that allows you to place different Tweens at different start positions on the timeline, in sequence or in parallel with one another, and then optionally yoyo (i.e. bounce) or repeat some number of times (or forever).

An extensive set of example usages of the asset in action is available in the "TS Tween System Examples" world, which I published as remixable so that people can easily get and see the source code for how all the examples are implemented.

How we built it

I researched a number of existing Typescript (and Javascript) tweening library APIs to try to find inspiration from mechanics had an established following, but implement their functionality in a Horizon Worlds specific way. This codebase probably draws the most inspiration from the MIT licensed https://github.com/tweenjs/tween.js codebase, but due to the many differences between HTML DOM and the HZW scene graph, it is substantially different in many ways.

A guiding principle was abstraction and enabling sophisticated use cases, while still making 'easy things easy' for users who did not want all the complexities and power of composable timeline management.

Challenges we ran into

When building a code-only asset, especially one that has an API more than just Entities with Components running on them, managing all the different .ts files is a bit tricky. If a Typescript file is referenced by an asset but not included as a Gizmo in the asset, it will not be part of the published package. Getting this right requires carefully spawning out and grouping Script Gizmos into the asset definition.

Additionally, visualizing what a complex timeline is going to do is not easy when all you have is the code to compose the parts together.

Finally, it's not really practical to make a code-based asset really 'self contained' with both all the functionality and examples or explanatory TextGizmos. People are not going to want the examples and text after they have studied and understood them. But if they 'delete' them from the instantiated asset, they will need to 'unlink' the asset from the source, meaning they will no longer get any feature and bug fix update notifications. So, all the examples had to be moved to a different published world.

Accomplishments that we're proud of

I am particularly happy with how the TweenTimeline composition turned out. You can make very sophisticated animations by composing a number of Tweens of individual position/rotation/color/etc. in parallel, and then composing those in series, and running the whole compound timeline with a single easing function.

Additionally, due to the abstracted architecture of the library, it is possible to 'scrub' the tweens idea of the clock time backwards and forwards at will. A demo of this in the "TS Tween System Examples" world shows this in action (best viewed via VR).

What we learned

There's a lot of depth possible when building a timeline animation system. There certainly is more that I would like to do, but given that all the timeline configuration needs to currently be done solely in code, it requires the user to 'think hard' about visualizing how the timeline would come together. The ability to create 'editor tools' in the DE that allowed visualizing and manipulating the timeline setup would make using the library a lot simpler.

What's next for My Entry

I think that it might be interesting to try creating the timeline composition Builder API in a somewhat different way that more closely matches what the Custom UI AnimationBinding does, rather than what people happen to use for HTML / DOM easing, as Horizon Worlds developers are likely more familiar with the Custom UI way of doing things than web developers.

Built With

Share this project:

Updates