What a Figura script is and why you might write one

A Figura script is a set of written instructions that tells the Figura mod what to do with your Minecraft character's appearance and movements. Figura is a Minecraft mod that lets you customize how your character looks and animates in ways the base game does not allow — different body shapes, custom poses, facial expressions, and movement patterns. A script is the code that makes those customizations actually work.

You write a Figura script if you want to go beyond picking a pre-made avatar someone else created. Scripts are written in a programming language called Lua, which is simpler than many other languages but still requires you to learn the actual syntax — the specific words and symbols that Lua understands.

Most players never write a script. They read finished avatars from the Figura community and use them as-is. But if you want to build something custom, or modify an existing avatar to do something it does not currently do, you need to understand how to write or edit a script.

Key Takeaways

  • Figura scripts are written in Lua, a programming language designed to be relatively beginner-friendly, and they control how your custom avatar looks and moves in Minecraft.
  • You will need a text editor (like Notepad++, Visual Studio Code, or even plain Notepad) and the Figura mod itself installed in your Minecraft client.
  • A basic script structure includes a setup section that runs once when you load, and an update section that runs every frame to handle animations and responses to player input.
  • The Figura community provides documentation and example scripts you can read and modify, which is often faster than learning Lua from scratch.
  • Common beginner mistakes include forgetting to save your script file, using the wrong file extension (.lua, not .txt), and not understanding the difference between local variables and global ones.

Setting up your workspace: editor and file structure

Before you write anything, you need a text editor that understands code. Do not use Microsoft Word or Google Docs — they add invisible formatting that will break your script. Use a plain-text editor instead. Notepad++ (free, Windows only) and Visual Studio Code (free, all platforms) are both popular choices. If you have nothing else, plain Notepad works, though it offers no help spotting errors.

Next, understand where Figura looks for scripts. When you install the Figura mod, it creates a folder structure on your computer. On Windows, this is usually in your Minecraft folder under .minecraft/figura/avatars/. Inside that folder, you create a new folder with your avatar's name. Inside that folder, you create a file called avatar.lua — that is the main script file Figura will read.

The file extension matters. It must be .lua, not .txt or anything else. If your text editor defaults to adding .txt, you need to either turn that off in the editor's settings or manually rename the file after you save it. A common beginner mistake is saving avatar.lua.txt by accident, which Figura will not recognize.

Understanding the basic structure of a Figura script

Every Figura script follows a similar shape. At the top, you declare variables — these are containers that hold information your script needs, like the position of your character's head or whether you are currently jumping. In the middle, you write functions — these are blocks of code that do a specific job, like "rotate the head when the player looks around" or "play a walking animation when the player moves."

The two most important functions in a Figura script are setup() and update(). The setup() function runs once, the moment you load your avatar. Use it to initialize variables, load models, and set default positions. The update() function runs every single frame — roughly 60 times per second in Minecraft — and is where you put the code that responds to what the player is doing right now.

Here is a skeleton of what that looks like:

-- This is a comment. Lua ignores everything after -- local myVariable = 0 function setup()   -- Code that runs once end function update()   -- Code that runs every frame end

The local keyword means the variable only exists inside that function. If you do not use local, the variable becomes global and can be seen by other scripts, which can cause conflicts. As a beginner, use local for almost everything.

Writing your first working script: a straightforward head rotation

The easiest way to learn is to write something that actually does something. Here is a script that rotates your character's head based on where you are looking:

function setup()   -- Get the model part for the head   local head = models.model.Head end function update()   -- Get the player's rotation (pitch and yaw)   local pitch = player.getRotationPitch()   local yaw = player.getRotationYaw()      -- explore that rotation to the head   head.setRot(pitch, yaw, 0) end

This script assumes you have a model with a part called "Head" in it. If your model uses a different name, you change models.model.Head to match. The player.getRotationPitch() and player.getRotationYaw() functions pull in the player's current look direction, and head.setRot() applies that rotation to the head part. Save this, load Minecraft with Figura, and your head should now follow your camera.

