diff --git a/README.md b/README.md index 39ff703..aa7fb08 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,74 @@ # Intorduction -The documentation of the Regolith project. +The repository of the documentation of the Regolith project. -If you're looking for Regolith repository, you can find it here: [https://github.com/Bedrock-OSS/regolith/](https://github.com/Bedrock-OSS/regolith/) +- If you're looking for the hosted documentation, you can find it here: [https://regolith-docs.readthedocs.io/](https://regolith-docs.readthedocs.io/) +- If you're looking for Regolith repository, you can find it here: [https://github.com/Bedrock-OSS/regolith/](https://github.com/Bedrock-OSS/regolith/) + +# Contributing +## Building Documentation Locally +This repository uses the `sphinx` documentation generator. The documentation is stored in the `docs` directory. All commands listed below assume that you are executing them from the `docs` directory. You can switch to the `docs` directory by running `cd docs`. + +### Installing Documentation Dependencies +To build the documentation you need to install required dependencies. +``` +pip install -r requirements.txt +``` +### Building Documentation for the First Time +When you build the documentation for the first time, you need +``` +./make.bat html +``` + +### Hosting Documentation Locally +You can host the documentation locally with the Python's built-in HTTP server. +``` +python -m http.server --bind localhost -d .\_build\html\ +``` +Then you can access the documentation at [http://localhost:8000](http://localhost:8000) + +### Rebuilding Documentation +To rebuild the documentation you can run the `./make.bat html` but it is recommended to clean the build directory first. You can clean the build directory by running the following command. +``` +rm -r _build\;./make.bat html +``` + +## Documentation Syntax +We're using the `myst-parser` to enable the markdown syntax in the documentation. There are a few things that you need to know about the syntax that aren't part of the standard Markdown. + +### Table of Contents + +Table of contents is defined in the `index.md` file. It is pretty simple to understand. You can read the `docs/index.md` file to learn by example. + +### Labels and References +Sphinx lets you define a name for a sectin of the documentation that you can use to create a hyperlink to that section in othe parts of the documentation. Linking pages like that is safer than linking them by their path because if the path changes, the link will still work. + +To define a label for a section, you can use the following syntax: +```markdown +(your-label)= +# Your Section Title +... +``` + +To link to that section, you can use the following syntax: +```markdown +{ref}`Text To Display` +``` + +When you build the documentation using the `make.bat` script, the commandline output will print warnings about the labels that aren't used or the references that are broken. + +### Note and Warning Boxes +You can create a colored box for notes and warnings by using the following syntax: +````markdown +```{note} +This is a note +``` +```` + +````markdown +```{warning} +This is a warning +``` +```` + +## Contribution Process +Simply for the repository, do your changes and create a pull request. diff --git a/docs/advanced/configuration.md b/docs/advanced/configuration.md deleted file mode 100644 index 8a81e64..0000000 --- a/docs/advanced/configuration.md +++ /dev/null @@ -1,97 +0,0 @@ -(configuration-file)= -# Configuration File - -The configuration of Regolith project 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 projects, such as [bridge](https://editor.bridge-core.app/). - -## Regolith Configuration - -Regolith builds on this standard with the addition of the `regolith` namespace, which is where all regolith-specific information is stored. - -```{warning} -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: - -```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 ' - "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" - } - }, - { - // 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 ' - "filterDefinitions": { - "name_ninja": { - "version": "1.0" - }, - "bump_manifest": { - "version": "1.0" - } - }, - - // The path to your regolith data folder, which contains configuration files for your filter. - "dataPath": "./packs/data" - } -} -``` diff --git a/docs/advanced/data-folder.md b/docs/advanced/data-folder.md deleted file mode 100644 index f3c1527..0000000 --- a/docs/advanced/data-folder.md +++ /dev/null @@ -1,66 +0,0 @@ -(data-folder)= -# Data Folder - -The Regolith `data` folder is a special folder where configuration files can be stored. - -## Location - -By default, the data folder is stored in `./packs/data`. This folder will be created for you when you run `regolith init`. - -If you would like to change the data folder location, you may do so by editing `"dataPath": "./packs/data"`. Please be aware you will need to create the folder yourself! - -## 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 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. - -```{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 - -When Regolith runs, it will move the `data` folder into the `tmp` directory, along with the `RP` and `BP` folders. You can access the files here directly, just as you do the pack files. - -For example: - -```python -with open('./data/bump_manifest/version.json', 'r') as f: - print(json.load(f)) -``` - -## Saving Data - -To save data, you will need to add `"exportData": true,` to your `filter.json` definition. This is opt-in, to avoid slow copying of large data folders. - -When regolith is finished running, data folders marked with `exportData` 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. - -For example if your filter is called `hello_world`, with `exportData` set to true, then you would be expected to store data into `data/hello_world/*`. - -```{warning} -This stands in contrast to the `RP` and `BP` folders, which will not be saved back into the project! -``` - -For example: - -filter.json -```json -{ - "description": "An example of using export data", - "exportData": true, - "filters": [ - { - "runWith": "python", - "script": "./main.py", - "name": "bump_manifest" - } - ] -} -``` - -filter -```python -with open('./data/bump_manifest/version.json', 'w') as f: - json.dump({'version': '1.0'}, f) -``` diff --git a/docs/advanced/export-targets.md b/docs/advanced/export-targets.md deleted file mode 100644 index cd82d9e..0000000 --- a/docs/advanced/export-targets.md +++ /dev/null @@ -1,131 +0,0 @@ -(export-targets)= -# Export Targets - -Export Targets determine where your generated files will go, after Regolith is finished compiling. You can set this target at the top level of Regolith, but it can be overridden inside individual profiles, if needed. - -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. - -## 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! - -## Additional Configuration for Non-Windows Users - -Some of the export targets listed below wouldn't make sense on systems other than Windows with Minecraft installed. They often rely on finding the `com.mojang` path first, and then placing the files in a path relative to that. This problem can be solved by setting environment variables that Regolith will use instead of the `com.mojang` path. - -- `COM_MOJANG_PREVIEW` - A fake path to the `com.mojang` folder in Minecraft preview releases. This is used by the `preview` export target. -- `COM_MOJANG` - A fake path to the `com.mojang` folder in regular Minecraft releases. - -## Available Export Targets - -These are the export targets that Regolith offers. - -### Development - -The development export target will place the compiled packs into your `com.mojang` `development_*_packs` folders of the specified Minecraft build (standard, preview or education endition). - -```json -"export": { - "target": "development", - "build": "standard" // or "preview" or "education" -} -``` - -Optionally, you can use `rpName` and `bpName` to specify the names of the folders that will be created in the `development_*_packs` folders. You can read more about these options at the end of this page of the documentation. - -```json -"export": { - "target": "development", - "build": "standard", - "rpName": "'my_rp'", - "bpName": "'my_bp'" -} -``` - -### Local - -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": { - "target": "local" -} -``` - -Local export optionally accepts `rpName` and `bpName` to specify the names of the folders that will be created in the `build` folders. You can read more about these options at the end of this page of the documentation. - -```json -"export": { - "target": "local", - "rpName": "'my_rp'", - "bpName": "'my_bp'" -} -``` - - - -### Exact - -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 options. Both paths support environment variables by using the `%VARIABLE_NAME%` syntax. - -Example: - -```json -"export": { - "target": "exact", - "rpPath": "...", - "bpPath": "..." -} -``` - -The exact export target doesn't support using `rpName` and `bpName`. The `rpPath` and `bpPath` should provide full paths to the desired locations. - -### World - -The World export target will place the compiled files into a specific world. This is useful for teams that prefer working in-world, as opposed to in the development pack folders. - -You need to use *either* `worldName` or `worldPath` to select the world. `worldPath` supports environment variables by using the `%VARIABLE_NAME%` syntax. If you use `worldName`, you have to specify the Minecraft build you're using - `standard`, `preview` or `education`. - -Example: - -```json -"export": { - "target": "world", - "build": "standard", - "worldName": "..." // This - // "worldPath": "..." // OR this -} -``` - -Optionally, you can use `rpName` and `bpName` to specify the names of the folders that will be created in the world. You can read more about these options at the end of this page of the documentation. - -```json -"export": { - "target": "world", - "worldPath": "...", - "rpName": "'my_rp'", - "bpName": "'my_bp'" -} -``` - -## The `rpName` and `bpName` expressions - -The `rpName` and `bpName` are expressions evaulated using the [go-simple-eval](https://github.com/stirante/go-simple-eval/) library. They let you specify the names of the folders of the exported packs in some of the export targets. - -The go-simple-eval library allows you to use simple expressions to generate the names of the folders. The expressions can use the following variables: - -- `project.name` - The name of the project. -- `project.author` - The author of the project. -- `os` - The host operating system. -- `arch` - The host architecture. -- `debug` - whether regolith is running in debug mode or not. -- `version` - The version of regolith. -- `profile` - The name of the profile being run. - -Go-simple-eval can concatenate strings using the `+` operator. The strings must be enclosed in single quotes. diff --git a/docs/advanced/profiles.md b/docs/advanced/profiles.md deleted file mode 100644 index 54fc120..0000000 --- a/docs/advanced/profiles.md +++ /dev/null @@ -1,68 +0,0 @@ -# Profiles - -A `profile` is a collection of filters, settings, and export information. By default, a Regolith project will be initialized with a single profile, called `default`. You can add additional profiles, as you need them. - -## Running Profiles - -You can use `regolith run` to run the default profile (default), or use `regolith run ` to run a specific profile - -## Why Profiles? - -Profiles are useful for creating different run-targets. - -For example, `default` profile may contain development focused filters, which are not desired for a final build. You can create a `build` or `package` profile, potentially with a different export target to fill this need. - -You can now run `regolith run default` 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 - "default": { - "filters": [ - {"filter": "example_filter"} - ], - "export": { - "target": "development", - "build": "standard" - } - }, - - // A second profile, with different filters - "build": { - "filters": [ - {"filter": "different_filter"} - ], - "export": { - "target": "development", - "build": "standard" - } - } - }, - "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. - -For example, `dataPath` can be defined at the top level, but customized per-profile if desired, by placing the key again inside of the profile: This path will be used when running this filter. - -```{note} -You can learn more about the configuration options available in Regolith {ref}`here`. -``` diff --git a/docs/advanced/user-configuration.md b/docs/advanced/user-configuration.md deleted file mode 100644 index ab1a192..0000000 --- a/docs/advanced/user-configuration.md +++ /dev/null @@ -1,80 +0,0 @@ -# User Configuration - -User configuration file is stored in the Regolith app data folder. On Windows, it's -`%localappdata%\regolith\user_config.json`**\***. The file is used to store the user -preferences for Regolith. - -## Available Options - -### `use_project_app_data_storage: bool` - -Default: `false` - -If set to `true`, the Regolith projects will store their cache (filters, their dependencies, etc.) in the app data folder, instead of the `.regolith` folder in the project folder. - -### `username: string` - -Default: `"Your name"` - -The username of the user, which will be used in the `author` field of the `manifest.json` file when creating a new project. - -### `resolvers: list[string]` - -Default: `["github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json"]` - -A list of resolvers, which will be used to resolve filter names to URLs for downloding when using the `regolith install` command. The default URL is always added to the end of the list. Note that the "URLs" used by the resolvers are not actual URLs. They have two parts, separated by `/`. The first part is an url to a repository on GitHub, and the second part is a path to the resolver file relative to the root of the repository. For example, the default resolver is on the `github.com/Bedrock-OSS/regolith-filter-resolver` repository, in the `resolver.json` file, but `github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json` is not a valid URL. - -### `resolver_cache_update_cooldown: string` - -Default: `"5m"` - -The cooldown between cache updates for the resolvers. The cooldown is specified in the [Go duration format](https://pkg.go.dev/time#ParseDuration). - -### `filter_cache_update_cooldown: string` - -Default: `"5m"` - -The cooldown between cache updates for the filters. The cooldown is specified in the [Go duration format](https://pkg.go.dev/time#ParseDuration). - -## The `regolith config` command - -The `regolith config` command is used to manage the user configuration of Regolith. It can access and modify -the user configuration file. The data is stored in the application data folder in the -"user_config.json" file. - -The behavior of the command changes based on the used flags and the number of provided arguments. -The cheetsheet below shows the possible combinations of flags and arguments and what they do: - -- `regolith config` - printing all properties -- `regolith config ` - printing specified property -- `regolith config ` - setting property value -- `regolith config --delete` - deleting a property -- `regolith config --append` - appending to a list proeprty -- `regolith config --index ` - replacing item in a list property -- `regolith config --index --delete` - deleting item in a list property - -The commands that print text can take the `--full` flag to print configuration with the default values -included (if they're not defined in the config file). Without the flag, the undefined properties -will be printed as null or empty list. - -## The structure of the user configuration file - -The `user_config.json` file is just a regular JSON file without any nesting. You can edit it manually -if you want to but you don't have to because everything can be done with the `regolith config` command. - -## Example config file -```json -{ - "use_project_app_data_storage": false, - "username": "Bedrock-OSS", - "resolvers": [ - "github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json" - ] -} -``` - ----- - -```{note} -On other platforms you can refer to Go's [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir) documentation. It's in "regolith" subdirectory of the path returned by this function. -``` diff --git a/docs/filters/create-a-filter.md b/docs/developing-filters/create-a-filter.md similarity index 100% rename from docs/filters/create-a-filter.md rename to docs/developing-filters/create-a-filter.md diff --git a/docs/developing-filters/custom-filter-resolvers.md b/docs/developing-filters/custom-filter-resolvers.md new file mode 100644 index 0000000..020e2d3 --- /dev/null +++ b/docs/developing-filters/custom-filter-resolvers.md @@ -0,0 +1,8 @@ +(custom-filter-resolvers)= +# Custom Filter Resolvers + +```{warning} +This page describes the use of the filter resolvers from the filter developer's perspective. If you are looking for a basic explanation of what filter resolvers are, and how to use them, see the {ref}`Filter Resolvers` section. +``` + +TODO \ No newline at end of file diff --git a/docs/filters/custom-filters.md b/docs/developing-filters/custom-filters.md similarity index 100% rename from docs/filters/custom-filters.md rename to docs/developing-filters/custom-filters.md diff --git a/docs/developing-filters/default-filter-data.md b/docs/developing-filters/default-filter-data.md new file mode 100644 index 0000000..defa088 --- /dev/null +++ b/docs/developing-filters/default-filter-data.md @@ -0,0 +1,3 @@ +# Default Filter Data + +TODO diff --git a/docs/filters/local-filters.md b/docs/developing-filters/local-filters.md similarity index 95% rename from docs/filters/local-filters.md rename to docs/developing-filters/local-filters.md index c2ece89..ca22c4e 100644 --- a/docs/filters/local-filters.md +++ b/docs/developing-filters/local-filters.md @@ -1,3 +1,4 @@ +(local-filters)= # 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: diff --git a/docs/filters/online-filters.md b/docs/developing-filters/online-filters.md similarity index 98% rename from docs/filters/online-filters.md rename to docs/developing-filters/online-filters.md index a24b92f..297b1b5 100644 --- a/docs/filters/online-filters.md +++ b/docs/developing-filters/online-filters.md @@ -33,7 +33,7 @@ You should move your programs and scripts into this folder. When your filter is ] } ``` - +(filter-property-export-data)= #### The `exportData` property This option lets you create remote filters that can modify their data folder. The older versions of diff --git a/docs/developing-filters/publishing-filters.md b/docs/developing-filters/publishing-filters.md new file mode 100644 index 0000000..51d9c06 --- /dev/null +++ b/docs/developing-filters/publishing-filters.md @@ -0,0 +1,3 @@ +# Publishing Filters + +TODO \ No newline at end of file diff --git a/docs/developing-filters/testing-filters.md b/docs/developing-filters/testing-filters.md new file mode 100644 index 0000000..dc592d7 --- /dev/null +++ b/docs/developing-filters/testing-filters.md @@ -0,0 +1,3 @@ +# Testing Filters + +TODO diff --git a/docs/filter-types/node-filters.md b/docs/filter-types/node-filters.md deleted file mode 100644 index d9767a3..0000000 --- a/docs/filter-types/node-filters.md +++ /dev/null @@ -1,29 +0,0 @@ -(node-filters)= -# NodeJS Filters - -As an asynchronous event-driven JavaScript runtime, Node.js is designed to build scalable network applications. - -## Installing NodeJS - -Before you can run Node filters, you will need to [install NodeJS](https://nodejs.org/en/download/). - -## Running NodeJS code as Filter - -The syntax for running a nodejs filter is this: - -```json -{ - "runWith": "nodejs", - "script": "./filters/example.js", - - // Optional property that defines the path to the folder with the package.json file - "requirements": "./filters" -} -``` - -## Requirements and Dependencies - -When installing, regolith will check for a `package.json` file. If requirements property is specified -reqolith will look in that folder, otherwise it will look in the folder with the script. - -When developing a Node filter with dependencies, you must create this file. You can create a `package.json` file yourself by using `npm init`. diff --git a/docs/filter-types/deno-filters.md b/docs/filters/deno-filters.md similarity index 100% rename from docs/filter-types/deno-filters.md rename to docs/filters/deno-filters.md diff --git a/docs/filter-types/dotnet-filters.md b/docs/filters/dotnet-filters.md similarity index 100% rename from docs/filter-types/dotnet-filters.md rename to docs/filters/dotnet-filters.md diff --git a/docs/filter-types/executable-filters.md b/docs/filters/executable-filters.md similarity index 96% rename from docs/filter-types/executable-filters.md rename to docs/filters/executable-filters.md index e0ee690..53d4246 100644 --- a/docs/filter-types/executable-filters.md +++ b/docs/filters/executable-filters.md @@ -36,4 +36,4 @@ platform: ``` You can learn more about the `when` property on in the documentation of the "config.json" file -{ref}`here`. +{ref}`here`. diff --git a/docs/filters/filters.md b/docs/filters/filter-introduction.md similarity index 81% rename from docs/filters/filters.md rename to docs/filters/filter-introduction.md index 5f451ab..9a1dee5 100644 --- a/docs/filters/filters.md +++ b/docs/filters/filter-introduction.md @@ -1,9 +1,10 @@ +(filters-introduction)= # Filters Introduction 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 {ref}`standard library`. You may also be interested in {ref}`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 +- Linting and error checking +- Code generation/automation +- Interpreting custom syntax diff --git a/docs/filters/filter-run-modes.md b/docs/filters/filter-run-modes.md deleted file mode 100644 index 00c6071..0000000 --- a/docs/filters/filter-run-modes.md +++ /dev/null @@ -1,53 +0,0 @@ -(filter-run-modes)= -# Filter Run Modes - -There are 3 ways of running Regolith: -- `regolith run` -- `regolith watch` -- `regolith apply-filter` - -## Run and Watch Commands - -Regolith `run` and `watch` are very similar to each other. They run a profile. The difference is -that the `watch` command will watch for changes in the RP, BP and {ref}`data` folders -and rerun the profile when they change. The `run` command will run the profile only once. - -The syntax for run and watch command is: - -``` -regolith run [profile-name] -``` - -``` -regolith watch [profile-name] -``` - -Where `[profile-name]` is the name of the profile defined your "config.json" file you want to run. -The `[profile-name]` is optional. If you don't specify it, the `"default"` profile will be run. - -A single run performs the following steps: -1. Copy your source files into a temporary folder. -2. Runs all of the filters of the profile. -3. Moves the files to the target location defined in the "export" property of the profile. - -Filters work on the copies of RP, BP, and data. Thanks to the use of copies, RP -and BP cannot be modified by the filters. The data folder can be modified -because after a successful run Regolith moves the files of the copy to the -the original data folder (this is useful for the filters so that they can store -some data between runs). - -## Apply-Filter Command - Running Regolith Destructively - -Running Regolith with `regolith run` or `regolith watch` is a safe operation because the filters can -only modify the data folder but not RP and BP. Sometimes you want to modify the RP and BP directly -in a destructive way. This is where the apply-filter command come in handy. You can apply any filter -by running the `regolith apply-filter` command. Unlike the `regolith run` command, the `regolith apply-filter` -command runs only one filter instead of running entire profile. - -The command is used like this: - -``` -regolith apply-filter [args...] -``` - -The `filter-name` is the name of one of the filters installed in your project. The `args` is a list of arguments passed to the filter. diff --git a/docs/filters/installing-filters.md b/docs/filters/installing-filters.md deleted file mode 100644 index 5251167..0000000 --- a/docs/filters/installing-filters.md +++ /dev/null @@ -1,131 +0,0 @@ -(installing-filters)= -# Installing and Updating Filters - -To start using a filter, you need to do four 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. - 4. Run your profile, to test it out! - -## Filter Dependencies - -Filters are written in [programming languages](https://www.wikiwand.com/en/Programming_language). These languages may not be installed on your computer by default. Before installing a filter, you should ensure you have the proper programming language installed. The "Filter Types" documentation has detailed installation instructions for every regolith-supported language! - -For example, if the filter relies on Python, you can find installation instructions {ref}`here`. - -## 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 `filter_identifier` will depend on where the filter is hosted. Filters listed on the [Bedrock-OSS/regolith-filter-resolver](https://github.com/Bedrock-OSS/regolith-filter-resolver/blob/main/resolver.json) repository can be installed by their name. For example, to install the `name_ninja` filter, you would run the: - -``` -regolith install name_ninja -``` -If the filter is not listed on the resolver repository, you will need to use the following format: -`github.com///`. - -For example, to install `name_ninja` using the full format, you would run: - -``` -regolith install github.com/Bedrock-OSS/regolith-filters/name_ninja -``` -The longer form can be used to install filters from private repositories. - - -```{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 -"default": { - "export": { - "readOnly": false, - "target": "development", - "build": "standard" - }, - "filters": [ - { - "filter": "FILTER_NAME", - } - ] -} -``` - -## Install All - -Regolith is intended to be used with git version control, and by default the `.regolith` folder is ignored. That means that when you collaborate on a project, or simply re-clone your existing projects, you will need an easy way to download all the filters again! - -You may use the command `regolith install-all`, which will check `config.json`, and install every filter in the `filterDefinitions`. - -```{warning} -This is only intended to be used with existing projects. To install new filters, use `regolith install`. -``` - -## Filter Versioning - -Filters in Regolith are optionally versioned with a [semantic version](https://semver.org/). As filters get updated, new versions will be released, and you can optionally update. - -```{warning} -If you don't specify a version, the `install` command will pick a sensible default. First, it will search for the latest release. If that doesn't exist (such as a filter that has no versions), it will select the latest commit in the repository. In both cases, the installed version will be `pinned`. -``` - -### Installing a Specific Version - -When installing, you can optionally include a version key after two equals signs (`==`): - - - ⭐ Version: `regolith install name_ninja==1.2.8` - - Unpinned Head: `regolith install name_ninja==HEAD` - - Unpinned Latest: `regolith install name_ninja==latest` - - SHA: `regolith install name_ninja==adf506df267d10189b6edcdfeec6c560247b823f` - -### Pinned Versions - -In your `config.json`, every filter will include a `version` field, which specifies which version of the filter to use. By default, this version will be `pinned`, meaning that it won't be updated, even if new versions release. This provides you safety, and ensures that your projects will continue to operate without interruption even if filters release breaking changes. - -Optionally, you may mark filters as `unpinned`, which signifies that your project wants the latest version of the filter, no questions asked. There are two available `unpinned` versions: - - `latest` points to the latest released version tag. - - `HEAD` points to the latest commit of the repository, regardless of release tags. - -### Updating your Filters - -If you want to update the version of the filter used in your project, you can use the `regolith install` command again. By default, the `install` command is not allowed to update existing filters, but you can use the `--update` or `--force` flag to change this behavior. The flag must be used after the `install` arguments. - -``` -regolith install name_ninja --update -``` - -Alternatively, you can modify the `version` field in `config.json` and run `regolith install-all`. Regolith install-all is useful for working in a team, when other team members may have to update or add filters to the project. - -If you want to update all filters in your project, you can use the `--update` flag with the `install-all` command. - -``` -regolith install-all --update -``` - -### Updating resolvers - -When using short names for filters, Regolith uses a resolver file from a remote repository to determine the URL of the filter. -By default, this remote repository is cached and only updated after 5 minutes since last update. If you want to update the resolver file immediately, you can use the `regolith update-resolver` command. - -Alternatively, you can use the `--force-resolver-update` flag to force the resolvers to update when installing a filter. - -``` -regolith install name_ninja --force-resolver-update -``` - -### Updating filter cache - -Regolith caches the filter repository when you install online filters. To avoid unnecessary frequent updates, Regolith skips them for installations that occur less than 5 minutes after the last update. -However, if you need to update the cache immediately, you can use the `--force-filter-update` flag while installing a filter. - -```bash -regolith install name_ninja --force-filter-update -# OR -regolith install-all --force-filter-update -``` \ No newline at end of file diff --git a/docs/filter-types/java-filters.md b/docs/filters/java-filters.md similarity index 100% rename from docs/filter-types/java-filters.md rename to docs/filters/java-filters.md diff --git a/docs/filter-types/nim-filters.md b/docs/filters/nim-filters.md similarity index 100% rename from docs/filter-types/nim-filters.md rename to docs/filters/nim-filters.md diff --git a/docs/filters/node-filters.md b/docs/filters/node-filters.md new file mode 100644 index 0000000..a0b26af --- /dev/null +++ b/docs/filters/node-filters.md @@ -0,0 +1,37 @@ +(node-filters)= +# NodeJS Filters + +NodeJS is a JavaScript runtime. It is also the most popular option for writing Regolith filters. If you're making Minecraft packs, there's a good chance you're already familiar with JavaScript, and have NodeJS installed. + +You can download NodeJS here: [https://nodejs.org/en/download/package-manager](https://nodejs.org/en/download/package-manager) + +```{note} +The [Gametests](https://github.com/Bedrock-OSS/regolith-filters/tree/master/gametests) filter is a very notable filter that for many users could be the main selling point of Regolith. Gametests is a filter that lets you use TypeScript. It compiles the script in the pack using ESBuild. + +The unusual name of the filter is a relic of its time of creation. The filter was created before current Scripting API was released. At that time, Minecraft only had the "gametest" API designed for writing tests of the packs. The filter was named after this API. +``` + +## Installing NodeJS + +Before you can run Node filters, you will need to [install NodeJS](https://nodejs.org/en/download/). + +## Running NodeJS code as Filter + +The syntax for running a nodejs filter is this: + +```json +{ + "runWith": "nodejs", + "script": "./filters/example.js", + + // Optional property that defines the path to the folder with the package.json file + "requirements": "./filters" +} +``` + +## Requirements and Dependencies + +When installing, regolith will check for a `package.json` file. If requirements property is specified +reqolith will look in that folder, otherwise it will look in the folder with the script. + +When developing a Node filter with dependencies, you must create this file. You can create a `package.json` file yourself by using `npm init`. diff --git a/docs/filter-types/profile-filters.md b/docs/filters/profile-filters.md similarity index 100% rename from docs/filter-types/profile-filters.md rename to docs/filters/profile-filters.md diff --git a/docs/filter-types/python-filters.md b/docs/filters/python-filters.md similarity index 85% rename from docs/filter-types/python-filters.md rename to docs/filters/python-filters.md index cada46d..1c28a2d 100644 --- a/docs/filter-types/python-filters.md +++ b/docs/filters/python-filters.md @@ -3,23 +3,24 @@ Python is an interpreted high-level general-purpose programming language. +(installing-python)= ## Installing Python -Before you can run Python filters, you will need to [install python](https://www.python.org/downloads/). +Before you can run Python filters, you will need to [install Python](https://www.python.org/downloads/). -Please ensure that you add python to your path: +Please ensure that you add Python to your path: ![](./python-filters/python-path.png) We recommend that you download more or less recent versions of Python. ```{warning} -It's generally not acceptable to install python via the Microsoft Store. Python installed from here is not available on the path. If you have trouble running Python filters with Regolith, please reinstall using the link above. +It's generally not acceptable to install Python via the Microsoft Store. Python installed from here is not available on the path. If you have trouble running Python filters with Regolith, please reinstall using the link above. ``` ## Running Python code as Filter -The syntax for running a python script is this: +The syntax for running a Python script is this: ```json { @@ -44,7 +45,7 @@ When developing a Python filter with dependencies, you must create this file. Yo [Python Venvs](https://docs.python.org/3/library/venv.html) are flexible, lightweight "virtual environments". -Regolith uses venvs to install dependencies, since it will prevent your global installation space from becoming polluted. When you install a python filter with dependencies, they will be installed into a venv, stored in `.regolith/cache/venvs/`. +Regolith uses venvs to install dependencies, since it will prevent your global installation space from becoming polluted. When you install a Python filter with dependencies, they will be installed into a venv, stored in `.regolith/cache/venvs/`. By default, all filters will share a single venv. diff --git a/docs/filter-types/python-filters/python-path.png b/docs/filters/python-filters/python-path.png similarity index 100% rename from docs/filter-types/python-filters/python-path.png rename to docs/filters/python-filters/python-path.png diff --git a/docs/filter-types/shell-filters.md b/docs/filters/shell-filters.md similarity index 100% rename from docs/filter-types/shell-filters.md rename to docs/filters/shell-filters.md diff --git a/docs/index.md b/docs/index.md index bc42de9..acce702 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,51 +2,70 @@ :hidden: :caption: Introduction -What Is Regolith? -Installing +Introduction +Installation +Additional Dependencies Getting Started Troubleshooting +Safety ``` ```{toctree} :hidden: -:caption: Advanced - -Configuration File -User Configuration -Data Folder -Export Targets -Profiles -Experiments -Safety +:caption: Project Configuration + +Project Config File +Format Versions +Profiles +Export Targets +Go-Simple-Eval +``` + +```{toctree} +:hidden: +:caption: Using Regolith + +Help & Autocompletion +Installing Filters +Filter Versioning +Updating Filters +Filter Resolvers +Running Filters +Regolith Cache +User Configuration +Experiments +Data Folder + ``` ```{toctree} :hidden: :caption: Filters -Introduction -Local Filters -Custom Filters -Online Filters -Installing Filters -Filter Run Modes -Create a Filter +Filter Introduction +Java Filters +.NET Filters +Nim Filters +Python Filters +Shell Filters +NodeJS Filters +Deno Filters +Profile Filters +Executable Filters ``` ```{toctree} :hidden: -:caption: Filter Types - -Java Filters -.NET Filters -Nim Filters -Python Filters -Shell Filters -NodeJS Filters -Deno Filters -Profile Filters -Executable Filters +:caption: Developing Filters + +Local Filters +Online Filters +Publishing Filters +Custom Filter Resolvers +Custom Filters +Create a Filter +Testing Filters +Default Filter Data ``` ```{toctree} diff --git a/docs/introduction/additional-dependencies.md b/docs/introduction/additional-dependencies.md new file mode 100644 index 0000000..ce9d44e --- /dev/null +++ b/docs/introduction/additional-dependencies.md @@ -0,0 +1,25 @@ +(additional-dependencies)= +# Additional Dependencies + +Regolith can be used as a stand-alone tool for generating Minecraft packs with your local filters. However, you can get the most out of Regolith created by its community and published on the internet. To use these filters, you will need to install additional dependencies. The dependencies you need depend on your workflow. This secotion provides some recommendations/requirements for using Regolith with filters from the internet. + +(git-dependency)= +## Git +Git is the most popular version control system in the world. It is also the most important dependency of Regolith. Without Git, you won't be able to install filters from the interent in your projects. Regolith uses Git to download filters from online repositories like GitHub. + +You can download Git from its website: [https://git-scm.com/download/](https://git-scm.com/download/) + +## Filter Runners + +Regolith supports filters written in various programming languages. To run these filters, you will need to install the appropriate runtime. You can find the installation instruction for each runtime in pages dedicated to different filter types: + - {ref}`Python` + - {ref}`NodeJS` + - {ref}`Deno` + - {ref}`Java` + - {ref}`Nim` + - {ref}`.NET` + +The runtimes are optional, unless you want to use filters written in the corresponding language. Some of the filter types don't require any runtime: + +- {ref}`Shell Filters` run shell commands directly. +- {ref}`Executable Filters` use compiled executables. diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md index d254f7d..776c4f3 100644 --- a/docs/introduction/getting-started.md +++ b/docs/introduction/getting-started.md @@ -1,112 +1,110 @@ # Getting Started -```{note} -To get started with Regolith, you should first read our {ref}`introduction` page, and the {ref}`installation` page. -``` - -You can test for installation by running `regolith` inside of a terminal. This guide will assume you have installed regolith directly, but you can follow along with a stand-alone build. Just ensure that the executable is placed inside of your project folder. - -If you run into issues installing, you can check our {ref}`troubleshooting guide` for tips. - ```{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 [here](https://tutorial.djangogirls.org/en/intro_to_command_line/). ``` +This tutorial will guide you through basic usage of Regolith. It assumes that you've already installed Regolith. If you haven't, please refer to the {ref}`installation` page. + +At the end of the tutorial, it is shown how to add filter from the internet into your project and run it. Installing filters requires Git, and the filter used as an example runs in Python. If you want to follow allong, you will need get these dependencies. To learn more about getting Git please refer to the {ref}`Additional Dependencies` section. To get the instructions for installing Python, please refer to the {ref}`Python Filters` section. + ## Creating a new Project -To create a new project, navigate to a blank folder, and run `regolith init`. This will create a few files: +To create a new project, navigate to a blank folder, and run the following command: +```text +regolith init +``` -![](./getting-started/project-folder.png) +This will create a few files: + +```text +📂 example-project + 📂 .regolith + 📂 packs + 📂 BP + 📂 data + 📂 RP + 📄 .gitignore + 📄 config.json +``` In short: - - `.regolith` is a special folder that regolith uses to store data. You don't need to look here. + - `.regolith` is a special folder that Regolith uses to store data. You don't need to look here. - `packs/BP` stores your behavior pack. - `packs/RP` stores your resource pack. - `packs/data` is a special folder that filters can use to store data. - `config.json` is the configuration file for Regolith. - - `.gitignore` is a file which tells [Git source control](https://git-scm.com/) - to ignore certain files. It's not a partof of Regolith but we highly - recommend using Git to manage your projects. + - `.gitignore` is a file which tells {ref}`Git source control` to ignore certain files. It's not a part of of Regolith but we highly recommend using Git to manage your projects. -## Config file +## Basic Project Configuration Next, open up `config.json`. We will be configuring a few fields here, for your addon. ```json { - "name": "Project name", // Enter your pack name here. (Example: spooky_gravestones) - "author": "Your name", // Enter your author name here. (example: SirLich) + "author": "Your name", // Enter your pack name here. (Example: spooky_gravestones) + "name": "Project name", // Enter your author name here. (example: Bedrock-OSS) "packs": { "behaviorPack": "./packs/BP", "resourcePack": "./packs/RP" }, "regolith": { + "dataPath": "./packs/data", + "filterDefinitions": {}, + "formatVersion": "1.4.0", "profiles": { "default": { - "filters": [], "export": { - "target": "development", "build": "standard", - "readOnly": false - } + "readOnly": false, + "target": "development" + }, + "filters": [] } - }, - "filterDefinitions": {}, - "dataPath": "./packs/data" + } } } ``` -Later on you can play with the additional configuration options, but for now, just set a project name, and author name. +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 {ref}`"development" export target` by default use the project name as a prefix. ```{note} -We suggest using a name like `dragons` or `cars` for the project name, as opposed to `My Dragon Adventure Map`, since the project name will be used as the folder name for the final export if you're -using the {ref}`"development" export target`. +You can read more about the `config.json` file in the {ref}`Configuration File` section. ``` -## Creating your Addon +## Adding Pack Files -At this point, you will want to add some files into your regolith project. If you have an existing project, you can copy/paste the files into the `RP` (resource pack) and `BP` (behavior pack) folders. +At this point, you will want to add some files into your Regolith project. If you have an existing project, you can copy/paste the files into the `RP` (resource pack) and `BP` (behavior pack) folders. -If you don't have an addon prepared, you may also create a fresh one directly in your project folder, following the normal rules. Add a `manifest.json`, a `pack_icon.png`, and any other files you want. The files should go directly into the `RP` and `BP` folders, like this: +If you don't have an addon prepared, you may use files from the [example project prepared for this tutorial](https://github.com/Bedrock-OSS/regolith-docs-tutorial-resources/releases/tag/1.4.1-getting-started). You can copy the into the content of `RP.zip` and `BP.zip` into the `RP` and `BP` folders respectively or you can get the full (final) version of the project from the `getting-started-full-project.zip` file. -![](./getting-started/project-folder-2.png) +```{note} +Regolith supports creating purely resource-pack- or behavior-pack-oriented projects. If your project doesn't have a resource pack or behavior pack, you can simply remove the appropriate field from the `config.json` file, and remove the `RP` or `BP` folder. +``` ## Running Regolith -There are two ways of running Regolith profiles `regolith run` and `regolith watch`. -They both run a profile defined in `config.json` file. - -The `regolith run [profile-name]` command runs provided profile once. If you don't -specify a profile, it will run the profile named "default". - -The `regolith watch [profile-name]` command works the same as `regolith run`, but -it will watch your source files and rerun the profile when they change. If you're -using `regolith run` you have to do it manually every time. - -By default the export is set to "development", which means that the files will -be copied to the `development_behavior_packs` and `development_resource_packs` -folders of `com.mojang`. The names of folders created in this export mode are -based on the name of the project like `project_name_bp` and `project_name_rp`. +You can run regolith using the following command: +``` +regolith run +``` +It runs the default {ref}`profile`. If unmodified, the `default` profile is set to export files into the `development` target. This means it copies the packs into the `development_behavior_packs` and `development_resource_packs` inside the [com.mojang folder](https://wiki.bedrock.dev/guide/project-setup.html#the-com-mojang-folder). ## Adding your first Filter -Regolith contains a very powerful filter system, that allows you to write filters in many languages, as well as running existing filters from the internet. For now, we will simply use the {ref}`standard library`, which is a set of approved filters that we maintain. - -As an example, we will use the `texture_list` filter, which automatically creates the `texture_list.json` file for you. To learn more about this file, and why automating it is helpful, read [here](https://wiki.bedrock.dev/concepts/texture-list.html). +Regolith contains a very powerful filter system, that allows you to write filters in many languages, as well as running existing filters from the internet. For now, we will simply use the {ref}`standard library`, which is a set of filters maintained by creators of Regolith - Bedrock-OSS. -### Installing +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](https://wiki.bedrock.dev/concepts/textures-list.html). -```{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 `default` profile. - -You should adjust the default profile in `config.json` to look like this: +You can install this filter by running the following command: +```text +regolith install texture_list --profile=default +``` +This command adds the filter to your project, and appends it to the "default" profile. +Alternatively, you can just run `regolith install texture_list`, and manually add the filter to the profile in the `config.json` file. The "default" profile in the config file should look like this: ```json "default": { "export": { @@ -121,25 +119,8 @@ You should adjust the default profile in `config.json` to look like this: ] } ``` - -### Running - -Now, you can re-run `regolith run`. - -Check `com.mojang`, and open the new `texture_list.json` file in `RP/textures/texture_list.json`. Every time you run regolith, this file will be re-created, based on your current textures. No need to manually edit it ever again! - -```{warning} -If your resource pack already contains `texture_list.json`, you should delete it. You don't need to manually worry about it anymore - Regolith will handle it! -``` +Now, you can re-run `regolith run`. This time, Regolith will not only copy your packs into the development folders in `com.mojang` folder, but also create the `textures_list.json` file for you in your resource pack. Every time you run Regolith, this file will be re-created, based on your current textures. No need to manually edit it ever again! ```{warning} If your project doesn't have any textures, than `texture_list.json` will simply create a blank file `[]`. Consider adding some textures to see the filter at work! ``` - -## Whats Next - -Now that you've created your first Regolith project, and installed your first filters, you are well on your way to being a Regolith expert! You should check out the {ref}`standard library`, to see if additional filters might be useful for you. - -Otherwise, you can learn about writing {ref}`custom filters` or -dive deeper into Regolith commands by reading about {ref}`Filter Run Modes` -and {ref}`Installing and Updating Filters`. diff --git a/docs/introduction/getting-started/project-folder-2.png b/docs/introduction/getting-started/project-folder-2.png deleted file mode 100644 index 0f3707f..0000000 Binary files a/docs/introduction/getting-started/project-folder-2.png and /dev/null differ diff --git a/docs/introduction/getting-started/project-folder.png b/docs/introduction/getting-started/project-folder.png deleted file mode 100644 index e9036f4..0000000 Binary files a/docs/introduction/getting-started/project-folder.png and /dev/null differ diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md new file mode 100644 index 0000000..92b75d6 --- /dev/null +++ b/docs/introduction/installation.md @@ -0,0 +1,64 @@ +(installation)= +# Installation +You can install Regolith using various methods, depending on your operating system. This section provides instructions for installing Regolith on Linux, Mac, and Windows systems. + +## Winget (Windows) +To install Regolith using winget, open a command prompt or terminal window and enter the following command: +``` +winget install Bedrock-OSS.regolith +``` +This will search the winget repository for the "Bedrock-OSS.regolith" package and install it on your system. If the installation is successful, you should see a message indicating that the package has been installed. + +To update Regolith in the future, simply run the following command: +``` +winget upgrade Bedrock-OSS.regolith +``` +This will check for any available updates to the Regolith package and install them on your system. + +```{warning} +Not every Windows computer has winget installed. If this is the case for your computer, you can install Regolith using the MSI file available on GitHub (see next section for instructions). +``` + +## MSI File (Windows) + +You can install Regolith using the MSI file available on the release page on GitHub: [https://github.com/Bedrock-OSS/regolith/releases/latest](https://github.com/Bedrock-OSS/regolith/releases/latest) + + +![](./installation/msi-download.png) + +The MSI file name follows the pattern `regolith-x.x.x.msi`, where `x.x.x` is the version number. Simply download the MSI file from the link above and run it to begin the installation process. Follow the prompts to complete the installation. + +![](./installation/regolith-msi.png) + +## Updating (Windows) + +To update Regolith after installation, you can use the "regolith-update.ps1" PowerShell script that is included with the installation. To run the script, follow these steps: + +1. Open a PowerShell window. +2. Run the following command: + +``` +regolith-update.ps1 +``` + +This will check for any available updates to Regolith and install them on your system. + +## Stand-alone Executable File (Linux, Mac, and Windows) + +Regolith can also be installed stand-alone. Simply download the correct zip for your operating system from the release page on GitHub: [https://github.com/Bedrock-OSS/regolith/releases/latest](https://github.com/Bedrock-OSS/regolith/releases/latest) + +For Windows, this is most likely `regolith_x.x.x_Windows_x86_64.zip`. + +![](./installation/exe-download.png) + +Unzip this package, and place the Regolith executable file somewhere convenient. In stand-alone mode, you will need a add the executable to your PATH environment variable or copy it into every project. + +## Checking Installation + +After installing, Regolith can be used in command-prompt by typing `regolith`. You should see something like this: + +![](./installation/regolith-help.png) + +```{note} +If you don't see this try restarting your terminal. If you encounter any issues, please refer to the {ref}`troubleshooting guide` for tips. +``` \ No newline at end of file diff --git a/docs/introduction/installing/exe-download.png b/docs/introduction/installation/exe-download.png similarity index 100% rename from docs/introduction/installing/exe-download.png rename to docs/introduction/installation/exe-download.png diff --git a/docs/introduction/installing/msi-download.png b/docs/introduction/installation/msi-download.png similarity index 100% rename from docs/introduction/installing/msi-download.png rename to docs/introduction/installation/msi-download.png diff --git a/docs/introduction/installation/regolith-help.png b/docs/introduction/installation/regolith-help.png new file mode 100644 index 0000000..9bdbce9 Binary files /dev/null and b/docs/introduction/installation/regolith-help.png differ diff --git a/docs/introduction/installing/regolith-msi.png b/docs/introduction/installation/regolith-msi.png similarity index 100% rename from docs/introduction/installing/regolith-msi.png rename to docs/introduction/installation/regolith-msi.png diff --git a/docs/introduction/installing.md b/docs/introduction/installing.md deleted file mode 100644 index 3e5b07f..0000000 --- a/docs/introduction/installing.md +++ /dev/null @@ -1,68 +0,0 @@ -(installing)= -# Installing - -## Windows Installation Using `winget` - -```{note} -Not every Windows computer has winget installed. If this is the case for your computer, you can install Regolith using the MSI file available on GitHub (see next section for instructions). -``` - -To install the application "Regolith" using winget, follow these steps: - -1. Open a command prompt or terminal window and enter the following command: - -``` -winget install Bedrock-OSS.regolith -``` -This will search the winget repository for the package "Bedrock-OSS.regolith" and install it on your system. - -2. If the installation is successful, you should see a message indicating that the package has been installed. - -To update Regolith in the future, simply run the following command: - -``` -winget upgrade Bedrock-OSS.regolith -``` - -This will check for any available updates to the Regolith package and install them on your system. - -## Windows Installation Using an `.msi` File - -### Installation - -Alternatively, you can install Regolith using the MSI file available on GitHub at the following link: https://github.com/Bedrock-OSS/regolith/releases/latest. The file will be named using the pattern `regolith-x.x.x.msi`, where `x.x.x` is the version number. To install Regolith using the MSI file, follow these steps: - -Download the MSI file from the link above. - -![](./installing/msi-download.png) - -Run the MSI file to begin the installation process. Follow the prompts to complete the installation. - -![](./installing/regolith-msi.png) - -#### Updates - -To update Regolith after installation, you can use the "regolith-update.ps1" PowerShell script that is included with the installation. To run the script, follow these steps: - -1. Open a PowerShell window. -2. Run the following command: - -``` -regolith-update.ps1 -``` - -This will check for any available updates to Regolith and install them on your system. - -## Linux, Mac, and Windows (stand-alone) - -Regolith can also be installed stand-alone. Simply install the correct zip for your operating system. For Windows, this is most likely `regolith_x.x.x_Windows_x86_64.zip`. - -![](./installing/exe-download.png) - -You may unzip this package, and place the `regolith.exe` file somewhere convenient. In stand-alone mode, you will need a copy of the regolith executable in every project that you intend to use Regolith with. Or, you can add the executable to your PATH environment variable. - -## Checking Installation - -After installing, Regolith can be used in any command-prompt by typing `regolith`. You should see something like this: - -![](./installing/regolith-help.png) \ No newline at end of file diff --git a/docs/introduction/installing/regolith-help.png b/docs/introduction/installing/regolith-help.png deleted file mode 100644 index d261744..0000000 Binary files a/docs/introduction/installing/regolith-help.png and /dev/null differ diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md new file mode 100644 index 0000000..4a8a499 --- /dev/null +++ b/docs/introduction/introduction.md @@ -0,0 +1,76 @@ +(introduction)= +# Introduction + +## What is Regolith? + +Regolith is a pack compiler for the Bedrock Edition of Minecraft. + +Regolith introduces the concept of a **project folder**, that includes the resource pack, behavior pack, and data folder that can be used for additional configuration. This structure is great for version control, and allows you to keep your "source-of-truth" outside of Minecraft's `com.mojang` folder. + +Here is what a newly initialized Regolith project looks like: + +```text +📂 example-project + 📂 .regolith + 📂 packs + 📂 BP + 📂 data + 📂 RP + 📄 .gitignore + 📄 config.json +``` + +### Compilation Flow + +In the simplest case, Regolith can be used to move your packs from the project folder, into your target location (usually the development folders in `com.mojang`). Each time you run regolith, the packs will be moved over, and updated. + +However, Regolith's real value preposition is the ability to run {ref}`arbitrary code during this copy`. + +We refer to these scripts and programs as {ref}`filters`. Here is the flow: +1. `RP`, `BP` and `data` folder are copied into a temporary location. +2. Every filter is executed in-order, editing temporary files in-place. +3. The contents of `RP` and `BP` are moved into your export location +4. If configured, some of the subfolders within `data` can be moved back into your project. + +This compilation flow allows you to make programmatic changes to your compiled addon, without effecting your source files. Since the data folder can be saved back to your project, it's possible to persistantly store the results of running filters there. + +## Why Regolith? + +### Extending the Packs Syntax + +Regolith allows you to create and extend packs syntax. For example, the [subfunctions](https://github.com/Nusiq/regolith-filters/tree/master/subfunctions) filter allows you to define functions within functions, without creating an additional file: + +``` +# Some code +function : + # The code of the subfunction + execute @a ~ ~ ~ function : + # The code of the nested subfunction +# Some other code +``` + +Regolith's capablities go beyond chaning the individual files. You can change entire structure of the project and use files that otherwise would not be supported by Minecraft (for example, custom image formats). + +As long as you can write a filter to interpret the new structure, and compile it into valid pack, then anything goes! + +### Non-Destructive Editing + +Imagine you have a script that loops over every entity, and creates some language-code translation for it. + +Lets say your entity `regolith:big_zombie` becomes named `Big Zombie`. + +If you run this script, and copy the files into your `en_US.lang`, you've saved yourself a lot of time, but you've also introduced a problem: You've *destructively edited your pack*. What this means, is that you have mixed up your tool-generated content, with your hand-written content. + +Imagine you add more entities, and run your script again: Now you are in the painful position of "merging" the new tool generated content, with your resource pack's `en_US.lang` file, which you may have edited in the interim. + +This is called *destructive editing*, and Regolith fixes it! + +A comparable Regolith filter would not suffer from this problem, because you never directly edit tool generated content. Your Regolith project folder contains only human written content, and your `com.mojang` folder contains only tool-generated content. + +This means as you add new entities, the names will be handled for you, without you ever seeing the names in `en_US.lang`, or needing to re-run the script! + +In other words, Regolith adds compiled content on top of your hand written content, leaving you free to create your content, without working around tool-generated content. + +```{note} +If this sounds interesting to you, you might be interested in the [name ninja filter](https://github.com/Bedrock-OSS/regolith-filters/tree/master/name_ninja). +``` diff --git a/docs/advanced/safety.md b/docs/introduction/safety.md similarity index 100% rename from docs/advanced/safety.md rename to docs/introduction/safety.md diff --git a/docs/introduction/troubleshooting.md b/docs/introduction/troubleshooting.md index 3f89b6e..ccb9812 100644 --- a/docs/introduction/troubleshooting.md +++ b/docs/introduction/troubleshooting.md @@ -40,8 +40,10 @@ The most common reason Regolith will crash is from a broken filter. The first st Filter errors will be printed like `[error][filter] ... `. -### Python Not Found +### Dependency Not Found -If you get a message like `[+]: Python not found, download and install it from https://www.python.org/downloads/`, this means that Python either not installed, or is not available on the path. +If you you get an error like `[+] ... not found, download and install it from ...`, this means that Regolith is unable to find a dependency required for the filter to run. In this case, follow the link provided, and install the dependency. -We provide {ref}`installation instructions`, to help you get Python installed correctly on your system. Please be aware that Python installed via the Microsoft Store will not work with Regolith, as it generally doesn't add itself to path. +Example errors: +- Python `[+]: Python not found, download and install it from https://www.python.org/downloads/` +- NodeJS `[+]: NodeJS not found, download and install it from https://nodejs.org/en/` diff --git a/docs/introduction/what-is-regolith.md b/docs/introduction/what-is-regolith.md deleted file mode 100644 index e57e223..0000000 --- a/docs/introduction/what-is-regolith.md +++ /dev/null @@ -1,83 +0,0 @@ -(what-is-regolith)= -# What is Regolith? - -Regolith is an Addon Compiler for the Bedrock Edition of Minecraft. - -```{warning} -This page introduces Regolith at a conceptual level. If you prefer, you can jump to the {ref}`installation instructions`. -``` - -Regolith introduces the concept of a "project folder", where your addons are written, including the Resource Pack, Behavior Pack, and any models, textures or configuration files. This single-folder-structure is great for version control, and allows you to keep your "source-of-truth" outside of com.mojang! - -Here is what a newly initialized Regolith project looks like: - -![](./what-is-regolith/project-folder.png) - -## Compiling - -In the simplest case, Regolith can be used to move your packs from the project folder, into your target location (usually the development folders in `com.mojang`). Each time you run regolith, the packs will be moved over, and updated. - -However, Regoliths real value preposition is the ability to run *arbitrary code during this copy*. - -We refer to these scripts and programs as `filters`. Here is the flow: -- `RP`, `BP` and `data` folder are copied into a `tmp` folder -- Every filter is executed in-order, editing the `tmp` folder in-place -- The contents of `RP` and `BP` are moved into your export location -- If configured, subfolders within `data` can be moved back into your data location - -This compilation flow allows you to make programmatic changes to your compiled addon, without effecting your source files. - -Since the data folder can be saved back to your project, it's possible to store persistant data there. - -## Filters - -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 {ref}`standard library`. - -For example, one of our standard filters is called `texture_convert`, which *filters* image formats for photo editing programs, and converts them into `.png` files. - -With this filter turned on, you can place Photoshop, Krita, or Gimp files directly into `RP/textures/*` folder! By the time your files reach `com.mojang`, the `.psd` files will be replaced by a normal `.png` -Minecraft won't know the difference! - -### Creating your own Filters - -You can write filters in Python, JavaScript, Java, or any other language, using our shell integration. You can learn more about creating custom filters {ref}`here`. - -## Why Regolith? - -### Extending the Addon Syntax - -Regolith allows you to create and extend addon-syntax. As long as you can write a filter to interpret the new syntax, and compile it into valid addon-syntax, then anything goes! - -For example, the [subfunctions](https://github.com/Nusiq/regolith-filters/tree/master/subfunctions) community filter allows you to define functions within functions, without creating an additional file: - -``` -# Some code -function : - # The code of the subfunction - execute @a ~ ~ ~ function : - # The code of the nested subfunction -# Some other code -``` - -With Regolith, you are empowered to write addons with an extended syntax - and Bedrock won't even know the difference! - -### Non-Destructive Editing - -Imagine you have a script that loops over every entity, and creates some language-code translation for it. - -Lets say your entity `regolith:big_zombie` becomes named `Big Zombie`. - -If you run this script, and copy the files into your `en_US.lang`, you've saved yourself a lot of time, but you've also introduced a problem: You've *destructively edited your addon*. What this means, is that you have mixed up your tool-generated content, with your hand-written content. - -Imagine you add more entities, and run your script again: Now you are in the painful position of "merging" the new tool generated content, with your addons `en_US.lang` file, which you may have edited in the interim. - -This is called *destructive editing*, and Regolith fixes it! - -A comparable Regolith filter would not suffer from this problem, because you never directly edit tool generated content. Your Regolith project folder contains only human written content, and your `com.mojang` folder contains only tool-generated content. - -This means as you add new entities, the names will be handled for you, without you ever seeing the names in `en_US.lang`, or needing to re-run the script! - -In other words, Regolith adds compiled content on top of your hand written content, leaving you free to create your content, without working around tool-generated content. - -```{note} -If this sounds interesting to you, you might be interested in the [name ninja filter](https://github.com/Bedrock-OSS/regolith-filters/tree/master/name_ninja). -``` diff --git a/docs/introduction/what-is-regolith/project-folder.png b/docs/introduction/what-is-regolith/project-folder.png deleted file mode 100644 index e9036f4..0000000 Binary files a/docs/introduction/what-is-regolith/project-folder.png and /dev/null differ diff --git a/docs/libraries/standard-library.md b/docs/libraries/standard-library.md index 1d071b1..dcf772f 100644 --- a/docs/libraries/standard-library.md +++ b/docs/libraries/standard-library.md @@ -17,7 +17,7 @@ The Standard Library is a special set of filters, written by the Regolith mainta | [texture_convert](https://github.com/Bedrock-OSS/regolith-filters/tree/master/texture_convert) | Converts popular image editor file formats, such as .psd to .png. | | [texture_list](https://github.com/Bedrock-OSS/regolith-filters/tree/master/texture_list) | Automatically creates the `texture_list.json` file, based on the images you've added into your resource pack. | -The full, up to date list of filters can be found on our github. We are looking into maintaining a list here, but for now please visit our GitHub. +The full, up to date list of filters can be found on our GitHub. We are looking into maintaining a list here, but for now please visit our GitHub. ## Using a Standard Filter diff --git a/docs/project-configuration/export-targets.md b/docs/project-configuration/export-targets.md new file mode 100644 index 0000000..ceffa17 --- /dev/null +++ b/docs/project-configuration/export-targets.md @@ -0,0 +1,113 @@ +(export-targets)= +# Export Targets + +Export Targets are defined in {ref}`profileds` and determine where your generated files will go, after Regolith is finished compiling. + +All of the export settings require using the `target` property. Some of the export targets require additional properties. Sections below lists all of the available export targets. + +## Export Target Types +### Development Export Target + +The development export target will place the compiled packs into your `com.mojang` `development_*_packs` folders of the specified Minecraft build - Bedrock Edition, Education Edition or Preview. + +```json +"export": { + "target": "development", + "build": "standard", + "rpName": "'my_rp'", + "bpName": "'my_bp'" +} +``` + +Properties: +- `build` - The Minecraft Edition to export to. Can be `standard`, `preview` or `education`. You can fake the `com.mojang` path using {ref}`export target environment variables`. +- `rpName` (optional) - The {ref}`go-simple-eval` expression used to generate the name of the resource pack folder. If not specified, defaults to `"project.name+'_rp'"`. +- `bpName` (optional) - The {ref}`go-simple-eval` expression used to generate the name of the behavior pack folder. If not specified, defaults to `"project.name+'_bp'"`. + - `readOnly` (optional) - If set to `true`, the exported files will be read-only. The default value is `false`. + +### Local Export Target + +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": { + "target": "local", + "rpName": "'my_rp'", + "bpName": "'my_bp'" +} +``` + +Properties: +- `rpName` (optional) - The {ref}`go-simple-eval` expression used to generate the name of the resource pack folder. If not specified, defaults to `"project.name+'_rp'"`. +- `bpName` (optional) - The {ref}`go-simple-eval` expression used to generate the name of the behavior pack folder. If not specified, defaults to `"project.name+'_bp'"`. +- `readOnly` (optional) - If set to `true`, the exported files will be read-only. The default value is `false`. + +### None Export Target +The `none` export target runs Regolith without exporting the files anywhere. This is useful when you have a filter that exports the files in some other custom way. + +```json +"export": { + "target": "none" +} +``` +The `none` doesn't have any additional properties. + + +### Exact Export Target + +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. + +```json +"export": { + "target": "exact", + "rpPath": "...", + "bpPath": "..." +} +``` + +Properties: +- `rpPath` - The path to the resource pack folder. The path can be relative or absolute and supports environment variables by using the `%VARIABLE_NAME%` syntax. +- `bpPath` - The path to the behavior pack folder. The path can be relative or absolute and supports environment variables by using the `%VARIABLE_NAME%` syntax. +- `readOnly` (optional) - If set to `true`, the exported files will be read-only. The default value is `false`. + +### World Export Target + +The World export target will place the compiled files into a specific world. This is useful for teams that prefer working in-world, as opposed to in the development pack folders. + +```json +"export": { + "target": "world", + "build": "standard", + "worldName": "...", // This + // "worldPath": "...", // OR this + "rpName": "'my_rp'", + "bpName": "'my_bp'" +} +``` +There are two ways of using the `"world"` export target, by specifying the `worldName` or `worldPath` property. + +Properties when using the world name: +- `build` - The Minecraft Edition to export to. Can be `standard`, `preview` or `education`. You can fake the `com.mojang` path using {ref}`export target environment variables`. +- `worldName` - The name of the world to export to. Regolith uses the *levelname.txt* file stored in the world files to determine the name of the world. + +Properties when using the world path: +- `worldPath` - The complete path to the world to export to. The path can be relative or absolute and supports environment variables by using the `%VARIABLE_NAME%` syntax. + +Shared properties: +- `rpName` - The {ref}`go-simple-eval` expression used to generate the name of the resource pack folder. If not specified, defaults to `"project.name+'_rp'"`. +- `bpName` - The {ref}`go-simple-eval` expression used to generate the name of the behavior pack folder. If not specified, defaults to `"project.name+'_bp'"`. +- `readOnly` (optional) - If set to `true`, the exported files will be read-only. The default value is `false`. + + +(export-target-environment-variables)= +## Export Target Environment Variables + +```{warning} +These environment variables are only available for non-Windows users. +``` + +Some of the export targets listed above wouldn't make sense on systems other than Windows with Minecraft installed. They often rely on finding the `com.mojang` path first, and then placing the files in a path relative to that. This problem can be solved by setting environment variables that Regolith will use instead of the `com.mojang` path. + +- `COM_MOJANG` - A fake path to the `com.mojang` folder in regular Minecraft releases. This is used by the `development` build. +- `COM_MOJANG_PREVIEW` - A fake path to the `com.mojang` folder in Minecraft preview releases. This is used by the `preview` build. +- `COM_MOJANG_EDU` - A fake path to the `com.mojang` folder in Minecraft Education Edition releases. This is used by the `education` build. diff --git a/docs/project-configuration/format-versions.md b/docs/project-configuration/format-versions.md new file mode 100644 index 0000000..12eb579 --- /dev/null +++ b/docs/project-configuration/format-versions.md @@ -0,0 +1,10 @@ +(format-versions)= +# Format Versions +This page lists changes in different format versions of the Regolith {ref}`config.json` file. + +- `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`. 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). + +```{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`. +``` \ No newline at end of file diff --git a/docs/project-configuration/go-simple-eval.md b/docs/project-configuration/go-simple-eval.md new file mode 100644 index 0000000..406382e --- /dev/null +++ b/docs/project-configuration/go-simple-eval.md @@ -0,0 +1,42 @@ +(go-simple-eval)= +# Go-Simple-Eval + +Regolith uses the [go-simple-eval library](https://github.com/stirante/go-simple-eval/) to evaluate some expressions in the project configuration file: +- The `when` expression in the {ref}`filter settings` object. +- The `rpName` and `bpName` in some of the {ref}`export targets`. + +## Syntax + +Go-simple-eval uses a simple syntax that supports basic operations you would expect from a programming language. + +```{warning} +This is not a full documentation of go-simple-eval, but the features explained here should be enough for using it in Regolith. +``` + +### Operators +- Comparison operators: `==`, `!=`, `<`, `<=`, `>`, `>=` +- Logical operators: `&&`, `||`, `!` +- Math operators: `+`, `-`, `*`, `/` +- String concatenation: `+` + +### Parentheses +You can use parentheses to group expressions like this: `(1 + 2) * 3`. + +### Strings +Strings must be enclosed in single quotes like this: `'This is a string'`. + +### Reserved Words +- `true` and `false` are reserved words for boolean values. +- `null` is a reserved word for null values. + +## Variables + +Regolith provides some variables that you can use in the expressions: + +- `project.name` - The name of the project. +- `project.author` - The author of the project. +- `os` - The host operating system. The value is retrieved from `runtime.GOOS`, which means that based on the host system, the value can be `linux`, `windows`, `darwin`, etc. +- `arch` - The host architecture. The value is retrieved from `runtime.GOARCH`, which means that based on the host system, the value can be `amd64`, `arm64`, etc. +- `debug` - whether regolith is running in debug mode or not (using the `--debug` flag). +- `version` - The version of regolith. +- `profile` - The name of the profile being run. diff --git a/docs/project-configuration/profiles.md b/docs/project-configuration/profiles.md new file mode 100644 index 0000000..94c1425 --- /dev/null +++ b/docs/project-configuration/profiles.md @@ -0,0 +1,66 @@ +(profiles)= +# Profiles + +A `profile` is a collection of filters, and export information. By default, a Regolith project is initialized with a single profile, called `default`. + +You can add additional profiles, as you need them. For example, `default` profile may build a base version of the project, similar to the one you would use to release the project. You can create a `dev` profile that {ref}`runs the default profile` and adds development focused content on top of that or a `build` profile that additionally creates a compressed version of the project for distribution. You can also use different profiles to export to different locations, like for example Minecraft Education Edition and Minecraft Bedrock Edition. + +You can run specific profiles using the `regolith run ` command. + +## Config Structure + +A profile is a JSON object, that you define in the `config.json` file inside the `profiles` object. The code snippet below shows their structure, you can view the structure of an example `config.json` file {ref}`here`. + +```json +"profiles": { + "default": { + "export": { + "target": "development", + "build": "standard", + "readOnly": false + }, + "filters": [ + { + "filter": "name_ninja", + "settings": { + "language": "en_GB.lang" + } + }, + { + "filter": "bump_manifest", + "arguments": ["-regolith"], + "disabled": true, + "when": "os == 'windows' && arch == 'amd64'" + } + ] + }, + "otherProfile": { + // ... + } +} +``` + +The code above defines two profiles, `default` and `otherProfile`. The `default` profile contains two filters, `name_ninja` and `bump_manifest` and the content of the `otherProfile` is omitted for brevity. A profile must contain two fields - `filters` and `export`. + +### Export Properties +Export field defines where the files will be exported. It's relatively complex, so it has its own page {ref}`here`. + +(project-config-filters-properties)= +### Filters Properties + +The filters field is an array of objects with references to the project's filters specified in {ref}`filterDefinitions`. They may also contain additional properties defining how to run the filter and under what conditions. + +#### filter +Filter is a required filed that references the filter to run. The filter must be defined in the `filterDefinitions` object in the project's `config.json` file. + +#### arguments +Arguments is an optional field that specify the command-line arguments to pass to the filter when it runs. It's an array of strings that are passed as arguments to the filter. Different filters may use this field differently, so you should refer to the filter's documentation for more information. + +#### settings +Settings, like arguments, is an optional field that affects the command-line arguments. When it's present, its content is passed to the filter as a JSON string as the first argument. Different filters may use this field differently, so you should refer to the filter's documentation for more information. + +#### disabled +The optional `disabled` field is added for convenience. You can set it to `true` to disable a filter without removing it from the profile. This can be useful when you want to temporarily disable a filter without losing the configuration. + +#### when +The optional `when` field is a boolean expression that disables the filter when it's false. The most common use case is to run a filter only on a specific operating system or architecture. You can read more about the syntax and available variables on it's own page {ref}`here`. diff --git a/docs/project-configuration/project-config-file.md b/docs/project-configuration/project-config-file.md new file mode 100644 index 0000000..7c5957a --- /dev/null +++ b/docs/project-configuration/project-config-file.md @@ -0,0 +1,101 @@ +(project-config-file)= +# Project Config File + +The configuration of Regolith project 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 projects, such as ["bridge."](https://editor.bridge-core.app/). + +## Regolith Configuration + +Regolith builds on this standard with the addition of the `regolith` namespace, which is where all regolith-specific information is stored. + +Example configuration file: +```json +{ + "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 + } + } + } + } +} +``` + +### 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` for more information. +- `author`- The author of the project. +- `packs`- The location of the behavior and resource packs. + +### 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. You can read more about it on the {ref}`format versions page`. + +(project-config-data-path)= +#### 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. + +(filter-definitions)= +#### filterDefinitions +Filter definitions field 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`. + +The syntax of the `filterDefinitions` field is as follows: +```json +"filterDefinitions": { + "name_ninja": { + "url": "github.com/Bedrock-OSS/regolith-filters", + "version": "1.2.4" + }, + "local_filter": { + "runWith": "python", + "script": "filters/local_filter/main.py" + }, +} +``` +In this example `name_ninja` is a filter downloaded from the internet with {ref}`pinned version` 1.2.4, and the `local_filter` is a Python filter that is stored locally. + + +#### 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`. diff --git a/docs/using-regolith/data-folder.md b/docs/using-regolith/data-folder.md new file mode 100644 index 0000000..b1a3c80 --- /dev/null +++ b/docs/using-regolith/data-folder.md @@ -0,0 +1,16 @@ +(data-folder)= +# Data Folder + +The `data` folder in a Regolith project is a special folder designed to store the files of the filters that don't belong to `BP` or `RP` folders. By default it is located in `./packs/data`, but you can change it by using the {ref}`dataPath` setting in the project configuration file. + + +## Filter Data + +The data folder typically contains subfolders that correspond to the filters installed in the project, but if you need, nothing stops you from adding files directly to its root or creating subfolders for other purposes. + +Using the same names of the folders that match the names of the filters isn't just a convention. It has some practical implications: + +1. Some filters provide default data files that will be copied into the data folder when you {ref}`install` them for the first time. +2. Some filters {ref}`may register their data folder as editable`. This means that all changes applied to their data folder during {ref}`running filters` will be saved in the project. + +As a user, you don't have to worry about these details too much. The install command will never overwrite filter's data if you already have it, and the majority of the filters doesn't register their data as editable; if they do it is most likely mentioned their documentation. diff --git a/docs/advanced/experiments.md b/docs/using-regolith/experiments.md similarity index 94% rename from docs/advanced/experiments.md rename to docs/using-regolith/experiments.md index 932c411..885238d 100644 --- a/docs/advanced/experiments.md +++ b/docs/using-regolith/experiments.md @@ -2,9 +2,7 @@ Experiments are new experimental features of Regolith to be released in the future versions, once proven to be stable and useful. The experiments can be enabled with the `--experiments` flag. -## Currently Available Experiments - -### `size_time_check` +## size_time_check The `size_time_check` is an experiment that aims to speed up `regolith run` and `regolith watch` commands. It achieves this by checking the size and modification time of the files before moving them between working and output directories. If the source file is the same size and has the same modification time as the destination file, the target file will remain untouched (Regolith assumes that the files are the same). diff --git a/docs/using-regolith/filter-resolvers.md b/docs/using-regolith/filter-resolvers.md new file mode 100644 index 0000000..b003b38 --- /dev/null +++ b/docs/using-regolith/filter-resolvers.md @@ -0,0 +1,51 @@ +(filter-resolvers)= +# Filter Resolvers + +```{warning} +This section only describes the resolvers from the user's perspective. If you are a filter developer and you want to know the details of creating your own resolver repository, see the {ref}`Custom Filter Resolvers` section. +``` + +Filter resolvers are files hosted on the internet that Regolith can use to resolve the short names of the filters to their full URLs when running the `regolith install` command. + +Thanks to this feature, you can run: +```text +regolith install name_ninja +``` +And you don't have to remember the full URL of the filter and write commands like: +```text +regolith install github.com/Bedrock-OSS/regolith-filters/name_ninja +``` + +## Default Resolver +By default, Regolith uses the default resolver hosted at [Bedrock-OSS/regolith-filter-resolver](https://github.com/Bedrock-OSS/regolith-filter-resolver) repository in the `resolver.json` file. + +Currently, there is no way to remove the default resolver from Regolith, but you can add your own resolvers which will take precedence over the default resolver (see the next section). + +## Adding Resolvers to Your User Configuration +The list of resolvers used by Regolith is stored in the {ref}`user configuration` file. You can edit it manually or use the `regolith config`. + +To add a resolver to the list, use `regolith config resolvers --append`, where the `` is the URL to the resolver repository, with the path to the resolver file relative to the root of the repository separated by a `/`. + +For example: +```text +regolith config resolvers github.com/Example/example-repository/path/to/resolver.json --append +``` +This command would append the `path/to/resolver.json` file from the `github.com/Example/example-repository` repository to the list of resolvers. + +```{warning} +The "URLs" in the resolvers list are not actual URLs, but Regolith can uderstand that which part of the path is the repository URL and which part is the path to the resolver file. +``` +You can also edit the {ref}`user configuration` file manually. + +## Removing Resolvers +To remove a resolver from the list, use the `--delete` flag combined with the `--index` flag to specify the index of the resolver you want to remove. + +For example: +```text +regolith config resolvers --delete --index=0 +``` +This command would remove the first resolver from the list (indexing starts from 0). + +If you don't specify the `--index` flag, all of the resolvers will be reomved. + +If you don't know what resolvers are in the list you can always print them with the `regolith config resolvers` command. diff --git a/docs/using-regolith/filter-versioning.md b/docs/using-regolith/filter-versioning.md new file mode 100644 index 0000000..0cb3104 --- /dev/null +++ b/docs/using-regolith/filter-versioning.md @@ -0,0 +1,24 @@ +(filter-versioning)= +# Filter Versioning + +Regolith filters are versioned either with versions assigned by its creator using [semantic version](https://semver.org/), or simply by SHA values of the commits on their GitHub repository. When you install a filter, by default Regolith saves the version it installed in the {ref}`config file`. + +## Version Pinning + +When installing, you can optionally include a version key after two equals signs (`==`). The value provided after the equal signs, decides whether the version of the installed filter will be pined or not. + +Version pinning makes sure that the filter is installed with the same version for everyone who runs the project, when they run `regolith install-all`. + +For pinned versions you can use semver or SHA of the commit in the git respository: + +- Specific version: `regolith install name_ninja==1.2.8` +- SHA: `regolith install name_ninja==adf506df267d10189b6edcdfeec6c560247b823f` + +If you don't want to pin the version, you have two options. + +- Unpinned Head: `regolith install name_ninja==HEAD` - This makes the install-all command always download the newest commit in the repository. +- Unpinned Latest: `regolith install name_ninja==latest` - This makes the install-all command always download the newest release of the filter. + +If you don't specify a version, the `install` command will pick a sensible default. First, it will search for the latest release, if that doesn't exist (in filters without releases), it will select the latest commit in the repository. In both cases, the installed version will be **pinned**. + +In your `config.json`, every {ref}`filter definition` will include a `version` field, which specifies which version of the filter to use. The version field can contain a semver version, a commit SHA, or the strings `HEAD` or `latest`, matching the version you specified when installing the filter. diff --git a/docs/using-regolith/help-and-autocompletion.md b/docs/using-regolith/help-and-autocompletion.md new file mode 100644 index 0000000..b30428d --- /dev/null +++ b/docs/using-regolith/help-and-autocompletion.md @@ -0,0 +1,41 @@ +# Help & Autocompletion + +## Help Command + +Regolith has a build in help command to explore its features. You can use it to get the list of the commands with their explanation. To get help simply run the following command: + +```text +regolith help +``` + +If you want to learn about specific subcommand for example `regolith run`, run `regolith help ` like this: + +```text +regolith help run +``` + +This way you can read about the command and get a full list of its flags, with their explanation. + +## Autocompletion + +Regolith CLI is implemented with [Cobra](https://github.com/spf13/cobra) which provides an autocompletion feature. Cobra supports generating autocompletion scripts for Bash, Zsh, Fish, and PowerShell. To generate the autocompletion script for your shell you need to run `regolith completion `. + +For example, to generate the autocompletion script for PowerShell run: + +```powershell +regolith completion powershell +``` +This command will generate the autocompletion script for PowerShell and print it to the console. + +In PowerShell, you can instantly run the script by running: + +```powershell +regolith completion powershell | Out-String | Invoke-Expression +``` +This will work until the end of the session. If you want to make it permanent, you can add the content of the script to your PowerShell profile. In PowerShell, the profile path is stored in the `$PROFILE` variable. + +If you're using other shells, the process is similar, just replace `powershell` with your shell name and put the generated script in the appropriate place for your shell. + +```{note} +Currently, the autocompletion feature in Regolith is very basic; it only provides the autocompletion for the subcommands. It doesn't provide autocompletion for the flags and arguments. +``` diff --git a/docs/using-regolith/installing-filters.md b/docs/using-regolith/installing-filters.md new file mode 100644 index 0000000..99bab33 --- /dev/null +++ b/docs/using-regolith/installing-filters.md @@ -0,0 +1,94 @@ +(installing-filters)= +# Installing Filters + +To start using a filter, you need to do four 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. + 4. Run your profile, to test it out! + +## Filter Dependencies + +Filters are written in [programming languages](https://www.wikiwand.com/en/Programming_language). These languages may not be installed on your computer by default. Before installing a filter, you should ensure you have the proper programming language installed. The "Filter Types" documentation has detailed installation instructions for every regolith-supported language! + +For example, if the filter relies on Python, you can find installation instructions {ref}`here`. + +## Installing a Filter + +```{warning} +The `install` command relies on `git`. You can read more about Git {ref}`here`. +``` + +Regolith contains a powerful installation command, downloads a filter from GitHub, and installs any required libraries for you. In general, the format is like this: `regolith install `. + +The value of `filter_identifier` will depend on the URL where the filter is hosted. Filters listed on the {ref}`resolvers` in your {ref}`user configuration` can be installed directly, just with their name. By default Regolith uses the resolver hosted on [Bedrock-OSS/regolith-filter-resolver](https://github.com/Bedrock-OSS/regolith-filter-resolver/blob/main/resolver.json) repository. + + +For example, to install the `name_ninja` filter (which is one of the filters created by Bedrock-OSS), you would run: +```text +regolith install name_ninja +``` + +If the filter is not listed on the resolver repository, you need to use the following format: +`github.com///`. + +For example, to install `name_ninja` using the full format, you would run: +```text +regolith install github.com/Bedrock-OSS/regolith-filters/name_ninja +``` + +The install command accepts multiple arguments, so you can install quickly install multiple fliters by running `regolith install ...`, for example: +```text +regolith install name_ninja texture_list +``` + +The `install` command also supports installing specific versions of the filters. You can read more about in the {ref}`Filter Versioning` page. By default Regolith installs the most recent release of the filter. + +## Adding Filter to Profile + +After installing, the filter will appear inside `filterDefinitions` of `config.json`. You can now add this filter to a profile like this: + +```json +"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 {ref}`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: +```text +regolith install name_ninja --profile=default +``` +This command would append the filter to the filters list of the default profile. + +## Install All + +Regolith is intended to be used with git version control, and by default the {ref}`.regolith` folder is ignored. That means that when you collaborate on a project, or simply re-clone your existing projects, you will need an easy way to download all the filters again! + +You may use the command `regolith install-all`, which will check `config.json`, and install every filter in the `filterDefinitions`. + + +## Cached Results of Regolith Install + +When you install multiple filters in a quick succession, it doesn't make much sense to update the filter and resolver respositories {ref}`cached on your computer`. The install command checks the time of the last cache update and skips its update, when it's recent enough. + +In some situations, you may want to skip the waiting time and force the cache update. The install command, has two flags that you can use to force the cache update during the installation: + +- `--force-filter-refresh` - forces the update of the {ref}`filter cache`, even if the filter repository was downloaded recently. +- `--force-resolver-refresh` - forces the update of the {ref}`resolver cache` even if the resolver repository was downloaded recently. This flag is not available for the install-all command, because install-all doesn't use the resolvers, it relies on the URLs provided directly in the {ref}`config.json` file. + +You can change the default cooldown times for downloading in your {ref}`user configuration`. + +If you want to update the filter resolvers, without installing any filters, you can use the following command: +```text +regolith update-resolvers +``` \ No newline at end of file diff --git a/docs/using-regolith/regolith-cache.md b/docs/using-regolith/regolith-cache.md new file mode 100644 index 0000000..75e457e --- /dev/null +++ b/docs/using-regolith/regolith-cache.md @@ -0,0 +1,52 @@ +(regolith-cache)= +# Regolith Cache + +Regolith uses a folder in the user's application data directory to store various caches and the user configuration file. On Windows, you can find this folder at `%localappdata%/regolith`. On other systems, please refer to the Golang documentation of the [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir) function (the path is the `regolith` subfolder of the result of this function). In later part of this documentation page we will refer to this folder using the Windows path (`%localappdata%/regolith`). + +Regolith uses the following caches: +- project-cache +- filter-cache +- resolver-cache + + +(project-cache)= +# Project Cache +Project cache is a cache used to store the project's files. This is where regolith installs the project's filters and creates the temporary files when it runs. + +By default, the project cache is located directly in the project's folder in the `.regolith` folder. This folder is added to the `.gitignore` if you initialize the project with `regolith init`. + +If you use the {ref}`use_project_app_data_storage` option in the user configuration, the files will be stored in `%localappdata%/regolith/project-cache` instead. + +The project cache can be cleaned with the following command: +```text +regolith clean +``` +This works only if you are in the project's folder. It will remove both the `.regolith` folder and the corresponding cache in the `%localappdata%/regolith/project-cache` folder. + +If you want to clean all of the project caches from the `%localappdata%/regolith/project-cache` you can run: +```text +regolith clean --user-cache +``` +The unintuitive name of the flag is due to the fact that this used to be the only cache that was stored in the user's application data directory. This flag will likely change in the future. + +The paths inside the `%localappdata%/regolith/project-cache` are based on the MD5 hash of the project's path in your file system. + +(filter-cache)= +# Filter Cache +Filter cache is a cache used by Regolith to store the repositories of the previously installed filters. Thanks to this cache, Regolith can install the filtes faster, because it doesn't have to download the entire repository every time. + +The filter cache files are stored in the `%localappdata%/regolith/filter-cache` folder. The paths inside the folder are based on the MD5 hash of the repository URL. + +You can clean the filter cache with the following command: +```text +regolith clean --filter-cache +``` +Doing that is useful when you have issues with installing a filter. This can happen if the maintainer of the repository force-pushes a new version of the filter making the local cache desynchronized with the remote repository. + +(resolver-cache)= +# Resolver Cache +Resolver cache is a cache used by Regolith to store the repositories of the filter resolvers. Storing them locally allows Regolith not to download the filter resolvers every time it needs to install a filter. + +The resolver cache files are stored in `%localappdata%/regolith/resolver-cache` folder. The paths inside the folder are based on the MD5 hash of the resolver repository URL. + +There is no command-line-based way to clean the resolver cache. If you want to clean it, you need to delete the files manually. diff --git a/docs/using-regolith/running-filters.md b/docs/using-regolith/running-filters.md new file mode 100644 index 0000000..ca95f74 --- /dev/null +++ b/docs/using-regolith/running-filters.md @@ -0,0 +1,46 @@ +(running-filters)= +# Running Filters + +There are 3 ways of running Regolith: +- `regolith run` +- `regolith watch` +- `regolith apply-filter` + +## Run and Watch Commands + +Regolith `run` and `watch` are very similar to each other. They run a profile. The difference is that the `watch` command will watch for changes in the RP, BP and {ref}`data` folders and rerun the profile when they change. The `run` command will run the profile only once. + +The syntax for run and watch command is: + +```text +regolith run [profile-name] +``` + +```text +regolith watch [profile-name] +``` + +Where `[profile-name]` is the name of the profile defined your {ref}`config.json` file you want to run. The `[profile-name]` is optional. If you don't specify it, the `default` profile will be run. + +A single run performs the following steps: +1. Copy your source files into a temporary folder. +2. Run all of the filters of the profile. +3. Move the files to the target location defined in the "export" property of the profile. + +Filters work on the copies of RP, BP, and data. Thanks to the use of copies RP, BP and data are not modified making the run and watch non-destructive. + +```{warning} +Some of the filters may modify the data folder if the choose to opt-in for this feature. You can read more about this feature {ref}`here`. This feature is useful for the filters that need to store some data between runs. +``` + +## Apply-Filter Command + +Running Regolith with `regolith run` or `regolith watch` is a safe operation because they generally don't modify the files of the project. + +If you want to apply the results of running a filter permanently to you project, you can use the `regolith apply-filter` command. + +The command is used like this: +```text +regolith apply-filter [args...] +``` +The `filter-name` is the name of one of the filters installed in your project. The `args` is a list of arguments passed to the filter. diff --git a/docs/using-regolith/updating-filters.md b/docs/using-regolith/updating-filters.md new file mode 100644 index 0000000..3b1e1d6 --- /dev/null +++ b/docs/using-regolith/updating-filters.md @@ -0,0 +1,28 @@ +# Updating Filers + +By default, when you try to install a filter that is already on the {ref}`filter definitions` list, Regolith won't let you do that. If you want to reinstall or update the filter, you need to use a flag for that. + +## Updating With the "install" Command + +If you want to update the version of the filter used in your project, you can use the `regolith install` command with the `--update` flag. For example: + +```text +regolith install name_ninja --update +``` +This command updates the name_ninja to the latest version available. It's exactly the same as running `regolith install name_ninja` before the filter is insatlled for the same time. + +The `--force` and `--update` flags in the `install` are **aliases**; they do the same thing. + +## Updating With the "install-all" Command + +Alternatively, you can modify the `version` field in `config.json` and run `regolith install-all` (without any flags). + +OR, if you want to update all filters in your project to their newest available versions, you can use: +```text +regolith install-all --update +``` + +Unlinke in the `install` command, `--update` and `--force` flags in the `install-all` command are **different**. + +- The `--update` flag in `install-all` is the same as running the `install` command for each filter listed in the `filterDefinitions` with the `--update` flag (it changes the versions of the filters). +- The `--force` flag in `install-all` reinstalls all of the filters without changing their versions. diff --git a/docs/using-regolith/user-configuration.md b/docs/using-regolith/user-configuration.md new file mode 100644 index 0000000..ee01602 --- /dev/null +++ b/docs/using-regolith/user-configuration.md @@ -0,0 +1,76 @@ +(user-configuration)= +# User Configuration + +User configuration file is stored in the Regolith app data folder. On Windows, it's `%localappdata%\regolith\user_config.json`. On other systems, please refer to the Golang documentation of the [os.UserCacheDir](https://pkg.go.dev/os#UserCacheDir) function to find the path it returns that corresponds to the `%localappdata%` on Windows. + +The `user_config.json` file is used to store the user preferences for Regolith. + +## User Configuration Properties + +User configuration can be examined using the {ref}`regolith config` command or by opening the `user_config.json` file in a text editor. The `regolith config` command with `--full` flag will show all properties, including the default values (which aren't defined in the file). This section describes the properties that can be found in the user configuration file. + +(use-project-app-data-storage)= +### use_project_app_data_storage: bool + +Default: `false` + +If set to `true`, the Regolith projects will store their cache (filters, their dependencies, etc.) in the {ref}`project-cache` folder, instead of `.regolith` subfolder stored in the project files. + +### username: string + +Default: `"Your name"` + +The name of the user, which will be used in the `author` field of the {ref}`config.json` file when creating a new project. + +### resolvers: list[string] + +Default: `["github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json"]` + +A list of {ref}`resolvers`, used to resolve filter names to URLs when using the {ref}`regolith install` command. The default URL is always added at the end of the list. + +Note that the "URLs" used by the resolvers are not actual URLs. They have two parts, separated by `/`. The first part is an URL to a repository on GitHub, and the second part is a path to the resolver file relative to the root of the repository. For example, the default resolver is on the `github.com/Bedrock-OSS/regolith-filter-resolver` repository, in the `resolver.json` file, but `github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json` is not a valid URL. + +### resolver_cache_update_cooldown: string + +Default: `"5m"` + +The cooldown between cache updates for the {ref}`resolver repositories`. The cooldown is specified in the [Go duration format](https://pkg.go.dev/time#ParseDuration). If you're running `regolith install` multiple times in a short period, the resolver cache will not be updated every time, but only after the cooldown period. + +### filter_cache_update_cooldown: string + +Default: `"5m"` + +The cooldown between cache updates for the {ref}`filter repositories`. The cooldown is specified in the [Go duration format](https://pkg.go.dev/time#ParseDuration). If you're running `regolith install` multiple times in a short period, the filter cache will not be updated every time, but only after the cooldown period. + +(regolith-config-command)= +## Regolith Config Command + +The `regolith config` command is used to manage the user configuration of Regolith. It can access and modify the user configuration file. The data is stored in the application data folder in the `user_config.json` file. + +The behavior of the command changes based on the used flags and the number of provided arguments. The cheetsheet below shows the possible combinations of flags and arguments and what they do: + +- `regolith config` - Print all properties defined in the user configuration file. +- `regolith config --full` - Print all properties including the default values of the unspecified properties. +- `regolith config ` - Print specified property. +- `regolith config ` - Set property value. +- `regolith config --delete` - Delete a property. +- `regolith config --append` - append to a list proeprty. +- `regolith config --index ` - Replace item in a list property. +- `regolith config --index --delete` - Delete item in a list property. + +The commands that print text can take the `--full` flag to print configuration with the default values included (if they're not defined in the config file). Without the flag, the undefined properties will be printed as null or empty list. + +## User Configuration File + +The `user_config.json` file is just a regular JSON file without any nesting. You can edit it manually if you want to but you don't have to because everything can be done with the `regolith config` command. + +Example `user_config.json` file: +```json +{ + "use_project_app_data_storage": false, + "username": "Bedrock-OSS", + "resolvers": [ + "github.com/Bedrock-OSS/regolith-filter-resolver/resolver.json" + ] +} +```