Hype Scene Magic

Hey everyone,

I'm excited to announce that I've updated the HypeSceneMagic project! Originally developed in 2019, HypeSceneMagic has been revitalized to leverage the powerful GSAP animation library, providing even smoother and more enhanced animation experiences within Tumult Hype.


Inspiration:

The core concept and aesthetics draw inspiration from Apple Keynote's Magic Move transition. If you've ever been captivated by the seamless transitions and animations in Apple presentations, that's exactly the level of polish we're aiming to bring to your Hype projects.

What's New?

  • GSAP Integration: The project now utilizes GSAP instead of the Web Animations API, offering more robust and feature-rich animation capabilities.
  • Enhanced Transition Properties: Added several properties and functions to fine-tune animations and transitions, including support for runtime transition mapping.
  • Case-Insensitive Identifiers: Transition identifiers are now case-insensitive and can be matched without the magic prefix, simplifying the process of matching elements across scenes.
  • Improved Performance: By leveraging GSAP's efficient animation engine, transitions are smoother and more performant.
  • Simplified Transition Modes: Removed the indirect transition mode to streamline the user experience, focusing on intuitive and straightforward transitions.
  • Updated Documentation: Enhanced code comments and documentation for better clarity, tailored specifically for Tumult Hype users.
    Usage & Integration:
    The integration remains straightforward:
  1. Include Required Libraries:
    Add the following scripts to your Head HTML in Tumult Hype:

    <script src="https://cdn.jsdelivr.net/npm/gsap@latest/dist/gsap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/gh/worldoptimizer/HypeSceneMagic/HypeSceneMagic.min.js"></script>
    

    Note: For production environments, it's recommended to download these scripts and include them locally in your project to ensure reliability and performance.

  2. Apply Magic Transitions:

    • Using Class Names: Assign class names starting with magic to elements you want to animate across scenes. For example, magicBox, magicCircle, or any unique identifier like magicMyElement.
    • Using Data Attributes: Alternatively, use the data-transition-id attribute to assign a unique identifier to elements. In this case it would be box, circle or MyElement.
      Identifiers are case-insensitive and matched without the magic prefix.
  3. Trigger Scene Transitions:

    showSceneNamedMagic (Hype signature)

    Use the provided functions to navigate between scenes with magic transitions using the familiar Hype function signature found on the regular showSceneNamed:

    // Navigate to a specific scene with magic transition
    hypeDocument.showSceneNamedMagic('SceneName', duration, easing, options);
    
    • duration: (Optional) Transition duration in seconds. Default is 0.5.
    • easing: (Optional) Easing function name. Default is power1.inOut.
    • options: (Optional) An object containing additional settings like crossFadeFactor, onTransitionStart , and onTransitionEnd.

    magicCard (shorthand)

    // Navigate using a magic card transition
    hypeDocument.magicCard(name, settingsOrDuration);
    

    This function provides a quick way to navigate from a single interface. It is especially good in conjunction with Hype Reactive Content or Hype Action Events, both of which enable running inline JavaScript from Trigger Custom Behavior.

    • name: (String) The navigation target. The supported values are:

      • '>': Navigates to the next scene in the timeline.
      • '<': Navigates to the previous scene.
      • '>SceneBaseName': Searches forward from the current scene and navigates to the first scene name that starts with SceneBaseName.
      • '<SceneBaseName': Searches backward from the current scene and navigates to the first scene name that starts with SceneBaseName.
      • 'ExactSceneName': Navigates directly to the scene with the specified name.
    • options: (Optional) This can be either a number specifying the transition duration in seconds (default is 0.5), or an Object containing any of the following properties:

      • duration: (Number) The transition duration in seconds. Default is 0.5.
      • ease: (String) The name of the easing function to use (e.g., power1.inOut).
      • crossFadeFactor: (Number) A value from 0 to 1 that controls the cross-fade timing.
      • onTransitionPrepare: (Function) A callback function that runs before any transition setup.
      • onTransitionStart: (Function) A callback function that runs when the transition animation begins.
      • onTransitionProgress: (Function) A callback function that runs repeatedly during the transition, providing the progress (a value from 0 to 1).
      • onTransitionEnd: (Function) A callback function that runs after the transition has fully completed.

      Usage Examples

      Here's how you can use magicCard for scene navigation:

      // Navigate to the next scene with a 1-second duration
      hypeDocument.magicCard('>', 1);
      
      // Navigate to the previous scene with default options
      hypeDocument.magicCard('<');
      
      // Find the next scene that starts with "Chapter"
      hypeDocument.magicCard('>Chapter');
      
      // Navigate to a specific scene with a custom ease and an end callback
      hypeDocument.magicCard('FinalResults', { 
        duration: 0.7, 
        ease: 'bounce.out', 
        onTransitionEnd: function() { 
          console.log('Arrived at the final results!'); 
        } 
      });
      