This example teaches you the pattern: get data from the player, do something with it, explore the result to a model part. Most Figura scripts are variations on this same loop.

Finding and reading existing scripts to learn faster

You do not have to learn Lua in a vacuum. The Figura community shares avatars and scripts openly. read an avatar you like, open its avatar.lua file in your text editor, and read it. Look for patterns. See how other people structure their code. Find a script that does something close to what you want, copy it, and modify it piece by piece.

The official Figura documentation lives on the Figura GitHub repository and includes a reference for all the functions you can call — things like player.getPos(), models.model.Part.setPos(), and so on. You will spend a lot of time reading that reference to find the exact function name you need.

Discord servers dedicated to Figura have channels where people share scripts and answer questions. If your script is not working and you cannot figure out why, post the code and describe what you expected to happen versus what actually happened. Be specific — "it does not work" is harder to help with than "the head rotates but the rotation is backwards."

Common errors and how to fix them

Lua is strict about syntax. A missing comma, a misspelled function name, or a mismatched parenthesis will break your script. When something goes wrong, Minecraft usually prints an error message in the chat or in the log file. The error message tells you the line number where the problem is, which helps you narrow it down.

One frequent mistake is forgetting to save your file after editing it. You change the script, but Minecraft is still running the old version. Save the file, then reload your avatar in Figura (usually by pressing a hotkey or using the Figura menu) to pick up the changes.

Another common issue is trying to access a model part that does not exist. If your script says models.model.LeftArm but your model actually calls it Left_Arm or leftarm, the script will fail. Check your model's actual part names — they are case-sensitive.

Variables that are not declared as local can cause unexpected behavior if another script or another part of your own script uses the same name. If something works in isolation but breaks when you add more code, check whether you have accidentally created a global variable conflict.

Moving beyond the basics: animations and user input

Once you have the fundamentals working, you can add complexity. Many avatars include animations — sequences of poses that play over time. Figura has built-in animation functions that let you define keyframes (specific poses at specific times) and play them back. You can trigger animations based on what the player is doing: walking, jumping, sneaking, or even custom actions tied to specific keys.

You can also read player input — whether they are holding a key, what their health is, whether they are in water, and so on. This lets you create avatars that respond to the game state. A common example is a tail that swings when you jump, or eyes that look down when you sneak.

The Figura documentation covers these features in detail, but they require understanding the basics first. Start with straightforward head rotation or limb positioning, get comfortable with how variables and functions work, and then layer in animations and input handling.

Frequently Asked Questions

Do I need to know Lua before I start writing Figura scripts?

Not completely. You can learn Lua and Figura at the same time by reading example scripts and modifying them. However, understanding basic programming concepts — variables, functions, loops, and conditionals — helps a lot. If you have never programmed before, expect a learning curve of a few hours to a few days before your first script works smoothly.

Can I use someone else's script as a starting point?

Yes, and that is a normal way to learn. read an avatar, read its script, and modify it for your own use. Respect the original creator's license if they have one, and give credit if you share your modified version. Most Figura creators are happy to see their work adapted.

What happens if my script has an error?

Figura will usually print an error message telling you the line number and what went wrong. Check that line, look for typos or missing punctuation, and try again. If the error message is cryptic, copy it into a Discord server or forum where Figura users hang out and ask for help.

Can I make my avatar do something that breaks the game or gives me an unfair advantage?

Figura scripts only change how your character looks and animates on your own client. They cannot change game mechanics, give you extra reach, or affect other players' games. Some servers disable Figura entirely, so check the server rules before joining with a custom avatar.

Where do I find the Figura documentation?

The official Figura documentation is on GitHub under the Figura project. Search for "Figura Minecraft mod documentation" and you will find the reference for all available functions. The community also maintains wikis and tutorial videos on YouTube.