You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/create-commands/arguments/types/entities-arguments.md
+30-16Lines changed: 30 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,23 +79,32 @@ We could then use this to target specific entities, for example:
79
79
80
80
::::
81
81
82
-
## Player argument
82
+
## PlayerProfile argument
83
83
84
-
The `PlayerArgument` class is very similar _(almost identical)_ to`EntitySelectorArgument.OnePlayer`. It returns a `Player` object and requires the player to be online.
84
+
The `PlayerProfileArgument` can serve a similar purpose as the`EntitySelectorArgument.OnePlayer` or `EntitySelectorArgument.ManyPlayers` if you only reference online players, but it can also be used to reference players that are offline or have never logged into your server.
85
85
86
-
:::info
87
-
The `PlayerArgument` internally uses the `GameProfile` class from Mojang's authlib, which means that this argument has a slight performance overhead compared to using `EntitySelectorArgument.OnePlayer`
88
-
:::
86
+
Because of this, it has a performance overhead even when the input is an online player or an entity selector.
87
+
88
+
<divclass="paper">
89
+
90
+
The `PlayerProfileArgument` returns a `List<com.destroystokyo.paper.profile.PlayerProfile>`.
91
+
92
+
</div>
93
+
<divclass="spigot">
94
+
95
+
The `PlayerProfileArgument` returns a `List<org.bukkit.profile.PlayerProfile>`.
89
96
90
-
::::tip Example – PlayerArgument without entity selectors
97
+
</div>
98
+
99
+
::::tip Example – PlayerProfileArgument without entity selectors
91
100
92
-
When registering a `PlayerArgument` you might notice that it includes `Entity Selectors` (`@a`, `@e`, `@r`, etc.). If you want to avoid those, you can use argument suggestions to only suggest the player names. For this example, let us create a /warp command:
101
+
When registering a `PlayerProfileArgument` you might notice that it includes `Entity Selectors` (`@a`, `@e`, `@r`, etc.). If you want to avoid those, you can use argument suggestions to only suggest the player names. For this example, let us create a /warp command:
93
102
94
103
```mccmd
95
104
/warp <player>
96
105
```
97
106
98
-
To get a `PlayerArgument` which only suggests the actual names, we can define it like this:
107
+
To get a `PlayerProfileArgument` which only suggests the actual names, we can define it like this:
99
108
100
109
<divclass="paper">
101
110
@@ -146,29 +155,34 @@ And there we have it! One thing to note is that entity selectors are still a val
146
155
147
156
::::
148
157
149
-
## OfflinePlayer argument
158
+
## AsyncPlayerProfile argument
150
159
151
-
The `OfflinePlayerArgument` class is identical to the `PlayerArgument` class, but instead of returning a `Player` object, it returns an `OfflinePlayer` object. Internally, this argument makes calls to Mojang servers (via Mojang's authlib), meaning it can be slightly slower than alternative methods such as using a `AsyncOfflinePlayerArgument`, which runs the API call asynchronously, or using a `StringArgument` and suggesting a list of existing offline players.
160
+
The `AsyncPlayerProfileArgument` class is identical to the `PlayerProfileArgument` class, but instead of making the API call synchronously, it makes the API call asynchronously. This means that the command will not block the main thread while waiting for the API call to complete.
152
161
153
-
The `OfflinePlayerArgument`_should_ be able to retrieve players that have never joined the server before.
162
+
<divclass="paper">
154
163
155
-
## AsyncOfflinePlayer argument
164
+
:::info
165
+
The `AsyncPlayerProfileArgument` returns a `CompletableFuture<List<com.destroystokyo.paper.profile.PlayerProfile>>` object, which can be used to retrieve the `List<com.destroystokyo.paper.profile.PlayerProfile>` object when the API call is complete.
166
+
:::
156
167
157
-
The `AsyncOfflinePlayerArgument` class is identical to the `OfflinePlayerArgument` class, but instead of making the API call synchronously, it makes the API call asynchronously. This means that the command will not block the main thread while waiting for the API call to complete.
168
+
</div>
169
+
<divclass="spigot">
158
170
159
171
:::info
160
-
The `AsyncOfflinePlayerArgument` returns a `CompletableFuture<OfflinePlayer>` object, which can be used to retrieve the `OfflinePlayer` object when the API call is complete.
172
+
The `AsyncPlayerProfileArgument` returns a `CompletableFuture<List<org.bukkit.profile.PlayerProfile>>` object, which can be used to retrieve the `List<org.bukkit.profile.PlayerProfile>` object when the API call is complete.
161
173
:::
162
174
175
+
</div>
176
+
163
177
::::tip Example - Checking if a player has joined before
164
178
165
-
Say we want to create a command that tells us if a player has joined the server before. We can use the `AsyncOfflinePlayerArgument` to fetch the `OfflinePlayer` object asynchronously. That way we simply wait for the request to complete, and once it does, we can check if the player has joined the server before. We want to create a command of the following form:
179
+
Say we want to create a command that tells us if a player has joined the server before. We can use the `AsyncPlayerProfileArgument` to fetch the `List<PlayerProfile>` object asynchronously. That way we simply wait for the request to complete, and once it does, we can check if the player has joined the server before. We want to create a command of the following form:
166
180
167
181
```mccmd
168
182
/playedbefore <player>
169
183
```
170
184
171
-
We now want to get the `CompletableFuture<OfflinePlayer>` object from the `AsyncOfflinePlayerArgument` and then use it to get the `OfflinePlayer` object. We can define it like this:
185
+
We now want to get the `CompletableFuture<List<PlayerProfile>>` object from the `AsyncPlayerProfileArgument` and then use it to get the `List<PlayerProfile>` object. We can define it like this:
0 commit comments