FiguraMC - User contributions [en]

Multiplayer Avatar Interaction

2025-01-30T12:30:08Z

Manuel: How to use avatar vars

Avatars can share values with one another to allow for interactions between them. An example of this would be the various petting scripts you can find in the community.

The basic princible works like this:
One avatar can store a value.
Another avatar can get this stored value and do something based on it.

To store a value that other avatars can read you use avatar:store(key, value)

For example
avatar:store("amount", 1)

Note: It is recommended to never store any UserData objects as this could lead to security issues! Best to only store primitives like numbers, strings, or regular tables!

Someone else can then read this value in their script by checking the avatarVars for each player.

for uuid, vars in pairs(world.avatarVars()) do
print(uuid)
printTable(vars)
end

So for our example you could read the "amount" which we set to 1 and show the player name as well:

for uuid, vars in pairs(world.avatarVars()) do
if vars["amount"] then
local playerName = uuid
for name, plr in pairs(world.getPlayers()) do
if plr:getUUID() == uuid then
playerName = name
end
end
print(playerName, "has amount of", vars[key])
end
end

Tutorials/Types/Tables

2024-09-26T20:45:22Z

Manuel: Automated upload of converted .txt file.

A table is a Lua value that can store values in specific keys. The act of getting a value from a table using a key is called “indexing”.



== Initialize Table ==

A table can be created using curly brackets.

<syntaxhighlight lang="lua">local t = {}</syntaxhighlight>



== Generic Indexing ==

<code>table[key]</code> is the way to index a table. You can either get what is currently at that key, or assign a value to that key. There is no limitation to what can be used as keys or values in a table. If you index a table with an unknown key, it will return <code>nil</code>. You can also use variables as a key to index a table using this method.

<syntaxhighlight lang="lua">local v = 6

t[2] = "number key, string value"

t["string key, table value"] = {}

t[false] = true

t[v] = "ree"

print(t[2]) --> "number key, string value"

print(t["reeee"]) --> nil

print(t["string key, table value"]) --> table 3be7a8</syntaxhighlight>



== String Indexing Shorthand ==

If that seems like a lot of work to index by a string, yes it is. <code>table.key</code> is the shorthand for indexing a table with a string. This has very specific restrictions for what the string can contain.

* Cannot start with a number (<code>t.2fort</code> will not work. Use <code>[]</code> indexing, or use a different string)

* Cannot contain spaces, periods, or other special characters

* Cannot be Lua Keywords (true, false, local, function)

<syntaxhighlight lang="lua">t.name = "Katt"

t.age = -1

t.gender = t.name

t.underscores_are_allowed = true</syntaxhighlight>



== Object Oriented Method Indexing ==

There is one more way to index a table. Many of the functions in Figura take in the object that called said function as the first parameter. This is because every object of the same type has the exact same functions. This is done via <code>table:key()</code>. 

<syntaxhighlight lang="lua">local posA = player:getPos()

local posB = player.getPos(player)</syntaxhighlight>



== Initialize Table with Values ==

You can assign values to keys when the table is initialized. Each key-value pair must be separated by a comma (<code>,</code>) 



<syntaxhighlight lang="lua">local a = {

[false] = 1,

["string with spaces"] = "string",

[v] = {

["a"] = 1,

["b"] = 2,

},

-- string shorthand rules still apply. This is equivalent to <code>["life"] = 42</code>

life = 42,

}</syntaxhighlight>

If you do not specify an index, the provided values will automatically be assigned a numeric index, starting at <code>1</code>. This is how arrays are handled in lua, just a table that acts as an array. A table array if you will. Unlike other languages, Lua arrays begin indexing at <code>1</code> and functions that take in an array expect the first element at <code>1</code>.



<syntaxhighlight lang="lua">local array = {

42, -- [1] = 42

36, -- [2] = 36

1024, -- [3] = 1024

1, -- [4] = 1

"string", -- [5] = "string"

v, -- [6] = v

t -- [7] = t

}

-- newlines are ignored, as with everything in lua

local array2 = { 42, 36, 1024, 1, "string", v, t }</syntaxhighlight>



== Iterating Over a Table ==

Iterating over a table is simple. You can iterate over every single index using <code>pairs</code>. This will go through every index, but it will be in an undefined order. <code>pairs</code> has 2 values it returns when used in a for loop: the current <code>key</code>, and the current <code>value</code> at that <code>key</code>. 

<syntaxhighlight lang="lua">for key, value in pairs(t) do

print(key, value)

end</syntaxhighlight>

If the order of the iteration is important, you can use <code>ipairs</code>, but it only goes over numerical indices. This is what you want to use for table arrays. It starts at index <code>1</code>, and increments by <code>1</code> until the table returns <code>nil</code>. When used in a for loop, <code>ipairs</code> returns the current index and the <code>value</code> at that <code>index</code>. 

<syntaxhighlight lang="lua">for index, value in ipairs(array) do

print(index, value)

end</syntaxhighlight>



== Length of Table Array ==

You can use the <code>#</code> operator to get the length of a table array. For tables with non-numeric indexes, you have to use <code>pairs</code> and calculate the length yourself, though the “length” of that kind of table isnt really useful. This follows the same rules as <code>ipairs</code> in the way that the table’s length is every numeric index until one returns <code>nil</code>. So <code>#{1,2,3,4}</code> will return <code>4</code>, and <code>#{1,2,nil,4}</code> will return <code>2</code>. As an example, <code>ipairs</code> is pretty much just this.

<syntaxhighlight lang="lua">for index = 1, #array, 1 do

print(index, array[index])

end</syntaxhighlight>



== Manipulating Table Arrays ==

Lua comes built in with ways to manipulate tables. Not all are described here, just the ones that I feel are most important. All of these functions are available via the <code>tables</code> global.



=== <code>table.insert(t, pos, value)</code> ===

This function can add a value at any index, shifting the other values to account for the added value. <code>table.insert(array, 1, “e”)</code> will insert <code>“e”</code> at the beggining of the table <code>array</code>, shifting every other value forward one index. When adding elements to the end of the array, you use the function as <code>table.insert(t, value)</code>. So <code>table.insert(array, “l”)</code> appends <code>“l”</code> to the end of the table <code>array</code>.



=== <code>table.remove(t, pos)</code> ===

This function can remove a value at any index, shifting the other values to account for the removed value. The value that was removed will be returned by this function as well. <code>table.remove(array, 1)</code> will remove the value at index <code>1</code> from the table, shifting all the values back an index. <code>pos</code> is optional, with the default value being <code>#t</code>. <code>table.remove(array)</code> will remove the last value in the table.

Tutorials/Types/Strings

2024-09-26T20:45:21Z

Manuel: Automated upload of converted .txt file.

A string is a Lua value that represents a sequence of characters.

Strings are not interpreted as code and are treated as literally being characters.

Strings are used with quotation marks (“)

Examples:

<syntaxhighlight lang="lua">"hello" -- this is a string, as identified by the quotes bracketing it

hello -- not a string</syntaxhighlight>

Tutorials/Types/Numbers

2024-09-26T20:45:21Z

Manuel: Automated upload of converted .txt file.

A number is a Lua value that represents a real number.

Although Lua doesn’t have an integer type, some methods may ask for integers, this means they want a whole number.

Tutorials/Types/Functions

2024-09-26T20:45:20Z

Manuel: Automated upload of converted .txt file.

A function contains code that can be executed by calling the function. This is useful if you want to use the same code multiple times and can make your code more structured.

To define a function you use the function keyword, then the name of the function and ().

Any code after it will be considered inside this function, until you tell lua that the function is done here by using the end keyword. For better readability we indent the code inside the function using spaces or tabs.

The print statement will not execute until the function is called.

<syntaxhighlight lang="lua">function hello()

print("Hello function!")

end</syntaxhighlight>

Whenever you call a function by putting () after the function name, all the code inside the function will run line by line first, before continuing with the rest of your code.

<syntaxhighlight lang="lua">print("Outside.")

hello()

print("Below hello.")</syntaxhighlight>

This will output the following:

<syntaxhighlight lang="lua">"Outside."

"Hello function!"

"Below hello."</syntaxhighlight>

You can also give the function some values to work with by putting variable names inside the (). These variables are called parameters. The function can also return a new value itself that is accessible from where the function is called. If no return is specified, the function returns nil (see “Types” section below). Here is an example of a function that calculates the sum of two numbers.



<syntaxhighlight lang="lua">function sum(a, b) -- parameters seperated by commas

local s = a + b -- calculate the sum

return s -- return the sum to be used by the caller

end

local var1 = 2

local var2 = 8

local var3 = sum(var1, var2) -- call the function and pass two variables. note that these do not have to be called a and b

print(var3) --> 10, as you might have noticed, `print` is also a function that takes a parameter</syntaxhighlight>

Some functions are called by Figura, you’re probably familiar with events.

<syntaxhighlight lang="lua">function events.render(delta, context)

log(context)

end</syntaxhighlight>

In this case the function is run once a frame (per context) and the parameters are supplied by Figura.

Sometimes functions are used as parameters for methods, like setOnLeftClick for actions, and setOnPress for keybinds. Since those methods call the given function (and thus don’t need a name to call them) they can be given anonymous functions. Anonymous functions are simply functions without names.

<syntaxhighlight lang="lua">myKey:setOnPress(function()

log("hi")

end)</syntaxhighlight>

Tutorials/Types/Booleans

2024-09-26T20:45:19Z

Manuel: Automated upload of converted .txt file.

A boolean is a Lua value that is either <code>true</code> or <code>false</code>.

Additionally, Lua treats all values as if they’re ‘truthy’ or ‘falsey’.

If a value is truthy and it’s in an if statement or a function that wants a boolean value, it’s treated like it’s true.

Example:

<syntaxhighlight lang="lua">if 0 then

log("truthy") -- numbers are truthy so this will always be logged

else

log("falsey")

end</syntaxhighlight>

If a value is falsey and it’s in an if statement or a function that wants a boolean value, it’s treated like it’s false.

Example:

