diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml deleted file mode 100644 index 0fef39f..0000000 --- a/.github/workflows/node.js.yml +++ /dev/null @@ -1,36 +0,0 @@ -# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node -# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions - -name: Node.js CI - -on: - push: - branches: [master] - pull_request: - branches: [master] - repository_dispatch: - workflow_dispatch: -jobs: - build: - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [14.x] - - steps: - - uses: actions/checkout@v2 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v1 - with: - node-version: ${{ matrix.node-version }} - - run: npm i yarn -g - - run: yarn - - run: git submodule init - - run: git submodule update - - run: yarn build - - name: Deploy - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./build diff --git a/.gitignore b/.gitignore index b2d6de3..d97e100 100644 --- a/.gitignore +++ b/.gitignore @@ -1,20 +1 @@ -# Dependencies -/node_modules - -# Production -/build - -# Generated files -.docusaurus -.cache-loader - -# Misc -.DS_Store -.env.local -.env.development.local -.env.test.local -.env.production.local - -npm-debug.log* -yarn-debug.log* -yarn-error.log* +site \ No newline at end of file diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..f59ec20 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +* \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..dcf98a2 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "workbench.iconTheme": "material-icon-theme" +} diff --git a/README.md b/README.md index 0847b88..b6d35d7 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,7 @@ -# Docs +# Horay! Docs! -This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. +# How to serve the docs +`python -m mkdocs serve` -## Installation - -```console -yarn install -``` - -## Local Development - -```console -yarn start -``` - -This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. - -## Build - -```console -yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -## Deployment - -```console -GIT_USER= USE_SSH=true yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +# How to push to gh-pages +`python -m mkdocs gh-deploy` \ No newline at end of file diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..4e6d604 --- /dev/null +++ b/TODO.md @@ -0,0 +1,2 @@ +- [x] Create a migration Guide +- [ ] Document [Compiler Context](https://github.com/mc-build/mcb/blob/main/src/mcl/Compiler.hx#L285-L304) \ No newline at end of file diff --git a/babel.config.js b/babel.config.js deleted file mode 100644 index e00595d..0000000 --- a/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -}; diff --git a/static/CNAME b/docs/CNAME similarity index 100% rename from static/CNAME rename to docs/CNAME diff --git a/src/pages/code-of-conduct.mdx b/docs/code-of-conduct.md similarity index 99% rename from src/pages/code-of-conduct.mdx rename to docs/code-of-conduct.md index cb338e5..1e8b2e3 100644 --- a/src/pages/code-of-conduct.mdx +++ b/docs/code-of-conduct.md @@ -97,4 +97,4 @@ typescript community code of conduct: https://github.com/typescript-community/go contributor-covenant homepage: http://contributor-covenant.org contributor-covenant version: http://contributor-covenant.org/version/1/4/ -- see hack and tell COC for the definition (https://hackandtell.org/#code_of_conduct) +- see hack and tell COC for the definition (https://hackandtell.org/#code_of_conduct) \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..2ad47d6 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,61 @@ +# Getting Started with MC-Build + +Getting started with MC-Build is easy! This guide will walk you through the process of installing MC-Build and creating your first project. + +## Installing MC-Build +In order to install MC-Build, You'll first need Node.js. + +If you don't already have Node.js, visit their site ([nodejs.org](https://nodejs.org/en/)) and download and run the installer. + +Once you've installed Node.js, open a command prompt and run the following command: + +```bash +npm i -g mc-build@latest +``` + +That's it! MC-Build is now installed. + +You can run `mcb` in the command prompt to verify that MC-Build is installed correctly: + +``` +$ mcb +MCB - A Minecraft Data Pack build tool. + +Usage: ... +``` + +## Creating a New Project. + +MC-Build comes with a command to help you quickly setup a new project. Simply navigate to your chosen `world/datapacks` folder, then run the following command: + +```bash +mcb create my_epic_datapack +``` + +This will create a new folder called `my_epic_datapack` in your `world/datapacks` folder, and set up a basic project structure for you. + +## The Project Structure + +- `my_epic_datapack` - This is the root folder of your project. + - `pack.mcmeta` - This file is identical to a vanilla `pack.mcmeta` file. + - `src/` - This folder is where you'll write your MC-Build code. + - `data/` - MC-Build will compile your code into this folder, which is the same structure as a vanilla data pack. + - `mcb.config.js` - The configuration file for your project. + +## Building Your Project + +Navigate to your project folder and run the following command: + +```bash +mcb watch +``` + +This will start the MC-Build compiler in watch mode, which will automatically compile your code whenever you make changes. + +You can also run `mcb build` to compile your code once, without watch mode. + +That's it! Your project is now ready for development. + +## What's Next? + +Check out the [Language Features](language-features/index.md) documentation for more information on how to write MC-Build code. diff --git a/static/img/favicon.ico b/docs/img/favicon.ico similarity index 100% rename from static/img/favicon.ico rename to docs/img/favicon.ico diff --git a/static/img/logo.png b/docs/img/logo.png similarity index 100% rename from static/img/logo.png rename to docs/img/logo.png diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..1023609 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +# Welcome to the MC-Build Documentation! + +Check out the [Getting Started](getting-started.md) guide to learn how to install and use MC-Build. + +## What is MC-Build? +MC-Build is a Data Pack pre-compiler language. Designed as a superset of Minecraft's commands, it's aimed to make it easier to write and maintain complex Data Packs without needing to learn or use an entirely different language. + +## Community + +Join our [Discord Server](https://discord.gg/kpGqTDX)! We're always happy to help out and answer any questions you might have. \ No newline at end of file diff --git a/docs/landing.md b/docs/landing.md deleted file mode 100644 index 72dd4ad..0000000 --- a/docs/landing.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -slug: / ---- - -# Installing mc-build - -[Video Tutorial on installing mc-build (Credit - AncientKingg)](https://streamable.com/bcljw4) - -To install mc-build on your device you must first install Node.js. Simply visit their site ([nodejs.org](https://nodejs.org/en/)) and download and run the installer. - -Once node is finished installing open a command prompt and run this command: `npm i -g mc-build` - -Tada! mc-build is now installed. - -# Creating a development environment - -To create a mc-build datapack, simply navigate to your chosen `world/datapacks` folder, and create a new datapack folder. - -Then inside the datapack folder, create a `src` folder, and a pack.mcmeta file. (The pack.mcmeta is identical to a vanilla pack.mcmeta) - -Then open a command prompt and navigate to your new datapack folder. - -Once inside your datapack folder, run the command `mcb`. - -That's it! Your datapack is now ready for development. - -# Creating a config file - -Open a command prompt and navigate to your datapack folder. Then: - -- To create a JSON config: `mcb -config json` -- To create a JavaScript config: `mcb -config js` diff --git a/docs/lang-mc/Getting-Started.md b/docs/lang-mc/Getting-Started.md deleted file mode 100644 index 93e29cf..0000000 --- a/docs/lang-mc/Getting-Started.md +++ /dev/null @@ -1,25 +0,0 @@ -# Installing mc-build - -[Video Tutorial on installing mc-build (Credit - AncientKingg)](https://streamable.com/bcljw4) - -To install mc-build on your device you must first install Node.js. Simply visit their site ([nodejs.org](https://nodejs.org/en/)) and download and run the installer. - -Once node is finished installing open a command prompt and run this command: `npm i -g mc-build` - -Tada! mc-build is now installed. - -# Creating a development environment -To create a mc-build datapack, simply navigate to your chosen `world/datapacks` folder, and create a new datapack folder. - -Then inside the datapack folder, create a `src` folder, and a pack.mcmeta file. (The pack.mcmeta is identical to a vanilla pack.mcmeta) - -Then open a command prompt and navigate to your new datapack folder. - -Once inside your datapack folder, run the command `mcb`. - -That's it! Your datapack is now ready for development. - -# Creating a config file -Open a command prompt and navigate to your datapack folder. Then: -- To create a JSON config: `mcb -config json` -- To create a JavaScript config: `mcb -config js` diff --git a/docs/lang-mc/The-mc-language.md b/docs/lang-mc/The-mc-language.md deleted file mode 100644 index 10fb7a2..0000000 --- a/docs/lang-mc/The-mc-language.md +++ /dev/null @@ -1,291 +0,0 @@ -# Contexts -- Folder context refers to where functions and directories can be defined. -- Function context refers to syntax inside of functions where commands can be written. -- Macro context refers to the folder context inside of `.mcm` files -``` -#!foo.mc -# Folder context -dir { - # Folder context - function bar { - # Function context - say Hello - } -} -# Folder context -function bas { - # Function context - say World! -} -``` -# Functions -You can create functions using the `function` keyword: -``` -function foo { - say I am called via `function mc_file_name:foo` -} -``` -Functions can only be defined within [Folder context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Directories -You can create sub directories using the `dir` keyword: -``` -dir foo { - function bar { - say I am called via `function mc_file_name:foo/bar` - } - dir bar { - function bas { - say I am called via `function mc_file_name:foo/bar/bas` - } - } -} -``` -Directories can only be defined within [Folder context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Function Blocks -Function blocks are used to define groups of commands that will be wrapped up into a function on compile-time. - -Using the `block` keyword will define a block and inline the generated function call: -``` -block { - scoreboard players set @s value 1 - tellraw @s {"score":{"objective":"value","name":"@s"}} -} -# When this compiles it will inline something similar to this: -# function mc_file_name:__generated__/block/0 - -# The block keyword can be omitted, but recommended for readability in most cases. -# This will compile the same as above -{ - scoreboard players set @s value 1 - tellraw @s {"score":{"objective":"value","name":"@s"}} -} -``` -Function blocks can also be defined at the end of execute commands: -``` -execute if score @s value matches 1 run block { - tellraw @s "Value is 1" -} -# When this compiles it will inline something similar to this: -# execute if score @s value matches 1 run function mc_file_name:__generated__/execute/0 - -# Again the block keyword can be omitted: -execute if score @s value matches 1 run { - tellraw @s "Value was 1" - scoreboard players set @s value 0 -} -``` -Keep in mind that if you do not omit the `block` keyword after an `execute` command it will always define a function, even if the block only contains a single command. If omitted and only 1 command is inside the block instead of making a function it will just append that command to the end of the `execute` command. For example: -``` -execute if score @s value matches 1 run { - tellraw @s "Value is 1" -} -``` -Would compile to `execute if score @s value matches 1 run tellraw @s "Value was 1"` - -Function blocks can also be named using the `name` keyword: -``` -block { - name foo - say hi -} -``` -This allows for manual naming to remove the `__generated__` folders from your datapack if you so choose. - -Function blocks can only be defined and used within [Function context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Clocks -Clocks are an easy way of running a function every x amount of time. -For instance you could create a clock that runs every 5 seconds like this: -``` -clock 5s { - say I run every 5 seconds! -} -``` -The time argument takes a `schedule` command time input (`5s`, `10t`, `1d`) - -Clocks can only be defined and used within [Folder context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# While, Async While, and Until -### While -The `while` loop can be used to run a set of commands while a condition (defined as an `execute` subcommand chain) is true. It will halt the execution of the function until the loop exits: -``` -scoreboard players set #i 0 -while(if score #i value matches ..10) { - tellraw @a [{"text":"loop "},{"score":{"name":"#i","objective":"value"}}] - scoreboard players add #i value 1 -} -say I will run once the while loop has ended! -``` -This will loop until the value of `#i` is greater than `10`, and then it will exit the loop and continue running the function - -### Async While -The async while loop will run a set of commands every x amount of time until it's condition is true without halting the execution of the function. -``` -scoreboard players set #i value 0 -async while(if score #i value matches ..10,5t) { - scoreboard players add #i value 1 - tellraw @a [{"text":"loop "},{"score":{"name":"#i","objective":"value"}}] -} -say I will run immediately after the first while loop -``` -The `async while` loop can also have a `finally` function block defined that will execute it's contents once the loop exits: -``` -scoreboard players set #i value 0 -async while(if score #i value matches ..10,5t) { - tellraw @a [{"text":"loop "},{"score":{"name":"#i","objective":"value"}}] - scoreboard players add #i value 1 -} finally { - say I will run once the loop exits! -} -say I will run immediately after the first while loop -``` - -### Until -The `until` loop will run a set of commands every x amount of time until the condition is met. It will not halt function execution: -``` -scoreboard players set #i value 0 -until(if score #i value matches 10,1s) { - tellraw @a [{"text":"loop "},{"score":{"name":"#i","objective":"value"}}] - scoreboard players add #i value 1 -} -``` -`blocking until` and the `finally` block are planned but not implemented as of yet. - -while, async while, and until can only be defined and used within [Function context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Multiline Commands -*WARNING* This feature is *experimental*. It may not always work the way you expect - -You can use `()` curved brackets to surround a command to allow newlines in that command: -``` -( - execute - if block ~ ~ ~ stone - if block ~ ~1 ~ stone - run say hi -) -# This would compile to: -execute if block ~ ~ ~ stone if block ~ ~1 ~ stone run say hi -``` - -Multiline commands can only be defined and used within [Function context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Inline & Multiline JS Blocks -### Inline JS block -Inline JS blocks are JS code wrapped in `<%` and `%>`. Whatever the JS inside of those brackets returns will be what is inserted into the command/line: -``` -# For instance if the value of config.text is "hello" than this code: -say <%config.text%> -# Will compile to this: -say hello -``` -Inline JS blocks cannot span multiple lines. - -### Multiline JS block -Multiline JS blocks are JS code wrapped in `<%%` and `%%>`. -``` -<%% - for (let i=0; i<10; i++) { - emit(`say ${i}`) - } -%%> -``` -The opening and closing brackets must be the only thing on their line. Only whitespace is allowed before them - -Inline and Multiline JS blocks can only be defined and used within [Function context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Compile time logic -### !IF -The compile time if statement can be used to omit code and/or functions if a certain condition is not met. For example if you didn't want a dev function to export unless a flag was true in the config you could do something like this: -``` -!IF(config.dev) { - function dev_tool { - say I'm a dev function. Yay! - } -} -``` -This would only generate that function IF config.dev is set to `true`. -### Shorthand !IF -Same as !IF, but less to type: -``` -!config.dev{ - say hi -} -``` -### LOOP -Compile time LOOP allows you to generate code based off of a JS iterable value. The second argument is the loop variable that will be passed to the context inside the loop. -``` -# This will generate 10 functions, loop_0-9 that say their name when ran -LOOP(10,i){ - function loop_<%i%> { - say loop_<%i%> - } -} -``` - -Compile time logic (!IF shorthand compile time if, and LOOP) can be defined and used within [Function and Folder context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - -# Execute if else blocks -Execute if else blocks allow you to write run-time if else logic with ease: -``` -execute(if score #i value matches 1){ - say The value is 1 -}else execute(if score #i value matches 2){ - say The value is 2 -}else{ - say I don't know what value it is, but it ain't 1 or 2 ',:I -} -``` - -Execute if else blocks can be defined and used within [Function context](https://github.com/mc-build/lang-mc/wiki/The-mc-language/#contexts) - - -# macros -You can only define macros in .mcm files. -``` -# mess.mcm -macro mess { - say $$0 - scoreboard players set $$1 $$2 10 -} -``` -Macros must be imported in order to be referenced. -``` -# foo.mc -import ./mess.mcm - -function bar { - macro mess Hello! @s objective - say Hello again! - # The macro keyword is optional in .mc files! - mess Uhoh .loop v -} -``` -The code above produces this: -``` -# function foo:bar -say Hello! -scoreboard players set @s objective 10 -say Hello again! -say Uhoh -scoreboard players set .loop v 10 -``` -You can append to the load and tick in a macro. It will only append once if the macro is used. -``` -macro mess2 { - tick { - say spam! - } - load { - say Reloaded! - } -} -``` - -JS inside of macros has a few extra globals: -#### emit `emit(text: string): void` -Emits text directly to the output function. -#### args `args: Array<{type: string, content: string}>` -A list of arguments passed to the macro diff --git a/docs/lang-mc/The-mcb-CLI.md b/docs/lang-mc/The-mcb-CLI.md deleted file mode 100644 index 1c26176..0000000 --- a/docs/lang-mc/The-mcb-CLI.md +++ /dev/null @@ -1,15 +0,0 @@ -Running just `mcb` in your datapack's folder will build the entire project once, and then wait for file changes and build newly changed files automatically. - -# Arguments - -#### `mcb -build` -Builds the entire project once and exits. - -#### `mcb -config js|json` -Creates a default config file of the given type - -#### `mcb -offline` -Prevents the update check allowing you to run mcb while disconnected from the internet - -#### `mcb add lang ` -Adds the given language to the project if it exists diff --git a/docs/language-features/blocks.md b/docs/language-features/blocks.md new file mode 100644 index 0000000..2c0a7f3 --- /dev/null +++ b/docs/language-features/blocks.md @@ -0,0 +1,92 @@ +Blocks are used to define an inline function, inside another function. + +``` +block [name] { [ | with <...>] + <...> +} +``` + +## Creating a Block +When creating a block inside of a function, it will inline a call to it's generated function. + +Creating an unnamed block will put the generated function into the parent function's folder + `zzz/.mcfunction`. + +??? info "Creating an Anonymous Block" + ```{title="Code"} + function example { + say Before block + block { + say Hello, world! + } + say After block + } + ``` + + ```{title="example.mcfunction"} + say Before block + function zzz/0 + say After block + ``` + + ```{title="zzz/0.mcfunction"} + say Hello, world! + ``` + +## Naming a Block +A named block will put it's generated function into the parent function's folder as `.mcfunction`. + +??? info "Creating an Named Block" + ```title="Code" + function example { + block my_block { + say Hello, world! + } + } + ``` + + ```{title="example.mcfunction"} + function my_block + ``` + + ```{title="my_block.mcfunction"} + say Hello, world! + ``` + +## Using Macro Arguments + +Blocks can take macro arguments, which are then passed to the inlined function call. + +??? info "Using Macro Arguments" + !!! example "Hard-coded Arguments" + ```{title="Code"} + function example { + block my_block { {input: "world"} + $say Hello, $(input)! + } + } + ``` + + ```{title="example.mcfunction"} + function my_block {input: "world"} + ``` + + ```{title="my_block.mcfunction"} + $say Hello, $(input)! + ``` + + !!! example "Dynamic Arguments" + ```{title="Code"} + function example { + block my_block { with storage example:arguments {} + $say Hello, $(input)! + } + } + ``` + + ```{title="example.mcfunction"} + function my_block with storage example:arguments {} + ``` + + ```{title="my_block.mcfunction"} + $say Hello, $(input)! + ``` diff --git a/docs/language-features/clocks.md b/docs/language-features/clocks.md new file mode 100644 index 0000000..58672f3 --- /dev/null +++ b/docs/language-features/clocks.md @@ -0,0 +1,28 @@ +Clocks are another way of defining a function that runs every so often. + +``` +clock