Skip to content

Commit 9702e7d

Browse files
JorelAliJorelAli
committed
Adds new particle argument documentation
1 parent 59c2c5c commit 9702e7d

File tree

10 files changed

+249
-31
lines changed

10 files changed

+249
-31
lines changed

‎docssrc/src/SUMMARY.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,9 @@
6969
- [LootTable argument](./argument_loottable.md)
7070
- [MathOperation arguments](./argument_mathoperation.md)
7171
- [NamespacedKey arguments](./argument_namespacedkey.md)
72-
- [Particle arguments](./argument_particle.md)
72+
- [Particle arguments](./argument_particles.md)
73+
- [Particle data (before 1.20.5)](./argument_particle_old.md)
74+
- [Particle data (1.20.5+)](./argument_particle_new.md)
7375
- [Potion effect arguments](./argument_potion.md)
7476
- [Recipe arguments](./argument_recipe.md)
7577
- [Sound arguments](./argument_sound.md)

‎docssrc/src/argument_particle_new.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Particle data (1.20.5+)
2+
3+
The particle argument requires additional data for a particle depending on what the particle is. The following particles have additional data required to display them:
4+
5+
<!-- To whoever has to maintain this block, I am sorry! - Skepter -->
6+
7+
<table class="table-wrapper">
8+
<thead>
9+
<tr>
10+
<th>Bukkit Particle</th>
11+
<th>Argument syntax</th>
12+
</tr>
13+
</thead>
14+
<tr>
15+
<td><code>BLOCK</code></td>
16+
<td>
17+
<pre>block{block_state:{Name:<b>"block_name"</b>}}</pre>
18+
<ul style="padding-left: 1.5em;">
19+
<li><b><code>block_name</code></b> - name of a block, such as <code>diamond_block</code></li>
20+
</ul>
21+
</td>
22+
</tr>
23+
<tr>
24+
<td><code>BLOCK_MARKER</code></td>
25+
<td>
26+
<pre>block_marker{block_state:{Name:<b>"block_name"</b>}}</pre>
27+
<ul style="padding-left: 1.5em;">
28+
<li><b><code>block_name</code></b> - name of a block, such as <code>diamond_block</code></li>
29+
</ul>
30+
</td>
31+
</tr>
32+
<tr>
33+
<td><code>DUST</code></td>
34+
<td>
35+
<pre>dust{color:[<b>red</b>,<b>green</b>,<b>blue</b>],scale:<b>scale</b>}</pre>
36+
<ul style="padding-left: 1.5em;">
37+
<li><b><code>red</code></b> - number for red, between 0.0 and 1.0</li>
38+
<li><b><code>green</code></b> - number for green, between 0.0 and 1.0</li>
39+
<li><b><code>blue</code></b> - number for blue, between 0.0 and 1.0</li>
40+
<li><b><code>scale</code></b> - number for the size of the particle</li>
41+
</ul>
42+
</td>
43+
</tr>
44+
<tr>
45+
<td><code>DUST_COLOR_TRANSITION</code></td>
46+
<td>
47+
<pre>dust_color_transition{from_color:[<b>red</b>,<b>green</b>,<b>blue</b>],<br>scale:<b>scale</b>,to_color:[<b>red</b>,<b>green</b>,<b>blue</b>]}</pre>
48+
<ul style="padding-left: 1.5em;">
49+
<li><b><code>red</code></b> - number for red, between 0.0 and 1.0</li>
50+
<li><b><code>green</code></b> - number for green, between 0.0 and 1.0</li>
51+
<li><b><code>blue</code></b> - number for blue, between 0.0 and 1.0</li>
52+
<li><b><code>scale</code></b> - number for the size of the particle</li>
53+
</ul>
54+
</td>
55+
</tr>
56+
<tr>
57+
<td><code>DUST_PILLAR</code></td>
58+
<td>
59+
<pre>dust_pillar{block_state:{Name:<b>"block_name"</b>}}</pre>
60+
<ul style="padding-left: 1.5em;">
61+
<li><b><code>block_name</code></b> - name of a block, such as <code>diamond_block</code></li>
62+
</ul>
63+
</td>
64+
</tr>
65+
<tr>
66+
<td><code>ENTITY_EFFECT</code></td>
67+
<td>
68+
<pre>entity_effect{color:[<b>red</b>,<b>green</b>,<b>blue</b>,<b>alpha</b>]}</pre>
69+
<ul style="padding-left: 1.5em;">
70+
<li><b><code>red</code></b> - number for red, between 0.0 and 1.0</li>
71+
<li><b><code>green</code></b> - number for green, between 0.0 and 1.0</li>
72+
<li><b><code>blue</code></b> - number for blue, between 0.0 and 1.0</li>
73+
<li><b><code>alpha</code></b> - number for transparency, between 0.0 and 1.0</li>
74+
</ul>
75+
</td>
76+
</tr>
77+
<tr>
78+
<td><code>FALLING_DUST</code></td>
79+
<td>
80+
<pre>falling_dust{block_state:{Name:<b>"block_name"</b>}}</pre>
81+
<ul style="padding-left: 1.5em;">
82+
<li><b><code>block_name</code></b> - name of a block, such as <code>diamond_block</code></li>
83+
</ul>
84+
</td>
85+
</tr>
86+
<tr>
87+
<td><code>ITEM</code></td>
88+
<td>
89+
<pre>item{item:"<b>item</b>"}</pre>
90+
<ul style="padding-left: 1.5em;">
91+
<li><b><code>item</code></b> - name of an item, such as <code>apple</code></li>
92+
</ul>
93+
</td>
94+
</tr>
95+
<tr>
96+
<td><code>SCULK_CHARGE</code></td>
97+
<td>
98+
<pre>sculk_charge{roll:<b>angle</b>}</pre>
99+
<ul style="padding-left: 1.5em;">
100+
<li><b><code>angle</code></b> - decimal angle the particle displays at in radians</li>
101+
</ul>
102+
</td>
103+
</tr>
104+
<tr>
105+
<td><code>SHRIEK</code></td>
106+
<td>
107+
<pre>shriek{delay:<b>delay</b>}</pre>
108+
<ul style="padding-left: 1.5em;">
109+
<li><b><code>delay</code></b> - delay in ticks for when the shriek particle should appear</li>
110+
</ul>
111+
</td>
112+
</tr>
113+
<tr>
114+
<td><code>VIBRATION</code></td>
115+
<td>
116+
<pre>vibration{destination:{type:"block",pos:[<b>x</b>,<b>y</b>,<b>z</b>]},<br>arrival_in_ticks:<b>ticks</b>}</pre>
117+
<ul style="padding-left: 1.5em;">
118+
<li><b><code>x</code></b> - decimal x-coordinate to move towards</li>
119+
<li><b><code>y</code></b> - decimal y-coordinate to move towards</li>
120+
<li><b><code>z</code></b> - decimal z-coordinate to move towards</li>
121+
<li><b><code>ticks</code></b> - time in ticks to take to move towards its destination</li>
122+
</ul>
123+
</td>
124+
</tr>
125+
</table>
126+
127+
## ParticleArgument examples
128+
129+
Because certain particles (in the table above) require additional data, it is not recommended to spawn a particle without its corresponding data. This can result in particles not showing due to missing requirements.
130+
131+
<div class="warning">
132+
133+
### Example - Show particles at a player's location (without data)
134+
135+
Say we wanted to have a command that displayed particles at a player's location. We will use the following command syntax:
136+
137+
```mccmd
138+
/showparticle <particle>
139+
```
140+
141+
With this, we can simply spawn the particle using the `World.spawnParticle(Particle, Location, int)` method:
142+
143+
<div class="multi-pre">
144+
145+
```java,Java
146+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentParticle1}}
147+
```
148+
149+
```kotlin,Kotlin
150+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentParticle1}}
151+
```
152+
153+
```kotlin,Kotlin_DSL
154+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentParticle1}}
155+
```
156+
157+
</div>
158+
159+
Running this can result in errors due to missing requirements. If you provide a particle that has additional requirements, Bukkit will throw an error and the particle will not be displayed. Instead, the example below should be used.
160+
161+
</div>
162+
163+
<div class="example">
164+
165+
### Example - Show particles at a player's location (with data)
166+
167+
We can fix the issues with the example above by providing the data of the argument using the `ParticleData` record:
168+
169+
```mccmd
170+
/showparticle <particle>
171+
```
172+
173+
In this case, we'll use the `World.spawnParticle(Particle particle, Location location, int count, T data)` method which accepts some particle data:
174+
175+
<div class="multi-pre">
176+
177+
```java,Java
178+
{{#include ../../commandapi-documentation-code/src/main/java/dev/jorel/commandapi/examples/java/Examples.java:argumentParticle2}}
179+
```
180+
181+
```kotlin,Kotlin
182+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/Examples.kt:argumentParticle2}}
183+
```
184+
185+
```kotlin,Kotlin_DSL
186+
{{#include ../../commandapi-documentation-code/src/main/kotlin/dev/jorel/commandapi/examples/kotlin/ExamplesKotlinDSL.kt:argumentParticle2}}
187+
```
188+
189+
</div>
190+
191+
This can be used with commands such as:
192+
193+
```mccmd
194+
/showparticle minecraft:dust_color_transition{from_color:[0.0,0.0,0.0],scale:20.0,to_color:[1.0,0.0,0.0]}
195+
/showparticle minecraft:block_marker{block_state:{Name:"diamond_block"}}
196+
```
197+
198+
</div>
199+
200+
## Particle data implementation notes
201+
202+
The `vibration` particle will return a particle data of the Bukkit `Vibration` class. In the `Vibration` class, you can access the destination location using the `Vibration.getDestination()` method, which returns a `Vibration.Destination` instance. The CommandAPI will **always** return a `Vibration.Destination.BlockDestination` instance, and will never return a `Vibration.Destination.EntityDestination` instance. An example of accessing the location can be found below:
203+
204+
```java
205+
ParticleData<Vibration> particleData; // The particle data you get from your argument
206+
Location destination = ((BlockDestination) particleData.data().getDestination()).getLocation();
207+
```

