Skip to content

Commit

Permalink
Merge pull request #143 from Bedrock-OSS/docs/filter-versioning
Browse files Browse the repository at this point in the history
Docs push
  • Loading branch information
SirLich authored Feb 28, 2022
2 parents c895286 + c8219a5 commit 62ac5f0
Show file tree
Hide file tree
Showing 10 changed files with 200 additions and 115 deletions.
57 changes: 30 additions & 27 deletions docs/_pages/docs/documentation/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,56 +7,59 @@ sidebar:
nav: "sidebar"
---

The configuration of regolith is stored completely in `config.json`, at the top level of your Regolith project. This file will be created when you run `regolith init`.
The configuration of regolith is stored inside of `config.json`, at the top level of your Regolith project. This file will be created when you run `regolith init`.

## 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 Bedrock, such as [bridge](https://editor.bridge-core.app/).

Here is an example of the format:
```json
{
"name": "example_project", // Project name
"author": "Regolith Team", // Author
"packs": {
"behaviorPack": "./packs/BP",
"resourcePack": "./packs/RP"
}
}
```
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

Alongside the standard configuration options. Regolith introduces its own namespace, where our settings are defined.
Regolith builds on this standard with the addition of the `regolith` namespace, which is where all regolith-specific information is stored:

Example config:
Example config, with many options explained:

```json
{
"name": "Project Name",
// These fields come from project standard
"name": "Project name",
"author": "Your name",
"packs": {
"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": {
"dev": {
"dataPath": "./packs/data",
// Every profile contains a list of filters to run
"filters": [
{
"filter": "hello_world"
// Filter name, as defined in filter_definitions
"filter": "name_ninja",

// Settings object, which configure how name_ninja will run
"settings": {
"language": "en_GB.lang"
}
],

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

// Filter definitions contains a full list of installed filters, known to Regolith
"filterDefinitions": {
"name_ninja": {
"version": "1.0"
}
},
"dataPath": "./packs/data"
}
}
```

## Properties Explained

`profiles` is a list of filters and export options, that can be run using `regolith run`. Learn more [here](/regolith/docs/profiles).

2 changes: 1 addition & 1 deletion docs/_pages/docs/documentation/custom-filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:
nav: "sidebar"
---

Regolith allows you to write your own local files, and register them directly as filters. Special support is provided for filters written with Python, Java, and Node JS,
Regolith allows you to write your own local files, and register them directly as filters. Special support is provided for filters written with Python, Node JS, and other languages.

To start writing a custom filter, you first need a script to run. We will use `hello_world.py` as an example:

Expand Down
16 changes: 10 additions & 6 deletions docs/_pages/docs/documentation/data-folder.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ sidebar:
nav: "sidebar"
---

The Regolith `data folder` is a special folder where configs can be stored. The data folder is used to store additional configuration files and assets for filters.
The Regolith `data folder` is a special folder where configuration files can be stored.

## Location

