Velocity

https://docs.papermc.io/velocity/
Admin
Velocity is a ridiculously scalable, flexible, and high-performance Minecraft proxy with advanced...
Tokens:29,580
Snippets:283
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example velocity-plugin.json

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

A complete example of a velocity-plugin.json file showing all fields: id, main, name, version, description, url, authors, dependencies, and provides.

```json
{


  "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.",
  "url": "https://github.com/PaperMC/docs",
  "authors": ["Strokkur24"],
  "dependencies": [


    {
      "id": "luckperms",
      "optional": true
    }
  ],
  "provides": ["other-plugin"]
}
```

--------------------------------

### version field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional version field for your plugin.

```json
{"version": "0.0.1-beta.7"}
```

--------------------------------

### Velocity startup console output

Source: https://docs.papermc.io/velocity/getting-started

Sample console output after starting the Velocity proxy, showing successful boot and listening on port 25565.

```text
[05:41:13 INFO]: Booting up Velocity 4.2.1-SNAPSHOT (git-74c932e5-b363)...
[05:41:13 INFO]: Loading localizations...
[05:41:13 INFO]: Connections will use epoll channels, libdeflate (Linux aarch64) compression, OpenSSL (Linux aarch64) ciphers
[05:41:13 INFO]: Loading plugins...
[05:41:13 INFO]: Loaded 0 plugins
[05:41:13 INFO]: Listening on /[0:0:0:0:0:0:0:0%0]:25565
[05:41:13 INFO]: Done (0.36s)!
```

--------------------------------

### description field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional description field for your plugin.

```json
{"description": "Some interesting plugin description."}
```

--------------------------------

### main field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the required main field, which is the path to your main plugin class.

```json
{"main": "com.example.yourplugin.PluginMain"}
```

--------------------------------

### id field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the required id field. Plugin IDs must start with a lowercase letter and may contain lowercase letters, digits, hyphens, and underscores. Total length must not exceed 64 characters.

```json
{"id": "a_cool_plugin"}
```

--------------------------------

### url field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional url field for your plugin's website.

```json
{"url": "https://github.com/PaperMC/Velocity"}
```

--------------------------------

### Velocity @Plugin and @Dependency variants

Source: https://docs.papermc.io/velocity/dev/dependency-management

Three annotated Velocity plugin examples show the base @Plugin declaration, the same declaration with a required @Dependency, and a version where the dependency is optional via `optional = true`. They appear consecutively in the dependency management section and are the only code examples on the page.

```java
@Plugin(
  id = "myfirstplugin",
  name = "My Plugin",
  version = "0.1.0"
)
public class VelocityTest {
  // ...
}
```

```java
@Plugin(
  id = "myfirstplugin",
  name = "My Plugin",
  version = "0.1.0",
  dependencies = {
    @Dependency(id = "wonderplugin")
  }
)
public class VelocityTest {
  // ...
}
```

```java
@Plugin(
  id = "myfirstplugin",
  name = "My Plugin",
  version = "0.1.0",
  dependencies = {
    @Dependency(id = "wonderplugin", optional = true)
  }
)
public class VelocityTest {
  // ...
}
```

--------------------------------

### dependencies field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional dependencies field. The value is an array of dependency objects with id and optional fields. The optional field defaults to false.

```json
{
  "dependencies": [
    {
      "id": "luckperms",
      "optional": true
    }
  ]
}
```

--------------------------------

### Recommended Velocity startup flags

Source: https://docs.papermc.io/velocity/tuning

Add these flags after the `java` command but before the `-jar` parameter. They tune the G1 garbage collector for Velocity's workload and include `-XX:MaxInlineLevel=15` for general performance improvement. Setups using these flags tend to have very low (less than 10 millisecond) GC pauses every few minutes.

```bash
-XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15
```

--------------------------------

### name field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional name field, a user-friendly variant of your plugin's name used for user-facing displays such as the /velocity plugins command.

