FiguraMC - User contributions [en]

ModelPart

2024-12-14T03:52:06Z

KitCat962: syntax spacing

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

Take below for example:
{{tree|icon=BBModel.png|content=<code>model.bbmodel</code>|inner=
{{tree|icon=BBGroup.png|content=root|inner=
{{tree|icon=BBGroup.png|content=Head|inner=
{{tree|icon=BBCube.png|content=Head}}
{{tree|icon=BBCube.png|content=HeadLayer}}
}}
{{tree|icon=BBGroup.png|content=RightArm|inner=
{{tree|icon=BBCube.png|content=RightArm}}
{{tree|icon=BBCube.png|content=RightArmLayer}}
}}
{{tree|icon=BBCube.png|content=Super Mega Awesome Thing}}
}}
}}

The way to access the {{Emoji|BBCube.png}} RightArm cube would be the following:
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["RightArm"]["RightArm"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.RightArm.RightArm

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awesome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awesome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ParentTypes ==
In Figura, a [[ParentType]] is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as [[ParentType/Hud|<code>Hud</code> parts have special rules]]. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart methods ==

=== ModelPart properties ===
Read-only properties of a ModelPart

==== getName ====
----
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== getType ====
----
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== getParent ====
----
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart|?}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== getChildren ====
----
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== isChildOf ====
----
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== copy ====
----
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[#setParentType|setParentType]],, [[#getParentType|getParentType]],

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[#getName|getName]],, [[#getChildren|getChildren]],, [[#addChild|addChild]],, [[#removeChild|removeChild]],

==== addChild ====
----
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[#copy|copy]],, [[#setPos|setPos]],

==== removeChild ====
----
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== remove ====
----
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[#addChild|addChild]],

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== setPos ====
----
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== getPos ====
----
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[#setPos|setPos]],

==== setRot ====
----
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== getRot ====
----
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setRot|setRot]],

==== setScale ====
----
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== getScale ====
----
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setScale|setScale]],

==== setPivot ====
----
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[#setOffsetPivot|setOffsetPivot]], instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== getPivot ====
----
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[#setPivot|setPivot]],

==== setOffsetRot ====
----
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[#getRot|getRot]], [[#getOffsetRot|getOffsetRot]],

==== getOffsetRot ====
----
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setOffsetRot|setOffsetRot]],

==== setOffsetScale ====
----
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== getOffsetScale ====
----
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setOffsetScale|setOffsetScale]],

