javascript
/
three.js
Mirror von https://github.com/tazdij/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400
							<!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 />
			[page:Number blendMode] - defines how the animation is blended/combined
			when two or more animations are simultaneously played.<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:Number blendMode]</h3>
		<p>
			Defines how the animation is blended/combined when two or more animations
			are simultaneously played. Valid values are *NormalAnimationBlendMode*
			(default) and *AdditiveAnimationBlendMode*.
		</p>

		<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 chosen
			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 chosen
			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 relatively 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this 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:this stopFading]()</h3>
		<p>
			Stops any scheduled [page:.fadeIn fading] which is applied to this action.
			This method can be chained.
		</p>

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

		<h3>[method:this 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:this 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>