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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
Animation
=========
Animation objects are used to gather data about specific animations. Although you can't spawn Animation objects directly, you can access them via other objects such as [Actor](/engine/actor) and [Player](/engine/player).
*Example*
```cs
using SurgeEngine.Actor;
object "MyExplosion" is "entity", "disposable", "private"
{
actor = Actor("MyExplosion");
state "main"
{
if(actor.animation.finished)
destroy();
}
}
```
Properties
----------
#### id
`id`: number.
The number of the animation, defined in a .spr file.
#### sprite
`sprite`: string, read-only.
The name of the sprite, defined in a .spr file.
#### exists
`exists`: boolean, read-only.
Will be `true` if the animation exists, i.e., if its sprite and its animation number have been defined in a .spr file.
*Available since:* Open Surge 0.5.1
#### finished
`finished`: boolean, read-only.
Will be `true` if the animation has finished playing.
#### anchor
`anchor`: [Vector2](/engine/vector2) object, read-only.
The hot spot of the animation normalized to [0,1] x [0,1].
*Available since:* Open Surge 0.6.0
#### hotSpot
`hotSpot`: [Vector2](/engine/vector2) object, read-only.
The hot spot of the animation. Coordinates are given in pixels.
*Note:* prior to Open Surge 0.6.0, this property was called `hotspot`.
#### actionSpot
`actionSpot`: [Vector2](/engine/vector2) object, read-only.
The action spot of the animation. Coordinates are given in pixels. If the sprite is flipped, the action spot is automatically flipped relative to the [hot spot](#hotspot) of the animation.
*Available since:* Open Surge 0.6.0
#### actionOffset
`actionOffset`: [Vector2](/engine/vector2) object, read-only.
When this vector is added to the position of the sprite, you'll get the position of the [action spot](#actionspot). This is suitable to be used with [transform.localPosition](/engine/transform#localposition).
*Available since:* Open Surge 0.6.0
#### repeats
`repeats`: boolean, read-only.
Does the animation repeat itself?
#### fps
`fps`: number, read-only.
Frames per second of the animation.
#### frameCount
`frameCount`: number, read-only.
The number of frames of the animation.
#### duration
`duration`: number, read-only.
The duration of the animation, in seconds.
*Available since:* Open Surge 0.6.1
#### frame
`frame`: number.
The current frame of the animation: an integer between `0` and `frameCount - 1`, inclusive.
#### speedFactor
`speedFactor`: number.
While the [FPS](#fps) rate controls the speed of the animation, the speed factor gives you an additional degree of control. This is a multiplier that defaults to 1.0, meaning that the animation will run using its normal speed. If it's set to 2.0, it will run using twice that speed. A value of 0.5 means half the speed, and so on.
#### sync
`sync`: boolean.
Is the animation is synchronized? A synchronized animation is a repeating animation that displays the same frame across multiple sprites. Defaults to `false`.
Functions
---------
#### prop
`prop(propertyName)`
Read the user-defined custom property named `propertyName` defined in a *custom_properties* block of the [sprite](#sprite) of this animation (.spr file). If the property exists, this function will return a string, a number, a boolean, or an [Array](/reference/array) of these, depending on the property. If the property does not exist, this function will return `null`.
*Available since:* Open Surge 0.6.1
*Arguments*
* `propertyName`: string. The name of a custom property.
*Returns*
Returns a string, a number, a boolean, an array of these primitive types with at least two elements, or `null`.
*Example*
```cs
/*
Example of a custom_properties block:
// .spr file
sprite "My Test Sprite"
{
// ...
custom_properties
{
number_of_layers 8
want_awesomeness true
font_name "GoodNeighbors"
position 100 200
}
}
*/
// It's a good idea to cast the value of the property to the expected type, so
// that your script will work reliably regardless of what is in the .spr file!
animation = actor.animation;
numberOfLayers = Number(animation.prop("number_of_layers")); // 8
wantAwesomeness = Boolean(animation.prop("want_awesomeness")); // true
fontName = String(animation.prop("font_name") || "Default Font Name"); // "GoodNeighbors"
foobar = String(animation.prop("foobar") || "undefined"); // "undefined"
position = animation.prop("position");
if(typeof position == "object") {
xpos = Number(position[0]); // 100
ypos = Number(position[1]); // 200
}
else {
xpos = 0;
ypos = 0;
}
```
#### findTransform
`findTransform()`
When a keyframe-based animation is playing, compute an approximation of the transformation applied to the sprite at the current time. You may use this function to make objects follow the transformed sprite or to know its location. If no keyframe-based animation is currently playing, the identity transform will be returned.
*Available since:* Open Surge 0.6.1
*Returns*
Returns a [Transform](/engine/transform) object.
*Example*
```cs
animationTransform = animation.findTransform();
Console.print(animationTransform.localPosition);
```
|
