Skip to main content

SpriteTask

A task for rendering a single Sprite from newSprite

warning

This page is a WIP. It contains all the information in Figura's documentation but we're working on adding more helpful descriptions.

For this entire page assume:

local mySprite = models:newSprite("myCoolSpriteName")

Sprite Task​

setTexture()​

Aliases: texture()

Sets this task's texture

The texture's width and height must be provided if the texture is a location

For custom textures, the dimensions are optional

setTexture(textureLocation, width, height)

Parameters:

NameTypeDescriptionDefault
textureLocationString--
widthInteger--
heightInteger--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

-- using a resource location
mySprite:setTexture("textures/item/turtle_egg.png", 16, 16)

-- using a custom texture
mySprite:setTexture(textures["myTexture"])

-- using a custom texture with dimensions
mySprite:setTexture(textures["myTexture"], 16, 16)

getTexture()​

Returns this task's current texture

getTexture()

Returns:

TypeDescription
String-

Example:

mySprite:getTexture()

setColor()​

Aliases: color()

Sets a color multiplier for this sprite

Values are RGBA from 0 to 1

Default values are 1, alpha is optional

setColor(rgb)

Parameters:

NameTypeDescriptionDefault
rgbVector3--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

mySprite:setColor(world.getBiome():getWaterColor())

getColor()​

Gets the current color multiplier of this sprite

Values are RGBA from 0 to 1

getColor()

Returns:

TypeDescription
Vector4-

Example:

mySprite:getColor()

setDimensions()​

Aliases: dimensions()

Sets the texture dimensions, used in UV calculation

setDimensions(dimensions)

Parameters:

NameTypeDescriptionDefault
dimensionsVector2--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

-- use the long water_flow texture then make it one block
mySprite:setTexture("textures/block/water_flow.png", 16, 16)
mySprite:setDimensions(32, 1024)

getDimensions()​

Returns the texture dimensions, used in UV calculation

getDimensions()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getDimensions()

setRegion()​

Aliases: region()

Sets the texture UV region

Uses its dimensions to calculate the max UV

setRegion(region)

Parameters:

NameTypeDescriptionDefault
regionVector2--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

mySprite:setRegion(64, 64)

getRegion()​

Gets the texture UV region

getRegion()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getRegion()

setRenderType()​

Aliases: renderType()

Sets the current render type of this sprite

TRANSLUCENT by default

Check the docs enum command for all render types

setRenderType(renderType)

Parameters:

NameTypeDescriptionDefault
renderTypeString--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

mySprite:setRenderType("CUTOUT")

getRenderType()​

Gets the name of the current render type for this sprite

getRenderType()

Returns:

TypeDescription
String-

Example:

mySprite:getRenderType()

setSize()​

Aliases: size()

Sets the width and height used to render this sprite

setSize(size)

Parameters:

NameTypeDescriptionDefault
sizeVector2--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

-- make my small egg bigger
mySprite:setTexture("textures/item/turtle_egg.png", 8, 8)
mySprite:setSize(16, 16)

getSize()​

Returns the width and height used to render this sprite

getSize()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getSize()

setUV()​

Aliases: uv()

Sets this texture UV offset

The Region and Dimension are used to calculate the end UV

setUV(uv)

Parameters:

NameTypeDescriptionDefault
uvVector2--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

-- Let's make a sprite task of flowing water!
mySprite:setTexture("textures/block/water_flow.png", 16, 16)
mySprite:setDimensions(32, 1024)
mySprite:setColor(world.getBiome():getWaterColor())

local t = 0

function events.tick()
    mySprite:setUV(1, t / 32)
    t = t + 1
end

getUV()​

Gets this texture UV offset

getUV()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getUV()

setUVPixels()​

Aliases: uvPixels()

Set this texture UV offset, in pixels, based on the texture's dimension

setUVPixels(uv)

Parameters:

NameTypeDescriptionDefault
uvVector2--

Returns:

TypeDescription
SpriteTaskReturns self for chaining

Example:

-- Let's make a sprite task of flowing water!
mySprite:setTexture("textures/block/water_flow.png", 16, 16)
mySprite:setDimensions(32, 1024)
mySprite:setColor(world.getBiome():getWaterColor())

local t = 0

function events.tick()
    mySprite:setUVPixels(1, t)
    t = t - 1
end

getUVPixels()​

Get this texture UV offset, in pixels, based on the texture's dimension

getUVPixels()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getUVPixels()

getVertices()​

Returns a table with all 4 vertices of this sprite

Changing the values through other functions will reset those vertices

getVertices()

Returns:

TypeDescription
Table-

Example:

mySprite:getVertices()

Render Task​

setLight()​

Aliases: light()

Sets the light override value of this task

Values are given from 0 to 15, indicating the block light and sky light levels you want to use

