Skip to main content

SpriteTask

A task for rendering a single Sprite from newSprite

For this entire page assume:

local mySprite = models:newSprite("myCoolSpritesName")

setTexture(texture: Texture | string, width: number?, height: number?): SpriteTask​

Sets this task's texture The texture dimensions, Width and Height, must be provided if the texture is a location For custom textures, the dimensions are optional

Parameters

NameTypeDescription
textureTextureEither a custom texture or a resource location.
widthnumber?Width of the texture in pixels. Optional for custom textures.
heightnumber?Height of the texture in pixels. Optional for custom textures.

Returns

NameTypeDescription
spriteTaskSpriteTaskThe SpriteTask you called this function on to allow 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(): Texture​

Returns this task's current texture

Example:

mySprite:getTexture()

setDimensions(dimensions: Vector2): SpriteTask​

Sets the texture dimensions, used in UV calculation. Accepts a Vector2 of dimension values or a number per value.

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(): Vector2​

Returns the texture dimensions, used in UV calculation

Example:

mySprite:getDimensions()

setSize(size: Vector2): SpriteTask​

Sets the width and height used to render this sprite. Accepts a Vector2 of size values or a number per value.

Example:

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

getSize(): Vector2​

Returns the width and height used to render this sprite

Example:

mySprite:getSize()

setRegion(region: Vector2): SpriteTask​

Sets the texture UV region. Accepts a Vector2 of region values or a number per value. Uses its dimensions to calculate the max UV.

Example:

mySprite:setRegion(64, 64)

getRegion(): Vector2​

Gets the texture UV region

Example:

mySprite:getRegion()

setUV(uv: Vector2): SpriteTask​

Sets this texture UV offset. Accepts a Vector2 of UV values or a number per value. The Region and Dimension are used to calculate the end UV.

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(): Vector2​

Gets this texture UV offset

Example:

mySprite:getUV()

setUVPixels(uv: Vector2): SpriteTask​

Set this texture UV offset, in pixels, based on the texture's dimension. Accepts a Vector2 of UV values or a number per value.

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(): Vector2​

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

Example:

mySprite:getUVPixels()

setColor(rgba: Vector4): SpriteTask​

Sets a color multiplier for this sprite. Values are RGBA from 0 to 1. Default values are 1, alpha is optional. Takes a Vector4 of rgba values or a number per value.

Example:

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

getColor(): Vector4​

Gets the current color multiplier of this sprite Values are RGBA from 0 to 1

Example:

mySprite:getColor()

setRenderType(renderType: RenderType): SpriteTask​

Sets the current render type of this sprite TRANSLUCENT by default Check the docs enum command for all render types

Example:

mySprite:setRenderType("CUTOUT")

getRenderType(): RenderType​

Gets the name of the current render type for this sprite

Example:

mySprite:getRenderType()

getVertices(): Vertex[]​

Returns a table with all 4 vertices of this sprite Changing the values through other functions will reset those vertices

Example:

mySprite:getVertices()

remove(): SpriteTask​

Removes this sprite task from the parent model part

Example:

mySprite:remove()

getName(): string​

Get this task's name

Example:

mySprite:getName()

setVisible(state: boolean): SpriteTask​

Sets whether or not this task should be rendered

Example:

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

isVisible(): boolean​

Checks if this task is visible

Example:

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

setLight(blockLight: number?, skyLight: number?): SpriteTask​

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

Example:

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

getLight(): Vector2​

Returns the light override value of this task

Example:

mySprite:getLight()

setOverlay(whiteOverlay: number?, hurtOverlay: number?): SpriteTask​

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

Example:

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

getOverlay(): Vector2​

Returns the overlay override value of this task

Example:

mySprite:getOverlay()

setPos(pos: Vector3): SpriteTask​

Sets the position of the task, relative with its attached part Uses model coordinates

Example:

mySprite:setPos(0, 16, 0)

getPos(): Vector3​

Gets this task position

Example:

mySprite:getPos()

setRot(rot: Vector3): SpriteTask​

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

Example:

mySprite:setRot(0, 45, 22.5)

getRot(): Vector3​

Gets this task rotation

Example:

mySprite:getRot()

setScale(scale: Vector3): SpriteTask​

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

Example:

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

getScale(): SpriteTask​

Gets this task scale

Example:

mySprite:getScale()

setMatrix(matrix: Matrix4): SpriteTask​

Sets the given matrix as the position matrix for this sprite 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 sprite task If you call setPos() or a similar function, the effects of setMatrix() will be overwritten

Example:

mySprite:setMatrix(matrices.mat4())

getPositionMatrix(): Matrix4​

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

Example:

mySprite:getPositionMatrix()

getPositionMatrixRaw(): Matrix4​

Returns the position matrix for this sprite task The Raw version of the function is different in that it doesn't recalculate the matrix before getting it

Example:

mySprite:getPositionMatrixRaw()

getNormalMatrix(): Matrix3​

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

Example:

mySprite:getNormalMatrix()

getNormalMatrixRaw(): Matrix3​

Returns the normal matrix for this sprite task The Raw version of the function is different in that it doesn't recalculate the matrix before returning it

Example:

mySprite:getNormalMatrixRaw()