```json
{"name": "A cool plugin"}
```

--------------------------------

### authors field example

Source: https://docs.papermc.io/velocity/dev/velocity-plugin-json

Shows the optional authors field, a list of your plugin's authors.

```json
{"authors": ["Strokkur24", "electronicboy"]}
```

--------------------------------

### Set Velocity system property via command line

Source: https://docs.papermc.io/velocity/reference/system-properties

Use this command to start the Velocity server with a system property, such as enabling packet decode logging. In PowerShell, wrap the -D argument in quotes because the property name contains a dot.

```bash
java -Dvelocity.packet-decode-logging=true -jar velocity.jar
```

--------------------------------

### Gradle (Kotlin) dependency setup for Velocity API

Source: https://docs.papermc.io/velocity/dev/creating-your-first-plugin

Gradle Kotlin DSL configuration to add the PaperMC repository and the Velocity API dependency. The annotationProcessor line is optional and only needed if you want the velocity-plugin.json file to be generated from @Plugin annotations.

```kotlin
repositories {
  maven(url = "https://repo.papermc.io/repository/maven-public/") {
    name = "papermc"
  }
}


dependencies {
  compileOnly("com.velocitypowered:velocity-api:4.2.1-SNAPSHOT")
  // If you want your velocity-plugin.json file to be generated based on plugin annotations
  annotationProcessor("com.velocitypowered:velocity-api:4.2.1-SNAPSHOT")
}

```

--------------------------------

### Gradle (Groovy) dependency setup for Velocity API

Source: https://docs.papermc.io/velocity/dev/creating-your-first-plugin

Gradle Groovy DSL configuration to add the PaperMC repository and the Velocity API dependency. The annotationProcessor line is optional and only needed if you want the velocity-plugin.json file to be generated from @Plugin annotations.

```groovy
repositories {
  maven {
    name = 'papermc'
    url = 'https://repo.papermc.io/repository/maven-public/'
  }
}


dependencies {
  compileOnly 'com.velocitypowered:velocity-api:4.2.1-SNAPSHOT'
  // If you want your velocity-plugin.json file to be generated based on plugin annotations
  annotationProcessor 'com.velocitypowered:velocity-api:4.2.1-SNAPSHOT'
}

```

--------------------------------

### Get all tasks scheduled by a plugin with tasksByPlugin(Object)

Source: https://docs.papermc.io/velocity/dev/scheduler-api

Retrieves all tasks scheduled by a plugin as a Collection<ScheduledTask>. The example iterates and cancels each task.

```java
Collection<ScheduledTask> tasks = server.getScheduler().tasksByPlugin(plugin);
// then you can control them, for example, cancel all task scheduled by a plugin
for (ScheduledTask task : tasks) {
  task.cancel();
}

```

--------------------------------

### Create a Velocity BrigadierCommand with argument and suggestions

Source: https://docs.papermc.io/velocity/dev/command-api

Creates a Velocity BrigadierCommand named "test" with a permission check, a no-argument execution that sends "Hello World", and an optional string argument with player-name suggestions and tooltips. Requires the Velocity API, Brigadier, and Adventure components; returns Command.SINGLE_SUCCESS on success or BrigadierCommand.FORWARD to forward to the server.

