Getting Started

Getting Started#

Warning

Regolith is a command-line application. It assumes you have some familiarity with navigating and using the command line. If you need a refresher, check out this tutorial.

This tutorial will guide you through the basic usage of Regolith. It assumes that you’ve already installed Regolith. If not, please refer to the installation page.

By the end of this tutorial, you’ll learn how to add and run a filter from the internet in your project. Installing filters requires Git, and the example filter runs in Python. If you want to follow along, ensure you have these dependencies installed. For Git installation instructions, see the Additional Dependencies section. For Python installation instructions, refer to the Python Filters section.

Creating a New Project#

To create a new project, navigate to an empty folder and run:

regolith init

This will create a few files:

📂 example-project
    📂 .regolith
    📂 packs
        📂 BP
        📂 data
        📂 RP
    📄 .gitignore
    📄 config.json

In short:

  • .regolith: A special folder Regolith uses to store its data. You typically don’t need to access this.

  • packs/BP: The folder for your behavior pack.

  • packs/RP: The folder for your resource pack.

  • packs/data: A special folder filters can use to store additional data.

  • config.json: Regolith’s configuration file.

  • .gitignore: A file that tells Git to ignore specific files. While not part of Regolith itself, using Git to manage your projects is highly recommended.

Basic Project Configuration#

Next, open up config.json. We will be configuring a few fields here, for your addon.

{
  "author": "Your name", // Replace with your name (e.g., Bedrock-OSS)
  "name": "Project name", // Replace with your project name (e.g., spooky_gravestones)
  "packs": {
    "behaviorPack": "./packs/BP",
    "resourcePack": "./packs/RP"
  },
  "regolith": {
    "dataPath": "./packs/data",
    "filterDefinitions": {},
    "formatVersion": "1.4.0",
    "profiles": {
      "default": {
        "export": {
          "build": "standard",
          "readOnly": false,
          "target": "development"
        },
        "filters": []
      }
    }
  }
}

Later on you can play with the additional configuration options, but for now, just set a project name, and author name (marked in the snipped above with comments).

Setting the name of the project is important, because Regolith often uses it to generate the names of the exported folders, for example, resource pack and behavior pack folders in the “development” export target by default use the project name as a prefix.

Note

For more details about the config.json file, refer to the Configuration File section.

Adding Pack Files#

At this stage, you’ll want to populate your Regolith project with files.

If you have an existing addon, copy and paste your files into the RP (resource pack) and BP (behavior pack) folders within your project directory.

If you don’t have an addon prepared, you can use files from the example project prepared for this tutorial.

  1. Download the RP.zip and BP.zip files from the link above.

  2. Extract the contents of RP.zip into the RP folder.

  3. Extract the contents of BP.zip into the BP folder.

Alternatively, you can download the complete, final version of the project as getting-started-full-project.zip.

Note

Regolith supports projects that focus solely on resource packs or behavior packs. If your project doesn’t have one of these, you can remove the corresponding field (behaviorPack or resourcePack) from the config.json file and delete the unused RP or BP folder.

Running Regolith#

To run Regolith, use the following command:

regolith run

By default, this runs the default profile, which (if unmodified) is configured to export files into the development target. This means your packs will be copied into the development_behavior_packs and development_resource_packs folders within the com.mojang folder.

Adding Your First Filter#

Regolith features a powerful filter system that supports writing custom filters in various programming languages and running pre-existing filters from the internet. For now, we’ll use the Standard Filters Library, a collection of filters maintained by the creators of Regolith, Bedrock-OSS.

As an example, we will use the texture_list filter, which automatically creates the textures_list.json file for you. To learn more about this file, and why automating it is helpful, read here.

To install the texture_list filter, run the following command:

regolith install texture_list --profile=default

This command installs the filter and appends it to the “default” profile in your config.json file.

If you prefer, you can install the filter without assigning it to a profile immediately:

regolith install texture_list

Then, manually update the default profile in the config.json file to include the filter:

"default": {
  "export": {
    "readOnly": false,
    "target": "development",
    "build": "standard"
  },
  "filters": [
    {
      "filter": "texture_list"
    }
  ]
}

Now, you can re-run regolith run. This time, in addition to copying your packs into the development folders in the com.mojang folder, Regolith will also generate the textures_list.json file in your resource pack. Each time you run Regolith, this file will be re-created based on your current textures. You’ll never need to manually edit it again!

Warning

If your project doesn’t contain any textures, the texture_list.json file will be generated as an empty file ([]). Add some textures to your project to see the filter in action!