Dev - Lua Libraries

Lua Command: s3sprite.load


Return Values


int imageID = s3sprite.load(string imagePath, int pivotX = 0, int pivotY = 0, int rectX = 0, int rectY = 0, int rectW = imageWidth, int rectH = imageHeight)


Loads the image specified with imagePath and returns its imageID for use with other commands (like s3sprite.create or s3sprite.getImageSize) of the sprite library.

imagePath is the only required parameter. It must be relative to the folder of the current mod and point to a JPG/JPEG or PNG file. PNGs with alpha channel are fully supported. Animated PNGs are not supported.

pivotX and pivotY specify the pivot of the image in pixels. This is the point which is used to position and rotate the image. By default it is set to the top left corner of the image (0|0). Example: To set the pivot of an image with 60x50 pixels to its center you would have to set it to (30|25) (pivotX to 30 and pivotY to 25). The pivot coordinates can be negative as well.

rectX, rectY, rectW and rectH can be used to specify the part of the source image you want to use. By default the entire image is used. The parameters are used to provide an offset (rectX, rectY) and a size (rectW, rectH) in pixels. They all must be positive values and the rectangle must be within the source texture size.


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


All loaded source textures are cached by the Stranded III resource manager. It never loads the same texture twice. So you can safely use this command with the same imagePath and different pivots or rectangles without wasting video memory.


This command should be executed directly when the Lua scripts are parsed so the textures can be preloaded in the load sequence of the game. Do not call it frequently/in loops.