6. Choice of web app animation framework¶

We use SVG images for graphics in CTGames because they are scalable for multiple screen resolutions (phones, tablets, and computer screens) and also for high-resolution printing (posters and workbooks of computational thinking puzzles using the graphics directly from CTGames games).

We use the Greensock GSAP JavaScript animation library to animate SVG images in the CTGames framework. Deciding on GSAP was not a straightforward process. This section explains the reasoning behind choosing GSAP.

There are tens if not hundreds of different ways to animate objects in the DOM through JavaScript and CSS, all of which can be accessed using Brython. One of the reasons for writing this section is to remember the reasons behind our decision should we decide to revisit the choice of animation library again.

6.1. Requirements for the CTGames SVG animation library¶

Our requirements for animation are two fold. First, we want to be able to move/rotate/modify SVG elements in the web app, and secondly we need a way to dynamically construct timelines.

Timelines offer the capability to dynamically construct sequences of animation steps where:

the steps are not known in advance; they are specified by a CTGames player while playing a CTGames game (e.g. a game that asks the player to program a robot using a simple programming language),
steps can be specified to be performed in sequence (when one ends, the next one automatically starts, without having to hard-code complicated timing delays/durations), and
steps can be specified to be performed in parallel.

Beyond these requirements, we have a strong preference for a free and open source animation library, rather than a proprietary/commercial one, should one be found that offers:

comparable reliability and ease of use as other libraries
has a large user base and/or multiple developers
fixes bugs at least on an annual basis

6.2. Technologies available¶

The different technologies we investigated are summarised in this section.

6.2.1. Direct manipulation of attributes and `requestAnimationFrame()`¶

SVG images have attributes such as position-related attributes (x, y), dimensions-related attributes (scale, width, height), opacity, transform, and so on. The transform attribute of SVG elements allows various transform functions such as rotate, translate, skew, and scale. Official docs for both SVG 1.1 transforms and SVG 2.0 transforms are available to learn more about the SVG transform attribute, as well as stakeholder tutorials and in-depth blog posts.

Changing attribute values and transform function parameters in a SVG image have an immediate effect. However, by incrementally changing the values while calling the JavaScript function requestAnimationFrame() one can have full control of an animation effect.

6.2.2. Native SVG animations (SMIL and SVG 2.0)¶

A complicated mixture of approaches exists to animate SVG objects in browsers. The most basic approach is to use SVG elements such as the <animate> element, for example with its from and to attributes as in <animate attributeType="XML" attributeName="x" from="0" to="100" dur="3s"/>.

The built-in animation features in SVG 1.1 are defined in terms of a separate standard called SMIL (see SMIL 3.0 Animation) which is widely supported by all browsers.

6.2.3. Web Animations API¶

Something that Chrome is willing to support is the Web Animations API, a proposal to combine several existing SVG animation approaches into one framework, that is also well-supported by other browsers. Stakeholder docs and tutorials are available.

However, the Web Animations API is quite low level and would require a high-level library to be written using Brython to make it convenient to use for timelines, for example. Although the official docs make it look full-featured, the limited examples in stakeholder docs and online tutorials make it seem rather limited.

6.2.4. CSS animations¶

CSS animations are nice and simple, but you cannot specify that one animation should start when another one ends. Instead you have to manually hardcode durations/delays to sync multiple animations.

6.2.5. JavaScript animation library¶

Several free and open source SVG animation libraries exist, but we were worried about tying ourselves to a JavaScript library that may not be actively developed in the future if it did not have a large user base. Commercial options exist also, but for CTGames a paid subscription model is uneconomical as we often have a half year and longer breaks in new games development.

So we tried special purpose libraries that would smooth over the uneven SVG support among browser implementations (reduces the need to test on multiple browsers and operating systems – for example Chrome currently (2021) uses WebKit on iOS and Blink on all other operating systems).

