EntityTask

A task for rendering an Entity from newEntity

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 myEntity = models:newEntity("myCoolEntityName")

---

Entity Task

asEntity()

Returns the entity associated with this task, or nil if the entity could not exist for any reason.

Due to the special circumstances some readings of the subsequent value may be completely useless

asEntity()

Returns:

Type	Description
EntityAPI	-

Example:

myEntity:asEntity():getBoundingBox()

---

setNbt()

Sets [the nbt of] the entity

Overload 1

setNbt(nbt)

Parameters:

Name	Type	Description	Default
nbt	String	-	-

Returns:

Type	Description
EntityTask	Returns self for chaining

Overload 2

setNbt(id, nbt)

Parameters:

Name	Type	Description	Default
id	String	-	-
nbt	String	-	-

Returns:

Type	Description
EntityTask	Returns self for chaining

Example:

myEntity:setNbt("minecraft:wolf", "{}")

myEntity:setNbt(
    toJson({
        id = "minecraft:wolf",
        Age = 1,
        CollarColor = 9,
        Sitting = true,
        Owner = player:getUUID(),
    })
)

myEntity:setNbt(
    toJson({
        id = "minecraft:zombie",
        IsBaby = true,
    })
)

---

setHeadRotation()

Updates the head rotation of the entity, if applicable

setHeadRotation(rotation)

Parameters:

Name	Type	Description	Default
rotation	Vector2	-	-

Returns:

Type	Description
EntityTask	Returns self for chaining

Example:

myEntity:setHeadRotation(vec(-45, 0))

---

updateWalkingDistance()

Updates the walking animations given the new information, if applicable. For an expected result it should be called every tick with the appropriate value

updateWalkingDistance(distance)

Parameters:

Name	Type	Description	Default
distance	Number	-	-

Returns:

Type	Description
EntityTask	Returns self for chaining

Example:

-- this example only works if the entity is moving
-- at the same speed as the player
local pos
local lastPos

function events.tick()
    lastPos = pos or player:getPos()
    pos = player:getPos()
    local distance = (pos - lastPos).xz:length()
    myEntity:updateWalkingDistance(distance)
end

---

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

Overload 1

setLight(light)

Parameters:

Name	Type	Description	Default
light	Vector2	-	-

Returns:

Type	Description
RenderTask	-

Overload 2

setLight(blockLight, skyLight)

Parameters:

Name	Type	Description	Default
blockLight	Integer	-	-
skyLight	Integer	-	-

Returns:

Type	Description
RenderTask	-

Example:

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

---

getLight()

Returns the light override value of this task

getLight()

Returns:

Type	Description
Vector2	-

Example:

myEntity: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:

Name	Type	Description	Default
matrix	Matrix4	-	-

Returns:

Type	Description
RenderTask	-

Example:

myEntity:setMatrix(matrices.mat4())

---

getName()

Get this task's name

getName()

Returns:

Type	Description
String	-

Example:

myEntity: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:

Type	Description
Matrix3	-

Example:

myEntity: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:

Type	Description
Matrix3	-

Example:

myEntity: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

Overload 1

setOverlay(overlay)

Parameters:

Name	Type	Description	Default
overlay	Vector2	-	-

Returns:

Type	Description
RenderTask	-

Overload 2

setOverlay(whiteOverlay, hurtOverlay)

Parameters:

Name	Type	Description	Default
whiteOverlay	Integer	-	-
hurtOverlay	Integer	-	-

Returns:

Type	Description
RenderTask	-

Example:

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

---

getOverlay()

Returns the overlay override value of this task

getOverlay()

Returns:

Type	Description
Vector2	-

Example:

myEntity:getOverlay()

---

setPos()

Aliases: pos()

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

Uses model coordinates

Overload 1

setPos(pos)

Parameters:

Name	Type	Description	Default
pos	Vector3	-	-

Returns:

Type	Description
RenderTask	-

Overload 2

setPos(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
RenderTask	-

Example:

myEntity:setPos(0, 16, 0)

---

getPos()

Gets this task position

getPos()

Returns:

Type	Description
Vector3	-

Example:

myEntity:getPos()

---

getPositionMatrix()

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

getPositionMatrix()

Returns:

Type	Description
Matrix4	-

Example:

myEntity: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:

Type	Description
Matrix4	-

Example:

myEntity:getPositionMatrixRaw()

---

setRot()

Aliases: rot()

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

Overload 1

setRot(rot)

Parameters:

Name	Type	Description	Default
rot	Vector3	-	-

Returns:

Type	Description
RenderTask	-

Overload 2

setRot(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
RenderTask	-

Example:

myEntity:setRot(0, 45, 22.5)

---

getRot()

Gets this task rotation

getRot()

Returns:

Type	Description
Vector3	-

Example:

myEntity:getRot()

---

setScale()

Aliases: scale()

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

Overload 1

setScale(scale)

Parameters:

Name	Type	Description	Default
scale	Vector3	-	-

Returns:

Type	Description
RenderTask	-

Overload 2

setScale(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
RenderTask	-

Example:

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

---

getScale()

Gets this task scale

getScale()

Returns:

Type	Description
Vector3	-

Example:

myEntity:getScale()

---

setVisible()

Aliases: visible()

Sets whether or not this task should be rendered

setVisible(visible)

Parameters:

Name	Type	Description	Default
visible	Boolean	-	-

Returns:

Type	Description
RenderTask	-

Example:

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

---

isVisible()

Checks if this task is visible

isVisible()

Returns:

Type	Description
Boolean	-

Example:

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

---

remove()

Removes this render task from the parent model part

remove()

Returns:

Type	Description
RenderTask	-

Example:

myEntity:remove()

---