diff --git a/README.md b/README.md index a783f9d5..4d2c0c55 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

-⭐ Visit the Website! ⇗ ⭐ +⭐ Go to the Documentation ⇗ ⭐

- Much like `bridge. v2`, Regolith introduces the concept of a "project folder", where your addons are written, including the RP, the BP, 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`. @@ -19,30 +19,24 @@ ## 🎫 Value Preposition - Fundamentally, Regolith is nothing new. Many tools like this exist, such as the `bridge v2` plugin system, or even something like Gulp or SASS. - - The value preposition for Regolith is that it allows many tools, in many languages and pay-structures to work together in a single, unified compilation flow. - - Hobbiests can use the [Standard Library ⇗](https://github.com/Bedrock-OSS/regolith-filters), or write their own filters. Marketplace teams can write proprietary filters, or internal filters. # 💻 Regolith Development ## 🎚 Setup: - **This setup is for developers. If you're a normal user, you can find simpler instructions -[here](https://bedrock-oss.github.io/regolith/guide/installing).** +[here](https://regolith-docs.readthedocs.io/en/latest/introduction/installation/).** ### 1. Install Golang - - **[Installation and beginners guide ⇗.](https://golang.org/doc/tutorial/getting-started)** ### 2. Install Dependencies - - `go get -u ./...` to recursively install all dependencies. ### 3. Test / Run - Since Regolith is a console application which requires very specific project setup and arguments, `go run .\main.go` doesn't really do anything. @@ -59,17 +53,16 @@ of useful test commands: - `dlv test ./test -- "-test.run" TestInstallAllAndRun` - debug the "TestInstallAllAndRun" test using [delve](https://github.com/go-delve/delve) -## 🏗 Building as a `.exe`: +You can also use [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=golang.Go) to run tests. +## 🏗 Building as a `.exe`: - You can build either with *GoReleaser*, or natively -### 1. Install GoReleaser +### 1. Native +There are a few ways to build: +- `go install` (installs to gopath) +- `go build` (creates a `.exe` file) +### 2. GoReleaser - `go install github.com/goreleaser/goreleaser@latest` - -### 2. Build - -There are a few ways to build: - - `go install` (installs to gopath) - - `go build` (creates a `.exe` file) - - `./scripts/build-local.sh` (¯\_(ツ)_/¯) + - `./scripts/build-local.sh` - use this script to build the project with GoReleaser. diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts index 5005a50b..0707a943 100644 --- a/docs/docs/.vitepress/config.ts +++ b/docs/docs/.vitepress/config.ts @@ -42,173 +42,6 @@ export default defineConfig({ footer: { message: 'Released under the MIT license.', copyright: `Copyright © ${new Date().getFullYear()} Bedrock OSS.` - }, - - nav: [ - { - text: 'Guide', - link: '/guide/what-is-regolith', - activeMatch: '/guide/' - }, - { - text: 'Standard Library', - link: '/standard-library' - }, - { - text: 'Community Filters', - link: '/community-filters' - }, - { - text: 'Resources', - items: [ - { - text: 'Project Config Standard', - link: 'https://github.com/Bedrock-OSS/project-config-standard' - } - ] - }, - { - text: await getLatestVersion(), - items: [ - { - text: 'Release Notes', - link: 'https://github.com/Bedrock-OSS/regolith/releases' - } - ] - } - ], - - sidebar: { - '/guide/': [ - { - text: 'Introduction', - collapsible: true, - items: [ - { - text: 'What Is Regolith?', - link: '/guide/what-is-regolith' - }, - { - text: 'Installing', - link: '/guide/installing' - }, - { - text: 'Getting Started', - link: '/guide/getting-started' - }, - { - text: 'Troubleshooting', - link: '/guide/troubleshooting' - } - ] - }, - { - text: 'Advanced', - collapsible: true, - items: [ - { - text: 'Configuration File', - link: '/guide/configuration' - }, - { - text: 'User Configuration', - link: '/guide/user-configuration' - }, - { - text: 'Data Folder', - link: '/guide/data-folder' - }, - { - text: 'Export Targets', - link: '/guide/export-targets' - }, - { - text: 'Profiles', - link: '/guide/profiles' - }, - { - text: 'Experiments', - link: '/guide/experiments' - }, - { - text: 'Safety', - link: '/guide/safety' - } - ] - }, - { - text: 'Filters', - collapsible: true, - items: [ - { - text: 'Introduction', - link: '/guide/filters' - }, - { - text: 'Local Filters', - link: '/guide/local-filters' - }, - { - text: 'Custom Filters', - link: '/guide/custom-filters' - }, - { - text: 'Online Filters', - link: '/guide/online-filters' - }, - { - text: 'Installing Filters', - link: '/guide/installing-filters' - }, - { - text: 'Filter Run Modes', - link: '/guide/filter-run-modes' - }, - { - text: 'Create a Filter', - link: '/guide/create-a-filter' - } - ] - }, - { - text: 'Filter Types', - collapsible: true, - items: [ - { - text: 'Java Filters', - link: '/guide/java-filters' - }, - { - text: '.NET Filters', - link: '/guide/dotnet-filters' - }, - { - text: 'Nim Filters', - link: '/guide/nim-filters' - }, - { - text: 'Python Filters', - link: '/guide/python-filters' - }, - { - text: 'Shell Filters', - link: '/guide/shell-filters' - }, - { - text: 'NodeJS Filters', - link: '/guide/node-filters' - }, - { - text: 'Deno Filters', - link: '/guide/deno-filters' - }, - { - text: 'Profile Filters', - link: '/guide/profile-filters' - } - ] - } - ] } } }) diff --git a/docs/docs/community-filters.md b/docs/docs/community-filters.md deleted file mode 100644 index 398ec39c..00000000 --- a/docs/docs/community-filters.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Community Filters ---- - - - -# Community Filters - -The beauty of Regolith is that filters can be written and shared by anyone! This page contains an uncurated list of community filters. If your filter doesn't appear here, [let us know](https://discord.com/invite/XjV87YN)! - -## Installing Community Filters -Community filters are installed via a URL-like resource definition: `github.com///`. - -For example `github.com/SirLich/echo-npc-regolith/echo`. - -::: warning -Please use extreme caution when running unknown code. Regolith and its maintainers take no responsibility for any damages incurred by using the filters on this page. To learn more, please read our [safety page](/guide/safety). -::: - -::: tip -Having trouble? You can learn more about online filters [here](/guide/online-filters). -::: - -## Filters - -| Name | Author | Language | Description | -| ---- | ------ | -------- | ----------- | -| [esbuild_executor](https://github.com/MajestikButter/Regolith-Filters/tree/main/esbuild_executor) | MajestikButter | nodejs | A regolith filter for using esbuild | -| [js_formatter](https://github.com/MajestikButter/Regolith-Filters/tree/main/js_formatter) | MajestikButter | nodejs | A regolith filter for formatting JavaScript files | -| [json_formatter](https://github.com/MajestikButter/Regolith-Filters/tree/main/json_formatter) | MajestikButter | nodejs | A regolith filter for formatting JSON files | -| [ts_transpiler](https://github.com/MajestikButter/Regolith-Filters/tree/main/ts_transpiler) | MajestikButter | nodejs | A regolith filter for transpiling Typescript files | -| [NBTEnchant](https://github.com/SmokeyStack/MCScripts/tree/main/NBTEnchant) | SmokeyStack | python | This script is used to generate .mcstructure files containing edited nbt data that is currently not possible to do ingame | -| [file_freedom](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/file_freedom) | Hatchibombotar | nodejs | This filter allows you to place bedrock addon file *anywhere* within the addon directories. | -| [functioner](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/functioner) | Hatchibombotar | nodejs | A filter for regolith that adds more syntax to function files. | -| [init-full](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/init-full) | Hatchibombotar | nodejs | Filter that creates bedrock manifest files on install | -| [link_manifests](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/link_manifests) | Hatchibombotar | nodejs | Links uuid's from the resource and behaviour pack manifests in the dependencies section. | -| [molang_insert](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/molang_insert) | Hatchibombotar | nodejs | A filter for regolith that allows you to insert molang. | -| [pack_commons](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/pack_commons) | Hatchibombotar | nodejs | Intended to allow copying of files into both the resource and behaviour packs | -| [simple_blocks](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/simple_blocks) | Hatchibombotar | nodejs | A filter that creates blocks from one file. | -| [templater](https://github.com/Hatchibombotar/useful-regolith-filters/tree/main/templater) | Hatchibombotar | nodejs | A templater filter for regolith. | -| [item_scale](https://github.com/MedicalJewel105/regolilters/tree/main/item_scale) | MedicalJewel105 | python | This filter generates render_offsets for 1.16.100+ items. | -| [custom_project](https://github.com/Nusiq/regolith-filters/tree/master/custom_project) | Nusiq | exe | No description. | -| [debug_say_function_name](https://github.com/Nusiq/regolith-filters/tree/master/debug_say_function_name) | Nusiq | python | No description. | -| [pytemplate](https://github.com/Nusiq/regolith-filters/tree/master/pytemplate) | Nusiq | python | No description. | -| [run_counter](https://github.com/Nusiq/regolith-filters/tree/master/run_counter) | Nusiq | python | A pointless filter for counting the number of uses of the 'regolith run' command. | -| [subfunctions](https://github.com/Nusiq/regolith-filters/tree/master/subfunctions) | Nusiq | python | No description. | -| [system_template](https://github.com/Nusiq/regolith-filters/tree/master/system_template) | Nusiq | python | No description. | -| [extend-vanilla-entities](https://github.com/littlechestnutgames/regolith-filters/tree/main/extend-vanilla-entities) | littlechestnutgames | python | A JSON partials system. | -| [digger_gen](https://github.com/SirLich/regolith-filters/tree/main/digger_gen) | SirLich | python | The `digger_gen` filter allows you to quickly and easily generate the `minecraft:digger` component, to satisfy your tool-building needs. | -| [e-backup](https://github.com/cda94581/regolith-filters/tree/main/e-backup) | cda94581 | nodejs | Backups your export target in case you made a mistake. | -| [export](https://github.com/cda94581/regolith-filters/tree/main/export) | cda94581 | nodejs | Exports your add-on into a ".mcaddon" automatically. | -| [minimize](https://github.com/cda94581/regolith-filters/tree/main/minimize) | cda94581 | nodejs | Minimize all file JSONs. Can save a tiny bit of space. Also kinda pointless but whatever. | -| [namespace](https://github.com/cda94581/regolith-filters/tree/main/namespace) | cda94581 | nodejs | Automatically apply and replace namespaces to each block, item, entity, recipe, attachable, particle, and fog. Useful for temporary namespaces before deployment. | -| [export](https://github.com/Makercamp-SRLs/Regolith-filters/tree/main/export) | Makercamp-SRLs | nodejs | Exports your add-on into a ".mcaddon", ".mcworld", ".mctemplate" automatically. | -| [module_importer](https://github.com/ShiCheng-Lu/Regolith-Filters/tree/main/module_importer) | ShiCheng-Lu | nodejs | A regolith filter for import | -| [command_lang](https://github.com/MCDevKit/regolith-library/tree/main/command_lang) | MCDevKit | shell | Compiles the CommandLang programming language into .mcfunction files. | -| [json_templating_engine](https://github.com/MCDevKit/regolith-library/tree/main/json_templating_engine) | MCDevKit | java | Compiles JSON templates into JSON files. Especially useful for making reusable pieces of content or large amounts of JSON files. | -| [jsonte](https://github.com/MCDevKit/regolith-library/tree/main/jsonte) | MCDevKit | exe | No description. | -| [classes](https://github.com/evilguy50/my-regolith-filters/tree/main/classes) | evilguy50 | nim | filter for adding OOP class like structure to functions | -| [dash](https://github.com/evilguy50/my-regolith-filters/tree/main/dash) | evilguy50 | nim | No description. | -| [ds_store](https://github.com/evilguy50/my-regolith-filters/tree/main/ds_store) | evilguy50 | nim | filter for removing .DS_Store files | -| [new_exec](https://github.com/evilguy50/my-regolith-filters/tree/main/new_exec) | evilguy50 | nodejs | filter for converting old execute commands to the 1.19.10 format | -| [shorthand](https://github.com/evilguy50/my-regolith-filters/tree/main/shorthand) | evilguy50 | python | filter for having shorthand syntax inside of functions | -| [strip](https://github.com/evilguy50/my-regolith-filters/tree/main/strip) | evilguy50 | nim | filter for striping comments from json, mcfunction, and lang files | -| [style_lint](https://github.com/evilguy50/my-regolith-filters/tree/main/style_lint) | evilguy50 | python | filter for automatic project styling | -| [title_ui](https://github.com/evilguy50/my-regolith-filters/tree/main/title_ui) | evilguy50 | nim | filter for generating title ui bindings | -| [echo](https://github.com/SirLich/echo-npc-regolith/tree/main/echo) | SirLich | python | No description. | -| [scalable-teams](https://github.com/cda94581/regolith-premade-addons/tree/main/scalable-teams) | cda94581 | nodejs | Generates a pre-made teams add-on, scalable and customizable. Appends itself to developed packs. | diff --git a/docs/docs/guide/configuration.md b/docs/docs/guide/configuration.md deleted file mode 100644 index cbbbcef0..00000000 --- a/docs/docs/guide/configuration.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Project 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/docs/guide/create-a-filter.md b/docs/docs/guide/create-a-filter.md deleted file mode 100644 index f9cd606c..00000000 --- a/docs/docs/guide/create-a-filter.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Create a Filter ---- - -# Create a Filter - -This step-by-step tutorial will guide you through the creation of your first Regolith filter, in the Python programming language. If you're new to Regolith, you may enjoy trying out some of our [standard filters](/standard-library) first. - -::: warning -This page is an in-depth tutorial for Regolith filter creation, including detailed information about data-flow and semantics. If you just want to get started programming, you may consider checking out the documentation on [custom filters.](/guide/custom-filters) -::: - -## Installing Python - -Before you can begin, you need to ensure that Python is installed on your system. There are [download instructions](/guide/python-filters) on our Python Filter page. - -## Getting Started - -If you don't have one yet, you should create a new Regolith project by navigating to a blank folder, and typing `regolith init`. - -::: tip -During this tutorial, `project` refers to the project folder you just created! -::: - -The first step is creating a new python file in `project/filters/giant_mobs.py`. Our first step will be simply printing `hello world!`, so add `print("hello world!")` into your new filter file. - -You can also create a small addon in `RP` and `BP`. For this tutorial, you need at least a working `manifest.json`, and a single working behavior entity, such as one copied from the vanilla files. - -### Testing your Filter - -At this point, you need to edit your `config.json` so that `giant_mobs` is registered as a local filter. Your config should look something like this: - -```json -{ - "name": "Giant Mobs", - "author": "Your Name", - "packs": { - "behaviorPack": "./packs/BP", - "resourcePack": "./packs/RP" - }, - "regolith": { - "profiles": { - "default": { - "filters": [ - { - "filter": "giant_mobs" - } - ], - "export": { - "target": "development", - "build": "standard", - "readOnly": true - } - } - }, - "filterDefinitions": { - "giant_mobs": { - "runWith": "python", - "script": "./filters/big_mobs.py" - } - }, - "dataPath": "./packs/data" - } -} -``` - -You can now run `regolith run default`. If everything went well, you should be able to navigate into Minecraft, and create a new world with your RP and BP added. Every time you want to test, re-run `regolith run default`. The "default" profile is special, so you can run it without specifying a profile name (`regolith run`). - -## Understanding Regolith - -Regolith projects are structured such that every filter will be run inside of a temporary folder, with all addon and configuration files available. You should *destructively edit these files in-place*! The files will be copied and moved around for you. - -The general structure will look like: - -``` -tmp folder - - RP - - manifest.json - - ... other files - - BP - - manifest.json - - ... other files - - data - - giant_mobs - - ... some config files - - giant_mobs.py -``` - -So for our cases, that means that we can access `RP` and `BP` folder to edit the addon files within. - -## Filter Goal - -In this filter, we are going to "filter" every entity in the project, and double it's size! We do this by reading every entity file, searching for the "scale" component, and editing it. - -To get started, you should structure your python file a bit better: - -```python -def main(): - print("put code here!") - -main() -``` diff --git a/docs/docs/guide/custom-filters.md b/docs/docs/guide/custom-filters.md deleted file mode 100644 index 38a9b418..00000000 --- a/docs/docs/guide/custom-filters.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Custom Filters ---- - -# Custom Filters - -Regolith allows you to write your own local files, and register them directly as filters. Special support is provided for filters written with Python, Node JS, and other languages. - -To start writing a custom filter, you first need a script to run. We will use `hello_world.py` as an example: - -```python -print("Hello world!") -``` - -## Creating Scripts - -New filters can be defined anywhere, but the suggested location is in `filters` folder, at the top level of the Regolith project. This folder isn't created for you, so you need to create it yourself. - -Once this folder is created, you can add your scripts here. You can organize with sub-folders if desired. - -## Filter Data - -The accepted flow for Regolith is to store configuration scripts and configs inside of the `data` folder. This folder has special support that makes it easy to access during compilation. Read more about the data folder [here](/guide/data-folder). - -## Registering Custom Filter - -Now you can register your script by placing the filter into `filterDefinitions`. Here is a full example, which defines a new filter named "test", and runs it in the "default" profile. - -```json -{ - "name": "example", - "author": "example", - "packs": { - "behaviorPack": "./packs/BP", - "resourcePack": "./packs/RP" - }, - "regolith": { - "profiles": { - "default": { - "filters": [ - { - "filter": "test" - } - ], - "export": { - "target": "local", - "readOnly": false - } - } - }, - "filterDefinitions": { - "test": { - "runWith": "python", - "script": "./filters/test.py" - } - }, - "dataPath": "./packs/data" - } -} -``` - -You can use the following "runWith" types: - - [python](/guide/python-filters) - - [nodejs](/guide/node-filters) - - [deno](/guide/deno-filters) - - [java](/guide/java-filters) - - [nim](/guide/nim-filters) - - [shell](/guide/shell-filters) - -There is also the [profile](/guide/profile-filters) filter with slightly different syntax. It lets you nest profiles. - -Please see the dedicated pages for these run-types for more information! - -## Filter Arguments - -Fundamentally, a Regolith run target is a wrapper around generating a system command, and running it. For example, the following json will generate the command: `python ./filters/hello_world.py`. - -```json -{ - "runWith": "python", - "script": "./filters/hello_world.py" -} -``` - -If you need to pass additional command line arguments, you can do so like this: - -`"arguments": ["-u", "--no-console"]` (example of additional console commands) - -These console arguments will be passed into the script as args. - -## Filter Settings - -The settings object is a special property of run targets, that allow passing in minified/stringified json as an arg. - -Here is an example: - -```json -{ - "runWith": "python", - "script": "./filters/message.py", - "settings": { - "message": "Hello World!" - } -} -``` - -This will generate: `python ./filters/message.py {'message':'Hello World!'}` - -This is useful for passing user-defined settings into your filter. Simply handle the first argument in the argument array, and interpret it as json! - -## Filter Environment Variables - -Every filter process ran by regolith has following additional environment variables: - - `FILTER_DIR` - This environment variable contains an absolute path to the cache directory, where currently ran filter is. - - `ROOT_DIR` - This environemnt variable contains an absolute path to the project root directory, where config.json file is. diff --git a/docs/docs/guide/data-folder.md b/docs/docs/guide/data-folder.md deleted file mode 100644 index adc30c16..00000000 --- a/docs/docs/guide/data-folder.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: 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/docs/guide/deno-filters.md b/docs/docs/guide/deno-filters.md deleted file mode 100644 index 832e1924..00000000 --- a/docs/docs/guide/deno-filters.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Deno Filters ---- - -# Deno Filters - -Deno is a new age javascript/typescript runtime with first class typescript support. - -## Installing Deno - -Before you can run deno filters, you will need to [install Deno](https://deno.land/). - -## Running Deno code as Filter - -The syntax for running a deno filter is this: - -```json -{ - "runWith": "deno", - "script": "./filters/example.ts" -} -``` - -## Requirements and Dependencies - -Deno manages and installs dependencies on runtime. So no additional setup required. diff --git a/docs/docs/guide/dotnet-filters.md b/docs/docs/guide/dotnet-filters.md deleted file mode 100644 index 0412f144..00000000 --- a/docs/docs/guide/dotnet-filters.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: .NET Filters ---- - -# .NET Filters - -.NET filters run programs written in the .NET framework using `dotnet` command. - -## Installing .NET - -Before you can run .NET filters, you will need to install -[.NET Runtime](https://dotnet.microsoft.com/download). - -## Running .NET applications as Filter - -The syntax for running a .NET filter is this: - -```json -{ - "runWith": "dotnet", - "path": "./filters/example.dll" -} -``` diff --git a/docs/docs/guide/exe-filters.md b/docs/docs/guide/exe-filters.md deleted file mode 100644 index 29b7b980..00000000 --- a/docs/docs/guide/exe-filters.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Executable Filters ---- - -# Executable Filters - -Exe filters allow the usage of executables. - -## Running executable as a Filter - -If you have have achieved the feat of having one executable for all platforms (or only care about one platform), you can simply do the following: - -```json -{ - "runWith": "exe", - "exe": "path/to/your/executable" -} -``` - -Alternatively, if you need to specify the executable based on platform. You can do it by using the `when` property to enable/disable the filter based on the -platform: - -```json -{ - "runWith": "exe", - "exe": "coolThing.exe", - "when": "os == \"windows\"" -}, -{ - "runWith": "exe", - "exe": "coolThingLinux", - "when": "os == \"linux\"" -}, -{ - "runWith": "exe", - "exe": "coolThingMac", - "when": "os == \"darwin\"" -}, -``` - -You can learn more about the `when` property on in the documentation of the "config.json" file -[here](/guide/configuration#regolith-configuration). diff --git a/docs/docs/guide/experiments.md b/docs/docs/guide/experiments.md deleted file mode 100644 index 237271ea..00000000 --- a/docs/docs/guide/experiments.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Experiments ---- - -# Experiments - -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` - -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). - -The `size_time_check` should greatly speed up the exports of large projects. - -The downside of this approach is that on the first run, the export will be slower, but on subsequent runs, the export will be much faster. This means that the `size_time_check` is not recommended for CI where Regolith is run only once. - -Usage: -``` -regolith run --experiments size_time_check -regolith watch --experiments size_time_check -``` \ No newline at end of file diff --git a/docs/docs/guide/export-targets.md b/docs/docs/guide/export-targets.md deleted file mode 100644 index b35f6b89..00000000 --- a/docs/docs/guide/export-targets.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 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. - -# 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/docs/guide/filter-run-modes.md b/docs/docs/guide/filter-run-modes.md deleted file mode 100644 index 1c254a5c..00000000 --- a/docs/docs/guide/filter-run-modes.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: 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 [data](/guide/data-folder) 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/docs/guide/filters.md b/docs/docs/guide/filters.md deleted file mode 100644 index 1d404088..00000000 --- a/docs/docs/guide/filters.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Filters ---- - -# 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 [standard library](/standard-library). You may also be interested in [community filters](/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 diff --git a/docs/docs/guide/getting-started.md b/docs/docs/guide/getting-started.md deleted file mode 100644 index 5f723077..00000000 --- a/docs/docs/guide/getting-started.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Getting Started -description: Learn how to use Regolith. ---- - -# Getting Started - -::: info -To get started with Regolith, you should first read our [introduction](/guide/what-is-regolith) page, and the [installation](/guide/installing) 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 [troubleshooting guide](/guide/troubleshooting) 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/). -::: - -## Creating a new Project - -To create a new project, navigate to a blank folder, and run `regolith init`. This will create a few files: - -![](/introduction/project_folder.png) - -In short: - - `.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. - -## Config file - -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) - "packs": { - "behaviorPack": "./packs/BP", - "resourcePack": "./packs/RP" - }, - "regolith": { - "profiles": { - "default": { - "filters": [], - "export": { - "target": "development", - "build": "standard", - "readOnly": false - } - } - }, - "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. - -::: tip -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 ["development" export target](/guide/export-targets). -::: - -## Creating your Addon - -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: - -![](/introduction/project_folder2.png) - -## 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`. - -## 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 [standard library](/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). - -### Installing - -::: 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: - -```json -"default": { - "export": { - "readOnly": false, - "target": "development", - "build": "standard" - }, - "filters": [ - { - "filter": "texture_list" - } - ] -} -``` - -### 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 -`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! -:::: - -:::: warning -`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 [standard library](/standard-library), to see if additional filters might be useful for you. - -Otherwise, you can learn about writing [custom filters](/guide/custom-filters) or -dive deeper into Regolith commands by reading about [Filter Run Modes](/guide/filter-run-modes) -and [Installing and Updating Filters](/guide/installing-filters). diff --git a/docs/docs/guide/installing-filters.md b/docs/docs/guide/installing-filters.md deleted file mode 100644 index b6afe958..00000000 --- a/docs/docs/guide/installing-filters.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Installing and Updating 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 [here](/guide/python-filters). - -## Installing a Filter - -Regolith contains a powerful installation command, which will download a filter from GitHub, and install any required libraries for you. In general, the format is like this: `regolith install ` - -The value of `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/docs/guide/installing.md b/docs/docs/guide/installing.md deleted file mode 100644 index 1ffac29a..00000000 --- a/docs/docs/guide/installing.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Installing ---- - -# Installing - -## Windows Installation Using `winget` - -::: info -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/docs/guide/java-filters.md b/docs/docs/guide/java-filters.md deleted file mode 100644 index 5b22d22a..00000000 --- a/docs/docs/guide/java-filters.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Java Filters ---- - -# Java Filters - -Java is a high-level compiled language, that runs inside the Java Virtual Machine. - -## Installing Java - -Before you can run Java filters, you will need to install Java Development Kit. - -There are many available JDKs to choose from. Few recommended are: - - [OpenJDK](https://jdk.java.net/) - - [AdoptOpenJDK](https://adoptopenjdk.net/) - - [LibericaJDK](https://bell-sw.com/pages/downloads/) - -## Running Java applications as Filter - -The syntax for running a java jar is this: - -```json -{ - "runWith": "java", - "script": "./filters/example.jar" -} -``` - -## Dependencies - -All dependencies should be bundled into a "fat JAR" as this filter type does not have an automatic dependency fetching. - diff --git a/docs/docs/guide/local-filters.md b/docs/docs/guide/local-filters.md deleted file mode 100644 index cbbc5da2..00000000 --- a/docs/docs/guide/local-filters.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 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: - -```json -{ - "runWith": "python", - "script": "./filters/example.py" -} -``` - -The `.` path will be local to the root of the regolith project. diff --git a/docs/docs/guide/nim-filters.md b/docs/docs/guide/nim-filters.md deleted file mode 100644 index 0c6f1286..00000000 --- a/docs/docs/guide/nim-filters.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Nim Filters ---- - -# Nim Filters - -Nim is a statically typed compiled systems programming language. It combines successful concepts from mature languages like Python, Ada and Modula. - -## Installing Nim - - 1. Download the newest version of [choosenim.](https://nim-lang.org/install_windows.html) - 2. Open a terminal in the same directory that you downloaded `choosenim`. - 3. Run `choosenim --firstInstall` - -## Running Nim code as Filter - -The syntax for running a nim filter is this: - -```json -{ - "runWith": "nim", - "script": "./filters/example.nim", - - // Optional property that defines the path to the folder with the *.nimble file - "requirements": "./filters" -} -``` - -## Requirements and Dependencies - -If your filter has dependencies, put a `.nimble` file in the same directory as your `.nim` file, alternatively -you can specify different path using the "requirements" property. Regolith will look for the nimble file in -the folder specified by "requirements" or if it's not defined in the same folder as the script. - -Documentation on how to make a `.nimble` file is located [here](https://github.com/nim-lang/nimble#creating-packages). diff --git a/docs/docs/guide/node-filters.md b/docs/docs/guide/node-filters.md deleted file mode 100644 index 49c5f5eb..00000000 --- a/docs/docs/guide/node-filters.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: NodeJS 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/docs/guide/online-filters.md b/docs/docs/guide/online-filters.md deleted file mode 100644 index 8fc0cc85..00000000 --- a/docs/docs/guide/online-filters.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Online Filters ---- - -# Online Filters - -Regolith allows custom filters to be placed on GitHub. This is perfect for a filter that you want to make public, or potentially share internally in a team. - -The standard [filters library](/standard-library) is a good reference for how to structure an online filter, but we will also explain here. - -## Creating Online Filter - -To create an online filter, your github project needs to be structured in a certain way. For starters, every filter needs its own folder, at the top of the github project. This folder name is very important, as it will be the name of the filter. - -You should move your programs and scripts into this folder. When your filter is installed, everything in this folder will be downloaded. - -### filter.json - -`filter.json` is a special file, which you should place at the top level of your filters folder. Once again, check out the standard-library for examples of a property structured regolith filter. - -```json -{ - // Description is a property which currently is not used by Regolith itself, but the web scraper uses - // it to add descriptions to the filters page of the documentation website. - "description": "A Hello World Filter - this will be displayed as a description on website pages.", - - // exportData is a property which tells Regolith whether or not to export the data folder back to the - // source files after running the profile that uses this filter. - "exportData": true, - - "filters": [ - { - "runWith": "python", - "script": "./hello_world.py" - } - ] -} -``` - -#### The `exportData` property - -This option lets you create remote filters that can modify their data folder. The older versions of -Regolith like 0.0.18 used to always export the entire filter data folder back to the source files -making the `regolith run` command destructive. This feature was added to let the filters remember -their state between runs. Most of the filters don't need this feature, so moving the files back and -forth was a waste of processing time. The `exportData` property is now disabled by default, but it -can be enabled for filters that need it. The `exportData` property causes Regolith to export the -folder named the same as the filter back to the source files. This way you can have both filters -that can modify their data folder and filters that can't. - -## Data Folder - -If you need some default configuration files for your remote filter, you can create a folder called `data` in your filter folder. Here, you can store your default configuration files. When a user runs `regolith install`, this data folder will be moved into their data folder, namespaced under the name of the filter. - -You can learn more about this flow [here](/guide/data-folder). - -## Test Folder - -It may be useful to you to include a test project, or test files, which are useful for development, but don't need to be downloaded by the end user. Anything placed in the `test` folder will not be installed by Regolith, and you can use this space for your own development. diff --git a/docs/docs/guide/profile-filters.md b/docs/docs/guide/profile-filters.md deleted file mode 100644 index 10f08cfc..00000000 --- a/docs/docs/guide/profile-filters.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Profile Filters ---- - -# Profile Filters - -Profile filters are a convinient way of working with multiple profiles on one project. They save you from writing repetitive code by letting you run one filter from another. Recursive dependencies are not allowed. - -## Running profile filter - -Unlike other filters, the profile filter doesn't need to have a filter definition. You can always use it as long as you have multiple profiles. - -The syntax for running a profile is this: - -```json -{ - "profile": "my_profile" -} -``` - -Simply add that to the filters list of a profile. - -Here is a complete `config.json` example: -```json -{ - "name": "nested_profilces_example", - "author": "Bedrock-OSS", - "packs": { - "behaviorPack": "./packs/BP", - "resourcePack": "./packs/RP" - }, - "regolith": { - "profiles": { - "default": { - "filters": [ - { - "filter": "example_filter_1" - } - ], - "export": { - "target": "local", - "readOnly": false - } - }, - "extended_default": { - "filters": [ - { - "profile": "default" - }, - { - "filter": "example_2" - } - ], - "export": { - "target": "local", - "readOnly": false - } - } - }, - "filterDefinitions": { - "example_filter_1": { - "runWith": "exe", - "exe": "./example_1" - }, - "example_filter_2": { - "runWith": "exe", - "exe": "./example_2" - } - }, - "dataPath": "./packs/data" - } -} -``` - -In this example `extended_default` profile runs the `default` profile and then it runs additional filter called `example_2`. diff --git a/docs/docs/guide/profiles.md b/docs/docs/guide/profiles.md deleted file mode 100644 index 85cc5414..00000000 --- a/docs/docs/guide/profiles.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Profiles ---- - -# 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. - -::: tip -You can learn more about the configuration options available in Regolith [here](/guide/configuration). -::: diff --git a/docs/docs/guide/python-filters.md b/docs/docs/guide/python-filters.md deleted file mode 100644 index 4df157e2..00000000 --- a/docs/docs/guide/python-filters.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Python Filters ---- - -# Python Filters - -Python is an interpreted high-level general-purpose programming language. - -## Installing Python - -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: - -![](/installing/python.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. -::: - -## Running Python code as Filter - -The syntax for running a python script is this: - -```json -{ - "runWith": "python", - "script": "./filters/example.py", - - // Optional property that defines the path to the file with the requirements - "requirements": "./filters/requirements.txt -} -``` - -## Requirements and Dependencies - -When installing, Regolith will check if the filter has any requirements. If the "requirements" property is set, -Regolith will use the file specified in the property to install the dependencies. If the property is not set, -Regolith will look for a file named "requirements.txt" in the same directory as the script. -If requirements file exits, Regolith will attempt to install these dependencies into a venv, as described below. - -When developing a Python filter with dependencies, you must create this file. You can create a `requirements.txt` file yourself by using `pip freeze`. - -## Venv Handling - -[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/`. - -By default, all filters will share a single venv. - -In case of collision, you may use `"venvSlot": ` property in the filter, to claim a unique venv id. You will need to reinstall the filter. diff --git a/docs/docs/guide/safety.md b/docs/docs/guide/safety.md deleted file mode 100644 index a5812eee..00000000 --- a/docs/docs/guide/safety.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Safety ---- - -# Safety - -Please be aware that Regolith is only intended to be used by users experienced with working inside command prompt. Due to the extreme power and flexibility that Regolith offers, there is an increased chance of harm to your system, if used improperly. We cannot accept any liability. You are fully responsible for the safety of your system. - -## Why is Regolith Unsafe? - -Regolith has the ability to run arbitrary code. This code is not sandboxed, and could damage your system. When writing your own filters, you are responsible to write safe code! - -Regolith also comes with the ability to download third-party filters from the internet. Regolith does not check these filters for safety. Only download and run internet filters if you are absolutely positive the author is trustworthy. - -A compromised filter is able to completely destroy your system. - -## Why isn't Regolith Sandboxed? - -Software sandboxing is extremely difficult, especially since Regolith offers run targets in multiple languages, as well as a native shell integration. - -Sandboxing would also limit the things our users can do. Currently, anything possible with programming can be integrated with Regolith! Sandboxing would limit this. - -Additionally, we believe sandboxing may give our users a false sense of security. Since no sandbox is foolproof, we prefer our users to operate with full caution, rather than trust an imperfect solution to guard them. diff --git a/docs/docs/guide/shell-filters.md b/docs/docs/guide/shell-filters.md deleted file mode 100644 index 177c7c6e..00000000 --- a/docs/docs/guide/shell-filters.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Shell Filters ---- - -# Shell Filters - -Shell Filters allow you to run arbitrary shell commands. This is useful for running scripts that are not natively supported in Regolith. - -## Running arbitrary Shell command as Filter - -The syntax for running a shell script is this: - -```json -{ - "runWith": "shell", - "command": "echo 'hello world'" -} -``` - -Here is another example: - -```json -{ - "runWith": "shell", - "command": "python -u ./filters/my_filter.py" -} -``` diff --git a/docs/docs/guide/troubleshooting.md b/docs/docs/guide/troubleshooting.md deleted file mode 100644 index 5077c17e..00000000 --- a/docs/docs/guide/troubleshooting.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Troubleshooting ---- - -# Troubleshooting - -Regolith is a useful tool, but its somewhat complex compilation flow leaves room for user error. This page will explain solutions to common mistakes, as well as guide you through more complex debugging strategies. - -## General Debugging Tips - -### Reading the Console - -Regolith is a console application, which means that you will need to interact with it via the terminal. When Regolith runs, it will print information into the same log. This information is very useful in debugging, as Regolith will print as much useful information as it can during failure states. - -Please get comfortable reading the console output, and try to become familiar with the syntax. Warnings and errors will be printed clearly. - -### Check your Version - -Regolith is a living, breathing application, which is receiving numerous updates. You can directly install the latest version of Regolith, or watch out for the "A new Version is Available" messages in the console output. - -## Common Issues - -### Regolith is not Recognized - -When first installing Regolith, you may get an error message like this: - -``` -regolith : The term 'regolith' is not recognized as the name of a cmdlet, function, script file, or operable program. - -Check the spelling of the name, or if a path was included, verify that the path is correct and try again. -``` - -The most common cause of this issue is incorrect installation. Here are some troubleshooting tips: - - - 1: First, try closing your shell, and opening a new one. Then rerun the `regolith` command. - - 2: Try a different shell. For example `gitbash` or `vscode` instead of `powershell`. - - 3: Try reinstalling Regolith - - 4: If you cannot get Regolith installed, you may download the stand-alone .exe, and place this in your project - -### Crash when Running - -The most common reason Regolith will crash is from a broken filter. The first step in debugging, is identifying which filter is failing. You can do so by navigating to the Regolith output log, and finding which filter caused the crash. - -Filter errors will be printed like `[error][filter] ... `. - -### Python 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. - -We provide [installation instructions](/guide/python-filters), 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. diff --git a/docs/docs/guide/user-configuration.md b/docs/docs/guide/user-configuration.md deleted file mode 100644 index 85f42e9f..00000000 --- a/docs/docs/guide/user-configuration.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: User Configuration ---- - -# 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" - ] -} -``` - ----- - -::: info -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/docs/guide/what-is-regolith.md b/docs/docs/guide/what-is-regolith.md deleted file mode 100644 index 9fb0b54c..00000000 --- a/docs/docs/guide/what-is-regolith.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: 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 [installation instructions](/guide/installing). -::: - -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: - -![](/introduction/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 [standard library](/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 [here](/guide/custom-filters). - -## 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. - -::: tip -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/docs/index.md b/docs/docs/index.md index 28de2359..62954bb7 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -6,24 +6,12 @@ description: 'A flexible and language-agnostic addon-compiler for the Bedrock Ed hero: name: Regolith - text: Addon Compiler for the Bedrock Edition of Minecraft - tagline: Fast, flexible, and easy to use. Meet the modern Minecraft Bedrock tooling. + tagline: The documentation has been moved to a new location. Please click the button below to access the new documentation. image: src: /logo.png alt: Regolith logo actions: - theme: brand - text: Get Started - link: /guide/what-is-regolith - -features: - - icon: ⚡️ - title: Blazingly Fast - details: Regolith can improve your productivity by automating away boring or repetitive tasks. - - icon: 🧩 - title: Flexible - details: Regolith is designed with a language-agnostic, tool-agnostic feature set. The flexibility of Regolith allows you to bring all scripts and tools under a single, unified workflow. - - icon: 🏷️ - title: Version Control Friendly - details: Regolith keeps the ‘source of truth’ out of your com.mojang folder, allowing for seamless git integration. + text: Go to the New Documentation + link: https://regolith-docs.readthedocs.io/en/latest/ --- diff --git a/docs/docs/public/installing/exe_download.png b/docs/docs/public/installing/exe_download.png deleted file mode 100644 index 3cdb816d..00000000 Binary files a/docs/docs/public/installing/exe_download.png and /dev/null differ diff --git a/docs/docs/public/installing/msi_download.png b/docs/docs/public/installing/msi_download.png deleted file mode 100644 index b087e2d6..00000000 Binary files a/docs/docs/public/installing/msi_download.png and /dev/null differ diff --git a/docs/docs/public/installing/python.png b/docs/docs/public/installing/python.png deleted file mode 100644 index 15977113..00000000 Binary files a/docs/docs/public/installing/python.png and /dev/null differ diff --git a/docs/docs/public/installing/regolith_help.png b/docs/docs/public/installing/regolith_help.png deleted file mode 100644 index d2617443..00000000 Binary files a/docs/docs/public/installing/regolith_help.png and /dev/null differ diff --git a/docs/docs/public/installing/regolith_msi.png b/docs/docs/public/installing/regolith_msi.png deleted file mode 100644 index 8f00b8ea..00000000 Binary files a/docs/docs/public/installing/regolith_msi.png and /dev/null differ diff --git a/docs/docs/public/introduction/project_folder.png b/docs/docs/public/introduction/project_folder.png deleted file mode 100644 index e9036f42..00000000 Binary files a/docs/docs/public/introduction/project_folder.png and /dev/null differ diff --git a/docs/docs/public/introduction/project_folder2.png b/docs/docs/public/introduction/project_folder2.png deleted file mode 100644 index 0f3707f0..00000000 Binary files a/docs/docs/public/introduction/project_folder2.png and /dev/null differ diff --git a/docs/docs/standard-library.md b/docs/docs/standard-library.md deleted file mode 100644 index e6d8e110..00000000 --- a/docs/docs/standard-library.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Standard Library ---- - - - -# Standard Library - -The Standard Library is a special set of filters, written by the Regolith maintainers. Standard Filters offers the safest, easiest, and best support. - -## Standard Filters - -| Filter | Description | -| ------ | ----------- | -| [blockbench_convert](https://github.com/Bedrock-OSS/regolith-filters/tree/master/blockbench_convert) | Converts blockbench models into `.geometry.json` files. | -| [bump_manifest](https://github.com/Bedrock-OSS/regolith-filters/tree/master/bump_manifest) | Bumps the manifest version in your RP and BP. Good for multiplayer testing where you need to avoid pack-caching issues. | -| [filter_tester](https://github.com/Bedrock-OSS/regolith-filters/tree/master/filter_tester) | Meant to be used by the filter developers to test other filters. It compares the expected results with the files generated by Regolith. | -| [fix_emissive](https://github.com/Bedrock-OSS/regolith-filters/tree/master/fix_emissive) | Fixes emissive issues in your textures, by removing the color data from fully transparent pixels. | -| [gametests](https://github.com/Bedrock-OSS/regolith-filters/tree/master/gametests) | Compiles gametests into pack. | -| [json_cleaner](https://github.com/Bedrock-OSS/regolith-filters/tree/master/json_cleaner) | Removes comments from all json files in the project. Useful, since some filters cannot understand files with comments. | -| [name_ninja](https://github.com/Bedrock-OSS/regolith-filters/tree/master/name_ninja) | Automatically generates entity, block, spawn egg, and item names, based on a custom 'name' field, or on the entities identifier. | -| [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. - -## Using a Standard Filter - -You may install standard filters by name. For example: `regolith install name_ninja`. - -The syntax for standard filters usage is like this: - -```json -{ - "filter": "", - "settings" { ... } // Optional -} -``` diff --git a/docs/docs/vite.config.ts b/docs/docs/vite.config.ts index 3635fd05..10379c69 100644 --- a/docs/docs/vite.config.ts +++ b/docs/docs/vite.config.ts @@ -1,16 +1,5 @@ //vite.config.ts -import { SearchPlugin } from "vitepress-plugin-search"; -import { defineConfig } from "vite"; +import { defineConfig } from 'vite' -//default options -var options = { - // ...flexSearchIndexOptions, - previewLength: 62, - buttonLabel: "Search", - placeholder: "Search...", -}; - -export default defineConfig({ - plugins: [SearchPlugin(options)], -}); \ No newline at end of file +export default defineConfig({}) diff --git a/docs/fetch-filters.ts b/docs/fetch-filters.ts deleted file mode 100644 index b939b28b..00000000 --- a/docs/fetch-filters.ts +++ /dev/null @@ -1,222 +0,0 @@ -import { writeFile } from 'node:fs/promises' -import { join, resolve } from 'node:path' -import { $fetch } from 'ohmyfetch' - -const COMMENT = `` - -async function writeStandardLibrary(): Promise { - console.log('- Fetching Standard Library -') - - const headerContent = [ - '---', - 'title: Standard Library', - '---', - '', - COMMENT, - '', - '# Standard Library', - '', - 'The Standard Library is a special set of filters, written by the Regolith maintainers. Standard Filters offers the safest, easiest, and best support.', - '', - '## Standard Filters' - ] - const footerContent = [ - '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', - '', - 'You may install standard filters by name. For example: `regolith install name_ninja`.', - '', - 'The syntax for standard filters usage is like this:', - '', - '```json', - '{', - ' "filter": "",', - ' "settings" { ... } // Optional', - '}', - '```' - ] - - const baseUrl = 'https://github.com/Bedrock-OSS/regolith-filters/tree/master/' - const rawBaseUrl = - 'https://raw.githubusercontent.com/Bedrock-OSS/regolith-filters/master/' - const ignoreList = ['future'] - - const getFilters = async (): Promise[]> => { - const data = await $fetch[]>( - 'https://api.github.com/repos/bedrock-oss/regolith-filters/contents/' - ) - const filters = data.filter((filter) => filter.type === 'dir') - return filters - } - const getFilterLink = (name: string): string => baseUrl + name - const getFilterDescription = async (name: string): Promise => { - const filterFileUrl = rawBaseUrl + name + '/filter.json' - const data = await $fetch(filterFileUrl, { parseResponse: JSON.parse }) - return data.description || 'No description.' - } - const formatFilters = async (): Promise => { - let columns: string[] = [] - for (const { name } of await getFilters()) { - if (ignoreList.includes(name)) continue - console.log(name) - columns.push( - `| [${name}](${getFilterLink(name)}) | ${await getFilterDescription( - name - )} |` - ) - } - return columns - } - - const fileContent = [ - ...headerContent, - '', - '| Filter | Description |', - '| ------ | ----------- |', - ...(await formatFilters()), - '', - ...footerContent, - '' - ].join('\n') - - await writeFile(join(resolve(), 'docs', 'standard-library.md'), fileContent) - console.log('Updated Standard Library') -} - -interface Filter { - name: string - author: string - lang: string - description: string - url -} - -async function writeCommunityFilters(): Promise { - console.log('- Fetching Community Filters -') - - const headerContent = [ - '---', - 'title: Community Filters', - '---', - '', - COMMENT, - '', - '# Community Filters', - '', - `The beauty of Regolith is that filters can be written and shared by anyone! This page contains an uncurated list of community filters. If your filter doesn't appear here, [let us know](https://discord.com/invite/XjV87YN)!`, - '', - '## Installing Community Filters', - 'Community filters are installed via a URL-like resource definition: `github.com///`.', - '', - 'For example `github.com/SirLich/echo-npc-regolith/echo`.', - '', - '::: warning', - 'Please use extreme caution when running unknown code. Regolith and its maintainers take no responsibility for any damages incurred by using the filters on this page. To learn more, please read our [safety page](/guide/safety).', - ':::', - '', - '::: tip', - 'Having trouble? You can learn more about online filters [here](/guide/online-filters).', - ':::', - '', - '## Filters' - ] - - const findReadmeDescription = (content: string): string => { - return ( - content.split('\n').find((line) => { - if (!line.startsWith('#') && line !== '') return line - }) || 'No description.' - ) - } - const fetchFilters = async (): Promise => { - const filters: Filter[] = [] - - const repos = await $fetch( - 'https://api.github.com/search/repositories?q=topic:regolith-filter' - ) - - for (const repo of repos.items) { - const author = repo.owner.login - if (author === 'Bedrock-OSS') continue - - const rootDir = await $fetch( - `https://api.github.com/repos/${repo.full_name}/contents` - ) - for (const rootItem of rootDir) { - let name = '' - let lang = '' - let description = '' - let url = '' - - if (rootItem.type === 'dir') { - const childDir = await $fetch(rootItem.url) - - for (const childItem of childDir) { - switch (childItem.name) { - case 'filter.json': - const filter = await $fetch(childItem.download_url, { - parseResponse: JSON.parse - }) - - name = rootItem.name - lang = filter.filters[0].runWith - url = rootItem.html_url - description = - filter?.filters[0]?.description || - filter?.description || - 'No description.' - continue - - case 'readme.md': - case 'README.md': - const readme = await $fetch(childItem.download_url) - description = findReadmeDescription(readme) - continue - - default: - continue - } - } - } else continue - - if (name && author && lang && description && url) { - console.log(name) - filters.push({ - name, - author, - lang, - description, - url - }) - } - } - } - - return filters - } - const formatFilters = async (): Promise => { - const filters = await fetchFilters() - const formattedFilters = filters.map( - ({ author, description, lang, name, url }) => { - return `| [${name}](${url}) | ${author} | ${lang} | ${description} |` - } - ) - return formattedFilters - } - - const content = [ - ...headerContent, - '', - '| Name | Author | Language | Description |', - '| ---- | ------ | -------- | ----------- |', - ...(await formatFilters()), - '' - ].join('\n') - - await writeFile(join(resolve(), 'docs', 'community-filters.md'), content) - console.log('Updated Community Filters') -} - -await writeStandardLibrary() -await writeCommunityFilters()