Installing Filters

To begin using a filter in Regolith, follow these four steps:

1. Ensure that you can run the filter.

2. Install the filter.

3. Add the filter to the desired profile.

4. Run your profile to test the filter.

Filter Dependencies

Filters are typically written in specific programming languages, and these languages may not be installed on your computer by default. Before installing a filter, ensure you have the required programming language(s) installed. Detailed installation instructions for every Regolith-supported language can be found in the “Filter Types” documentation.

For instance, if a filter depends on Python, you can find the installation instructions here.

Install Command

Warning

The install command requires git. You can read more about Git here.

Regolith provides a powerful install command that downloads filters from Git repositories and installs any necessary libraries. The general format is:

regolith install <filter_identifier>

The filter_identifier depends on where the filter is hosted. Filters listed in the resolvers of your user configuration can be installed directly by name. By default, Regolith uses the resolver hosted on the Bedrock-OSS/regolith-filter-resolver repository.

For example, to install the name_ninja filter (a Bedrock-OSS filter), run:

regolith install name_ninja

If the filter is not listed in the resolver repository, you need to use the following format:

regolith install github.com/<user>/<repository>/<folder>

Or, for non-GitHub hosted filters:

regolith install <repository-url>/<folder>

For example, to install name_ninja using the full format:

regolith install github.com/Bedrock-OSS/regolith-filters/name_ninja

You can install multiple filters at once by passing multiple arguments:

regolith install name_ninja texture_list

The install command also supports installing specific versions of filters. For more details, refer to the Filter Versioning page. By default, Regolith installs the latest release of each filter.

Adding Filter to Profile

Once the filter is installed, it will appear in the filterDefinitions section of config.json. You can now add it to a profile, like this:

"default": {
  "export": {
    "readOnly": false,
    "target": "development",
    "build": "standard"
  },
  "filters": [
    {
      "filter": "name_ninja" // The name of the filter from filterDefinitions
    }
  ]
}

If the filter doesn’t need any additional configuration you can append it to the end of the list of the filters of the profile by using the --profile flag. For example:

regolith install name_ninja --profile=default

This command will automatically add the filter to the filter list of the default profile.

Install All Command

Regolith is designed to be used with Git version control. By default, the .regolith folder is ignored. This means that when collaborating on a project or re-cloning existing ones, you’ll need a quick way to re-download all the filters.

You can use the regolith install-all command, which checks your config.json file and installs every filter listed in the filterDefinitions.

Cached Results of Regolith Install

When installing multiple filters in quick succession, Regolith avoids unnecessary updates to the filter and resolver repositories that are cached on your computer. It checks the timestamp of the last cache update and skips refreshing the cache if it’s recent enough.

In some situations, you might want to skip the cache wait time and force an update. The install command has two flags that can force a cache update:

• --force-filter-refresh: Forces the update of the filter cache, even if the filter repository was downloaded recently.

• --force-resolver-refresh: Forces the update of the resolver cache, even if the resolver repository was downloaded recently. Note: This flag is not available for the install-all command because install-all doesn’t use resolvers; it depends on the URLs provided directly in the config.json.

You can adjust the default cooldown times for downloading filters in your user configuration.

If you want to update the filter resolvers, without installing any filters, you can use the following command:

regolith update-resolvers