feat: Bukkit configs, help.yml and permissions.yml (#571)

* add the final bukkit configs, help.yml and permissions.yml

* apply formatting and fix spelling

* apply suggeston

Co-authored-by: Matouš Kučera <[email protected]>

* remove mention of formatting permissions

This behaviour is subject to change, and shouldn't be documented (probable bug)

* punctuation

* add not-a-permission-plugin-replacement warning

* Update src/config/paper/help.yml

Co-authored-by: Lulu13022002 <[email protected]>

---------

Co-authored-by: Matouš Kučera <[email protected]>
Co-authored-by: Lulu13022002 <[email protected]>

Author: 3 people

astro.config.ts

@@ -85,6 +85,8 @@ export default defineConfig({
                             "paper/reference/bukkit-configuration",
                             "paper/reference/spigot-configuration",
                             "paper/reference/bukkit-commands-configuration",
+                            "paper/reference/bukkit-permissions-configuration",
+                            "paper/reference/bukkit-help-configuration",
                             "paper/reference/server-properties",
                             "paper/reference/vanilla-data-files",
                           ],

src/config/paper/help.yml

@@ -0,0 +1,108 @@
+general-topics:
+  <topic name>:
+    header:
+      message: A custom help "topic" to show when the user types "`/help <topic>`".
+    shortText:
+      description: |
+        The first line of the help entry, used as a summary in index pages.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    fullText:
+      description: |
+        The remaining lines of this help entry.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    permission:
+      description: |
+        The permission required to view this help entry.
+
+        If this is empty/not set, the entry does not require a permission.
+      default: '""'
+
+index-topics:
+  <topic name>:
+    header:
+      message: |
+        A composite help topic index.
+
+        If the topic name is the special value "Default",
+        it will override the automatically generated index used for /help with no arguments.
+    shortText:
+      description: |
+        The short text used in other index topics.
+
+        This is not displayed when showing this topic itself.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    preamble:
+      description: |
+        Information to show before the index.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    permission:
+      description: |
+        A custom permission required to view this help entry.
+
+        If this is empty/not set, the entry does not require a permission.
+      default: '""'
+    commands:
+      description: |
+        What to show in the index.
+
+        This is a list of commands, or other help topics.
+
+        They will be displayed in the order they are listed here
+        in "topic name: short text" format.
+
+        Each entry is a maximum of 1 minimum-width chat line (55 chars).
+      default: "[]"
+
+amended-topics:
+  <topic name>:
+    shortText:
+      description: |
+        A replacement for the short text of the topic.
+
+        If this is empty/not set, the original short text is used.
+
+        If this contains the literal string `<text>`, it will be replaced with the original short text.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    fullText:
+      description: |
+        A replacement for the full text of the topic.
+
+        If this is empty/not set, the original full text is used.
+
+        If this contains the literal string `<text>`, it will be replaced with the original full text.
+
+        This is formatted with legacy "&" style formatting.
+      default: '""'
+    permission:
+      description: |
+        Overrides the permission required to view this help entry.
+
+        If this is empty/not set, the original permission is NOT used, instead no permission is required.
+      default: '""'
+
+ignore-plugins:
+  description: |
+    A list of plugins to ignore when generating help topics for registered commands.
+
+    If "All" is included, all plugins are ignored.
+
+    If the special plugin name "Bukkit" is included, all commands registered by Bukkit are ignored.
+  default: "[]"
+
+command-topics-in-master-index:
+  description: |
+    Whether to allow command topics (topics starting with a `/`) to be shown in the main index.
+
+    This is the index shown when the user types "`/help`" or "`/help <page>`".
+    Command alias topics are always hidden.
+  default: "true"

src/config/paper/permissions.yml

@@ -0,0 +1,29 @@
+<permission>:
+  default:
+    description: |
+      Who this permission is granted to by default.
+
+      "true": all players.
+
+      "false": no players.
+
+      "op": only operators (also aliased as "isop", "operator", "isoperator", "admin", and "isadmin").
+
+      "!op": all players except operators (also aliased as "notop", "!operator", "notoperator", "!admin", "notadmin").
+    default: "op"
+  children:
+    header:
+      message: A list (not shown) or a map (shown below) of child permissions.
+    <permission>:
+      description: |
+        A child permission of this permission.
+
+        The value is either a boolean, where false inverts the whether the permission would be granted to this.
+
+        or a top level permission entry,
+        except the default is this parent permissions default value,
+        and any child permissions of the newly created permission are bubbled up to the top level.
+      default: "true"
+  description_:
+    description: The description of the permission.
+    default: '""'

src/content/docs/paper/admin/reference/configuration/bukkit-help-configuration.mdx

@@ -0,0 +1,18 @@
+---
+title: help.yml
+slug: paper/reference/bukkit-help-configuration
+---
+
+import ConfigNode from "/src/components/ConfigNode.astro";
+import HelpYML from "/src/config/paper/help.yml?raw";
+import { parse } from "yaml";
+
+:::note
+
+The below YAML shows you the structure for `help.yml`.
+
+Click on a leaf node to view the description for that setting.
+
+:::
+
+<ConfigNode data={parse(HelpYML)} />

src/content/docs/paper/admin/reference/configuration/bukkit-permissions-configuration.mdx

@@ -0,0 +1,26 @@
+---
+title: permissions.yml
+slug: paper/reference/bukkit-permissions-configuration
+---
+
+import ConfigNode from "/src/components/ConfigNode.astro";
+import PermissionsYML from "/src/config/paper/permissions.yml?raw";
+import { parse } from "yaml";
+
+:::note
+
+The below YAML shows you the structure for `permissions.yml`.
+
+Click on a leaf node to view the description for that setting.
+
+:::
+
+:::caution
+
+This is NOT a replacement for a permissions plugin.
+
+This file is used to define metadata about permissions themselves, including a description and a default value.
+
+:::
+
+<ConfigNode data={parse(PermissionsYML)} />

src/content/docs/paper/admin/reference/configuration/index.mdx

@@ -32,9 +32,9 @@ If this is not the case, they offer a brief explanation to what they are.
   - [bukkit.yml](/paper/reference/bukkit-configuration)
   - [commands.yml](/paper/reference/bukkit-commands-configuration)
   - [eula.txt](/paper/reference/vanilla-data-files#eulatxt) stores the EULA consent status
-  - help.yml stores configuration for the `/help` command
+  - [help.yml](/paper/reference/bukkit-help-configuration) stores configuration for the `/help` command
   - [ops.json](/paper/reference/vanilla-data-files#opsjson) stores information about players with operator status
-  - permissions.yml stores permission configuration
+  - [permissions.yml](/paper/reference/bukkit-permissions-configuration) stores additional permission definitions
   - [server.properties](/paper/reference/server-properties)
   - [spigot.yml](/paper/reference/spigot-configuration)
   - usercache.json caches players' Mojang API data, e.g. their head textures