<syntaxhighlight lang="lua">if nil then

log("truthy")

else

log("falsey") -- nil is falsey so this will always be logged

end</syntaxhighlight>

The only values that are falsey are false and nil, every other value (numbers, tables, modelparts, etc) is truthy. (nil as a value means there’s no information. It’s literally nothing)

The <code>not</code> operator flips the truthiness of the value into true or false.

Examples (all of these are true statements):

<syntaxhighlight lang="lua">not true == false

not false == true

not nil == true -- a non-boolean value is turned into a boolean

not models == false -- models is a modelpart and truthy, so flipping it turns it into false</syntaxhighlight>

When used in methods <code>true</code> usually activates something, and <code>false</code> deactivates it. However in some places returning true may turn something off, always read the description of a method, field, or event to discover what boolean does what.

Tutorials/Sounds

2024-09-26T20:45:15Z

Manuel: Automated upload of converted .txt file.

Playing sounds tutorial

Using Figura you can play custom sounds and sounds from Minecraft itself.

This article assumes you know to avoid calling the player in init.



== Playing A Sound ==

The most common way to play a sound is through the <code>playSound</code> function in the sound API.

<syntaxhighlight lang="lua">sounds:playSound(soundID, position, volume, pitch, loop)</syntaxhighlight>

As you can see this function takes five arguments, the sound ID, the position it will be played, the volume (this dictates how close players need to be to hear the sound, default is 1), its pitch (default is 1), and whether or not it will start playing immediately after it ends (default is false).