Passing nil will reset the lighting override for this task

setLight(light)

Parameters:

NameTypeDescriptionDefault
lightVector2--

Returns:

TypeDescription
RenderTask-

Example:

local blockLight = world.getLightLevel(player:getPos())
local skyLight = world.getSkyLightLevel(player:getPos())
mySprite:setLight(blockLight, skyLight)

getLight()​

Returns the light override value of this task

getLight()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getLight()

setMatrix()​

Aliases: matrix()

Sets the given matrix as the position matrix for this render task

The normal matrix is automatically calculated as the inverse transpose of this matrix

Calling this DOES NOT CHANGE the values of position, rot, or scale in the render task

If you call setPos() or a similar function, the effects of setMatrix() will be overwritten

setMatrix(matrix)

Parameters:

NameTypeDescriptionDefault
matrixMatrix4--

Returns:

TypeDescription
RenderTask-

Example:

mySprite:setMatrix(matrices.mat4())

getName()​

Get this task's name

getName()

Returns:

TypeDescription
String-

Example:

mySprite:getName()

getNormalMatrix()​

Recalculates the normal matrix for this render task, based on its current position, rotation, scale, and pivot, then returns this matrix

getNormalMatrix()

Returns:

TypeDescription
Matrix3-

Example:

mySprite:getNormalMatrix()

getNormalMatrixRaw()​

Returns the normal matrix for this render task

The Raw version of the function is different in that it doesn't recalculate the matrix before returning it

getNormalMatrixRaw()

Returns:

TypeDescription
Matrix3-

Example:

mySprite:getNormalMatrixRaw()

setOverlay()​

Aliases: overlay()

Sets the overlay override value of this task

Values you give are 0 to 15, indicating the white overlay and the damage overlay levels you want to use

Passing nil will reset the overlay override for this task

setOverlay(overlay)

Parameters:

NameTypeDescriptionDefault
overlayVector2--

Returns:

TypeDescription
RenderTask-

Example:

local hurt = player:getNbt.HurtTime > 0
mySprite:setOverlay(hurt and 0 or nil, 1)

getOverlay()​

Returns the overlay override value of this task

getOverlay()

Returns:

TypeDescription
Vector2-

Example:

mySprite:getOverlay()

setPos()​

Aliases: pos()

Sets the position of the task, relative to its attached part

Uses model coordinates

setPos(pos)

Parameters:

NameTypeDescriptionDefault
posVector3--

Returns:

TypeDescription
RenderTask-

Example:

mySprite:setPos(0, 16, 0)

getPos()​

Gets this task position

getPos()

Returns:

TypeDescription
Vector3-

Example:

mySprite:getPos()

getPositionMatrix()​

Recalculates the matrix for this render task, based on its current position, rotation, scale, and pivot, then returns this matrix

getPositionMatrix()

Returns:

TypeDescription
Matrix4-

Example:

mySprite:getPositionMatrix()

getPositionMatrixRaw()​

Returns the position matrix for this render task

The Raw version of the function is different in that it doesn't recalculate the matrix before getting it

getPositionMatrixRaw()

Returns:

TypeDescription
Matrix4-

Example:

mySprite:getPositionMatrixRaw()

setRot()​

Aliases: rot()

Sets the rotation of the task, relative to its attached part

setRot(rot)

Parameters:

NameTypeDescriptionDefault
rotVector3--

Returns:

TypeDescription
RenderTask-

Example:

mySprite:setRot(0, 45, 22.5)

getRot()​

Gets this task rotation

getRot()

Returns:

TypeDescription
Vector3-

Example:

mySprite:getRot()

setScale()​

Aliases: scale()

Sets the scale of the task, relative to its attached part

setScale(scale)

Parameters:

NameTypeDescriptionDefault
scaleVector3--

Returns:

TypeDescription
RenderTask-

Example:

mySprite:setScale(0.4, 0.4, 0.4) -- mySprite:setScale(0.4) also works

getScale()​

Gets this task scale

getScale()

Returns:

TypeDescription
Vector3-

Example:

mySprite:getScale()

setVisible()​

Aliases: visible()

Sets whether or not this task should be rendered

setVisible(visible)

Parameters:

NameTypeDescriptionDefault
visibleBoolean--

Returns:

TypeDescription
RenderTask-

Example:

local myPage = action_wheel.newPage()
myPage:newAction():setOnToggle(function(state)
    mySprite:setVisible(state)
end)

isVisible()​

Checks if this task is visible

isVisible()

Returns:

TypeDescription
Boolean-

Example:

if mySprite:isVisible() then
    -- do something
end

remove()​

Removes this render task from the parent model part

remove()

Returns:

TypeDescription
RenderTask-

Example:

mySprite:remove()