TX3D ENGINE

# Animation组件

使用Animation组件可以为实体添加动画效果。在Tx3d Engine中动画有以下两个来源：

🌏 由建模软件创建

在加载包含动画信息的模型时引擎会为模型实体自动添加一个Animation组件。

import { Animation } from '@tx3d/core';

// 加载动画模型
engine.loadGLTF( 'assets/models/Soldier/Soldier.glb', {

    transform: {

        position: [ 0, 0, 0 ],
        rotation: [ 0, Math.PI, 0 ]

    }

} ).then( ( entity ) => {

    // 获取Animation组件
    const animation = entity.getComponent( Animation );

    // 获取包含的动画名称
    const animationNames = animation.animationNames();

    // 播放第一个动画
    animation.play( animationNames[ 0 ] );

}, ( error ) => {

    // TODO:加载失败

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

注意

Animation组件会添加到模型根实体上，模型实体结构，详见"模型数据"。

🌏 手动创建

手动创建动画时需要构建动画片段（AnimationClipParameters）、动画关键帧信息（AnimationKeyframeParameters），有关动画详细信息请参考"THREE动画系统" (opens new window)。

import { LoopPingPong } from 'three';
import { Animation, Shield } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity();

// 添加一个Shield组件
const shield = entity.addComponent( Shield, {

    radius: 5.0,
    power: 1.25,
    speed: 0.0,
    map: 'assets/textures/Grid.png'

} );

// 添加一个Animation组件，实现Shield颜色渐变动画
const animation = entity.addComponent( Animation, {

    animations: [ {

        name: 'gradient',
        tracks: [ {

            type: 'color',
            name: 'Shield.material.color',
            times: [ 0.0, 1.0, 2.0 ],
            values: [ 0.26, 0.75, 0.9, 0.15, 1.0, 0.0, 0.75, 0.0, 1.0 ]

        } ]

    } ]

} );

// 设置颜色渐变动画循环模式
animation.setLoop( 'gradient', LoopPingPong );

// 播放颜色渐变动画
animation.play( 'gradient' );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

提示

Animation组件初始化参数，详见AnimationParameters。

# 接口

🌏 animationNames 获取动画名称

// 获取动画名称
const animationNames = animation.animationNames();
1
2

🌏 addAnimation 添加一个动画

import { Animation } from '@tx3d/core';

// 加载采煤机模型
engine.loadGLTF( 'assets/models/采煤机/采煤机.gltf' ).then( ( entity ) => {

    // 获取动画组件
    const animation = entity.getComponent( Animation );

    // 播放割煤动画
    animation.play( 'Take 001' );

    // 添加一个采煤机位移动画
    animation.addAnimation( {

        name: 'transform',
        tracks: [ {

            type: 'vector',
            name: `${entity.transform.sceneNode.name}.position`,
            times: [ 0.0, 60.0 ],
            values: [ 65.0, 0.0, 0.0, -65.0, 0.0, 0.0 ]

        } ]

    } );

    // 设置采煤机位移动画循环模式
    animation.setLoop( 'transform', LoopPingPong );

    // 播放采煤机位移动画
    animation.play( 'transform' );

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

提示

动画参数，详见AnimationClipParameters。

🌏 play 播放动画

// 播放'Run'动画
animation.play( 'Run' );
1
2

🌏 pause 暂停播放动画或继续播放动画

// 暂停播放'Run'动画
animation.pause( 'Run', true );

// 继续播放'Run'动画
animation.pause( 'Run', false );
1
2
3
4
5

🌏 stop 停止播放动画

// 停止播放'Run'动画
animation.stop( 'Run' );
1
2

🌏 reset 重置动画

// 重置'Run'动画
animation.reset( 'Run' );
1
2

🌏 isScheduled 判断动画是否已激活

// 判断'Run'动画是否已激活
if ( animation.isScheduled( 'Run' ) ) {

    // TODO:

}
1
2
3
4
5
6

注意

激活动画并不意味动画正在运行，需要额外使用'isRunning'进行判断。

🌏 isRunning 判断动画是否正在运行

// 判断'Run'动画是否正在运行
if ( animation.isRunning( 'Run' ) ) {

    // TODO:

}
1
2
3
4
5
6

🌏 isPaused 判断动画是否已暂停

// 判断'Run'动画是否已暂停
if ( animation.isPaused( 'Run' ) ) {

    // TODO:

}
1
2
3
4
5
6

🌏 setEnabled 设置动画是否启用

// 启用'Run'动画
animation.setEnabled( 'Run', true );

// 禁用'Run'动画
animation.setEnabled( 'Run', false );
1
2
3
4
5

🌏 setDuration 设置动画播放总时长，单位：秒。

// 设置'Run'动画播放总时长
animation.setDuration( 'Run', 30.0 );
1
2

🌏 getDuration 获取动画播放总时长，单位：秒。

// 获取'Run'动画播放总时长
const duration = animation.getDuration( 'Run' );
1
2

🌏 setTimeScale 设置动画时间缩放。

// 设置'Run'动画时间缩放（用于控制动画播放速度）
animation.setTimeScale( 'Run', 2.0 );
1
2

🌏 getTimeScale 获取动画时间缩放。

// 获取'Run'动画时间缩放
const timeScale = animation.getTimeScale( 'Run' );
1
2

🌏 setWeight 设置动画权重，在[0 ~ 1]区间。

// 设置'Run'动画权重
animation.setWeight( 'Run', 0.5 );
1
2

🌏 getWeight 获取动画权重，在[0 ~ 1]区间。

// 获取'Run'动画权重
const weight = animation.getWeight( 'Run' );
1
2

🌏 setTime 设置当前动画时刻。

// 设置'Run'动画当前时刻
animation.setTime( 'Run', 5.0 );
1
2

🌏 getTime 获取当前动画时刻。

// 获取'Run'动画当前时刻
const time = animation.getTime( 'Run' );
1
2

🌏 setStartAt 设置动画开始时刻。

// 设置'Run'动画开始时刻
animation.setStartAt( 'Run', 5.0 );
1
2

🌏 setLoop 设置动画循环模式。

import { LoopRepeat } from 'three';

// 设置'Run'动画循环模式
animation.setLoop( 'Run', LoopRepeat );
1
2
3
4

提示

1.动画循环模式可选LoopOnce（播放一次）、LoopRepeat（循环播放，每次循环结束时候将回到起始动作开始下一次循环）、LoopPingPong（往复循环播放，像乒乓球一样在起始点与结束点之间来回循环），详见"THREE动画常量" (opens new window)；
2.设置循环播放（LoopRepeat或LoopPingPong）时，可以指定循环播放次数。

// 设置循环播放'Run'动画，且循环播放5次
animation.setLoop( 'Run', LoopRepeat, 5 );
1
2

🌏 setClampWhenFinished 设置动画播放结束后停留在最后一帧还是回到初始帧

// 设置'Run'动画播放结束后停留在最后一帧
animation.setClampWhenFinished( 'Run', true );
1
2

🌏 fadeIn 动画渐入

🌏 fadeOut 动画渐出

🌏 crossFadeFromTo 从一个动画渐变到另一个动画

🌏 stopFading 停止动画渐入或渐出

# 事件

# 监听动画结束事件

使用Animation组件的onAnimationFinished属性添加动画结束事件监听。

// 添加动画结束事件监听
const listener = animation.onAnimationFinished.add( ( event ) => {

    // TODO:

} );

// 移除指定动画结束事件监听
animation.onAnimationFinished.remove( listener );

// 清空所有动画结束事件监听
animation.onAnimationFinished.clear();
1
2
3
4
5
6
7
8
9
10
11
12

注意

动画结束监听适用于LoopOnce循环模式，动画播放结束后触发回调。

# 监听动画循环事件

使用Animation组件的onAnimationLoop属性添加动画循环事件监听。

// 添加动画循环事件监听
const listener = animation.onAnimationLoop.add( ( event ) => {

    // TODO:

} );

// 移除指定动画循环事件监听
animation.onAnimationLoop.remove( listener );

// 清空所有动画循环事件监听
animation.onAnimationLoop.clear();
1
2
3
4
5
6
7
8
9
10
11
12

注意

动画循环监听适用于LoopRepeat和LoopPingPong循环模式，每完成一次动画播放就会触发一次回调。

Last Updated: 9/25/2023, 5:31:17 PM

← Annotation组件 →