For Minecraft sounds the sound ID is the internal name of the sound, you can find these on the [https://minecraft.wiki/w/Sounds.json/Java_Edition_values Minecraft Wiki] under the Sound Event column. It will play one of the sounds associated with that ID at random.

Example, note that the id is a string because it’s in quotes:

<syntaxhighlight lang="lua">sounds:playSound("entity.bat.ambient", player:getPos())</syntaxhighlight>

For this example I’m supplying the player position as the location or else it will play at (0,0,0) in the world itself. Because I left out the volume, pitch, and loop, the default values of 1, 1, and false were filled in by Figura. Meaning, it will play with default pitch, default volume, and it won’t loop.

Example with the other arguments filled:

<syntaxhighlight lang="lua">sounds:playSound("entity.bat.ambient", player:getPos(), 1, 1, false)</syntaxhighlight>



== Custom Sounds ==

Playing a custom sound is exactly the same as playing a Minecraft sound, except the sound ID is now the name of the sound file.

Ex: If your file is <code>horn.ogg</code> then your playSound line would look like this:

<syntaxhighlight lang="lua">sounds:playSound("horn", player:getPos())</syntaxhighlight>

Minecraft will only play specific sound files, namely sounds that are .ogg files. Here’s an [https://audio.online-convert.com/convert-to-ogg online OGG converter]. You will want to change the audio channels setting to <code>mono</code> and the audio codec to <code>Vorbis</code>.

If your custom sound is stored in a subfolder in the avatar, the subfolder name gets added onto the sound name like this:

<syntaxhighlight lang="lua">sounds:playSound("subfolder.horn", player:getPos())</syntaxhighlight>



=== Mono vs Stereo Sounds ===

The audio channel type determines if the right and left ear will have two separate channels (meaning that the left and right ears can be different) or if they’ll have the same channel for both ears.

Mono sounds are half the size of stereo when it comes to file size. Mono also acts like your average vanilla sound meaning only people near you will be able to hear the sound.

Stereo sounds are much bigger (and sounds are already quite big when it comes to file size) and will play for ''everyone in the server'' similarly to activating an end portal. There’s no way to get around that other than to swap the audio channels to mono.



== Alternative Ways To Play Sounds ==

If you want to make a long or looping sound follow your movement you’re going to need to use a different method for playing sounds.

You have to store a reference to the sound in a variable so you can use it later

<syntaxhighlight lang="lua">local wDeath = sounds["entity.wither.death"]</syntaxhighlight>

Now you have the wither death sound available for your use wherever within that local scope.

<syntaxhighlight lang="lua">wDeath:play():loop(true)</syntaxhighlight>

Will play the sound and make it loop, but without a position it will be at (0,0,0) in the world.

<syntaxhighlight lang="lua">function events.tick()

wDeath:pos(player:getPos())

end</syntaxhighlight>

Full example:

<syntaxhighlight lang="lua">local wDeath = sounds["entity.wither.death"]

wDeath:play():loop(true)

function events.tick()

wDeath:pos(player:getPos())

end</syntaxhighlight>

You can alter the volume, pitch, and loop with this method as well.

Pings (Tutorial)

2024-09-26T20:45:13Z

Manuel: Automated upload of converted .txt file.

Information on pings

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

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

* Keybinds 

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

* Action Wheel 

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

* HostAPI 

** The HostAPI exclusivly contains variables that only you, the owner of the avatar and the owner of the machine running Minecraft, has access to. All functions contained within are vanilla variables that are not synced with the Minecraft Server. They are wrapped in a nice, explicit package stating that they are never synced. This is unlike the PlayerAPI, which you can assume is always synced (to some extent (I’m looking at you <code>isGrounded</code>))

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



== General Pings ==

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



=== Ping Rate Limiting ===

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

* 1024 bytes per second

* 32 pings per second

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



=== Pingable Values ===

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

* <code>nil</code> - 0 Bytes

** if a type that is not supported is used as a parameter, it will be replaced with <code>nil</code>.

* <code>boolean</code> - 0 Bytes

* <code>integer</code> - 1-4 Bytes

** <code>integers</code> only take up as many bytes as it needs.

** <code>integers</code> are signed. For example, to only use a single byte the value must be between -128 and 127.

* <code>double</code> - 8 Bytes

** If the number has a decimal at all, or is outside the range of a 4 byte <code>integer</code>, it will be sent as a <code>double</code>.

* <code>string</code> - 2+n Bytes

** <code>strings</code> will always use 2 bytes to store the length.

** Ascii characters will be a single byte each.

** UTF-8 characters will be multiple bytes per character.

** The absolute maximum size of string you can send is <code>65535</code> characters. If a larger string is sent, it will be truncated.

* <code>table</code> - Too Many Bytes

** Every key and value is send as data, resulting in high byte costs.

** It is recommended to never send a table over pings.

* <code>VectorN</code> - 1+8*N Bytes

** Vectors have a single byte that stores the size of the Vector.

** Vectors are always assumed to store <code>doubles</code>. If you have a Vector of integers, I recommend sending them as 3 seperate arguments instead.

* <code>MatrixN</code> - 2+8*W*H Bytes

** Matrices store both the width and height of the matrix, then every value as a <code>double</code>.



=== Ping ===

Below is an example ping.

<syntaxhighlight lang="lua">function pings.pingName(a)

print("Ping")

print(".")

print("Data Recieved:", a)

print(".")

print("Pong")

end</syntaxhighlight>

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

To call it, just call it like any other lua function.

<syntaxhighlight lang="lua">pings.pingName("This is a string wooooooooooooooooo")</syntaxhighlight>

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

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

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

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

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

<syntaxhighlight lang="lua">--do not do

actionVariable:onToggle(pings.pingName())</syntaxhighlight>



== Advanced Pings ==

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



=== Ping on Init ===

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

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

<syntaxhighlight lang="lua">local function doThing(state)

models.modelA:setVisible(state)

models.modelB:setVisible(not state)

end

pings.doThing = doThing

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

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

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

local keybindState = false

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

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

doThing(keybindState)

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

function keyA.press()

keybindState = not keybindState

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

pings.doThing(keybindState)

end</syntaxhighlight>

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



=== Byte Array ===

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

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

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

<syntaxhighlight lang="lua">function pings.recieveData(str)

local byteArray = table.pack(string.byte(str))

printTable(byteArray)

end

local packet=[]

for i=1,20 do

table.insert(packet, math.random(0,255))

end

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

function keyA.press()

local packedString = string.char(table.unpack(packet))

pings.recieveData(packedString)

end

</syntaxhighlight>

Tutorials/Particles

2024-09-26T20:45:11Z

Manuel: Automated upload of converted .txt file.

Spawning particles tutorial

Using the particle API you can spawn particles from Minecraft. These work similarly to the <code>/particle</code> command in-game. For particles with special properties like dust, they are placed in the name.

Most of the article assumes you know to avoid calling the player in init.



== Spawning Particles ==

<syntaxhighlight lang="lua">particles:newParticle(particleID, position, velocity)</syntaxhighlight>

If you’re looking at the [https://minecraft.wiki/w/Particles Minecraft wiki] then the particle id is the name under the ‘Java Edition ID Name’ column. Or, it’s the same id used by the /particle command. If you’re using Minecraft particles you can exclude the Minecraft “mod name”.

<syntaxhighlight lang="lua">particles:newParticle("minecraft:explosion", player:getPos())</syntaxhighlight>

I’ve added the player position, but excluded the velocity.

Dust example, it’s color is included in its name:

<syntaxhighlight lang="lua">particles:newParticle("dust 0 1 1 1", player:getPos())</syntaxhighlight>

This will spawn an aqua dust particle as the color values need a number between 0 and 1, the fourth number is the alpha. I excluded the ‘minecraft:’ mod name to demonstrate that it’s unnecessary.



== Spawning At A Part Location ==

To spawn a particle at a modelPart’s position you’ll need to get the position matrix of that part, and insert it into the position like normal.

<syntaxhighlight lang="lua">particles:newParticle("explosion", modelPart:partToWorldMatrix():apply())</syntaxhighlight>

Where <code>modelPart</code> is a reference to a real modelPart in your avatar.



== An Alternative Method ==

You can store a reference to a specific particle, and then use it later to change its properties wile it still exists in the world.

<syntaxhighlight lang="lua">local boom = particles["explosion"]

function events.entity_init()

boom:spawn():setPos(player:getPos())

end</syntaxhighlight>

It’s in an entity_init event to protect from an entity init error



== Community Resources ==



=== Confetti by Manuel ===

Spawns custom particles that you make in Blockbench. [https://github.com/Manuel-3/figura-scripts/tree/main/src/confetti Find it here on GitHub]

Tutorials/ModelPart Indexing

2024-09-26T20:45:11Z

Manuel: Automated upload of converted .txt file.

import Emoji from ‘@site/src/components/Emoji’; import FileTreeRoot from ‘@site/src/components/FileTree/Root’; import FileTreeNode from ‘@site/src/components/FileTree/Node’;

This page describes the process to access any ModelPart from the global ModelPart <code>models</code>



= Getting a ModelPart =

A property of all ModelParts is that you can get a child ModelPart of a parent ModelPart by [[tutorials/types/Tables#generic-indexing|indexing]] the parent with the child’s name. <code>models</code> itself is a ModelPart. All bbmodel files in the avatar act as child ModelParts to <code>models</code>. Everything in the root of a Blockbench project is a child of the bbmodel ModelPart. After that, parenting follows the parent structure as defined in the Blockbench OUTLINER. For example the cube <Emoji icon="blockbench/cube"/> <code>RightArm</code>, 

<FileTreeRoot> <FileTreeNode label="model.bbmodel" icon="file/bbmodel"> <FileTreeNode label="Head" icon="blockbench/group"> <FileTreeNode label="Head" icon="blockbench/cube"/> <FileTreeNode label="Head Layer" icon="blockbench/cube"/> </FileTreeNode> <FileTreeNode label="RightArm" icon="blockbench/group"> <FileTreeNode label="RightArm" icon="blockbench/cube"/> <FileTreeNode label="RightArm Layer" icon="blockbench/cube"/> </FileTreeNode> </FileTreeNode> </FileTreeRoot>

Would be accessed via <code>models.model.RightArm.RightArm</code>



== Figura Model Format ==

Using the Figura Model Format Blockbench plugin you can right click a group/cube/mesh and copy the path to your clipboard.

To use the plugin open Blockbench and go to <code>File</code> in the upper left, and go down to the <code>Plugins…</code> option, you can find <code>Figura Model Format</code> there.

Once the plugin is installed, open the Blockbench project and go back to <code>File</code> and then <code>Convert Project</code>. Choose the <code>Figura Model</code> format and press confirm.

After that’s complete you can right click on a group/cube/mesh and copy the path to your clibboard. Note that this path will not include any subfolders the Blockbench model is in.



= Storing a ModelPart =

As there is nothing special about indexing straight from <code>models</code> all the time (its just another ModelPart), if a specific ModelPart is used multiple times in a script we can store it in a variable for ease of access.

<syntaxhighlight lang="lua">--sets a World parented part to match the player's position and body rotation

local worldPart = models.model.World

function events.RENDER(delta, context)

worldPart:setPos(player:getPos(delta) * 16)

worldPart:setRot(0, -player:getBodyYaw(delta) + 180, 0)

end</syntaxhighlight>



= BBmodels in subfolders =

bbmodel files in subfolders are a special case. For them, the folder itself acts as another ModelPart. 

<FileTreeRoot> <FileTreeNode label="subfolderA" icon="file/folder"> <FileTreeNode label="Pet.bbmodel" icon="file/bbmodel"/> <FileTreeNode label="bow.bbmodel" icon="file/bbmodel"/> </FileTreeNode> <FileTreeNode label="subfolderB" icon="file/folder"> <FileTreeNode label="model.bbmodel" icon="file/bbmodel"/> <FileTreeNode label="bow.bbmodel" icon="file/bbmodel"/> </FileTreeNode> </FileTreeRoot>

The bbmodel <Emoji icon="file/bbmodel"/> <code>Pet.bbmodel</code> would be accessed by <code>models.subfolderA.Pet</code>.

Tutorials/Keybinds

2024-09-26T20:45:09Z

Manuel: Automated upload of converted .txt file.

Keybind tutorial

Through Figura’s keybind API you can have the script listen for key presses to make things happen. Common uses are to trigger animations or toggle modelParts on and off.

Keybinds are unsynced information, meaning that without a ping other players cannot know that you pressed a key at all. This guide will be using pings with all the example keybinds.

'''Note: Keybinds can be used while the player is unloaded (aka you are out of render distance), if the player API is called during this time your script will error.''' You can protect yourself from these errors by adding this check: <code>if not player:isLoaded() then return end</code> as the first line of code run '''''inside the ping.'''''



== Example Keybind ==

First things first, you need to initialize the keybind

<syntaxhighlight lang="lua">local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h")</syntaxhighlight>

At this point, the keybind will show up in the avatar’s keybind list- accessible via the Figura menu- with the name Keybind Name and assigned to the letter H. But pressing H won’t do anything yet.

More keybinds ids can be found in the [[../enums/Keybinds-List.md|KeybindsList]] page

There are multiple ways to detect keybinds, but the most common is through <code>press</code> and <code>release</code> as they are easiest to ping. If you’re not familiar with pings see [[./Pings|Pings]].

Underneath creating the key we will be tying the press of the key to a ping function. It’s done underneath as the code is read top-down and the key must exist first.

<syntaxhighlight lang="lua">local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h", false)

exampleKey.press = pings.examplePing</syntaxhighlight>

This itself won’t do anything until we create the function pings.examplePing, this must be done above where press is assigned to the ping function, because the ping function will need to exist before it can be assigned. If it’s done beneath nothing will happen.

The false at the end decides whether or not the keybind will function while a gui like the inventory is opening. It can be skipped and the value will be considered false. If it’s set to true then this keybind will run even while any gui is open or closed.

<syntaxhighlight lang="lua">function pings.examplePing()

log("Pressed!")

end

local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h")

exampleKey.press = pings.examplePing</syntaxhighlight>

And there we have it! Now this keybind will send Pressed! in chat every time H is pressed. At this point you could put whatever lines of code you wish into the ping function and it will be synced.

Alternatively, <code>release</code> will run the keybind when the key is released rather than when it is first pressed.



== Toggling With A Keybind ==

This is going to look extremely similar to the last example, but we are going to add in a boolean that we’re toggling

<syntaxhighlight lang="lua">local keybindState = true

-- Here the keybindState is true, meaning the first press will swap it to false

-- If you wish the first press to swap to false, change the true to false above

function pings.examplePing(state)

log("state is " .. tostring(state))

models:setVisible(state)

-- This will toggle the visibility of all or models, add in a model path to turn on/off specific modelParts

-- animations.bbmodelName.animationName:setPlaying(not state)

-- And this is an example of toggling an animation on/off, I'm using not state here because the first press will set this toggle to false and thusly stop the animation, swapping the boolean value like this will make the first press play it

end

local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h")

exampleKey.press = function()

keybindState = not keybindState

-- This not is flipping the boolean value between true and false

pings.examplePing(keybindState)

end

-- This time .press is being tied to a function that is then calling the ping, instead of being 'attached' to it directly.</syntaxhighlight>



== Detecting When A Key Is Held Down ==

If you have the know-how it is possible to use the <code>isPressed()</code> function to detect when a key is being held down, but it’s not recommended, as using press and release in conjunction is far more effective.

<syntaxhighlight lang="lua">local keybindState = false

-- keybindState is the variable you will be using to keep track of the pressed-ness of the keybind

function pings.examplePing(state)

keybindState = state

-- keybindState is made equivalent to the state sent by press or release for use in other parts of the script

end

local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.h")

exampleKey.press = function()

pings.examplePing(true)

end

-- Here, examplePing is sending the boolean value true to the ping function

exampleKey.release = function()

pings.examplePing(false)

end

-- When it's released, the boolean value false will be sent, indicating that the key is no longer being pressed

-- This is unnecessary, but can be used to track the state of keybindState so you can see it working, at this point you can use keybindState wherever and however you wish- as long as it's in the same script file

function events.tick()

log(keybindState)

end</syntaxhighlight>



== Canceling A Key Press ==

A key press can be “cancelled” (Minecraft won’t register it as being pressed) using <code>return</code>. Specifically, if you <code>return true</code> in the function for the key press it will cancel the press. Returning a non-truthy value will not cancel the key press, so you can use a toggling variable to control the return. Note that returning in the ping will not cancel the key press, only doing it inside the keybind’s press function will cancel it.

Below is an example for cancelling the detection of the <code>w</code> key while also sending a ping.



<syntaxhighlight lang="lua">function pings.examplePing()

log("Pressed!")

end

local exampleKey = keybinds:newKeybind("Keybind Name", "key.keyboard.w")

exampleKey.press = function()

pings.examplePing() return true

end</syntaxhighlight>

If you want to cancel without sending a ping, that is completely possible. But the return always has to be at the end of the function.



== Using A Vanilla Keybind ==

If you want to detect a vanilla action like attacking or walking forwards but want it to be compatible in the case that someone bound forward to an arrow key you can directly get the vanilla keybind and use it. There’s multiple ways to accomplish this but we’ll use the same method as previous examples.

<syntaxhighlight lang="lua">local exampleKey = keybinds:newKeybind("Keybind Name", keybinds:getVanillaKey("key.forward"))</syntaxhighlight>

This will now detect the forward key regardless of what it’s bound to. <code>getVanillaKey()</code> is going to need a key id from a specific list of ids that all correspond to a vanilla keybind. They can be found in the [[../enums/KeyIDs.md|keyIDs]] enum.

Tutorials/Emissive Textures

2024-09-26T20:45:09Z

Manuel: Automated upload of converted .txt file.

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

This page describes everything to know about Emissive Textures.



== Defining a Texture as Emissive ==

Every ModelPart in BlockBench has a reference to a single texture. When Figura loads the avatar, Figura looks for a texture with the same name as the texture used by the ModelPart but with <code>_e</code> added to the end of it. For example, the emissive texture used by ModelParts that use <Emoji icon="file/texture"/> <code>texture.png</code> will use <Emoji icon="file/texture"/> <code>texture_e.png</code> as their emissive texture. <code>_e</code> is one of the [[../start_here/BlockBench#texture-suffix|texture suffixes]] that Figura looks for when loading an avatar.

<img src={require("@site/static/img/emissive-example/names.png").default} width="400"></img>



== Emissive Texture Behavior ==

<img src={require("@site/static/img/emissive-example/emissive.png").default} align="right"/>

The pixels on a Texture using the <code>“EMISSIVE”</code> [[../enums/RenderTypes|RenderType]] are not interpreted the same was as a regular texture. 

First of all, the alpha values of pixels are ignored. This means that the emissive texture itself cannot be halfway visible. Its either the pixel is completely opaque, or completely gone. No in between. On the texture below, both pixels will render the exact same. Even though they appear to be 2 distinct colors, the right color has an alpha value of <code>139</code> and is blending with the gray GitHub background. They have the exact same RGB values and will be rendered exactly the same under the <code>“EMISSIVE”</code> RenderType. <img src={require("@site/static/img/emissive-example/alpha.png").default} width="40"/>

Second, the “brightness” of a pixel is what determines the intensity of the emissive glow. If you know HSV, its the Value that controls this property. Emissive Intensity controls how bright the pixel will render, but also how much of the pixel behind it will show through. On the texture below, both pixels will render with the same color. The pixel on the left will render with max brightness, not allowing the pixels on the base texture to blend through. The pixel on the right won’t glow as much, but allows the pixels on the base texture to blend through. <img src={require("@site/static/img/emissive-example/brightness.png").default} width="40"/>



== Iris Emissives ==

If you use Iris, regardless of the fact of if you are currently using custom shaders, the <code>“EMISSIVE”</code> RenderType is modified to use the alpha value when rendering the emissive texture. How exactly is not known. Experimentation is required.



== Emissive Render Types ==

There are three emissive render types: EMISSIVE, EMISSIVE_SOLID, and EYES. All of these '''require''' the original _e texture and will make the same pixels glow that are in the _e texture.



=== EMISSIVE ===

This is the default render type of the _e texture.



=== EMISSIVE_SOLID ===

Like EMISSIVE, but it doesn’t allow transparency, transparent pixels will render as black.



=== EYES ===

The render type as Enderman and Spider eyes. This will not make the glowing pixels visible while you are under the invisibility effect.



=== Setting Render Type Example ===

To be clear: To use these you still need to have the _e texture, this can simply change the rendering of it

You can set the render type to “Eyes” like this

<syntaxhighlight lang="lua">models:setSecondaryRenderType("Eyes")</syntaxhighlight>

Note: The glow on the paperdoll and the skull may look slightly different.

Tutorials/Custom-Items

2024-09-26T20:45:07Z

Manuel: Automated upload of converted .txt file.

import Emoji from ‘@site/src/components/Emoji’; import FileTreeRoot from ‘@site/src/components/FileTree/Root’; import FileTreeNode from ‘@site/src/components/FileTree/Node’;



= Custom Items =

Custom items tutorial

Using Figura you can make custom items that are visible in first and third person.

You’ll need to use the Item [[../enums/ModelPartParentTypes|keyword]] and the item_render event combined.



== Item Keyword ==

If you give a Blockbench group the Item keyword (by starting the group name with <code>Item</code>) it will be primed and ready to be used as an item. Without the event the Item group will vanish- and so will every item you hold. It has to be Item with a capital I.

<img src={require("@site/static/img/items/good-keyword.png").default} width="400"></img>



== Item Render Event ==

The item_render event runs once a frame for every item you’re rendering and they do their own things in their own version of the event.

In order to make the Item show up you must return it in the item_render event. This example assumes the bbmodel is named <code>model</code> and that the keyworded group is named Item. If you wish to test this change <code>model</code> to your bbmodel name and the Item group to your version.

<syntaxhighlight lang="lua">function events.item_render()

return models.model.Item

end</syntaxhighlight>

This will replace every single item you’re holding with your custom item



== Replacing Specific Items ==

Here’s an exmaple for replacing a single item by id:

<syntaxhighlight lang="lua">function events.item_render(item)

if item.id == "minecraft:crossbow" then

return models.model.ItemBow

end

end</syntaxhighlight>

Here’s an exmaple for replacing a single item by name:

<syntaxhighlight lang="lua">function events.item_render(item)

if item:getName() == "Lightning" then

return models.model.ItemBow

end

end</syntaxhighlight>

You can use the event’s arguments to get different information from the item you’re holding, and they are: the itemstack, rendering mode, position, rotation, scale, and if its in the left hand. [[../enums/ItemDisplayModes|Possible item rendering modes.]]

<syntaxhighlight lang="lua">function events.item_render(item, mode, pos, rot, scale, left)

end</syntaxhighlight>

This is storing all the values you can get, but in most cases you only need item and sometimes mode. Let’s replace bows, shields, and all swords. These are all for a blockbench model that looks like this:

<FileTreeRoot> <FileTreeNode label="model.bbmodel" icon="file/bbmodel"> <FileTreeNode label="ItemSword" icon="blockbench/group"/> <FileTreeNode label="ItemBow" icon="blockbench/group"/> <FileTreeNode label="ItemShield" icon="blockbench/group"/> </FileTreeNode> </FileTreeRoot>

<syntaxhighlight lang="lua">function events.item_render(item)

if item.id == "minecraft:bow" then

return models.model.ItemBow

elseif item.id == "minecraft:shield" then

return models.model.ItemShield

elseif item.id:find("sword") then

return models.model.ItemSword

end

end</syntaxhighlight>

The find function is searching the id for the word ‘sword’ so you don’t need to type in every single sword id. This also makes it compatible with modded swords.



== Things To Note ==

# Do ''not'' put the Item group inside any other group. The Blockbench outliner should look like this:

<FileTreeRoot> <FileTreeNode label="model.bbmodel" icon="file/bbmodel"> <FileTreeNode label="Item" icon="blockbench/group"/> </FileTreeNode> </FileTreeRoot>

or

<FileTreeRoot> <FileTreeNode label="model.bbmodel" icon="file/bbmodel"> <FileTreeNode label="Item" icon="blockbench/group"/> <FileTreeNode label="Item2" icon="blockbench/group"/> </FileTreeNode> </FileTreeRoot>

because you can have more than one of these keywords. Do '''not''' nest Item keywords inside another. And, do '''not''' have more than one custom item per instance of the Item keyword.

<img src={require("@site/static/img/items/bad-location.png").default} width="400"></img>

You '''could''' put your Item group in another group but be careful, doing so makes it easier to cause unwanted behavior. For example, if you put it into RightArm or LeftArm it will be force unrendered, defeating the point of it.

<ol start="2" style="list-style-type: decimal;">

<li>0,0,0 in Blockbench is where the player will be holding the item in the world</li></ol>

Tutorials/Commands

2024-09-26T20:45:07Z

Manuel: Automated upload of converted .txt file.

Figura comes with a small set of commands that can help you use Figura. As Figura is a client-side mod these only affect the client.



== Normal Commands ==



=== Debug ===

Usage: <code>/figura debug</code>

Debug generates a file in your Figura directory that contains information about your Figura mod settings and the avatar you currently have equipped. This includes the file sizes of all of the elements in the avatar.



=== Docs ===

Usage: <code>/figura docs</code>

Docs contains all of the documentation you can find in the Globals and Enums section of this wiki, simply use autofill to discover all of the options.



=== Emojis ===

Usage: <code>/figura emojis</code>

Emojis contains a list of all the emojis added by Figura. <code>/figura emojis all</code> can show you all of them at once.



=== Export ===

Usage: <code>/figura export avatar</code>

Export, as the name suggests, exports certain files to your Figura directory. The most useful is <code>/figura export avatar</code> which puts your currently worn avatar’s moon file into your directory. If you’ve lost your avatar and it’s still on Figura’s backend, you can retrieve its .moon file with this command.



=== Links ===

<code>/figura links</code>

Links contains all the links for various Figura pages.



=== Load ===

[WIP]



=== Reload ===

<code>/figura reload</code>

Reload reloads your currently equipped avatar.



=== Run ===

Usage: <code>/figura run log("Hello World")</code>

Run runs whatever lua code you type after it.



== Debug Mode Commands ==

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



=== Backend2 ===

[WIP]



=== Set_Avatar ===

Usage: <code>/figura set_avatar targetuuid sourceuuid</code>

Set_avatar can be used to set the avatar of an entity using its uuid. targetuuid is the entity whose avatar is being set, and sourceuuid is the entity from where the avatar is coming from. For example, if you were to set a cow to have the avatar you’re wearing, the cow’s uuid would be the targetuuid and your uuid would be the sourceuuid.

Tutorials/Avatar-Metadata

2024-09-26T20:45:04Z

Manuel: Automated upload of converted .txt file.

import Emoji from ‘@site/src/components/Emoji’; import FileTreeRoot from ‘@site/src/components/FileTree/Root’; import FileTreeNode from ‘@site/src/components/FileTree/Node’;



= Avatar Metadata =

avatar.json information

<Emoji icon="file/json"/> <code>avatar.json</code> is the file that contains Avatar Metadata. It tells Figura specific information about the avatar.



== Json Basics ==

The format that metadata is stored in is JSON. More specifically, a JSON object. It behaves very similar to a Lua table, it just uses different syntax. However, JSON has a very strict syntax and any errors will cause the avatar to fail to load.

JSON objects operate on key value pairs. Keys are separated from their values using colons (<code>:</code>), and entries are separated with commas (<code>,</code>). Unlike Lua tables, keys must be strings.

<syntaxhighlight lang="json">{

"key": "value",

"stringKey,numberValue": 4,

"objectValue": {

"key, but of sub object": "value, but of sub object"

},

"arrayWooo": [1, 2, "stringlol", {}, "42"]

}</syntaxhighlight>



== Metadata Fields ==

Figura looks for specific keys in this JSON object and does things based on the value. Remember that all of these keys are optional. You only need to define the ones you care about.



=== <code>“name”</code> : String ===

The value of this key determines the name of the avatar. This name is showed on the avatar information sidebar on the right of the Wardrobe, but also determines the name used to find the avatar on the left of the Wardrobe. If this key is not present, the name of the folder containing the <Emoji icon="file/json"/><code>avatar.json</code> file is used.

<syntaxhighlight lang="json">{

"name": "Katt"

}</syntaxhighlight>



=== <code>“description”</code> : String ===

The value of this key will appear below the avatar’s name in the wardrobe.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json"

}</syntaxhighlight>



=== <code>“authors”</code> : String[] ===

The value of this key is an array of strings. An array can contain many different values within itself, and Figura expects these values to be strings. The values are used in the Authors field in the avatar information sidebar.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"]

}</syntaxhighlight>



=== <code>“author”</code> : String ===

A place for a single author, should you dislike <code>“authors”</code>. Does the exact same thing as <code>“authors”</code> with only 1 element. If the <code>“authors”</code> key is present, this key is ignored.



=== <code>“version”</code> : String ===

A place to define a [https://semver.org/ Semantic Versioning] version. You can define the lowest possible Figura version that this avatar will run on. If another client uses a Figura version that is less than the version defined here, a <Emoji icon="badge/warning"/> warning badge will appear on your nameplate for them. If they hover over it, it will state that their Figura version is lower than what this avatar was designed to run on. If this key does not exist, Figura will use the version that was used to load the avatar. 

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["KitCat962", "Katakana962"],

"version": "0.1.0"

}</syntaxhighlight>



=== <code>“color”</code> : String ===

This key defines the color of the <Emoji icon="badge/mark"/> Figura mark on your nameplate. It must be a string in the format of a 3 character hex code or a 6 character hex code. For example, both <code>“3ab”</code> and <code>“FF00FF”</code> are valid inputs. If this key does not exist, the color <code>“5AAAFF”</code> will be used.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"],

"version": "0.1.0",

"color": "fc5bd9"

}</syntaxhighlight>



=== <code>“autoScripts”</code> : String[] ===

By default, every single <Emoji icon="file/lua"/> script file in the avatar will execute in an undefined order. The <code>require</code> function can be used to control when a script is first executed, but some may prefer to define the script order in the metadata. This key is an array of strings that define which scripts run and in which order. Scripts not defined here will not run by default on avatar init, but can still be ran via <code>require</code>. A script is specified via it’s file name without the <code>.lua</code> extension. If a script is in a subfolder, that folder must also be defined, with the folder separator being a period (<code>.</code>). Consider the following avatar: 

<FileTreeRoot> <FileTreeNode label="KattExampleAvatar" icon="file/folder"> <FileTreeNode label="accessories" icon="file/folder"> <FileTreeNode label="halo.bbmodel" icon="file/bbmodel"/> <FileTreeNode label="ribbon.bbmodel" icon="file/bbmodel"/> </FileTreeNode> <FileTreeNode label="libs" icon="file/folder"> <FileTreeNode label="armorAidLib.lua" icon="file/lua"/> <FileTreeNode label="RainbowNameplate.lua" icon="file/lua"/> <FileTreeNode label="JsonifyTextLib.lua" icon="file/lua"/> </FileTreeNode> <FileTreeNode label="avatar.json" icon="file/json"/> <FileTreeNode label="player.bbmodel" icon="file/bbmodel"> <FileTreeNode label="diamond_layer_1" icon="file/texture"/> <FileTreeNode label="diamond_layer_2" icon="file/texture"/> </FileTreeNode> <FileTreeNode label="script.lua" icon="file/lua"/> <FileTreeNode label="skin.png" icon="file/texture"/> <FileTreeNode label="pet.bbmodel" icon="file/bbmodel"/> </FileTreeNode> </FileTreeRoot>

To make only <code>RainbowNameplate.lua</code> run on avatar init, the <code>autoScripts</code> would look like 

<syntaxhighlight lang="json">"autoScripts":["libs.RainbowNameplate"]</syntaxhighlight>

For our example metadata file, we will state that only <Emoji icon="file/lua"/> <code>script.lua</code> will run by default, and the script itself will call <code>require</code> on the library scripts which will “import” them into itself. You may be thinking “whats the point of <code>”autoScripts”</code> if <code>require</code> is objectively better at controlling script load order?“, To which my response would be”I don’t know”. But if you give an empty array, then no script will run which can be useful for debugging.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"],

"version": "0.1.0",

"color": "fc5bd9",

"autoScripts": ["script"]

}</syntaxhighlight>



=== <code>“autoAnims”</code> : String[] ===

This key defines which animations should start playing when the avatar first loads. The string to reference an animation follows the pattern <code>“modelPath.animName”</code>. Consider the following avatar: 

<FileTreeRoot> <FileTreeNode label="KattExampleAvatar" icon="file/folder"> <FileTreeNode label="accessories" icon="file/folder"> <FileTreeNode label="halo.bbmodel" icon="file/bbmodel"/> <FileTreeNode label="ribbon.bbmodel" icon="file/bbmodel"/> </FileTreeNode> <FileTreeNode label="libs" icon="file/folder"> <FileTreeNode label="armorAidLib.lua" icon="file/lua"/> <FileTreeNode label="RainbowNameplate.lua" icon="file/lua"/> <FileTreeNode label="JsonifyTextLib.lua" icon="file/lua"/> </FileTreeNode> <FileTreeNode label="avatar.json" icon="file/json"/> <FileTreeNode label="player.bbmodel" icon="file/bbmodel"> <FileTreeNode label="diamond_layer_1" icon="file/texture"/> <FileTreeNode label="diamond_layer_2" icon="file/texture"/> </FileTreeNode> <FileTreeNode label="script.lua" icon="file/lua"/> <FileTreeNode label="skin.png" icon="file/texture"/> <FileTreeNode label="pet.bbmodel" icon="file/bbmodel"/> </FileTreeNode> </FileTreeRoot>

If we want the animation <code>“idle”</code> in the bbmodel <Emoji icon="file/bbmodel"/> <code>player.bbmodel</code>, we would include the string <code>“player.idle”</code> in the <code>“autoAnims”</code> array. Folder seperation is done with a period (<code>.</code>) instead of slash (<code>/</code>). If we want the animation <code>“spin”</code> in the model <Emoji icon="file/bbmodel"/> <code>halo.bbmodel</code>, we would include the string <code>“accessories.halo.spin”</code> in the <code>“autoAnims”</code> array. This is not table indexing like how you would index the <code>animations</code> table to get an Animation. It is just string concatenation. <code>autoAnims</code> has a very niche use case as 99% of the time you have animations that you only want playing sometimes or want to play on a trigger. The only real use case is for a constantly playing looping animation that you don’t want to waste ~8 instructions on play at the beginning of a script, or perhaps you have an avatar that does not have any script files and you want to keep it that way.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"],

"version": "0.1.0",

"color": "fc5bd9",

"autoScripts": ["script"],

"autoAnims": ["player.idle", "accessories.halo.spin"]

}</syntaxhighlight>



=== <code>“ignoredTextures”</code> : String[] ===

This key defines which textures should be ignored when loading the avatar. This is useful for when you have a cube that gets its texture set via code, but since all cubes must have a blockbench texture for Figura to even load the cube, you will either have to waste space with a dummy texture or use another texture in the model, which probably won’t look good on the cube. This key allows you to have that dummy texture in blockbench without having to waste precious bytes on having that texture loaded with the avatar. Referencing a texture is exactly the same format as getting a Texture object with the <code>textures</code> global. Consider this avatar: 

<FileTreeRoot> <FileTreeNode label="KattExampleAvatar" icon="file/folder"> <FileTreeNode label="accessories" icon="file/folder"> <FileTreeNode label="halo.bbmodel" icon="file/bbmodel"/> <FileTreeNode label="ribbon.bbmodel" icon="file/bbmodel"/> </FileTreeNode> <FileTreeNode label="libs" icon="file/folder"> <FileTreeNode label="armorAidLib.lua" icon="file/lua"/> <FileTreeNode label="RainbowNameplate.lua" icon="file/lua"/> <FileTreeNode label="JsonifyTextLib.lua" icon="file/lua"/> </FileTreeNode> <FileTreeNode label="avatar.json" icon="file/json"/> <FileTreeNode label="player.bbmodel" icon="file/bbmodel"> <FileTreeNode label="diamond_layer_1" icon="file/texture"/> <FileTreeNode label="diamond_layer_2" icon="file/texture"/> </FileTreeNode> <FileTreeNode label="script.lua" icon="file/lua"/> <FileTreeNode label="skin.png" icon="file/texture"/> <FileTreeNode label="pet.bbmodel" icon="file/bbmodel"/> </FileTreeNode> </FileTreeRoot>

Hypothetically, the armor of this avatar is being handled by <Emoji icon="file/lua"/> <code>armorAidLib.lua</code>. It changes the texture of cubes to the vanilla armor textures. There is no need to have the <Emoji icon="file/texture"/> <code>diamond_layer_1</code> and <Emoji icon="file/texture"/> <code>diamond_layer_2</code> textures in the bbmodel, but setting the cubes to use <Emoji icon="file/texture"/> <code>skin.png</code> will make editing the model a pain. So we remove both unused textures.

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"],

"version": "0.1.0",

"color": "fc5bd9",

"autoScripts": ["script"],

"autoAnims": ["player.idle", "accessories.halo.spin"],

"ignoredTextures": ["player.diamond_layer_1", "player.diamond_layer_2"]

}</syntaxhighlight>



=== <code>“customizations”</code> : {“ModelPart” : {“Customization” : “String”}} ===

Does that Type identifier make any sense? Not really, but thats what the <code>“customizations”</code> property is. <code>“customizations”</code> allows for modifications to ModelParts that cant be done in BlockBench. You can still do this stuff via script, but the intent is for an avatar that does not have a script to still have access to some functionality. <code>“customizations”</code> itself is a JSON object. The keys of that object are references to ModelParts, with the values being another JSON object. ''That'' object contains key value pairs that operate on the referenced ModelPart. Consider the following avatar: 

<FileTreeRoot> <FileTreeNode label="KattExampleAvatar" icon="file/folder"> <FileTreeNode label="accessories" icon="file/folder"> <FileTreeNode label="ribbon.bbmodel" icon="file/bbmodel"> <FileTreeNode label="cube" icon="blockbench/cube"/> </FileTreeNode> </FileTreeNode> <FileTreeNode label="avatar.json" icon="file/json"/> <FileTreeNode label="player.bbmodel" icon="file/bbmodel"> <FileTreeNode label="Head" icon="blockbench/group"> <FileTreeNode label="Head" icon="blockbench/cube"/> </FileTreeNode> </FileTreeNode> </FileTreeNode> </FileTreeRoot>

To target the <Emoji icon="blockbench/group"/> <code>Head</code>, the correct key to use would be <code>“player.Head”</code>. To target the <Emoji icon="file/bbmodel"/> <code>ribbon</code>, the correct key to use would be <code>“accessories.ribbon”</code>. 

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {},

"accessories.ribbon": {}

}

}</syntaxhighlight>