==== setOffsetPivot ====
----
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== getOffsetPivot ====
----
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[#setOffsetPivot|setOffsetPivot]],

==== setMatrix ====
----
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePos ====
----
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueRot ====
----
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueScale ====
----
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePivot ====
----
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== setVisible ====
----
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== getVisible ====
----
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool|?}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== setColor ====
----
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== getColor ====
----
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[#setColor|setColor]],

==== setOpacity ====
----
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== getOpacity ====
----
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[#setOpacity|setOpacity]],

==== setLight ====
----
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer|?}}, skyLight {{type|integer|?}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== getLight ====
----
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[#setLight|setLight]],

==== setOverlay ====
----
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer|?}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== getOverlay ====
----
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[#setOverlay|setOverlay]],

=== renderTasks ===
todo: put all rendertask functions in here

=== Render methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

== Navigation ==
{{Navbox documentation}}

ModelPart

2024-12-14T03:49:54Z

KitCat962: Grammer

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}Take below for example:{{tree|icon=BBModel.png|content=<code>model.bbmodel</code>|inner=
{{tree|icon=BBGroup.png|content=root|inner=
{{tree|icon=BBGroup.png|content=Head|inner=
{{tree|icon=BBCube.png|content=Head}}
{{tree|icon=BBCube.png|content=HeadLayer}}
}}
{{tree|icon=BBGroup.png|content=RightArm|inner=
{{tree|icon=BBCube.png|content=RightArm}}
{{tree|icon=BBCube.png|content=RightArmLayer}}
}}
{{tree|icon=BBCube.png|content=Super Mega Awesome Thing}}
}}
}}

The way to access the {{Emoji|BBCube.png}} RightArm cube would be the following:
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["RightArm"]["RightArm"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.RightArm.RightArm

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awesome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awesome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ParentTypes ==
In Figura, a [[ParentType]] is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as [[ParentType/Hud|<code>Hud</code> parts have special rules]]. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart methods ==

=== ModelPart properties ===
Read-only properties of a ModelPart

==== getName ====
----
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== getType ====
----
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== getParent ====
----
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart|?}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== getChildren ====
----
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== isChildOf ====
----
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== copy ====
----
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[#setParentType|setParentType]],, [[#getParentType|getParentType]],

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[#getName|getName]],, [[#getChildren|getChildren]],, [[#addChild|addChild]],, [[#removeChild|removeChild]],

==== addChild ====
----
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[#copy|copy]],, [[#setPos|setPos]],

==== removeChild ====
----
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== remove ====
----
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[#addChild|addChild]],

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== setPos ====
----
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== getPos ====
----
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[#setPos|setPos]],

==== setRot ====
----
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== getRot ====
----
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setRot|setRot]],

==== setScale ====
----
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== getScale ====
----
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setScale|setScale]],

==== setPivot ====
----
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[#setOffsetPivot|setOffsetPivot]], instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== getPivot ====
----
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[#setPivot|setPivot]],

==== setOffsetRot ====
----
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[#getRot|getRot]], [[#getOffsetRot|getOffsetRot]],

==== getOffsetRot ====
----
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setOffsetRot|setOffsetRot]],

==== setOffsetScale ====
----
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== getOffsetScale ====
----
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setOffsetScale|setOffsetScale]],

==== setOffsetPivot ====
----
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== getOffsetPivot ====
----
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[#setOffsetPivot|setOffsetPivot]],

==== setMatrix ====
----
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePos ====
----
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueRot ====
----
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueScale ====
----
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePivot ====
----
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== setVisible ====
----
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== getVisible ====
----
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool|?}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== setColor ====
----
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== getColor ====
----
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[#setColor|setColor]],

==== setOpacity ====
----
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== getOpacity ====
----
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[#setOpacity|setOpacity]],

==== setLight ====
----
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer|?}}, skyLight {{type|integer|?}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== getLight ====
----
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[#setLight|setLight]],

==== setOverlay ====
----
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer|?}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== getOverlay ====
----
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[#setOverlay|setOverlay]],

=== renderTasks ===
todo: put all rendertask functions in here

=== Render methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

== Navigation ==
{{Navbox documentation}}

ModelPart

2024-09-28T20:16:06Z

KitCat962: /* ParentTypes via BlockBench */ link to hud specifications/tutorial page

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ParentTypes ==
In Figura, a [[ParentType]] is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as [[ParentType/Hud|<code>Hud</code> parts have special rules]]. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== getName ====
----
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== getType ====
----
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== getParent ====
----
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart|?}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== getChildren ====
----
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== isChildOf ====
----
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== copy ====
----
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[#setParentType|setParentType]],, [[#getParentType|getParentType]],

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[#getName|getName]],, [[#getChildren|getChildren]],, [[#addChild|addChild]],, [[#removeChild|removeChild]],

==== addChild ====
----
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[#copy|copy]],, [[#setPos|setPos]],

==== removeChild ====
----
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== remove ====
----
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[#addChild|addChild]],

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== setPos ====
----
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== getPos ====
----
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[#setPos|setPos]],

==== setRot ====
----
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== getRot ====
----
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setRot|setRot]],

==== setScale ====
----
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== getScale ====
----
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setScale|setScale]],

==== setPivot ====
----
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[#setOffsetPivot|setOffsetPivot]], instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== getPivot ====
----
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[#setPivot|setPivot]],

==== setOffsetRot ====
----
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[#getRot|getRot]], [[#getOffsetRot|getOffsetRot]],

==== getOffsetRot ====
----
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setOffsetRot|setOffsetRot]],

==== setOffsetScale ====
----
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== getOffsetScale ====
----
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setOffsetScale|setOffsetScale]],

==== setOffsetPivot ====
----
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== getOffsetPivot ====
----
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[#setOffsetPivot|setOffsetPivot]],

==== setMatrix ====
----
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePos ====
----
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueRot ====
----
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueScale ====
----
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePivot ====
----
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== setVisible ====
----
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== getVisible ====
----
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool|?}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== setColor ====
----
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== getColor ====
----
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[#setColor|setColor]],

==== setOpacity ====
----
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== getOpacity ====
----
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[#setOpacity|setOpacity]],

==== setLight ====
----
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer|?}}, skyLight {{type|integer|?}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== getLight ====
----
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[#setLight|setLight]],

==== setOverlay ====
----
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer|?}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== getOverlay ====
----
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[#setOverlay|setOverlay]],

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

Models

2024-09-28T16:28:16Z

KitCat962: Changed redirect target from ModelParts to ModelPart

#REDIRECT [[ModelPart]]

ModelPart

2024-09-28T16:18:43Z

KitCat962: /* Visual Manipulation */ regex fail lmao

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ParentTypes ==
In Figura, a [[ParentType]] is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== getName ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== getType ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== getParent ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart|?}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== getChildren ====
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== isChildOf ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== copy ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[#setParentType|setParentType]],, [[#getParentType|getParentType]],

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[#getName|getName]],, [[#getChildren|getChildren]],, [[#addChild|addChild]],, [[#removeChild|removeChild]],

==== addChild ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[#copy|copy]],, [[#setPos|setPos]],

==== removeChild ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== remove ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[#addChild|addChild]],

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== setPos ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== getPos ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[#setPos|setPos]],

==== setRot ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== getRot ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setRot|setRot]],

==== setScale ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== getScale ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setScale|setScale]],

==== setPivot ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[#setOffsetPivot|setOffsetPivot]], instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== getPivot ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[#setPivot|setPivot]],

==== setOffsetRot ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[#getRot|getRot]], [[#getOffsetRot|getOffsetRot]],

==== getOffsetRot ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setOffsetRot|setOffsetRot]],

==== setOffsetScale ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== getOffsetScale ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setOffsetScale|setOffsetScale]],

==== setOffsetPivot ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== getOffsetPivot ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[#setOffsetPivot|setOffsetPivot]],

==== setMatrix ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePos ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueRot ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueScale ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePivot ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool|?}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[#setColor|setColor]],

==== setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[#setOpacity|setOpacity]],

==== setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer|?}}, skyLight {{type|integer|?}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[#setLight|setLight]],

==== setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer|?}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[#setOverlay|setOverlay]],

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-28T16:17:01Z

KitCat962: reduced @see, changed headings, nullable tag

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ParentTypes ==
In Figura, a [[ParentType]] is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== getName ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== getType ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== getParent ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart|?}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== getChildren ====
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== isChildOf ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== copy ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[#setParentType|setParentType]],, [[#getParentType|getParentType]],

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[#getName|getName]],, [[#getChildren|getChildren]],, [[#addChild|addChild]],, [[#removeChild|removeChild]],

==== addChild ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[#copy|copy]],, [[#setPos|setPos]],

==== removeChild ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== remove ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[#addChild|addChild]],

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== setPos ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== getPos ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[#setPos|setPos]],

==== setRot ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== getRot ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setRot|setRot]],

==== setScale ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== getScale ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setScale|setScale]],

==== setPivot ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[#setOffsetPivot|setOffsetPivot]], instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== getPivot ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[#setPivot|setPivot]],

==== setOffsetRot ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[#getRot|getRot]], [[#getOffsetRot|getOffsetRot]],

==== getOffsetRot ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[#setOffsetRot|setOffsetRot]],

==== setOffsetScale ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== getOffsetScale ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[#setOffsetScale|setOffsetScale]],

==== setOffsetPivot ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== getOffsetPivot ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[#setOffsetPivot|setOffsetPivot]],

==== setMatrix ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePos ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueRot ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTrueScale ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== getTruePivot ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool|?}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== ModelPart:getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[#setColor|setColor]],

==== ModelPart:setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== ModelPart:getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[#setOpacity|setOpacity]],

==== ModelPart:setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer|?}}, skyLight {{type|integer|?}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== ModelPart:getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[#setLight|setLight]],

==== ModelPart:setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2|?}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer|?}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== ModelPart:getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[#setOverlay|setOverlay]],

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-28T15:15:42Z

KitCat962: KitCat962 moved page ModelParts to ModelPart over redirect: Misspelled title: modelpart

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart}} <nowiki>|</nowiki> {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>
'''@see''' [[Globals#printTable|printTable]]

==== <code>ModelPart:isChildOf</code> ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} <nowiki>|</nowiki> {{type|nil}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== ModelPart:getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setColor|setColor]]

==== ModelPart:setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== ModelPart:getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOpacity|setOpacity]]

==== ModelPart:setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, skyLight {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== ModelPart:getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setLight|setLight]]

==== ModelPart:setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== ModelPart:getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOverlay|setOverlay]]

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-28T14:22:37Z

KitCat962: /* ModelPart:getParent */ |

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
| {{type|ModelPart}} <nowiki>|</nowiki> {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>
'''@see''' [[Globals#printTable|printTable]]

==== <code>ModelPart:isChildOf</code> ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} <nowiki>|</nowiki> {{type|nil}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== ModelPart:getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setColor|setColor]]

==== ModelPart:setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== ModelPart:getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOpacity|setOpacity]]

==== ModelPart:setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, skyLight {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== ModelPart:getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setLight|setLight]]

==== ModelPart:setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== ModelPart:getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOverlay|setOverlay]]

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-28T14:16:55Z

