javascript
/
three.js
mirror of https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363
							<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<base href="../../../" />
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>[name]</h1>

		<p class="desc">
			AnimationActions schedule the performance of the animations which are stored in
			[page:AnimationClip AnimationClips].<br /><br />

			Note: Most of AnimationAction's methods can be chained.<br /><br />

			For an overview of the different elements of the three.js animation system see the
			"Animation System" article in the "Next Steps" section of the manual.
		</p>


		<h2>Constructor</h2>


		<h3>[name]( [param:AnimationMixer mixer], [param:AnimationClip clip], [param:Object3D localRoot] )</h3>
		<p>
			[page:AnimationMixer mixer] - the *AnimationMixer* that is controlled by this action.<br />
			[page:AnimationClip clip] - the *AnimationClip* that holds the animation data for this action.<br />
			[page:Object3D localRoot] - the root object on which this action is performed.<br /><br />

			Note: Instead of calling this constructor directly you should instantiate an AnimationAction with
			[page:AnimationMixer.clipAction] since this method provides caching for better performance.
		</p>


		<h2>Properties</h2>


		<h3>[property:Boolean clampWhenFinished]</h3>
		<p>
			If *clampWhenFinished* is set to true the animation will automatically be [page:.paused paused]
			on its last frame.<br /><br />

			If *clampWhenFinished* is set to false, [page:.enabled enabled] will automatically be switched
			to false when the last loop of the action has finished, so that this action has no further
			impact.<br /><br />

			Default is false.<br /><br />

			Note: *clampWhenFinished* has no impact if the action is interrupted (it has only an effect if
			its last loop has really finished).
		</p>

		<h3>[property:Boolean enabled]</h3>
		<p>
			Setting *enabled* to *false* disables this action, so that it has no impact. Default is *true*.<br /><br />

			When the action is re-enabled, the animation continues from its current [page:.time time]
			(setting *enabled* to *false* doesn't reset the action).<br /><br />

			Note: Setting *enabled* to *true* doesn’t automatically restart the animation. Setting *enabled*
			to *true* will only restart the animation immediately if the following condition is fulfilled:
			[page:.paused paused] is *false*, this action has not been deactivated in the meantime (by
			executing a [page:.stop stop] or [page:.reset reset] command), and neither [page:.weight weight]
			nor [page:.timeScale timeScale] is 0.
		</p>

		<h3>[property:Number loop]</h3>
		<p>
			The looping mode (can be changed with [page:.setLoop setLoop]). Default is
			[page:Animation THREE.LoopRepeat] (with an infinite number of [page:.repetitions repetitions])<br /><br />

			Must be one of these constants:<br /><br />
			[page:Animation THREE.LoopOnce] - playing the clip once,<br />
			[page:Animation THREE.LoopRepeat] - playing the clip with the choosen number of *repetitions*,
			each time jumping from the end of the clip directly to its beginning,<br />
			[page:Animation THREE.LoopPingPong] - playing the clip with the choosen number of *repetitions*,
			alternately playing forward and backward.
		</p>

		<h3>[property:Boolean paused]</h3>
		<p>
			Setting *paused* to *true* pauses the execution of the action by setting the effective time scale
			to 0. Default is *false*.<br /><br />
		</p>

		<h3>[property:Number repetitions]</h3>
		<p>
			The number of repetitions of the performed [page:AnimationClip] over the course of this action.
			Can be set via [page:.setLoop setLoop]. Default is *Infinity*.<br /><br />
			Setting this number has no effect, if the [page:.loop loop mode] is set to
			[page:Animation THREE.LoopOnce].
		</p>

		<h3>[property:Number time]</h3>
		<p>
			The local time of this action (in seconds, starting with 0).<br /><br />

			The value gets clamped or wrapped to 0...clip.duration (according to the loop state). It can be
			scaled relativly to the global mixer time by changing [page:.timeScale timeScale] (using
			[page:.setEffectiveTimeScale setEffectiveTimeScale] or [page:.setDuration setDuration]).<br />
		</p>

		<h3>[property:Number timeScale]</h3>
		<p>
			Scaling factor for the [page:.time time]. A value of 0 causes the animation to pause. Negative
			values cause the animation to play backwards. Default is 1.<br /><br />
			Properties/methods concerning *timeScale* (respectively *time*) are:
			[page:.getEffectiveTimeScale getEffectiveTimeScale],
			[page:.halt halt],
			[page:.paused paused],
			[page:.setDuration setDuration],
			[page:.setEffectiveTimeScale setEffectiveTimeScale],
			[page:.stopWarping stopWarping],
			[page:.syncWith syncWith],
			[page:.warp warp].
		</p>

		<h3>[property:Number weight]</h3>
		<p>
			The degree of influence of this action (in the interval [0, 1]). Values between 0 (no impact)
			and 1 (full impact) can be used to blend between several actions. Default is 1. <br /><br />
			Properties/methods concerning  *weight* are:
			[page:.crossFadeFrom crossFadeFrom],
			[page:.crossFadeTo crossFadeTo],
			[page:.enabled enabled],
			[page:.fadeIn fadeIn],
			[page:.fadeOut fadeOut],
			[page:.getEffectiveWeight getEffectiveWeight],
			[page:.setEffectiveWeight setEffectiveWeight],
			[page:.stopFading stopFading].
		</p>

		<h3>[property:Boolean zeroSlopeAtEnd]</h3>
		<p>
			Enables smooth interpolation without separate clips for start, loop and end. Default is *true*.
		</p>

		<h3>[property:Boolean zeroSlopeAtStart]</h3>
		<p>
			Enables smooth interpolation without separate clips for start, loop and end. Default is *true*.
		</p>


		<h2>Methods</h2>


		<h3>[method:AnimationAction crossFadeFrom]( [param:AnimationAction fadeOutAction], [param:Number durationInSeconds], [param:Boolean warpBoolean] )</h3>
		<p>
			Causes this action to [page:.fadeIn fade in], fading out another action simultaneously, within
			the passed time interval. This method can be chained.<br /><br />

			If warpBoolean is true, additional [page:.warp warping] (gradually changes of the time scales)
			will be applied.<br /><br />

			Note: Like with *fadeIn*/*fadeOut*, the fading starts/ends with a weight of 1.

		</p>

		<h3>[method:AnimationAction crossFadeTo]( [param:AnimationAction fadeInAction], [param:Number durationInSeconds], [param:Boolean warpBoolean] )</h3>
		<p>
			Causes this action to [page:.fadeOut fade out], fading in another action simultaneously, within
			the passed time interval. This method can be chained.<br /><br />
			If warpBoolean is true, additional [page:.warp warping] (gradually changes of the time scales)
			will be applied.<br /><br />

			Note: Like with *fadeIn*/*fadeOut*, the fading starts/ends with a weight of 1.
		</p>

		<h3>[method:AnimationAction fadeIn]( [param:Number durationInSeconds] )</h3>
		<p>
			Increases the [page:.weight weight] of this action gradually from 0 to 1, within the passed time
			interval. This method can be chained.
		</p>

		<h3>[method:AnimationAction fadeOut]( [param:Number durationInSeconds] )</h3>
		<p>
			Decreases the [page:.weight weight] of this action gradually from 1 to 0, within the passed time
			interval. This method can be chained.
		</p>

		<h3>[method:Number getEffectiveTimeScale]()</h3>
		<p>
			Returns the effective time scale (considering the current states of warping and
			[page:.paused paused]).
		</p>

		<h3>[method:number getEffectiveWeight]()</h3>
		<p>
			Returns the effective weight (considering the current states of fading and
			[page:.enabled enabled]).
		</p>

		<h3>[method:AnimationClip getClip]()</h3>
		<p>
			Returns the clip which holds the animation data for this action.
		</p>

		<h3>[method:AnimationMixer getMixer]()</h3>
		<p>
			Returns the mixer which is responsible for playing this action.
		</p>

		<h3>[method:Object3D getRoot]()</h3>
		<p>
			Returns the root object on which this action is performed.
		</p>

		<h3>[method:AnimationAction halt]( [param:Number durationInSeconds] )</h3>
		<p>
			Decelerates this animation's speed to 0 by decreasing [page:.timeScale timeScale] gradually
			(starting from its current value), within the passed time interval. This method can be chained.
		</p>

		<h3>[method:Boolean isRunning]()</h3>
		<p>
			Returns true if the action’s [page:.time time] is currently running.<br /><br />

			In addition to being activated in the mixer (see [page:.isScheduled isScheduled]) the following conditions must be fulfilled:
			[page:.paused paused] is equal to false, [page:.enabled enabled] is equal to true,
			[page:.timeScale timeScale] is different from 0, and there is no scheduling for a delayed start
			([page:.startAt startAt]).<br /><br />

			Note: *isRunning* being true doesn’t necessarily mean that the animation can actually be seen.
			This is only the case, if [page:.weight weight] is additionally set to a non-zero value.
		</p>

		<h3>[method:Boolean isScheduled]()</h3>
		<p>
			Returns true, if this action is activated in the mixer.<br /><br />
			Note: This doesn’t necessarily mean that the animation is actually running (compare the additional
			conditions for [page:.isRunning isRunning]).
		</p>

		<h3>[method:AnimationAction play]()</h3>
		<p>
			Tells the mixer to activate the action. This method can be chained.<br /><br />

			Note: Activating this action doesn’t necessarily mean that the animation starts immediately:
			If the action had already finished before (by reaching the end of its last loop), or if a time
			for a delayed start has been set (via [page:.startAt startAt]), a [page:.reset reset] must be
			executed first. Some other settings ([page:.paused paused]=true, [page:.enabled enabled]=false,
			[page:.weight weight]=0, [page:.timeScale timeScale]=0) can prevent the animation from playing,
			too.
		</p>

		<h3>[method:AnimationAction reset]()</h3>
		<p>
			Resets the action. This method can be chained.<br /><br />

			This method sets [page:.paused paused] to false, [page:.enabled enabled] to true,
			[page:.time time] to 0, interrupts any scheduled fading and warping, and removes the internal
			loop count and scheduling for delayed starting.<br /><br />

			Note: .*reset* is always called by [page:.stop stop], but .*reset* doesn’t call .*stop* itself.
			This means: If you want both, resetting and stopping, don’t call .*reset*; call .*stop* instead.
		</p>

		<h3>[method:AnimationAction setDuration]( [param:Number durationInSeconds] )</h3>
		<p>
			Sets the duration for a single loop of this action (by adjusting [page:.timeScale timeScale]
			and stopping any scheduled warping). This method can be chained.
		</p>

		<h3>[method:AnimationAction setEffectiveTimeScale]( [param:Number timeScale] )</h3>
		<p>
			Sets the [page:.timeScale timeScale] and stops any scheduled warping. This method can be chained.<br /><br />

			If [page:.paused paused] is false, the effective time scale (an internal property) will also be set
			to this value; otherwise the effective time scale (directly affecting the animation at
			this moment) will be set to 0.<br /><br />

			Note: .*paused* will not be switched to *true* automatically, if .*timeScale* is set to 0 by
			this method.
		</p>

		<h3>[method:AnimationAction setEffectiveWeight]( [param:Number weight] )</h3>
		<p>
			Sets the [page:.weight weight] and stops any scheduled fading. This method can be chained.<br /><br />

			If [page:.enabled enabled] is true, the effective weight (an internal property) will also be set
			to this value; otherwise the effective weight (directly affecting the animation at this moment)
			will be set to 0.<br /><br />

			Note: .*enabled* will not be switched to *false* automatically, if .*weight* is set to 0 by
			this method.
		</p>

		<h3>[method:AnimationAction setLoop]( [param:Number loopMode], [param:Number repetitions] )</h3>
		<p>
			Sets the [page:.loop loop mode] and the number of [page:.repetitions repetitions]. This method
			can be chained.
		</p>

		<h3>[method:AnimationAction startAt]( [param:Number startTimeInSeconds] )</h3>
		<p>
			Defines the time for a delayed start (usually passed as [page:AnimationMixer.time] +
			deltaTimeInSeconds). This method can be chained.<br /><br />

			Note: The animation will only start at the given time, if .*startAt* is chained with
			[page:.play play], or if the action has already been activated in the mixer (by a previous
			call of .*play*, without stopping or resetting it in the meantime).
		</p>

		<h3>[method:AnimationAction stop]()</h3>
		<p>
			Tells the mixer to deactivate this action. This method can be chained.<br /><br />

			The action will be immediately stopped and completely [page:.reset reset].<br /><br />

			Note: You can stop all active actions on the same mixer in one go via
			[page:AnimationMixer.stopAllAction mixer.stopAllAction].
		</p>

		<h3>[method:AnimationAction stopFading]()</h3>
		<p>
			Stops any scheduled [page:.fadeIn fading] which is applied to this action. This method can be
			chained.
		</p>

		<h3>[method:AnimationAction stopWarping]()</h3>
		<p>
			Stops any scheduled [page:.warp warping] which is applied to this action. This method can be
			chained.
		</p>

		<h3>[method:AnimationAction syncWith]( [param:AnimationAction otherAction] )</h3>
		<p>
			Synchronizes this action with the passed other action. This method can be chained.<br /><br />

			Synchronizing is done by setting this action’s [page:.time time] and [page:.timeScale timeScale] values
			to the corresponding values of the other action (stopping any scheduled warping).<br /><br />

			Note: Future changes of the other action's *time* and *timeScale* will not be detected.
		</p>

		<h3>[method:AnimationAction warp]( [param:Number startTimeScale], [param:Number endTimeScale], [param:Number durationInSeconds] )</h3>
		<p>
			Changes the playback speed, within the passed time interval, by modifying
			[page:.timeScale timeScale] gradually from *startTimeScale* to *endTimeScale*. This method can
			be chained.
		</p>


		<h2>Events</h2>


		<p class="desc">
			There are two events indicating when a single loop of the action respectively the entire action has finished. You can react to them with:
		</p>
		<code>
		mixer.addEventListener( 'loop', function( e ) { …} ); // properties of e: type, action and loopDelta
		mixer.addEventListener( 'finished', function( e ) { …} ); // properties of e: type, action and direction
		</code>

		<h2>Source</h2>

		<p>
			[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
		</p>
	</body>
</html>