FiguraMC - User contributions [en]

Tutorials/Persisting-Variables

2025-02-23T19:29:27Z

Riftlight: Fix init ping, and add clarifying comment regarding it

Avatars can use the [[ConfigAPI]] to make their variables persist across reloads. This can be used for things such as saving settings across avatars or saving information about an avatar's state.

To begin with, create a config file. This can be done with either a script or a /figura run command; it's safest to use a script in an IDE to have syntax highlighting and avoid errors. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- All keys must be strings!
config:save("pantsColor", vec(0.5, 0.8, 0.1))
config:save("hatVisible", true)
config:save("legLength", 5)

</syntaxhighlight>Run this script by selecting the avatar it's under. Once it's run, check the existence of the <code>variablePersistence.json</code> file at <code>figura/config</code>. If it's there, that code can be deleted. Next, make some code to read the data in that file when the script is loaded. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- The "or (value)" syntax sets the default value if the config:load is nil
local hatVisible = config:load("hatVisible") or true
local legLength = config:load("legLength") or 1
local pantsColor = config:load("pantsColor") or vec(0.9, 0.1, 0.9)

function pings.updateFromConfig(hat, leg, pants)
models.model.root.Head.Hat:setVisible(hat)

models.model.root.LeftLeg:setScale(1, leg, 1)
models.model.root.RightLeg:setScale(1, leg, 1)

models.model.root.LeftLeg["Left Pants"]:setColor(pants)
models.model.root.RightLeg["Right Pants"]:setColor(pants)
end

function events.entity_init()
pings.updateFromConfig(hatVisible, legLength, pantsColor)
end
</syntaxhighlight>You'll notice we call the ping in entity_init. Since this will not be called for people who only later load the avatar, you should also sync pings every so often in a tick event. Finally, make some code that updates the config when you change values.<syntaxhighlight lang="lua">
-- The host:isHost() checks are not necessary, but they help explicitly show that their content is host-only
function pings.toggleHat(state)
models.model.root.Head.Hat:setVisible(state)
if host:isHost() then
config:save("hatVisible", state)
end
end

function pings.scaleLegs(scale)
models.model.root.LeftLeg:setScale(1, scale, 1)
models.model.root.RightLeg:setScale(1, scale, 1)
if host:isHost() then
config:save("legLength", scale)
end
end

function pings.colorPants(rgb)
models.model.root.LeftLeg["Left Pants"]:setColor(rgb)
models.model.root.RightLeg["Right Pants"]:setColor(rgb)
if host:isHost() then
config:save("pantsColor", rgb)
end
end
</syntaxhighlight>

Tutorials/Persisting-Variables

2025-01-07T01:13:43Z

Riftlight: Clarify host:isHost checks

Avatars can use the [[ConfigAPI]] to make their variables persist across reloads. This can be used for things such as saving settings across avatars or saving information about an avatar's state.

To begin with, create a config file. This can be done with either a script or a /figura run command; it's safest to use a script in an IDE to have syntax highlighting and avoid errors. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- All keys must be strings!
config:save("pantsColor", vec(0.5, 0.8, 0.1))
config:save("hatVisible", true)
config:save("legLength", 5)

</syntaxhighlight>Run this script by selecting the avatar it's under. Once it's run, check the existence of the <code>variablePersistence.json</code> file at <code>figura/config</code>. If it's there, that code can be deleted. Next, make some code to read the data in that file when the script is loaded. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- The "or (value)" syntax sets the default value if the config:load is nil
local hatVisible = config:load("hatVisible") or true
local legLength = config:load("legLength") or 1
local pantsColor = config:load("pantsColor") or vec(0.9, 0.1, 0.9)

function pings.updateFromConfig(hat, leg, pants)
models.model.root.Head.Hat:setVisible(hat)

models.model.root.LeftLeg:setScale(1, leg, 1)
models.model.root.RightLeg:setScale(1, leg, 1)

models.model.root.LeftLeg["Left Pants"]:setColor(pants)
models.model.root.RightLeg["Right Pants"]:setColor(pants)
end

pings.updateFromConfig(hatVisible, legLength, pantsColor)
</syntaxhighlight>Finally, make some code that updates the config when you change values.<syntaxhighlight lang="lua">
-- The host:isHost() checks are not necessary, but they help explicitly show that their content is host-only
function pings.toggleHat(state)
models.model.root.Head.Hat:setVisible(state)
if host:isHost() then
config:save("hatVisible", state)
end
end

function pings.scaleLegs(scale)
models.model.root.LeftLeg:setScale(1, scale, 1)
models.model.root.RightLeg:setScale(1, scale, 1)
if host:isHost() then
config:save("legLength", scale)
end
end

function pings.colorPants(rgb)
models.model.root.LeftLeg["Left Pants"]:setColor(rgb)
models.model.root.RightLeg["Right Pants"]:setColor(rgb)
if host:isHost() then
config:save("pantsColor", rgb)
end
end
</syntaxhighlight>

ConfigAPI

2024-09-29T00:17:47Z

Riftlight: Remove tutorial in favor of putting it at Tutorials/Persisting-Variables

{{Host only|kind=API}}

The <code>ConfigAPI</code> allows storing and loading data between reloads of your avatar.

ConfigAPI is available as the global <code>config</code> variable.

== Data types ==
Only some data types are supported by ConfigAPI. All other data types will be converted to {{type|nil}}. The supported data types are:
* {{type|nil}}
* {{type|boolean}}
* {{type|string}}
* {{type|number}}
* {{type|table}}
* all types of {{type|Vector}}
* all types of {{type|Matrix}}
== ConfigAPI methods ==

=== Configuration switching ===

==== setName ====
----
Also available as <code>ConfigAPI:name</code>.

Sets the name of the configuration file to read and write data to. By default, the name of the configuration file is the same as the name of the currently loaded avatar.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setName(name {{type|string}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
config:setName("my_config_file_name")
</syntaxhighlight>

==== getName ====
----
Returns the name of the active configuration file.

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

<syntaxhighlight lang="lua">
-- Print the active configuration file's name.
print(config:getName())
</syntaxhighlight>

=== Reading and writing data ===
==== load ====
----
Read a saved value from the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]]) by key and return it.
If no key is given, return all of the saved keys and values in a table.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>load(key {{type|string}})</code>
| {{type|any|?}}
|-
| <code>load()</code>
| {{type|table}}
|}

<syntaxhighlight lang="lua">
-- Print all saved values.
printTable(config:load())
-- Print one specific value.
print(config:load("my_value"))
</syntaxhighlight>

