update rainglow docs

orifu · orifu · commit 59f7054b00f4 · 2024-09-25T00:48:37.000+01:00
diff --git a/src/content/docs/rainglow/config.md b/src/content/docs/rainglow/config.md
@@ -5,32 +5,57 @@ sidebar:
   order: 2
 ---
 
-<!-- todo: 1.3.x -->
+The rainglow config file is stored in `.minecraft/config/rainglow.toml` by default. Here is how it looks by default:
 
-## for versions below `1.3.0`
+```toml
+// rainglow.toml
+# The currently active rainglow mode, which determines the possible colours for entities to spawn with.
+# If custom, will be reset to the default mode if you join a server that does not have the mode.
+# default: rainbow
+default_mode = "rainbow"
+# The custom colours to use when the mode is set to custom.
+custom_colours = ["blue", "white", "pink"]
+# Whether to allow recolouring entities via dyes.
+# default: false
+allow_dyeing = false
+
+# The rarity of coloured entities, with 0 making all entities vanilla and 100 making all entities coloured.
+[rarities]
+	allay = 100
+	glow_squid = 100
+	slime = 100
+
+# Toggles for disabling colours for each entity.
+[toggles]
+	allay = true
+	glow_squid = true
+	slime = true
+```
 
-### general information
+<details>
+<summary>Click for versions before 1.3.0!</summary>
 
-- The rainglow configuration is stored in `[your_instance_folder (usually .minecraft)/[your_config_directory (usually config)]/rainglow.toml`.
-  If you have not edited anything this means it is in `.minecraft/config/rainglow.toml`.
+The rainglow configuration is stored in `.minecraft/config/rainglow.toml` by default. If you have changed your Minecraft/config folder it may be elsewhere.
 
 ### example configuration
 
 ```toml
 mode = "genderfluid_pride"
 custom = ["blue", "red", "green", "pink", "yellow", "orange", "indigo", "purple", "white", "gray", "black"]
 enable_server_sync = true
+rarity = 100
 
 enable_glow_squid = true
 enable_slime = true
 enable_allay = false
 ```
 
-<!-- todo: is information about `rarity` missing? -->
-
 ### what are those things?
 
