diff --git a/docs/filters/installing-filters.md b/docs/filters/filter-installation.md similarity index 99% rename from docs/filters/installing-filters.md rename to docs/filters/filter-installation.md index 5251167..d9371bb 100644 --- a/docs/filters/installing-filters.md +++ b/docs/filters/filter-installation.md @@ -1,4 +1,4 @@ -(installing-filters)= +(filter-installation)= # Installing and Updating Filters To start using a filter, you need to do four things: diff --git a/docs/filters/filters.md b/docs/filters/filters-introduction.md similarity index 96% rename from docs/filters/filters.md rename to docs/filters/filters-introduction.md index 5f451ab..978277b 100644 --- a/docs/filters/filters.md +++ b/docs/filters/filters-introduction.md @@ -1,3 +1,4 @@ +(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` diff --git a/docs/index.md b/docs/index.md index bc42de9..3c3a902 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,8 +2,8 @@ :hidden: :caption: Introduction -What Is Regolith? -Installing +Introduction +Installation Getting Started Troubleshooting ``` @@ -25,11 +25,11 @@ Safety :hidden: :caption: Filters -Introduction +Filters Introduction Local Filters Custom Filters Online Filters -Installing Filters +Filter Installation Filter Run Modes Create a Filter ``` diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md index d254f7d..3d0f896 100644 --- a/docs/introduction/getting-started.md +++ b/docs/introduction/getting-started.md @@ -1,7 +1,7 @@ # Getting Started ```{note} -To get started with Regolith, you should first read our {ref}`introduction` page, and the {ref}`installation` page. +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. @@ -142,4 +142,4 @@ Now that you've created your first Regolith project, and installed your first fi 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`. +and {ref}`Installing and Updating Filters`. diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md new file mode 100644 index 0000000..90b569e --- /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. +``` \ 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..a16c4c1 --- /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 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 persistantly store the results of running filters there. + +## Why Regolith? + +### Extending the Addon Syntax + +Regolith allows you to create and extend addon-syntax. 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 +``` + +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/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