Hints Module

Matt Karl edited this page Sep 25, 2015 · 17 revisions

The Hints module can be used for the playback of instructional voice-over, animation, or custom functions upon pressing of the Container's helpButton, and/or on a timer.

Features

  • Play hints on timeout
  • Play hints on helpButton click
  • Hint tiering (sequential) and/or randomization
  • Controls the enabled state of the Container's helpButton.
  • Will use the LearningMedia module's playInstruction() method (if present) to fire Start/End Instruction events for AnimatorHints or VOHints.

Dependencies

Usage

If the Hints module is included in a project, a HintsPlayer object will be added as a property called hints to the Application. This instance is used to control all Hints module functionality. (Unless otherwise specified, all functions and properties referenced here will be properties of Application.instance.hints)

####Setting Before using HintsPlayer, a hint must be set - only one hint at a time may be set, but a GroupHint may be used in cases where a collection of hints should be randomized or played in sequentially each time the HintsPlayer is told to play(). When a hint is set, HintsPlayer is automatically enabled. See Hint Types below for more info on setting hints.

####Playing Once a hint is set, it will play either by manually calling play(), when the Container's helpButton is pressed, or at an interval set by calling startTimer(<duration>). startTimer's duration argument is optional, and defaults to 12000ms, or whatever the most recently set duration was (can be also changed by setting timerDuration). Once a timer has been started, it may be stopped by calling stopTimer() or removeTimer(). The timer may be reset to 0 (and continue running) by calling resetTimer().

Container helpButton

When a hint starts playing, the Container's helpButton will automatically be disabled. For Animator and VO Hints, this button will be re-enabled when the hint finishes playing, unless the hint is cancelled early such as by VOPlayer.play() being called or Animator.play() being called for the same MovieClip instance. The Container's helpButton can be manually enabled and disabled by setting the HintsPlayer's boolean property, enabled. It is recommended to manually disable this button during the playback of instruction or feedback, or any other time when interrupting gameplay with a hint may cause undesirable behavior.

Hint Types

Hints may be set by calling anim() to set an AnimatorHint, vo() to set a VOHint, group() to set a GroupHint, or func() to set a FunctionHint.

VOHint

Set by calling vo() with same arguments as VOPlayer.play(), use the VOPlayer to play the specified audio. Automatically disables and re-enables the HintsPlayer.

AnimatorHint

Set by calling anim() with same arguments as Animator.play(), use the Animator to play the specified MovieClip event (label) synced with audio. Automatically disables and re-enables the HintsPlayer.

FunctionHint

Set by calling func(<function>), call a function when it's time for a hint to play. As of SpringRoll 0.4, The function called will receive 2 arguments, completeCallback and cancelledCallback, which it should call when the custom hint is completed or cancelled to re-enable the HintsPlayer. Alternatively, you can call the HintPlayer's funcDone() function when complete. (In Springroll < 0.4, upon completion of a FunctionHint, you should set enabled = true and startTimer(), if applicable.)

// For SpringRoll 0.4+
app.hints.func(function(done)
{
	// call this when completed after an async action
	done(); // or: app.hints.funcDone();

});

// For SpringRoll < 0.3
app.hints.func(function()
{
	// call this when completed after an async action
	app.hints.enabled = true; // or app.hints._done();

});
GroupHint

A collection of any number of any other type of hint. Set by calling group() and chaining additional hint setting functions afterward.

To create a group of hints to randomize between, chain up any number of hint setting calls, like this:

app.hints.group()
	.vo("hint1")
	.vo("hint2")
	.vo("hint3");

To set a group of tiered hints that cycles in order each time a hint is played, separate tiers of hints in sequential order with addTier(), like this:

app.hints.group()
	.vo("lookForTheThing")
	.addTier()
	.vo("theThingIsRedAndRound")
	.addTier()
	.anim(thingMC, {
		anim:"clickMe", 
		audio:"clickHere"
	});

You can also have hints randomize within tiers:

app.hints.group()
	.vo("hint1")
	.vo("hint2")
	.addTier()
	.anim(thingMC, {
		anim:"clickMe",
		audio:"clickHere"
	});

Other than the randomization and/or sequencing, the individual hints in a GroupHint behave exactly the same as when set individually.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.