FiguraMC - User contributions [en]

Blockbench

2024-11-02T23:47:17Z

PoolloverNathan: /* Animation Properties */ PoolloverNathan vs MediaWiki — may the most insane win

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.<br/>

== Project Properties ==

This is the popup that appears when you create a Project. You can also get to this page via File->Project.<br/> <img src={require("@site/static/img/blockbench/project.png").default} width="400"></img><br/> 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.<br/> <img src={require("@site/static/img/blockbench/convert_project.png").default} width="400"></img><br/>

The <code>File Name</code> and <code>Model Identifier</code> fields are unused by Figura.<br/> <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.<br/><br/>

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

<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>.<br/>

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>.<br/>

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

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

The <code>Render Mode</code> field determines how the texture will be rendered. In Blockbench, this changes nothing visually.<br/> '''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.<br/>

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

=== 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.<br/> 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]. <b>Do not confuse this with the Primary Texture</b>. “Normal” means something very specific in modeling. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. <b><i>This suffix currently does not function</i></b>.
* <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. <b><i>This suffix currently does not function</i></b>.

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.<br/> <img src={require("@site/static/img/blockbench/settexture.png").default} width="300"></img><br/>

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.<br/> For textures with file extensions, the suffix goes before the extension. <Emoji icon="file/texture"/> <code>skin_e.png</code><br/>

== Animations ==

=== Animation Properties ===

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

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

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

<div style="margin-left: var(--space-lg); margin-top: -1em">
; 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.
; 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.
; 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.
</div>

; 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'''.<br/> To remedy this, Figura allows writing lua code into keyframe fields.<br/>

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.<br/> 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.<br/>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.<br/> 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><br/> 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.<br/> 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.<br/>

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

'''Inverse Kinematics'''<br/> Don’t bother. Not a thing in Figura.

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

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

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

Template:D

2024-11-02T23:29:21Z

PoolloverNathan: template data

<includeonly><dt>{{{1}}}</dt><dd>{{{2}}}</dd></includeonly><noinclude>{{lowercase}}A <code><dt></code> and <code><dd></code> pair for nested or otherwise manually-created definition lists.
<templatedata>
{
"params": {
"1": {
"label": "term",
"description": "The term or key of the definition list item.",
"type": "content",
"required": true
},
"2": {
"label": "definition",
"description": "The definition or value for the list item.",
"required": true
}
},
"paramOrder": [
"1",
"2"
]
}
</templatedata></noinclude>

Template:D

2024-11-02T22:57:46Z

PoolloverNathan: Created page with "<includeonly><dt>{{{1}}}</dt><dd>{{{2}}}</dd></includeonly><noinclude>{{lowercase}}A <code><dt></code> and <code><dd></code> pair for nested or otherwise manually-created definition lists. <templatedata> { "params": { "1": {}, "2": {} } } </templatedata></noinclude>"

Blockbench

2024-11-02T22:56:35Z

PoolloverNathan: /* Animation Properties */ properly nested definition lists

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.<br/>

== Project Properties ==

This is the popup that appears when you create a Project. You can also get to this page via File->Project.<br/> <img src={require("@site/static/img/blockbench/project.png").default} width="400"></img><br/> 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.<br/> <img src={require("@site/static/img/blockbench/convert_project.png").default} width="400"></img><br/>

The <code>File Name</code> and <code>Model Identifier</code> fields are unused by Figura.<br/> <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.<br/><br/>

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

<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>.<br/>

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>.<br/>

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

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

The <code>Render Mode</code> field determines how the texture will be rendered. In Blockbench, this changes nothing visually.<br/> '''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.<br/>

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

=== 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.<br/> 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]. <b>Do not confuse this with the Primary Texture</b>. “Normal” means something very specific in modeling. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. <b><i>This suffix currently does not function</i></b>.
* <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. <b><i>This suffix currently does not function</i></b>.

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.<br/> <img src={require("@site/static/img/blockbench/settexture.png").default} width="300"></img><br/>

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.<br/> For textures with file extensions, the suffix goes before the extension. <Emoji icon="file/texture"/> <code>skin_e.png</code><br/>

== Animations ==

=== Animation Properties ===

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

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

; 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:
: <dl>
: {{d|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.}}
: {{d|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.}}
: {{d|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.}}
: </dl>

; 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'''.<br/> To remedy this, Figura allows writing lua code into keyframe fields.<br/>

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.<br/> 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.<br/>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.<br/> 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><br/> 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.<br/> 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.<br/>

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

'''Inverse Kinematics'''<br/> Don’t bother. Not a thing in Figura.

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

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

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

Template:Nest

2024-11-02T22:51:03Z

PoolloverNathan: Created page with "<includeonly>{{{1}}}</includeonly><noinclude>Returns the argument unmodified, to fix parsing issues when nesting certain types of elements.</noinclude>"

<includeonly>{{{1}}}</includeonly><noinclude>Returns the argument unmodified, to fix parsing issues when nesting certain types of elements.</noinclude>

Template:Note

2024-10-09T21:55:20Z

PoolloverNathan: get template data'd

<div style="border-left: 6px solid {{{color|#5ea5ff}}}; border-radius: 6px; padding-left: 7.5px">
<div style="color: {{{color|#5ea5ff}}}">{{{icon|ⓘ}}} {{{tag|Note}}}</div>
{{{1}}}
</div><noinclude>
<templatedata>
{
"params": {
"1": {
"type": "content",
"required": true,
"label": "content",
"description": "The text displayed in the note.",
"example": "You should be aware of this."
},
"color": {
"description": "The color to use for the line and tag.",
"type": "string",
"default": "#5ea5ff"
},
"icon": {
"description": "The symbol to display in the header.",
"example": "⊗",
"type": "string",
"default": "ⓘ"
},
"tag": {
"description": "The type of note to display.",
"example": "Warning",
"type": "string",
"default": "Note"
}
},
"description": "Displays an indented note.",
"paramOrder": [
"1",
"icon",
"tag",
"color"
],
"format": "block"
}
</templatedata>
</noinclude>

FiguraMC:Contributing/Style Guide/TypeExample

2024-10-09T21:50:20Z

PoolloverNathan: link to templates

