FiguraMC - User contributions [en]

Community Resources

2024-10-05T20:27:29Z

Joeyy: Undo revision 524 by Joeyy (talk)

{{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 <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:13:38Z

Joeyy: removed origins api; no license

{{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.
*ModdedSMP is a seasonal modpack server, each season coming with its own theme.

Below is the Vanilla FiguraSMP address since the Modded SMP is currently between seasons.
vanilla.figuramc.org
==='''4p5.nz''' 🛡️===
'''4p5.nz''' is an invite-only creative/operator server where players have free reign over the world around them.
4p5.nz

Avatar

2024-09-29T01:06:10Z

Joeyy: Redirected page to AvatarAPI

#REDIRECT [[AvatarAPI]]

Vectors

2024-09-29T01:05:43Z

Joeyy: Changed redirect target from Vectors (Global) to VectorsAPI

#REDIRECT [[VectorsAPI]]

Matrices

2024-09-29T01:05:14Z

Joeyy: Redirected page to MatricesAPI

#REDIRECT [[MatricesAPI]]

World

2024-09-29T01:04:32Z

Joeyy: Redirected page to WorldAPI

#REDIRECT [[WorldAPI]]

Vanilla model

2024-09-29T01:04:17Z

Joeyy: Redirected page to VanillaModelAPI

#REDIRECT [[VanillaModelAPI]]

User

2024-09-29T01:04:00Z

Joeyy: Redirected page to EntityAPI

#REDIRECT [[EntityAPI]]

Textures

2024-09-29T01:03:42Z

Joeyy: Redirected page to TextureAPI

#REDIRECT [[TextureAPI]]

Sounds

2024-09-29T01:03:29Z

Joeyy: Redirected page to SoundAPI

#REDIRECT [[SoundAPI]]

Resources

2024-09-29T01:03:15Z

Joeyy: Redirected page to ResourcesAPI

#REDIRECT [[ResourcesAPI]]

Renderer

2024-09-29T01:02:58Z

Joeyy: Redirected page to RendererAPI

#REDIRECT [[RendererAPI]]

Raycast

2024-09-29T01:02:16Z

Joeyy: Redirected page to RaycastAPI

#REDIRECT [[RaycastAPI]]

Player

2024-09-29T01:02:03Z

Joeyy: Redirected page to PlayerAPI

#REDIRECT [[PlayerAPI]]

Particles

2024-09-29T01:01:49Z

Joeyy: Redirected page to ParticleAPI

#REDIRECT [[ParticleAPI]]

Net

2024-09-29T01:01:32Z

Joeyy: Redirected page to NetworkingAPI

#REDIRECT [[NetworkingAPI]]

Keybinds

2024-09-29T00:57:26Z

Joeyy: redirect global to the type

#REDIRECT [[KeybindAPI]]

Json

2024-09-29T00:57:11Z

Joeyy: redirect global to the type

#REDIRECT [[JsonAPI]]

Host

2024-09-29T00:56:52Z

Joeyy: redirect global to the type

#REDIRECT [[HostAPI]]

Data

2024-09-29T00:56:06Z

Joeyy: redirect global to the type

#REDIRECT [[DataAPI]]

Client

2024-09-29T00:55:41Z

Joeyy: redirect global to the type

#REDIRECT [[ClientAPI]]

Nameplate

2024-09-29T00:55:10Z

Joeyy: redirect global to the type

#REDIRECT [[NameplateAPI]]

Animations

2024-09-29T00:53:22Z

Joeyy: redirect global to the type

#REDIRECT [[AnimationAPI]]

Action wheel

2024-09-29T00:53:04Z

Joeyy: redirect global to the type

#REDIRECT [[ActionWheelAPI]]

Main Page

2024-09-29T00:49:50Z

Joeyy: Slapping the doc navbox here until someone the main page better

{{Notice
|content=
<div style="font-size: 1.5em; font-weight: bold; margin: 0.5em 0 0 0;">This wiki is under heavy construction.</div>
{{#if:{{{extra|}}}|{{{extra}}}
}}To contribute to this wiki, see [[Special:WantedPages|Wanted Pages]], [[Special:WhatLinksHere/Template:Stub|Stubs]], and [[Contributing]].
|outline=#f2a03c
|background=#ffe8cc
}}
{{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}}

Template:Navbox documentation

2024-09-29T00:47:16Z

Joeyy: VectorsAPI and MatricesAPI

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Documentation
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[EventsAPI]]
* [[FileAPI]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[MatricesAPI]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[VectorsAPI]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}<noinclude>
Navbox for the bottom of all pages containing documentation.

== Usage==
<syntaxhighlight lang="WikiText">
{{Navbox documentation}}
</syntaxhighlight>
</noinclude>

Template:Navbox documentation

2024-09-28T20:46:36Z

Joeyy: Added EventsAPI

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Documentation
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[EventsAPI]]
* [[FileAPI]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}<noinclude>
Navbox for the bottom of all pages containing documentation.

== Usage==
<syntaxhighlight lang="WikiText">
{{Navbox documentation}}
</syntaxhighlight>
</noinclude>

Events

2024-09-28T20:45:48Z

Joeyy: Joeyy moved page Events to EventsAPI: Matching type name

#REDIRECT [[EventsAPI]]

EventsAPI

2024-09-28T20:45:48Z

Joeyy: Joeyy moved page Events to EventsAPI: Matching type name

{{#invoke:Distinguish|hatnote|Event}}
Events is a global which contains every {{Type|Event}}, which are fired when certain things happen. For example, if you want to count ticks, you can use the tick or world tick event.
<syntaxHighlight lang="lua">
local tick = 0

-- Register event
function events.TICK()
tick = tick + 1
end
-- or
events.TICK:register(function()
tick = tick + 1
end)
</syntaxHighlight>
Note that not everyone needs to count ticks

== Methods ==
{| class="wikitable"
|-
! Method
! Description
|-
| [[Events/getEvents|getEvents]]
| Returns a table of every event
|}

== Fields ==
{| class="wikitable"
|-
! Event
! Description
|-
| [[Events/ENTITY_INIT|ENTITY_INIT]]
| Runs when the player is loaded
|-
| [[Events/TICK|TICK]]
| Runs every tick the player is rendered
|-
| [[Events/WORLD_TICK|WORLD_TICK]]
| Runs every tick the world is rendered
|-
| [[Events/RENDER|RENDER]]
| Runs every frame the player is rendered
|-
| [[Events/POST_RENDER|POST_RENDER]]
| Runs every frame AFTER the player is rendered
|-
| [[Events/WORLD_RENDER|WORLD_RENDER]]
| Runs every frame the world is rendered
|-
| [[Events/POST_WORLD_RENDER|POST_WORLD_RENDER]]
| Runs every frame AFTER the world is rendered
|-
| [[Events/SKULL_RENDER|SKULL_RENDER]]
| Runs every frame for every skull when the skull is rendered.
|-
| [[Events/ARROW_RENDER|ARROW_RENDER]]
| Runs every frame for every arrow when rendered.
|-
| [[Events/TRIDENT_RENDER|TRIDENT_RENDER]]
| Runs every frame for every trident when rendered.
|-
| [[Events/ITEM_RENDER|ITEM_RENDER]]
| Runs every frame for every item when rendered.
|-
| [[Events/CHAT_SEND_MESSAGE|CHAT_SEND_MESSAGE]]
| Runs every time the player sends something in chat, including commands. Allows for changing the message
|-
| [[Events/CHAT_RECEIVE_MESSAGE|CHAT_RECEIVE_MESSAGE]]
| Runs every time the player receives something in chat. Allows for changing the message
|-
| [[Events/MOUSE_SCROLL|MOUSE_SCROLL]]
| Runs every time the mouse is scrolled. Allows for cancelling the vanilla function
|-
| [[Events/MOUSE_MOVE|MOUSE_MOVE]]
| Runs every time the mouse is moved. Allows for cancelling the vanilla function
|-
| [[Events/MOUSE_PRESS|MOUSE_PRESS]]
| Runs every time the mouse is clicked. Allows for cancelling the vanilla function
|-
| [[Events/KEY_PRESS|KEY_PRESS]]
| Runs every time a key is pressed. Allows for cancelling the vanilla function
|-
| [[Events/CHAR_TYPED|CHAR_TYPED]]
| Runs every time a character is typed.
|-
| [[Events/USE_ITEM|USE_ITEM]]
| Runs every time an item is used by the player.
|-
| [[Events/ON_PLAY_SOUND|ON_PLAY_SOUND]]
| Runs every time a sound is played
|-
| [[Events/RESOURCE_RELOAD|RESOURCE_RELOAD]]
| Runs every time resources are reloaded
|-
| [[Events/TOTEM|TOTEM]]
| Runs every time a totem of undying is activated
|-
| [[Events/DAMAGE|DAMAGE]]
| Runs whenever the player takes damage
|}

[[Category:Globals]]

Template:Navbox documentation

2024-09-28T20:43:36Z

Joeyy: Added FileAPI

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Documentation
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[FileAPI]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}<noinclude>
Navbox for the bottom of all pages containing documentation.

== Usage==
<syntaxhighlight lang="WikiText">
{{Navbox documentation}}
</syntaxhighlight>
</noinclude>

File

2024-09-28T20:42:30Z

Joeyy: redirect global to the type

#REDIRECT [[FileAPI]]

FileAPI

2024-09-28T20:41:47Z

Joeyy: added navbox

{{Host only|kind=API}}

<code>FileAPI</code> allows your avatar to access files in isolated folder.

FileAPI is available as global <code>file</code> variable.

== Security ==
FileAPI is fully isolated in your data folder. It is located in your Figura folder, so, default path for it would be <code>figura/data</code>. FileAPI can't access any files or directories out of this folder, even when using symbolic links. Attempt to access file or directory outside data folder will result in error.
Every used path in methods is relative to data folder.

== FileAPI methods ==

=== Security checks ===

Security related methods of FileAPI.

==== allowed ====
----
Checks if FileAPI usage is allowed for this avatar.

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

<syntaxhighlight lang="lua">
-- Prints false on non-host avatar.
print(file:allowed())
</syntaxhighlight>

==== isPathAllowed ====
----
Checks if path is allowed for usage.

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

<syntaxhighlight lang="lua">
-- Relative paths are always relative to data folder.
print(file:isPathAllowed("foo")) -- true
-- Relative paths that are pointing outside of data folder are not allowed.
print(file:isPathAllowed("../foo")) -- false
-- Absolute paths pointing to figura data folder are also allowed.
print(file:isPathAllowed("C:/path/to/figura/data/foo")) -- true
-- Absolute paths outside of data folder are not allowed.
print(file:isPathAllowed("C:/foo")) -- false
</syntaxhighlight>

=== Common ===

Methods related both to files and directories.

==== exists ====
----
Checks if specified path exists.

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

<syntaxhighlight lang="lua">
print(file:exists("foo.bar")) -- true
</syntaxhighlight>

==== delete ====
----
Deletes file or directory by specified path. Returns true if successful.

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

<syntaxhighlight lang="lua">
-- Directory fooBar is empty
print(file:delete("fooBar")) -- true
-- Directory barFoo has files inside
print(file:delete("barFoo")) -- false
-- foo.bar is not open by any program
print(file:delete("foo.bar")) -- true
-- bar.foo doesn't exist
print(file:delete("bar.foo")) -- false
</syntaxhighlight>

=== Directories ===

Directory related methods of FileAPI.

==== isDirectory ====
----
Checks if specified path is directory.

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

<syntaxhighlight lang="lua">
print(file:isDirectory("fooBar")) -- true
</syntaxhighlight>

==== mkdir ====
----
Creates directory by specified path. Returns true if successful.

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

<syntaxhighlight lang="lua">
print(file:exists("foo")) -- false
print(file:mkdir("foo")) -- true
print(file:exists("foo")) -- true
</syntaxhighlight>

'''@see''' [[#exists|exists]]

==== mkdirs ====
----
Creates directory by specified path, and all parent directories if they doesn't exist. Returns true if successful.

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

<syntaxhighlight lang="lua">
print(file:exists("foo/bar")) -- false
print(file:mkdir("foo/bar")) -- false
print(file:mkdirs("foo/bar")) -- true
print(file:exists("foo/bar")) -- true
</syntaxhighlight>

'''@see''' [[#exists|exists]], [[#mkdir|mkdir]]

==== list ====
----
Lists files and directories by specified path. Returns table with paths, or null if path doesn't exist or not a directory.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>list(path {{type|string}})</code>
| {{type|string|[]?}}
|}

<syntaxhighlight lang="lua">
printTable(file:list("")) --[[{
"foo.bar",
"fooBar",
"barFoo"
}]]
</syntaxhighlight>

=== Files ===
Methods related to files.

==== isFile ====
----
Checks if specified path is a file.

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

<syntaxhighlight lang="lua">
print(file:isFile("foo.bar")) -- true
</syntaxhighlight>

==== openReadStream ====
----
Open input stream for file at specified path. Throws an error if file doesn't exist.

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

<syntaxhighlight lang="lua">
-- Opens an input stream.
local is = file:openReadStream("foo.bar")

-- Stream must be closed when you finished working with it.
is:close()
</syntaxhighlight>

'''@see''' [[InputStream#close|InputStream:close]]

==== openWriteStream ====
----
Open output stream for file at specified path. Throws an error if unable to create a file.

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

<syntaxhighlight lang="lua">
-- Opens an output stream.
local os = file:openWriteStream("bar.foo")

-- Stream must be closed when you finished working with it.
os:close()
</syntaxhighlight>

'''@see''' [[OutputStream#close|OutputStream:close]]

==== readString ====
----
Reads file at specified path and returns it's contents as a string in specified encoding.
Default encoding is <code>utf8</code>.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>readString(path {{type|string}})</code>
| {{type|string}}
|-
| <code>readString(path {{type|string}}, encoding {{type|BufferEncoding}})</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
print(file:readString("foo.bar")) -- Hello, world!
</syntaxhighlight>

==== writeString ====
----
Writes string in specified encoding to file by specified path.
Default encoding is <code>utf8</code>.

{| class="wikitable"
! Arguments
|-
| <code>writeString(path {{type|string}}, contents {{type|string}})</code>
|-
| <code>writeString(path {{type|string}}, contents {{type|string}}, encoding {{type|BufferEncoding}})</code>
|}

<syntaxhighlight lang="lua">
print(file:writeString("foo.bar", "Hello, world!"))
</syntaxhighlight>

== Navigation ==
{{Navbox documentation}}

ConfigAPI

2024-09-28T20:41:20Z

Joeyy: added navbox

{{Host only|kind=API}}

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

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

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

== ConfigAPI Methods ==

=== Configuration Switching ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Navigation ==
{{Navbox documentation}}

ModelPart

2024-09-28T20:38:31Z

Joeyy: added navbox

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, <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 [[ParentType/Hud|<code>Hud</code> parts have special rules]]. Be careful!

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

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

Simply [[#Accessing_ModelParts|access]] the ModelPart, then call <code>setParentType</code> on it, passing in the ParentType as a string.
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("RightArm")
</syntaxhighlight>
To remove a ParentType from a ModelPart, call <code>setParentType</code> with the string <code>"None"</code>
<syntaxhighlight lang="lua">
local head = models.model.root.Head
head:setParentType("None")
</syntaxhighlight>
ModelParts <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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Expects a value between 0 and 1.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

root:setLight(12, 8)

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

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

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

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

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

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

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

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

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

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

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

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

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

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

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

root:setOverlay(8, 15)

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

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

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

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

== Navigation ==
{{Navbox documentation}}

Template:Navbox documentation

2024-09-28T20:34:54Z

Joeyy: didn't realize it'd already show

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Documentation
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}<noinclude>
Navbox for the bottom of all pages containing documentation.

== Usage==
<syntaxhighlight lang="WikiText">
{{Navbox documentation}}
</syntaxhighlight>
</noinclude>

Template:Navbox documentation

2024-09-28T20:34:24Z

Joeyy: Navbox!

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Documentation
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}<noinclude>
Navbox for the bottom of all pages containing documentation.

== Usage==
<syntaxhighlight lang="WikiText">
{{Navbox documentation}}
</syntaxhighlight>
== Example ==
{{Navbox documentation}}
</noinclude>

User:Joeyy/sandbox

2024-09-28T20:27:53Z

Joeyy: were navigating

<templatestyles src="Template:Flatlist/styles.css"/>
== Working on Navbox Template ==
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Wiki
|-
! scope="row" | Globals
|
<div class="hlist">
* [[action_wheel]]
* [[animations]]
* [[avatar]]
* [[client]]
* [[config]]
* [[data]]
* [[events]]
* [[figuraMetatables]]
* [[file]]
* [[host]]
* [[json]]
* [[keybinds]]
* [[listFiles]]
* [[matrices]]
* [[models]]
* [[nameplate]]
* [[net]]
* [[parseJson]]
* [[particles]]
* [[pings]]
* [[player]]
* [[print]]
* [[printJson]]
* [[printTable]]
* [[raycast]]
* [[renderer]]
* [[require]]
* [[resources]]
* [[sounds]]
* [[textures]]
* [[toJson]]
* [[type]]
* [[user]]
* [[vanilla_model]]
* [[vec]]
* [[vectors]]
* [[world]]
</div>
|-
! scope="row" | Types
|
<div class="hlist">
* [[Action]]
* [[ActionWheelAPI]]
* [[Animation]]
* [[AnimationAPI]]
* [[AvatarAPI]]
* [[Biome]]
* [[BlockState]]
* [[BlockTask]]
* [[Buffer]]
* [[ConfigAPI]]
* [[EntityAPI]]
* [[EntityNameplateCustomization]]
* [[EntityTask]]
* [[Event]]
* [[Future]]
* [[HostAPI]]
* [[HttpRequestBuilder]]
* [[InputStream]]
* [[ItemStack]]
* [[ItemTask]]
* [[JsonArray]]
* [[JsonBuilder]]
* [[JsonObject]]
* [[JsonSerializer]]
* [[Keybind]]
* [[Matrix2]]
* [[Matrix3]]
* [[Matrix4]]
* [[ModelPart]]
* [[NameplateCustomization]]
* [[NameplateCustomizationGroup]]
* [[OutputStream]]
* [[Page]]
* [[Particle]]
* [[ParticleAPI]]
* [[RendererAPI]]
* [[RenderTask]]
* [[Sound]]
* [[SoundAPI]]
* [[SpriteTask]]
* [[TextTask]]
* [[Texture]]
* [[TextureAtlas]]
* [[VanillaPart]]
* [[Vector2]]
* [[Vector3]]
* [[Vector4]]
* [[Vertex]]
* [[ViewerAPI]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
* [[BlockRaycastTypes]]
* [[Colors]]
* [[EntityPoses]]
* [[FluidRaycastTypes]]
* [[HeightmapTypes]]
* [[ItemDisplayModes]]
* [[Keybinds]]
* [[KeyIDs]]
* [[LoopModes]]
* [[ParentTypes]]
* [[PlayerModelParts]]
* [[PlayStates]]
* [[PostEffects]]
* [[Registries]]
* [[RenderModes]]
* [[RenderTypes]]
* [[StringEncodings]]
* [[TextureTypes]]
* [[UseActions]]
</div>
|}

== Option 1 ==

{| class="wikitable" width="100%"
! scope="col" colspan="2" | ModelPart Methods
|-
! scope="row" | [[#ModelPart Properties|ModelPart Properties]]
|
<div class="hlist">
* [[#ModelPart:getName|<code>getName</code>]]
* [[#ModelPart:getType|<code>getType</code>]]
</div>
|-
! scope="row" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|
<div class="hlist">
* [[#ModelPart:getParent|<code>getParent</code>]]
* [[#ModelPart:getChildren|<code>getChildren</code>]]
* [[#ModelPart:isChildOf|<code>isChildOf</code>]]
* [[#ModelPart:copy|<code>copy</code>]]
* [[#ModelPart:addChild|<code>addChild</code>]]
* [[#ModelPart:removeChild|<code>removeChild</code>]]
* [[#ModelPart:remove|<code>remove</code>]]
</div>
|-
! scope="row" | [[#Manipulation|Manipulation]]
|
<div class="hlist">
* [[#ModelPart:setPos|<code>setPos</code>]]
* [[#ModelPart:getPos|<code>getPos</code>]]
* [[#ModelPart:setRot|<code>setRot</code>]]
* [[#ModelPart:getRot|<code>getRot</code>]]
* [[#ModelPart:setScale|<code>setScale</code>]]
* [[#ModelPart:getScale|<code>getScale</code>]]
* [[#ModelPart:setPivot|<code>setPivot</code>]]
* [[#ModelPart:getPivot|<code>getPivot</code>]]
* [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
* [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
* [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
* [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
* [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
* [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
* [[#ModelPart:setMatrix|<code>setMatrix</code>]]
* [[#ModelPart:getTruePos|<code>getTruePos</code>]]
* [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
* [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
* [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
</div>
|}

== Option 2 ==

i think i hate this

{| class="wikitable" style="text-align: center"
! scope="row" | [[#ModelPart Properties|ModelPart Properties]]
|-
| [[#ModelPart:getName|<code>getName</code>]]
|-
| [[#ModelPart:getType|<code>getType</code>]]
|-
! scope="row" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|-
| [[#ModelPart:getParent|<code>getParent</code>]]
|-
| [[#ModelPart:getChildren|<code>getChildren</code>]]
|-
| [[#ModelPart:isChildOf|<code>isChildOf</code>]]
|-
| [[#ModelPart:copy|<code>copy</code>]]
|-
| [[#ModelPart:addChild|<code>addChild</code>]]
|-
| [[#ModelPart:removeChild|<code>removeChild</code>]]
|-
| [[#ModelPart:remove|<code>remove</code>]]
|-
! scope="row" | [[#Manipulation|Manipulation]]
|-
| [[#ModelPart:setPos|<code>setPos</code>]]
|-
| [[#ModelPart:getPos|<code>getPos</code>]]
|-
| [[#ModelPart:setRot|<code>setRot</code>]]
|-
| [[#ModelPart:getRot|<code>getRot</code>]]
|-
| [[#ModelPart:setScale|<code>setScale</code>]]
|-
| [[#ModelPart:getScale|<code>getScale</code>]]
|-
| [[#ModelPart:setPivot|<code>setPivot</code>]]
|-
| [[#ModelPart:getPivot|<code>getPivot</code>]]
|-
| [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
|-
| [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
|-
| [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
|-
| [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
|-
| [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
|-
| [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
|-
| [[#ModelPart:setMatrix|<code>setMatrix</code>]]
|-
| [[#ModelPart:getTruePos|<code>getTruePos</code>]]
|-
| [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
|-
| [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
|-
| [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
|}

== Option 3 ==

{| class="wikitable" style="text-align: center"
! scope="col" | [[#ModelPart Properties|ModelPart Properties]]
|-
|
<div class="hlist">
* [[#ModelPart:getName|<code>getName</code>]]
* [[#ModelPart:getType|<code>getType</code>]]
</div>
|-
! scope="col" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|-
|
<div class="hlist">
* [[#ModelPart:getParent|<code>getParent</code>]]
* [[#ModelPart:getChildren|<code>getChildren</code>]]
* [[#ModelPart:isChildOf|<code>isChildOf</code>]]
* [[#ModelPart:copy|<code>copy</code>]]
* [[#ModelPart:addChild|<code>addChild</code>]]
* [[#ModelPart:removeChild|<code>removeChild</code>]]
* [[#ModelPart:remove|<code>remove</code>]]
</div>
|-
! scope="col" | [[#Manipulation|Manipulation]]
|-
|
<div class="hlist">
* [[#ModelPart:setPos|<code>setPos</code>]]
* [[#ModelPart:getPos|<code>getPos</code>]]
* [[#ModelPart:setRot|<code>setRot</code>]]
* [[#ModelPart:getRot|<code>getRot</code>]]
* [[#ModelPart:setScale|<code>setScale</code>]]
* [[#ModelPart:getScale|<code>getScale</code>]]
* [[#ModelPart:setPivot|<code>setPivot</code>]]
* [[#ModelPart:getPivot|<code>getPivot</code>]]
* [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
* [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
* [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
* [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
* [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
* [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
* [[#ModelPart:setMatrix|<code>setMatrix</code>]]
* [[#ModelPart:getTruePos|<code>getTruePos</code>]]
* [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
* [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
* [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
</div>
|}

FileAPI

2024-09-28T19:53:03Z

Joeyy: /* FileAPI methods */ add hr

ConfigAPI

2024-09-28T19:52:15Z

Joeyy: Make consistent with other Type pages

ModelPart

2024-09-28T19:48:56Z

Joeyy: /* ModelPart Methods */ add hr

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* Head
* HEAD
* Head2
* HeadPhones

If you name a group the following, <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 [[#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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Expects a value between 0 and 1.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

root:setLight(12, 8)

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

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

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

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

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

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

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

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

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

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

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

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

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

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

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

root:setOverlay(8, 15)

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

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

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

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

Template:Args

2024-09-28T16:35:44Z

Joeyy: Table rows for Template:Method

|-
| <code>{{{name}}}({{{1}}})</code>
| {{{return|self: {{type|{{ROOTPAGENAME}}}}}}}

ModelPart

2024-09-28T05:41:13Z

Joeyy: /* ModelPart:getRot */ small typo

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:getRot()) --> vec(45,0,0)
</syntaxhighlight>
'''@see''' [[ModelParts#ModelPart:setRot|setRot]]

==== <code>ModelPart:setScale</code> ====
Sets the scale of the ModelPart. Scales the ModelPart around the PivotPoint.

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

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

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

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

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

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

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

==== <code>ModelPart:setPivot</code> ====
Sets the pivot point of the ModelPart. ''This overrides the pivot point defined in blockbench.'' It is recommended to use [[ModelParts#ModelPart:setOffsetPivot|setOffsetPivot]] instead.

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

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

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

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

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

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

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

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

==== <code>ModelPart:setOffsetRot</code> ====
Sets a rotation value that will be added to the ModelPart's rotation.

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

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

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

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

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

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

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

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

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

==== <code>ModelPart:setOffsetScale</code> ====
Sets a scale value that will be multiplied with the ModelPart's scale.

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

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

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

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

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

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

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

==== <code>ModelPart:setOffsetPivot</code> ====
Sets a value that will be added to the ModelPart's pivot point.

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

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

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

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

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

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

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

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

==== <code>ModelPart:setMatrix</code> ====
Allows you to manually define the matrix used for positioning this ModelPart. Returns self for method chaining.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Expects a value between 0 and 1.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

root:setLight(12, 8)

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

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

Valid values for whiteOverlay: 0-15

Valid values for hurtOverlay: 0-7

whiteOverlay is a gradually increasing white tint from 0 - 15

hurtOverlay is an unchanging red tint from 0 - 7.

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

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

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

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

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

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

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

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

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

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

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

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

root:setOverlay(8, 15)

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

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

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

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

User:Joeyy/sandbox

2024-09-28T05:38:25Z

Joeyy: option 1 + option 2 per duck suggestion

<templatestyles src="Template:Flatlist/styles.css"/>
== Working on Navbox Template ==
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Wiki
|-
! scope="row" | Types
|
<div class="hlist">
*[[vec]]
*[[action_wheel]]
*[[animations]]
*[[figuraMetatables]]
*[[nameplate]]
*[[world]]
*[[vanilla_model]]
*[[ModelParts]]
*[[player]]
*[[events]]
*[[keybinds]]
*[[vectors]]
*[[matrices]]
*[[client]]
*[[host]]
*[[avatar]]
*[[particles]]
*[[sounds]]
*[[renderer]]
*[[user]]
*[[pings]]
*[[textures]]
*[[config]]
*[[data]]
*[[file]]
*[[json]]
*[[resources]]
*[[net]]
*[[raycast]]
*[[type]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
*[[Keybinds]]
*[[ParentTypes]]
*[[RenderTypes]]
*[[TextureTypes]]
*[[KeyIDs]]
*[[EntityPoses]]
*[[ItemDisplayModes]]
*[[PostEffects]]
*[[PlayStates]]
*[[LoopModes]]
*[[Colors]]
*[[PlayerModelParts]]
*[[UseActions]]
*[[RenderModes]]
*[[StringEncodings]]
*[[BlockRaycastTypes]]
*[[FluidRaycastTypes]]
*[[HeightmapTypes]]
*[[Registries]]
</div>
|}

== Option 1 ==

{| class="wikitable" width="100%"
! scope="col" colspan="2" | ModelPart Methods
|-
! scope="row" | [[#ModelPart Properties|ModelPart Properties]]
|
<div class="hlist">
* [[#ModelPart:getName|<code>getName</code>]]
* [[#ModelPart:getType|<code>getType</code>]]
</div>
|-
! scope="row" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|
<div class="hlist">
* [[#ModelPart:getParent|<code>getParent</code>]]
* [[#ModelPart:getChildren|<code>getChildren</code>]]
* [[#ModelPart:isChildOf|<code>isChildOf</code>]]
* [[#ModelPart:copy|<code>copy</code>]]
* [[#ModelPart:addChild|<code>addChild</code>]]
* [[#ModelPart:removeChild|<code>removeChild</code>]]
* [[#ModelPart:remove|<code>remove</code>]]
</div>
|-
! scope="row" | [[#Manipulation|Manipulation]]
|
<div class="hlist">
* [[#ModelPart:setPos|<code>setPos</code>]]
* [[#ModelPart:getPos|<code>getPos</code>]]
* [[#ModelPart:setRot|<code>setRot</code>]]
* [[#ModelPart:getRot|<code>getRot</code>]]
* [[#ModelPart:setScale|<code>setScale</code>]]
* [[#ModelPart:getScale|<code>getScale</code>]]
* [[#ModelPart:setPivot|<code>setPivot</code>]]
* [[#ModelPart:getPivot|<code>getPivot</code>]]
* [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
* [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
* [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
* [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
* [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
* [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
* [[#ModelPart:setMatrix|<code>setMatrix</code>]]
* [[#ModelPart:getTruePos|<code>getTruePos</code>]]
* [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
* [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
* [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
</div>
|}

== Option 2 ==

i think i hate this

{| class="wikitable" style="text-align: center"
! scope="row" | [[#ModelPart Properties|ModelPart Properties]]
|-
| [[#ModelPart:getName|<code>getName</code>]]
|-
| [[#ModelPart:getType|<code>getType</code>]]
|-
! scope="row" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|-
| [[#ModelPart:getParent|<code>getParent</code>]]
|-
| [[#ModelPart:getChildren|<code>getChildren</code>]]
|-
| [[#ModelPart:isChildOf|<code>isChildOf</code>]]
|-
| [[#ModelPart:copy|<code>copy</code>]]
|-
| [[#ModelPart:addChild|<code>addChild</code>]]
|-
| [[#ModelPart:removeChild|<code>removeChild</code>]]
|-
| [[#ModelPart:remove|<code>remove</code>]]
|-
! scope="row" | [[#Manipulation|Manipulation]]
|-
| [[#ModelPart:setPos|<code>setPos</code>]]
|-
| [[#ModelPart:getPos|<code>getPos</code>]]
|-
| [[#ModelPart:setRot|<code>setRot</code>]]
|-
| [[#ModelPart:getRot|<code>getRot</code>]]
|-
| [[#ModelPart:setScale|<code>setScale</code>]]
|-
| [[#ModelPart:getScale|<code>getScale</code>]]
|-
| [[#ModelPart:setPivot|<code>setPivot</code>]]
|-
| [[#ModelPart:getPivot|<code>getPivot</code>]]
|-
| [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
|-
| [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
|-
| [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
|-
| [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
|-
| [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
|-
| [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
|-
| [[#ModelPart:setMatrix|<code>setMatrix</code>]]
|-
| [[#ModelPart:getTruePos|<code>getTruePos</code>]]
|-
| [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
|-
| [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
|-
| [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
|}

== Option 3 ==

{| class="wikitable" style="text-align: center"
! scope="col" | [[#ModelPart Properties|ModelPart Properties]]
|-
|
<div class="hlist">
* [[#ModelPart:getName|<code>getName</code>]]
* [[#ModelPart:getType|<code>getType</code>]]
</div>
|-
! scope="col" | [[#Editing ModelPart Hierarchy|Editing ModelPart Hierarchy]]
|-
|
<div class="hlist">
* [[#ModelPart:getParent|<code>getParent</code>]]
* [[#ModelPart:getChildren|<code>getChildren</code>]]
* [[#ModelPart:isChildOf|<code>isChildOf</code>]]
* [[#ModelPart:copy|<code>copy</code>]]
* [[#ModelPart:addChild|<code>addChild</code>]]
* [[#ModelPart:removeChild|<code>removeChild</code>]]
* [[#ModelPart:remove|<code>remove</code>]]
</div>
|-
! scope="col" | [[#Manipulation|Manipulation]]
|-
|
<div class="hlist">
* [[#ModelPart:setPos|<code>setPos</code>]]
* [[#ModelPart:getPos|<code>getPos</code>]]
* [[#ModelPart:setRot|<code>setRot</code>]]
* [[#ModelPart:getRot|<code>getRot</code>]]
* [[#ModelPart:setScale|<code>setScale</code>]]
* [[#ModelPart:getScale|<code>getScale</code>]]
* [[#ModelPart:setPivot|<code>setPivot</code>]]
* [[#ModelPart:getPivot|<code>getPivot</code>]]
* [[#ModelPart:setOffsetRot|<code>setOffsetRot</code>]]
* [[#ModelPart:getOffsetRot|<code>getOffsetRot</code>]]
* [[#ModelPart:setOffsetScale|<code>setOffsetScale</code>]]
* [[#ModelPart:getOffsetScale|<code>getOffsetScale</code>]]
* [[#ModelPart:setOffsetPivot|<code>setOffsetPivot</code>]]
* [[#ModelPart:getOffsetPivot|<code>getOffsetPivot</code>]]
* [[#ModelPart:setMatrix|<code>setMatrix</code>]]
* [[#ModelPart:getTruePos|<code>getTruePos</code>]]
* [[#ModelPart:getTrueRot|<code>getTrueRot</code>]]
* [[#ModelPart:getTrueScale|<code>getTrueScale</code>]]
* [[#ModelPart:getTruePivot|<code>getTruePivot</code>]]
</div>
|}

User:Joeyy/sandbox

2024-09-28T05:29:37Z

Joeyy: /* ModelPart Methods */

User:Joeyy/sandbox

2024-09-28T05:27:22Z

Joeyy: testing out navigation for Type pages

Main Page

2024-09-28T04:31:57Z

Joeyy: Better than nothing main page

{{Notice
|content=[https://figura-wiki.pages.dev <big>'''Looking for the old wiki? Click Here'''</big>]
}}

==Docs==
* [[ModelPart]]
* [[Events]]
* [[Event]]
* [[ConfigAPI]]
* [[Colors]]

==Tutorials==
* [[Pings (Tutorial)]]
* [[Blockbench]]
* [[Blinking]]

Models

2024-09-27T01:58:08Z

Joeyy: jk that didnt work 208 by Joeyy (talk)

#REDIRECT [[ModelParts]]

Models

2024-09-27T01:56:07Z

Joeyy: fix the capital M to match the global

{{DISPLAYTITLE:title}}
#REDIRECT [[ModelParts]]

Models

2024-09-27T01:52:43Z

Joeyy: redirect global to the type

#REDIRECT [[ModelParts]]

User:Joeyy/sandbox

2024-09-27T01:18:15Z

Joeyy: ModelPart real

<templatestyles src="Template:Flatlist/styles.css"/>
{| class="wikitable" width="100%"
! scope="col" colspan="6" | Wiki
|-
! scope="row" | Types
|
<div class="hlist">
*[[vec]]
*[[action_wheel]]
*[[animations]]
*[[figuraMetatables]]
*[[nameplate]]
*[[world]]
*[[vanilla_model]]
*[[ModelParts]]
*[[player]]
*[[events]]
*[[keybinds]]
*[[vectors]]
*[[matrices]]
*[[client]]
*[[host]]
*[[avatar]]
*[[particles]]
*[[sounds]]
*[[renderer]]
*[[user]]
*[[pings]]
*[[textures]]
*[[config]]
*[[data]]
*[[file]]
*[[json]]
*[[resources]]
*[[net]]
*[[raycast]]
*[[type]]
</div>
|-
! scope="row" | Enums
|
<div class="hlist">
*[[Keybinds]]
*[[ParentTypes]]
*[[RenderTypes]]
*[[TextureTypes]]
*[[KeyIDs]]
*[[EntityPoses]]
*[[ItemDisplayModes]]
*[[PostEffects]]
*[[PlayStates]]
*[[LoopModes]]
*[[Colors]]
*[[PlayerModelParts]]
*[[UseActions]]
*[[RenderModes]]
*[[StringEncodings]]
*[[BlockRaycastTypes]]
*[[FluidRaycastTypes]]
*[[HeightmapTypes]]
*[[Registries]]
</div>
|}