Models
The global instance of the Avatar Models and its subtypes
Transformations
setVisible(bool)
Sets this part to be visible or invisible
The default value is nil, meaning the part copies its visibility from its parent part
Example:
models:setVisible(false)
getVisible()
Gets whether or not this model part is visible
The default value is nil, meaning it copies the visibility of its parent part during rendering
Example:
models:getVisible()
setRot(Vector3)
Sets the absolute rotation for this part
Nil values for rotation are assumed to be 0
Angles are given in degrees
For relative rotation values, check out the "offset" rot functions
Example:
models:setRot(0, 90, 0)
getRot()
Gets the rotation of the model part, including its rotation in Blockbench
For relative rotation values, check out the "offset" rot functions
Example:
models:setRot()
setPos(Vector3)
Sets the position offset for this part from its Blockbench position
Nil values for position are assumed to be 0
Example:
models:setPos(0, 5, 0)
getPos()
Gets the position of the model part, as an offset from its position in Blockbench
Only changes from 0 when you call setPos()
Example:
models:getPos()
setScale(Vector3)
Sets the scale factor for this part
Nil values for scale are assumed to be 1
Example:
models:setScale(2, 2, 2)
getScale()
Gets the scale of the model part, as a multiple of its Blockbench size
Only changes from 1 when you call setScale()
Example:
models:getScale()
setPivot(Vector3)
Sets the absolute pivot for this part
Nil values are assumed to be 0
For relative pivot offsets, check out the "offset" pivot functions
Example:
models:setPivot(0, 5, 0)
getPivot()
Gets the pivot point of the model part, including its pivot in Blockbench
For relative values, check out the "offset" pivot functions
Example:
models:getPivot()
setOffsetRot(Vector3)
Sets the offset rotation for this part
Nil values for rotation are assumed to be 0
Angles are given in degrees
For absolute rotation values, check out the non-offset rot functions
Example:
models:setOffsetRot(0, 90, 0)
getOffsetRot()
Gets the offset rotation of the model part, offset from its rotation in Blockbench
For absolute rotation values, check out the non-offset rot functions
Example:
models:getOffsetRot()
setOffsetScale(Vector3)
Sets the offset scale for this part
Nil values are assumed to be 1
For absolute scale values, check out the non-offset rot functions
Example:
models:setOffsetScale(2, 2, 2)
getOffsetScale()
Gets the offset scale of the model part, offset from its default scale
For absolute scale values, check out the non-offset rot functions
Example:
models:getOffsetScale()
setOffsetPivot(Vector3)
Sets the offset pivot point for this part
Nil values are assumed to be 0
For absolute pivot point values, check out the non-offset pivot functions
Example:
models:setOffsetPivot(0, 5, 0)
getOffsetPivot()
Gets the offset pivot of the model part, offset from its pivot in Blockbench
For absolute pivot point values, check out the non-offset pivot functions
Example:
models:getOffsetPivot()
setMatrix(Matrix4)
Sets the given matrix as the position matrix for this model part
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 model part
If you call setPos() or a similar function, the effects of setMatrix() will be overwritten
Example:
models:setMatrix(matrices.mat4())
getPositionMatrix()
Recalculates the matrix for this model part, based on its current position, rotation, scale, and pivot, then returns this matrix
Example:
models:getPositionMatrix()
getPositionMatrixRaw()
Returns the position matrix for this model part
The Raw version of the function is different in that it doesn't recalculate the matrix before getting it
Example:
models:getPositionMatrixRaw()
getNormalMatrix()
Recalculates the normal matrix for this model part, based on its current position, rotation, scale, and pivot, then returns this matrix
Example:
models:getNormalMatrix()
getNormalMatrixRaw()
Returns the normal matrix for this model part
The Raw version of the function is different in that it doesn't recalculate the matrix before returning it
Example:
models:getNormalMatrixRaw()
Part Information
getName()
The name of this model part
Example
models:getName()
getType()
Returns whether this part is a "GROUP", a "CUBE", or a "MESH" Example
models:getType()
getTrueRot()
Gets the true rotation of this model part, which is a sum of the rotation, the offset rotation and the animation position
Example:
models:getTrueRot()
getTruePos()
Gets the true position of this model part, which is a sum of the position and the animation position
Example:
models:getTruePos()
getTrueScale()
Gets the true scale of this model part, which is a sum of the scale, the offset scale and the animation scale
Example:
models:getTrueScale()
getTruePivot()
Gets the true pivot of this model part, which is a sum of the pivot and the offset pivot
Example:
models:getTruePivot()
partToWorldMatrix()
Gets a matrix which transforms a point from this part's position to a world location
Recommended to use this in POST_RENDER, as by then the matrix is updated
In RENDER it will be 1 frame behind the part's visual position for that frame
Also, if the model is not rendered in-world, the part's matrix will not be updated
Paperdoll rendering and other UI rendering will not affect this matrix
Example:
models:partToWorldMatrix():apply()
Rendering
setPrimaryRenderType(string)
Sets the current primary render type of this model part
Nil by default, meaning the part copies the primary render type of its parent during rendering
Check the docs enum command for all render types
Example:
models:setPrimaryRenderType("END_PORTAL")
getPrimaryRenderType()
Gets the current primary render type of this model part
Nil by default, meaning the part copies the primary render type of its parent
Example:
models:getPrimaryRenderType() == "TRANSLUCENT_CULL"
setSecondaryRenderType(string)
Sets the current secondary render type of this model part
Nil by default, meaning the part copies the secondary render type of its parent during rendering
Check the docs enum command for all render types
Example:
models:setSecondaryRenderType("GLINT")
getSecondaryRenderType()
Gets the current secondary render type of this model part
Nil by default, meaning the part copies the secondary render type of its parent
Example:
models:getSecondaryRenderType() == "LINES"
setOpacity(Number)
Sets the opacity multiplier of this part
Note that opacity settings will only take effect if the part has a suitable Render Type for them, mainly TRANSLUCENT
Check out modelPart.setPrimaryRenderType() for how to do this
Example:
models:setOpacity(0.5)
getOpacity()
Gets the opacity multiplier of this part
Note that opacity settings will only take effect if the part has a suitable Render Type for them, mainly TRANSLUCENT
Check out modelPart.setPrimaryRenderType() for how to do this
Example:
models:getOpacity()
setLight()
Sets the light level to be used when rendering this part
Values you give are 0 to 15, indicating the block light and sky light levels you want to use
Passing nil will reset the lighting override for this part
Example:
-- Example for mimicking vanilla lighting
local blockLight = world.getBlockLightLevel(player:getPos():add(0, .4, 0))
local skyLight = world.getSkyLightLevel(player:getPos():add(0, .4, 0))
models:setLight(blockLight, skyLight)
getLight()
Gets the light level you set earlier to this part
Does not interact with Minecraft's lighting system, only retrieving values you set earlier with setLight()
Example:
models:getOpacity()
setOverlay()
Sets the overlay color to be used when rendering this part
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 part
Example:
-- Example for a hurt overlay
local hurt = player:getNbt().HurtTime > 0
models:setOverlay(hurt and 0 or nil, 1)
getOverlay()
Gets the overlay color you set earlier to this part
Does not interact with Minecraft's overlay system, only retrieving values you set earlier with setOverlay()
Example:
models:getOverlay()
setColor(Vector3)
Sets the color multiplier for this part for primary and secondary colors
Values are RGB from 0 to 1
Example:
models:setColor(0 / 255, 0 / 255, 255 / 255)
getColor()
Returns the average set color from this part, as adding the primary color with the secondary, then dividing them
Values are RGB from 0 to 1
Example:
models:getColor()
setPrimaryColor(Vector3)
Sets the primary color multiplier for this part
Values are RGB from 0 to 1
Example:
models:setPrimaryColor(0 / 255, 0 / 255, 255 / 255)
getPrimaryColor()
Gets the primary color multiplier of this part
Values are RGB from 0 to 1
Example:
models:getPrimaryColor()
setSecondaryColor(Vector3)
Sets the secondary color multiplier for this part
Values are RGB from 0 to 1
Example:
models:setSecondaryColor(0 / 255, 0 / 255, 255 / 255)
getSecondaryColor()
Gets the secondary color multiplier of this part
Values are RGB from 0 to 1
Example:
models:getSecondaryColor()
setPreRender(fun)
Sets a function to run before this part starts being rendered
setMidRender(fun)
Sets a function to run during the middle of this part's rendering, after its matrices are calculated
setPostRender(fun)
Sets a function to run after this part and its children is rendered
preRender
Function to run before this part starts being rendered
midRender
Function to run during the middle of this part's rendering, after its matrices are calculated
postRender
Function to run after this part and its children is rendered
Animations
getAnimRot()
Gets the rotation offset provided by the currently active animation of this model part
Example:
models:getAnimRot()
getAnimPos()
Gets the position offset provided by the currently active animation of this model part
Example:
models:getAnimPos()
getAnimScale()
Gets the scale multiplier provided by the currently active animation of this model part
Example:
models:getAnimScale()
overrideVanillaRot()
Returns if this part vanilla rotation is being overridden by an animation
Example:
models:overrideVanillaRot()
overrideVanillaPos()
Returns if this part vanilla position is being overridden by an animation
Example:
models:overrideVanillaPos()
overrideVanillaScale()
Returns if this part vanilla scale is being overridden by an animation
Example:
models:overrideVanillaScale()
Texturing
setPrimaryTexture(string)
Sets the primary texture override of this part
Check the TextureType types in the enums
If using "resource", the second parameter should indicate the path to the Minecraft texture you want to use
If using "custom", the second parameter should indicate a texture object
Example:
-- Vanilla Skin
models:setPrimaryTexture("Skin")
-- Custom Texture
models:setPrimaryTexture("Custom", textures["myTexture"])
-- Minecraft Resource
models:setPrimaryTexture("Resource", "textures/entity/pig/pig.png")
getPrimaryTexture()
Gets the primary texture of this part
Returns two values, first being the override type, second being the value, if any.
Example:
models:getPrimaryTexture()
setSecondaryTexture(string)
Sets the secondary texture override of this part
Check the TextureType types in the list docs
If using "resource", the second parameter should indicate the path to the Minecraft texture you want to use
If using "custom", the second parameter should indicate a texture object
Example:
-- Vanilla Skin
models:setSecondaryTexture("Skin")
-- Custom Texture
models:setSecondaryTexture("Custom", textures["myTexture"])
-- Minecraft Resource
models:setSecondaryTexture("Resource", "textures/entity/pig/pig.png")
getSecondaryTexture()
Gets the secondary texture of this part
Returns two values, first being the override type, second being the value, if any.
Example:
models:getSecondaryTexture()
getTextures()
Returns a table with all textures used by this part
Do not include children textures, so groups usually will return an empty table
This function is currently bugged, but it is mainly useless anyway
Example:
models:getTextures()
getTextureSize()
Gets the width, height of this part's texture in pixels
Throws an error if this part has multiple different-sized textures on it, or if the part is a Group
Example:
models:getTextureSize()
setUV(Vector2)
Sets the UV of this part
This function is normalized, meaning it works with values 0 to 1
If you say setUV(0.5, 0.25), for example, it will scroll by half of your texture width to the right, and one fourth of the texture width downwards
Example:
models:setUV(0.5, 0.5)
getUV()
Gets the UV of this part
This function is normalized, meaning it will return values between 0 to 1
Example:
models:getUV()
setUVPixels(Vector2)
Sets the UV of this part in pixels
Automatically divides by the results of getTextureSize(), so you can just input the number of pixels you want the UV to scroll by
Errors if the part has multiple different-sized textures
If this part is a Group, it will attempt to setUVPixels on its children
Example:
models:setUVPixels(16.16)
getUVPixels()
Gets the UV of this part
Automatically multiplies the result by getTextureSize()
Errors if the part has multiple different-sized textures of if the part is a Group
Example:
models:getUVPixels()
setUVMatrix(Matrix3)
Sets the UV matrix of this part
This matrix is applied to all UV points during the transform, with the UVs treated as homogeneous vectors
setUV() and setUVPixels() are actually just simpler ways of setting this matrix
Example:
models:setUVMatrix(matrices.mat3())
getUVMatrix()
Gets the UV matrix of this part
Example:
models:getUVMatrix()
Render Tasks
newText(string)
Adds a new Text Render Task on this part with the given name
The name is not visible in-game, set the text using setText
Example:
models:newText("Example")
newItem(string)
Adds a new Item Render Task on this part with the given name
Example:
models:newItem("Example")
newBlock(string)
Adds a new Block Render Task on this part with the given name
Example:
models:newBlock("Example")
newSprite(string)
Adds a new Sprite Render Task on this part with the given name
Example:
models:newSprite("Example")
newTask(renderTask)
Adds the given Render Task on this part, effectively duplicating it
getTask(string?)
Gets the Render Task with the given name from this part
Returns a table with all tasks if a name is not given
Example:
models:getTask()
removeTask(string?)
Removes the Task with the given name from this part
Removes ALL tasks if a name is not given
Example:
models:removeTask()
Misc
setParentType()
Sets the parent type of the part
See the ParentType parts in the enums for legal types
Example:
models:setParentType("Head")
getParentType()
Returns the current parent type of the part
Example:
models:getParentType()
getVertices(string)
Return a table with all vertices from the given texture id
Returns nil if no vertices was found
Example:
models:getVertices("myTexture")
getAllVertices()
Return a table of all texture ids and its vertices
Example:
models:getAllVertices()
getParent()
Gets the parent part of this part
If this part has no parent, returns nil
Example
models:getParent()
getChildren()
Gets the children of this part, stored in a table
Example:
models:getChildren()
isChildOf(ModelPart)
Checks if this part is a child of the given part
Example:
models:isChildOf(models)
moveTo(ModelPart)
Moves this part to be a child of the given part
Example:
models:moveTo(models)
-- This is recursive
addChild(ModelPart)
Adds the given part into this part's children list
Example:
models:addChild(models)
-- This is recursive
removeChild(ModelPart)
Removes the given part from this part's children list
Example:
models:removeChild(models)
-- This is recursive
copy(string)
Returns a copy of this part, with all customizations and vertices copied
Children parts are passed as reference, in a new list
Example:
models:copy("Example")
newPart(string,string?)
Creates a new, empty, group model part as a child of this part, at the same pivot point
Takes two arguments, the new part's name and optionally its parent type
Example:
-- Example with same parent type
models:newPart("Example")
-- Example with different parent type
models:newPart("Example", "Head")