Now for the keys that work inside these sub-objects.



==== <code>“primaryRenderType”</code> : String ====

Sets the RenderType to use for the Primary/Default texture. The default primaryRenderType is <code>“TRANSLUCENT”</code>.

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL"

}

}

}</syntaxhighlight>



==== <code>“secondaryRenderType”</code> : String ====

Sets the RenderType to use for the Secondary/Emissive/<code>_e</code> texture. The default secondaryRenderType is <code>“EMISSIVE”</code>.

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {

"secondaryRenderType": "GLINT"

},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL"

}

}

}</syntaxhighlight>



==== <code>“parentType”</code> : String ====

Keywords in BlockBench set the ParentType of the ModelPart. This key overrides that, or sets one if there is no Keyword. The default ParentType is <code>“None”</code>

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {

"secondaryRenderType": "GLINT",

"parentType": "Body"

},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL"

}

}

}</syntaxhighlight>



==== <code>“moveTo”</code> : String ====

Forces the ModelPart reference given to be a child of this ModelPart. This is useful if you like to organize your avatar into separate bbmodels. You can use this to stitch them together.

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {

"secondaryRenderType": "GLINT",

"parentType": "Body"

},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL",

"moveTo": "player.Head"

}

}

}</syntaxhighlight>



==== <code>“visible”</code> : Boolean ====

