目录— 个文件
⌕
目录加载中…
…/module/ani/AutoPlaySpine.ts
1/**
2 * AutoPlaySpine:自动播放 Spine 动画组件
3 *
4 * 功能:
5 * - 进入节点时按配置自动播放指定动画
6 * - 支持是否循环播放
7 * - 非循环播放时:播放结束后,等待一段时间再重新播放
8 *
9 * 使用方式:
10 * - 将本组件挂在带有 Spine 组件的节点上
11 * - 在 `skeleton` 上拖入 `sp.Skeleton`,填写 `animationName`
12 */
13
14import { _decorator, Component, sp, UIOpacity } from 'cc';
15
16const { ccclass, property } = _decorator;
17
18@ccclass('AutoPlaySpine')
19export class AutoPlaySpine extends Component {
20
21 @property(sp.Skeleton)
22 /** 目标 Spine 组件(不填则使用本节点上的 Skeleton) */
23 skeleton: sp.Skeleton | null = null;
24
25 @property({ tooltip: '要播放的动画名(必须在 Spine 中存在)' })
26 animationName: string = '';
27
28 @property({ tooltip: '是否循环播放(true=内部无限循环,不再考虑间隔)' })
29 loop: boolean = false;
30
31 @property({ tooltip: '是否在 onEnable 时自动开始播放' })
32 autoPlay: boolean = true;
33
34 @property({ tooltip: '非循环模式下,单次播放结束后再播放前的等待时间(秒,>0 为循环间隔,≤0(如 -1)表示只播放一次不再循环)' })
35 interval: number = 1;
36
37 @property({ tooltip: '非循环模式下,单次播放完成后是否将整体透明度设为 0' })
38 hideOnComplete: boolean = true;
39
40 /** 当前是否处于“单次播放 + 等待下一次”的模式 */
41 private _awaitNextPlay: boolean = false;
42 /** 距离下一次播放的剩余等待时间 */
43 private _waitRemain: number = 0;
44
45 /** 本节点上的 UIOpacity(用于控制整体透明度) */
46 private _uiOpacity: UIOpacity | null = null;
47
48 onEnable() {
49 this._awaitNextPlay = false;
50 this._waitRemain = 0;
51
52 if (this.autoPlay) {
53 this.Play();
54 return;
55 }
56 this.Stop();
57 }
58
59 onDisable() {
60 this.Stop();
61 }
62
63 update(dt: number) {
64 if (!this._awaitNextPlay) return;
65 if (this.loop) return; // 循环模式下不会进入这里
66
67 this._waitRemain -= dt;
68 if (this._waitRemain <= 0) {
69 this._awaitNextPlay = false;
70 this.playOnceInternal();
71 }
72 }
73
74 /**
75 * 开始播放(根据 loop 配置单次或循环)
76 */
77 public Play(): void {
78 if (!this.node.active) {
79 this.node.active = true;
80 if (this.autoPlay) return;
81 }
82 const sk = this.getSkeleton();
83 if (!sk || !this.animationName) {
84 return;
85 }
86
87 // 开始播放时先恢复为可见
88 const uiOpacity = this.getUIOpacity();
89 if (uiOpacity) {
90 uiOpacity.opacity = 255;
91 }
92
93 sk.setCompleteListener(undefined as any);
94 sk.paused = false;
95
96 if (this.loop) {
97 sk.setAnimation(0, this.animationName, true);
98 this._awaitNextPlay = false;
99 return;
100 }
101
102 this.playOnceInternal();
103 }
104
105 /**
106 * 播放指定动画
107 * @param animationName 动画名
108 */
109 public PlayOnName(animationName: string) {
110 this.animationName = animationName;
111 this.Play();
112 }
113
114 /**
115 * 停止播放
116 */
117 public Stop(): void {
118 const sk = this.getSkeleton();
119 if (sk) {
120 sk.clearTrack(0);
121 sk.setCompleteListener(undefined as any);
122 sk.paused = true;
123 }
124 this._awaitNextPlay = false;
125 this._waitRemain = 0;
126 }
127
128 /**
129 * 获取或自动获取 Skeleton
130 */
131 private getSkeleton(): sp.Skeleton | null {
132 if (this.skeleton && this.skeleton.isValid) {
133 return this.skeleton;
134 }
135 const sk = this.node.getComponent(sp.Skeleton);
136 if (!sk) {
137 return null;
138 }
139 this.skeleton = sk;
140 return sk;
141 }
142
143 /**
144 * 播放一次动画,并监听完成事件以便进入等待阶段
145 */
146 private playOnceInternal(): void {
147 const sk = this.getSkeleton();
148 if (!sk || !this.animationName) {
149 return;
150 }
151
152 // 每次单次播放开始时确保可见
153 const uiOpacity = this.getUIOpacity();
154 if (uiOpacity) {
155 uiOpacity.opacity = 255;
156 }
157
158 this._awaitNextPlay = false;
159 this._waitRemain = 0;
160 sk.paused = false;
161 sk.setCompleteListener(() => {
162 // 一次动画播放完成,开始等待下一次
163 if (!this.loop && this.interval > 0 && this.node.isValid) {
164 this._awaitNextPlay = true;
165 this._waitRemain = this.interval;
166 }
167
168 // 根据配置决定是否在播放完成后将整体透明度置为 0
169 if (this.hideOnComplete && this.node && this.node.isValid) {
170 const uiOpacityInner = this.getUIOpacity();
171 if (uiOpacityInner) {
172 uiOpacityInner.opacity = 0;
173 }
174 }
175 // 单次动画完成后停止 Skeleton 每帧更新;下次播放时会恢复。
176 sk.paused = true;
177 });
178
179 sk.setAnimation(0, this.animationName, false);
180 }
181
182 /**
183 * 获取或自动挂载 UIOpacity,用于控制透明度
184 */
185 private getUIOpacity(): UIOpacity | null {
186 if (this._uiOpacity && this._uiOpacity.isValid) {
187 return this._uiOpacity;
188 }
189 if (!this.node || !this.node.isValid) {
190 return null;
191 }
192 const uiOpacity = this.node.getComponent(UIOpacity) || this.node.addComponent(UIOpacity);
193 this._uiOpacity = uiOpacity;
194 return uiOpacity;
195 }
196}
讲解197 行
骨骼播放人工通读
AutoPlaySpine.ts
由启用回调或外部 Play 驱动 Spine 零号轨道,循环模式交给骨骼自身,单次模式通过完成监听设置等待状态再由 update 倒计时重播。等待与透明度组件缓存在实例,完成后会暂停骨骼并可隐藏;Stop 清轨道但不会恢复透明度。
先看 Play 的激活分支,再连读 playOnceInternal 完成回调与 update 重播。
特殊处理与易错点
- 时序Play 激活非活动节点且 autoPlay 为真时,依赖 onEnable 发起播放后直接返回。L77
- 特殊处理单次播放完成会暂停骨骼;interval 大于零才安排下一次。
- 易错点完成监听被组件整体覆盖,Stop 清监听与轨道但不恢复可见性。L117
14注释AutoPlaySpine:自动播放 Spine 动画组件 功能: - 进入节点时按配置自动播放指定动画 - 支持是否循环播放 - 非循环播放时:播放结束后,等待一段时间再重新播放 使用方式: - 将本组件挂在带有 Spine 组件的节点上 - 在 `skeleton` 上拖入 `sp.Skeleton`,填写 `animationName`
19注释AutoPlaySpine:AutoPlaySpine:自动播放 Spine 动画组件 功能: - 进入节点时按配置自动
23属性目标 Spine 组件(不填则使用本节点上的 Skeleton)
26属性目标 Spine 组件(不填则使用本节点上的 Skeleton)
29属性loop(boolean):该模块的运行态字段。
32属性自动播放(boolean):该模块的运行态字段。
35属性interval(number):该模块的运行态字段。
38属性隐藏 On Complete(boolean):该模块的运行态字段。
41属性单次播放完成且间隔为正时开启,下一次重播前关闭。
43属性完成回调写入 interval,update 逐帧扣减。
46属性本节点上的 UIOpacity(用于控制整体透明度)
48方法清空重播等待状态并按自动播放开关播放或停止。
59方法节点禁用时清除骨骼轨道以及尚未完成的重播等待。
63方法逐帧扣减单次动画间隔并在到期后重新播放。
77方法激活目标节点并按循环开关播放指定骨骼动画。
88注释开始播放时先恢复为可见
109方法替换实例动画名称后按当前循环与间隔规则播放。
117方法清理零号轨道和完成监听并终止下一次播放等待。
131方法优先复用有效绑定骨骼,否则查找本节点骨骼并缓存。
146方法播放单次动画并在完成时隐藏暂停及安排间隔。
153注释每次单次播放开始时确保可见
163注释一次动画播放完成,开始等待下一次
169注释根据配置决定是否在播放完成后将整体透明度置为 0
176注释单次动画完成后停止 Skeleton 每帧更新;下次播放时会恢复。
185方法复用有效透明度组件或在本节点补建并缓存。