Example Project:

For a comprehensive example that also includes Hype Data Magic and Hype Reactive Content, check out the project below:

HypeSceneMagic-with-Data-Magic.hype.zip (1,6 MB)

This example demonstrates how you can combine multiple extensions to create dynamic and interactive content. For simpler examples scroll down!

Getting Started:

For simpler examples and a step-by-step guide on how to get started, please refer to the GitHub repository and read through the thread below.


With these updates, HypeSceneMagic is now more powerful and easier to use than ever. I can't wait to see the amazing transitions and animations you'll create with it!

Happy animating!


Note: The old version using the Web Animations API has been deprecated in favor of the new GSAP-powered version. Here is the static cover for safe keeping if I don't want to use the video anymore:

12 Likes

↑ look at project


Important Update: As of Hype Scene Magic version 2.5.5, some features described below have been changed or deprecated. Notably, the Direct and Indirect Transition Modes are no longer available. The information remains here for historical context, but please refer to the latest documentation for current features and usage.


What's New in Hype Scene Magic 2.4.0

Release Highlights:

  • Implemented data-transition-id, data-transition-delay, and data-transition-duration attributes.
  • Implemented data-transition-order with 'front' and 'back' keywords for z-index control.
  • Added 'target' keyword for delay, duration, and order to use values from the target element.
  • Enabled mixing and matching of magic class notation and data-transition-id.
  • [Deprecated in v2.5.5] Added direct and indirect transition modes (default was indirect).

Note: The Direct and Indirect Transition Modes introduced in this version have been removed in version 2.5.5 to simplify the transition process and improve usability.


Fine-Grained Control Over Transition Timing

Hype Scene Magic now offers enhanced control over transition timing for individual elements. By using data-transition-delay and data-transition-duration attributes, you can customize how each element behaves within the overall transition duration.

New Data-Transition Attributes

To provide greater flexibility and control, several new data-transition attributes have been introduced:

Attribute Description Example Values
data-transition-id Assigns a unique identifier to elements for matching between scenes. Identifiers are case-insensitive and exclude magic. example1, box
data-transition-delay Specifies the delay before the transition starts. Accepts unitless factors, percentages (50%), or time units (0.5s). 0, 0.5, 50%, 0.5s
data-transition-duration Defines the duration of the transition. Accepts unitless factors, percentages, or time units. 1, 0.75, 75%, 0.75s
data-transition-order Controls the z-index order during the transition. Accepts 'front', 'back', or a specific number. front, back, 10

Special Keyword: target

  • target: You can use the keyword target with data-transition-delay, data-transition-duration, and data-transition-order attributes to inherit values from the corresponding element in the target scene. This allows for dynamic adjustments based on the properties of the element you're transitioning to.

Transition Modes (Deprecated in v2.5.5)

The following information about Transition Modes is retained for historical context but is no longer applicable as of version 2.5.5.

Indirect Mode (Default in v2.4.0)

In indirect mode, delays and durations are calculated relative to the total transition duration, ensuring that both the delay and the transition time fit within the overall time.

Direct Mode

In direct mode, the delay is applied first, and then the transition duration follows. This allows for more precise control over the timing of each part of the transition but is more complex.

To enable direct mode in version 2.4.0:

HypeSceneMagic.setDefault('transitionMode', 'direct');

Note: Both direct and indirect modes have been removed in version 2.5.5 to streamline the transition process.


Z-index Management with data-transition-order

This version introduces z-index management at the element stacking order level, enabling you to control the layering of elements during transitions:

  • Keywords 'front' and 'back': Easily bring elements to the front or send them to the back during transitions.
  • Numeric Values: Specify exact z-index positions for precise control over element stacking.

Additional Thoughts on Element-Based Transition Groups