Overrides the visibility defined in BlockBench. Useful to be able to hide ModelParts in BlockBench to edit the model more easily, without it affecting the final result of the Avatar.

<syntaxhighlight lang="json">{

"customizations": {

"player.Head": {

"secondaryRenderType": "GLINT",

"parentType": "Body"

},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL",

"moveTo": "player.Head",

"visible": true

}

}

}</syntaxhighlight>



==== <code>“remove”</code> : Boolean ====

This customization will prevent the targeted ModelPart from loading at all. 

<syntaxhighlight lang="json">{

"customizations": {

"accessories.exampleMesh": {

"smooth": true

}

}

}</syntaxhighlight>



==== <code>“smooth”</code> : Boolean ====

This customization must be applied directly to a mesh object. This will calculate the vertex normals so that the mesh appears smooth, reducing the visibility of individual triangles.

<syntaxhighlight lang="json">{

"customizations": {

"accessories.exampleMesh": {

"smooth": true

}

}

}</syntaxhighlight>



== Final Example <code>avatar.json</code> ==

<syntaxhighlight lang="json">{

"name": "Katt",

"description": "Example avatar.json",

"authors": ["@KitCat962", "KitCat#0962", "Katakana962"],

"version": "0.1.0",

"color": "fc5bd9",

"autoScripts": ["script"],

"autoAnims": ["player.idle", "accessories.halo.spin"],

"ignoredTextures": ["player.diamond_layer_1", "player.diamond_layer_2"],

"customizations": {

"player.Head": {

"secondaryRenderType": "GLINT",

"parentType": "Body"

},

"accessories.ribbon": {

"primaryRenderType": "END_PORTAL",

"moveTo": "player.Head",

"visible": true

}

}

}</syntaxhighlight>

