Skip to content

Commit eb84a7f

Browse files
MC-XiaoHeiMC-XiaoHei
committed
feat: finish velocity part
1 parent b93f2fd commit eb84a7f

File tree

4 files changed

+251
-1
lines changed

4 files changed

+251
-1
lines changed

‎docs/en/velocity/intro.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
order: 1
3+
preferences: ['build-system']
4+
authors:
5+
- JorelAli
6+
- DerEchtePilz
7+
---
8+
9+
# Velocity
10+
11+
:::warning Developer's Note:
12+
13+
The CommandAPI hasn't been released for Velocity yet.
14+
We do, however, offer snapshot builds. This small section on Velocity will outline how to get the snapshot builds and what limitations the CommandAPI currently has on Velocity.
15+
16+
This page focuses on outlining how to set up the CommandAPI for Velocity. It expects that you are already familiar with how to set up a Velocity plugin.
17+
18+
:::
19+
20+
## Adding the snapshot repository with Maven or Gradle
21+
22+
Because we do not have an official release yet, the snapshot builds are not published in the Maven Central repository. Instead you need to add our snapshot repository:
23+
24+
<div class="maven">
25+
26+
```xml
27+
<repositories>
28+
<repository>
29+
<id>oss.sonatype.org-snapshot</id>
30+
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
31+
</repository>
32+
</repositories>
33+
```
34+
35+
</div>
36+
<div class="gradle">
37+
38+
<div class="groovy">
39+
40+
```groovy
41+
repositories {
42+
maven {
43+
url = "https://s01.oss.sonatype.org/content/repositories/snapshots"
44+
}
45+
}
46+
```
47+
48+
</div>
49+
<div class="kts">
50+
51+
```kotlin
52+
repositories {
53+
maven {
54+
url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots")
55+
}
56+
}
57+
```
58+
59+
</div>
60+
61+
</div>
62+
63+
## Adding the dependency
64+
65+
As mentioned, Velocity can only be accessed with snapshot builds. These snapshot build version are following standard semantic versioning and thus have the `-SNAPSHOT` suffix:
66+
67+
<div class="maven">
68+
69+
```xml
70+
<dependencies>
71+
<dependency>
72+
<groupId>dev.jorel</groupId>
73+
<artifactId>commandapi-velocity-shade</artifactId>
74+
<version>9.7.1-SNAPSHOT</version>
75+
</dependency>
76+
</dependencies>
77+
```
78+
79+
</div>
80+
<div class="gradle">
81+
82+
<div class="groovy">
83+
84+
```groovy
85+
dependencies {
86+
implementation "dev.jorel:commandapi-velocity-shade:9.7.1-SNAPSHOT"
87+
}
88+
```
89+
90+
</div>
91+
<div class="kts">
92+
93+
```kotlin
94+
dependencies {
95+
implementation("dev.jorel:commandapi-velocity-shade:9.7.1-SNAPSHOT")
96+
}
97+
```
98+
99+
</div>
100+
101+
</div>
102+
103+
## Setting up the CommandAPI
104+
105+
The CommandAPI requires two steps: loading and enabling. We will perform these steps in Velocity's loading stages, construction and initialization. These two stages are explained in [their documentation](https://docs.papermc.io/velocity/dev/api-basics#a-word-of-caution).
106+
We will perform the CommandAPI's loading step in the construction phase first:
107+
108+
<<< @/../reference-code/src/main/java/velocity/Intro.java#loadCommandAPIExample
109+
110+
Next, we want to utilize Velocity's `ProxyInitializeEvent` to perform the CommandAPI's enabling step:
111+
112+
113+
<<< @/../reference-code/src/main/java/velocity/Intro.java#enableCommandAPIExample
114+
115+
## Current limitations
116+
117+
The CommandAPI currently only offers support for a very limited amount of arguments on Velocity. This is because arguments are primarily implemented on the backend servers.
118+
However, the CommandAPI offers access for the primitive type arguments:
119+
120+
- [`IntegerArgument`](../create-commands/arguments/types/primitive-arguments#numerical-arguments)
121+
- [`LongArgument`](../create-commands/arguments/types/primitive-arguments#numerical-arguments)
122+
- [`FloatArgument`](../create-commands/arguments/types/primitive-arguments#numerical-arguments)
123+
- [`DoubleArgument`](../create-commands/arguments/types/primitive-arguments#numerical-arguments)
124+
- [`BooleanArgument`](../create-commands/arguments/types/primitive-arguments#boolean-arguments)
125+
- [`StringArgument`](../create-commands/arguments/types/string-arguments#string-argument)
126+
- [`TextArgument`](../create-commands/arguments/types/string-arguments#text-argument)
127+
- [`GreedyStringArgument`](../create-commands/arguments/types/string-arguments#greedy-string-argument)
128+
- [`LiteralArgument`](../create-commands/arguments/types/literal/literal-arguments)
129+
- [`MultiLiteralArgument`](../create-commands/arguments/types/literal/multiliteral-arguments)
130+
131+
## Registering a simple command
132+
133+
Command registration works the same way as it does in Bukkit. To visualize this, we want to register a simple command that generates a random number between a chosen minimum and a chosen maximum value:
134+
135+
::::tip Example – Registering a simple command
136+
137+
We want to register the command `/randomnumber` with the following syntax:
138+
139+
```mccmd
140+
/randomnumber <min> <max>
141+
```
142+
143+
To accomplish that, we register the command like this:
144+
145+
:::tabs
146+
===Java
147+
<<< @/../reference-code/src/main/java/velocity/Intro.java#registerCommandExample
148+
===Kotlin
149+
<<< @/../reference-code/src/main/kotlin/velocity/Intro.kt#registerCommandExample
150+
:::
151+
152+
::::

‎reference-code/pom.xml‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
<kotlin.version>2.0.0</kotlin.version>
1919
<paper.version>1.21-R0.1-SNAPSHOT</paper.version>
2020
<commandapi.version>9.7.0</commandapi.version>
21+
<commandapiVelocity.version>9.6.2-SNAPSHOT</commandapiVelocity.version>
2122

2223
</properties>
2324

@@ -35,6 +36,10 @@
3536
<url>https://repo.codemc.org/repository/maven-public/</url>
3637
<layout>default</layout>
3738
</repository>
39+
<repository>
40+
<id>oss.sonatype.org-snapshot</id>
41+
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
42+
</repository>
3843
</repositories>
3944

4045
<build>
@@ -92,6 +97,14 @@
9297
<scope>provided</scope>
9398
</dependency>
9499

100+
<!-- Velocity dependencies -->
101+
<dependency>
102+
<groupId>com.velocitypowered</groupId>
103+
<artifactId>velocity-api</artifactId>
104+
<version>3.4.0-SNAPSHOT</version>
105+
<scope>provided</scope>
106+
</dependency>
107+
95108
<!-- Testing -->
96109
<dependency>
97110
<groupId>org.junit.jupiter</groupId>
@@ -105,11 +118,13 @@
105118
<groupId>dev.jorel</groupId>
106119
<artifactId>commandapi-bukkit-test-toolkit</artifactId>
107120
<version>${commandapi.version}</version>
121+
<scope>test</scope>
108122
</dependency>
109123
<dependency>
110124
<groupId>com.github.seeseemelk</groupId>
111125
<artifactId>MockBukkit-v1.21</artifactId>
112126
<version>3.133.2</version>
127+
<scope>test</scope>
113128
</dependency>
114129

115130
<!-- CommandAPI -->
@@ -127,7 +142,11 @@
127142
<groupId>dev.jorel</groupId>
128143
<artifactId>commandapi-annotations</artifactId>
129144
<version>${commandapi.version}</version>
130-
<scope>provided</scope>
145+
</dependency>
146+
<dependency>
147+
<groupId>dev.jorel</groupId>
148+
<artifactId>commandapi-velocity-shade</artifactId>
149+
<version>${commandapiVelocity.version}</version>
131150
</dependency>
132151

133152
<!-- Other -->

‎reference-code/src/main/java/velocity/Intro.java‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
package velocity;
2+
3+
import com.google.inject.Inject;
4+
import com.velocitypowered.api.event.Subscribe;
5+
import com.velocitypowered.api.event.proxy.ProxyInitializeEvent;
6+
import com.velocitypowered.api.proxy.ProxyServer;
7+
import dev.jorel.commandapi.CommandAPI;
8+
import dev.jorel.commandapi.CommandAPICommand;
9+
import dev.jorel.commandapi.CommandAPIVelocityConfig;
10+
import dev.jorel.commandapi.arguments.IntegerArgument;
11+
import net.kyori.adventure.text.Component;
12+
import org.slf4j.Logger;
13+
14+
import java.util.Random;
15+
import java.util.concurrent.ThreadLocalRandom;
16+
17+
class Intro {
18+
class ExamplePlugin {
19+
private final ProxyServer server;
20+
private final Logger logger;
21+
22+
// #region loadCommandAPIExample
23+
@Inject
24+
public ExamplePlugin(ProxyServer server, Logger logger) {
25+
this.server = server;
26+
this.logger = logger;
27+
28+
CommandAPI.onLoad(new CommandAPIVelocityConfig(server, this));
29+
}
30+
// #endregion loadCommandAPIExample
31+
}
32+
33+
// #region enableCommandAPIExample
34+
@Subscribe
35+
public void onProxyInitialization(ProxyInitializeEvent event) {
36+
// Any CommandAPI command registrations...
37+
CommandAPI.onEnable();
38+
}
39+
// #endregion enableCommandAPIExample
40+
41+
{
42+
// #region registerCommandExample
43+
new CommandAPICommand("randomnumber")
44+
.withArguments(new IntegerArgument("min"))
45+
.withArguments(new IntegerArgument("max"))
46+
.executesPlayer((player, args) -> {
47+
int min = (int) args.get("min");
48+
int max = (int) args.get("max");
49+
Random random = ThreadLocalRandom.current();
50+
int randomNumber = random.nextInt(min, max);
51+
player.sendMessage(Component.text().content("Your random number is: " + randomNumber));
52+
})
53+
.register();
54+
// #endregion registerCommandExample
55+
}
56+
}

‎reference-code/src/main/kotlin/velocity/Intro.kt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package velocity
2+
3+
import dev.jorel.commandapi.CommandAPICommand
4+
import dev.jorel.commandapi.arguments.IntegerArgument
5+
import dev.jorel.commandapi.executors.PlayerCommandExecutor
6+
import net.kyori.adventure.text.Component
7+
import java.util.concurrent.ThreadLocalRandom
8+
9+
fun intro() {
10+
// #region registerCommandExample
11+
CommandAPICommand("randomnumber")
12+
.withArguments(IntegerArgument("min"))
13+
.withArguments(IntegerArgument("max"))
14+
.executesPlayer(PlayerCommandExecutor { player, args ->
15+
val min = args["min"] as Int
16+
val max = args["max"] as Int
17+
val random = ThreadLocalRandom.current()
18+
val randomNumber = random.nextInt(min, max)
19+
player.sendMessage(Component.text().content("Your random number is: $randomNumber"))
20+
})
21+
.register()
22+
// #endregion registerCommandExample
23+
}

0 commit comments

Comments
 (0)