Sprites can be translated, rotated or scaled.
This affects where and how their canvas is displayed within the scene.
Sprites with a "rotation" of 0 are untransformed.
The canvas of an untransformed sprite has a positive x-axis pointing right and a positive y-axis pointing up.
Figure 1: Untransformed sprite with an image drawn on its canvas at 0,0
A sprite with a rotation of 180 degrees will render its canvas upside down.
The two scaling properties "scalex" and "scaley" can be used to stretch, contract or mirror the canvas.
Scaling is not affected by the rotation of the sprite.
The "scalex" value of 0.5 will contract the sprite along its x-axis to half its original size.
Negative scale values will flip or mirror the canvas along its x or y axis.
Figure 2: Sprite transformations
In addition to being transformed, sprites can also be modulated.
The "alpha" property controls the transparency of sprites.
The "color" property modulates the RGB color values of everything drawn on the canvas.
Let's say that we have drawn a white (255, 255, 255) circle on some sprite's canvas.
Setting the "color" property to red (255, 0, 0) will truncate the greens and blues of the circle making it appear red.
If the circle was black (0, 0, 0) trying to modulate its colors would have no effect since black is the absence of color.
Figure 3: Sprite modulation
When our scene contains overlapping sprites, we need to define the order in which those sprites should be rendered.
To do so, we need to assign each sprite a unique "depth" value.
There is no way to determine the order in which two overlapping sprites will be rendered if they have the same depth.
Alpha modifier value. This is a number value from 0 to 1 (default is 1)
Blending mode of the sprite
Canvas of the sprite. This is a canvas object
Color modulation value. This is a color object
Z-ordering of the sprite. Sprites with greater depth are rendered first. This is a number value (default is 0)
Rotation of the sprite in degrees. The sprite turns clockwise as this value increases. This is a number value (default is 0)
Horizontal scaling of the sprite. This is a number value (default value is 1)
Vertical scaling of the sprite. This is a number value (default value is 1)
Includes or excludes the sprite from being rendered. This is a boolean value (default is true)
X-position of the sprite in parent coordinates. This is a number value (default is 0)
Y-position of the sprite in parent coordinates. This is a number value (default is 0)
- Sprite ( [x, y] )
Creates a new sprite object
- change_position ( x, y )
Translates the sprite by a given amount
- change_rotation ( degrees )
Rotates the sprite around its origin by a given amount in degrees
- change_rotation_r ( radians )
Rotates the sprite around its origin by a given amount in radians
- change_scale ( x, y )
Scales the sprite by a given amount
- change_scalex ( x )
Scales the sprite horizontally by a given amount
- change_scaley ( y )
Scales the sprite vertically by a given amount
- get_local_point ( x, y )
Transforms a position from topmost parent to local coordinates. Returns the transformed coordinates
- get_parent_point ( x, y )
Transforms a position from local to parent coordinates. Returns the transformed coordinates
- get_world_point ( x, y )
Transforms a position from local to topmost parent coordinates. Returns the transformed coordinates
- set_position ( x, y )
Translates the sprite to a given location
- set_rotation ( degrees )
Rotates the sprite to a given angle in degrees
- set_rotation_r ( radians )
Rotates the sprite to a given angle in radians
- set_scale ( x, y )
Scales the sprite to given proportions