Tutorials/Animations

2024-09-26T20:45:03Z

Manuel: Automated upload of converted .txt file.

Tutorial for playing and troubleshooting Blockbench animations

Figura can play animations from Blockbench using the Animation API.



== Playing an Animation ==

In order to play an animation you need to index the animation through the Blockbench model it is in and the <code>animations</code> global.

Let’s say we have a Blockbench model named <code>example</code>

<img src={require("@site/static/img/animation/exampleBbmodel.png").default} width="200"></img>

and an animation named <code>idle</code>

<img src={require("@site/static/img/animation/exampleIdle.png").default} width="400"></img>

If we want to play this animation we can use this code:

<syntaxhighlight lang="lua">animations.example.idle:play()</syntaxhighlight>

<code>animations</code> stores all the animation data for every Blockbench model. 

The next part of the index is always the Blockbench model name that contains the animation you want to play, in our case this is <code>example.bbmodel</code> (if your Blockbench model is in a subfolder, that will need to be included as well like <code>animations[“subfolder.example”].idle</code>)

And the last is always the animation name, in this case <code>idle</code>.



== Blockbench is Tricking You ==

If you’re looking at your animation in Blockbench and there’s two names, the smaller name in gray is the actual animation name.

<img src={require("@site/static/img/animation/exampleLie.png").default} width="400"></img>

'''You can’t use the method above to play the animation if it looks like this image'''

You have two options: Rename the animation, or deal with the long animation name



=== Option One: ===

Rename the animation <img src={require("@site/static/img/animation/exampleIdle.png").default} width="400"></img>



=== Option Two: ===

Deal with the animation name by changing the code.

<syntaxhighlight lang="lua">animations.example["animation.model.idle"]:play()</syntaxhighlight>



== Alternatives to play() ==

There is another function that can play animations, <code>setPlaying(bool)</code>

You can put a boolean value inside the parenthesis for the function and it will play the animation if the boolean is true, or stop it if the boolean is false

This is often used for toggles in the action wheel.



=== setPlaying Example ===

By nature, setPlaying needs to be in a function that will run multiple times, we’re going to use a tick event but you could use a ping or anything else

<syntaxhighlight lang="lua">function events.tick()

local crouching = player:getPose() == "CROUCHING"

-- This detects if you are crouching and stores it into crouch.

-- So: crouch == true when crouching, and crouch == false when you're not crouching

animations.example.idle:setPlaying(crouching)

end</syntaxhighlight>

And now our animation <code>idle</code> will play whenever we’re crouching!

This methodology can be expanded infinitely but it gets more complex the more animations you add.



== Simple Idle-Walk-Sprint-Crouch Setup ==

As an example we’ll do code for a set of four animations: idle, walk, sprint, and crouch. Here’s our animations in our Blockbench model. <img src={require("@site/static/img/animation/exampleAnims.png").default} width="400"></img>

<syntaxhighlight lang="lua">function events.tick()

local crouching = player:getPose() == "CROUCHING"

-- This is the same line of code from the previous example

local walking = player:getVelocity().xz:length() > .01

-- walking == true when moving, and walking == false when still (or going directly up/down as we excluded the y axis)

local sprinting = player:isSprinting()

-- If you want to find more player functions, check out the Player Global page

-- Now we're going to use a lot of logic to figure out when animations should/shouldn't play

animations.example.idle:setPlaying(not walking and not crouching)

-- You're idle when not walking and not crouching

animations.example.walk:setPlaying(walking and not crouching and not sprinting)

-- You're walking when... walking and not crouching, but you want to make sure you're not sprinting either

animations.example.sprint:setPlaying(sprinting and not crouching)

-- You probably can catch my drift by now

animations.example.crouch:setPlaying(crouching)

end</syntaxhighlight>



== Common Errors ==



=== Fixing the index error ===

You might run into some script errors while doing this, here’s some solutions to <code>attempt to index ? (a nil value)</code>

The error will tell you about a key, the key is AFTER the part that’s experiencing an incorrect.

<img src={require("@site/static/img/animation/exampleErrorAnim.png").default} width="400"></img>

Like in this example, it says that <code>setPlaying</code> is the key, so we know that the problem is BEFORE it.

You’ll notice that the animation name is misspelled, once you fix that the error will go away or change.

<img src={require("@site/static/img/animation/exampleErrorBbmodel.png").default} width="400"></img>

Here it is again, but this time the key is <code>idle</code>, meaning the problem is with the Blockbench model name.

You’ll notice that it’s misspelled in this version, fixing it will make the error go away or change.



=== Errors inside a keyframe ===

Errors inside keyframes are vary vastly, but you can indentify them by the name of the animation in the error. Here’s three examples: <img src={require("@site/static/img/animation/exampleErrorKeyframe.png").default} width="800"></img>

How you fix this will greatly depend on what the error is.



== Overriding Vanilla Animations ==

You can override vanilla animations using the override setting in Blockbench, this is set per-animation and it overrides per-part and per-channel (rotation, position, scale). It only overrides while the animation is playing. <img src={require("@site/static/img/animation/exampleCheck.png").default} width="400"></img>

<img src={require("@site/static/img/animation/exampleOverride.png").default} width="400"></img>



== Special Keyframe Types ==

Blockbench animations have a special category of keyframes called Effects keyframes. There are three of them and Figura ignores Particle and Sound



=== Instruction Keyframes ===

The third special keyframe type is Instruction, 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.

Each instruction is its own ‘scope’ meaning that variables local to any of the scripts can’t be accessed by the keyframes without specifically interfacing between them.



== Community Resources ==



=== Jimmy’s Animation Handler ===