```java
package com.example.velocityplugin;

import com.mojang.brigadier.arguments.StringArgumentType;
import com.mojang.brigadier.Command;
import com.mojang.brigadier.tree.LiteralCommandNode;
import com.velocitypowered.api.command.BrigadierCommand;
import com.velocitypowered.api.command.CommandSource;
import com.velocitypowered.api.command.VelocityBrigadierMessage;
import com.velocitypowered.api.proxy.ProxyServer;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public final class TestBrigadierCommand {

  public static BrigadierCommand createBrigadierCommand(final ProxyServer proxy) {
    LiteralCommandNode<CommandSource> helloNode = BrigadierCommand.literalArgumentBuilder("test")
      // Here you can filter the subjects that can execute the command.
      // This is the ideal place to do "hasPermission" checks
      .requires(source -> source.hasPermission("test.permission"))
      // Here you can add the logic that will be used in
      // the execution of the "/test" command without any argument
      .executes(context -> {
        // Here you get the subject that executed the command
        CommandSource source = context.getSource();

        Component message = Component.text("Hello World", NamedTextColor.AQUA);
        source.sendMessage(message);

        // Returning Command.SINGLE_SUCCESS means that the execution was successful
        // Returning BrigadierCommand.FORWARD will send the command to the server
        return Command.SINGLE_SUCCESS;
      })
      // Using the "then" method, you can add sub-arguments to the command.
      // For example, this subcommand will be executed when using the command "/test <some argument>"
      // A RequiredArgumentBuilder is a type of argument in which you can enter some undefined data
      // of some kind. For example, this example uses a StringArgumentType.word() that requires
      // a single word to be entered, but you can also use different ArgumentTypes provided by Brigadier
      // that return data of type Boolean, Integer, Float, other String types, etc
      .then(BrigadierCommand.requiredArgumentBuilder("argument", StringArgumentType.word())
        // Here you can define the hints to be provided in case the ArgumentType does not provide them.
        // In this example, the names of all connected players are provided
        .suggests((context, builder) -> {
          // Here we provide the names of the players along with a tooltip,
          // which can be used as an explanation of a specific argument or as a simple decoration
          proxy.getAllPlayers().forEach(player -> builder.suggest(
              player.getUsername(),
              // A VelocityBrigadierMessage takes a component.
              // In this case, the player's name is provided with a rainbow
              // gradient created using MiniMessage.
              VelocityBrigadierMessage.tooltip(
                  MiniMessage.miniMessage().deserialize("<rainbow>" + player.getUsername())
              )
          ));
          // If you do not need to add a tooltip to the hint
          // or your command is intended only for versions lower than Minecraft 1.13,
          // you can omit adding the tooltip, since for older clients,
          // the tooltip will not be displayed.
          builder.suggest("all");
          return builder.buildFuture();
        })
        // Here the logic of the command "/test <some argument>" is executed
        .executes(context -> {
          // Here you get the argument that the CommandSource has entered.
          // You must enter exactly the name as you have named the argument
          // and you must provide the class of the argument you expect, in this case... a String
          String argumentProvided = context.getArgument("argument", String.class);
          // This method will check if the given string corresponds to a
          // player's name and if it does, it will send a message to that player
          proxy.getPlayer(argumentProvided).ifPresent(player ->
            player.sendMessage(Component.text("Hello!"))
          );
          // Returning Command.SINGLE_SUCCESS means that the execution was successful
          // Returning BrigadierCommand.FORWARD will send the command to the server
          return Command.SINGLE_SUCCESS;
        })
      )
      .build();

    // BrigadierCommand implements Command
    return new BrigadierCommand(helloNode);
  }
}
```

--------------------------------

### Implement SimpleCommand with permission and suggestions

Source: https://docs.papermc.io/velocity/dev/command-api

Implements the SimpleCommand interface with execute, hasPermission, suggest, and suggestAsync methods. Note that invocation.arguments() excludes the command alias and returns an empty array when no arguments are given. The hasPermission method controls execution and autocompletion; if permission is denied, both are delegated to the server.