==== save ====
----
Associate a key with a value in the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]].) Only some types of values are allowed; see [[ConfigAPI#Data Types|Data Types]] for details.

If {{type|nil}} is provided as the value, then the key is removed from the file.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>save(key {{type|string}}, value {{type|any|?}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
-- Save a value to be used later.
config:save("my_value", "Figura Wiki")
</syntaxhighlight>

== Navigation ==
{{Navbox documentation}}

Tutorials/Persisting-Variables

2024-09-29T00:17:00Z

Riftlight: Move from configapi

Avatars can use the [[ConfigAPI]] to make their variables persist across reloads. This can be used for things such as saving settings across avatars or saving information about an avatar's state.

To begin with, create a config file. This can be done with either a script or a /figura run command; it's safest to use a script in an IDE to have syntax highlighting and avoid errors. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- All keys must be strings!
config:save("pantsColor", vec(0.5, 0.8, 0.1))
config:save("hatVisible", true)
config:save("legLength", 5)

</syntaxhighlight>Run this script by selecting the avatar it's under. Once it's run, check the existence of the <code>variablePersistence.json</code> file at <code>figura/config</code>. If it's there, that code can be deleted. Next, make some code to read the data in that file when the script is loaded. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- The "or (value)" syntax sets the default value if the config:load is nil
local hatVisible = config:load("hatVisible") or true
local legLength = config:load("legLength") or 1
local pantsColor = config:load("pantsColor") or vec(0.9, 0.1, 0.9)

function pings.updateFromConfig(hat, leg, pants)
models.model.root.Head.Hat:setVisible(hat)

models.model.root.LeftLeg:setScale(1, leg, 1)
models.model.root.RightLeg:setScale(1, leg, 1)

models.model.root.LeftLeg["Left Pants"]:setColor(pants)
models.model.root.RightLeg["Right Pants"]:setColor(pants)
end

pings.updateFromConfig(hatVisible, legLength, pantsColor)
</syntaxhighlight>Finally, make some code that updates the config when you change values.<syntaxhighlight lang="lua">
-- Check if host:isHost() to ensure that the config:save only runs for the host
function pings.toggleHat(state)
models.model.root.Head.Hat:setVisible(state)
if host:isHost() then
config:save("hatVisible", state)
end
end

function pings.scaleLegs(scale)
models.model.root.LeftLeg:setScale(1, scale, 1)
models.model.root.RightLeg:setScale(1, scale, 1)
if host:isHost() then
config:save("legLength", scale)
end
end

function pings.colorPants(rgb)
models.model.root.LeftLeg["Left Pants"]:setColor(rgb)
models.model.root.RightLeg["Right Pants"]:setColor(rgb)
if host:isHost() then
config:save("pantsColor", rgb)
end
end
</syntaxhighlight>

ConfigAPI

2024-09-28T21:16:24Z

Riftlight: nil checks

{{Host only|kind=API}}

The <code>ConfigAPI</code> allows storing and loading data between reloads of your avatar.

ConfigAPI is available as the global <code>config</code> variable.

== Tutorial ==

To begin with, create a config file. This can be done with either a script or a /figura run command; it's safest to use a script in an IDE to have syntax highlighting and avoid errors. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- All keys must be strings!
config:save("pantsColor", vec(0.5, 0.8, 0.1))
config:save("hatVisible", true)
config:save("legLength", 5)

</syntaxhighlight>Run this script by selecting the avatar it's under. Once it's run, check the existence of the <code>variablePersistence.json</code> file at <code>figura/config</code>. If it's there, that code can be deleted. Next, make some code to read the data in that file when the script is loaded. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- The "or (value)" syntax sets the default value if the config:load is nil
local hatVisible = config:load("hatVisible") or true
local legLength = config:load("legLength") or 1
local pantsColor = config:load("pantsColor") or vec(0.9, 0.1, 0.9)

function pings.updateFromConfig(hat, leg, pants)
models.model.root.Head.Hat:setVisible(hat)

models.model.root.LeftLeg:setScale(1, leg, 1)
models.model.root.RightLeg:setScale(1, leg, 1)

models.model.root.LeftLeg["Left Pants"]:setColor(pants)
models.model.root.RightLeg["Right Pants"]:setColor(pants)
end

pings.updateFromConfig(hatVisible, legLength, pantsColor)
</syntaxhighlight>Finally, make some code that updates the config when you change values.<syntaxhighlight lang="lua">
-- Check if host:isHost() to ensure that the config:save only runs for the host
function pings.toggleHat(state)
models.model.root.Head.Hat:setVisible(state)
if host:isHost() then
config:save("hatVisible", state)
end
end

function pings.scaleLegs(scale)
models.model.root.LeftLeg:setScale(1, scale, 1)
models.model.root.RightLeg:setScale(1, scale, 1)
if host:isHost() then
config:save("legLength", scale)
end
end

function pings.colorPants(rgb)
models.model.root.LeftLeg["Left Pants"]:setColor(rgb)
models.model.root.RightLeg["Right Pants"]:setColor(rgb)
if host:isHost() then
config:save("pantsColor", rgb)
end
end
</syntaxhighlight>

== Data types ==
Only some data types are supported by ConfigAPI. All other data types will be converted to {{type|nil}}. The supported data types are:
* {{type|nil}}
* {{type|boolean}}
* {{type|string}}
* {{type|number}}
* {{type|table}}
* all types of {{type|Vector}}
* all types of {{type|Matrix}}
== ConfigAPI methods ==

=== Configuration switching ===

==== setName ====
----
Also available as <code>ConfigAPI:name</code>.

Sets the name of the configuration file to read and write data to. By default, the name of the configuration file is the same as the name of the currently loaded avatar.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setName(name {{type|string}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
config:setName("my_config_file_name")
</syntaxhighlight>

==== getName ====
----
Returns the name of the active configuration file.

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

<syntaxhighlight lang="lua">
-- Print the active configuration file's name.
print(config:getName())
</syntaxhighlight>

=== Reading and writing data ===
==== load ====
----
Read a saved value from the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]]) by key and return it.
If no key is given, return all of the saved keys and values in a table.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>load(key {{type|string}})</code>
| {{type|any|?}}
|-
| <code>load()</code>
| {{type|table}}
|}

<syntaxhighlight lang="lua">
-- Print all saved values.
printTable(config:load())
-- Print one specific value.
print(config:load("my_value"))
</syntaxhighlight>

==== save ====
----
Associate a key with a value in the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]].) Only some types of values are allowed; see [[ConfigAPI#Data Types|Data Types]] for details.

If {{type|nil}} is provided as the value, then the key is removed from the file.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>save(key {{type|string}}, value {{type|any|?}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
-- Save a value to be used later.
config:save("my_value", "Figura Wiki")
</syntaxhighlight>

== Navigation ==
{{Navbox documentation}}

ConfigAPI

2024-09-28T21:09:21Z

Riftlight: Add silly little tutorial :3

{{Host only|kind=API}}

The <code>ConfigAPI</code> allows storing and loading data between reloads of your avatar.

ConfigAPI is available as the global <code>config</code> variable.

To begin with, create a config file. This can be done with either a script or a /figura run command; it's safest to use a script in an IDE to have syntax highlighting and avoid errors. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
-- All keys must be strings!
config:save("pantsColor", vec(0.5, 0.8, 0.1))
config:save("hatVisible", true)
config:save("legLength", 5)

</syntaxhighlight>Run this script by selecting the avatar it's under. Once it's run, check the existence of the <code>variablePersistence.json</code> file at <code>figura/config</code>. If it's there, that code can be deleted. Next, make some code to read the data in that file when the script is loaded. <syntaxhighlight lang="lua">
config:setName("variablePersistence")
local hatVisible = config:load("hatVisible")
local legLength = config:load("legLength")
local pantsColor = config:load("pantsColor")

function pings.updateFromConfig(hat, leg, pants)
models.model.root.Head.Hat:setVisible(hat)

models.model.root.LeftLeg:setScale(1, leg, 1)
models.model.root.RightLeg:setScale(1, leg, 1)

models.model.root.LeftLeg["Left Pants"]:setColor(pants)
models.model.root.RightLeg["Right Pants"]:setColor(pants)
end

pings.updateFromConfig(hatVisible, legLength, pantsColor)
</syntaxhighlight>Finally, make some code that updates the config when you change values.<syntaxhighlight lang="lua">
-- Check if host:isHost() to ensure that the config:save only runs for the host
function pings.toggleHat(state)
models.model.root.Head.Hat:setVisible(state)
if host:isHost() then
config:save("hatVisible", state)
end
end

function pings.scaleLegs(scale)
models.model.root.LeftLeg:setScale(1, scale, 1)
models.model.root.RightLeg:setScale(1, scale, 1)
if host:isHost() then
config:save("legLength", scale)
end
end

function pings.colorPants(rgb)
models.model.root.LeftLeg["Left Pants"]:setColor(rgb)
models.model.root.RightLeg["Right Pants"]:setColor(rgb)
if host:isHost() then
config:save("pantsColor", rgb)
end
end
</syntaxhighlight>
== Data Types ==
Only some data types are supported by ConfigAPI. All other data types will be converted to {{type|nil}}. The supported data types are:
* {{type|nil}}
* {{type|boolean}}
* {{type|string}}
* {{type|number}}
* {{type|table}}
* all types of {{type|Vector}}
* all types of {{type|Matrix}}
== ConfigAPI Methods ==

=== Configuration Switching ===

==== setName ====
----
Also available as <code>ConfigAPI:name</code>.

Sets the name of the configuration file to read and write data to. By default, the name of the configuration file is the same as the name of the currently loaded avatar.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>setName(name {{type|string}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
config:setName("my_config_file_name")
</syntaxhighlight>

==== getName ====
----
Returns the name of the active configuration file.

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

<syntaxhighlight lang="lua">
-- Print the active configuration file's name.
print(config:getName())
</syntaxhighlight>

=== Reading and Writing Data ===
==== load ====
----
Read a saved value from the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]]) by key and return it.
If no key is given, return all of the saved keys and values in a table.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>load(key {{type|string}})</code>
| {{type|any|?}}
|-
| <code>load()</code>
| {{type|table}}
|}

<syntaxhighlight lang="lua">
-- Print all saved values.
printTable(config:load())
-- Print one specific value.
print(config:load("my_value"))
</syntaxhighlight>

==== save ====
----
Associate a key with a value in the active configuration file (see [[ConfigAPI#ConfigAPI:setName|setName]].) Only some types of values are allowed; see [[ConfigAPI#Data Types|Data Types]] for details.

If {{type|nil}} is provided as the value, then the key is removed from the file.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>save(key {{type|string}}, value {{type|any|?}})</code>
| self {{type|ConfigAPI}}
|}

<syntaxhighlight lang="lua">
-- Save a value to be used later.
config:save("my_value", "Figura Wiki")
</syntaxhighlight>

== Navigation ==
{{Navbox documentation}}

ModelPart

2024-09-27T03:31:44Z

Riftlight: Grammar stuff :smile+1:

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

=== 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> ====
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.

=== 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

Blockbench

2024-09-27T03:22:39Z

Riftlight: Blockbench capitalization consistency & some grammar

The basics on how to use Blockbench

Proper tutorials for Blockbench can be found online. This page just explains Figura specific stuff. This page assumes you are using the Desktop version of Blockbench, not the online app. 

== Project Properties ==

This is the popup that appears when you create a Project. You can also get to this page via File->Project. <img src={require("@site/static/img/blockbench/project.png").default} width="400"></img> Figura only accepts <Emoji icon="file/bbmodel"/> bbmodels in the Generic Model format. If your format is not Generic Model, Figura will refuse to load the avatar. To convert a project, File->Convert Project. Deselect <code>Create Copy</code>, ensure format is Generic Model, and press Confirm. If the popup does not go away after pressing Confirm, close it manually. <img src={require("@site/static/img/blockbench/convert_project.png").default} width="400"></img> 

The <code>File Name</code> and <code>Model Identifier</code> fields are unused by Figura. <code>UV Mode</code> determines how Blockbench handles how UVs are positioned. Figura will handle both <code>Box UV</code> and <code>Per-face UV</code>. Its up to you which you want. UVs determine where a 2D texture is applied to a 3D model. Each face has it’s own UV coordinates which determines where on the 2D texture it will get it’s pixels from. 

<img src={require("@site/static/img/blockbench/uvmode_box.png").default} width="200" style={{"float":"right"}}></img> <code>Box UV</code> forces each face of a cube to match how vanilla does UVs. If you have ever edited your own vanilla skin before, you will recognize the pattern. While this does simplify the texturing process, it limits what you can do. Also, all textures in the model must have the same size, as what is a pixel is determined by the project’s global <code>Texture Size</code> instead of the size of the texture itself. Also, meshes cannot be used while using <code>Box UV</code> 

<div style="clear:both;"></div>

<img src={require("@site/static/img/blockbench/uvmode_perface.png").default} width="200" style={{"float":"right"}}></img>

<code>Per-face UV</code> allows full control over each face of the cube/mesh. Each face can be positioned, scaled, and rotated individually from each other. You can even set a different texture for each face, or remove a face to reduce clutter. While the pixel grid is effected by the project’s global <code>Texture Size</code>, changing the <code>Texture Size</code> has zero effect on the UVs themselves, unlike <code>Box UV</code> which will have destructive effects when changing the project

<div style="clear:both;"></div>

<code>Texture Size</code>. 

The <code>Texture Size</code> field aids with UV calculation. In rendering, UVs are a float from 0-1 representing the percentage of the texture that this point is at. A UV of (0.5,0.5) represents the center of the texture, regardless of the texture’s own size. A way of calculating this percentage is to take the pixel coordinate you want and divide it by the texture’s size. (32,16)/(64,64)=(0.5,0.25). The <code>Texture Size</code> field determines this texture size globally. Blockbench never uses the texture’s actual size, which causes issues when you have a model with textures of different sizes. Thankfully, changing it only has an effect on ModelParts that use <code>Box UV</code>, so when you need to edit ModelParts using a different sized texture, you can change this with no worries so long as you are using <code>Per-face UV</code>. 

== ModelParts ==

=== ParentTypes ===

If the name of a <Emoji icon="blockbench/group"/> group begins with a specific string, Figura will apply special effects to that group. Some examples include <code>Head</code>, <code>RightArm</code>, and <code>World</code>. These are called [[../enums/ModelPartParentTypes|ParentTypes]].

=== <code>Blank</code> Texture ===

ModelParts that use the Blockbench inbuilt <code>Blank</code> texture will not be loaded by Figura at all. If you want a Model to not have a texture and assign the texture via script, use the [[../tutorials/Avatar-Metadata|<code>ignoredTextures</code> metadata customization]]. The <code>Transparent</code> texture that can only be applied to individual faces in Per-face UV behave the same way. Figura will not load those faces.

=== Meshes ===

<Emoji icon="blockbench/mesh"/> Meshes are allowed. Nothing special with Figura. This is just here for those that need to be explicitly told Meshes work.

== Textures ==

=== Local/External Textures ===

In Blockbench, textures have 2 distinct states: Local and External. To determine the state your texture is in, Right Click a texture->Properties. An External texture will have a file path, while a Local one will not. There is one key factor for a texture to be External, and that is for the file itself to be inside the avatar’s folder. If the filepath does not lead to a file inside the avatar’s folder, Figura will load it as a Local file. <img src={require("@site/static/img/blockbench/texture_local.png").default} width="300"></img><img src={require("@site/static/img/blockbench/texture_external.png").default} width="300"></img> 

Whether a texture is Local or External will determine how Figura will load it which is important when getting a Texture in script. 

The <code>Render Mode</code> field determines how the texture will be rendered. In Blockbench, this changes nothing visually. '''Figura ignores <code>Render Mode</code>.''' The Primary Texture will always be <code>TRANSLUCENT</code> by default, and the Secondary Texture will always be <code>EMISSIVE</code> by default. 

The <code>Render Sides</code> field determines if the cube should be rendered when looking at the back of a face. '''Figura ignores <code>Render Sides</code>.''' To apply the same effect, use the <code>TRANSLUCENT_CULL</code> [[../enums/RenderTypes|RenderType]] in a script. 

=== Texture Suffix ===

In Blockbench, each cube (face) can only point to a single texture, which means that Figura needs to get creative when it wants to link multiple textures together for stuff like emissive textures. When Figura loads a texture, it looks for another texture with the same name but with a specific suffix. Then for all ModelParts in Blockbench that use the texture, Figura will link the suffixed texture to that ModelPart as well.

List of suffixes used by Figura:

* <code>_e</code>: This texture will be used as the Secondary Texture, also known as the [[../tutorials/Emissive%20Textures|Emissive Texture]], of the ModelPart. The Secondary RenderType of a ModelPart is by default <code>EMISSIVE</code>, but can be changed in script.
* <code>_n</code>: This texture will be used as the [https://en.wikipedia.org/wiki/Normal_mapping Normal Texture]. Do not confuse this with the Primary Texture. “Normal” means something very specific in modeling. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.
* <code>_s</code>: This texture will be used as the [https://en.wikipedia.org/wiki/Specularity Specular Texture]. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.

An example is the <Emoji icon="blockbench/group"/> <code>Head</code>, <Emoji icon="file/texture"/> <code>skin</code>, and <Emoji icon="file/texture"/> <code>skin_e</code>. When the <Emoji icon="blockbench/group"/> <code>Head</code> uses the texture <Emoji icon="file/texture"/> <code>skin</code>, when the Avatar is loaded, <Emoji icon="file/texture"/> <code>skin_e</code> is used as the Secondary Texture, ie the Emissive Texture. <img src={require("@site/static/img/blockbench/settexture.png").default} width="300"></img> 

For a texture to have the same name, they must both be either [[#localexternal-textures|Local or External]], and should they be external, they must be in the same folder. Otherwise, they will not have the same name internally. For textures with file extensions, the suffix goes before the extension. <Emoji icon="file/texture"/> <code>skin_e.png</code> 

== Animations ==

=== Animation Properties ===

This popup appears when you create an animation. To get back to this popup, Right Click an Animation->Properties. 

<img src={require("@site/static/img/blockbench/animation_properties.png").default} width="500"></img> 

; Name
: This is the animation’s name. It is very important that you change this to something shorter. The entire textbox is the animation’s name, so unless you want to refer to this animation in lua with <code>animations.player["animation.model.new"]</code>, change the name. An animation named just <code>"new"</code> is indexed via <code>animations.player.new</code>. Much nicer, right?

; Loop Mode
: This controls what happens when the animation reaches the end. There are 3 valid loop modes:
: {{tagged|Play Once|The animation will stop immediately at the end. Note that badly-made animations may have a visible jump to their original position in this mode.}}
: {{tagged|Hold On Last Frame|The animation will hold the values from its last frame after ending. Note that while an animation is holding, it is still considered playing, so calling <code>:play()</code> again will do nothing.}}
: {{tagged|Loop|When the animation reaches its end, it will jump to the beginning. Note that the start and end frames should be the same in this mode, as there won't be an in-between animation.}}

; Override
: If this is enabled, Mimic-type [[Enums/ParentTypes|Enums/ParentTypes]] won't apply their rotations while this animation is playing. Note that keyframes must be present on the specific channel for override to apply! For example, putting a keyframe on Head's rotation won't apply override to its position or scale, Body, or even other Heads.

; Snapping
: This sets what unit of time Blockbench will set animations to. Holding Ctrl allows you to bypass this. Figura ignores this value.

; Anim Time Update
: ''Default value: 0''
: This allows you to set the time Figura starts playing the animation at. For example, setting this to 2 skips the first 2 seconds of the animation. This lets you add keyframes before the animation to help with interpolations.
: {{tagged|Trivia|In Molang (and, therefore, Blockbench), this sets the animation's time ''every tick'' to a Molang expression. In Figura, you can achieve the equivalent by calling <code>setTime</code> in a script.}}

; Blend Weight
: Every keyframe value in the animation is multiplied by this value. This isn't very useful itself, but can be used by scripts (for example, [[GSAnimBlend]]) to transition into or out of animations.

; Start Delay
: ''Default value: 0''
: This delays the animation's start time by the given amount.

; Loop Delay
: ''Default value: 0''
: This sets the amount of time the animation will pause at the end before it loops again. This is only relevant in Loop mode.

=== Keyframe Expressions ===

While Blockbench supports Molang, '''Figura does not'''. To remedy this, Figura allows writing lua code into keyframe fields. 

Figura provides data for the keyframe expression, which is accessible via the <code>...</code> variable.

It has 2 pieces of data, the keyframe time, and the Animation object of the animation itself. Keyframe time is measured in percentage, not seconds. So, assuming a Step interpolation keyframe, <code>0</code> is at the time at the keyframe itself and <code>1</code> is at the next keyframe. Keyframe time is only useful when the keyframe uses Step interpolation. When using other interpolation types, the expression will execute before it has reached the keyframe itself to interpolate. While this happens, it will give the Keyframe time of the previous keyframe and go back to zero once it reaches itself.

They can be extracted via the following line:

<syntaxhighlight lang="lua">local time, anim = ...</syntaxhighlight>

Keyframe Expressions accept 2 different formats:

* A single lua expression that evaluates to a number
* A lua script that <code>returns</code> a number

<code>math.sin(world.getTime())</code> is a single lua expression, so it is a valid Keyframe Expression. However, <code>local _, anim=... math.sin(anim:getTime())</code> is not a single lua expression and will need to have an explicit return value:

<syntaxhighlight lang="lua">local _, anim = ...

return math.sin(anim:getTime())</syntaxhighlight>

Alternatively, you can rewrite it as a single lua expression: <code>math.sin({...}[2]:getTime())</code> This deconstructs the <code>...</code> varargs into a table and grabs the second value.

=== Instruction Keyframes ===

Instruction Keyframes run lua code when the Animation reaches that keyframe. This can be used to play sounds, spawn particles, literally anything. Remember that Lua code is what goes in this spot, not Molang. You can access Instruction Keyframes via the Magic Wand icon. An Effects timeline should appear along with the other ModelPart timelines.

=== Animation Features That Figura Does Not Care About ===

Below are features provided by Blockbench Animations that figura does not use when loading the bbmodel. 

'''Variable Placeholders''' <img src={require("@site/static/img/blockbench/animation_variableplaceholders.png").default} width="200"></img> This is completely ignored by Figura. 

'''Inverse Kinematics''' Don’t bother. Not a thing in Figura.

'''Global Rotation''' There is a toggle for Global Rotation next to the Rotation timeline for ModelParts. Figura does not obey this, so keep it disabled. 

'''Sound Keyframes''' Figura does not read these. Use [[#instruction-keyframes|Instruction Keyframes]]. 

'''Particle Keyframes''' Figura does not read these. Use [[#instruction-keyframes|Instruction Keyframes]].