= Page title = 
(Don't add an additional level-1 heading for the page title.)

If necessary, use <code><nowiki>{{</nowiki>[[Template:host only|host only]]<nowiki>}}</nowiki></code>, <code><nowiki>{{</nowiki>[[Template:Notice|Notice]]|...<nowiki>}}</nowiki></code>, or <code><nowiki>{{</nowiki>[[Template:Notice/Warning|Notice/Warning]]|...<nowiki>}}</nowiki></code>. For example:

{{host only|nocat=yes}}

(Important information about the type...)

== Methods ==
{| class="wikitable"
|-
! Method
! Brief description
|-
| [[#methodName|methodName]]
| description
|-
| [[#secondCategoryMethod|secondCategoryMethod]]
| Returns the position of the ModelPart as a {{type|Vector3}}
|}
== Fields ==
{| class="wikitable"
|-
! Field
! Description
! Type
|-
| field
| Brief description
| {{type|type}}
|-
| TICK
| Runs every tick the player is rendered
| {{type|Event}}
|}

== Methods ==
=== Category ===
Brief description
==== methodName ====
----
Description

Overloads:
{| class="wikitable"
|-
! Arguments
! Return Type
|-
| pos {{Type|Vector3}}, name {{Type|string?}}
| {{Type|nil}}
|-
| x {{Type|number}}, y {{Type|number}}, z {{Type|number}}, name {{Type|string?}}
| {{Type|nil}}
|}
Description
<syntaxHighlight lang="lua">
-- Example Code
</syntaxHighlight>
=== Category ===
Brief description
==== secondCategoryMethod ====
----
Description

Overloads:
{| class="wikitable"
|-
! Arguments
! Return Type
|-
| rotation {{Type|Vector3}}
| {{Type|nil}}
|-
| x {{Type|number}}, y {{Type|number}}, z {{Type|number}}
| {{Type|nil}}
|}
<syntaxHighlight lang="lua">
-- Example Code
</syntaxHighlight>

FiguraMC:Contributing/Style Guide

2024-10-09T21:44:38Z

PoolloverNathan: bunny, that was a subtle suggestion

{{Stub}}
== General Guidelines ==
* Avoid writing in the first/second person
** Only write in the second person in tutorials
** Avoid using [[wikipedia:English personal pronouns|personal pronouns]]
** See [[wikipedia:Grammatical person|Grammatical person]]
* Properly capitalize wikilinks where it makes sense

== Types ==
When creating a type page, please use the following layout:

{{VeryObviouslyTranscluded/2|FiguraMC:Contributing/Style Guide/TypeExample|TypeExample}}

Each method in the table should link to the section more in-depth explaining it.

LogTable

2024-10-05T20:38:16Z

PoolloverNathan: see previous edit

#REDIRECT [[PrintTable]]

Log

2024-10-05T20:35:28Z

PoolloverNathan: ensure people attempting to access fallacious printing methods are redirected to the true form of printing

#REDIRECT [[print]]

Community Resources

2024-10-05T20:30:17Z

PoolloverNathan: /* 4p5.nz 🛡️ */ unfuck sidebar

{{Notice/Warning
|content='''This page is heavily unfinished.'''<br>
Please wait before referring other people to this page. If you're able to, please [[FiguraMC:Contributing|contribute]]!
}}
{{Notice
|content='''Some of the resources listed here are not officially endorsed by FiguraMC.'''<br>
* Resources affiliated with FiguraMC will be marked as such with a ⭐ icon.
}}
= Documentation =
==='''[https://applejuiceyy.github.io/figs/ Figs]'''===
'''Figs''' is an online documentation browser for Figura, making using Figura's built-in documentation easier to use.
==='''[https://wiki.figuramc.org Figura Wiki]''' (YOU ARE HERE) ⭐===
The '''Figura Wiki''' is an online wiki that aims to document Figura, its scripting language, modeling, etc.
== Lua Documenation ==
==='''[https://manuel-3.github.io/lua-quickstart Lua Quickstart Guide]'''===
'''Manuel's Lua Quickstart Guide''' is a quick, online tutorial guiding users through the basics of Lua syntax.
==='''[http://lua.org/manual/5.1 Lua 5.1 Manual]'''===
The '''Lua Manual''' is a long document describing the ins and outs of vanilla Lua. Although some of it will not apply to Figura Lua, it's still very useful for learning about the standard libraries.
== Tutorials ==
==='''[https://www.youtube.com/playlist?list=PLNz7v2g2SFA8lOQUDS4z4-gIDLi_dWAhl Chloe's Video Tutorial Series]'''===
'''Chloe's Tutorial Series''' is a video series on YouTube that acts as a way for new users to get used to the mod. The series covers everything from modeling and modifying <code>avatar.json</code> files to scripting.
= Tools =
==='''[https://github.com/GrandpaScout/FiguraRewriteVSDocs GS' Figura VSCode Documentation]'''===
'''GrandpaScout's Figura VSCode Documentation''' is an addon for Visual Studio Code (along with Code OSS and VSCodium) that adds Figura's documentation and snippets to [https://marketplace.visualstudio.com/items?itemName=sumneko.lua sumneko's Lua Language Server plugin].
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/GrandpaScout/FiguraRewriteVSDocs/wiki Install Guide]
</div>
</div>
==='''[https://github.com/KitCat962/figura-format-bbplugin Katt's Figura Blockbench Extension]'''===
The '''Figura Blockbench Extension''' adds a new model format to Blockbench, the Figura Model format. It extends the base Generic Model format by adding tools to make the avatar creation process easier, lifting restrictions to the Generic Model format that Figura supports, and removing features Figura doesn't.
= Assets (Scripts, Libraries, APIs) =
{{Notice
|content='''Some assets only exist within the [https://discord.figuramc.org FiguraMC Discord].'''<br>
* Assets that link to the FiguraMC Discord will be marked with a 💬 icon.
}}
== Animation Helpers ==
==='''[https://github.com/GrandpaScout/GSAnimBlend GSAnimBlend]'''===
'''GSAnimBlend''' is a script that automatically adds blends to the start and end of animations.
==='''[https://github.com/JimmyHelp/JimmyAnims Jimmy's Animation Handler]'''===
'''JimmyAnim''' (full name Jimmy's Animation Helper) is a library that plays specific Blockbench animations based on the player's current action.
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://jimmyhelp.notion.site/JimmyAnims-79adfdca2fe04f9c9ede5e0bfd898b6a Documentation]
* [https://github.com/JimmyHelp/JimmyAnims/blob/main/JimmyExample.lua Example Usage]
</div>
</div>
== World Interactions==
==='''[https://discord.com/channels/1129805506354085959/1132467393050968214/1132467393050968214 Origins API]''' 💬===
Katt's '''Origins API''' is an API that uses the player's NBT data to get information about the player's [https://modrinth.com/mod/origins Origin].
==Visual Elements==
==='''[https://github.com/Manuel-3/figura-scripts/tree/main/src/confetti Confetti]'''===
'''Confetti''' is a library that allows users to add custom particles, either sprite or modelpart, to their avatars
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/readme.md Documentation]
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/example.zip Example Avatar]
</div>
</div>
==='''[https://discord.com/channels/1129805506354085959/1137506926742216835 KattArmor]''' 💬===
'''KattArmor''' (sometimes called Katt Armor API/Library) is a library that allows users to edit their avatar's armor, whether by adding pivots using a script or by using unique models and textures.

<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1155212562980425818 How-To Guide]
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1262160359905562705 Example Avatars]
</div>
</div>
= Community =
==='''[https://discord.figuramc.org FiguraMC Discord]''' ⭐===
The '''FiguraMC Discord Server''' is the central place for everything Figura, including help and support for the mod, avatar showcasing, and more. You'll also need to join this server to request whitelist to the FiguraSMP.
== Minecraft Servers ==
{{Notice
|content='''Some servers listed below are whitelisted.'''<br>
* Servers that have a public whitelist application process will be marked with a 🔒 icon.
* Servers that are invite-only will be marked with a 🛡️ icon.
}}
=== Figura Plaza ⭐ ===
'''IP: <span style="user-select: all">plaza.figuramc.org</span>'''

The '''Figura Plaza''' is an official lobby-like server where players can join, hang out with other Figura users, make avatars in company, play games, and occasionally attend events. The server does not have any survival gameplay, and disables PvP by default. The server also provides a selection of free temporary items to use when testing avatars.

=== Figura SMP ⭐🔒 ===
'''IP: <span style="user-select: all">vanilla.figuramc.org</span>''' • '''Version: 1.21'''

The '''Figura SMP''' (also referred to as Vanilla SMP) is an official survial server that stays close to the base game, plus a few server-side mods for quality-of-life purposes. You are perfectly able to join this server without any mods, and even on a vanilla client. You can read the server rules in [https://discord.com/channels/1129805506354085959/1130186794873405510 #info] and get whitelisted by putting your name in [https://discord.com/channels/1129805506354085959/1130187119680311470 #whitelist]. note that both of these channel links require you to be in [https://discord.figuramc.org the official Discord server for Figura].

==== Modded SMP ====
'''IP: <span style="user-select: none">[TBD]</span>''' • '''Version: 1.20.1-fabric''' • '''Modpack: <span style="user-select: none">[TBD]</span>'''

The '''Modded SMP''' is a seasonal modpack server adjacent to Figura SMP, each season coming with its own theme. '''Currently offline.''' The next season is themed after a nuclear apocalypse and is set for release Soon™. Getting whitelisted for Figura SMP also makes you whitelisted for this server (and vice versa).

=== 4p5.nz 🛡️ ===
'''IP: <span style="user-select: all">4p5.nz</span>''' • '''Version: 1.21'''

'''4p5.nz''' is an invite-only creative/operator server where players have free reign over the world around them.

Community Resources

2024-10-05T20:28:42Z

PoolloverNathan: /* Minecraft Servers */ minor spelling mistake

{{Notice/Warning
|content='''This page is heavily unfinished.'''<br>
Please wait before referring other people to this page. If you're able to, please [[FiguraMC:Contributing|contribute]]!
}}
{{Notice
|content='''Some of the resources listed here are not officially endorsed by FiguraMC.'''<br>
* Resources affiliated with FiguraMC will be marked as such with a ⭐ icon.
}}
= Documentation =
==='''[https://applejuiceyy.github.io/figs/ Figs]'''===
'''Figs''' is an online documentation browser for Figura, making using Figura's built-in documentation easier to use.
==='''[https://wiki.figuramc.org Figura Wiki]''' (YOU ARE HERE) ⭐===
The '''Figura Wiki''' is an online wiki that aims to document Figura, its scripting language, modeling, etc.
== Lua Documenation ==
==='''[https://manuel-3.github.io/lua-quickstart Lua Quickstart Guide]'''===
'''Manuel's Lua Quickstart Guide''' is a quick, online tutorial guiding users through the basics of Lua syntax.
==='''[http://lua.org/manual/5.1 Lua 5.1 Manual]'''===
The '''Lua Manual''' is a long document describing the ins and outs of vanilla Lua. Although some of it will not apply to Figura Lua, it's still very useful for learning about the standard libraries.
== Tutorials ==
==='''[https://www.youtube.com/playlist?list=PLNz7v2g2SFA8lOQUDS4z4-gIDLi_dWAhl Chloe's Video Tutorial Series]'''===
'''Chloe's Tutorial Series''' is a video series on YouTube that acts as a way for new users to get used to the mod. The series covers everything from modeling and modifying <code>avatar.json</code> files to scripting.
= Tools =
==='''[https://github.com/GrandpaScout/FiguraRewriteVSDocs GS' Figura VSCode Documentation]'''===
'''GrandpaScout's Figura VSCode Documentation''' is an addon for Visual Studio Code (along with Code OSS and VSCodium) that adds Figura's documentation and snippets to [https://marketplace.visualstudio.com/items?itemName=sumneko.lua sumneko's Lua Language Server plugin].
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/GrandpaScout/FiguraRewriteVSDocs/wiki Install Guide]
</div>
</div>
==='''[https://github.com/KitCat962/figura-format-bbplugin Katt's Figura Blockbench Extension]'''===
The '''Figura Blockbench Extension''' adds a new model format to Blockbench, the Figura Model format. It extends the base Generic Model format by adding tools to make the avatar creation process easier, lifting restrictions to the Generic Model format that Figura supports, and removing features Figura doesn't.
= Assets (Scripts, Libraries, APIs) =
{{Notice
|content='''Some assets only exist within the [https://discord.figuramc.org FiguraMC Discord].'''<br>
* Assets that link to the FiguraMC Discord will be marked with a 💬 icon.
}}
== Animation Helpers ==
==='''[https://github.com/GrandpaScout/GSAnimBlend GSAnimBlend]'''===
'''GSAnimBlend''' is a script that automatically adds blends to the start and end of animations.
==='''[https://github.com/JimmyHelp/JimmyAnims Jimmy's Animation Handler]'''===
'''JimmyAnim''' (full name Jimmy's Animation Helper) is a library that plays specific Blockbench animations based on the player's current action.
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://jimmyhelp.notion.site/JimmyAnims-79adfdca2fe04f9c9ede5e0bfd898b6a Documentation]
* [https://github.com/JimmyHelp/JimmyAnims/blob/main/JimmyExample.lua Example Usage]
</div>
</div>
== World Interactions==
==='''[https://discord.com/channels/1129805506354085959/1132467393050968214/1132467393050968214 Origins API]''' 💬===
Katt's '''Origins API''' is an API that uses the player's NBT data to get information about the player's [https://modrinth.com/mod/origins Origin].
==Visual Elements==
==='''[https://github.com/Manuel-3/figura-scripts/tree/main/src/confetti Confetti]'''===
'''Confetti''' is a library that allows users to add custom particles, either sprite or modelpart, to their avatars
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/readme.md Documentation]
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/example.zip Example Avatar]
</div>
</div>
==='''[https://discord.com/channels/1129805506354085959/1137506926742216835 KattArmor]''' 💬===
'''KattArmor''' (sometimes called Katt Armor API/Library) is a library that allows users to edit their avatar's armor, whether by adding pivots using a script or by using unique models and textures.

<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1155212562980425818 How-To Guide]
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1262160359905562705 Example Avatars]
</div>
</div>
= Community =
==='''[https://discord.figuramc.org FiguraMC Discord]''' ⭐===
The '''FiguraMC Discord Server''' is the central place for everything Figura, including help and support for the mod, avatar showcasing, and more. You'll also need to join this server to request whitelist to the FiguraSMP.
== Minecraft Servers ==
{{Notice
|content='''Some servers listed below are whitelisted.'''<br>
* Servers that have a public whitelist application process will be marked with a 🔒 icon.
* Servers that are invite-only will be marked with a 🛡️ icon.
}}
=== Figura Plaza ⭐ ===
'''IP: <span style="user-select: all">plaza.figuramc.org</span>'''

