From cecc7e006565bc784b4a5474e33545dfded5cf39 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Sat, 21 Feb 2026 21:12:22 +0100 Subject: [PATCH 1/6] feat(velocity): document velocity-plugin.json file --- astro.config.ts | 1 + .../creating-your-first-plugin.mdx | 6 +- .../getting-started/velocity-plugin-json.mdx | 90 +++++++++++++++++++ 3 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx diff --git a/astro.config.ts b/astro.config.ts index c568f3646..392e4deaa 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -323,6 +323,7 @@ export default defineConfig({ items: [ "velocity/dev/creating-your-first-plugin", "velocity/dev/api-basics", + "velocity/dev/velocity-plugin-json", "velocity/dev/pitfalls", ], }, diff --git a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index f9f35b9e3..51a44a5fd 100644 --- a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -71,6 +71,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg dependencies { compileOnly("com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}") + // If you want your velocity-plugin.json file to be generated based on plugin annotations annotationProcessor("com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}") } ``` @@ -86,6 +87,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg dependencies { compileOnly 'com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}' + // If you want your velocity-plugin.json file to be generated based on plugin annotations annotationProcessor 'com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}' } ``` @@ -114,7 +116,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg \{LATEST_VELOCITY_RELEASE} provided - + com.velocitypowered velocity-api @@ -157,7 +159,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg org.apache.maven.plugins maven-compiler-plugin - + com.velocitypowered diff --git a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx new file mode 100644 index 000000000..5951fd99d --- /dev/null +++ b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx @@ -0,0 +1,90 @@ +--- +title: The Velocity plugin file +description: A full reference of the velocity-plugin.json file. +slug: velocity/dev/velocity-plugin-json +--- + +import { FileTree } from "@astrojs/starlight/components"; + +The `velocity-plugin.json` file is the configuration file for your plugin. It contains information +about your plugin's name, description, version, main class path, and other. + +The `velocity-plugin.json` file is located in the `resources` directory of your plugin. It is generated +automatically if you configured the Velocity annotation processor and used the `@Plugin` annotation. + + + - velocity-plugin/ + - src/ + - main/ + - java/ + - resources/ + - **velocity-plugin.json** + - build.gradle.kts + - settings.gradle.kts + + +## Example +This is an example `velocity-plugin.json` file: + +```json title=velocity-plugin.json +{ + "id": "example-plugin", + "name": "Velocity Example Plugin", + "version": "1.0.0", + "description": "An example plugin for showcasing the plugin json file.", + "main": "com.velocitypowered.testplugin.TestPluginMain" +} +``` + +## Fields +The only required fields are `id` and `main`. Any other fields are optional. + +### id +The ID of the plugin. This ID needs to be unique for each plugin. +- `"id": "a_cool_plugin"` + +Plugin IDs must start with a lowercase letter and may contain lowercase letters, +digits, hyphens, and underscores. The total length must not exceed 64 characters. + +### main +The path towards your main plugin class. +- `"main": "com.example.yourplugin.PluginMain"` + +### name +A user-friendly variant of your plugin's name. +- `"name": "A cool plugin"` + +### version +The version of your plugin. +- `"version": "0.0.1-beta.7"` + +### description +The description of your plugin. +- `"description": "Some interesting plugin description."` + +### url +The URL of your plugin's website. +- `"url": "https://github.com/PaperMC/Velocity"` + +### authors +A list of your plugin's authors. +- `"authors": ["Strokkur24", "electronicboy"]` + +### dependencies +Your plugin's dependencies. The value of this field is an array of dependency objects. + +The dependency object itself has three fields: +- `id` the plugin ID of the plugin you depend upon +- `version` the version of your dependency. This field is not required. +- `optional` whether the dependency is optional. This field is not required. Defaults to `false`. + +```json +{ + "dependencies": [ + { + "id": "luckperms", + "optional": true + } + ] +} +``` From efc739c45f900c6c8169b19faaabcecaeaab3fe4 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Sat, 21 Feb 2026 21:53:18 +0100 Subject: [PATCH 2/6] fix: remove version dependency field --- .../velocity/dev/getting-started/velocity-plugin-json.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx index 5951fd99d..087096d65 100644 --- a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx +++ b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx @@ -73,10 +73,9 @@ A list of your plugin's authors. ### dependencies Your plugin's dependencies. The value of this field is an array of dependency objects. -The dependency object itself has three fields: +The dependency object itself has two fields: - `id` the plugin ID of the plugin you depend upon -- `version` the version of your dependency. This field is not required. -- `optional` whether the dependency is optional. This field is not required. Defaults to `false`. +- `optional` whether the dependency is optional. This field is not required and defaults to `false`. ```json { From abf62775ab4a98db731487a6ed55acf8f2294ee7 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Thu, 2 Apr 2026 22:46:14 +0200 Subject: [PATCH 3/6] feat: add name/id documentation, made example use all fields, replace field headers with list entries, move sidebar entry, add note inside creating-your-first-plugin --- astro.config.ts | 2 +- .../creating-your-first-plugin.mdx | 9 ++ .../getting-started/velocity-plugin-json.mdx | 134 +++++++++++------- 3 files changed, 90 insertions(+), 55 deletions(-) diff --git a/astro.config.ts b/astro.config.ts index c4d3d0df9..a00e81063 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -323,8 +323,8 @@ export default defineConfig({ label: "Getting started", items: [ "velocity/dev/creating-your-first-plugin", - "velocity/dev/api-basics", "velocity/dev/velocity-plugin-json", + "velocity/dev/api-basics", "velocity/dev/pitfalls", ], }, diff --git a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index 51a44a5fd..4695aad65 100644 --- a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -57,6 +57,15 @@ How to set up a build system is outside the scope of this page, but you can look system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userguide.html) or [Maven](https://maven.apache.org/guides/getting-started/index.html)) for assistance. +:::info[velocity-plugin.json] + +Before you set up your build system, you should think about whether you want your `velocity-plugin.json` +to be generated automatically using a `@Plugin` annotation in your source code or if you want to write it +manually. Depending on which you prefer, you may need to add additional lines to your build files. You can find +more information on the [`velocity-plugin.json`] file [here](/velocity/dev/velocity-plugin-json). + +::: + ### Setting up the dependency diff --git a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx index 087096d65..853dadfa6 100644 --- a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx +++ b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx @@ -7,10 +7,9 @@ slug: velocity/dev/velocity-plugin-json import { FileTree } from "@astrojs/starlight/components"; The `velocity-plugin.json` file is the configuration file for your plugin. It contains information -about your plugin's name, description, version, main class path, and other. - -The `velocity-plugin.json` file is located in the `resources` directory of your plugin. It is generated -automatically if you configured the Velocity annotation processor and used the `@Plugin` annotation. +about your plugin's name, description, version, main class path, and other. It is located in the `resources` +directory of your plugin and may be generated automatically, if you configured the Velocity annotation processor +and used a `@Plugin` annotation somewhere in your code. - velocity-plugin/ @@ -28,62 +27,89 @@ This is an example `velocity-plugin.json` file: ```json title=velocity-plugin.json { - "id": "example-plugin", + "id": "example-plugin", // required "name": "Velocity Example Plugin", "version": "1.0.0", "description": "An example plugin for showcasing the plugin json file.", - "main": "com.velocitypowered.testplugin.TestPluginMain" -} -``` - -## Fields -The only required fields are `id` and `main`. Any other fields are optional. - -### id -The ID of the plugin. This ID needs to be unique for each plugin. -- `"id": "a_cool_plugin"` - -Plugin IDs must start with a lowercase letter and may contain lowercase letters, -digits, hyphens, and underscores. The total length must not exceed 64 characters. - -### main -The path towards your main plugin class. -- `"main": "com.example.yourplugin.PluginMain"` - -### name -A user-friendly variant of your plugin's name. -- `"name": "A cool plugin"` - -### version -The version of your plugin. -- `"version": "0.0.1-beta.7"` - -### description -The description of your plugin. -- `"description": "Some interesting plugin description."` - -### url -The URL of your plugin's website. -- `"url": "https://github.com/PaperMC/Velocity"` - -### authors -A list of your plugin's authors. -- `"authors": ["Strokkur24", "electronicboy"]` - -### dependencies -Your plugin's dependencies. The value of this field is an array of dependency objects. - -The dependency object itself has two fields: -- `id` the plugin ID of the plugin you depend upon -- `optional` whether the dependency is optional. This field is not required and defaults to `false`. - -```json -{ + "main": "com.example.testplugin.TestPluginMain", // required + "url": "https://github.com/PaperMC/docs", + "authors": ["Strokkur24"], "dependencies": [ { - "id": "luckperms", - "optional": true + "id": "luckperms", // required for dependencies + "optional": true // defaults to false } ] } ``` + +## Fields +The only required fields are `id` and `main`. Any other fields are optional. + +- **`id`**\ + The ID of the plugin. This ID needs to be unique for each plugin. It is used for identifying your + plugin internally and also used as the name for your plugin's logger. + + Plugin IDs must start with a lowercase letter and may contain lowercase letters, + digits, hyphens, and underscores. The total length must not exceed 64 characters. + + ```json + {"id": "a_cool_plugin"} + ``` + +- **`main`**\ + The path towards your main plugin class. + + ```json + {"main": "com.example.yourplugin.PluginMain"} + ``` + +- **`name`**\ + A user-friendly variant of your plugin's name. This is used for any user-facing display of your plugin, such + as the `/velocity plugins` command. + + ```json + {"name": "A cool plugin"} + ``` + +- **`version`**\ + The version of your plugin. + ```json + {"version": "0.0.1-beta.7"} + ``` + +- **`description`**\ + The description of your plugin. + ```json + {"description": "Some interesting plugin description."} + ``` + +- **`url`**\ + The URL of your plugin's website. + ```json + {"url": "https://github.com/PaperMC/Velocity"} + ``` + +- **`authors`**\ + A list of your plugin's authors. + ```json + {"authors": ["Strokkur24", "electronicboy"]} + ``` + +- **`dependencies`**\ + Your plugin's dependencies. The value of this field is an array of dependency objects. + + The dependency object itself has two fields: + - `id` the plugin ID of the plugin you depend upon + - `optional` whether the dependency is optional. This field is not required and defaults to `false`. + + ```json + { + "dependencies": [ + { + "id": "luckperms", + "optional": true + } + ] + } + ``` From 958afa45dac3e3cf0374eca52a12615d04c00a85 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Fri, 3 Apr 2026 18:04:01 +0200 Subject: [PATCH 4/6] chore: fix incorrect aside identifier --- .../velocity/dev/getting-started/creating-your-first-plugin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index 4695aad65..b08e251b0 100644 --- a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -57,7 +57,7 @@ How to set up a build system is outside the scope of this page, but you can look system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userguide.html) or [Maven](https://maven.apache.org/guides/getting-started/index.html)) for assistance. -:::info[velocity-plugin.json] +:::note[velocity-plugin.json] Before you set up your build system, you should think about whether you want your `velocity-plugin.json` to be generated automatically using a `@Plugin` annotation in your source code or if you want to write it From 2455466711f0630a99f6f7badc520d904614bf90 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Fri, 3 Apr 2026 18:12:00 +0200 Subject: [PATCH 5/6] chore: remove [] --- .../velocity/dev/getting-started/creating-your-first-plugin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index b08e251b0..c7b27e51b 100644 --- a/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -62,7 +62,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg Before you set up your build system, you should think about whether you want your `velocity-plugin.json` to be generated automatically using a `@Plugin` annotation in your source code or if you want to write it manually. Depending on which you prefer, you may need to add additional lines to your build files. You can find -more information on the [`velocity-plugin.json`] file [here](/velocity/dev/velocity-plugin-json). +more information on the `velocity-plugin.json` file [here](/velocity/dev/velocity-plugin-json). ::: From fbc45ca8e8bf738a44912223c226abd5d7062803 Mon Sep 17 00:00:00 2001 From: Strokkur24 Date: Fri, 3 Apr 2026 18:30:14 +0200 Subject: [PATCH 6/6] chore: replace comments with line markers from EC --- .../dev/getting-started/velocity-plugin-json.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx index 853dadfa6..e86464b26 100644 --- a/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx +++ b/src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx @@ -25,19 +25,21 @@ and used a `@Plugin` annotation somewhere in your code. ## Example This is an example `velocity-plugin.json` file: -```json title=velocity-plugin.json +```json title=velocity-plugin.json {" Required values:":2-4} {" The ID is required. Optional defaults to false:":11-15} { - "id": "example-plugin", // required + + "id": "example-plugin", + "main": "com.example.testplugin.TestPluginMain", "name": "Velocity Example Plugin", "version": "1.0.0", "description": "An example plugin for showcasing the plugin json file.", - "main": "com.example.testplugin.TestPluginMain", // required "url": "https://github.com/PaperMC/docs", "authors": ["Strokkur24"], "dependencies": [ + { - "id": "luckperms", // required for dependencies - "optional": true // defaults to false + "id": "luckperms", + "optional": true } ] }