Addons

Addons

Pantella has a system for addons that allows you to extend the functionality without needing to modify the core code. This is useful for creating addons you intend to share with end-users, or for creating addons that are specific to your own use case.

Typically addons are added to the addons directory in the Pantella installation. They might also require a plugin to be installed in your game to send game events to Pantella. This is useful for creating custom game events that can be used to trigger custom lines in Pantella.

Addons - The Basics

Addons are comprised of a metadata.json file and several folders with python scripts. The metadata.json file is used to define the addon's name, version, and other metadata. The python scripts are used to extend the functionality of Pantella.

Addons can also include a characters directory that contains character files. These character files can be used to define custom characters that can be used in the game. You can read more about characters and their associated files in the Characters page.

Addons can also include a voice_samples directory that contains more dictionaries labeled with two letter language codes, and within those directories, the voice samples for the characters in the addon. This can also be used to add voice samples for any character in the base game lacking a voice. You can read more about voice samples and their associated files in the Text To Speech page.

Addons can also include a behaviors directory that contains behavior files. These behavior files can be used to define custom behaviors that can be used in the game. You can read more about behaviors and their associated files in the Behaviors page.

Addons can also include a game_event_renderers directory that contains python scripts that render game events. These scripts can be used to render custom game events that are sent to Pantella. You can read more about game event renderers below.

Addons can finally also include a prompt_style.json file that contains custom prompt styles. This file can be used to define custom prompt styles that can be used in the game. You can read more about prompt styles and their associated files in the Prompt Style Info page and below.

There are going to be more parts to addons in the future, but for now, this is the basic structure of an addon.

Creating a Basic Addon

Addons are comprised of a metadata.json file and several folders with python scripts. The metadata.json file is used to define the addon's name, version, and other metadata. The python scripts are used to extend the functionality of Pantella. First step is adding support to Skyrim to send the game events to Pantella. You'll need to create a plugin in the Creation Kit that sends the game events to Pantella.

1 - Creating a Plugin

There's a bunch of ways this could be handled, but the way I'm going to use for this demonstration is to create a new quest in the Creation Kit that will have a script that listens for events and sends game events to Pantella. This is a simple way to get started.

Open your Creation Kit and create a new quest. Name it something like YourAddonPantellaGameEvents. Lets say you want to add a game event for when the player enters the Bannered Mare. Bare in mind, a game event is already normally sent whenever you change location but lets pretend this isn't redunant for the sake of the demonstration.

First open the quest and go to the Scripts. Then click Add to create a new script. Name it something like YourAddonPantellaGameEventsScript. Open the script and add the following code:

2 - Writing the Papyrus Script

Scriptname YourAddonPantellaGameEventsScript extends Quest

Event OnLocationChange(Location akOldLocation, Location akNewLocation)
    ; check if radiant dialogue is playing, and end conversation if the player leaves the area
    String radiant_dialogue_active = MiscUtil.ReadFromFile("_pantella_radiant_dialogue.txt") as String
    if radiant_dialogue_active == "True"
        MiscUtil.WriteToFile("_pantella_end_conversation.txt", "True",  append=false)
    endIf
    String currLoc = (akNewLocation as form).GetName()
    if currLoc == ""
        currLoc = "Skyrim"
    endIf
    if currLoc == "WhiterunBanneredMare"
        MiscUtil.WriteToFile("_pantella_in_game_events.txt", "your_addon_line_type<ArrivedAtBanneredMare>\n")
    endIf
endEvent

Make sure to compile the script and save it. Then go back to the quest and add the script to the quest. Save the plugin and then load install it in your Skyrim game.

3 - Creating the Pantella Addon

To create an addon, you need to create a folder in the addons directory of the Pantella installation. The folder should be named after your addon. Inside the folder, you need to create a metadata.json file. The metadata.json file should contain the following fields:

{
    "name": "template_addon_name_1",
    "version": "1.0.0",
    "description": "A template addon for creating new addons.",
    "author": "Your username/a link to your profile",
    "project_url": "https://link/to/your/project/repo/this/addon/is/for",
    "enabled": false,
    "dependencies": [
        {
            "type": "llm",
            "name": "openai_api"
        },
        {
            "type": "character",
            "name": "Jarl Balgruuf the Greater",
            "ref_id": "00013BAA",
            "base_id": "00013BAA"
        },
        {
            "type": "addon",
            "name": "generic_guard_templates",
            "min_version": "1.0.0"
        }
    ]
}

• name (string): The name of the addon.
• version (string): The version of the addon.
• description (string): A description of the addon.
• author (string): The author of the addon.
• project_url (string): A URL to the project the addon is for.
• enabled (boolean): Whether the addon is enabled or not.
• dependencies (list): A list of dependencies for the addon. Each dependency should have the following fields:
  • type (string): The type of dependency. Can be llm, character, or addon.
  • name (string): The name of the dependency.
  • ref_id (string, optional): The ref_id of the dependency. Only required for character dependencies.
  • base_id (string, optional): The base_id of the dependency. Only required for character dependencies.
  • min_version (string, optional): The minimum version of the dependency. Only required for addon dependencies.

Depenecies are optional to include.

After creating the metadata.json file, you can work on adding functionality for your custom game events. There's two ways to do this. You can either create a prompt_style.json file in the addon directory, or create another folder in the addon directory called game_event_renderers. Inside the game_event_renderers folder, you can create a python script that will handle the game event.

Using a Python Script

The script should have a function called render that takes in the line type, the game_event_type, a dictionary called args_dict and the raw line. Here's an example of what the script could look like: The name of the script can be default.py or it should match the game event title.

# ./addons/your_addon/game_event_renderers/your_addon_line_type/default.py
from src.logging import logging # Import the logging module to add logs to the log file.
def render(line_type: str, game_event_title: str, args_dict: dict, line: str):
    """Render the line based on the line type."""
    logging.info(f"Rendering line: {line_type} - {game_event_title} - {line}", args_dict)
    if game_event_title == "ArrivedAtBanneredMare":
        return "You have arrived at the Bannered Mare."

# ./addons/your_addon/game_event_renderers/your_addon_line_type/ArrivedAtBanneredMare.py
from src.logging import logging # Import the logging module to add logs to the log file.
def render(line_type: str, game_event_title: str, args_dict: dict, line: str):
    """Render the line based on the line type."""
    logging.info(f"Rendering line: {line_type} - {game_event_title} - {line}", args_dict)
    return "You have arrived at the Bannered Mare."

Using a prompt_style.json file

Alternatively, and more realistically for this specific example, you can create a prompt_style.json file in the addon directory. The prompt_style.json file should contain the following fields:

{
    "your_addon_line_type": {
        "ArrivedAtBanneredMare": "You have arrived at the Bannered Mare."
    }
}

This will render the line "You have arrived at the Bannered Mare." when the game event "ArrivedAtBanneredMare" is sent to Pantella. Congratulations! You've created your first Pantella addon. You can now enable the addon and test it out in your game.

Addons - The Future

In the future, Pantella will have a more robust system for creating addons. This will allow addons to include new inference engines, new character generators, new behavior managers, and more. This will allow for a more modular system that can be extended by the community. If you have any ideas for addons, feel free to share them in the #general channel on the Pantella Discord server. If you would like to learn more about the modules in Pantella, you can read about them in the Modules page.