Snap.svg
Snap.svg is the successor to the well-known Raphaël JavaScript library that still has a very large user base. The author of Raphaël discontinued it to instead create Snap.svg as a more modern equivalent. Unfortunately, Snap.svg has some well-publicised bugs that limit its functionality. The author has discontinued work on Snap.svg, with the latest version being v0.5.1 from February 2017, so it is unlikely these bugs will get fixed.
SVG.js
SVG.js is faster than Snap.svg and contains all of the functionality needed for CTGames, including timelines. It has good documentation, a bunch of CSS-Tricks articles, and a large user base. It is actively maintained with regular releases and 9.5k GitHub stars, and its own tag with 500+ tagged questions on Stack Overflow (all as of early 2022).
Velocity
The Velocity JavaScript animation library is a very high quality and extensive library that looks like it has everything needed for CTGames. However, the docs seem to be written for someone coming from jQuery (jQuery is mentioned 81 times on the first page of the website — tested 5 March 2022). The Python developers of CTGames are using Brython because they don’t want to have to learn JavaScript just to make a web app, and it seems that learning about jQuery is a prerequisite in order to use Velocity.
GSAP
Greensock GSAP is a very polished JavaScript animation library that claims to always use the most efficient JavaScript solution under the hood, and to smooth over (SVG, and other) specification implementation differences between browsers. The documentation is extensive, online tutorials are numerous, and the user base seems very large (1,600+ tagged questions on Stack Overflow, and Greensock claims GSAP is used by 8.5 million websites). The basic version of GSAP (which is sufficient for CTGames) is open source software, however it uses a licence that restricts it to non-commercial projects – a paid version of GSAP is needed to build commercial products.

6.2.6. Libraries with timeline support¶

We need timeline functionality to allow the CTGames games programmers to conveniently program animations for their games. Options include:

writing our own timeline library using the JavaScript function requestAnimationFrame() or the equivalent function in the Web Animations API; for example, a function for translation would have to be written that takes a SVG image and translation parameters as arguments and repeatedly updates the values in the SVG’s attributes by some small increment while calling requestAnimationFrame() each time for a smooth animation,
the Web Animations API has full-featured but low-level timeline support through DocumentTimeline objects,
the Snapsvg Animation Queue provides timeline support for Snap.svg,
Tweene provides timeline support for the Velocity JavaScript library, and
use an all-in-one solution of an animation library that includes timeline functionality, for example SVG.js and GSAP provide their own high-level timeline support.

6.2.7. Summary¶

In summary:

Animating with CSS
— does not offer full control of animations
Animating with SVG 2.0 or SMIL
— offers full control from Brython, but Chrome is slow to adopt the former and may drop support for the latter
Animating with the Web Animations API
— offers full control from Brython, but low-level (will require us to write higher-level Brython wrapper functions)
Animating with JavaScript (using requestAnimationFrame())
— offers full control from Brython, but low-level (will require us to write our own timeline library, for example)
Animating with JavaScript (using a library such as Snap.svg, SVG.js, GSAP, Velocity)
— offers full control from Brython, a huge number of options from low-level to high-level, but if the library is ever discontinued we will have to re-do all animations

6.3. Analysis¶

Our options for a long-lived (supported by all browsers in the long-term) animation API for CTGames developers seem to be:

rewrite the CTGames SVG animation API to use Web Animations functions on SVG images instead of using requestAnimationFrame() as it does currently
use an off-the-shelf high-level SVG animation library (free and open source or proprietary/commercial)
ignore short-term compatibility, build an CTGames animation API over native SVG animations that works exclusively on Firefox for now, and wait for Chrome to catch up with its implementation of SVG 2.0
none of the above; decide not to provide any animation API and force CTGames developers to learn the low-level Web Animations API

6.4. Our decision¶

The initial animation approach we took in CTGames was to animate objects by directly modifying their properties and attributes and calling the JavaScript function requestAnimationFrame() that works with SVGs as well as all other DOM elements (see section “Direct manipulation of attributes and requestAnimationFrame()” above). We programmed a high-level Brython API on top of the low-level JavaScript and SVG animation functions to allow CTGames developers to conveniently build animations without needing to learn about the underlying JavaScript and SVG machinery. This fully-featured library in CTGames also provided sequential and parallel timelines.

However, variable SVG support across different browsers (details given above) meant that, over time, particular animations broke with particular browsers. Although the original plan had been to periodically update the library in response to these kinds of browser vendor changes, while still keeping the library’s API constant, ultimately this plan became too challenging; features broke at a faster rate than we could cope with given the limited development time available to us.

The built-in animation functionality native to SVG images initially looked like the best alternative option for CTGames. However, as described in section “Native SVG animations (SMIL and SVG 2.0)”, the uneven support among browsers makes this a headache.

We felt we had to move to an established animation library that automatically dealt with inhomogeneities across browsers. A selection of off-the-shelf JavaScript libraries is outlined in section “JavaScript animation library” (e.g. Snap.svg, SVG.js, GASP, Velocity). We first adopted SNAP.svg but after after a couple of years (due to the lack of updates, as explained in section “JavaScript animation library”) we needed to change. Our choice was between SVG.js and GSAP. We went with the latter because the documentation was so extensive and polished (how-to videos, etc.) that it would be more appreciated by the relatively inexperienced undergraduate programmers working on CTGames. If the open source but non-free (non-libre) licence of GSAP ever becomes a problem we will switch to SVG.js.