```java
package com.example.velocityplugin;

import com.velocitypowered.api.command.CommandSource;
import com.velocitypowered.api.command.SimpleCommand;
import java.util.concurrent.CompletableFuture;
import java.util.List;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public final class TestCommand implements SimpleCommand {

  @Override
  public void execute(final Invocation invocation) {
    CommandSource source = invocation.source();
    // Get the arguments after the command alias
    String[] args = invocation.arguments();

    source.sendMessage(Component.text("Hello World!", NamedTextColor.AQUA));
  }

  // This method allows you to control who can execute the command.
  // If the executor does not have the required permission,
  // the execution of the command and the control of its autocompletion
  // will be sent directly to the server on which the sender is located
  @Override
  public boolean hasPermission(final Invocation invocation) {
    return invocation.source().hasPermission("command.test");
  }

  // With this method you can control the suggestions to send
  // to the CommandSource according to the arguments
  // it has already written or other requirements you need
  @Override
  public List<String> suggest(final Invocation invocation) {
    return List.of();
  }

  // Here you can offer argument suggestions in the same way as the previous method,
  // but asynchronously. It is recommended to use this method instead of the previous one
  // especially in cases where you make a more extensive logic to provide the suggestions
  @Override
  public CompletableFuture<List<String>> suggestAsync(final Invocation invocation) {
    return CompletableFuture.completedFuture(List.of());
  }
}
```

--------------------------------

### velocity.toml [servers] configuration

Source: https://docs.papermc.io/velocity/getting-started

Initial [servers] section of velocity.toml, listing server names and addresses, plus the 'try' list that determines connection order on login or kick.

```toml
[servers]
# Configure your servers here. Each key represents the server's name, and the value
# represents the IP address of the server to connect to.
lobby = "127.0.0.1:30066"
factions = "127.0.0.1:30067"
minigames = "127.0.0.1:30068"


# In what order we should try servers when a player logs in or is kicked from a server.
try = [
  "lobby",
  "factions"
]
```

--------------------------------

### Create start.sh to launch Velocity on macOS or Linux

Source: https://docs.papermc.io/velocity/getting-started

Unix shell script that launches Velocity with a fixed memory allocation and JVM tuning flags. Requires Java 25 and must be saved in the same directory as the Velocity JAR; the wildcard 'velocity*.jar' matches the downloaded JAR. Before running, execute 'chmod u+x start.sh' to make the script executable, then run './start.sh'.

```bash
#!/bin/sh


java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity*.jar

```

--------------------------------

### Create start.bat to launch Velocity on Windows

Source: https://docs.papermc.io/velocity/getting-started

Windows batch script that launches Velocity with a fixed memory allocation and JVM tuning flags. Requires Java 25 and must be saved in the same directory as the Velocity JAR; change 'velocity.jar' to match your downloaded JAR or rename the file to 'velocity.jar'. After saving, double-click 'start.bat' to run it.

```bat
@echo off
java -Xms1G -Xmx1G -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -XX:MaxInlineLevel=15 -jar velocity.jar
pause

```

--------------------------------

### Cancel a scheduled task and check its status

Source: https://docs.papermc.io/velocity/dev/scheduler-api

The schedule() method returns a ScheduledTask. Use cancel() to cancel the task (cannot be uncancelled) and status() to get its current status.

```java
ScheduledTask task = server.getScheduler()
  .buildTask(plugin, () -> {
    // do stuff here
  })
  .repeat(5L, TimeUnit.MINUTES)
  .schedule();
// ...
task.cancel();
// ...
System.out.println(task.status());

```

--------------------------------

### Register a command with CommandManager in Velocity plugin

Source: https://docs.papermc.io/velocity/dev/command-api

Shows the main plugin class that injects ProxyServer, builds CommandMeta with aliases and plugin ownership, and registers a BrigadierCommand. The comment indicates SimpleCommand and RawCommand can be registered similarly since all implement Command.