If you have a lot of animations that need detections, Jimmy’s Animation Handler can play your animations for you. [https://github.com/JimmyHelp/JimmyAnims Find it here on GitHub]



=== GSAnimBlend ===

If you want to smooth the transition between animations so it doesn’t jump between them you can use GSAnimBlend. [https://github.com/GrandpaScout/GSAnimBlend Find it here on GitHub]

User:PenguinEncounter/OldTutorials/ActionWheel

2024-09-26T20:45:00Z

Manuel: Automated upload of converted .txt file.

Tutorial for most things action wheel

If you’re just here to copy-paste something without the tutorial go [[./ActionWheel/#here-is-the-full-copy-paste-for-an-example-action-wheel|here]]

The Action Wheel is a gui element provided by Figura that allows for adding highly customizable Actions that can provide additional functionality to your avatar.

The Action Wheel operates on Pages. Only a single Page can be active at a time. Pages contain Actions. A Page can have an unlimited amount of Actions, but the Action Wheel can only render 8 at a time. While a Page with more than 8 Actions is active, you can use the scroll wheel to move between the groups of 8 Actions within the Page.

The docs page for the [[../globals/action-wheel|Action Wheel]] has more examples for specific action wheel functions



== Example Action Wheel ==

The first step is to create the Page that will hold the Actions. This is done via the <code>newPage</code> function.

<syntaxhighlight lang="lua">local mainPage = action_wheel:newPage()</syntaxhighlight>

This creates a new page, but thats it. If you save and try to open the Action Wheel (Default Keybind B), you will see a message stating that there is no active page. We can use the <code>setPage</code> function while providing a reference to a Page object to set the active page.

<syntaxhighlight lang="lua">action_wheel:setPage(mainPage)</syntaxhighlight>

Tada. New blank page and Figura isnt screaming at us. Now for some actions. You can call the <code>newAction</code> function on a Page object. This will create a new Action ''and'' add it to the Page.

You technically do not need to store the Action in a variable. If you do, please give it a unique variable name. Using the same variable name for all actions can cause issues when doing more advanced stuff.

<syntaxhighlight lang="lua">local action = mainPage:newAction()</syntaxhighlight>

New Action, but it really doesn’t look like much. Lets add a title, a display item, and perhaps change the color that appears when the Action is hovered over.

One thing to remember is that all Action functions return itself. This allows for functions to be chained together, always modifying the same action



<syntaxhighlight lang="lua">local action = mainPage:newAction()

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)</syntaxhighlight>

Pretty, but functionally useless. Lets add a function to the <code>leftClick</code> field. When the Action is left clicked, the function stored in the Action’s <code>leftClick</code> field gets invoked.



<syntaxhighlight lang="lua">local action = mainPage:newAction()

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)

-- the onLeftClick function just sets the Action's leftClick field

:onLeftClick(function()

print("Hello World!")

end)</syntaxhighlight>

Now we have an Action that does stuff. You may not notice anything, but there is a glaring issue with the current code.

The issue is that the leftClick code will only execute on your computer.

As described in [[./Pings|Pings]], Figura is completely clientside. The Action Wheel is a feature added by Figura, meaning it will never be synced between clients via the Minecraft Server. So instead, we must use Pings that utilize Figura’s Backend to sync data between clients.

First step is to take the code that would be executed on leftClick, and turn it into a ping function. Then, instead of assigning an anonymous function to <code>leftClick</code>, we assign the ping function itself to <code>leftClick</code>

'''''IMPORTANT: ALL PING FUNCTIONS MUST HAVE UNIQUE NAMES''''' Also, please name your ping function so that it describes what it does. I ''hate'' seeing <code>pings.actionClicked</code> in the hellp channel in discord. Do something like <code>pings.playEmote1</code> or <code>pings.setArmorVisibility</code>.



<syntaxhighlight lang="lua">-- Create ping function that does the same thing the Action would have done.

-- It must be defined above the Action.

function pings.actionClicked()

print("Hello World!")

end

local action = mainPage:newAction()

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)

-- Pass in the ping function itself into onLeftClick

:onLeftClick(pings.actionClicked)</syntaxhighlight>

And there you have it. An Action that correctly executes it’s contents across all clients.

While this will correctly sync the timing of the execution of the ping function with all clients, it needs a slight modification if you want to send arguments with the ping.



<syntaxhighlight lang="lua">function pings.actionClicked(a)

print("Hello World!", a)

end

local action = mainPage:newAction()

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)

:onLeftClick(function()

pings.actionClicked(math.random())

end)</syntaxhighlight>

What we are doing is wrapping the call to the ping function inside another function.

The code below is a common mistake beginners can fall into. While the code might seem correct to those less code literate, it translates to “call the ping function, then assign the return result to the <code>leftClick</code> field”. A ping will never have a return value, meaning <code>leftClick</code> is being assigned the value <code>nil</code>, meaning nothing.



<syntaxhighlight lang="lua">mainPage:newAction()

:onLeftClick(pings.actionClicked2(math.random()))

-- Do not do use this code. It will not work.</syntaxhighlight>



==== Here is the full copy paste for an example Action Wheel ====



<syntaxhighlight lang="lua">local mainPage = action_wheel:newPage()

action_wheel:setPage(mainPage)

function pings.actionClicked()

print("Hello World!")

-- animation example (commented out to avoid erroring):

-- animations.bbmodelname.animationname:play()

end

local action = mainPage:newAction()

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)

:onLeftClick(pings.actionClicked)</syntaxhighlight>



=== Toggle Example ===

This is an exmaple of the onToggle function, which swaps between two states. It does not work on its own as it doesn’t have a page.



<syntaxhighlight lang="lua">function pings.toggling(state)

models:setVisible(state)

-- animation toggle example (commented out to avoid erroring):

-- animations.bbmodelname.animationname:setPlaying(state)

end

local toggleaction = mainPage:newAction() -- If you're getting an error here it's probably because you didn't make the page

:title("disabled")

:toggleTitle("enabled")

:item("red_wool")

:toggleItem("green_wool")

:setOnToggle(pings.toggling)</syntaxhighlight>



=== Multiple Actions Example ===

When working with multiple actions, it’s important to give the actions and pings unique names



<syntaxhighlight lang="lua">local mainPage = action_wheel:newPage()

action_wheel:setPage(mainPage)

function pings.actionClicked() -- this ping is named actionClicked

print("Hello World!")

end

local action = mainPage:newAction()

-- this action is saved to action

:title("My Action")

:item("minecraft:stick")

:hoverColor(1, 0, 1)

:onLeftClick(pings.actionClicked)

-- this calls the ping named actionClicked

function pings.toggling(state)

-- this ping is named toggling. it's important that all pings have unique names

models:setVisible(state)

end

local toggleaction = mainPage:newAction()

-- this action is saved to toggleaction. it's important that actions are saved to unique variables

:title("disabled")

:toggleTitle("enabled")

:item("red_wool")

:toggleItem("green_wool")

:setOnToggle(pings.toggling)

-- this calls the ping named toggling</syntaxhighlight>



=== Multiple Pages Example ===



<syntaxhighlight lang="lua">local mainPage = action_wheel:newPage()

local secondPage = action_wheel:newPage() -- make sure you save the pages to unique variables

action_wheel:setPage(mainPage) -- this is setting the page you'll see when you first open the wheel to mainPage

local toSecond = mainPage:newAction()

:title("Change To Second Page")

:item("item_frame")

:onLeftClick(function()

-- this is a new action on mainPage. its purpose will be to swap to secondPage

-- this doesn't need to be pinged

log("Swapped to the second page")

action_wheel:setPage(secondPage)

end)

local toMain = secondPage:newAction()

:title("Change To Main Page")

:item("glow_item_frame")

:onLeftClick(function()

-- this is a new action on secondPage. its purpose will be to swap to mainPage

log("Swapped to the main page")

action_wheel:setPage(mainPage)

end)

local newAction = secondPage:newAction()

:title("Hello")

:item("zombie_head")

:onLeftClick(function()

-- this is a second action on the second page just to show it can be done

log("Hello World")

end)</syntaxhighlight>



== Further Reading ==

Go [[../globals/Action-Wheel/Action.md|here]] for more information on Actions.

Go [[../globals/Action-Wheel/Page.md|here]] for more information on Pages.



== Advanced Action Wheel ==

Go [[../tutorials/ActionWheel-Advanced|here]] for an advanced action wheel tutorial.



==== For when you want to skip the tutorials altogether ====