KitCat962: /* ModelPart:getChildren */ minor tweaks

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array containing all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
printTable(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>
'''@see''' [[Globals#printTable|printTable]]

==== <code>ModelPart:isChildOf</code> ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} <nowiki>|</nowiki> {{type|nil}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== ModelPart:getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setColor|setColor]]

==== ModelPart:setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== ModelPart:getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOpacity|setOpacity]]

==== ModelPart:setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, skyLight {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== ModelPart:getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setLight|setLight]]

==== ModelPart:setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== ModelPart:getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOverlay|setOverlay]]

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-28T00:43:02Z

KitCat962: /* Visual Manipulation */ setColor setLight setOpacity setOverlay & getters

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

{{note|<code>models</code> itself is a ModelPart. This allows you to apply transformations to the entire model, using e.g. <code>models:setScale(0.5)</code>.|tag=Trivia|color=#A155DA}}

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be indexed with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined way. This behavior includes acting as a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, or parrots, and binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a case-sensitive ParentType.

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType which can cause unintended behavior!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Editing ModelPart Hierarchy ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursively checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children because it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursively goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} <nowiki>|</nowiki> {{type|nil}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture. Children of this ModelPart inherit the color, multiplied with their own.

1,1,1 multiplies all color channels by 1, resulting in the texture unchanged. 0,0,0 results in all channels being black.

Expects values between 0 and 1. Numbers larger than 1 results in undocumented behaviour. <code>nil</code> values are interpreted as 1. If only <code>r</code> is defined as a number and both <code>g</code> and <code>b</code> are omitted, <code>r</code> is used for all 3 color channels.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setColor(color {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(colorAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setColor(r {{type|number}}, g {{type|number}}, b {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Darken the entire model
root:setColor(0.5,0.5,0.5)
-- Tint the Head red by reducing the other color channels.
-- Color is inherited from parents, so the effective color is (0.5, 0.45, 0.45)
root.Head:setColor(1,0.7,0.7)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- If you want to 'reset' a child's color value, extra work is needed.

-- Color is max red
local color = vec(1,0,0)
local root = models.model.root
-- root has color
root:setColor(color)
-- Through magic and wizardry, this 'resets' the color of Head back to white, dispite it's parent having a non-white color
root.Head:setColor(-color + 2)
</syntaxhighlight>

==== ModelPart:getColor ====
Gets the value set by <code>setColor</code>. Returns 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getColor()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setColor(0.5)
print(root:getColor()) --> (0.5, 0.5, 0.5)
root.Head:setColor(1,0.7,0.7)
// getColor is not recursive
print(root.Head:getColor()) --> (1, 0.7, 0.7)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setColor|setColor]]

==== ModelPart:setOpacity ====
Sets the opacity of the ModelPart. Children of this ModelPart inherit the opacity, multiplied with their own.

Minecraft has a minimum visible opacity of 0.1. Opacity values lower than 0.1 will not render at all. Needs verification.

Only supported on [[RenderType|RenderTypes]] that support translucency. The default primary RenderType is <code>TRANSLUCENT</code>, so most don't have to worry about it.

Expects a value between 0 and 1.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOpacity(opacity {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Half opacity
root:setOpacity(0.5)
-- Half of half opacity
root.Head:setColor(0.5)
</syntaxhighlight>

==== ModelPart:getOpacity ====
Gets the value set by <code>setOpacity</code>. Returns 1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOpacity()</code>
| {{type|number}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
root:setOpacity(0.5)
print(root:getOpacity()) --> 0.5
root.Head:setOpacity(0.5)
// getOpacity is not recursive
print(root.Head:getOpacity()) --> 0.5
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOpacity|setOpacity]]

==== ModelPart:setLight ====
Overrides the lightlevels used to render the ModelPart. Children of this ModelPart inherit the lightlevel.

Expects 2 values between 0 and 15, or <code>nil</code>. Providing <code>nil</code> will undo the override, allowing Minecraft to control the lightlevel again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setLight(light {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setLight(blockLight {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, skyLight {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Max light
root:setLight(15, 15)
</syntaxhighlight>

<syntaxhighlight lang="lua">
local root = models.model.root
-- set light based on position (This is a fix for broken lighting on World parts)
function events.tick()
local pos = player:getPos()
local blockLight = world.getBlockLightLevel(pos)
local skyLight = world.getSkyLightLevel(pos)
root:setLight(blockLight, skyLight)
end
</syntaxhighlight>
'''@see''' [[PlayerAPI#PlayerAPI:getPos|player:getPos]] [[WorldAPI#WorldAPI.getBlockLightLevel|world.getBlockLightLevel]] [[WorldAPI#WorldAPI.getSkyLightLevel|world.getSkyLightLevel]]

==== ModelPart:getLight ====
Gets the value set by <code>setLight</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getLight()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getLight()) --> nil

root:setLight(12, 8)

let light = root:getLight()
print(light) --> vec(12, 8)
print("BlockLightLevel -> ", light.x) --> "BlockLightLevel -> 12"
print("SkyLightLevel -> ", light.y) --> "BlockLightLevel -> 8"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setLight|setLight]]

==== ModelPart:setOverlay ====
Overrides the values used for rendering the red damage tint and the white creeper fuse effect. Really only useful for preventing the damage overlay from rendering on stuff like armor.

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

When set, hurtOverlay overrides whiteOverlay. For whiteOverlay to not be overriden, hurtOverlay needs to be 8 or more.

Providing <code>nil</code> will undo the override, allowing Minecraft to control the overlay again.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOverlay(overlayVector {{type|Vector2}} <nowiki>|</nowiki> {{type|nil}})</code>
| self {{type|ModelPart}}
|-
| <code>setOverlay(whiteOverlay {{type|integer}} <nowiki>|</nowiki> {{type|nil}}, hurtOverlay {{type|integer}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
-- Damage overlay
root:setOverlay(0, 0)
-- Literally no difference
root:setOverlay(0, 5)
root:setOverlay(0, 7)

-- Doesnt work. Damage overlay overrides white
root:setOverlay(15, 0)

-- This works. Max white overlay
root:setOverlay(15, 15)

-- This can be used to for preventing the damage overlay on armor
root:setOverlay(0, 15)

-- Give control back to Minecraft
root:setOverlay(nil)
</syntaxhighlight>

==== ModelPart:getOverlay ====
Gets the value set by <code>setOverlay</code>. Returns <code>nil</code> when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOverlay()</code>
| {{type|Vector2}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root

print(root:getOverlay()) --> nil

root:setOverlay(8, 15)

let overlay = root:getOverlay()
print(overlay) --> vec(8, 15)
print("whiteOverlay -> ", overlay.x) --> "whiteOverlay -> 8"
print("hurtOverlay -> ", overlay.y) --> "hurtOverlay -> 15"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOverlay|setOverlay]]

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-27T02:13:37Z

KitCat962: grammer

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar, and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into a ModelPart.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

<pre>Fun Fact: models itself is a ModelPart</pre>

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be index with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined behaviour. This behaviour includes behaving like a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, and parrots, or binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself, or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a ParentType

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType and can cause unintended behaviour!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Child Manipulation ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursivly checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children cause it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursivly goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} <nowiki>|</nowiki> {{type|nil}} {{until|0.1.5}}
|-
| <code>getVisible()</code>
| {{type|bool}} {{since|0.1.5}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture.

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

User:KitCat962

2024-09-27T01:46:02Z

KitCat962: Undo revision 203 by KitCat962 (talk)

[[File:Kitcat avatar shades.png|thumb|199x199px]]
hehehe

User:KitCat962

2024-09-27T01:45:29Z

KitCat962: heading testing

[[File:Kitcat avatar shades.png|thumb|199x199px]]
hehehe

= HEADING =

== Heading ==

=== Heading ===

==== heading ====

ModelPart

2024-09-27T01:32:58Z

KitCat962: /* ModelPart Methods */ new categories

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to do achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar, and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into ModelParts.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

<pre>Fun Fact: models itself is a ModelPart</pre>

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be index with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined behaviour. This behaviour includes behaving like a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, and parrots, or binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself, or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a ParentType

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType and can cause unintended behaviour!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Child Manipulation ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursivly checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children cause it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

=== Visual Manipulation ===
Methods relating to modifying how a ModelPart looks

todo: put anything related to renderType, textures, and other visual modifications in here

==== ModelPart:setVisible ====
Sets if this ModelPart is visible or not. Children of this ModelPart will also be invisible while this part is invisible.

A value of <code>nil</code> is interpreted as <code>true</code> on 0.1.4 and below, and <code>false</code> on 0.1.5 and above. This message will disappear <s>if</s> when 0.1.6 is released.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setVisible(visible {{type|boolean}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
local head = models.model.root.Head

head:setVisible(false) -- Bye bye Head!
</syntaxhighlight>

==== ModelPart:getVisible ====
Recursivly goes up the ModelPart tree until it finds a ModelPart that is invisible, or the ModelPart is <code>models</code>

In other words, if a parent part is invisible, this function returns <code>false</code>. If all parent parts are visible, this function will return <code>true</code> or <code>nil</code>. Kinda stupid. This is fixed in 0.1.5 to never return <code>nil</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getVisible()</code>
| {{type|bool}} | {{type|nil}}
|}
<syntaxhighlight lang="lua">
local root = models.model.root.Head

print(root.Head:getVisible()) --> nil --< this is stupid
root:setVisible(false) -- Bye bye root!
print(root.Head:getVisible()) --> false
root:setVisible(true) -- Welcome back root!
print(root.Head:getVisible()) --> true --< aaaaaaaa
</syntaxhighlight>

==== ModelPart:setColor ====
Sets a value to multiply with all pixels on the ModelPart's texture.

=== renderTasks ===
todo: put all rendertask functions in here

=== Render Methods ===
todo: Put partToWorldMatrix, preRender, midRender, and PostRender in here

=== Animation Methods ===
todo: put getAnimPos/Rot/Scale and overrideVanillaPos/Rot/Scale in here

ModelPart

2024-09-27T00:48:24Z

KitCat962: Redundant heading

A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to do achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar, and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into ModelParts.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

<pre>Fun Fact: models itself is a ModelPart</pre>

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be index with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined behaviour. This behaviour includes behaving like a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, and parrots, or binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself, or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a ParentType

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType and can cause unintended behaviour!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Child Manipulation ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursivly checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children cause it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

ModelPart

2024-09-27T00:47:10Z

KitCat962: Category descriptions

== What are ModelParts ==
A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to do achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar, and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into ModelParts.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

<pre>Fun Fact: models itself is a ModelPart</pre>

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be index with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined behaviour. This behaviour includes behaving like a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, and parrots, or binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself, or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a ParentType

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType and can cause unintended behaviour!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===
Read-only properties of a ModelPart

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Child Manipulation ===
Methods relating to getting other ModelParts and manipulating the ModelPart tree

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursivly checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children cause it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===
Methods relating to manipulating the ModelPart within physical space

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

ModelPart

2024-09-27T00:40:48Z

KitCat962: /* ModelPart Methods */ added translation related methods

== What are ModelParts ==
A ModelPart represents a Cube, Mesh, or Group from Blockbench.

Via scripting, ModelParts can be modified dynamically to do achieve whatever visuals you need (limited to Minecraft's rendering engine)

== Accessing ModelParts ==
<code>models</code> is the global that acts as the Root of your avatar, and is where all ModelParts are stored, either as a child of <code>models</code>, a child of a child, or further down the tree.

Specifically, <code>models</code>'s children are Blockbench models. When an avatar is selected, not only are a bbmodel's Cubes, Meshes, and Groups converted into ModelParts, but the bbmodel file itself is converted into ModelParts.

To access a child ModelPart from a parent ModelPart, [https://www.lua.org/pil/2.5.html index] the parent using the child's name as a string.

Example:
<syntaxhighlight lang="lua">
local bbmodel = models["model"] -- access the bbmodel "model.bbmodel"
</syntaxhighlight>

This logic is the same for every single ModelPart. If you want to access a child, index the parent with the child's name.

<pre>Fun Fact: models itself is a ModelPart</pre>

The below example accesses the Head Group from the [[WikiExampleAvatar]]
<syntaxhighlight lang="lua">
local head = models["model"]["root"]["Head"]
</syntaxhighlight>
If the above seems tedious, Lua provides a shorthand way of indexing with strings. It only works when the string contains no spaces or special characters.
<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Below is invalid, as the name contains spaces
local superMegaAwsomeThing = models.model.root.Super Mega Awsome Thing

-- Super Mega Awsome Thing would need to be index with the normal method
local superMegaAwsomeThing = models.model.root["Super Mega Awsome Thing"]
</syntaxhighlight>

=== BBModels within folders ===
When a bbmodel is within a folder, Figura will actually turn the folder itself into a ModelPart. This can be confusing as ModelParts are the only thing that does this.

<syntaxhighlight lang="lua">
local folderHead = models.folder.model.root.Head
</syntaxhighlight>

== ModelPart ParentTypes ==
In Figura, a ParentType is applied to a ModelPart causing the ModelPart to behave in a predefined behaviour. This behaviour includes behaving like a vanilla part like the Head or LeftLeg, moving the rendering of special parts like held items, armor, and parrots, or binding the ModelPart to the World instead of the Player.

ParentTypes can either be applied in Blockbench itself, or via script.
=== ParentTypes via BlockBench ===
To define a ParentType in Blockbench, the name of a Group must begin with a ParentType

For example, the <code>Head</code> ParentType causes the ModelPart to move and rotate like the vanilla Head. If you name a Group the following, it will have this ParentType:

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, it will not have the <code>Head</code> ParentType:

* head => 'head' is not a valid ParentType. Capitalization matters!
* BigHead => Does not begin with ParentType
* HeAd => 'HeAd' is not a valid ParentType. Capitalization matters!

Do note that some English words naturally start with a ParentType and can cause unintended behaviour!

For example, the word "Guitar". Seems innocent, right? Well, "Guitar" starts with "Gui", and "Gui" is an alias for the ParentType <code>Hud</code>, a ParentType that binds the ModelPart to the Heads Up Display where the hotbar and inventory reside. This causes the ModelPart to not be visible, as <code>Hud</code> parts have special rules. Be careful!

<pre>Note: ParentTypes are sometimes called Keywords by legacy Figura users</pre>

=== ParentTypes via Script ===
Calling the <code>setParentType</code> on any ModelPart will override it's ParentType.

Simply [[ModelParts#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts do not remember their original ParentType! If you need a ModelPart's original ParentType, store it in a variable for later:
<syntaxhighlight lang="lua">
local head = models.model.root.Head
local headParentType = head:getParentType()
head:setParentType("None")
</syntaxhighlight>
== ModelPart Methods ==

=== ModelPart Properties ===

==== <code>ModelPart:getName</code> ====
Returns the name of this ModelPart. ModelParts can have duplicate names.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getName()</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getName()) --> "Head"
</syntaxhighlight>

==== <code>ModelPart:getType</code> ====
Returns the original type of this ModelPart. Can be <code>Cube</code>, <code>Mesh</code>, or <code>Group</code>. BBModels and folders are considered Groups. Cubes with no texture data are also considered Groups, as with no texture data their face data is stripped.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getType()</code>
|| <code>"Cube" | "Mesh" | "Group"</code>
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getType()) --> "Group"
</syntaxhighlight>

=== Child Manipulation ===

==== <code>ModelPart:getParent</code> ====
Returns the parent of this ModelPart, or <code>nil</code> if this is <code>models</code> or a loose ModelPart created via script.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getParent()</code>
|| {{type|ModelPart}} | {{type|nil}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
print(head:getParent()) --> ModelPart(root)
</syntaxhighlight>

==== <code>ModelPart:getChildren</code> ====
Returns an array of all children of this ModelPart
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getChildren()</code>
|| {{type|ModelPart|[]}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
print(root:getChildren()) --[[
ModelPart(Head),
ModelPart(Body),
ModelPart(RightArm),
ModelPart(LeftArm),
ModelPart(RightLeg),
ModelPart(LeftLeg),
]]--
</syntaxhighlight>

==== <code>ModelPart:isChildOf</code> ====
Recursivly checks if this child is a decedent of the provided ModelPart.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isChildOf(part {{type|ModelPart}})</code>
|| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
local model = models.model
local head = model.root.Head
print(head:isChildOf(model)) --> true
</syntaxhighlight>

==== <code>ModelPart:copy</code> ====
Copies the data of this ModelPart, assigning it a new name, then returning it. The new name has nothing to do with ParentTypes. The children of the copy are references to the original ModelPart's children. Extra work needs to be done to recursively copy it's children. The [[ModelPart#ModelPart_addChild|addChild]] method can then be used to add the copy to the ModelPart tree.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>copy(newName {{type|string}})</code>
|| {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy) --> ModelPart(NewHead)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- The parentType is copied with the ModelPart
local head = models.model.root.Head

local headCopy = head:copy("NewHead")
print(headCopy:getParentType()) --> "Head"

headCopy:setParentType("None")
print(headCopy:getParentType()) --> "None"
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setParentType|setParentType]], [[ModelParts#ModelPart:getParentType|getParentType]]

<syntaxhighlight lang="lua">
-- Extra work is needed to deep copy a ModelPart's children as well
local function deepCopy(model)
local copy = model:copy(model:getName())
for _, child in pairs(copy:getChildren()) do
copy:removeChild(child):addChild(deepCopy(child))
end
return copy
end

local head = models.model.root.Head
local headCube = head.Head

-- headCopyA contains references to head's children cause it is a shallow copy
local headCopyA = head:copy("NewHead")
print(headCopyA.Head == headCube) --> true

-- headCopyB contains true copies of head's children as it was passed through a function that recursively copies children
local headCopyB = deepCopy(head)
print(headCopyB.Head == headCube) --> false
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getName|getName]], [[ModelParts#ModelPart:getChildren|getChildren]], [[ModelParts#ModelPart:addChild|addChild]], [[ModelParts#ModelPart:removeChild|removeChild]]

==== <code>ModelPart:addChild</code> ====
Adds the provided ModelPart as one of this ModelPart's children. Beware of adding a parent of this ModelPart as a child! This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>addChild(part {{type|ModelPart}})</code>
|| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local headCopy = root.Head:copy("NewHead")
root:addChild(headCopy)
headCopy:setPos(10,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:copy|copy]], [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:removeChild</code> ====
Removes a child from this ModelPart. Takes in the child ModelPart itself. This method returns this ModelPart for method chaining.
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>removeChild(partToRemove {{type|ModelPart}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local root = models.model.root
local head = root.Head
root:removeChild(head) -- Bye bye Head!

-- Head is still valid and can be re-added later, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
</syntaxhighlight>

==== <code>ModelPart:remove</code> ====
Removes this ModelPart from the parent's child list. Returns self
{| class="wikitable"
! Arguments !! Return Type
|-
| <code>remove()</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:remove() -- Bye bye Head!

-- Head is still valid and can be re-added, so long as we keep a variable referencing it.
print(head) --> ModelPart(Head)
models.model.root.LeftLeg:addChild(head)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:addChild|addChild]]

=== Manipulation ===

==== <code>ModelPart:setPos</code> ====
Sets the offset of the the position of the ModelPart. Position translation applies on the local rotation axis.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPos(pos {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPos(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Move 10 units on the local y axis
head:setPos(0, 10, 0)
</syntaxhighlight>

==== <code>ModelPart:getPos</code> ====
Returns the value that was used for <code>setPos</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPos()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getPos()) --> vec(0,0,0)
head:setPos(0, 10, 0)
print(head:getPos()) --> vec(0,10,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPos|setPos]]

==== <code>ModelPart:setRot</code> ====
Sets the rotation of the ModelPart. Rotates the ModelPart around the PivotPoint.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- Rotate 45 degrees on the x axis, causing the avatar to look down
head:setRot(0, 45, 0)
</syntaxhighlight>

==== <code>ModelPart:getRot</code> ====
Returns the value that was used for <code>setRot</code>. Will be the Rotation values defined in BlockBench when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getRot()) --> vec(0,0,0) -- Most ModelParts will not have a rotation set in blockbench
head:setRot(45, 0, 0)
print(head:getPos()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Squishes and stretches the entire model
models.model:setScale(1.5, 0.75, 1.5)
</syntaxhighlight>

==== <code>ModelPart:getScale</code> ====
Returns the value that was used for <code>setScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getScale()) --> vec(1,1,1)
head:setScale(2)
print(head:getScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setScale|setScale]]

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- For a normal size humanoid model, the Head's pivot point is usually at 0,24,0
-- If we assume that the Head cube is an 8x8x8 cube,
-- then the head will rotate around the center of the cube instead of the neck
head:setPivot(0, 28, 0)
</syntaxhighlight>

==== <code>ModelPart:getPivot</code> ====
Returns the Pivot Point defined in BlockBench, or the value set by <code>setPivot</code> if it was already overwritten.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- The Head group's pivot point for a humanoid model is usually at 0,24,0
print(head:getPivot()) --> vec(0,24,0)
head:setPivot(0,0,0)
-- We have completely ruined the rendering of this ModelPart
print(head:getPivot()) --> vec(0,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setPivot|setPivot]]

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

Angles are interpreted as degrees. <code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetRot(rot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetRot(pitch {{type|number}}, yaw {{type|number}}, roll {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- ModelParts inherit their rotation from blockbench. The Head usually has a rotation of 0,0,0 for consistency with the vanilla model
print(head:getRot()) --> vec(0,0,0)
-- Set the offset to 45 degrees on the x axis, causing the avatar to look down
head:setOffsetRot(0, 45, 0)
-- The original rotation is unchanged.
print(head:getRot()) --> vec(0,0,0)

-- setOffsetRot is not additive.
head:setOffsetRot(0, 25, 0)
print(head:getOffsetRot()) --> vec(0,25,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:getRot|getRot]] [[ModelParts#ModelPart:getOffsetRot|getOffsetRot]]

==== <code>ModelPart:getOffsetRot</code> ====
Returns the value that was used for <code>setOffsetRot</code>. Will be 0,0,0 when the script begins

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetRot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetRot()) --> vec(0,0,0)
head:setOffsetRot(45, 0, 0)
print(head:getOffsetRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetRot|setOffsetRot]]

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

<code>nil</code> values are interpreted as 1. If a number is provided for x and both y and z are not defined, x will be used for all 3 axis.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetScale(scale {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(scaleAll {{type|number}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetScale(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head
-- Double the size of the head
head:setScale(2)
-- Half the size of the head
head:setOffsetScale(0.5)
-- Results in no changes
-- I have no idea what this is used for
</syntaxhighlight>

==== <code>ModelPart:getOffsetScale</code> ====
Returns the value that was used for <code>setOffsetScale</code>. Always 1,1,1 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetScale()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetScale()) --> vec(1,1,1)
head:setOffsetScale(2)
print(head:getOffsetScale()) --> vec(2,2,2)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetScale|setOffsetScale]]

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

<code>nil</code> values are interpreted as 0.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setOffsetPivot(pivot {{type|Vector3}})</code>
| self {{type|ModelPart}}
|-
| <code>setOffsetPivot(x {{type|number}}, y {{type|number}}, z {{type|number}})</code>
| self {{type|ModelPart}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

-- If we assume that the Head cube is an 8x8x8 cube and offset the pivot up by 4,
-- then the head will rotate around the center of the cube instead of the neck
head:setOffsetPivot(0, 4, 0)
-- Notice that we did not need to know the original pivot point to do this
</syntaxhighlight>

==== <code>ModelPart:getOffsetPivot</code> ====
Returns the value that was used for <code>setOffsetPivot</code>. Always 0,0,0 when script begins.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getOffsetPivot()</code>
| {{type|Vector3}}
|}

<syntaxhighlight lang="lua">
local head = models.model.root.Head

print(head:getOffsetPivot()) --> vec(0,0,0)
head:setOffsetPivot(0,4,0)
print(head:getOffsetPivot()) --> vec(0,4,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]]

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

Using <code>setPos</code>, <code>setRot</code>, <code>setScale</code>, <code>setPivot</code>, <code>setOffsetRot</code>, <code>setOffsetScale</code>, or <code>setOffsetPivot</code> will undo <code>setMatrix</code>

Using <code>getPos</code>, <code>getRot</code>, <code>getScale</code>, <code>getPivot</code>, <code>getOffsetRot</code>, <code>getOffsetScale</code>, or <code>getOffsetPivot</code> will return invalid values while <code>setMatrix</code> is in effect.

<code>getTruePos</code>, <code>getTrueRot</code>, <code>getTrueScale</code>, and <code>getTruePivot</code> are probably also affected, but nobody tested them yet.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setMatrix(matrix {{type|Matrix4}})</code>
| self {{type|ModelPart}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePos</code> ====
Returns the position after all calculations are done. This includes <code>setPos</code> and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueRot</code> ====
Returns the rotation after all calculations are done. This includes <code>setRot</code>, <code>setOffsetRot</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePos()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTrueScale</code> ====
Returns the scale after all calculations are done. This includes <code>setScale</code>, <code>setOffsetScale</code>, and the data from all playing Animations.

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTrueScale()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

==== <code>ModelPart:getTruePivot</code> ====
Returns the pivot point after all calculations are done. This includes <code>setPivot</code> and <code>setOffsetPivot</code>

This does not include ParentTypes or transformations applied from a parent part.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>getTruePivot()</code>
| self {{type|Vector3}}
|}
<syntaxhighlight lang="lua">
-- no example provided
</syntaxhighlight>

ModelPart

2024-09-26T23:23:45Z

KitCat962: /* Child Manipulation */ forgot remove

User:KitCat962

2024-09-26T23:20:48Z

KitCat962: hehehe

[[File:Kitcat avatar shades.png|thumb|199x199px]]
hehehe

File:Kitcat avatar shades.png

2024-09-26T23:18:33Z

KitCat962: hehehe

== Summary ==
hehehe

ModelPart

2024-09-26T22:59:52Z

KitCat962: /* ModelPart Methods */ @see works now

ModelPart

2024-09-26T22:50:28Z

KitCat962: /* ModelPart:copy */

ModelPart

2024-09-26T22:47:04Z

KitCat962: /* ModelPart:getParent */

ModelPart

2024-09-26T22:44:47Z

KitCat962: /* ModelPart:getType */

ModelPart

2024-09-26T22:42:39Z

KitCat962: /* ModelPart Methods */ base properties and children methods

ModelPart

2024-09-26T21:11:35Z

KitCat962: '

ModelPart

2024-09-26T21:03:44Z

KitCat962: ////

ModelPart

2024-09-26T21:00:24Z

KitCat962: MODELPARTS

User:KitCat962

2024-09-26T20:07:14Z

KitCat962: page added

hehehe