Anubis: Getting Started

This page is a tutorial on Anubis, a scripting language in Baldur's Gate 3. For more on Anubis, have a look at Introduction to Anubis and the pages linked there.

Overview

This tutorial will take you through the complete process of setting up Anubis, creating your first behaviour, and configuring it for a character in the game. Even if you're new to scripting, we’ll guide you step-by-step through everything you need to know.

By the end of this tutorial, you will:

1. Set up your first Anubis script
2. Build a simple behaviour using actions and conditions
3. Create an Anubis configuration to assign that behaviour to a character in the game

Part One: Setting Up Your First Anubis Script

Installing and Setting Up Your Environment

Before writing your first script, ensure you have your code editor of choice set up.

Writing a Basic Anubis Script

We’ll start by creating a simple behaviour that makes a character stand still. Open your code editor and create a new Anubis script called Guard.ann. Let's take the following as our basic script:

game.states.Guard = State {
    function ()
        -- Action: What should the character do?
        nodes.Stand = Action {
            function()
                DebugText(me, "I'm standing still and guarding something!")
                Sleep(6.0)
            end
        }
    end
}

Understanding the Script

• State: The main building block for behaviours in Anubis. In this case, we’re defining a state called Guard. The terms State and behaviour (tree) will be used interchangeably throughout this tutorial.
• Action: Actions define what the character does within a state. Here, the action makes the character stand still and prints a message every 6 seconds.

Part Two: Building a Simple Behaviour

Next, let's modify this script to add a behaviour where a character can either wander around if there is nobody around or stand still if there is a player nearby.

Changing the Anubis Script

Let's add two possible actions for the character: Wander and Stand. This will require some basic conditions to determine when to perform each action.

Modify Guard.ann and write the following code:

game.states.Guard = State {
    function ()
        -- local variable that tells us whether the NPC is tired or not
        local tired = false
        -- Wander action
        nodes.Wander = Action {
            function()
                DebugText(me, "Not tired, wandering around")
                Sleep(6.0)
                tired = true -- after walking around needs to rest
            end,
            CanEnter = function()
                return not tired -- Wander only if not tired
            end
        }
        -- Stand still action
        nodes.Stand = Action {
            function()
                DebugText(me, "Tired, standing still and guarding something")
                Sleep(6.0)
                tired = false
            end,
            CanEnter = function()
                return tired -- Stand still only if tired
            end
        }        
    end
}

Understanding the Script

• CanEnter: Each action has a CanEnter function that checks whether it can be executed. In this example, the guard can wander around if they aren’t tired or stand still if they are. After they perform an action, we flip the tired variable, so that after the current action is finished and the game decides what the guard needs to do next, they will have to choose a different behaviour from the current one.

Placing the Script into the Correct Directory

• Move your Anubis script (Guard.ann) to the folder <PathToYourWorkspace>\Stable\LSProjects\Apps\<ProjectName>\Data\Mods\<ModName>\Scripts\anubis\node.

Part Three: Creating an Anubis Configuration

Now that you have a behaviour, you need to create a configuration (or config) file to assign this behaviour to a specific character or object in the game.

What is an Anubis Configuration?

An Anubis configuration assigns a behaviour tree (like the Guard state) to a character or object. It can also include parameters to modify how the behaviour works for that specific character.

Writing the Configuration Script

Let’s create a configuration file that assigns the Guard behavior to a character. Create a new file called Guard.anc and write the following:

game.configs.Guard = Config{
    root = StateRef{game.roots.DefaultCharacter,
        genericBehaviours = StateRef{game.states.CrimesHumanoid},
        idle = StateRef{game.states.Guard},
    }
}

Understanding the Configuration Script

• Config: This defines the configuration for a character or object.
• root: Specifies the main behaviour tree that this character should use. In this case, we assign the DefaultCharacter state (it’s a generic state that is installed with the editor which you can and should use for all characters in the game).
• parameters of DefaultCharacter: DefaultCharacter is a state that is composed of several sub-behaviours, one for the guard when he is in combat (combat), one for when he is reacting to crimes (genericBehaviours) and one for all other cases(idle). For combat and crimes we use already existing generic behaviours:
  • genericBehaviours = StateRef{game.states.CrimesHumanoid}
  • combat = StateRef{game.states.DefaultCombat}
  • For idle we need to use the behaviour that we have just created:
    • idle = StateRef{game.states.Guard}
• generic behaviours - Reusing the same generic states for combat and crimes ensures that all NPCs across the game behave in a similar manner. In most cases your config files will have a similar structure where you only need to replace the idle state with a custom state created by you.

Part Four: Testing the Script and Config in the Game

Once your script and configuration files are written, it's time to test them in the Editor.

Put the Config into the Correct Folder (Mod-Specific):

1. Move your Anubis config (Guard.anc) to the folder <PathToYourWorkspace>\Stable\LSProjects\Apps\<ProjectName>\Data\Mods\<ModName>\Scripts\anubis\config

Set Up a Character

1. Open a test level or create a new one.
2. Add a new character to the level.
3. In the Sidebar properties, find the Anubis Config Name property and assign the Guard.anc config to it.

Test the Behaviour

1. Enter Game Mode.
2. Check whether the character changes their behaviour and displays a different debug message every 6 seconds.

Conclusion

In this tutorial, you’ve successfully:

• Set up your first Anubis script
• Created a simple behaviour where a character can wander or guard something
• Configured the behaviour for use in the game

You now have the foundational knowledge to create more complex behaviours, handle conditions, and assign them to different characters in your game. Next, you can explore Modifying Simple Behaviours with Interruptions and Selectors or adding more advanced features to your scripts like Adding Proxy Nodes and Expanding Selection Logic!