If you scrolled to the bottom of the page just to copy-paste something without the tutorial go [[./ActionWheel/#here-is-the-full-copy-paste-for-an-example-action-wheel|here]]

Tutorials/ActionWheel-Advanced

2024-09-26T20:44:59Z

Manuel: Automated upload of converted .txt file.

Advanced action wheel tutorial

If you haven’t read and understood the beginner action wheel tutorial, start [[../tutorials/ActionWheel.md|there]].



== Multi Page Setup ==

Creating a network of Pages can be overwhelming. Lets try to rectify that.

This method for creating a Page Network divides the Pages into seperate, isolated files. These files return an Action that can be added to a different page. This Action will set the cuurrent page to the page in the file, but it first stores a reference to the Page it came from. That way when you want to go back to the previous page, its as simple as setting the current page to the stored Page.

This allows Pages to be modular and easily reorganized if needed. More importantly, it can help make multiple pages less overwhelming.

<syntaxhighlight lang="lua">--ActionWheel.lua

-- This file controls the root Page. All Pages are 'children' of this Page.

local mainpage = action_wheel:newPage()

-- setAction is used to add an Action that already exists to this Page

-- You need to specify the slot the Action wil go into, but -1 can be used to put it in the next available slot.

mainpage:setAction(-1, require("Page1"))

mainpage:setAction(-1, require("Page2"))

action_wheel:setPage(mainpage)</syntaxhighlight>



<syntaxhighlight lang="lua">--Page1.lua

-- Create the Page

local page = action_wheel:newPage()

-- Define the Actions within the Page (These are dummy example Actions)

page:newAction():title():color():onLeftClick()

page:newAction():title():color():onLeftClick()

page:newAction():title():color():onLeftClick()

-- This variable stores the Page to go back to when done with this Page

local prevPage

-- This Action just sets the stored page as active

page:newAction()

:title("GoBack")

:item("minecraft:barrier")

:onLeftClick(function()

action_wheel:setPage(prevPage)

end)

-- Page:newAction automatically adds the Action to the Page.

-- This is unwanted, so action_wheel:newAction() is used so just make an Action.

-- This is the Action that will be returned by require and will be used to navigate to this file's Page

return action_wheel:newAction()

:title("Page1")

:onLeftClick(function()

-- store the current active page so that we can set it back as active later

prevPage = action_wheel:getCurrentPage()

-- set this file's page as active

action_wheel:setPage(page)

end)</syntaxhighlight>



<syntaxhighlight lang="lua">--Page2.lua

-- Page2 is just to show that the entire process can be repeated verbatum, so long as the variables are local.

local page = action_wheel:newPage()

page:newAction():title():color():onLeftClick()

page:newAction():title():color():onLeftClick()

page:newAction():title():color():onLeftClick()

local prevPage

page:newAction()

:title("GoBack")

:item("minecraft:barrier")

:onLeftClick(function()

action_wheel:setPage(prevPage)

end)

return action_wheel:newAction()

:title("Page2")

:onLeftClick(function()

prevPage = action_wheel:getCurrentPage()

action_wheel:setPage(page)

end)</syntaxhighlight>



== Setting Default State of Toggle Action ==

This primarily utilizes calling a ping function without the network code, which is explained [[./Pings#ping-on-init|here]]

This example will correctly set the default visibility of a theoretical jetpack model



<syntaxhighlight lang="lua">-- This variable's initial value will control the default state of the togglable thing.

local jetpackEnabled = true

local jetpackModel = models.model.Body.Jetpack -- reference a ModelPart for convinience

local function setJetpack(bool)

jetpackEnabled = bool -- this will be a ping function, so we still need to set the client's variable for when it is used in the toggle.

jetpackModel:setVisible(bool)

end

pings.setJetpack = setJetpack -- we now have a normal function and a ping function that calls the normal function after network stuff

-- This event controls the particle effect of the jetpack

function events.tick()

-- once every 4 ticks while the jetpack is visible

if jetpackEnabled and world.getTime() % 4 == 0 then

-- spawn particles relative to the model itself in the world

local partMatrix = jetpackModel:partToWorldMatrix()

particles:newParticle("minecraft:flame", partMatrix:apply(3, -6, 0))

particles:newParticle("minecraft:flame", partMatrix:apply(-3, -6, 0))

end

end

-- Page boilerplate

local mainpage = action_wheel:newAction()

action_wheel:setPage(mainpage)

-- calling a ping in the script initialization is a bad idea, hence why the reference to the normal function is needed

setJetpack(jetpackEnabled)

mainpage:newAction()

:title("Enable Jetpack")

:toggleTitle("Disable Jetpack")

:onToggle(pings.setJetpack) -- use the ping for the action toggle, as that is still needs to be pinged

:toggled(jetpackEnabled) -- the toggled function sets the internal state of the Toggle Action. It *does not* call toggle or untoggle.</syntaxhighlight>

Tutorials/.How-To-Read-Documentation

2024-09-26T20:44:59Z

Manuel: Automated upload of converted .txt file.

= How To Read Documentation =

<div class="danger">

This article needs to be entirely rewritten for the current docs.

</div>

'''This article is a WIP.'''

As of writing this article, the GitHub wiki is not complete, but there are other sources of documentation for Figura out there. The most updated one is called Figs and it’s made and managed by GitHub user applejuiceyy. [https://applejuiceyy.github.io/figs/ Here’s a link].

User GrandpaScout has their [https://github.com/GrandpaScout/FiguraRewriteVSDocs VSDocs] which are used in conjunction with the text/code editor Visual Studio Code. These docs will help autofill function names and blockbench model paths for you.

In-game, Figura has a custom command to find documentation. <code>/figura docs</code>



== The Basics ==



=== Globals ===

Globals are where functions that allow you to access various information are stored. For instance, functions relating to player data are stored in the global <code>player</code>, and functions relating to the avatar’s models are stored in the global <code>models</code>.



=== Enums ===

Enums are not functions, but rather lists of key words a function may return or take as an argument. For example, the <code>ParentTypes</code> enums contains all the parent types you could set a modelPart to (which are equivalent to the Blockbench keywords). On the other hand, the <code>EntityPoses</code> enums contains all the entity poses (including non-player poses) that an entity can achieve, as returned by <code>getPose()</code>



== Reading Figs ==

This page will be providing a tutorial on how to find and use all of Figura’s functions using Figs.

We will be viewing Figs in the ‘experienced person’ mode. By default Figs is in new person mode, to change this you can select the Preferences button in the upper right of the webpage.

Upon opening Figs you will be primarily presented the option to select your version, this is the version of Figura you are using. If you select the wrong one you may be missing functions or you may be seeing functions you can’t actually use. If you skip selecting a version Figs will be showing you the functions in the latest version of Figura.

Regardless of if you select a version or not you will see a list of words on the left of the screen. The ones are the top are globals, and then you can scroll down that sidebar to see miscellaneous types and miscellaneous enums.

Figs has a search function which will find any word in the name or description of a function, so if you don’t know what global a function is in, you can use the search function to keyword search for it. (For example, if you want to change the camera, search for camera and scroll)

Let’s say we want to make a custom elytra that turns off/on depending on if we’re wearing an elytra. We’re a player, so all of our information is going to be in the player API. On the left sidebar scroll down until you find <code>player</code> underneath the globals section. Aside from scrolling through the entire player API list you could search for the word ‘item’ (as we are looking for item information) until you find <code>getItem()</code>



=== How To Read What’s Being Given ===

There’s going to be some information there, and all of it is necessary. You can click on <code>PlayerAPI.getItem</code> to open the full page for the function (though this doesn’t provide more information)

<code>PlayerAPI.getItem</code> tells us that the function <code>getItem</code> is in the PlayerAPI. Functions in the player API are accessed via the <code>player</code> global so the function can be accessed by writing <code>player:getItem()</code>. But it doesn’t tell us how to get all the information we want out of it yet.

Look down until you see <code>overload 1:</code> this next bit of information is the second piece of the puzzle

<code>PlayerAPI:getItem(index: Integer): ItemStack</code> is giving us '''four''' very important pieces of information, the first two we’ve already gone over.

The third piece of information is what’s inside the brackets <code>()</code>. In this case it’s <code>index: Integer</code>. In this context, “index” refers to the item slot being checked. An integer is a whole number, so this tells us that the slot to check is determined by putting a whole number in the brackets.

Looking back up at the description of the item, Figs tells us <code>slots are indexed with 1 as the main hand, 2 as the off hand, and 3,4,5,6 as the 4 armor slots from the boots to the helmet</code>. In short, the integer we enter as an argument will dictate what slot it will search. Figs says 6 is the helmet and it goes down to the boots, and we want the chestplate slot so 5 is the integer we must give it.

At this point we have this: <code>player:getItem(5)</code> and we’re going to test that it’s working with a bit of code

<syntaxhighlight lang="lua">function events.tick()

log(player:getItem(5))

end</syntaxhighlight>

And… huzzah! Our game chat is being spammed by the log, and that log is telling us what’s in our chestplate slot.

The game is telling us, at the end of the message, that this is an ItemStack. If you look back at figs’ overload: <code>PlayerAPI:getItem(index: Integer): ItemStack</code> you’ll notice that ‘ItemStack’ is after the parenthesis. That’s because the information after the colon <code>:</code> is what the function is going to return. Essentially, what it’s going to give back to us after it’s done.

So now we can get information from the chesplate slot, but we’re not doing anything with that information yet, we must dive into information given to us via the ItemStack.

In Figs, click on <code>ItemStack</code> and it will bring you to another page that has even more functions on it.

We want to know if this ItemStack is from an elytra. The best way to do this is via the item’s id. If you’ve ever used the /give command, you give yourself an item via the item ID, and it looks like <code>minecraft:stick</code> or something similar. An item’s id can also be viewed by turning advanced tooltips on using F3+H.

If you’ve searched the ItemStack page for id you will easily find the <code>getID()</code> function.

Its overload looks like this: <code>ItemStack:getID(): String</code>

Like before, getID() is in ItemStack, meaning it wants an ItemStack, but we don’t have an ItemStack API like the player API, we can’t do ItemStack:getID() because ItemStack is meaningless (it’s not in the list of globals). However, <code>player:getItem(5)</code> returns an ItemStack which the <code>getID()</code> function can be used on directly. As such, we can use <code>player:getItem(5):getID()</code> which in our testing log looks like this:

<syntaxhighlight lang="lua">function events.tick()

log(player:getItem(5):getID())

end</syntaxhighlight>

You might be wondering about putting something in getID’s parentehsis, so let’s turn our attention back to the overload figs gives us. In <code>ItemStack:getID(): String</code> the parenthesis are empty here. That means no arguments are necessary and nothing should be put in the brackets. Anything given will be ignored.

Notably, it’s returning a String which is quite literally a string of characters. Putting something in quotes makes it a string. So <code>true</code> is a boolean, but <code>“true”</code> is a string. In our case this string of characters is the id of the item in our chestplate slot. At this point we can compare the string of our item with the string of the elytra id.

<syntaxhighlight lang="lua">function events.tick()

log(player:getItem(5):getID() == "minecraft:elytra")

end</syntaxhighlight>

This statement is known as an evaluation. The doubled equals sign <code>==</code> tells the game to compare the two values on either side of it. In the case of functions, it will compare the value the function returns. If an elytra is worn then <code>player:getItem(5):getID()</code> will return <code>“minecraft:elytra</code>, which is equal to what we’re checking for and as such the game will show <code>true</code>. The evaluation can be combined with other code to do more with it, such as store its value in a variable or put it in an if statement.

So, after all this, our elytra detection is <code>player:getItem(5):getID() == “minecraft:elytra”</code>. It’s using the player API to run <code>getItem()</code> on the player, and then use <code>getID()</code> on the player’s item, and then compare it’s ID to that of the elytra to find out if we’re wearing an elytra or not.

For clarification: The log is another function that we put the final result into. It serves to make the information we put in it as an argument to the chat. If you copied the log that will break things



== Using The In-Game Docs ==

WIP

Blockbench

2024-09-26T20:34:06Z

Manuel: Automated upload of converted .txt file.

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