Blockbench - Revision history

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

2024-11-02T23:47:17Z

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

← Older revision		Revision as of 23:47, 2 November 2024
Line 76:		Line 76:
	; Loop Mode		; Loop Mode
	: This controls what happens when the animation reaches the end. There are 3 valid loop modes:		: This controls what happens when the animation reaches the end. There are 3 valid loop modes:
	: ~~<dl~~>
	~~: {{d\|~~Play Once\|The animation will stop immediately at the end. Note that badly-made animations may have a visible jump to their original position in this mode.}}		<div style="margin-left: var(--space-lg); margin-top: -1em">
	~~: {{d\|~~Hold On Last Frame\|The animation will hold the values from its last frame after ending. Note that while an animation is holding, it is still considered playing, so calling <code>:play()</code> again will do nothing.}}		; Play Once
	: ~~{{d\|Loop\|~~When the animation reaches its end, it will jump to the beginning. Note that the start and end frames should be the same in this mode, as there won't be an in-between animation.}}		: The animation will stop immediately at the end. Note that badly-made animations may have a visible jump to their original position in this mode.
	: </dl>		; Hold On Last Frame
			: The animation will hold the values from its last frame after ending. Note that while an animation is holding, it is still considered playing, so calling <code>:play()</code> again will do nothing.
			; Loop
			: When the animation reaches its end, it will jump to the beginning. Note that the start and end frames should be the same in this mode, as there won't be an in-between animation.
			</div>

	; Override		; Override

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

2024-11-02T22:56:35Z

Animation Properties: properly nested definition lists

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

	; Override		; Override

Riftlight: Blockbench capitalization consistency & some grammar

2024-09-27T03:22:39Z

Blockbench capitalization consistency & some grammar

PoolloverNathan: can we smite iOS users yet

2024-09-27T03:10:31Z

can we smite iOS users yet

← Older revision		Revision as of 03:10, 27 September 2024
Line 27:		Line 27:
	=== ParentTypes ===		=== ParentTypes ===

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

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

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

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

	=== Texture Suffix ===		=== Texture Suffix ===
Line 55:		Line 55:
	List of suffixes used by Figura:		List of suffixes used by Figura:

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

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

	; Loop Mode		; Loop Mode

PoolloverNathan: /* Animation Properties */ rewrite

2024-09-27T03:06:28Z

Animation Properties: rewrite

← Older revision		Revision as of 03:06, 27 September 2024
Line 71:		Line 71:
	<img src={require("@site/static/img/blockbench/animation_properties.png").default} width="500"></img><br/>		<img src={require("@site/static/img/blockbench/animation_properties.png").default} width="500"></img><br/>

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

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

	~~<code>~~Override~~</code> determines if~~ Mimic-type ~~<a href="..~~/~~enums~~/~~ModelPartParentTypes">~~ParentTypes~~</a> will~~ apply their ~~transformations~~ while this animation is playing. ~~It only effects ModelParts~~ that ~~have~~ a keyframe ~~in this animation~~. ~~Default <code>false</code> <br/><br/>~~		; Override
			: If this is enabled, Mimic-type [[Enums/ParentTypes\|Enums/ParentTypes]] won't apply their rotations while this animation is playing. Note that keyframes must be present on the specific channel for override to apply! For example, putting a keyframe on Head's rotation won't apply override to its position or scale, Body, or even other Heads.

	~~<code>~~Snapping~~</code> determines the snapping distance for keyframes~~. Holding ~~ctrl while moving a keyframe ignores~~ this. ~~<b>~~Figura ~~does not care about~~ this value~~</b>~~. ~~<br/><br/>~~		; Snapping
			: This sets what unit of time Blockbench will set animations to. Holding Ctrl allows you to bypass this. Figura ignores this value.

	~~<code>~~Anim Time Update~~</code>. I have no clue what this does in blockbench, but figura uses this~~ value ~~for determining~~ the ~~start offset~~. ~~In other words~~, ~~when you call <code>play</code>~~ this is the ~~time that figura will start~~ the animation at. This ~~allows~~ you ~~to put~~ keyframes ~~behind the start of~~ the animation ~~which can~~ help with ~~Cubic Interpolation keyframes~~. ~~Default is~~ <code>0</code>. ~~<br/><br/>~~		; Anim Time Update
			: ''Default value: 0''
			: This allows you to set the time Figura starts playing the animation at. For example, setting this to 2 skips the first 2 seconds of the animation. This lets you add keyframes before the animation to help with interpolations.
			: {{tagged\|Trivia\|In Molang (and, therefore, Blockbench), this sets the animation's time ''every tick'' to a Molang expression. In Figura, you can achieve the equivalent by calling <code>setTime</code> in a script.}}

	~~<code>~~Blend Weight~~</code> is a multiplier for every single~~ keyframe in the animation. ~~Not~~ very useful ~~as a property~~, but it can be ~~changed in script~~ to ~~raise~~ or ~~reduce the intensity~~ of animations. ~~Default is <code>1</code>. <br/><br/>~~		; Blend Weight
			: Every keyframe value in the animation is multiplied by this value. This isn't very useful itself, but can be used by scripts (for example, [[GSAnimBlend]]) to transition into or out of animations.

	~~<code>~~Start Delay~~</code> is~~ the time ~~it takes after calling <code>play</code> for~~ the ~~animation to actually start. Default is <code>0</code>~~. ~~<br/><br/>~~		; Start Delay
			: ''Default value: 0''
			: This delays the animation's start time by the given amount.

	~~<code>~~Loop Delay~~</code> is a property that only shows up with~~ the ~~Loop <code>Loop Mode</code>. It adds a delay between~~ the animation ~~ending, then starting~~ again. ~~Default~~ is ~~<code>0</code>~~. ~~<br/><br/>~~		; Loop Delay
			: ''Default value: 0''
			: This sets the amount of time the animation will pause at the end before it loops again. This is only relevant in Loop mode.

	=== Keyframe Expressions ===		=== Keyframe Expressions ===

PoolloverNathan: PoolloverNathan moved page BlockBench to Blockbench: Misspelled title: not how you spell blockbench

2024-09-27T02:04:35Z

PoolloverNathan moved page BlockBench to Blockbench: Misspelled title: not how you spell blockbench

← Older revision		Revision as of 02:04, 27 September 2024
(No difference)

PenguinEncounter: Remove extraneous IDs and paragraph breaks

2024-09-26T21:14:36Z

Remove extraneous IDs and paragraph breaks

Show changes

Manuel: Automated upload of converted .txt file.

2024-09-26T20:34:06Z

Automated upload of converted .txt file.

New page

import Emoji from ‘@site/src/components/Emoji’;

The basics on how to use Blockbench

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



== Project Properties ==

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

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

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

<div style="{{"clear":"both"}}">

</div>

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

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

<div style="{{"clear":"both"}}">

</div>

<code>Texture Size</code>. 

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



== ModelParts ==



=== ParentTypes ===

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



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

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



=== Meshes ===

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



== Textures ==



=== Local/External Textures ===

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

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

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

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



=== Texture Suffix ===

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

List of suffixes used by Figura:

* <code>_e</code>: This texture will be used as the Secondary Texture, also known as the [[../tutorials/Emissive%20Textures|Emissive Texture]], of the ModelPart. The Secondary RenderType of a ModelPart is by default <code>“EMISSIVE”</code>, but can be changed in script.

* <code>_n</code>: This texture will be used as the [https://en.wikipedia.org/wiki/Normal_mapping Normal Texture]. Do not confuse this with the Primary Texture. “Normal” means something very specific in modeling. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.

* <code>_s</code>: This texture will be used as the [https://en.wikipedia.org/wiki/Specularity Specular Texture]. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.

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

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



== Animations ==



=== Animation Properties ===

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

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

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

<code>Loop Mode</code> controls what happens when the animation stops. There are 3 valid loop modes: Play Once, Hold On Last Frame, and Loop. Play Once stops the animation once the animation ends. Hold On Last Frame keeps the animation values from the end of the animation. The animation is still technically playing. Loop sets the animation’s time to 0, or to the animation’s end if the animation is playing backwards. 

<code>Override</code> determines if Mimic-type <a href="../enums/ModelPartParentTypes">ParentTypes</a> will apply their transformations while this animation is playing. It only effects ModelParts that have a keyframe in this animation. Default <code>false</code> 

<code>Snapping</code> determines the snapping distance for keyframes. Holding ctrl while moving a keyframe ignores this. Figura does not care about this value. 

<code>Anim Time Update</code>. I have no clue what this does in blockbench, but figura uses this value for determining the start offset. In other words, when you call <code>play</code> this is the time that figura will start the animation at. This allows you to put keyframes behind the start of the animation which can help with Cubic Interpolation keyframes. Default is <code>0</code>. 

<code>Blend Weight</code> is a multiplier for every single keyframe in the animation. Not very useful as a property, but it can be changed in script to raise or reduce the intensity of animations. Default is <code>1</code>. 

<code>Start Delay</code> is the time it takes after calling <code>play</code> for the animation to actually start. Default is <code>0</code>. 

<code>Loop Delay</code> is a property that only shows up with the Loop <code>Loop Mode</code>. It adds a delay between the animation ending, then starting again. Default is <code>0</code>. 



=== Keyframe Expressions ===

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

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

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

They can be extracted via the following line:

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

Keyframe Expressions accept 2 different formats:

* A single lua expression that evaluates to a number

* A lua script that <code>returns</code> a number

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

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

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

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



=== Instruction Keyframes ===

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



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

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

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

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

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

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

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

← Older revision		Revision as of 03:22, 27 September 2024
Line 1:		Line 1:
	The basics on how to use Blockbench		The basics on how to use Blockbench

	Proper tutorials for ~~blockbench~~ can be found online. This page just explains Figura specific stuff. This page assumes you are using the Desktop version of ~~BlockBench~~, not the online app.<br/>		Proper tutorials for Blockbench can be found online. This page just explains Figura specific stuff. This page assumes you are using the Desktop version of Blockbench, not the online app.<br/>

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

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

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

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

	== ModelParts ==		== ModelParts ==
Line 31:		Line 31:
	=== <code>Blank</code> Texture ===		=== <code>Blank</code> Texture ===

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

	=== Meshes ===		=== Meshes ===
Line 41:		Line 41:
	=== Local/External Textures ===		=== Local/External Textures ===

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

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

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

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

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

	List of suffixes used by Figura:		List of suffixes used by Figura:
Line 104:		Line 104:
	=== Keyframe Expressions ===		=== Keyframe Expressions ===

	While ~~blockbench~~ supports Molang, '''Figura does not'''.<br/> To remedy this, Figura allows writing lua code into keyframe fields.<br/>		While Blockbench supports Molang, '''Figura does not'''.<br/> To remedy this, Figura allows writing lua code into keyframe fields.<br/>

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

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

	They can be extracted via the following line:		They can be extracted via the following line:
Line 133:		Line 133:
	=== Animation Features That Figura Does Not Care About ===		=== Animation Features That Figura Does Not Care About ===

	Below are features provided by ~~BlockBench~~ Animations that figura does not use when loading the bbmodel.<br/>		Below are features provided by Blockbench Animations that figura does not use when loading the bbmodel.<br/>

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