The '''Figura Plaza''' is an official lobby-like server where players can join, hang out with other Figura users, make avatars in company, play games, and occasionally attend events. The server does not have any survival gameplay, and disables PvP by default. The server also provides a selection of free temporary items to use when testing avatars.

=== Figura SMP ⭐🔒 ===
'''IP: <span style="user-select: all">vanilla.figuramc.org</span>''' • '''Version: 1.21'''

The '''Figura SMP''' (also referred to as Vanilla SMP) is an official survial server that stays close to the base game, plus a few server-side mods for quality-of-life purposes. You are perfectly able to join this server without any mods, and even on a vanilla client. You can read the server rules in [https://discord.com/channels/1129805506354085959/1130186794873405510 #info] and get whitelisted by putting your name in [https://discord.com/channels/1129805506354085959/1130187119680311470 #whitelist]. note that both of these channel links require you to be in [https://discord.figuramc.org the official Discord server for Figura].

==== Modded SMP ====
'''IP: <span style="user-select: none">[TBD]</span>''' • '''Version: 1.20.1-fabric''' • '''Modpack: <span style="user-select: none">[TBD]</span>'''

The '''Modded SMP''' is a seasonal modpack server adjacent to Figura SMP, each season coming with its own theme. '''Currently offline.''' The next season is themed after a nuclear apocalypse and is set for release Soon™. Getting whitelisted for Figura SMP also makes you whitelisted for this server (and vice versa).

=== '''4p5.nz''' 🛡️ ===
'''IP: <span style="user-select: all">4p5.nz</span>''' • '''Version: 1.21'''

'''4p5.nz''' is an invite-only creative/operator server where players have free reign over the world around them.

Community Resources

2024-10-05T20:25:46Z

PoolloverNathan: /* Minecraft Servers */ reformatting

{{Notice/Warning
|content='''This page is heavily unfinished.'''<br>
Please wait before referring other people to this page. If you're able to, please [[FiguraMC:Contributing|contribute]]!
}}
{{Notice
|content='''Some of the resources listed here are not officially endorsed by FiguraMC.'''<br>
* Resources affiliated with FiguraMC will be marked as such with a ⭐ icon.
}}
= Documentation =
==='''[https://applejuiceyy.github.io/figs/ Figs]'''===
'''Figs''' is an online documentation browser for Figura, making using Figura's built-in documentation easier to use.
==='''[https://wiki.figuramc.org Figura Wiki]''' (YOU ARE HERE) ⭐===
The '''Figura Wiki''' is an online wiki that aims to document Figura, its scripting language, modeling, etc.
== Lua Documenation ==
==='''[https://manuel-3.github.io/lua-quickstart Lua Quickstart Guide]'''===
'''Manuel's Lua Quickstart Guide''' is a quick, online tutorial guiding users through the basics of Lua syntax.
==='''[http://lua.org/manual/5.1 Lua 5.1 Manual]'''===
The '''Lua Manual''' is a long document describing the ins and outs of vanilla Lua. Although some of it will not apply to Figura Lua, it's still very useful for learning about the standard libraries.
== Tutorials ==
==='''[https://www.youtube.com/playlist?list=PLNz7v2g2SFA8lOQUDS4z4-gIDLi_dWAhl Chloe's Video Tutorial Series]'''===
'''Chloe's Tutorial Series''' is a video series on YouTube that acts as a way for new users to get used to the mod. The series covers everything from modeling and modifying <code>avatar.json</code> files to scripting.
= Tools =
==='''[https://github.com/GrandpaScout/FiguraRewriteVSDocs GS' Figura VSCode Documentation]'''===
'''GrandpaScout's Figura VSCode Documentation''' is an addon for Visual Studio Code (along with Code OSS and VSCodium) that adds Figura's documentation and snippets to [https://marketplace.visualstudio.com/items?itemName=sumneko.lua sumneko's Lua Language Server plugin].
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/GrandpaScout/FiguraRewriteVSDocs/wiki Install Guide]
</div>
</div>
==='''[https://github.com/KitCat962/figura-format-bbplugin Katt's Figura Blockbench Extension]'''===
The '''Figura Blockbench Extension''' adds a new model format to Blockbench, the Figura Model format. It extends the base Generic Model format by adding tools to make the avatar creation process easier, lifting restrictions to the Generic Model format that Figura supports, and removing features Figura doesn't.
= Assets (Scripts, Libraries, APIs) =
{{Notice
|content='''Some assets only exist within the [https://discord.figuramc.org FiguraMC Discord].'''<br>
* Assets that link to the FiguraMC Discord will be marked with a 💬 icon.
}}
== Animation Helpers ==
==='''[https://github.com/GrandpaScout/GSAnimBlend GSAnimBlend]'''===
'''GSAnimBlend''' is a script that automatically adds blends to the start and end of animations.
==='''[https://github.com/JimmyHelp/JimmyAnims Jimmy's Animation Handler]'''===
'''JimmyAnim''' (full name Jimmy's Animation Helper) is a library that plays specific Blockbench animations based on the player's current action.
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://jimmyhelp.notion.site/JimmyAnims-79adfdca2fe04f9c9ede5e0bfd898b6a Documentation]
* [https://github.com/JimmyHelp/JimmyAnims/blob/main/JimmyExample.lua Example Usage]
</div>
</div>
==Visual Elements==
==='''[https://github.com/Manuel-3/figura-scripts/tree/main/src/confetti Confetti]'''===
'''Confetti''' is a library that allows users to add custom particles, either sprite or modelpart, to their avatars
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/readme.md Documentation]
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/example.zip Example Avatar]
</div>
</div>
==='''[https://discord.com/channels/1129805506354085959/1137506926742216835 KattArmor]''' 💬===
'''KattArmor''' (sometimes called Katt Armor API/Library) is a library that allows users to edit their avatar's armor, whether by adding pivots using a script or by using unique models and textures.

<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1155212562980425818 How-To Guide]
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1262160359905562705 Example Avatars]
</div>
</div>
= Community =
==='''[https://discord.figuramc.org FiguraMC Discord]''' ⭐===
The '''FiguraMC Discord Server''' is the central place for everything Figura, including help and support for the mod, avatar showcasing, and more. You'll also need to join this server to request whitelist to the FiguraSMP.
== Minecraft Servers ==
{{Notice
|content='''Some servers listed below are whitelisted.'''<br>
* Servers that have a public whitelist application process will be marked with a 🔒 icon.
* Servers that are invite-only will be marked with a 🛡️ icon.
}}
=== Figura Plaza ⭐ ===
'''IP: <span style="user-select: all">plaza.figuramc.org</span>'''

The '''Figura Plaza''' is an official lobby-like server where players can join, hang out with other Figura users, make avatars in company, play games, and occasionally attend events. The server does not have any survival gameplay, and disables PvP by default. The server also provides a selection of free temporary items to use when testing avatars.

=== Figura SMP ⭐🔒 ===
'''IP: <span style="user-select: all">vanilla.figuramc.org</span>''' • '''Version: 1.21'''

