Skip to content

Commit

Permalink
Update the configuration.md and change the order of the pages in the …
Browse files Browse the repository at this point in the history 
…'advanced' section.
  • Loading branch information
@Nusiq
Nusiq committed Dec 14, 2024
1 parent 4d25b60 commit 08dcc65
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 76 deletions.
147 changes: 73 additions & 74 deletions docs/advanced/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ The configuration of Regolith project is stored inside of `config.json`, at the

## Project Config Standard

Regolith follows the [Project Config Standard](https://github.com/Bedrock-OSS/project-config-standard). This config is a shared format, used by programs that interact with Minecraft projects, such as [bridge](https://editor.bridge-core.app/).
Regolith follows the [Project Config Standard](https://github.com/Bedrock-OSS/project-config-standard). This config is a shared format, used by programs that interact with Minecraft projects, such as ["bridge."](https://editor.bridge-core.app/).

## Regolith Configuration

Expand All @@ -15,83 +15,82 @@ Regolith builds on this standard with the addition of the `regolith` namespace,
This page only shows an example configuration. There are other documentation pages to fully explain concepts such as `filters` and `profiles`.
```

Example config, with many options explained:

Example configuration file:
```json
{
// These fields come from project standard
"name": "Project Name",
"author": "Author Name",
"packs": {
// You should create your packs directly within these folders.
// Example: 'regolith_project/packs/BP/manifest.json'
"behaviorPack": "./packs/BP",
"resourcePack": "./packs/RP"
},

// These fields are for Regolith specifically
"regolith": {
// Profiles are a list of filters and export information, which can be run with 'regolith run <profile>'
"profiles": {
// 'default' is the default profile. You can add more.
"default": {

// Every profile contains a list of filters to run, in order.
"filters": [
{
// Filter name, as defined in filter_definitions
"filter": "name_ninja",

// Settings object, which configure how name_ninja will run (optional)
"settings": {
"language": "en_GB.lang"
"name": "Project Name",
"author": "Author Name",
"packs": {
"behaviorPack": "./packs/BP",
"resourcePack": "./packs/RP"
},
"regolith": {
"formatVersion": "1.4.0",
"dataPath": "./packs/data",
"filterDefinitions": {
"bump_manifest": {
"url": "github.com/Bedrock-OSS/regolith-filters",
"version": "1.0.0"
},
"name_ninja": {
"url": "github.com/Bedrock-OSS/regolith-filters",
"version": "1.2.4"
}
},
"profiles": {
"default": {
"filters": [
{
"filter": "name_ninja",
"settings": {
"language": "en_GB.lang"
}
},
{
"filter": "bump_manifest",
"arguments": ["-regolith"],
"disabled": true,
"when": "os == 'windows' && arch == 'amd64'"
}
],
"export": {
"target": "development",
"build": "standard",
"readOnly": false
}
}
},
{
// A second filter, which will run after 'name_ninja'
"filter": "bump_manifest",

// Arguments list is a list of arguments to pass to the command that runs the filter (optional).
// If filter uses both settings and arguments, the settings json is passed as the first argument.
"arguments": ["-regolith"],

// "disabled" is a bolean that determines whether or not to run this filter (optional).
"disabled": true,

// "when" lets you specify a condition, which determines whether or not to run
// this filter. "when" has access to following variables:
// - "os" - the operating system (e.g. "windows", "linux", "darwin")
// - "arch" - the architecture (e.g. "amd64", "arm64")
// - "version" - the version of regolith or 0.0.0 when running from source
// - "debug" - whether the debug flag is passed to regolith or not
// - "profile" - current profile being run
// - "filterLocation" - absolute location of the filter folder
"when": "os == 'windows' && arch == 'amd64'"
}
],

// Export target defines where your files will be exported
"export": {
"target": "development",
"build": "standard",
"readOnly": false
}
}
},
}
}
```

// Filter definitions contains a full list of installed filters, known to Regolith.
// You may install more filters using 'regolith install <identifier>'
"filterDefinitions": {
"name_ninja": {
"version": "1.0"
},
"bump_manifest": {
"version": "1.0"
}
},
### Project Config Standard Fields
- `name`- The name of the project. Regolith uses it to determine the names of the exported packs in some cases. See {ref}`Export Targets<export-targets>` for more information.
- `author`- The author of the project.
- `packs`- The location of the behavior and resource packs.

// The path to your regolith data folder, which contains configuration files for your filter.
"dataPath": "./packs/data"
}
}
### Regolith Fields
Everything inside the `regolith` field contains Regolith-specific information.

#### formatVersion
The version of the Regolith configuration format. This is used to determine how Regolith should read the configuration file. Usually, you don't have to worry about this field, Regolith will create it for you when you initialize a project.

```{warning}
The `formatVersion` field was introduced quite late in the development of Regolith. The format version changes when the format of the configuration file changes in a way that breaks the backward compatibility. The format versions use the same version number as the version of Regolith that introduce them. Not all versions of Regolith add new format version. The lowest possible value and the default (if not specified) is `1.2.0`.
```

Below is a list of available format versions and the changes they introduced:

- `1.2.0` - The first available `formatVersion'. This is the default if the field is not specified.
- `1.4.0` - This version changed the way the `export` field works. You can read about the current implementation of the export target in {ref}`it's own page<export-targets>`. Unfortunately, the `1.4.0` format change was implemented before we had versioned documentation, so the only way to read about it now is to look at the [source of the old version of the documentation](https://github.com/Bedrock-OSS/regolith/blob/1.2.0/docs/docs/guide/export-targets.md).

#### dataPath
The path to the folder where Regolith will store the data folders of the filters. It's like an extension to `behaviorPack` and `resourcePack` folders, feeding data to your project, but specifically for the Regolith filters.

#### filterDefinitions
Filter definitions is mostly managed by Regolith itself. It contains a list of the filters used in the project. Every time you run the `regolith install` command, Regolith will add a new filter to this list with its version and URL.

The only time you should manually edit this field is when you want create a {ref}`local filter<local-filters>`.

#### profiles
Profiles are sequences of filters that you can run with the `regolith run` command. You can read more about them in the {ref}`profiles page<profiles>`.
4 changes: 2 additions & 2 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ Safety <introduction/safety>
:caption: Advanced
Configuration File <advanced/configuration>
Profiles <advanced/profiles>
Export Targets <advanced/export-targets>
User Configuration <advanced/user-configuration>
Data Folder <advanced/data-folder>
Export Targets <advanced/export-targets>
Profiles <advanced/profiles>
Experiments <advanced/experiments>
```

Expand Down

0 comments on commit 08dcc65

Please sign in to comment.