找物源码导读Cocos Creator 3.8 · assets/scripts
0%
已读 0 / 424
目录— 个文件
目录加载中…
…/module/ani/AutoSpriteFrameAnim.ts
1/**
2 * 自动播放 Sprite 帧动画组件
3 *
4 * 按序切换 Sprite.spriteFrame,支持:自动播放、循环、播放速度、开始延迟、播放完成回调
5 * 挂到带 Sprite 的节点上,在编辑器里拖入帧序列即可。
6 *
7 * 播放完成时(不循环且播放完最后一帧)会触发节点事件:'AnimationComplete'
8 */
9
10import { _decorator, Component, Sprite, SpriteFrame } from 'cc';
11
12const { ccclass, property } = _decorator;
13
14@ccclass('AutoSpriteFrameAnim')
15export class AutoSpriteFrameAnim extends Component {
16
17 @property(Sprite)
18 /** 目标 Sprite(不填则用本节点上的 Sprite) */
19 targetSprite: Sprite | null = null;
20
21 @property([SpriteFrame])
22 /** 帧序列(按顺序播放) */
23 frames: SpriteFrame[] = [];
24
25 @property
26 /** 是否自动播放 */
27 autoPlay: boolean = true;
28
29 @property
30 /** 是否循环 */
31 loop: boolean = true;
32
33 @property({ tooltip: '每帧显示时长(秒)' })
34 /** 每帧显示时长(秒) */
35 frameInterval: number = 0.1;
36
37 @property({ tooltip: '播放速度倍率,1=正常' })
38 /** 播放速度倍率,1=正常 */
39 speed: number = 1;
40
41 @property({ tooltip: '开始播放前的延迟(秒)' })
42 /** 开始播放前的延迟(秒) */
43 startDelay: number = 0;
44
45 /** 当前帧索引 */
46 private _curFrameIndex: number = 0;
47 /** 当前帧已显示时长 */
48 private _elapsed: number = 0;
49 /** 是否正在播放 */
50 private _playing: boolean = false;
51 /** 是否已过 startDelay */
52 private _delayPassed: boolean = false;
53 /** 延迟剩余时间 */
54 private _delayRemain: number = 0;
55
56 onEnable() {
57 this._curFrameIndex = 0;
58 this._elapsed = 0;
59 this._playing = false;
60 this._delayPassed = this.startDelay <= 0;
61 this._delayRemain = this.startDelay;
62
63 if (this.autoPlay && this.frames.length > 0) {
64 this._playing = true;
65 this.ApplyFrame(0);
66 }
67 }
68
69 onDisable() {
70 this._playing = false;
71 }
72
73 update(dt: number) {
74 if (!this._playing || this.frames.length === 0) return;
75
76 if (!this._delayPassed) {
77 this._delayRemain -= dt;
78 if (this._delayRemain <= 0) {
79 this._delayPassed = true;
80 this._elapsed = 0;
81 }
82 return;
83 }
84
85 this._elapsed += dt * this.speed;
86 const interval = this.frameInterval;
87 if (this._elapsed < interval) return;
88
89 this._elapsed -= interval;
90 let next = this._curFrameIndex + 1;
91
92 if (next >= this.frames.length) {
93 if (this.loop) {
94 next = 0;
95 } else {
96 this._playing = false;
97 return;
98 }
99 }
100
101 this._curFrameIndex = next;
102 this.ApplyFrame(next);
103 }
104
105 /**
106 * 应用帧
107 * @param index 帧索引
108 */
109 private ApplyFrame(index: number) {
110 const sprite = this.targetSprite ?? this.node.getComponent(Sprite);
111 const frame = this.frames[index];
112 if (sprite && frame) {
113 sprite.spriteFrame = frame;
114 }
115 }
116
117 /**
118 * 开始播放(从头)
119 */
120 Play() {
121 this._curFrameIndex = 0;
122 this._elapsed = 0;
123 this._delayPassed = this.startDelay <= 0;
124 this._delayRemain = this.startDelay;
125 this._playing = true;
126 if (this.frames.length > 0) {
127 this.ApplyFrame(0);
128 }
129 }
130
131 /**
132 * 停止播放
133 */
134 Stop() {
135 this._playing = false;
136 }
137
138 /**
139 * 暂停/恢复:通过 speed=0 实现暂停
140 * @param v 是否暂停
141 */
142 set Paused(v: boolean) {
143 this.speed = v ? 0 : 1;
144 }
145
146
147 /**
148 * 是否暂停
149 * @returns 是否暂停
150 */
151 get Paused(): boolean {
152 return this.speed === 0;
153 }
154
155 /**
156 * 是否正在播放
157 * @returns 是否正在播放
158 */
159 get IsPlaying(): boolean {
160 return this._playing;
161 }
162}
讲解163 行
序列帧播人工通读

AutoSpriteFrameAnim.ts

启用或 Play 会重置帧索引与等待,update 根据速度倍率累积时间并顺序替换 SpriteFrame。播放状态全部保存在实例,每帧最多推进一张图,结束会停在最后一帧;头部宣称的完成事件并未实现,暂停设置也会把原速度改回一倍。

先看 update 的延迟与终止分支,再看 ApplyFrame 和 Paused 的赋值。

特殊处理与易错点

  • 易错点非循环结束仅设置 _playing=false,没有派发 AnimationComplete。
  • 时序每帧只减一次 frameInterval,卡顿不会在同帧补齐多帧。
  • 特殊处理延迟按真实 dt 扣减,不受 speed=0 暂停影响。
10注释自动播放 Sprite 帧动画组件 按序切换 Sprite.spriteFrame,支持:自动播放、循环、播放速度、开始延迟、播放完成回调 挂到带 Sprite 的节点上,在编辑器里拖入帧序列即可。 播放完成时(不循环且播放完最后一帧)会触发节点事件:'AnimationComplete'
15注释AutoSpriteFrameAnim:自动播放 Sprite 帧动画组件 按序切换 Sprite.spriteFrame,支持:自
19属性目标 Sprite(不填则用本节点上的 Sprite)
23属性帧序列(按顺序播放)
27属性是否自动播放
31属性是否循环
35属性每帧显示时长(秒)
39属性播放速度倍率,1=正常
43属性开始播放前的延迟(秒)
46属性当前帧索引
48属性减去一次间隔后保留剩余累计时间,每个 update 最多前进一帧。
50属性是否正在播放
52属性是否已过 startDelay
54属性Play 和启用时复制 startDelay,按 dt 扣减。
56方法重置索引和等待状态并按自动播放开关显示首帧。
69方法节点禁用时清除播放标记而保留当前显示帧。
73方法扣减首播延迟并按速度累积时间推进至下一帧。
109方法查找目标精灵并把指定索引的有效帧赋给它。
120方法从首帧重置计时和首播延迟并设置正在播放。
134方法清除正在播放标记而不改变当前索引和画面。
142方法通过覆盖速度倍率切换暂停,恢复固定为正常一倍速度。
151注释是否暂停
159方法读取播放标记以区分停止结束与仍在等待推进。