What a Figura script is and why you'd write one

A Figura script is a piece of code you write in Lua (a lightweight programming language) that tells Figura what to do with your Minecraft avatar. Figura is a mod that lets you customize how your character looks and moves in multiplayer servers, and scripts are how you control those customizations — things like changing your model's appearance, adding animations, or responding to in-game events.

You write scripts because the visual changes Figura makes are controlled by code, not by clicking buttons in a menu. If you want your avatar to do something specific — wave when you jump, change color when you take damage, or display a custom model part — you need a script to make it happen. The script runs on your computer and only affects what other players see when they look at you.

Scripts live in a folder on your computer called your avatar directory. When you load an avatar in Figura, the mod reads the scripts in that folder and runs them. You can write scripts from scratch, edit existing ones, or copy and modify scripts other players have shared.

Key Takeaways

  • Figura scripts are written in Lua and stored in your avatar folder, which Figura creates automatically when you first run the mod.
  • You need a plain text editor (like Notepad++ or VS Code) to write scripts, not Word or Google Docs.
  • The simplest script to start with is one that prints a message to the chat when you load your avatar, which teaches you the basic structure without needing to understand complex Figura functions.
  • Figura provides built-in functions (ready-made commands) that you call in your script to do things like move model parts or detect when you jump.
  • Testing your script means loading your avatar in Figura and watching the game console or chat to see if it works or if there are errors.

Set up your text editor and avatar folder

Before you write anything, you need two things: a plain text editor and a place to put your script. A plain text editor is a program that saves files as raw text with no formatting — Notepad (built into Windows) works, but Notepad++ (free, Windows) or VS Code (free, all platforms) are better because they highlight Lua code in different colors, which makes mistakes easier to spot.

Open your Minecraft folder. On Windows, press Windows key + R, type %appdata%, and look for a folder called .minecraft. On Mac, open Finder, press Command + Shift + G, and type ~/Library/Application Support/minecraft. Inside that folder, look for a directory called figura — if it does not exist, run Minecraft with Figura installed once, and the mod will create it for you.

Inside your figura folder, create a new folder with the name of your avatar (for example, my_avatar). This is your avatar directory. Inside that folder, create a new file called script.lua using your text editor. This is where your first script will live. The file name matters — Figura looks for a file called script.lua in your avatar folder when it loads.

Write a script that prints a message

Start with the simplest possible script: one that prints a message to your chat when your avatar loads. Open script.lua in your text editor and type this:

print("Hello from my Figura avatar!")

Save the file. The print() function is a Lua command that sends text to the console (a window that shows messages from the game). When Figura loads your avatar, it runs this line and you will see your message appear.

Load Minecraft, join a world or server, and open your Figura menu (the default key is usually F8, but check your keybinds). Navigate to your avatar folder and load the avatar that contains your script. If everything worked, you will see your message in the console. If you do not see it, press F3 to open the debug screen and look for a console tab, or check the latest.log file in your .minecraft folder for error messages.

Understand the structure of a real script

That first script works, but it only runs once when the avatar loads. A real script needs to run continuously while you play, checking for things that happen (like you jumping or moving) and responding to them. Figura scripts use a function called tick() that runs many times per second — this is where most of your code goes.

Here is a script structure you will use over and over:

function tick()   -- Your code here runs every frame end

Anything between function tick() and end runs repeatedly while you are in the game. The two dashes -- mark a comment, which is text the script ignores — use comments to explain what your code does so you remember later.

Figura also provides built-in functions — ready-made commands you can call to do things. For example, player:isJumping() checks whether you are jumping right now, and models:setVisible("part_name", false) hides a part of your model. You do not need to write these functions yourself; Figura provides them, and you just call them by name.

Add a simple action to your script

Now write a script that actually does something. This example makes your avatar print a message every time you jump:

local wasJumping = false function tick()   local isJumping = player:isJumping()   if isJumping and not wasJumping then     print("You jumped!")   end   wasJumping = isJumping end

This script uses a few Lua concepts. local wasJumping = false creates a variable (a container that holds information) and sets it to false. Inside tick(), local isJumping = player:isJumping() checks whether you are jumping right now. The if statement says "if you are jumping now AND you were not jumping last frame, print a message." At the end, wasJumping = isJumping remembers whether you were jumping this frame, so next frame the script can compare it to the new jump state.

Save this script, reload your avatar in Figura, and jump. You should see "You jumped!" in the console each time. If you see an error instead, check that you typed the code exactly — Lua is strict about spelling and punctuation.

Find and use Figura's built-in functions

The real power of Figura scripts comes from the functions Figura provides. These let you move model parts, change colors, detect player actions, and more. You do not need to memorize them — Figura's documentation lists them all.

The official Figura wiki (at figura.mods.gg) has a complete list of functions organized by category: player functions (things about you), model functions (things about your avatar's appearance), and event functions (things that happen in the game). When you want to do something specific — like rotate a model part or detect when you take damage — search the wiki for the function name.

For example, if you want to rotate a part of your model, the wiki shows you that models:setRotation("part_name", x, y, z) is the function to use, and it explains what each number means. You copy that function into your script, replace "part_name" with the actual name of the part you want to rotate, and fill in the rotation values.

Test your script and fix errors

When you load an avatar with a script that has a mistake, Figura will not run it and will show an error message. The error message tells you what went wrong and which line it happened on. Common mistakes include misspelling a function name, forgetting a closing parenthesis, or using a variable name that does not exist.

If your script runs but does not do what you expected, use print() to check what is happening. For example, if a function is not working, print the value of a variable to see if it is what you think it is. Open the console, look at what prints, and compare it to what you expected. This is called debugging, and it is how you figure out why code is not working the way you want.

Reload your avatar in Figura after you make changes to your script — the mod does not automatically re-read the file. Some players use a script reload command or bind a key to reload, but the simplest way to start is to unload and reload your avatar from the Figura menu.

Frequently Asked Questions

What language is Figura script written in?

Figura scripts are written in Lua, a lightweight programming language designed to be easy to learn. You do not need to know Lua before you start — you can learn it by writing simple scripts and reading the Figura wiki examples.

Where do I find the Figura wiki to look up functions?

The official Figura documentation is at figura.mods.gg and includes a complete list of functions, what they do, and examples of how to use them. The wiki is organized by category, so you can search for what you want to do.

Can I use scripts other players have written?

Yes. Many players share avatar scripts online, and you can download them and put them in your avatar folder. You can also edit shared scripts to change how they work. If you are new to scripting, reading other people's scripts is a good way to learn how things are done.

What happens if my script has an error?

Figura will show an error message in the console that tells you what went wrong and which line it happened on. Check that line for typos, missing punctuation, or function names spelled wrong. The most common mistakes are forgetting a closing parenthesis or misspelling a Figura function name.

Do my scripts run on other players' computers?

No. Your scripts run only on your computer and control how your avatar looks to other players. Other players see the result of your script (your avatar moving or changing color), but they do not run the script itself. Each player's scripts run only for them.