Click here to read my thoughts on element-based transition groups I really enjoy the interactive user interfaces in Penpot and Figma, which allow for board-based interactions similar to what Hype Scene Magic offers for scenes. In Hype, similar actions can be performed at an element level using relative timelines. However, due to the confusing behavior of values changing across timelines in Hype (if you're not extremely careful), this approach hasn't worked well for me.
I would be interested in incorporating a similar approach to what Penpot offers on an element level in Hype. Perhaps refining the behavior of relative/sub timelines and value editing could make this a feasible solution (which Tumult would need to implement), or introducing a new UI driven by "states" could be an exciting alternative (again, requiring Tumult's involvement). As a workaround, using redundant groups is possible but not elegant—I might give it a spin.

Please Note: The features and modes described in this announcement were accurate as of version 2.4.0. Since then, Hype Scene Magic has evolved, and some features have been changed or deprecated in later versions, including the removal of transition modes in version 2.5.5. For the most up-to-date information and features, please refer to the latest documentation.

6 Likes

*Edit, nvm me. I already see what I was looking for

Already have a nice usecase in mind for something I have to do manually with GSAP now, but would be neat to get it done in Hype fully.

2 Likes

↑ look at project

2.5.0

  • Adapted to use GSAP instead of Web Animations API

2.5.1

  • Fixed id bug supporting multiple layouts (use the same name for layouts)
4 Likes

Setup:

Result:
CleanShot2024-11-16at14.55.43-ezgif.com-optimize (2)

Example:
HypeSceneMagic-Example2.hype.zip (949,7 KB)

3 Likes

2 posts were split to a new topic: Feedback for Hype Scene Magic

↑ look at project

2.5.2

  • Added support for data-transition-fallback attributes when magic pair is not matched
  • Unified and cleaned up parsing, and added more documentation.

2.5.3

  • Added data-transition-fallback-from and data-transition-fallback-to for fine-grained directional transitions

Note: data-transition-fallback has been refactored to data-transition-animation in v2.5.8

CleanShot 2024-11-16 at 23.12.56

Hype Easing Names Mapped to GSAP Equivalents

Hype easing names are automatically mapped to their corresponding GSAP easing functions for seamless integration.

HypeSceneMagic Easing GSAP Equivalent
easein power1.in
easeout power1.out
easeinout power1.inOut

Example: Using Mapped Easing

When using HypeSceneMagic with mapped easings, the easing name is internally converted to the appropriate GSAP easing function. For instance:

// This converts "easeout" to GSAP's "power1.out"
hypeDocument.showSceneNamedMagic("Scene2", 1.5, "easeout");

Directly Using GSAP Easings

You can also specify any GSAP easing function directly for more advanced transitions. Keep in mind that HypeSceneMagic might switch to Anime.js in the future, so direct GSAP easings are not officially supported, but should continue to work just fine as long as you bundle and use the GSAP version of this Hype Scene Magic.

Example: Using GSAP Bounce with Custom Strength

Here's how to apply a GSAP easing like bounce.out with custom parameters:

// Pro tip: Customize easing behavior, such as increasing bounce strength
hypeDocument.showSceneNamedMagic("Scene2", 1.5, "bounce.out(2)");

By following this documentation, you can take advantage of both mapped and custom easing functions to create smooth and dynamic scene transitions.

Read more about GSAP easing functions.

2 Likes

I want to give a shout-out to @petester. Due to feedback regarding persistent symbols, I reconsidered how to handle magic transitions, leading to some improvements in the code.

Starting with version 2.5.4+, SceneMagic now uses Hype's native crossfade transition while managing all the magic movements separately. This enables Hype to properly handle its persistent symbols and perform all runtime tasks. Initially, I was concerned about the timing differences this would introduce, as earlier versions used half the duration for the original scene to fade out.

However, I managed to solve this elegantly! By overwriting the opacity from the fade with a CSS variable (using !important), we maintain the original 50% crossfade timing that I prefer. Even better, I made the timing completely configurable—you can now decide how much of the transition is dedicated to fading between scenes versus elements repositioning themselves. This also opened up the possibility for custom durations and delays for individual elements.

The end result is a more robust system that works seamlessly with Hype's core functionality while maintaining the precise control over transitions that SceneMagic is known for.

4 Likes

↑ look at project

2.5.4

  • Removed the indirect transition mode as it was too complex and unintuitive

2.5.5

  • Refactored to use a native Hype crossfade transition, but overridden with the magicTransition class
  • Added z-index management for proper scene layering during transitions
  • Added support for runtime transition mapping and made identifiers case-insensitive

2.5.6

  • Refactored beforeStart/afterEnd to onTransitionStart/onTransitionEnd
  • Added animation registration system for reusable animations

2.5.7

  • Added onTransitionProgress callback to track overall transition progress
  • Added custom behaviors: magicTransitionStart/End, magicTransition_{fromScene}to{toScene}, magicTransitionFrom_{fromScene}, magicTransitionTo_{toScene} (scene names without spaces)

2.5.8

  • Added support for data-transition-animation on non-magic elements
  • Added data-transition-animation-from/to for directional animations
  • Renamed fallback to animation in attribute names for consistency
  • Added hypeDocument.applyAnimation() to apply registered and custom GSAP animations to elements
  • Added durationAnimation and refactored duration to durationTransition

2.5.9

  • Fixed issue where transitions without magic elements would complete too early
  • Added minimum duration enforcement using GSAP timeline
  • Fixed an issue when matching layouts by dimensions interfered with matching by name

2.6.0

  • Added support for multiple magic identifiers per element
  • Removed match tracking in favor of "last match wins" approach (using killTweensOf)
  • Added onTransitionPrepare callback and moved onTransitionStart to timeline start
3 Likes

CleanShot2024-12-06at00.55.27-ezgif.com-optimize

"Hey everyone, I will add some new examples soon!"

4 Likes


magicEaseDemo.hype.zip (130,4 KB)

This is an exotic test demonstrating the use of custom easings. The built-in ones with GSAP are straightforward to use… simply name them according to the GSAP easing naming convention. This demo file also illustrates how to utilize the custom easing plugin to create your own easing functions using the built-in editor on the GSAP web page. Again, I am using a wrapper function called magic card, but you can also directly use show scene magic. These are mainly test files for my project, so I extracted a helper function because it's convenient, and I also use reactive content in that project. It works without either, though.

↑ look at project

2.6.1

  • Fixed issue where non-magic elements with data-transition-animation weren't being properly restored

2.6.2

  • Added skipProperties to default configuration to skip properties from being tweened like fontFamily
  • Fixed issue when delays and durations exceeded into next magic transition by ending previous master timeline

2.6.3

  • Fixed issue where getCurrentMagicProperties was not being used for source elements

2.6.4

  • Refactored property caching and getting for clarity and robustness

This is a new demo of magic transitions. I'm using shorthand, reactive content, and more extensions than needed, but I just wanted to quickly demo the latest version.

sceneMagicPhoneLandscapeAd.hype.zip (1,2 MB)

1 Like

Here is another example inspired by a section I saw on the Apple page for the Ultra Watch.

sceneMagicAppleWatchSection.hype.zip (744,7 KB)

2 Likes

So, I stumbled upon this bug and regression in the rotational component, but after a lot of trial and error, I managed to fix it. The matrix calculation was a bit tricky because it was tied to the transform property and inline styles, which made it hard to use with external libraries like GSAP. The fix was to pull the rotational components into the style itself and out of transform, thanks to the magic of modern CSS version 2.0. This lets us do a two-tier calculation, so GSAP can handle multi-turn rotations in both directions, going beyond the 180-degree limit of the matrix skewing capabilities. This only affects rotations of 180 degrees and more. So it wasn't a big priority, but I will put the new transform decomposition behind the flag and turn it on in the next version.

Update:
Bug is resolve, one thing remains … it is that Hypes Text-Elements don't have proper sizes by default, so they might be troublesome in rotations. To fix, just give them a proper fixed size (drag or by number pad).

1 Like

↑ look at project

2.7.0

  • Added decomposeTransform flag. Implemented robust rotation synchronization.
  • Added magicCard shorthand for powerful scene navigation with support for next/previous and relative scene names.

2.7.1

  • Added Hype IDE specific code to show visual indicators for magic elements.

2.7.2

  • Removed angle normalization and shortest path logic for rotation.

2.7.3

  • Added logic to recover lost rotation values from the pristine cache.

Last two example have been updated and are back online.

Very cool to see the examples!

Hmm... just a thought but maybe you can look at the bounding box and then explicitly give them a width/height yourself?

1 Like

Hello Jonathan, I did that (using offsetWidth and offsetHeight), but weirdly, the bounding box is always a little bit off and not on a consistent basis, so I couldn't adjust. The same text element copied to a second scene would yield slightly different values when measured in HypeScenePrepareForDisplay. So, I removed that feature again. It was called autoDimensions, but I rolled it back. There were a lot of inconsistencies. As this problem only appears when you rotate a text element without explicit size, I thought I would just leave that alone for now. If you set a size it vanishes and also, If you put text into a normal rectangle, height and width are always there, as far as my testing goes. Happy to continue the discussion in DMs, but for now I am happy with the 2.7.3 release.

1 Like

CleanShot 2025-09-17 at 13.09.54

This demo (was still sitting in my project folder) shows how Persistent Symbols work with Hype Scene Magic. I'm really proud of this because Hype Scene Magic hijacks a genuine cross-fade process. I use the timing to run multiple tasks at once, and all the usual transition functions still work.

I've got a Persistent symbol in the foreground that I trigger with custom behavior during transitions. You could also trigger the animations with a click, but I think it's better for persistent symbols to just listen and react based on which scene they're on. The listen approach is more passive and triggers automatically when you arrive at each scene if it was a magic transition.

This file shows also how to register animations with names and reuse those aliases, so you don't need to add props to every data attribute. It uses data transition attributes without magic ID linking, mainly to demonstrate the persistent symbol.

sceneMagicPersistentSymbolSupport.hype.zip (34,6 KB)

1 Like