Hype Timeline Watcher

Extension Project
1

Hype Timeline Watcher
Hype Timeline Watcher1920×1357 202 KB

Getting Started with Hype Timeline Watcher Extension

This guide will help you get started with the Hype Timeline Watcher Extension, from basic usage to more advanced configurations.

Simple Usage: Handling Timeline Completion

  1. Define onTimelineComplete Function:
    Create the onTimelineComplete function in your Hype document's functions. This function will handle completion events for any timeline without the need to watch it.

    // Create a new function in Hype named 'onTimelineComplete'
function onTimelineComplete(hypeDocument, element, event) {
  console.log('Timeline:', event.timelineName, 'is complete');
}

Watching a Timeline with Progress Events

To handle progress events, you need to watch a timeline.

  1. Define onTimelineProgress Function:
    Create the onTimelineProgress function in your Hype document's functions to handle progress events.

    // Create a new function in Hype named 'onTimelineProgress'
function onTimelineProgress(hypeDocument, element, event) {
  console.log('Timeline:', event.timelineName, 'Current Time:', event.currentTime);
}

  2. Watch a Timeline:
    Add the following code to your scene's load action or a suitable initialization script to start watching a timeline.

    hypeDocument.watchTimelineByName('MyTimeline');

Differentiating Timelines by Name

If you have multiple timelines and want to handle them differently, use the timelineName from the event object to differentiate them.

  1. Update onTimelineProgress Function:
    Modify the onTimelineProgress function to use a switch statement based on the timeline name.

    // Create a new function in Hype named 'onTimelineProgress'
function onTimelineProgress(hypeDocument, element, event) {
  switch (event.timelineName) {
    case 'Timeline1':
      console.log('Timeline1 progress:', event.currentTime);
      break;
    case 'Timeline2':
      console.log('Timeline2 progress:', event.currentTime);
      break;
    default:
      console.log('Other timeline progress:', event.currentTime);
      break;
  }
}

  2. Update onTimelineComplete Function:
    Similarly, modify the onTimelineComplete function.

    // Create a new function in Hype named 'onTimelineComplete'
function onTimelineComplete(hypeDocument, element, event) {
  switch (event.timelineName) {
    case 'Timeline1':
      console.log('Timeline1 is complete');
      break;
    case 'Timeline2':
      console.log('Timeline2 is complete');
      break;
    default:
      console.log('Other timeline is complete');
      break;
  }
}

  3. Watch Multiple Timelines:
    Watch multiple timelines by adding them in your initialization script.

    hypeDocument.watchTimelineByName('Timeline1');
hypeDocument.watchTimelineByName('Timeline2');

Using Custom Callbacks

For more advanced usage, you can specify custom callbacks directly when watching timelines.

  1. Watch a Timeline with Custom Callbacks:
    Use the following code to watch a timeline and specify custom callbacks for progress, start, pause, resume, and completion events.

    hypeDocument.watchTimelineByName('MyTimeline', {
  onTimelineProgress: function(hypeDocument, element, event) {
    console.log('Custom Progress:', event.timelineName, 'Current Time:', event.currentTime);
  },
  onTimelineComplete: function(hypeDocument, element, event) {
    console.log('Custom Complete:', event.timelineName, 'is complete');
  },
  onTimelineStart: function(hypeDocument, element, event) {
    console.log('Custom Start:', event.timelineName, 'has started');
  },
  onTimelinePause: function(hypeDocument, element, event) {
    console.log('Custom Pause:', event.timelineName, 'has paused');
  },
  onTimelineResume: function(hypeDocument, element, event) {
    console.log('Custom Resume:', event.timelineName, 'has resumed');
  }
});

Watching Timelines in Symbols

To watch timelines within symbols, you need to pass the symbolInstance in the settings object.

  1. Watch a Timeline in a Symbol:
    Use the following code to watch a timeline within a symbol and specify custom callbacks.

    var symbolInstance = hypeDocument.getSymbolInstanceById('symbolId');