```java
package com.example.velocityplugin;

import com.google.inject.Inject;
import com.velocitypowered.api.command.BrigadierCommand;
import com.velocitypowered.api.event.Subscribe;
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
import com.velocitypowered.api.plugin.Plugin;
import com.velocitypowered.api.proxy.ProxyServer;

@Plugin(id = "helloworld")
public final class HelloWorldPlugin {
  private final ProxyServer proxy;

  @Inject
  public HelloWorldPlugin(ProxyServer proxy) {
    this.proxy = proxy;
  }

  @Subscribe
  public void onProxyInitialize(ProxyInitializeEvent event) {
    CommandManager commandManager = proxy.getCommandManager();
    // Here you can add meta for the command, as aliases and the plugin to which it belongs (RECOMMENDED)
    CommandMeta commandMeta = commandManager.metaBuilder("test")
      // This will create a new alias for the command "/test"
      // with the same arguments and functionality
      .aliases("otherAlias", "anotherAlias")
      .plugin(this)
      .build();

    // You can replace this with "new EchoCommand()" or "new TestCommand()"
    // SimpleCommand simpleCommand = new TestCommand();
    // RawCommand rawCommand = new EchoCommand();
    // The registration is done in the same way, since all 3 interfaces implement "Command"
    BrigadierCommand commandToRegister = TestBrigadierCommand.createBrigadierCommand(proxy);

    // Finally, you can register the command
    commandManager.register(commandMeta, commandToRegister);
  }
}
```

--------------------------------

### Schedule a self-cancelling task with Consumer<ScheduledTask>

Source: https://docs.papermc.io/velocity/dev/scheduler-api

Uses a Consumer<ScheduledTask> to create a task that can cancel itself. The example cancels after the counter exceeds 10, using repeat(Duration.ofSeconds(4L)).

```java
AtomicInteger integer = new AtomicInteger(0);


ScheduledTask task = server.getScheduler()
  .buildTask(plugin, (selfTask) -> {
    // do stuff here, for example...
    if (integer.addAndGet(1) > 10) {
      selfTask.cancel();
    }
  })
  .repeat(Duration.ofSeconds(4L))
  .schedule();

```

--------------------------------

### SimpleCommand

Source: https://docs.papermc.io/velocity/dev/command-api

Documentation for the SimpleCommand interface in Velocity, including its methods and invocation object.

```APIDOC
## SimpleCommand

### Description
Implements a command using the SimpleCommand interface, modeled after Bukkit and BungeeCord conventions. Provides methods for execution, permission checking, and tab completion suggestions.

### Interface
`com.velocitypowered.api.command.SimpleCommand`

### Methods
- **execute(Invocation invocation)** - Called when the command is executed. The invocation contains the CommandSource and arguments array.
- **hasPermission(Invocation invocation)** - Returns a boolean indicating whether the CommandSource has permission to execute the command. If false, execution and autocompletion are delegated to the server.
- **suggest(Invocation invocation)** - Returns a List<String> of tab completion suggestions based on the arguments.
- **suggestAsync(Invocation invocation)** - Returns a CompletableFuture<List<String>> for asynchronous suggestion generation. Recommended for complex suggestion logic.

### Invocation Object
- **source()** - Returns the CommandSource that executed the command.
- **arguments()** - Returns an array of strings containing the arguments after the command alias. Does not include the alias. Returns an empty array if no arguments are specified.

### Example
```java
public final class TestCommand implements SimpleCommand {
  @Override
  public void execute(final Invocation invocation) {
    CommandSource source = invocation.source();
    String[] args = invocation.arguments();
    source.sendMessage(Component.text("Hello World!", NamedTextColor.AQUA));
  }

  @Override
  public boolean hasPermission(final Invocation invocation) {
    return invocation.source().hasPermission("command.test");
  }

  @Override
  public List<String> suggest(final Invocation invocation) {
    return List.of();
  }

  @Override
  public CompletableFuture<List<String>> suggestAsync(final Invocation invocation) {
    return CompletableFuture.completedFuture(List.of());
  }
}
```

### Notes
- `invocation.arguments()` does not include the command alias. For `/stats Player2 kills`, arguments[0] is `Player2` and arguments[1] is `kills`.
```

--------------------------------

### Velocity plugin annotation with id and metadata

Source: https://docs.papermc.io/velocity/dev/api-basics

The @Plugin annotation tells Velocity that this class contains the plugin and that it should be loaded when the proxy starts. The id field is used to identify the plugin.

