Dev - Lua Libraries

Lua Command: s3sprite.create

Parameters

Return Values

Signature

S3Sprite spriteInstance = s3sprite.create(int imageID, int x = 0, int y = 0, order order = 0, color color = "white")

Description

Creates a new sprite instance on the screen with the image imageID and returns the spriteInstance for use with other commands. spriteInstance will be NIL if the creation failed (this may happen because imageID does not point to an existing image).

The position is specified in pixels and starts with (0|0) in the top left corner of the screen. This is also the default position. A custom position can be specified with the parameters x and y. It is possible to change the position after creation with commands like s3sprite.setPosition.

The order defines the rendering order (and optionally also the sorting layer). Images with a lower order/sorting layer are rendered first.

Optionally a color and transparency can be defined with color. The default color is white (r,g,b = 255), the default transparency is opaque (alpha 1).

Example:

Loading and displaying an image
1
2
cursor = s3sprite.load("interface/cursor.png")
s3sprite.create(cursor, 5, 5)

Note:

spriteInstance will be nil if the sprite creation failed. This commonly only happens when the specified image does not exist.

Note:

Using huge numbers of sprites can have a negative impact on the framerate of the game. Make sure to free unused sprites properly with s3sprite.free or s3sprite.freeAll.

Note:

See data types: order to learn how orders are specified!

Note:

See data types: color to learn how colors are specified!