Expand All @@ -17,9 +17,12 @@ If you would like to change the data folder location, you may do so by editing `

## Remote Filter Installation

When a remote filter is installed, it has the opportunity to place some files into your data folder. If the remote filter repository contains its own `data` folder, the contents will be moved into `data/filter_name/*`. This is a little bit like an installation script, and allows the filter to handle its own first-time setup.
When a remote filter is installed, it has the opportunity to place some files into your data folder.

Don't worry! Your data won't be lost.Installation script will never overwrite your data files. If the folder is already in use during installation, a warning will be played and the step will be skipped.
If the remote filter repository contains a `data` folder, at the same level as `filter.json`, the contents will be moved into `data/filter_name/*`. This is our supported "first time setup" flow. If you're developing a remote filter, you are encouraged to use the data folder, and create configuration files with sensible defaults.

{: .notice--warning}
Don't worry! Your data won't be lost. `regolith install` will never overwrite your data files. If the folder is already in use during installation, a warning will be logged and the step will be skipped.

## Accessing the Data Folder

Expand All @@ -28,19 +31,20 @@ When Regolith runs, it will move the `data` folder into the `tmp` directory, alo
For example: `(python)`

```py
with open('./data/bump_manifest/version.json', 'r') as f:
with open('./data/bump_manifest/version.json', 'r') as f:
print(json.load(f))
```

## Saving Data

When regolith is finished running, the data folder will be moved from the temporary location, back into the normal location. This flow allows you to store persistent data, by editing or creating new files.

This stands in contrast to the `RP` and `BP` folders, which will not be saved back into the project.
{: .notice--warning}
This stands in contrast to the `RP` and `BP` folders, which will not be saved back into the project!

For example: `(python)`

```py
with open('./data/bump_manifest/version.json', 'w') as f:
with open('./data/bump_manifest/version.json', 'w') as f:
json.dump({'version': '1.0'}, f)
```
36 changes: 12 additions & 24 deletions docs/_pages/docs/documentation/export-targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,17 @@ Export Targets determine where your generated files will go, after Regolith is f

Export is an object, and the keys inside determine how it will function. The `target` key is required, but some export targets require additional keys.

```json
"export": {
"target": "local"
}
```
# Configuration

Some configuration properties may be used with all export targets.

## readOnly

`readOnly` changes the permissions of exported files to read-only. The default value is `false`. This property can be used to protect against accidental editing of files that should only be edited by Regolith!

# Export Targets

The following targets exist.
These are the export targets that Regolith offers.

## Development

Expand All @@ -33,8 +35,7 @@ The development export target will place the compiled packs into your `com.mojan

## Local

This export target will place the compiled packs into a folder called `build`, created in your regolith project. Mostly useful for quick testing.
Example:
This export target will place the compiled packs into a folder called `build`, created in your regolith project. This export target is mostly useful for quick testing.

```json
"export": {
Expand All @@ -46,7 +47,7 @@ Example:

The Exact export target will place the files to specific, user specified locations. This is useful when you need absolute control over Regoliths export functionality.

`rpPath` and `bpPath` are required.
`rpPath` and `bpPath` are required options.

Example:

Expand All @@ -69,20 +70,7 @@ Example:
```json
"export": {
"target": "world",
"worldName": "...",
"worldPath": "...
"worldName": "...", // This
"worldPath": "..." // OR this
}
```

## Package

The packaging workflow for Regolith is still being worked on.

# Additional properties

This is a list of properties that can always be added regardless of the
`target` property being used.

- `readOnly` - changes the permissions of exported files to read-only. The default
value is `false`. This property can be used to protect against accidental
editing of files that should only be edited by Regolith.
55 changes: 0 additions & 55 deletions docs/_pages/docs/documentation/filters.md

This file was deleted.

43 changes: 42 additions & 1 deletion docs/_pages/docs/documentation/profiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ A `profile` is a collection of filters, settings, and export information. By def

## Running Profiles

You can use `regolith run` to run the default profile (dev), or use `regolith run <filter name>` to run a specific profile
You can use `regolith run` to run the default profile (dev), or use `regolith run <profile name>` to run a specific profile

## Why Profiles?

Expand All @@ -21,6 +21,47 @@ For example, `dev` profile may contain development focused filters, which are no

You can now run `regolith run dev` normally, and then sometimes `regolith run build` when you need a new final build.

Here is an example `config.json` with a second profile called `package`.

```json
{
"name": "moondust",
"author": "Regolith Gang",
"packs": {
"behaviorPack": "./packs/BP",
"resourcePack": "./packs/RP"
},
"regolith": {

// This is the list of profiles!
"profiles": {

// This is the default profile
"dev": {
"filters": [
{"filter": "example_filter"}
],
"export": {
"target": "development",
}
},

// A second profile, with different filters
"build": {
"filters": [
{"filter": "different_filter"}
],
"export": {
"target": "development",
}
}
},
"filterDefinitions": {},
"dataPath": "./packs/data"
}
}
```

## Profile Customization

For the most part, any setting inside of the Regolith config can be overridden inside of a particular profile.
Expand Down
7 changes: 7 additions & 0 deletions docs/_pages/docs/filters/creating-filter.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,10 @@ sidebar:

This step-by-step tutorial will guide you through the creation of your first Regolith filter, in the Python programming language. If you're new to Regolith, you may enjoy trying out some of our [standard filters](/regolith/docs/standard-filters) first.

## Installing Python

Before we can begin, we need to ensure that Python is installed on our system. There are [download instructions](/regolith/docs/python-filters) on our Python Filter page.

## Local Development


Loading

0 comments on commit 62ac5f0

Please sign in to comment.