```java
@Plugin(id = "myfirstplugin", name = "My First Plugin", version = "0.1.0-SNAPSHOT",
        url = "awesome.org", description = "I did it!", authors = {"Me"})
public class VelocityTest {
```

--------------------------------

### Fire an event with server.getEventManager().fire()

Source: https://docs.papermc.io/velocity/dev/event-api

Fires the event using the server's event manager. The fire method returns a CompletableFuture, so use thenAccept to continue logic after all listeners have handled the event.

```java
server.getEventManager().fire(new PrivateMessageEvent(sender, recipient, message)).thenAccept((event) -> {
  // event has finished firing
  // do some logic dependent on the result
});
```

--------------------------------

### Register a separate listener class with EventManager

Source: https://docs.papermc.io/velocity/dev/event-api

Example of registering a separate listener class from the main plugin class. The main class is automatically registered, but additional listeners must be registered manually with the EventManager.

```java
@Plugin(id = "myfirstplugin", name = "My Plugin", version = "0.1.0", dependencies = {@Dependency(id = "wonderplugin")})
public class VelocityTest {


  private final ProxyServer server;
  private final Logger logger;


  @Inject
  public VelocityTest(ProxyServer server, Logger logger) {
    this.server = server;
    this.logger = logger;
  }


  @Subscribe
  public void onInitialize(ProxyInitializeEvent event) {
    server.getEventManager().register(this, new MyListener());
  }
}


public class MyListener {


  @Subscribe
  public void onPlayerChat(PlayerChatEvent event) {
    // do something here
  }


}

```

--------------------------------

### Maven 4+ dependency setup for Velocity API

Source: https://docs.papermc.io/velocity/dev/creating-your-first-plugin

Maven 4+ pom.xml configuration with the PaperMC repository and the Velocity API dependency. The processor dependency is optional and only needed if you want the velocity-plugin.json file to be generated from @Plugin annotations.

```xml
<project>
  <repositories>
    <repository>
      <id>papermc</id>
      <url>https://repo.papermc.io/repository/maven-public/</url>
    </repository>
  </repositories>


  <dependencies>
    <dependency>
      <groupId>com.velocitypowered</groupId>
      <artifactId>velocity-api</artifactId>
      <version>4.2.1-SNAPSHOT</version>
      <scope>provided</scope>
    </dependency>
    <!-- add the annotation processor if you want your velocity-plugin.json file to be generated -->
    <dependency>
      <groupId>com.velocitypowered</groupId>
      <artifactId>velocity-api</artifactId>
      <version>4.2.1-SNAPSHOT</version>
      <type>processor</type>
    </dependency>
  </dependencies>
</project>

```

--------------------------------

### Implement RawCommand to echo raw arguments

Source: https://docs.papermc.io/velocity/dev/command-api

Implements the RawCommand interface to pass the command alias and arguments directly without processing. Useful for /say-style commands or when using an external command framework. The execute method echoes the raw arguments back to the source.

```java
package com.example.velocityplugin;

import com.velocitypowered.api.command.RawCommand;
import net.kyori.adventure.text.Component;

public final class EchoCommand implements RawCommand {

  @Override
  public void execute(final Invocation invocation) {
    invocation.source().sendMessage(Component.text(invocation.arguments()));
  }

  @Override
  public boolean hasPermission(final Invocation invocation) {
    return invocation.source().hasPermission("command.echo");
  }
}
```

--------------------------------

### Player information forwarding error messages

Source: https://docs.papermc.io/velocity/faq

Error messages shown when player information forwarding is misconfigured. The first two indicate improper forwarding setup; the third indicates Velocity modern forwarding is enabled on the backend but not on the proxy.

```text
Can't connect to server lobby: If you wish to use IP forwarding, please enable it in your Bungeecord config as well!
```

```text
Can't connect to server lobby: Your server did not send a forwarding request to the proxy. Is it set up correctly?
```

```text
Can't connect to server lobby: This server requires you to connect with Velocity.
```
Tokens:
Raw