Merge pull request #8 from Hugman76/build_rush

Add Build Rush documentation

docs/build-rush/builds.md

@@ -0,0 +1,79 @@
+# Adding a build
+
+## Building and saving the structure
+
+!!! warning
+    You need to know how to use the structure block and its SAVE mode to create a build.
+
+First off, you need to build your structure in any creative world that you can download generated structures from. Either in a single-player world, or in a server that allows you to do so.
+
+!!! tip
+    If you have access to the Nucleoid build server, you can join the original builds map `/map join buildrush:builds`.
+    This map contains all the builds that were made by fellow Nucleoid contributors up to 3.0.0.
+
+    To download any generated build on the Nucleoid build server, visit this site: [https://build.nucleoid.xyz/](https://build.nucleoid.xyz/generated/)
+
+You also need to choose a size for your build. Builds must have the same width, length and height.
+Let's say you want a size of `n` blocks for you build. This means you need to create a structure of dimensions `n`x`n`x`n`.
+
+You can also add a custom floor for your build, allowing the structure to be `n`x`n+1`x`n`.
+Players won't have to build this floor, as it will replace the floor of all plots when building. Please make sure that all blocks of the floor have a solid top surface.
+
+!!! tip
+    Do not worry about falling blocks like sand for you floor, as barrier blocks will be placed under the plot floors if the map does not have blocks there.
+
+!!! example
+    If you want to create a build of size 7, you can create a structure of dimensions 7x8x7, with the floor being at the bottom of the structure.
+    If you do not want this floor, you can create a structure of dimensions 7x7x7.
+
+After finishing your build, save it using the structure block. The name of the structure file can be renamed manually afterward.
+Entities are not supported, so make sure to not include them while saving.
+
+Structures are stored under the `structures` folder of the datapack, so save it there when you're done.
+
+## Creating the build file
+
+You now need to add a build configuration that will add information about your build.
+Builds are stored in the `build_rush/builds` folder of the datapack, so create a `.json` file there.
+
+Here are the configuration fields of a build:
+```json5
+{
+  "structure": "build_rush:build/my_build",
+  "name": {
+    "translate": "build.my_build"
+  },
+  "author": {
+    "name": "jeb_",
+    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6"
+  }
+}
+```
+
+| Field         | Description                     | Required | Defaults to |
+|---------------|---------------------------------|----------|-------------|
+| `structure`   | The path to the structure file. | Yes      |             |
+| `name`        | The name of the build.          | Yes      |             |
+| `author`      | The author of the build.        | No       |             |
+| `author.name` | The name of the author.         | Yes      |             |
+| `author.uuid` | The UUID of the author.         | No       |             |
+
+!!! tip
+    If a game tries to load any build that is not valid in any way, it will get ignored and a warning will be sent in the console.
+
+A standalone build will not get used in any gamemode, that's because it is the game config that defines the list of builds that it's going to use.
+However, you can add your build to the `build_rush:generic` tag, which is used by the generic game modes.
+
+## Notes on contributions
+
+If you are contributing to the Build Rush repository, please make sure to follow this checklist before submitting your pull request:
+- Your build is replicable in normal gameplay, on any maps. (no floating blocks)
+- Your build features as less redstone mechanics as possible.
+- If the name of your build is already used, add an underscore and a number at the end of the name. (`build`, `build_2`, `build_3`, ...)
+- Your structure file and your build configuration have the same name.
+- The structure is saved under the `structures/builds` folder inside the `build_rush` datapack.
+- If the build is not made for specific gamemode, add it to the `build_rush:generic` build tag.
+- The build name is translatable. Use existing translations if possible, if not add a translation key that follows the `build.<name>` pattern.
+
+!!! warning
+    Currently, the generic game modes of Build Rush were made for build sizes of 5, 7 and 9. Only size 5 is used for now though. 

docs/build-rush/index.md

@@ -0,0 +1,10 @@
+# About
+
+[![GitHub contributors](https://img.shields.io/github/contributors/NucleoidMC/BuildRush?logo=github&style=for-the-badge)](https://github.com/NucleoidMC/plasmid)
+[![GitHub last commit](https://img.shields.io/github/last-commit/NucleoidMC/BuildRush?logo=github&style=for-the-badge)](https://github.com/NucleoidMC/plasmid)
+
+Build Rush is a build memorizing minigame for Minecraft!  
+The goal is to memorize a structure and then rebuild it as fast and as correct as possible.
+
+!!! info
+    This tutorial is currently updated for **Build Rush 3.0.x**.

docs/build-rush/maps.md

@@ -0,0 +1,85 @@
+# Adding a map
+
+## Creating the map template
+
+Please follow the [Plasmid tutorial](/plasmid/maps) on how to create a map template.
+
+A Build Rush map template needs the following regions:
+- `center_plot`: the center of the map, where the players will be teleported to at first, and where the chosen build may appear at points. (only 1)
+- `plot`: the plots where the players will build. There must be at least as many plots as the max amount of players in the game configuration (see below).
+
+A map can only support one size of builds. The size of the chosen builds is determined by the size of the plots.
+
+All plots must be of the same size (width and length) and be 1 block high.
+
+!!! tip
+    If you get anything wrong with your map, the game will not start. You can check the logs to see what went wrong.
+
+Map templates are stored in the `map_templates` folder of the datapack, so save it there when you're done.
+
+## Creating the game configuration
+
+Please follow the [Plasmid tutorial](/plasmid/getting-started/#creating-a-config) on how to create a game configuration.
+
+You now need to add a game configuration that will use your map.
+Game configurations are stored in the `games` folder of the datapack, so create your `.json` file there.
+
+Here are the configuration fields added by Build Rush, on top of the ones added by Plasmid: 
+```json5
+{
+  // ...
+  "players": {
+    "min": 1,
+    "threshold": 8,
+    "max": 16
+  },
+  "map": {
+    "template": "build_rush:my_map",
+    "nametag_offset": 5,
+    "nametag_size": 2.0
+  },
+  "builds": "#build_rush:generic"
+  // ...
+}
+```
+
+The game type is `build_rush:standard`.
+
+| Field                | Description                                                   | Required | Defaults to |
+|----------------------|---------------------------------------------------------------|----------|-------------|
+| `players`            | The configuration of number of players.                       | Yes      |             |
+| `map`                | The configuration of the map.                                 | Yes      |             |
+| `map.template`       | The map template to use.                                      | Yes      |             |
+| `map.nametag_offset` | The offset of the name tag above the player's plot.           | No       | 10          |
+| `map.nametag_size`   | The size of the name tag above the player's plot.             | No       | 5.0         |
+| `builds`             | The list of builds to use. Can be a list of builds, or a tag. | Yes      |             |
+
+For the builds list, you can use the `#build_rush:generic` tag that includes most of the available builds.
+
+!!! note
+    The builds field can contain any builds, even if they are not compatible with the map. Only compatible builds from the entry list will get used.
+
+## Notes on contributions
+
+If you are contributing to the Build Rush repository, please make sure to follow this checklist before submitting your pull request:
+- Your map template and game configuration have the same name.
+- Your game configuration is in the correct subfolder: `small` is for maps compatible with 5x5 builds, `medium` is for 7x7, and `large` is for 9x9.
+- Your game configuration is listed in the `random` game configuration in the same subfolder.
+- The game configuration follows this example:
+  ```json5
+  {
+    // ...
+    "name": {                                        
+      "translate": "game.build_rush.small.with_map",   // change "small" with "medium" or "large" depending on the size of your plots
+        "with": [
+        {
+          "translate": "map.build_rush.my_map"         // change "my_map" with the identifier of your map (and translate it in lang/en_us.json)
+        }
+      ]
+    },
+    "icon": "minecraft:diamond",                       // as your game will show up in the list of games, you need an item to represent it
+    // ...
+  }
+  ```
+- Your game configuration has an icon.
+- The build list is large enough, to counter the feeling of repetitiveness. Use the `#build_rush:generic` if you don't have enough builds.

mkdocs.yml

@@ -36,6 +36,10 @@ nav:
   - Backend:
     - backend/index.md
     - backend/http-api.md
+  - Build Rush:
+    - build-rush/index.md
+    - build-rush/maps.md
+    - build-rush/builds.md
 
 extra:
   social: