diff --git a/docs/_pages/docs/documentation/config.md b/docs/_pages/docs/documentation/config.md index 15bf27c8..b6e0eb46 100644 --- a/docs/_pages/docs/documentation/config.md +++ b/docs/_pages/docs/documentation/config.md @@ -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 ' "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). - diff --git a/docs/_pages/docs/documentation/custom-filters.md b/docs/_pages/docs/documentation/custom-filters.md index 1e0ccc05..d54fa57a 100644 --- a/docs/_pages/docs/documentation/custom-filters.md +++ b/docs/_pages/docs/documentation/custom-filters.md @@ -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: diff --git a/docs/_pages/docs/documentation/data-folder.md b/docs/_pages/docs/documentation/data-folder.md index 4752073f..93eed131 100644 --- a/docs/_pages/docs/documentation/data-folder.md +++ b/docs/_pages/docs/documentation/data-folder.md @@ -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 @@ -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 @@ -28,7 +31,7 @@ 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)) ``` @@ -36,11 +39,12 @@ with open('./data/bump_manifest/version.json', 'r') as f: 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) ``` \ No newline at end of file diff --git a/docs/_pages/docs/documentation/export-targets.md b/docs/_pages/docs/documentation/export-targets.md index 6a0b8f5b..f5fd0554 100644 --- a/docs/_pages/docs/documentation/export-targets.md +++ b/docs/_pages/docs/documentation/export-targets.md @@ -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 @@ -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": { @@ -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: @@ -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. diff --git a/docs/_pages/docs/documentation/filters.md b/docs/_pages/docs/documentation/filters.md deleted file mode 100644 index 4d982930..00000000 --- a/docs/_pages/docs/documentation/filters.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -permalink: /docs/filter-types -layout: single -classes: wide -title: Filters -sidebar: - nav: "sidebar" ---- - -Regolith contains three distinct filter types, which allow you maximum flexibility in where to store your logic. - -## Standard Library - -The standard library is a special [github repository](https://github.com/Bedrock-OSS/regolith-filters) hosted in the Bedrock OSS organization. - -This repository is special, since folders here can be accessed by-name inside of Regolith, instead of by URL. This makes the standard library very easy to use for beginners! - -The full list of available standard-library filters can be found [here](/regolith/docs/standard-library). - - -Example: - -```json -{ - "filter": "json_cleaner" -} -``` - -This filter is equivalent to `"url": "https://github.com/Bedrock-OSS/regolith-filters/tree/master/json_cleaner"`, but since its hosted in our repository, you can just use the folder name. - -## Online Filters - -Online filters use the same format as standard filters, except instead of being hosted in our library repository, they can be contained in any github repository. This allows you to easily share your filters with other people. Regolith will handle the installation process. - -Example: - -```json -{ - "url": "github.com/user/repo/folder" -} -``` - -## Local Filters - -Local filters are great for quickly prototyping, or for personal filters that you do not want to share with anyone. In this case, you can simply run a local file: - - -```json -{ - "runWith": "python", - "script": "./filters/example.py" -} -``` - -The `.` path will be local to the root of the regolith project. \ No newline at end of file diff --git a/docs/_pages/docs/documentation/profiles.md b/docs/_pages/docs/documentation/profiles.md index 5a805890..19387a75 100644 --- a/docs/_pages/docs/documentation/profiles.md +++ b/docs/_pages/docs/documentation/profiles.md @@ -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 ` to run a specific profile +You can use `regolith run` to run the default profile (dev), or use `regolith run ` to run a specific profile ## Why Profiles? @@ -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. diff --git a/docs/_pages/docs/filters/creating-filter.md b/docs/_pages/docs/filters/creating-filter.md index ef508d6f..9d4106f5 100644 --- a/docs/_pages/docs/filters/creating-filter.md +++ b/docs/_pages/docs/filters/creating-filter.md @@ -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 + + diff --git a/docs/_pages/docs/filters/filters.md b/docs/_pages/docs/filters/filters.md new file mode 100644 index 00000000..fe74549c --- /dev/null +++ b/docs/_pages/docs/filters/filters.md @@ -0,0 +1,95 @@ +--- +permalink: /docs/filter-types +layout: single +classes: wide +title: Filters +sidebar: + nav: "sidebar" +--- + +A filter is any program or script that takes the files inside of your RP and BP and *transforms* them in some way. Many of these filters have already been written, and are included as part of the [standard library](/regolith/docs/standard-filters). You may also be interested in [community filters](/regolith/docs/community-filters) + +At it's core, you can think of a filter as the ability to run arbitrary code during the compilation process. This allows you to accomplish a number of tasks: + + - Linting and error checking + - Code generation/automation + - Interpreting custom syntax + +## Installing and Using Filters + +To start using a filter, you need to do three things: + + 1) Ensure you can run the filter + 2) Install the filter + 3) Add the filter to the profile which you would like to use it. + +### Filter Dependencies + +Filters are written in programming languages. These languages may not be installed on your computer by default. Before installing a filter, you should ensure you have the proper programming installed. The "Filter Types" documentation documentation has detailed installation instructions for every regolith-supported language. + +For example if the filter relies on python, you can find [installation instructions here](regolith/docs/python-filters). + +### Installing a Filter + +Regolith contains a powerful installation command, which will download a filter from github, and install any required libraries for you. In general, the format is like this: + +`regolith install ` + +The value of `location` will depend on where the filter is hosted. This is explained bellow. + +{: .notice--warning} +The `install` command relies on `git`. [You may download git here](https://git-scm.com/download/win). + +### Adding Filter to Profile + +After installing, the filter will appear inside of `filter_definitions` of `config.json`. You can now add this filter to a profile like this: + +```json +"dev": { + "export": { + "readOnly": false, + "target": "development" + }, + "filters": [ + { + "filter": "FILTER_NAME", + } + ] +} +``` + +## Filter Types + +### Standard Library +The standard library is a special [github repository](https://github.com/Bedrock-OSS/regolith-filters) hosted in the Bedrock OSS organization. This repository is special, since filters here can be accessed by name, instead of by URL. This makes the standard library very easy to use for beginners! + +The full list of available standard-library filters can be found [here](/regolith/docs/standard-library). + +To install, you may use the name directly: e.g., `regolith install json_cleaner` + +{: .notice--warning} +This is equivalent to `regolith install https://github.com/Bedrock-OSS/regolith-filters/tree/master/json_cleaner`, but since its hosted in our repository, you can just use `json_cleaner`! + +### Community Filters + +Community filters use the same format as standard filters, except instead of being hosted in our library repository, they can be contained in any github repository. To install a community filter, you will need to use the full URL: + +Example: `regolith install https://github.com/Bedrock-OSS/regolith-filters/tree/master/json_cleaner` + +## Filter Versions + + + +## Local Filters + +Local filters are great for quickly prototyping, or for personal filters that you do not want to share with anyone. In this case, you can simply run a local file: + + +```json +{ + "runWith": "python", + "script": "./filters/example.py" +} +``` + +The `.` path will be local to the root of the regolith project. \ No newline at end of file diff --git a/docs/_pages/docs/documentation/online-filters.md b/docs/_pages/docs/filters/online-filters.md similarity index 100% rename from docs/_pages/docs/documentation/online-filters.md rename to docs/_pages/docs/filters/online-filters.md diff --git a/docs/_pages/docs/getting_started/getting-started.md b/docs/_pages/docs/getting_started/getting-started.md index 0fffd3d1..b02dc1ea 100644 --- a/docs/_pages/docs/getting_started/getting-started.md +++ b/docs/_pages/docs/getting_started/getting-started.md @@ -17,7 +17,6 @@ If you run into issues installing, you can check our [troubleshooting guide](/re **Warning:** Regolith is a command line application. It assumes some familiarity with how to navigate and use the command line. You can get a [refresher](https://tutorial.djangogirls.org/en/intro_to_command_line/) here. - ## Creating a new Project To create a new project, navigate to a blank folder, and run `regolith init`. This will create a few files: @@ -91,6 +90,9 @@ As an example, we will use the `texture_list` filter, which automatically create ### Installing +{: .notice--warning} +The `install` command relies on `git`. [You may download git here](https://git-scm.com/download/win). + You can install this filter by running `regolith install texture_list`, which will make the filter available for use. The last step is selecting where/when the filter will run. In our case, we want to run the filter every time we export using the default `dev` profile.