Glimmr Canvas Animation

version 1/111030 by Erik Temple

  • Home page
  • Beginning
  • Previous
  • Next



  • Section: Reel animation tracks

    "Reel" tracks show a succession of images in a way similar to that of traditional animation on film, or the animated GIFs familiar from the web. The sequence of images to be shown is specified using a list of figure names assigned to the track's "image-reel" property. Reel tracks can function only with entities that display a single image at a time, and thus we are limited to targeting:

        sprites (g-element)
        g-canvas (affecting the background image of the canvas)

    (But see the "parameterized reel" preset below, which lets us define a reel for any display property of any kind of g-element, canvas, or g-window.)

    The reel must be defined in advance of triggering the animation track; this is done by setting the "image-reel" property of the animation track object to a list of figure names. (We can repeat figure names in the list to show the figure a second time; this can be used to provide pacing.)

    To invoke a reel preset we use the following phrase:

        animate <track> as a reel animation targeting <target> at <interval> with a duration of <length> frames, <cycling><randomized>

    If we wish, we may omit the duration, resulting in this variant phrasing:

        animate <track> as a reel animation targeting <target> at <interval>, <cycling><randomized>

    If we do this, the duration will be set automatically to the number of entries in the image-reel. Moreover, if we also set the "cycling" option when no duration has been set, the track will continue to repeat ad infinitum, or until stopped by another event (such as a callback from another track; see the section on callbacks below).

    The images in the image-reel list will be shown in order, unless we set the "randomized" option for a reel track, in which case an image will be chosen at random from the reel for each frame. (We can of course include multiple mentions of the same figure to influence percentages; if Figure 1 is listed twice in the reel while Figure 2 is listed just once, then the chance that Figure 1 will be displayed is twice as great as the chance that Figure 2 will be.)

    Here are some examples of usage (code snippets, not complete games):

    Targeting a sprite, showing each frame in the reel just once:
        The leaping track is an animation track.

        The image-reel of the leaping track is {Figure of Leap 01, Figure of Leap 02, Figure of Leap 03, Figure of Leap 04}.

        The Frog is a sprite. The image-ID is Figure of Frog Sitting.

        Instead of jumping:
            animate the leaping track as a reel animation targeting the Frog at 200 milliseconds per frame with a duration of 4 frames.

    Targeting a canvas and using the shorter form. Note that because the "cycling" option is set and there is no duration specified, this track will repeat endlessly:
        The swirling track is an animation track.

        The image-reel of the swirling track is {Figure of Swirl 01, Figure of Swirl 02, Figure of Swirl 03, Figure of Swirl 04, Figure of Swirl 05}.

        The background image of the graphics-canvas is Figure of Still Water.

        When play begins:
            animate the swirling track as a reel animation targeting the graphics-canvas at 12 frames per second, cycling.

    Reel tracks normally are not affected by setting the easing equations. However, if AFTER using the animate phrase we reset the length of the animation cycle so that it is not equal to the number of entries in the image-reel, easing will be used to reconcile the two. Effectively, the easing equation will describe how time will be "stretched" to fit the reel. The animation rule will use the easing of the track to extend or contract the length of the animation using the frames in the original reel. For example, if our original image reel was specified as a list with four entries, and we then fit the sequence to 12 frames using the linear easing rule, each of the four images in the original would be displayed for approximately 3 frames. If we are using a rapid in, slow out easing equation, however, then the first entry in the reel list might be displayed for only one frame, while the last might be held for four frames. Note that, due to rounding errors, this will not always work perfectly, particularly when the original reel sequence specified is short. We achieve this effect by using the "fit... sequence to ... frames" phrase:

        fit <track> sequence into/to <length> frame/frames

    Extending the example above:

        The swirling track is an animation track. The easing of the swirling track is the quadratic easing out rule.

        The image-reel of the swirling track is {Figure of Swirl 01, Figure of Swirl 02, Figure of Swirl 03, Figure of Swirl 04, Figure of Swirl 05}.

        The background image of the graphics-canvas is Figure of Still Water.

        When play begins:
            animate the swirling track as a reel animation targeting the graphics-canvas at 8 frames per second, cycling;
            fit the swirling track sequence to 12 frames.
            
    The "fit... sequence to ... frames" phrase works *only* with reel and parameterized reel tracks. It will have unanticipated effects if used with other types of animation track preset.