symbolInstance.watchTimelineByName('MySymbolTimeline', {
  onTimelineProgress: function(hypeDocument, element, event) {
    console.log('Custom Progress for Symbol:', event.timelineName, 'Current Time:', event.currentTime);
  },
  onTimelineComplete: function(hypeDocument, element, event) {
    console.log('Custom Complete for Symbol:', event.timelineName, 'is complete');
  },
  onTimelineStart: function(hypeDocument, element, event) {
    console.log('Custom Start for Symbol:', event.timelineName, 'has started');
  },
  onTimelinePause: function(hypeDocument, element, event) {
    console.log('Custom Pause for Symbol:', event.timelineName, 'has paused');
  },
  onTimelineResume: function(hypeDocument, element, event) {
    console.log('Custom Resume for Symbol:', event.timelineName, 'has resumed');
  }
});

Unwatching Timelines

To stop watching a timeline, use the unwatchTimelineByName function.

  1. Unwatch a Timeline:
    Add the following code to stop watching a specific timeline.

    hypeDocument.unwatchTimelineByName('MyTimeline');

  2. Unwatch a Timeline in a Symbol:
    If you are watching a timeline within a symbol, use the following code to stop watching it.

    var symbolInstance = hypeDocument.getSymbolInstanceById('symbolId');
symbolInstance.unwatchTimelineByName('MySymbolTimeline');

By following these steps, you can set up the Hype Timeline Watcher Extension for simple usage, differentiate timeline handling, utilize custom callbacks for more advanced functionality, including within symbols, and unwatch timelines when they are no longer needed.

Content Delivery Network (CDN)

Latest version can be linked into your project using the following in the head section of your project:

<script src="https://cdn.jsdelivr.net/gh/worldoptimizer/HypeTimelineWatcher/HypeTimelineWatcher.min.js"></script>

Optionally you can also link a SRI version or specific releases.
Read more about that on the JsDelivr (CDN) page for this extension at JsDelivr - HypeTimelineWatcher.

Learn how to use the latest extension version and how to combine extensions into one file at
HypeCookBook - Including external files and Hype extensions.

Based on this thread and a simpler version found here:

6 Likes
2

Discussion and Preview of the next version

Update: I removed the code preview here as the latest code is now on GitHub,
thanks @h_classen for testing.

The feedback below is still relevant and tbd.

v1.1.2
This version adds callbacks to detect play, resume, start, and complete. It refactors the callbacks to be onTimelineComplete, onTimelineProgress, onTimelineResume, onTimelinePause... They are all called only if a timeline is watched. The built-in HypeTimelineComplete is now its separate event and can be used without a timeline watcher declaration. This is my workaround after attempting to address the issue that the element in HypeTimelineComplete is not populated with any discerning features!

Small Hype Event features request and discussion

@jonathan I'd really like to see element set in context and correctly!**
see stateUsingJavascriptTesting.hype.zip (92,3 KB)

I was trying to use:

function HypeTimelineComplete(hypeDocument, element, event) {
    var symbolInstance = element ? hypeDocument.getSymbolInstanceById(element.id) : null;
    handleTimelineEvent(hypeDocument, symbolInstance, event.timelineName, null, 'HypeTimelineComplete');
}

However, I cannot retrieve the symbolInstance since element consistently represents the scene, and I have not identified any distinguishing feature to access the symbol element or identify its origin from a symbol.

Therefor the mentioned split in this preview between the onTimline… events and HypeTimelineComplete.

Another nice to have thing would be a way to get the names of timelines by code

3

is not so consistent when setting up a cycling timeline eather by adding a timelineaction goToTimeInTimelineNamed or continueTimelineNamed with option reverse ... fires from time to time.

if it's meant like reached end i'd say it should fire always

1 Like
4

I will check if that can be arranged. Thank you for the feedback.

Update: After investigating, I found that it was a rounding error due to time and duration being fractional. I have made the necessary adjustments to the code and the test file. If there are no more issues, I will upload it to Github tomorrow. Done!

Update 2: I also added the missing unwatchTimelineByName

1 Like