The '''Figura SMP''' (also referred to as Vanilla SMP) is an official survial server that stays close to the base game, plus a few server-side mods for quality-of-life purposes. You are perfectly able to join this server without any mods, and even on a vanilla client. You can read the server rules in [https://discord.com/channels/1129805506354085959/1130186794873405510 #info] and get whitelisted by putting your name in <sub>Subscript text</sub>[https://discord.com/channels/1129805506354085959/1130187119680311470 #whitelist]. note that both of these channel links require you to be in [https://discord.figuramc.org the official Discord server for Figura].

==== Modded SMP ====
'''IP: <span style="user-select: none">[TBD]</span>''' • '''Version: 1.20.1-fabric''' • '''Modpack: <span style="user-select: none">[TBD]</span>'''

The '''Modded SMP''' is a seasonal modpack server adjacent to Figura SMP, each season coming with its own theme. '''Currently offline.''' The next season is themed after a nuclear apocalypse and is set for release Soon™. Getting whitelisted for Figura SMP also makes you whitelisted for this server (and vice versa).

=== '''4p5.nz''' 🛡️ ===
'''IP: <span style="user-select: all">4p5.nz</span>''' • '''Version: 1.21'''

'''4p5.nz''' is an invite-only creative/operator server where players have free reign over the world around them.

Community Resources

2024-10-05T20:15:45Z

PoolloverNathan: /* FiguraSMP ⭐🔒 */ migrate server ip, elaborate on whitelist and msmp

{{Notice/Warning
|content='''This page is heavily unfinished.'''<br>
Please wait before referring other people to this page. If you're able to, please [[FiguraMC:Contributing|contribute]]!
}}
{{Notice
|content='''Some of the resources listed here are not officially endorsed by FiguraMC.'''<br>
* Resources affiliated with FiguraMC will be marked as such with a ⭐ icon.
}}
= Documentation =
==='''[https://applejuiceyy.github.io/figs/ Figs]'''===
'''Figs''' is an online documentation browser for Figura, making using Figura's built-in documentation easier to use.
==='''[https://wiki.figuramc.org Figura Wiki]''' (YOU ARE HERE) ⭐===
The '''Figura Wiki''' is an online wiki that aims to document Figura, its scripting language, modeling, etc.
== Lua Documenation ==
==='''[https://manuel-3.github.io/lua-quickstart Lua Quickstart Guide]'''===
'''Manuel's Lua Quickstart Guide''' is a quick, online tutorial guiding users through the basics of Lua syntax.
==='''[http://lua.org/manual/5.1 Lua 5.1 Manual]'''===
The '''Lua Manual''' is a long document describing the ins and outs of vanilla Lua. Although some of it will not apply to Figura Lua, it's still very useful for learning about the standard libraries.
== Tutorials ==
==='''[https://www.youtube.com/playlist?list=PLNz7v2g2SFA8lOQUDS4z4-gIDLi_dWAhl Chloe's Video Tutorial Series]'''===
'''Chloe's Tutorial Series''' is a video series on YouTube that acts as a way for new users to get used to the mod. The series covers everything from modeling and modifying <code>avatar.json</code> files to scripting.
= Tools =
==='''[https://github.com/GrandpaScout/FiguraRewriteVSDocs GS' Figura VSCode Documentation]'''===
'''GrandpaScout's Figura VSCode Documentation''' is an addon for Visual Studio Code (along with Code OSS and VSCodium) that adds Figura's documentation and snippets to [https://marketplace.visualstudio.com/items?itemName=sumneko.lua sumneko's Lua Language Server plugin].
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/GrandpaScout/FiguraRewriteVSDocs/wiki Install Guide]
</div>
</div>
==='''[https://github.com/KitCat962/figura-format-bbplugin Katt's Figura Blockbench Extension]'''===
The '''Figura Blockbench Extension''' adds a new model format to Blockbench, the Figura Model format. It extends the base Generic Model format by adding tools to make the avatar creation process easier, lifting restrictions to the Generic Model format that Figura supports, and removing features Figura doesn't.
= Assets (Scripts, Libraries, APIs) =
{{Notice
|content='''Some assets only exist within the [https://discord.figuramc.org FiguraMC Discord].'''<br>
* Assets that link to the FiguraMC Discord will be marked with a 💬 icon.
}}
== Animation Helpers ==
==='''[https://github.com/GrandpaScout/GSAnimBlend GSAnimBlend]'''===
'''GSAnimBlend''' is a script that automatically adds blends to the start and end of animations.
==='''[https://github.com/JimmyHelp/JimmyAnims Jimmy's Animation Handler]'''===
'''JimmyAnim''' (full name Jimmy's Animation Helper) is a library that plays specific Blockbench animations based on the player's current action.
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://jimmyhelp.notion.site/JimmyAnims-79adfdca2fe04f9c9ede5e0bfd898b6a Documentation]
* [https://github.com/JimmyHelp/JimmyAnims/blob/main/JimmyExample.lua Example Usage]
</div>
</div>
==Visual Elements==
==='''[https://github.com/Manuel-3/figura-scripts/tree/main/src/confetti Confetti]'''===
'''Confetti''' is a library that allows users to add custom particles, either sprite or modelpart, to their avatars
<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/readme.md Documentation]
* [https://github.com/Manuel-3/figura-scripts/blob/main/src/confetti/example.zip Example Avatar]
</div>
</div>
==='''[https://discord.com/channels/1129805506354085959/1137506926742216835 KattArmor]''' 💬===
'''KattArmor''' (sometimes called Katt Armor API/Library) is a library that allows users to edit their avatar's armor, whether by adding pivots using a script or by using unique models and textures.

<div class="mw-collapsible mw-collapsed">
<h4>
Additional Resources
<div class="mw-collapsible-toggle-placeholder"></div>
</h4>
<div class="mw-collapsible-content">
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1155212562980425818 How-To Guide]
* [https://discord.com/channels/1129805506354085959/1137506926742216835/1262160359905562705 Example Avatars]
</div>
</div>
= Community =
==='''[https://discord.figuramc.org FiguraMC Discord]''' ⭐===
The '''FiguraMC Discord Server''' is the central place for everything Figura, including help and support for the mod, avatar showcasing, and more. You'll also need to join this server to request whitelist to the FiguraSMP.
== Minecraft Servers ==
{{Notice
|content='''Some servers listed below are whitelisted.'''<br>
* Servers that have a public whitelist application process will be marked with a 🔒 icon.
* Servers that are invite-only will be marked with a 🛡️ icon.
}}
==='''Figura Plaza''' ⭐===
'''Figura Plaza''' is a lobby-like server where players can join, hang out with other Figura users, make avatars in company, play games, and occasionally attend events.
plaza.figuramc.org
==='''FiguraSMP''' ⭐🔒===
The '''FiguraSMP''' is a set of two survival multiplayer servers—Vanilla and Modded—that are ran in affiliation with FiguraMC.
* Vanilla FiguraSMP is a server that stays close to the base game, only adding quality of life features for public servers. '''IP: <span style="user-select: all">vanilla.figuramc.org</span>'''
* ModdedSMP is a seasonal modpack server, each season coming with its own theme. '''Currently offline.''' The next season is themed after a nuclear apocalypse and is set for release Soon™.

You can read the server rules in [https://discord.com/channels/1129805506354085959/1130186794873405510 #info] and get whitelisted by putting your name in [https://discord.com/channels/1129805506354085959/1130187119680311470 #whitelist]. note that both of these channel links require you to be in [https://discord.figuramc.org the official Discord server for Figura].

==='''4p5.nz''' 🛡️===
'''4p5.nz''' is an invite-only creative/operator server where players have free reign over the world around them.
4p5.nz

FiguraMC:Contributing

2024-10-05T04:07:33Z

PoolloverNathan: Undo revision 508 by PoolloverNathan (talk)

{{Stub}}
== Contributing to the Mod ==
Please refer to [https://github.com/FiguraMC/Figura/blob/1.20/CONTRIBUTING.md the GitHub repo]
== Contributing to the Wiki ==
=== Information ===
When contributing to this wiki, there are a couple things you should remember:
* Follow the [[FiguraMC:Rules|rules]]
* Follow the [[FiguraMC:Contributing/Style Guide|style guide]]
=== Style Guide ===
{{VeryObviouslyTranscluded|FiguraMC:Contributing/Style Guide|Style Guide}}
=== Rules ===
{{VeryObviouslyTranscluded|FiguraMC:Rules}}
=== (Temporary) Getting an Account ===
Until account creation is set up, contact one of the wiki admins.

FiguraMC:Contributing

2024-10-05T04:07:01Z

PoolloverNathan: inline transclude

{{Stub}}
== Contributing to the Mod ==
Please refer to [https://github.com/FiguraMC/Figura/blob/1.20/CONTRIBUTING.md the GitHub repo]
== Contributing to the Wiki ==
=== Information ===
When contributing to this wiki, there are a couple things you should remember:
* Follow the [[FiguraMC:Rules|rules]]
* Follow the [[FiguraMC:Contributing/Style Guide|style guide]]
=== Style Guide ===
{{FiguraMC:Contributing/Style Guide|Style Guide}}
=== Rules ===
{{FiguraMC:Rules}}
=== (Temporary) Getting an Account ===
Until account creation is set up, contact one of the wiki admins.

Template:VeryObviouslyTranscluded

2024-10-05T03:54:11Z

PoolloverNathan: suppress external link icon

<div style="border-left: thin solid black; padding-left: 1mm">
<div style="float: right; margin-top: -1.5em">
''From [[{{{1}}}|{{{2|{{{1}}}}}}]] (<span class="plainlinks">[{{fullurl:{{{1}}}|action=edit}} edit]</span>)''
</div>
{{{{{1}}}}}
</div>

FiguraMC:Contributing

2024-10-05T03:52:20Z

PoolloverNathan:

{{Stub}}
== Contributing to the Mod ==
Please refer to [https://github.com/FiguraMC/Figura/blob/1.20/CONTRIBUTING.md the GitHub repo]
== Contributing to the Wiki ==
=== Information ===
When contributing to this wiki, there are a couple things you should remember:
* Follow the [[FiguraMC:Rules|rules]]
* Follow the [[FiguraMC:Contibuting/Style Guide|style guide]]
=== Style Guide ===
{{VeryObviouslyTranscluded|User:TheKillerBunny/Style Guide|Style Guide}}
=== Rules ===
{{VeryObviouslyTranscluded|FiguraMC:Rules}}
=== (Temporary) Getting an Account ===
Until account creation is set up, contact one of the wiki admins.

Template:VeryObviouslyTranscluded

2024-10-05T03:48:47Z

PoolloverNathan: reformat

<div style="border-left: thin solid black; padding-left: 1mm">
<div style="float: right; margin-top: -1em">
''From [[{{{1}}}|{{{2|{{{1}}}}}}]] ([{{fullurl:{{{1}}}|action=edit}} edit])''
</div>
{{{{{1}}}}}
</div>

Template:VeryObviouslyTranscluded

2024-10-05T03:35:10Z

PoolloverNathan: Created page with "''Transcluded from {{{1}}}}}} ([{{fullurl:{{{1}}}|action=edit}} edit])'' {{{{{1}}}}}"

''Transcluded from [[{{{1}}}|{{{2|{{{1}}}}}}]] ([{{fullurl:{{{1}}}|action=edit}} edit])''
{{{{{1}}}}}

FiguraMC:Contributing

2024-10-05T03:34:26Z

PoolloverNathan: get created

{{stub}}
== Rules ==
{{VeryObviouslyTranscluded|FiguraMC:Rules}}

Main Page

2024-10-05T03:30:42Z

PoolloverNathan: pipe trick

{{Notice/Warning
|content=
<div style="font-size: 1.5em; font-weight: bold; margin: 0.5em 0 0 0;">This wiki is under heavy construction.</div>
To contribute to this wiki, see [[Special:WantedPages|Wanted Pages]], [[:Category:Stubs|Stubs]], and [[FiguraMC:Contributing|Contributing]].
}}
{{Notice
|content=[https://figura-wiki.pages.dev <span style="font-size: 1.5em; color: black !important;">'''Looking for the old wiki? Click here!'''</span>]
}}

== Navigation ==
{{Navbox documentation}}

Main Page

2024-10-05T03:30:14Z

PoolloverNathan: google en passant

{{Notice/Warning
|content=
<div style="font-size: 1.5em; font-weight: bold; margin: 0.5em 0 0 0;">This wiki is under heavy construction.</div>
To contribute to this wiki, see [[Special:WantedPages|Wanted Pages]], [[:Category:Stubs|Stubs]], and [[FiguraMC:Contributing]].
}}
{{Notice
|content=[https://figura-wiki.pages.dev <span style="font-size: 1.5em; color: black !important;">'''Looking for the old wiki? Click here!'''</span>]
}}

== Navigation ==
{{Navbox documentation}}

Module:Distinguish

2024-09-29T01:39:10Z

PoolloverNathan: lua doin a little trollin

Module:Distinguish

2024-09-29T01:38:49Z

PoolloverNathan: mediawiki doin a little trollin

Module:Distinguish/doc

2024-09-29T01:38:18Z

PoolloverNathan: Created page with "* {{distinguish}} * {{distinguish|Foo}} * {{distinguish|Foo|Bar}} * {{distinguish|Foo|Bar|Baz}}"

* {{distinguish}}
* {{distinguish|Foo}}
* {{distinguish|Foo|Bar}}
* {{distinguish|Foo|Bar|Baz}}

Module:Distinguish

2024-09-29T01:37:28Z

PoolloverNathan: accept 0 arguments

Template:Type

2024-09-28T19:30:51Z

PoolloverNathan: depluralize example Vector and Matrix plus suggestion

<includeonly><templatestyles src="Template:Type/style.css"/>{{#if:{{{3|{{{link|}}}}}}
|{{type/link|{{{1}}}|mod={{{2|{{{mod|}}}}}}|link={{{3|{{{link}}}}}}}}
|{{#switch:{{{1}}}
| nil
| number
| numbers
| double
| doubles
| integer
| integers
| string
| strings
| boolean
| bool
| booleans
| true
| false
| function
| functions
| table
| any
| tables = {{type/builtin|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
| Vectors
| vectors
| Vector
| Vector2
| Vector3
| Vector4 = {{type/vector|{{{1}}}|name=Vector|mod={{{2|{{{mod|}}}}}}}}
| Matrices
| matrices
| Matrix
| Matrix2
| Matrix3
| Matrix4 = {{type/vector|{{{1}}}|name=Matrix|mod={{{2|{{{mod|}}}}}}}}
| {{type/custom|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
}}
}}</includeonly><noinclude> 
'''Displays a ''type widget''.'''

* If a link is provided: [[Template:Type/link]]
* Built-in types: [[Template:Type/builtin]]
* Custom types (fallback): [[Template:Type/custom]]. If the page with <code>[argument 1] (type)</code> (i.e. disambiguated) exists, that page will be used instead of the plain name for the link.

Stylesheet: [[Template:Type/style.css]] (edit to add colors and decorations for custom types)

== Examples ==
* {{type|nil}} <code><nowiki>{{type|nil}}</nowiki></code>
* {{type|number}}
* {{type|number|?}} (optional number)
* {{type|string}}
* {{type|boolean}}
* {{type|function}}
* {{type|table}}
* {{type|Vector}} ({{type|Vector2}}, {{type|Vector3}}, {{type|Vector4}})
* {{type|Matrix}} ({{type|Matrix2}}, {{type|Matrix3}}, {{type|Matrix4}})
* {{type|Event}} (custom type that exists)
* {{type|CrashAPI}} (custom type that doesn't exist)
* {{type|Main Page|link=Main Page}} (links to the [[Main Page]]) <code><nowiki>{{type|Main Page|link=Main Page}}</nowiki></code>
[[Template:Type/testcases|Testcases page.]]
<templatedata>
{
"params": {
"1": {
"label": "Type name",
"suggestedvalues": [
"nil",
"boolean",
"integer",
"number",
"string",
"function",
"table",
"Vector",
"Matrix"
],
"required": true
},
"link": {
"aliases": [
"3"
],
"label": "Custom link target",
"type": "wiki-page-name"
},
"mod": {
"aliases": [
"2"
],
"label": "Type modifiers",
"description": "Modifiers to the type, like array / optional",
"type": "content",
"suggestedvalues": [
"[]",
"?",
"[]?"
]
}
},
"description": "Displays and links to types.",
"paramOrder": [
"1",
"mod",
"link"
],
"format": "inline"
}
</templatedata></noinclude>

Main Page

2024-09-27T18:50:04Z

PoolloverNathan: redirect to page list

#REDIRECT [[Special:AllPages]]

(redirect requested by joeyy)
[[File:Screenshot_2024-09-27_14.48.30.png]]

[https://figura-wiki.pages.dev <big>'''Looking for the old wiki? Click here!'''</big>]

File:Screenshot 2024-09-27 14.48.30.png

2024-09-27T18:49:08Z

PoolloverNathan:

Event

2024-09-27T18:47:19Z

PoolloverNathan: PoolloverNathan moved page Event to Event (type): Distinguishing from Events

#REDIRECT [[Event (type)]]

Event (type)

2024-09-27T18:47:19Z

PoolloverNathan: PoolloverNathan moved page Event to Event (type): Distinguishing from Events

{{Distinguish|Events}}

The event type is used for events such as <code>events.TICK</code>. To create an event function, use one of the following.

<syntaxHighlight lang="lua"> local tick = 0
function events.WORLD_TICK()
tick = tick + 1
end
-- OR
local tick = 0
events.WORLD_TICK:register(function()
tick = tick + 1
end, "TICK_COUNTER")
</syntaxHighlight>

== Methods ==
{| class="wikitable"
|-
! | Method
! | Description
|-
| [[/remove|remove]]
| Takes in a {{type|string}} with the name of the event, and removes it, stopping it from being called
|-
| [[/clear|clear]]
| Clears the event of all methods
|-
| [[/register|register]]
| Takes in a {{type|function}} to run when the event is fired, with an optional name argument ({{type|string}})
|-
| [[/getRegisteredCount|getRegisteredCount]]
| Returns the amount of functions registered, with an optional name argument ({{type|string}})
|}

[[Category:Types]]

Template:Type/style.css

2024-09-27T18:02:58Z

PoolloverNathan: spell matrix correctly & select a

.lua-type {
display: inline-flex;
align-items: stretch;
flex-flow: row nowrap;
width: max-content;
border-radius: 3px;
overflow: hidden;
font-family: monospace;
}
.lua-type a {
border-radius: 3px;
background-color: #eeeeee;
padding: 0 3px;
background-image: none;
z-index: 2;
}
.lua-type .lua-type-mod {
margin-left: -3px;
padding: 0 3px 0 6px;
background-color: #ffffff;
border: 1px solid #dddddd;
z-index: 1;
}
.lua-type a, .lua-type a:visited {
color: #000000;
}
.lua-type[data-name="nil"] a {
background-color: #ffffff;
border: 1px solid #808080;
}
.lua-type[data-name="any"] a {
background-color: #ffffff;
border: 1px dotted #808080;
}
.lua-type[data-name="table"] a, .lua-type[data-name="tables"] a {
background-color: #ffffdd;
}
.lua-type[data-name="function"] a, .lua-type[data-name="functions"] a {
background-color: #eeddff;
}
.lua-type[data-name="string"] a, .lua-type[data-name="strings"] a {
background-color: #ddffdd;
}
.lua-type[data-name="boolean"] a, .lua-type[data-name="booleans"] a, .lua-type[data-name="bool"] a {
background-color: #ffddff;
}
.lua-type[data-name="number"] a, .lua-type[data-name="numbers"] a, .lua-type[data-name="integer"] a, .lua-type[data-name="integers"] a, .lua-type[data-name="double"] a, .lua-type[data-name="doubles"] a {
background-color: #ddddff;
}
.lua-type[data-name="Vector"] a {
background-color: #ffeedd;
}
.lua-type[data-name="Matrix"] a {
background-color: #ffddee;
}
.lua-type.lua-type[data-missing] a {
background-color: #ffdddd;
color: #d73333;
}

Template:Type/style.css

2024-09-27T18:01:09Z

PoolloverNathan: is ^= disallowed?

.lua-type {
display: inline-flex;
align-items: stretch;
flex-flow: row nowrap;
width: max-content;
border-radius: 3px;
overflow: hidden;
font-family: monospace;
}
.lua-type a {
border-radius: 3px;
background-color: #eeeeee;
padding: 0 3px;
background-image: none;
z-index: 2;
}
.lua-type .lua-type-mod {
margin-left: -3px;
padding: 0 3px 0 6px;
background-color: #ffffff;
border: 1px solid #dddddd;
z-index: 1;
}
.lua-type a, .lua-type a:visited {
color: #000000;
}
.lua-type[data-name="nil"] a {
background-color: #ffffff;
border: 1px solid #808080;
}
.lua-type[data-name="any"] a {
background-color: #ffffff;
border: 1px dotted #808080;
}
.lua-type[data-name="table"] a, .lua-type[data-name="tables"] a {
background-color: #ffffdd;
}
.lua-type[data-name="function"] a, .lua-type[data-name="functions"] a {
background-color: #eeddff;
}
.lua-type[data-name="string"] a, .lua-type[data-name="strings"] a {
background-color: #ddffdd;
}
.lua-type[data-name="boolean"] a, .lua-type[data-name="booleans"] a, .lua-type[data-name="bool"] a {
background-color: #ffddff;
}
.lua-type[data-name="number"] a, .lua-type[data-name="numbers"] a, .lua-type[data-name="integer"] a, .lua-type[data-name="integers"] a, .lua-type[data-name="double"] a, .lua-type[data-name="doubles"] a {
background-color: #ddddff;
}
.lua-type[data-name="Vector"] {
background-color: #ffeedd;
}
.lua-type[data-name="Matri"] {
background-color: #ffddee;
}
.lua-type.lua-type[data-missing] a {
background-color: #ffdddd;
color: #d73333;
}

Template:Type

2024-09-27T18:00:04Z

PoolloverNathan: pass name through

<includeonly><templatestyles src="Template:Type/style.css"/>{{#if:{{{3|{{{link|}}}}}}
|{{type/link|{{{1}}}|mod={{{2|{{{mod|}}}}}}|link={{{3|{{{link}}}}}}}}
|{{#switch:{{{1}}}
| nil
| number
| numbers
| double
| doubles
| integer
| integers
| string
| strings
| boolean
| bool
| booleans
| true
| false
| function
| functions
| table
| any
| tables = {{type/builtin|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
| Vectors
| vectors
| Vector2
| Vector3
| Vector4 = {{type/vector|{{{1}}}|name=Vector|mod={{{2|{{{mod|}}}}}}}}
| Matrices
| matrices
| Matrix2
| Matrix3
| Matrix4 = {{type/vector|{{{1}}}|name=Matrix|mod={{{2|{{{mod|}}}}}}}}
| {{type/custom|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
}}
}}</includeonly><noinclude> 
'''Displays a ''type widget''.'''

* If a link is provided: [[Template:Type/link]]
* Built-in types: [[Template:Type/builtin]]
* Custom types (fallback): [[Template:Type/custom]]. If the page with <code>[argument 1] (type)</code> (i.e. disambiguated) exists, that page will be used instead of the plain name for the link.

Stylesheet: [[Template:Type/style.css]] (edit to add colors and decorations for custom types)

== Examples ==
* {{type|nil}} <code><nowiki>{{type|nil}}</nowiki></code>
* {{type|number}}
* {{type|number|?}} (optional number)
* {{type|string}}
* {{type|boolean}}
* {{type|function}}
* {{type|table}}
* {{type|Vectors}} ({{type|Vector2}}, {{type|Vector3}}, {{type|Vector4}})
* {{type|Matrices}} ({{type|Matrix2}}, {{type|Matrix3}}, {{type|Matrix4}})
* {{type|Event}} (custom type that exists)
* {{type|CrashAPI}} (custom type that doesn't exist)
* {{type|Main Page|link=Main Page}} (links to the [[Main Page]]) <code><nowiki>{{type|Main Page|link=Main Page}}</nowiki></code>
[[Template:Type/testcases|Testcases page.]]
<templatedata>
{
"params": {
"1": {
"label": "Type name",
"suggestedvalues": [
"nil",
"boolean",
"integer",
"number",
"string",
"function",
"table"
],
"required": true
},
"link": {
"aliases": [
"3"
],
"label": "Custom link target",
"type": "wiki-page-name"
},
"mod": {
"aliases": [
"2"
],
"label": "Type modifiers",
"description": "Modifiers to the type, like array / optional",
"type": "content",
"suggestedvalues": [
"[]",
"?",
"[]?"
]
}
},
"description": "Displays and links to types.",
"paramOrder": [
"1",
"mod",
"link"
],
"format": "inline"
}
</templatedata></noinclude>

Template:Type/style.css

2024-09-27T17:58:18Z

PoolloverNathan: colorize vectors & matrices

.lua-type {
display: inline-flex;
align-items: stretch;
flex-flow: row nowrap;
width: max-content;
border-radius: 3px;
overflow: hidden;
font-family: monospace;
}
.lua-type a {
border-radius: 3px;
background-color: #eeeeee;
padding: 0 3px;
background-image: none;
z-index: 2;
}
.lua-type .lua-type-mod {
margin-left: -3px;
padding: 0 3px 0 6px;
background-color: #ffffff;
border: 1px solid #dddddd;
z-index: 1;
}
.lua-type a, .lua-type a:visited {
color: #000000;
}
.lua-type[data-name="nil"] a {
background-color: #ffffff;
border: 1px solid #808080;
}
.lua-type[data-name="any"] a {
background-color: #ffffff;
border: 1px dotted #808080;
}
.lua-type[data-name="table"] a, .lua-type[data-name="tables"] a {
background-color: #ffffdd;
}
.lua-type[data-name="function"] a, .lua-type[data-name="functions"] a {
background-color: #eeddff;
}
.lua-type[data-name="string"] a, .lua-type[data-name="strings"] a {
background-color: #ddffdd;
}
.lua-type[data-name="boolean"] a, .lua-type[data-name="booleans"] a, .lua-type[data-name="bool"] a {
background-color: #ffddff;
}
.lua-type[data-name="number"] a, .lua-type[data-name="numbers"] a, .lua-type[data-name="integer"] a, .lua-type[data-name="integers"] a, .lua-type[data-name="double"] a, .lua-type[data-name="doubles"] a {
background-color: #ddddff;
}
.lua-type[data-name^="vector"], .lua-type[data-name^="Vector"] {
background-color: #ffeedd;
}
.lua-type[data-name^="matri"], .lua-type[data-name^="Matri"] {
background-color: #ffddee;
}
.lua-type.lua-type[data-missing] a {
background-color: #ffdddd;
color: #d73333;
}

Template:Type

2024-09-27T17:55:27Z

PoolloverNathan: add vector/matrix support

<includeonly><templatestyles src="Template:Type/style.css"/>{{#if:{{{3|{{{link|}}}}}}
|{{type/link|{{{1}}}|mod={{{2|{{{mod|}}}}}}|link={{{3|{{{link}}}}}}}}
|{{#switch:{{{1}}}
| nil
| number
| numbers
| double
| doubles
| integer
| integers
| string
| strings
| boolean
| bool
| booleans
| true
| false
| function
| functions
| table
| any
| tables = {{type/builtin|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
| Vectors
| vectors
| Vector2
| Vector3
| Vector4 = {{type/vector|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
| Matrices
| matrices
| Matrix2
| Matrix3
| Matrix4 = {{type/vector|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
| {{type/custom|{{{1}}}|mod={{{2|{{{mod|}}}}}}}}
}}
}}</includeonly><noinclude> 
'''Displays a ''type widget''.'''

* If a link is provided: [[Template:Type/link]]
* Built-in types: [[Template:Type/builtin]]
* Custom types (fallback): [[Template:Type/custom]]. If the page with <code>[argument 1] (type)</code> (i.e. disambiguated) exists, that page will be used instead of the plain name for the link.

Stylesheet: [[Template:Type/style.css]] (edit to add colors and decorations for custom types)

== Examples ==
* {{type|nil}} <code><nowiki>{{type|nil}}</nowiki></code>
* {{type|number}}
* {{type|number|?}} (optional number)
* {{type|string}}
* {{type|boolean}}
* {{type|function}}
* {{type|table}}
* {{type|Vectors}} ({{type|Vector2}}, {{type|Vector3}}, {{type|Vector4}})
* {{type|Matrices}} ({{type|Matrix2}}, {{type|Matrix3}}, {{type|Matrix4}})
* {{type|Event}} (custom type that exists)
* {{type|CrashAPI}} (custom type that doesn't exist)
* {{type|Main Page|link=Main Page}} (links to the [[Main Page]]) <code><nowiki>{{type|Main Page|link=Main Page}}</nowiki></code>
[[Template:Type/testcases|Testcases page.]]
<templatedata>
{
"params": {
"1": {
"label": "Type name",
"suggestedvalues": [
"nil",
"boolean",
"integer",
"number",
"string",
"function",
"table"
],
"required": true
},
"link": {
"aliases": [
"3"
],
"label": "Custom link target",
"type": "wiki-page-name"
},
"mod": {
"aliases": [
"2"
],
"label": "Type modifiers",
"description": "Modifiers to the type, like array / optional",
"type": "content",
"suggestedvalues": [
"[]",
"?",
"[]?"
]
}
},
"description": "Displays and links to types.",
"paramOrder": [
"1",
"mod",
"link"
],
"format": "inline"
}
</templatedata></noinclude>

Template:Tagged

2024-09-27T17:24:16Z

PoolloverNathan: grid?

<includeonly>
<span style="display: inline-grid; grid-template-columns: max-content 1fr">
<span>'''{{{1}}}''': </span>
<span>{{{2}}}</span>
</span>
</includeonly>
<noinclude>
testing inline text {{tagged|foo bar baz|bar baz bar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar baz bar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar baz}}
</noinclude>

Template:Tagged

2024-09-27T17:21:19Z

PoolloverNathan: fix

<includeonly>
<div style="display: inline-flex">
<div style="flex: 0 0 auto">'''{{{1}}}''': </div>
<div style="flex: 1 0 0"><div style="width: 100%">{{{2}}}</div></div>
</div>
</includeonly>
<noinclude>
testing inline text {{tagged|foo bar baz|bar baz bar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar baz bar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar bazbar baz}}
</noinclude>

Tutorials/Commands

2024-09-27T17:18:43Z

PoolloverNathan: essentially rewrite

Figura comes with a small set of commands to act as menu shortcuts or access advanced features. As Figura is a client-side mod, these only affect the client.

{{note|Figura commands are '''only visible client-side''' and therefore cannot be used server-side (e.g. in command blocks or functions, or even in <code>/execute</code>). If you try, it will appear as an invalid command.|tag=Warning|icon=⚠}}

<span id="normal-commands"></span>

; <code name="docs">/figura docs</code>
: This command allows you to quickly access a list of types (and their fields/methods) and enums (and their values), as well as a brief description for each one. Note that some internal docs may

; <code name="emojis>/figura emojis</code>
: This command lists all the emojis added by Figura. <code>/figura emojis all</code> can show you all of them at once.

; <code name="export_avatar>/figura export avatar</code>
: This exports your currently saved avatar data to a file in your Figura directory. The

; <code>/figura links</code>
: This command prints a list of links to various Figura websites.

; <code>/figura load ''directory''</code>
: This command loads a Figura avatar by the name of its ''directory'' in your avatars folder. This can be useful if you don't want to open the Figura menu, or you have a lot of avatars and don't want to search through them.

; <code>/figura reload</code>
: This command reloads your currently-selected avatar, equivalent to pressing your reload keybind.

; <code>/figura run ''code''</code>
: This command runs the code you supply in the context of your avatar, with the ability to access any '''global''' variables you've declared. If you don't have an avatar selected, or its script has errored. you will not be able to run code.

== Debug Mode Commands ==

More commands can be unlocked by turning Debug Mode on in Figura’s settings and rejoining the world..

; <code name="debug">/figura debug</code>
: This generates a file in your Figura directory that contains information about your Figura mod settings and the avatar you currently have equipped. This includes the file sizes of all of the elements in the avatar. ''This command is currently broken on Forge.''

; <code name="backend2">/figura backend2</code>
: Usage unknown; presumably used to test the Figura backend.

; <code name="set_avatar">/figura set_avatar ''to'' ''from''</code>
: This command copies equipped avatars between entities, which allows you to e.g. test [[CEM]] avatars. Note that both arguments must be the entities' '''UUIDs''' — merely their name or a selector will not be accepted.
: {{tagged|<code>to</code>|This is the UUID of the entity you wish to set the avatar of. You can get the UUID by autocompleting a command, such as <code>/tp</code>, while looking at them. (This command also works on players, somewhat.)}}
: {{tagged|<code>from</code>|This is the UUID of the entity you want to copy the avatar ''from''. You can acquire this by using the command <code>/list uuids</code> (check your game logs if you wish to copy the output) or a website such as [https://mcuuid.net].}}

Tutorial:Blinking

2024-09-27T16:54:29Z

PoolloverNathan: modelpart indexing reference

[[File:EyeGroup.png|thumb]] Avatars may blink as a means to convey a character's personality and suggest liveliness. To blink, you must first have eyes that have been split into a separate [[ModelPart]]. Your script will scale this group to simulate blinking.
To begin with, define variables containing parameters the script will use: the [[ModelPart Indexing|path to]] the eye model, their height, and the length of the blinking animation.
<syntaxHighlight lang="lua">
local eyes = models.model.root.UpperBody.TheHead.Eyes
local EYE_HEIGHT = 2 --The height of your eyes in blockbench units
local BLINK_RATE = 4 * 20 -- 4 Seconds
</syntaxHighlight>The <code>BLINK_RATE</code> particle is multiplied by 20 as the script will deal in ticks, and there are 20 ticks in a second.

Next, the logic that determines when to blink will be performed in a <code>TICK</code> event. 4 new variables will also be needed to store the calculated position and scale for the eyes, alongside a simple timer. These will be initialised outside of the <code>TICK</code> event.
<syntaxHighlight lang="lua">
local oldScale = vec(1, 1, 1)
local newScale = vec(1, 1, 1)
local oldPos = vec(0, 0, 0)
local newPos = vec(0, 0, 0)

local tick = 0
function events.TICK()
-- Sets old pos and scale for later interpolation
oldPos = newPos
oldScale = newScale
tick = tick + 1

-- If time to blink, set new position and scale to close the eyes, otherwise open them
if tick % BLINK_RATE == 0 then
newScale = vec(1, 0, 1)
newPos = vec(0, EYE_HEIGHT / -2, 0)
else
newScale = vec(1, 1, 1)
newPos = vec(0, 0, 0)
end
end
</syntaxHighlight>

In order to give the blinking a smooth appearance, the rendered position and scale will be calculated and set in a <code>RENDER</code> event, using the variables initialized earlier.

<syntaxHighlight lang="lua">
function events.RENDER(delta)
-- This interpolates the blinking to make for a smooth blink
local scale = math.lerp(oldScale, newScale, delta)
local pos = math.lerp(oldPos, newPos, delta)

eyes:setPos(pos):setScale(scale)
end
</syntaxHighlight>

[[Category:Tutorials]]

Tutorial:Blinking

2024-09-27T16:53:30Z

PoolloverNathan: move eye thingy

[[File:EyeGroup.png|thumb]] Avatars may blink as a means to convey a character's personality and suggest liveliness. To blink, you must first have eyes that have been split into a separate [[ModelPart]]. Your script will scale this group to simulate blinking.
To begin with, define variables containing parameters the script will use: the path to the eye model, their height, and the length of the blinking animation.
<syntaxHighlight lang="lua">
local eyes = models.model.root.UpperBody.TheHead.Eyes
local EYE_HEIGHT = 2 --The height of your eyes in blockbench units
local BLINK_RATE = 4 * 20 -- 4 Seconds
</syntaxHighlight>The <code>BLINK_RATE</code> particle is multiplied by 20 as the script will deal in ticks, and there are 20 ticks in a second.

Next, the logic that determines when to blink will be performed in a <code>TICK</code> event. 4 new variables will also be needed to store the calculated position and scale for the eyes, alongside a simple timer. These will be initialised outside of the <code>TICK</code> event.
<syntaxHighlight lang="lua">
local oldScale = vec(1, 1, 1)
local newScale = vec(1, 1, 1)
local oldPos = vec(0, 0, 0)
local newPos = vec(0, 0, 0)

local tick = 0
function events.TICK()
-- Sets old pos and scale for later interpolation
oldPos = newPos
oldScale = newScale
tick = tick + 1

-- If time to blink, set new position and scale to close the eyes, otherwise open them
if tick % BLINK_RATE == 0 then
newScale = vec(1, 0, 1)
newPos = vec(0, EYE_HEIGHT / -2, 0)
else
newScale = vec(1, 1, 1)
newPos = vec(0, 0, 0)
end
end
</syntaxHighlight>

In order to give the blinking a smooth appearance, the rendered position and scale will be calculated and set in a <code>RENDER</code> event, using the variables initialized earlier.

<syntaxHighlight lang="lua">
function events.RENDER(delta)
-- This interpolates the blinking to make for a smooth blink
local scale = math.lerp(oldScale, newScale, delta)
local pos = math.lerp(oldPos, newPos, delta)

eyes:setPos(pos):setScale(scale)
end
</syntaxHighlight>

[[Category:Tutorials]]

ModelPart

2024-09-27T15:17:11Z

PoolloverNathan: /* Child Manipulation */ who the fuck thought that was a good header

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, <b>it will not</b> 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 <em>any</em> 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 <b>do not</b> 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.

=== 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-27T15:13:59Z

PoolloverNathan: /* Accessing ModelParts */ don't use a pre for a fun fact (peer-review: is calling this trivia appropriate? taking that tradition from explainxkcd)

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, <b>it will not</b> 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 <em>any</em> 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 <b>do not</b> 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

Template:Note

2024-09-27T15:11:10Z

PoolloverNathan: separate icon customization

Template:Note

2024-09-27T15:10:46Z

PoolloverNathan: allow customization

Template:Fr

2024-09-27T14:24:59Z

PoolloverNathan: glorified fraction slash

{{{1}}}⁄{{{2}}}

Template:Note

2024-09-27T04:39:20Z

PoolloverNathan: mobile compat

Pings (Tutorial)

2024-09-27T04:36:09Z

PoolloverNathan: format link

With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>

----

What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:

; Keybinds
: If the Minecraft Server tracked every single keystroke, it would be a major security issue. The exact keystrokes are never sent, only the result of those keystrokes.

; Action Wheel
: The Action Wheel is a feature added by Figura. Remember how I said that Figura never comunicates with the Minecraft Server? It should be obvious why the Action Wheel isnt synced.

; HostAPI
: The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent — some methods such as <code>[[PlayerAPI/isGrounded|isGrounded]]</code> feel the need to be ''special'')

So how can we sync information with other players if we cannot do it through the Minecraft Server? The answer is Pings.

== General Pings ==
Pings utilize Figura’s Backend to sync information with other clients. Pings are functions that when called, triggers all other clients to call the same function for their instance of your avatar.

=== Ping Rate Limiting ===
The backend restricts you on how much data you can send over a period of time. The developer given limits are:

* 1024 bytes per second
* 32 pings per second

If either of these are reached, the backend will ignore any comunication from you for some amount of time.

{{note|In some cases, fluctuations in network speed may cause some pings to become clumped close enough to reach this limit if they are slightly below. It's wise to leave a bit of buffer room just in case.}}

=== Pingable Values ===
Pings can send most primitive types and some userdata types.<br/> All pingable types use a single byte to represent the type of data that is being sent. This byte is not included in the listed byte totals.

* {{Type|nil}} - 0 Bytes
** if a type that is not supported is used as a parameter, it will be replaced with {{Type|nil}}.

* {{Type|boolean}} - 0 Bytes

* {{Type|integer}} - 1-4 Bytes
** {{Type|integers}} only take up as many bytes as they need.
** {{Type|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.

* {{Type|double}} - 8 Bytes
** If the number has a decimal at all, or is outside the range of a 4 byte {{Type|integer}}, it will be sent as a {{Type|double}}.

* {{Type|string}} - 2+n Bytes
** {{Type|strings}} will always use 2 bytes to store the length of the string.
** ASCII characters will be a single byte each.
** UTF-8 characters will be multiple bytes per character.
** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

* {{Type|table}} - (all keys) + (all values) Bytes
** Every key and value is send as data, resulting in high byte costs.
** It is recommended to never send a table over pings.

* {{Type|Vector}} - 1+8*N Bytes
** {{Type|Vectors}} use a single byte to store the size of the Vector.
** Vectors are always assumed to store {{Type|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.

* {{Type|Matrix}} - 2+8*W*H Bytes
** {{Type|Matrices}} store both the width and height of the matrix, then every value as a {{Type|double}}.

=== Ping ===
Below is an '''example''' ping.

<syntaxhighlight lang="lua">function pings.pingName(a)
print("Ping")
print(".")
print("Data Recieved:", a)
print(".")
print("Pong")
end
</syntaxhighlight>

It accepts a single variable, which it will print to the chat as an example.

To call it, just call it like any other lua function.
<syntaxhighlight lang="lua">
pings.pingName("This is a string wooooooooooooooooo")
</syntaxhighlight>

When you as the host call the ping, the function will execute for all other clients, regardless of their current state.

Do note that if a non-host client reaches a line where a ping gets called, it is completely ignored. No data is sent to the backend, and the contents of the ping will not be executed.

Ping functions can be passed into functions that expect a function as a parameter, such as Action <code>onToggle</code>.

<syntaxhighlight lang="lua">
actionVariable:onToggle(pings.pingName)
</syntaxhighlight>

Remember that we are passing the function itself as a variable. The below would be passing the ''return result'' of the ping function, which is nigh guarenteed to be <code>nil</code> as Pings ''should never'' return a value.

<syntaxhighlight lang="lua">
--do not do
actionVariable:onToggle(pings.pingName())</syntaxhighlight>

<span id="advanced-pings"></span>

== Advanced Pings ==

Situational techniques that may be handy, depending on the use case.

=== Ping on Init ===
Calling a ping function when the script is first loaded is a horrible idea. The ping will only ever execute for other clients when you, the host, load the avatar. Not only that, it may never be executed on other clients, as they might not have your avatar loaded by the time you broadcast the ping.

How do we get around this? Well, when you assign a function to an index in the <code>pings</code> table, the Lua Function gets replaced with a Java Function. This happens because of metatables, specifically the <code>__newindex</code> metamethod. Functions cannot be modified, so if we store the function before adding it to the <code>pings</code> table, we can use it like a regular function, and use the same code as a ping function.

<syntaxhighlight lang="lua">local function doThing(state)
models.modelA:setVisible(state)
models.modelB:setVisible(not state)
end

pings.doThing = doThing

-- doThing and pings.doThing are 2 completely seperate values at this point, as the pings table has replaced the index at pings.doThing with a Java Function that wraps the doThing Lua Function.

-- <code>doThing==pings.doThing</code> will return <code>false</code>

print(doThing, pings.doThing, doThing == pings.doThing)

local keybindState = false

-- I call the local doThing instead of pings.doThing, as pings.doThing is a function that invokes network code.

-- This ensures that the default state is set correctly. If this was a ping function, both models will be visible for other clients until you press the keybind.

doThing(keybindState)

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()

keybindState = not keybindState

-- We still need to call the ping function in the keybind.

pings.doThing(keybindState)

end</syntaxhighlight>

The alternative is to reiterate the <code>models.modelA:setVisible(state) models.modelB:setVisible(not state)</code> part of the ping.<br/> For larger pings it will be combersome to rewrite code that is already defined, which is why this technique is useful.

<span id="byte-array"></span>

=== Byte Array ===
There are some situations where you will want to send a large amount of raw bytes, and you need to do it efficiently. The most efficient way is to send a string.

Asside from the 2 constant bytes for the length, a string will always be 1 byte per ascii character (UTF-8 characters are multiple ascii characters, interpreted as a single character). This makes it very consistent in terms of bytes, making it easy to predict and avoid being rate limited.

Below is a basic conversion of a byte array to a string, ready to be pinged and converted back into a byte array on the client’s end.

<syntaxhighlight lang="lua">function pings.recieveData(str)
local byteArray = table.pack(string.byte(str))
printTable(byteArray)
end

local packet=[]
for i=1,20 do
table.insert(packet, math.random(0,255))
end

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()
local packedString = string.char(table.unpack(packet))
pings.recieveData(packedString)
end
</syntaxhighlight>

Pings (Tutorial)

2024-09-27T04:34:58Z

PoolloverNathan: minor reformatting; mention leaving buffer room

With normal mods, there is comunication between the Minecraft Server and it’s clients which allows everything to stay in sync. <br/> Figura is completely client-side. It will never comunicate with the Minecraft Server you are connected to. Figura does not have a server-side component, meaning nothing will happen if you put the mod on a server.<br/>

----

What does this mean for you, the user? It means that certain functionality that only your client has access to will not be synced with other players.<br/> Some examples:

; Keybinds
: If the Minecraft Server tracked every single keystroke, it would be a major security issue. The exact keystrokes are never sent, only the result of those keystrokes.

; Action Wheel
: The Action Wheel is a feature added by Figura. Remember how I said that Figura never comunicates with the Minecraft Server? It should be obvious why the Action Wheel isnt synced.

; HostAPI
: The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent — some methods such as [[PlayerAPI/isGrounded]] feel the need to be ''special'')

So how can we sync information with other players if we cannot do it through the Minecraft Server? The answer is Pings.

== General Pings ==
Pings utilize Figura’s Backend to sync information with other clients. Pings are functions that when called, triggers all other clients to call the same function for their instance of your avatar.

=== Ping Rate Limiting ===
The backend restricts you on how much data you can send over a period of time. The developer given limits are:

* 1024 bytes per second
* 32 pings per second

If either of these are reached, the backend will ignore any comunication from you for some amount of time.

{{note|In some cases, fluctuations in network speed may cause some pings to become clumped close enough to reach this limit if they are slightly below. It's wise to leave a bit of buffer room just in case.}}

=== Pingable Values ===
Pings can send most primitive types and some userdata types.<br/> All pingable types use a single byte to represent the type of data that is being sent. This byte is not included in the listed byte totals.

* {{Type|nil}} - 0 Bytes
** if a type that is not supported is used as a parameter, it will be replaced with {{Type|nil}}.

* {{Type|boolean}} - 0 Bytes

* {{Type|integer}} - 1-4 Bytes
** {{Type|integers}} only take up as many bytes as they need.
** {{Type|integers}} are signed. For example, to only use a single byte the value must be between -128 and 127.

* {{Type|double}} - 8 Bytes
** If the number has a decimal at all, or is outside the range of a 4 byte {{Type|integer}}, it will be sent as a {{Type|double}}.

* {{Type|string}} - 2+n Bytes
** {{Type|strings}} will always use 2 bytes to store the length of the string.
** ASCII characters will be a single byte each.
** UTF-8 characters will be multiple bytes per character.
** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

* {{Type|table}} - (all keys) + (all values) Bytes
** Every key and value is send as data, resulting in high byte costs.
** It is recommended to never send a table over pings.

* {{Type|Vector}} - 1+8*N Bytes
** {{Type|Vectors}} use a single byte to store the size of the Vector.
** Vectors are always assumed to store {{Type|doubles}}. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.

* {{Type|Matrix}} - 2+8*W*H Bytes
** {{Type|Matrices}} store both the width and height of the matrix, then every value as a {{Type|double}}.

=== Ping ===
Below is an '''example''' ping.

<syntaxhighlight lang="lua">function pings.pingName(a)
print("Ping")
print(".")
print("Data Recieved:", a)
print(".")
print("Pong")
end
</syntaxhighlight>

It accepts a single variable, which it will print to the chat as an example.

To call it, just call it like any other lua function.
<syntaxhighlight lang="lua">
pings.pingName("This is a string wooooooooooooooooo")
</syntaxhighlight>

When you as the host call the ping, the function will execute for all other clients, regardless of their current state.

Do note that if a non-host client reaches a line where a ping gets called, it is completely ignored. No data is sent to the backend, and the contents of the ping will not be executed.

Ping functions can be passed into functions that expect a function as a parameter, such as Action <code>onToggle</code>.

<syntaxhighlight lang="lua">
actionVariable:onToggle(pings.pingName)
</syntaxhighlight>

Remember that we are passing the function itself as a variable. The below would be passing the ''return result'' of the ping function, which is nigh guarenteed to be <code>nil</code> as Pings ''should never'' return a value.

<syntaxhighlight lang="lua">
--do not do
actionVariable:onToggle(pings.pingName())</syntaxhighlight>

<span id="advanced-pings"></span>

== Advanced Pings ==

Situational techniques that may be handy, depending on the use case.

=== Ping on Init ===
Calling a ping function when the script is first loaded is a horrible idea. The ping will only ever execute for other clients when you, the host, load the avatar. Not only that, it may never be executed on other clients, as they might not have your avatar loaded by the time you broadcast the ping.

How do we get around this? Well, when you assign a function to an index in the <code>pings</code> table, the Lua Function gets replaced with a Java Function. This happens because of metatables, specifically the <code>__newindex</code> metamethod. Functions cannot be modified, so if we store the function before adding it to the <code>pings</code> table, we can use it like a regular function, and use the same code as a ping function.

<syntaxhighlight lang="lua">local function doThing(state)
models.modelA:setVisible(state)
models.modelB:setVisible(not state)
end

pings.doThing = doThing

-- doThing and pings.doThing are 2 completely seperate values at this point, as the pings table has replaced the index at pings.doThing with a Java Function that wraps the doThing Lua Function.

-- <code>doThing==pings.doThing</code> will return <code>false</code>

print(doThing, pings.doThing, doThing == pings.doThing)

local keybindState = false

-- I call the local doThing instead of pings.doThing, as pings.doThing is a function that invokes network code.

-- This ensures that the default state is set correctly. If this was a ping function, both models will be visible for other clients until you press the keybind.

doThing(keybindState)

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()

keybindState = not keybindState

-- We still need to call the ping function in the keybind.

pings.doThing(keybindState)

end</syntaxhighlight>

The alternative is to reiterate the <code>models.modelA:setVisible(state) models.modelB:setVisible(not state)</code> part of the ping.<br/> For larger pings it will be combersome to rewrite code that is already defined, which is why this technique is useful.

<span id="byte-array"></span>

=== Byte Array ===
There are some situations where you will want to send a large amount of raw bytes, and you need to do it efficiently. The most efficient way is to send a string.

Asside from the 2 constant bytes for the length, a string will always be 1 byte per ascii character (UTF-8 characters are multiple ascii characters, interpreted as a single character). This makes it very consistent in terms of bytes, making it easy to predict and avoid being rate limited.

Below is a basic conversion of a byte array to a string, ready to be pinged and converted back into a byte array on the client’s end.

<syntaxhighlight lang="lua">function pings.recieveData(str)
local byteArray = table.pack(string.byte(str))
printTable(byteArray)
end

local packet=[]
for i=1,20 do
table.insert(packet, math.random(0,255))
end

local keyA = keybinds:newKeybind("KeybindName", "key.keyboard.k")

function keyA.press()
local packedString = string.char(table.unpack(packet))
pings.recieveData(packedString)
end
</syntaxhighlight>