-- `mode`: the mode declares which colours are currently shown in your game. Rainglow comes with a set of default modes, and as a server owner you can [define your own](/rainglow/creating-custom-modes/). When you change this, all squids with now-invalid colours will have their colours re-rolled. Information on which modes can be used by default can be found [here](/rainglow/reference/#default-modes).
+- `mode`: the mode declares which colours are currently shown in your game. Rainglow comes with a set of default modes, and you can [define your own](/rainglow/creating-custom-modes/) using data packs. When you change this, all squids with now-invalid colours will have their colours re-rolled. A list of default modes can be found [here](/rainglow/reference/#default-modes).
 - `custom`: this defines all the colours available in the "custom" mode. Information on which colours can be added can be found [here](/rainglow/reference/#available-colours).
-- `enable_server_sync`: this option only changes anything if you're a server owner. If `true`, it will force the client to use the mode you have set in your configuration, and also send the client any custom modes you've made. More information on what this does and how it works can be found [here](/rainglow/server-sync/).
+- `enable_server_sync`: if this is set to `true` on a server, connecting clients will use the mode you have set in your configuration, and also send the client any custom modes you've made. More information on what this does and how it works can be found [here](/rainglow/server-sync/).
+- `rarity`: the percentage likelihood of any entity having a custom colour. This defaults to 100, meaning 100% of entities have rainglow colours.
 - `enable_[entity]`: rainglow provides granular control over whether to use custom colour for each supported entity. If `false`, the entity will use its vanilla colours. Information on which entities can be added can be found [here](/rainglow/reference/#available-entities).
+
+</details>
diff --git a/src/content/docs/rainglow/creating-custom-modes.mdx b/src/content/docs/rainglow/creating-custom-modes.mdx
@@ -7,15 +7,13 @@ sidebar:
 
 import { FileTree } from '@astrojs/starlight/components';
 
-## introduction
-
 This article explains how to make a custom mode through JSON.
 
 It includes both a tutorial and full documentation on JSON properties and available colours.
 
 ## tutorial
 
-The first step to creating a rainglow datapack is establishing the directory structure. Your normal data pack looks like this:
+The first step to creating a rainglow data pack is establishing the directory structure. Your normal data pack looks like this:
 
 <FileTree>
 
@@ -27,14 +25,14 @@ The first step to creating a rainglow datapack is establishing the directory str
 
 </FileTree>
 
-We're going to be creating a new folder in `data` named `rainglow`, which corresponds to the id of the mod. Inside this folder we'll be creating another named `custom_modes`, from which rainglow discovers data. All files ending with `.json` in this folder will be loaded.
+We're going to be creating a new folder in `data` named `rainglow`, where rainglow related files go. Inside this folder we'll be creating another named `custom_modes`, from which rainglow discovers data. All files ending with `.json` in this folder will be loaded.
 
 Our structure now looks like this:
 
 <FileTree>
 
 - data
-  - minecraft/ this folder is not used in our little datapack, it can simply be deleted
+  - minecraft/ this folder is not used in our data pack, it can simply be deleted
   - **rainglow**
     - **custom_modes**
       - ... rainglow mode jsons go here!
@@ -45,9 +43,10 @@ Our structure now looks like this:
 
 Now, we get to the fun part: creating your mode! For this tutorial, our goal is to make a mode with the colours of a sunset.
 
-In your `custom_modes` folder, create a `.json` file. This can be named anything, as long as it ends with `.json` so that rainglow knows to load it. Our file will be named `sunset.json`.
+In your `custom_modes` folder, create a new file for our custom mode. It can be called anything, as long as it's a `.json` file. Our file will be named `sunset.json`.
 
 ```json
+// sunset.json
 {
   "id": "sunset",
   "textColour": "E07000",
@@ -58,33 +57,34 @@ In your `custom_modes` folder, create a `.json` file. This can be named anything
 To break down this file, we have three properties:
 
 - `id`: the name of your mode. This can only contain lowercase letters and underscores. Examples: `lesbian_pride`, `monochrome`, `rainbow`.
-- `textColour`: the colour of the text for your mode. This will be shown in the config screen. It is in a hex code format. You can get a hex code for any colour from a site like [tslat's colour picker](http://tslat.net/minitools/colourpicker/index.html).
+- `textColour`: the colour of the text for your mode, in hex format. This is the colour of the text shown on the config screen. Colour pickers, such as [the one built-in to Google](https://google.com/search?q=color%20picker), will be helpful.
 - `colourIds`: an array of colours that will be included in your mode. These are in the format of colour ids, which denote colours built into the mod. A full list of available colours can be found [here](/rainglow/reference/#available-colours).
 
-Finally, you need to add translations for your mode. This has to be done through a resource pack, which is defined on the client. If you're implementing a custom mode on your server, this will have to be sent to the client when they log in. Documentation on this can be found [here](https://minecraft.wiki/w/Tutorials/Creating_a_resource_pack).
+Finally, you need to add translations for your custom mode. This has to be done through a resource pack, which is defined on the client. If you're implementing a custom mode on your server, this will have to be sent to the client when they log in. Documentation on this can be found [here](https://minecraft.wiki/w/Tutorials/Creating_a_resource_pack#Server_resource_packs).
 
-In your resource pack, you must have a structure like this:
+Your resource pack should have a structure like this:
 
 <FileTree>
 
 - assets
   - rainglow
     - lang
-      - en_us.json an english lang file
+      - en_us.json an english language file
 - pack.mcmeta metadata for your pack
 - pack.png the icon for your pack
 
 </FileTree>
 
-Inside `en_us.json` (or a different filename if you're using a different language) you must put content like this:
+Inside your language file, you can then define your mode's name using a key in the format `"rainglow.mode.[id]"`. For our sunset example, the language file will look like this:
 
 ```json
+// en_us.json
 {
   "rainglow.mode.sunset": "Sunset"
 }
 ```
 
-The text after `rainglow.mode.` must be set to your custom mode's id, and the text "Sunset" will be replaced with your custom mode's full name.
+Now when referring to our sunset mode, its name will be shown as "Sunset".
 
 Finally, place your datapack and resource pack inside minecraft's `datapacks` and `resourcepacks` folders respectively.
 
diff --git a/src/content/docs/rainglow/reference.md b/src/content/docs/rainglow/reference.md
@@ -8,7 +8,7 @@ next: check out bodacious berries!
 
 ## available colours
 
-rainglow's available colours are:
+rainglow's available colours are Minecraft's default 16, and `indigo`:
 
 - `black`
 - `blue`
@@ -30,24 +30,26 @@ rainglow's available colours are:
 
 ## default modes
 
-|       mode id       | colours                                                                 |
-| :-----------------: | ----------------------------------------------------------------------- |
-|    `all_colours`    | everything listed in the "available colours" section                    |
-|      `custom`       | whatever you've defined in your [configuration file](/rainglow/config/) |
-|      `rainbow`      | `red`, `orange`, `yellow`, `green`, `lime`, `blue`, `indigo`, `purple`  |
-|     `aro_pride`     | `black`, `gray`, `white`, `green`                                       |
-|     `ace_pride`     | `black`, `gray`, `white`, `purple`                                      |
-|     `bi_pride`      | `blue`, `pink`, `purple`                                                |
-|     `gay_pride`     | `blue`, `cyan`, `green`, `white`                                        |
-| `genderfluid_pride` | `purple`, `white`, `black`, `pink`, `blue`                              |
-|   `lesbian_pride`   | `red`, `orange`, `white`, `pink`, `purple`                              |
-|    `monochrome`     | `black`, `gray`, `white`                                                |
-|    `enby_pride`     | `yellow`, `white`, `black`, `purple`                                    |
-|     `pan_pride`     | `pink`, `yellow`, `blue`                                                |
-|    `trans_pride`    | `blue`, `white`, `pink`                                                 |
+|       mode id       | colours                                                                 | ui color |
+| :-----------------: | ----------------------------------------------------------------------- | -------- |
+|    `all_colours`    | everything listed in the "available colours" section                    | #00ff00  |
+|      `custom`       | whatever you've defined in your [configuration file](/rainglow/config/) | #00ffe1  |
+|      `rainbow`      | `red`, `orange`, `yellow`, `green`, `lime`, `blue`, `indigo`, `purple`  | #aa208f  |
+|     `ace_pride`     | `black`, `gray`, `white`, `purple`                                      | #a252Bf  |
+|     `aro_pride`     | `black`, `gray`, `white`, `green`                                       | #61d85b  |
+|     `bi_pride`      | `blue`, `pink`, `purple`                                                | #0063a0  |
+|     `gay_pride`     | `blue`, `cyan`, `green`, `white`                                        | #61d85b  |
+| `genderfluid_pride` | `purple`, `white`, `black`, `pink`, `blue`                              | #a02cb7  |
+|   `lesbian_pride`   | `red`, `orange`, `white`, `pink`, `purple`                              | #db4b32  |
+|    `monochrome`     | `black`, `gray`, `white`                                                | #b7b7b7  |
+|    `enby_pride`     | `yellow`, `white`, `black`, `purple`                                    | #705ca8  |
+|     `pan_pride`     | `pink`, `yellow`, `blue`                                                | #cea800  |
+|    `trans_pride`    | `blue`, `white`, `pink`                                                 | #d472e5  |
 
 ## available entities
 
-- `glow_squid`
-- `allay`
-- `slime`
+|  entity id   | default colour |
+| :----------: | -------------- |
+| `glow_squid` | `blue`         |
+|   `allay`    | `blue`         |
+|   `slime`    | `lime`         |
diff --git a/src/content/docs/rainglow/server-sync.md b/src/content/docs/rainglow/server-sync.md
@@ -7,12 +7,12 @@ sidebar:
 
 ## what is it?
 
-Server sync is rainglow's solution to making sure that everyone on your server has a consistent experience. When enabled, everyone must use the same mode and the same configuration, ensuring that they all see the same things. The config screen is locked from editing, and it is not reloaded from the file until the player leaves the server locking it.
-
-Server sync also sends any custom modes you may have created to the client!
+Server sync is rainglow's solution to making sure that everyone on your server has a consistent experience. When enabled, the server will inform clients about the colours of entities, meaning everyone sees the same things! While connected to a server, players won't be able to use the config screen.
 
 ## how does that work?
 
-When a player joins the server that has server sync enabled, it sends two packets: one with the server's configuration, and one with a list of custom modes on the server. First, the client parses the list of custom modes and configures and adds any that do not exist on its side. The client takes the config and sets all its internal values to that of the server's config.
+When a player joins the server that has server sync enabled, it sends three packets: one with the server's configuration, one with a list of custom modes on the server, and a map from entity UUIDs to their colours. First, the client parses the list of custom modes and configures and adds any that do not exist on its side. The client takes the config and sets all its internal values to that of the server's config.
+
+When a colour packet is sent, the client stores which entities have which colour. More of these packets may be sent later; for example, if an entity spawns in, or an entity's colour changes.
 
-When the player leaves the server, the modes are removed and the config is reloaded from its file. Nothing is written permanently to disk when playing on a server that forces sync.
+When the player leaves the server, the overrides are removed, and the config is reloaded from its file. The player's config will not be changed while playing on a server that forces sync.