docssrc/src/argument_particle.md renamed to docssrc/src/argument_particle_old.md

Lines changed: 6 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,22 @@
1-
# Particle arguments
2-
3-
![A particle argument suggesting a list of Minecraft particle effects](./images/arguments/particle.png)
4-
5-
The `ParticleArgument` class represents Minecraft particles. This is casted to the CommandAPI's `ParticleData` class.
6-
7-
## The `ParticleData` class
8-
9-
The `ParticleData` class is a record that contains two values:
10-
11-
- `Particle particle`, which is the Bukkit enum `Particle` representation of what particle was provided
12-
- `T data`, which represents any additional particle data which was provided.
13-
14-
```java
15-
public record ParticleData<T>(Particle particle, T data);
16-
```
17-
18-
The `T data` can be used in Bukkit's `World.spawnParticle(Particle particle, Location location, int count, T data)` method.
19-
20-
## Particle data
1+
# Particle data (1.16.5 - 1.20.4)
212

223
The particle argument requires additional data for a particle depending on what the particle is. Information about this can be found [on the Argument types page on the MinecraftWiki](https://minecraft.wiki/w/Argument_types#particle). The following particles have additional data required to display them:
234

245
| Bukkit Particle | Minecraft particle | Arguments |
256
|-------------------------|-------------------------|-----------------------------------------------------------------------|
26-
| `BLOCK_CRACK` | `block` | `block block_id`<br>`block block_id[block_state=value]` |
27-
| `BLOCK_MARKER` | `block_marker` | `block_marker block_id`<br>`block_marker block_id[block_state=value]` |
7+
| `BLOCK_CRACK` | `block` | `block block_id`<br><br>`block block_id[block_state=value]` |
8+
| `BLOCK_MARKER` | `block_marker` | `block_marker block_id`<br><br>`block_marker block_id[block_state=value]` |
289
| `REDSTONE` | `dust` | `dust red green blue size` |
2910
| `DUST_COLOR_TRANSITION` | `dust_color_transition` | `dust_color_transition red1 green1 blue1 size red2 green2 blue2` |
30-
| `FALLING_DUST` | `falling_dust` | `falling_dust block_id`<br>`falling_dust block_id[block_state=value]` |
31-
| `ITEM_CRACK` | `item` | `item item_id`<br>`item item_id{NBT}` |
11+
| `FALLING_DUST` | `falling_dust` | `falling_dust block_id`<br><br>`falling_dust block_id[block_state=value]` |
12+
| `ITEM_CRACK` | `item` | `item item_id`<br><br>`item item_id{NBT}` |
3213
| `SCULK_CHARGE` | `sculk_charge` | `sculk_charge angle` |
3314
| `SHRIEK` | `shriek` | `shriek delay` |
3415
| `VIBRATION` | `vibration` | `vibration x y z ticks` |
3516

3617
## ParticleArgument examples
3718

38-
Because certain particles (in the table above) require additional data, it is no longer recommended to spawn a particle without its corresponding data. This can result in particles not showing due to missing requirements.
19+
Because certain particles (in the table above) require additional data, it is not recommended to spawn a particle without its corresponding data. This can result in particles not showing due to missing requirements.
3920

4021
<div class="warning">
4122

‎docssrc/src/argument_particles.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Particle arguments
2+
3+
![A particle argument suggesting a list of Minecraft particle effects](./images/arguments/particle.png)
4+
5+
The `ParticleArgument` class represents Minecraft particles. This is casted to the CommandAPI's `ParticleData` class.
6+
7+
## The `ParticleData` class
8+
9+
The `ParticleData` class is a record that contains two values:
10+
11+
- `Particle particle`, which is the Bukkit enum `Particle` representation of what particle was provided
12+
- `T data`, which represents any additional particle data which was provided.
13+
14+
```java
15+
public record ParticleData<T>(Particle particle, T data);
16+
```
17+
18+
The `T data` can be used in Bukkit's `World.spawnParticle(Particle particle, Location location, int count, T data)` method.
19+
20+
## Particle data
21+
22+
Particle data depends on your version of Minecraft. In 1.20.5, Minecraft and Spigot updated their particle API and they are no longer compatible with each other. Information about how the CommandAPI uses particle data can be found using the links below:
23+
24+
- [Particle data for Minecraft 1.16.5 - 1.20.4](./argument_particle_old.md)
25+
- [Particle data for Minecraft 1.20.5+](./argument_particle_new.md)

‎docssrc/src/arguments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ The type to cast each argument (declared in the `dev.jorel.commandapi.arguments`
142142
| [`ObjectiveArgument`](./argument_objectives.md#objective-argument) | `org.bukkit.scoreboard.Objective` |
143143
| [`ObjectiveCriteriaArgument`](./argument_objectives.md#objective-criteria-argument) | `String` |
144144
| [`OfflinePlayerArgument`](./argument_entities.md#offlineplayer-argument) | `org.bukkit.OfflinePlayer` |
145-
| [`ParticleArgument`](./argument_particle.md) | `dev.jorel.commandapi.wrappers.ParticleData` |
145+
| [`ParticleArgument`](./argument_particles.md) | `dev.jorel.commandapi.wrappers.ParticleData` |
146146
| [`PlayerArgument`](./argument_entities.md#player-argument) | `org.bukkit.entity.Player` |
147147
| [`PotionEffectArgument`](./argument_potion.md) | `org.bukkit.potion.PotionEffectType` |
148148
| [`PotionEffectArgument.NamespacedKey`](./argument_potion.md) | `org.bukkit.NamespacedKey` |

‎docssrc/src/internal.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ The CommandAPI's arguments are representations of the different arguments that t
4545
| `minecraft:objective` | [`ObjectiveArgument`](./argument_objectives.md#objective-argument) |
4646
| `minecraft:objective_criteria` | [`ObjectiveCriteriaArgument`](./argument_objectives.md#objective-criteria-argument) |
4747
| `minecraft:operation` | [`MathOperationArgument`](./argument_mathoperation.md) |
48-
| `minecraft:particle` | [`ParticleArgument`](./argument_particle.md) |
48+
| `minecraft:particle` | [`ParticleArgument`](./argument_particles.md) |
4949
| `minecraft:resource_location` | [`AdvancementArgument`](./advancementargument.md)<br />[`BiomeArgument`](./argument_biome.md)<br />[`CustomArgument<T>`](./argument_custom.md)<br />[`LootTableArgument`](./argument_loottable.md)<br />[`NamespacedKeyArgument`](./argument_namespacedkey.md)<br />[`RecipeArgument`](./argument_recipe.md)<br />[`SoundArgument`](./argument_sound.md) |
5050
| `minecraft:rotation` | [`RotationArgument`](./argument_rotation.md) |
5151
| `minecraft:score_holder` | [`ScoreHolderArgument`](./argument_scoreboards.md#score-holder-argument) |

‎docssrc/src/intro.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Here's the list of changes to the documentation between each update. You can vie
4343
- Updates [CommandArguments](./commandarguments.md) to document new additions for safe arguments
4444
- Updates [Potion effect arguments](./argument_potion.md) to include examples for the newly added `NamespacedKey` variant for the `PotionEffectArgument`
4545
- Updates [Arguments](./arguments.md) to list the newly added `PotionEffectArgument.NamespacedKey` argument
46+
- Updates [Particles](./argument_particles.md) page to include both [old particle information](./argument_particle_old.md) and [new particle information](./argument_particle_new.md)
4647

4748
### Documentation changes 9.2.0 \\(\rightarrow\\) 9.3.0
4849

@@ -146,7 +147,7 @@ Here's the list of changes to the documentation between each update. You can vie
146147

147148
### Documentation changes 7.0.0 \\(\rightarrow\\) 8.0.0
148149

149-
- Updated particle arguments in the [Particle arguments](./argument_particle.md) section.
150+
- Updated particle arguments in the [Particle arguments](./argument_particles.md) section.
150151
- Update the [Upgrading guide](./upgrading.md) for the new changes in 8.0.0.
151152

152153
### Documentation changes 6.5.4 \\(\rightarrow\\) 7.0.0

‎docssrc/src/safeargumentsuggestions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ The list of supported arguments are displayed in the following table. The parame
6262
| [`NBTCompoundArgument`](./argument_nbt.md) | `de.tr7zw.nbtapi.NBTContainer` |
6363
| [`ObjectiveArgument`](./argument_objectives.md#objective-argument) | **`org.bukkit.scoreboard.Objective`** |
6464
| [`OfflinePlayerArgument`](./argument_entities.md#player-argument) | `org.bukkit.OfflinePlayer` |
65-
| [`ParticleArgument`](./argument_particle.md) | `org.bukkit.Particle` |
65+
| [`ParticleArgument`](./argument_particles.md) | `org.bukkit.Particle` |
6666
| [`PlayerArgument`](./argument_entities.md#player-argument) | `org.bukkit.entity.Player` |
6767
| [`PotionEffectArgument`](./argument_potion.md) | `org.bukkit.potion.PotionEffectType` |
6868
| [`RecipeArgument`](./argument_recipe.md) | `org.bukkit.inventory.Recipe` |

0 commit comments

Comments
 (0)