1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
|
From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Zach Brown <zach.brown@destroystokyo.com>
Date: Sat, 10 Jun 2017 16:59:40 -0500
Subject: [PATCH] Fix upstream javadocs
diff --git a/src/main/java/org/bukkit/BanList.java b/src/main/java/org/bukkit/BanList.java
index a04cde615f8c4bc593f8d9f8f6f1438008aaa707..548f6d28c28d74bed8b58ee82875909354afe132 100644
--- a/src/main/java/org/bukkit/BanList.java
+++ b/src/main/java/org/bukkit/BanList.java
@@ -38,6 +38,9 @@ public interface BanList<T> {
/**
* Gets a {@link BanEntry} by target.
+ * <p>
+ * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
+ * null when trying to request them. The replacement is bans by UUID.
*
* @param target entry parameter to search for
* @return the corresponding entry, or null if none found
@@ -59,6 +62,9 @@ public interface BanList<T> {
/**
* Adds a ban to this list. If a previous ban exists, this will
* update the previous entry.
+ * <p>
+ * Bans by name for ban type {@link Type#NAME NAME} are no longer supported and this method will return
+ * null when trying to request them. The replacement is bans by UUID.
*
* @param target the target of the ban
* @param reason reason for the ban, null indicates implementation default
@@ -139,6 +145,9 @@ public interface BanList<T> {
/**
* Gets if a {@link BanEntry} exists for the target, indicating an active
* ban status.
+ * <p>
+ * Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
+ * The replacement is bans by UUID.
*
* @param target the target to find
* @return true if a {@link BanEntry} exists for the target, indicating an
@@ -161,6 +170,9 @@ public interface BanList<T> {
/**
* Removes the specified target from this list, therefore indicating a
* "not banned" status.
+ * <p>
+ * Bans by name for ban type {@link Type#NAME NAME} are no longer supported.
+ * The replacement is bans by UUID.
*
* @param target the target to remove from this list
*/
diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
index 72983c3ea04382570c4b52e879dab56702bae55a..dec72e92fb9e489d1d04cdf60c2f1d34571f9410 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -1538,6 +1538,8 @@ public final class Bukkit {
/**
* Gets every player that has ever played on this server.
+ * <p>
+ * <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
diff --git a/src/main/java/org/bukkit/ChunkSnapshot.java b/src/main/java/org/bukkit/ChunkSnapshot.java
index 0cf808356a1a5c6fc4bcf97a694ed9beb80a776a..dc765dea47a9a1c1520fb16ddb24f81413ed0dd1 100644
--- a/src/main/java/org/bukkit/ChunkSnapshot.java
+++ b/src/main/java/org/bukkit/ChunkSnapshot.java
@@ -136,7 +136,7 @@ public interface ChunkSnapshot {
* Get raw biome temperature at given coordinates
*
* @param x X-coordinate (0-15)
- * @param y Y-coordinate (0-15)
+ * @param y Y-coordinate (world minHeight (inclusive) - world maxHeight (exclusive))
* @param z Z-coordinate (0-15)
* @return temperature at given coordinate
*/
diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
index 62a8bb18855be13ed1c466b4be7afcd3c91dc7aa..de9fd0fadd6d16ffe883a618bf499214878f443d 100644
--- a/src/main/java/org/bukkit/Particle.java
+++ b/src/main/java/org/bukkit/Particle.java
@@ -195,7 +195,7 @@ public enum Particle implements Keyed {
}
/**
- * Options which can be applied to redstone dust particles - a particle
+ * Options which can be applied to dust particles - a particle
* color and size.
*/
public static class DustOptions {
diff --git a/src/main/java/org/bukkit/RegionAccessor.java b/src/main/java/org/bukkit/RegionAccessor.java
index 4c9fd558fbf7f57a948fbb7f80f4651048c0fb57..458119a9ef7ce8e1f59bd47caa5b4bc698715440 100644
--- a/src/main/java/org/bukkit/RegionAccessor.java
+++ b/src/main/java/org/bukkit/RegionAccessor.java
@@ -158,7 +158,7 @@ public interface RegionAccessor {
* Creates a tree at the given {@link Location}
*
* @param location Location to spawn the tree
- * @param random Random to use to generated the tree
+ * @param random Random to use to generate the tree
* @param type Type of the tree to create
* @return true if the tree was created successfully, otherwise false
*/
@@ -170,14 +170,14 @@ public interface RegionAccessor {
* The provided consumer gets called for every block which gets changed
* as a result of the tree generation. When the consumer gets called no
* modifications to the world are done yet. Which means, that calling
- * {@link #getBlockState(Location)} in the consumer while return the state
+ * {@link #getBlockState(Location)} in the consumer will return the state
* of the block before the generation.
* <p>
* Modifications done to the {@link BlockState} in the consumer are respected,
* which means that it is not necessary to call {@link BlockState#update()}
*
* @param location Location to spawn the tree
- * @param random Random to use to generated the tree
+ * @param random Random to use to generate the tree
* @param type Type of the tree to create
* @param stateConsumer The consumer which should get called for every block which gets changed
* @return true if the tree was created successfully, otherwise false
@@ -197,7 +197,7 @@ public interface RegionAccessor {
* If it returns {@code false} the block won't get set in the world.
*
* @param location Location to spawn the tree
- * @param random Random to use to generated the tree
+ * @param random Random to use to generate the tree
* @param type Type of the tree to create
* @param statePredicate The predicate which should get used to test if a block should be set or not.
* @return true if the tree was created successfully, otherwise false
diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
index 0ba391e6a1e585f29930b4111421e99f6eb11b4a..2f68b766267b53e98dee3054e0a69be8b9cdf70f 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -581,13 +581,10 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
* </ul>
* <p>
* <b>Note:</b> If set to 0, {@link SpawnCategory} mobs spawning will be disabled.
- * <p>
- * Minecraft default: 1.
- * <br>
- * <b>Note: </b> the {@link SpawnCategory#MISC} are not consider.
*
* @param spawnCategory the category of spawn
* @return the default ticks per {@link SpawnCategory} mobs spawn value
+ * @throws IllegalArgumentException if the category is {@link SpawnCategory#MISC}
*/
public int getTicksPerSpawns(@NotNull SpawnCategory spawnCategory);
@@ -1298,6 +1295,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
/**
* Gets every player that has ever played on this server.
+ * <p>
+ * <b>This method can be expensive as it loads all the player data files from the disk.</b>
*
* @return an array containing all previous players
*/
diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
index 9885fd1adc1f93a80d650e6d42dfa3a0b084db9f..c4f2f03ec31998d486dad1d45ef83df3f77b5e28 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -2766,7 +2766,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link StructureType}.
* Finding unexplored structures can, and will, block if the world is
- * looking in chunks that gave not generated yet. This can lead to the world
+ * looking in chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter
@@ -2800,7 +2800,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link StructureType}.
* Finding unexplored structures can, and will, block if the world is
- * looking in chunks that gave not generated yet. This can lead to the world
+ * looking in chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter
@@ -2833,7 +2833,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
/**
* Find the closest nearby structure of a given {@link Structure}. Finding
* unexplored structures can, and will, block if the world is looking in
- * chunks that gave not generated yet. This can lead to the world
+ * chunks that have not generated yet. This can lead to the world
* temporarily freezing while locating an unexplored structure.
* <p>
* The {@code radius} is not a rigid square radius. Each structure may alter
diff --git a/src/main/java/org/bukkit/attribute/AttributeModifier.java b/src/main/java/org/bukkit/attribute/AttributeModifier.java
index d66502c9df2592cd18694481e7e90a71a5c3a359..ee39c0b83e558681e8b006172d34c98e2c83cda2 100644
--- a/src/main/java/org/bukkit/attribute/AttributeModifier.java
+++ b/src/main/java/org/bukkit/attribute/AttributeModifier.java
@@ -117,8 +117,7 @@ public class AttributeModifier implements ConfigurationSerializable, Keyed {
}
/**
- * Get the {@link EquipmentSlot} this AttributeModifier is active on,
- * or null if this modifier is applicable for any slot.
+ * Get the {@link EquipmentSlotGroup} this AttributeModifier is active on.
*
* @return the slot
*/
diff --git a/src/main/java/org/bukkit/block/Bed.java b/src/main/java/org/bukkit/block/Bed.java
index f9bd74f9ce6bd6650726e5a993f9b6e292cdc74d..f4c37ce1fe7aac3dde8485ee51fc8888ed56e79e 100644
--- a/src/main/java/org/bukkit/block/Bed.java
+++ b/src/main/java/org/bukkit/block/Bed.java
@@ -4,7 +4,22 @@ import org.bukkit.material.Colorable;
/**
* Represents a captured state of a bed.
- * @deprecated does not provide useful information beyond the material itself
*/
-@Deprecated
-public interface Bed extends TileState, Colorable { }
+// Paper start
+// @Deprecated
+public interface Bed extends TileState, Colorable {
+
+ @Override
+ @org.jetbrains.annotations.NotNull org.bukkit.DyeColor getColor();
+
+ /**
+ * <b>Unsupported</b>
+ *
+ * @throws UnsupportedOperationException not supported, set the block type
+ */
+ @Override
+ @org.jetbrains.annotations.Contract("_ -> fail")
+ @Deprecated(forRemoval = true)
+ void setColor(@org.bukkit.UndefinedNullability("not supported") org.bukkit.DyeColor color);
+// Paper end
+}
diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
index f8e12868f2e629cdf4784f0157fdb2f8e7b01f99..bda4ab21b3ac2acbe328c0c6887c33283399971e 100644
--- a/src/main/java/org/bukkit/block/Block.java
+++ b/src/main/java/org/bukkit/block/Block.java
@@ -357,7 +357,7 @@ public interface Block extends Metadatable, Translatable {
* Gets the temperature of this block.
* <p>
* If the raw biome temperature without adjusting for height effects is
- * required then please use {@link World#getTemperature(int, int)}.
+ * required then please use {@link World#getTemperature(int, int, int)}.
*
* @return Temperature of this block
*/
@@ -405,7 +405,10 @@ public interface Block extends Metadatable, Translatable {
boolean applyBoneMeal(@NotNull BlockFace face);
/**
- * Returns a list of items which would drop by destroying this block
+ * Returns a list of items which could drop by destroying this block.
+ * <p>
+ * The items are not guaranteed to be consistent across multiple calls to this
+ * method as this just uses the block type's loot table.
*
* @return a list of dropped items for this type of block
*/
@@ -413,8 +416,11 @@ public interface Block extends Metadatable, Translatable {
Collection<ItemStack> getDrops();
/**
- * Returns a list of items which would drop by destroying this block with
- * a specific tool
+ * Returns a list of items which could drop by destroying this block with
+ * a specific tool.
+ * <p>
+ * The items are not guaranteed to be consistent across multiple calls to this
+ * method as this just uses the block type's loot table.
*
* @param tool The tool or item in hand used for digging
* @return a list of dropped items for this type of block
@@ -423,8 +429,11 @@ public interface Block extends Metadatable, Translatable {
Collection<ItemStack> getDrops(@Nullable ItemStack tool);
/**
- * Returns a list of items which would drop by the entity destroying this
- * block with a specific tool
+ * Returns a list of items which could drop by the entity destroying this
+ * block with a specific tool.
+ * <p>
+ * The items are not guaranteed to be consistent across multiple calls to this
+ * method as this just uses the block type's loot table.
*
* @param tool The tool or item in hand used for digging
* @param entity the entity destroying the block
diff --git a/src/main/java/org/bukkit/block/data/BlockData.java b/src/main/java/org/bukkit/block/data/BlockData.java
index 29fd06cb800f9b7cc91a120ccbe2980422ed9653..cd3b3e05cc825cfedec07f9a2a1e0b7b2a8866d6 100644
--- a/src/main/java/org/bukkit/block/data/BlockData.java
+++ b/src/main/java/org/bukkit/block/data/BlockData.java
@@ -224,7 +224,7 @@ public interface BlockData extends Cloneable {
* {@link Material#REDSTONE_WIRE} -> {@link Material#REDSTONE}
* {@link Material#CARROTS} -> {@link Material#CARROT}
* </pre>
- * @return placement material
+ * @return placement material or {@link Material#AIR} if it doesn't have one
*/
@NotNull
Material getPlacementMaterial();
diff --git a/src/main/java/org/bukkit/block/data/FaceAttachable.java b/src/main/java/org/bukkit/block/data/FaceAttachable.java
index 9599e1237b9717ddbf84c3738bf6c1293e8b3c54..950266b4bb0a2fabeb9539c5676ed58f0b0fe620 100644
--- a/src/main/java/org/bukkit/block/data/FaceAttachable.java
+++ b/src/main/java/org/bukkit/block/data/FaceAttachable.java
@@ -38,7 +38,7 @@ public interface FaceAttachable extends BlockData {
*/
WALL,
/**
- * The switch is mounted to the ceiling and pointing dowanrds.
+ * The switch is mounted to the ceiling and pointing downwards.
*/
CEILING;
}
diff --git a/src/main/java/org/bukkit/block/data/type/CommandBlock.java b/src/main/java/org/bukkit/block/data/type/CommandBlock.java
index 9a7122c907308e4e0a4d0eab815df16899503c19..3b1dab4c1c38477fbe651382f37fdb042ce67cd1 100644
--- a/src/main/java/org/bukkit/block/data/type/CommandBlock.java
+++ b/src/main/java/org/bukkit/block/data/type/CommandBlock.java
@@ -4,7 +4,7 @@ import org.bukkit.block.data.Directional;
/**
* 'conditional' denotes whether this command block is conditional or not, i.e.
- * will only execute if the preceeding command block also executed successfully.
+ * will only execute if the preceding command block also executed successfully.
*/
public interface CommandBlock extends Directional {
diff --git a/src/main/java/org/bukkit/block/data/type/Gate.java b/src/main/java/org/bukkit/block/data/type/Gate.java
index 494f97d47b52bc99b13748c1b57730fbd37d8f51..ebc98607b93294847f95e793304bc5d2528de2a3 100644
--- a/src/main/java/org/bukkit/block/data/type/Gate.java
+++ b/src/main/java/org/bukkit/block/data/type/Gate.java
@@ -5,7 +5,7 @@ import org.bukkit.block.data.Openable;
import org.bukkit.block.data.Powerable;
/**
- * 'in_wall" indicates if the fence gate is attached to a wall, and if true the
+ * 'in_wall' indicates if the fence gate is attached to a wall, and if true the
* texture is lowered by a small amount to blend in better.
*/
public interface Gate extends Directional, Openable, Powerable {
diff --git a/src/main/java/org/bukkit/block/data/type/Switch.java b/src/main/java/org/bukkit/block/data/type/Switch.java
index be06f8db02ca41d5cc3a5dc02951ad27e3cc8f9d..d91a07c7bcb36b3810bb2db89afef1eefd89253d 100644
--- a/src/main/java/org/bukkit/block/data/type/Switch.java
+++ b/src/main/java/org/bukkit/block/data/type/Switch.java
@@ -21,7 +21,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
* Sets the value of the 'face' property.
*
* @param face the new 'face' value
- * @deprecated use {@link #getAttachedFace()}
+ * @deprecated use {@link #setAttachedFace(AttachedFace)}
*/
@Deprecated
void setFace(@NotNull Face face);
@@ -42,7 +42,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
*/
WALL,
/**
- * The switch is mounted to the ceiling and pointing dowanrds.
+ * The switch is mounted to the ceiling and pointing downwards.
*/
CEILING;
}
diff --git a/src/main/java/org/bukkit/entity/ArmorStand.java b/src/main/java/org/bukkit/entity/ArmorStand.java
index 91fc11dda99de506be83d40df8929bf7cd8e8d85..7dc631ebd009f5f5c3ac1699c3f3515c47609c05 100644
--- a/src/main/java/org/bukkit/entity/ArmorStand.java
+++ b/src/main/java/org/bukkit/entity/ArmorStand.java
@@ -360,5 +360,8 @@ public interface ArmorStand extends LivingEntity {
* @param move {@code true} if this armour stand can move, {@code false} otherwise
*/
void setCanMove(boolean move);
+
+ @Override
+ org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
// Paper end
}
diff --git a/src/main/java/org/bukkit/entity/Arrow.java b/src/main/java/org/bukkit/entity/Arrow.java
index a1615334cae50c7d64ca6d86cb7070405a26b332..e396f351a46e4220fa4df11eaa93d813dced664c 100644
--- a/src/main/java/org/bukkit/entity/Arrow.java
+++ b/src/main/java/org/bukkit/entity/Arrow.java
@@ -93,7 +93,7 @@ public interface Arrow extends AbstractArrow {
* Removes a custom potion effect from this arrow.
*
* @param type the potion effect type to remove
- * @return true if the an effect was removed as a result of this call
+ * @return true if the effect was removed as a result of this call
* @throws IllegalArgumentException if this operation would leave the Arrow
* in a state with no Custom Effects and PotionType.UNCRAFTABLE
*/
diff --git a/src/main/java/org/bukkit/entity/EnderDragon.java b/src/main/java/org/bukkit/entity/EnderDragon.java
index 1e56aef9188487d3e9c737e85025f601ab359a72..92cd35c87bad578c2b714761c93a5b72ebf4bc9e 100644
--- a/src/main/java/org/bukkit/entity/EnderDragon.java
+++ b/src/main/java/org/bukkit/entity/EnderDragon.java
@@ -30,7 +30,7 @@ public interface EnderDragon extends ComplexLivingEntity, Boss, Mob, Enemy {
*/
FLY_TO_PORTAL,
/**
- * The dragon will land on on the portal. If the dragon is not near
+ * The dragon will land on the portal. If the dragon is not near
* the portal, it will fly to it before mounting.
*/
LAND_ON_PORTAL,
diff --git a/src/main/java/org/bukkit/entity/Entity.java b/src/main/java/org/bukkit/entity/Entity.java
index 4e1fb0974d061d5bb64899cac576318d2e6f8bf6..539b3527d0c66611e21712f29b90fba939e661e3 100644
--- a/src/main/java/org/bukkit/entity/Entity.java
+++ b/src/main/java/org/bukkit/entity/Entity.java
@@ -180,9 +180,13 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
public List<org.bukkit.entity.Entity> getNearbyEntities(double x, double y, double z);
/**
- * Returns a unique id for this entity
+ * Returns the network protocol ID for this entity. This is
+ * not to be used as an identifier for the entity except in
+ * network-related operations. Use {@link #getUniqueId()} as
+ * an entity identifier instead.
*
- * @return Entity id
+ * @return the network protocol ID
+ * @see #getUniqueId()
*/
public int getEntityId();
diff --git a/src/main/java/org/bukkit/entity/HumanEntity.java b/src/main/java/org/bukkit/entity/HumanEntity.java
index 274f3ccbc39d4d6ff0665abf334d526317275dd0..a7bfaa874cbd3fc8d24fffe2f7f14594b37fa18c 100644
--- a/src/main/java/org/bukkit/entity/HumanEntity.java
+++ b/src/main/java/org/bukkit/entity/HumanEntity.java
@@ -22,6 +22,11 @@ import org.jetbrains.annotations.Nullable;
*/
public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder {
+ // Paper start
+ @Override
+ org.bukkit.inventory.@NotNull EntityEquipment getEquipment();
+ // Paper end
+
/**
* Returns the name of this player
*
diff --git a/src/main/java/org/bukkit/entity/ItemFrame.java b/src/main/java/org/bukkit/entity/ItemFrame.java
index b688b3856cb3068a539fcecfbfa113f8ab4160a9..c275b881cbd11307a6dcc7190d7a7d4063000ad8 100644
--- a/src/main/java/org/bukkit/entity/ItemFrame.java
+++ b/src/main/java/org/bukkit/entity/ItemFrame.java
@@ -75,7 +75,7 @@ public interface ItemFrame extends Hanging {
public void setRotation(@NotNull Rotation rotation) throws IllegalArgumentException;
/**
- * Returns whether the item frame is be visible or not.
+ * Returns whether the item frame is visible or not.
*
* @return whether the item frame is visible or not
*/
diff --git a/src/main/java/org/bukkit/entity/Mob.java b/src/main/java/org/bukkit/entity/Mob.java
index f3f62e13cc1b6172808c52f2d5f520f1f584e6db..ad5dbf310fe7b34c997bb339f09697222f862005 100644
--- a/src/main/java/org/bukkit/entity/Mob.java
+++ b/src/main/java/org/bukkit/entity/Mob.java
@@ -9,6 +9,10 @@ import org.jetbrains.annotations.Nullable;
*/
public interface Mob extends LivingEntity, Lootable {
+ // Paper start
+ @Override
+ org.bukkit.inventory.@org.jetbrains.annotations.NotNull EntityEquipment getEquipment();
+ // Paper end
/**
* Instructs this Mob to set the specified LivingEntity as its target.
* <p>
diff --git a/src/main/java/org/bukkit/entity/PigZombie.java b/src/main/java/org/bukkit/entity/PigZombie.java
index ae9eaaa8e38e1d9dfc459926c7fc51ddb89de84a..b2ec535bb1b0ce0c114ddd7638b90218b05cd835 100644
--- a/src/main/java/org/bukkit/entity/PigZombie.java
+++ b/src/main/java/org/bukkit/entity/PigZombie.java
@@ -44,8 +44,6 @@ public interface PigZombie extends Zombie {
/**
* <b>Not applicable to this entity</b>
- *
- * @return UnsuppotedOperationException
*/
@Override
public int getConversionTime();
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index add0826af957c773975f840c28cf77afbab85a09..fea44ddd358b65681d13215244836c21fc88e0fd 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -476,15 +476,15 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Saves the players current location, health, inventory, motion, and
- * other information into the username.dat file, in the world/player
- * folder
+ * other information into the <uuid>.dat file, in the
+ * <level-name>/playerdata/ folder.
*/
public void saveData();
/**
* Loads the players current location, health, inventory, motion, and
- * other information from the username.dat file, in the world/player
- * folder.
+ * other information from the <uuid>.dat file, in the
+ * <level-name>/playerdata/ folder.
* <p>
* Note: This will overwrite the players current inventory, health,
* motion, etc, with the state from the saved dat file.
@@ -821,7 +821,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Plays an effect to just this player.
*
- * @param <T> the data based based on the type of the effect
+ * @param <T> the data based on the type of the effect
* @param loc the location to play the effect at
* @param effect the {@link Effect}
* @param data a data bit needed for some effects
@@ -1232,7 +1232,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
*
* Use supplied alternative character to the section symbol to represent legacy color codes.
*
- * @param alternateChar Alternate symbol such as '&'
+ * @param alternateChar Alternate symbol such as '&'
* @param message The message to send
* @deprecated use {@link #sendActionBar(net.kyori.adventure.text.Component)}
*/
@@ -1705,7 +1705,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Allows this player to see a player that was previously hidden. If
- * another another plugin had hidden the player too, then the player will
+ * another plugin had hidden the player too, then the player will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the player
@@ -1732,7 +1732,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
/**
* Allows this player to see an entity that was previously hidden. If
- * another another plugin had hidden the entity too, then the entity will
+ * another plugin had hidden the entity too, then the entity will
* remain hidden until the other plugin calls this method too.
*
* @param plugin Plugin that wants to show the entity
@@ -1815,9 +1815,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
- * <li>There is no concept of resetting texture packs back to default
- * within Minecraft, so players will have to relog to do so or you
- * have to send an empty pack.
* <li>The request is send with "null" as the hash. This might result
* in newer versions not loading the pack correctly.
* </ul>
@@ -1851,9 +1848,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
- * <li>There is no concept of resetting resource packs back to default
- * within Minecraft, so players will have to relog to do so or you
- * have to send an empty pack.
* <li>The request is send with empty string as the hash. This might result
* in newer versions not loading the pack correctly.
* </ul>
@@ -1890,9 +1884,6 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
* case this method will have no affect on them. Use the
* {@link PlayerResourcePackStatusEvent} to figure out whether or not
* the player loaded the pack!
- * <li>There is no concept of resetting resource packs back to default
- * within Minecraft, so players will have to relog to do so or you
- * have to send an empty pack.
* <li>The request is sent with empty string as the hash when the hash is
* not provided. This might result in newer versions not loading the
* pack correctly.
diff --git a/src/main/java/org/bukkit/entity/Slime.java b/src/main/java/org/bukkit/entity/Slime.java
index a5ad3250cebfeb302c58e0bfd6db1295913c927e..bfac874840cf1f36afba16ae4d176c5821a68cfb 100644
--- a/src/main/java/org/bukkit/entity/Slime.java
+++ b/src/main/java/org/bukkit/entity/Slime.java
@@ -11,6 +11,16 @@ public interface Slime extends Mob, Enemy {
public int getSize();
/**
+ * Setting the size of the slime (regardless of previous size)
+ * will set the following attributes:
+ * <ul>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_MAX_HEALTH}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_MOVEMENT_SPEED}</li>
+ * <li>{@link org.bukkit.attribute.Attribute#GENERIC_ATTACK_DAMAGE}</li>
+ * </ul>
+ * to their per-size defaults and heal the
+ * slime to its max health (assuming it's alive).
+ *
* @param sz The new size of the slime.
*/
public void setSize(int sz);
diff --git a/src/main/java/org/bukkit/entity/Sniffer.java b/src/main/java/org/bukkit/entity/Sniffer.java
index af5110b4160979c39cc1e5de6fa3bd7957b21403..15a0a733b0e5804655b5957cbf20831290d52a08 100644
--- a/src/main/java/org/bukkit/entity/Sniffer.java
+++ b/src/main/java/org/bukkit/entity/Sniffer.java
@@ -12,8 +12,6 @@ public interface Sniffer extends Animals {
/**
* Gets the locations explored by the sniffer.
- * <br>
- * <b>Note:</b> the returned locations use sniffer's current world.
*
* @return a collection of locations
*/
@@ -22,9 +20,6 @@ public interface Sniffer extends Animals {
/**
* Remove a location of the explored locations.
- * <br>
- * <b>Note:</b> the location must be in the sniffer's current world for this
- * method to have any effect.
*
* @param location the location to remove
* @see #getExploredLocations()
diff --git a/src/main/java/org/bukkit/entity/Villager.java b/src/main/java/org/bukkit/entity/Villager.java
index 6bf3af3ed81b66f61e53105d3591165ea74dba0e..a91400cd8bb4c72d1f3200a17f6de025540fe09d 100644
--- a/src/main/java/org/bukkit/entity/Villager.java
+++ b/src/main/java/org/bukkit/entity/Villager.java
@@ -202,7 +202,7 @@ public interface Villager extends AbstractVillager {
*/
NITWIT,
/**
- * Sheperd profession. Wears a brown robe. Shepherds primarily trade for
+ * Shepherd profession. Wears a brown robe. Shepherds primarily trade for
* wool items, and shears.
*/
SHEPHERD,
diff --git a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
index a0f6f1af304190b4c5db4b284d460f625eeb7801..7e21548cac8515c281ec86853e9272ab7695b24f 100644
--- a/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockDropItemEvent.java
@@ -10,15 +10,19 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Called if a block broken by a player drops an item.
+ * Called after a block is broken by a player and potential drops are computed, even if said blocks loot table
+ * does not define any drops at the point the event is constructed.
*
* If the block break is cancelled, this event won't be called.
*
- * If isDropItems in BlockBreakEvent is set to false, this event won't be
+ * If isDropItems in {@link org.bukkit.event.block.BlockBreakEvent} is set to false, this event won't be
* called.
*
+ * If a block is broken and isDropItems is set to true, this event will be called even if the block does
+ * not drop any items, for example glass broken by hand. In this case, #getItems() will be empty.
+ *
* This event will also be called if the player breaks a multi block structure,
- * for example a torch on top of a stone. Both items will have an event call.
+ * for example a torch on top of a stone. Both items will be included in the #getItems() list.
*
* The Block is already broken as this event is called, so #getBlock() will be
* AIR in most cases. Use #getBlockState() for more Information about the broken
diff --git a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
index e534954457a9961a26dbec7ac035bec07e1d6694..a7c297364805c58ae16895055d8eae0484384b7d 100644
--- a/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockExplodeEvent.java
@@ -13,6 +13,9 @@ import org.jetbrains.annotations.NotNull;
* Note that due to the nature of explosions, {@link #getBlock()} will always be
* an air block. {@link #getExplodedBlockState()} should be used to get
* information about the block state that exploded.
+ * <p>
+ * The event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
+ * is disabled as no block interaction will occur.
*/
public class BlockExplodeEvent extends BlockEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
@@ -29,6 +32,7 @@ public class BlockExplodeEvent extends BlockEvent implements Cancellable {
this.cancel = false;
}
+ @io.papermc.paper.annotation.DoNotUse // Paper
@Deprecated(forRemoval = true)
public BlockExplodeEvent(@NotNull final Block what, @NotNull final List<Block> blocks, final float yield) {
this(what, what.getState(), blocks, yield);
diff --git a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
index 340fa397e68c024df380a28db21545a0c83d9fa6..79ac8a5db689cf9f8e2ff4cb7c06df6989128d10 100644
--- a/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java
@@ -34,7 +34,7 @@ public class BlockPistonRetractEvent extends BlockPistonEvent {
/**
* Get an immutable list of the blocks which will be moved by the
- * extending.
+ * retracting.
*
* @return Immutable list of the moved blocks.
*/
diff --git a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
index be0a2d1f234d8265d98e54e518a994957b1f3ab7..4e3c406ba883aae553e8d69b6b719b872cd6096c 100644
--- a/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
+++ b/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java
@@ -114,7 +114,7 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
/**
* Gets the value whether the player would be allowed to build here.
- * Defaults to spawn if the server was going to stop them (such as, the
+ * Defaults to false if the server was going to stop them (such as, the
* player is in Spawn). Note that this is an entirely different check
* than BLOCK_CANBUILD, as this refers to a player, not universe-physics
* rule like cactus on dirt.
diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
index fc2120e03737f5882d6ae916db93fdcf4939b2ba..f2edd4a9357832e9dec3fb0aafa006335d7b289b 100644
--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
@@ -81,7 +81,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
/**
* Get a list of available {@link EnchantmentOffer} for the player. You can
* modify the values to change the available offers for the player. An offer
- * may be null, if there isn't a enchantment offer at a specific slot. There
+ * may be null, if there isn't an enchantment offer at a specific slot. There
* are 3 slots in the enchantment table available to modify.
*
* @return list of available enchantment offers
diff --git a/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java b/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
index a37febd0d4dd5b733e9ee72628fdf9395fec4367..9cee218b9ee14688356f16b1f58512186286e7e9 100644
--- a/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
+++ b/src/main/java/org/bukkit/event/entity/AreaEffectCloudApplyEvent.java
@@ -8,7 +8,7 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Called when a lingering potion applies it's effects. Happens
+ * Called when a lingering potion applies its effects. Happens
* once every 5 ticks
*/
public class AreaEffectCloudApplyEvent extends EntityEvent implements Cancellable {
diff --git a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
index 90b287cd2cc6f05bb0c588d8be397cf52a7822de..15cb5ea4b68eca070f73d2b899543274415ad240 100644
--- a/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
+++ b/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java
@@ -158,11 +158,12 @@ public class CreatureSpawnEvent extends EntitySpawnEvent {
*/
DROWNED,
/**
- * When an cow is spawned by shearing a mushroom cow
+ * When a cow is spawned by shearing a mushroom cow
*/
SHEARED,
/**
- * When eg an effect cloud is spawned as a result of a creeper exploding
+ * When an entity is spawned as a result of an explosion. Like an area effect cloud from
+ * a creeper or a dragon fireball.
*/
EXPLOSION,
/**
diff --git a/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java b/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
index 573165ddf3368a96e1ffc6476eb27c9e29a6f86e..148c4aad384ae8e3b8b22d264a84bddfbcafdf1e 100644
--- a/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java
@@ -12,6 +12,10 @@ import org.jetbrains.annotations.Nullable;
/**
* Called when an entity is damaged by a block
+ * <p>
+ * For explosions, the Block returned by {@link #getDamager()} has
+ * already been cleared. See {@link #getDamagerBlockState()} for a snapshot
+ * of the block if it has already been changed.
*/
public class EntityDamageByBlockEvent extends EntityDamageEvent {
private final Block damager;
@@ -51,6 +55,9 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
/**
* Returns the captured BlockState of the block that damaged the player.
+ * <p>
+ * This block state is not placed so {@link org.bukkit.block.BlockState#isPlaced}
+ * will be false.
*
* @return the block state
*/
diff --git a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
index 10d0e18dfd423b108fe381e8142867eb10399359..099efafa14c10910e4ed04abb1823f0c1a96b6a6 100644
--- a/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityExplodeEvent.java
@@ -9,7 +9,9 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Called when an entity explodes
+ * Called when an entity explodes interacting with blocks. The
+ * event isn't called if the {@link org.bukkit.GameRule#MOB_GRIEFING}
+ * is disabled as no block interaction will occur.
*/
public class EntityExplodeEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java b/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
index c866df03d66dd8724e12c7353da4cf144c70b2c8..94ee5a3354722aa5d825da727b7b7071fdc6bacc 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPickupItemEvent.java
@@ -7,7 +7,7 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Thrown when a entity picks an item up from the ground
+ * Thrown when an entity picks an item up from the ground
*/
public class EntityPickupItemEvent extends EntityEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java b/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
index 327876e0ad7dcfeb71d9d22afe1c04bcd71c3bf9..71d664dd89995f088c47d17b38547d530319470c 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPlaceEvent.java
@@ -11,7 +11,7 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
- * Triggered when a entity is created in the world by a player "placing" an item
+ * Triggered when an entity is created in the world by a player "placing" an item
* on a block.
* <br>
* Note that this event is currently only fired for four specific placements:
diff --git a/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java b/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
index 31a5515c08c9454d52a0d946d103a2d526c15e48..d743cc5ee34fd7bc5db92f4b17fed9f3aa5ffbcc 100644
--- a/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityPotionEffectEvent.java
@@ -133,7 +133,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
public enum Action {
/**
- * When the potion effect is added because the entity didn't have it's
+ * When the potion effect is added because the entity didn't have its
* type.
*/
ADDED,
@@ -237,7 +237,7 @@ public class EntityPotionEffectEvent extends EntityEvent implements Cancellable
*/
SPIDER_SPAWN,
/**
- * When the entity gets effects from a totem item saving it's life.
+ * When the entity gets effects from a totem item saving its life.
*/
TOTEM,
/**
diff --git a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
index d51d2ec1d04d9ea8a25a70d0d856f2355ebfcb4a..7ecff9fcee19fc94be784474fea620e5dd434731 100644
--- a/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityRegainHealthEvent.java
@@ -105,7 +105,7 @@ public class EntityRegainHealthEvent extends EntityEvent implements Cancellable
*/
SATIATED,
/**
- * When a player regains health from eating consumables
+ * When an animal regains health from eating consumables
*/
EATING,
/**
diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
index dee186e99463a56394bbc2039d1e763d109125b9..c6e4d69eecd2789b1d78fe99fe590932e9758ba1 100644
--- a/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
+++ b/src/main/java/org/bukkit/event/entity/EntityTargetEvent.java
@@ -156,7 +156,7 @@ public class EntityTargetEvent extends EntityEvent implements Cancellable {
FOLLOW_LEADER,
/**
* When another entity tempts this entity by having a desired item such
- * as wheat in it's hand.
+ * as wheat in its hand.
*/
TEMPT,
/**
diff --git a/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java b/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
index c17ff41a688b2cbd877cda25d4ec033ac8ef5524..bd67b7cba78b9bbdd82a5a40048e658a979e3108 100644
--- a/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
+++ b/src/main/java/org/bukkit/event/entity/PiglinBarterEvent.java
@@ -10,8 +10,7 @@ import org.jetbrains.annotations.NotNull;
/**
* Stores all data related to the bartering interaction with a piglin.
*
- * This event can be triggered by a piglin picking up an item that's on its
- * bartering list.
+ * Called when a piglin completes a barter.
*/
public class PiglinBarterEvent extends EntityEvent implements Cancellable {
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
index bc71bc2d3ace0d19d730c09f05f9e0655bcee8f5..24077da8e6a7937f66eafc6779206055cf82e8d2 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceBurnEvent.java
@@ -8,7 +8,9 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
- * Called when an ItemStack is successfully burned as fuel in a furnace.
+ * Called when an ItemStack is successfully burned as fuel in a furnace-like block such as a
+ * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
+ * {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceBurnEvent extends BlockEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
index 65db4991bd4789991868c0d75fea4034fed487a8..5ffd28fd24b4477a07fc9f6a3f669a6f4da9fa26 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceExtractEvent.java
@@ -9,7 +9,9 @@ import org.bukkit.material.MaterialData;
import org.jetbrains.annotations.NotNull;
/**
- * This event is called when a player takes items out of the furnace
+ * This event is called when a player takes items out of a furnace-like block such as a
+ * {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker}, or
+ * {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceExtractEvent extends BlockExpEvent {
private final Player player;
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
index 066e7dd9a34d35c8b643a5efcf95d6a5ef47c7ee..f8f9b08a0bd82a2667ae4e0c99dae9103f0db3f0 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceSmeltEvent.java
@@ -6,7 +6,9 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
- * Called when an ItemStack is successfully smelted in a furnace.
+ * Called when an ItemStack is successfully smelted in a furnace-like block
+ * such as a {@link org.bukkit.block.Furnace}, {@link org.bukkit.block.Smoker},
+ * or {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceSmeltEvent extends BlockCookEvent {
diff --git a/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java b/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
index 1440c6115520d692faf75455df35b92aa8734491..0808e7aeffb69160913344de5b5e21d5e857f1d6 100644
--- a/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/FurnaceStartSmeltEvent.java
@@ -8,7 +8,10 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
/**
- * Called when a Furnace starts smelting.
+ * Called when any of the furnace-like blocks start smelting.
+ * <p>
+ * Furnace-like blocks are {@link org.bukkit.block.Furnace},
+ * {@link org.bukkit.block.Smoker}, and {@link org.bukkit.block.BlastFurnace}.
*/
public class FurnaceStartSmeltEvent extends InventoryBlockStartEvent {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
index 79797a2be7fb139d528116d34d13e51d39b96e56..f2a2a2ad9930499c5bf624e73571a3294a90db14 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
@@ -16,12 +16,16 @@ import org.jetbrains.annotations.Nullable;
/**
* This event is called when a player clicks in an inventory.
* <p>
+ * In case of a drag action within an inventory, InventoryClickEvent is never called.
+ * Instead, {@link InventoryDragEvent} is called at the end of the drag.
+ * <p>
* Because InventoryClickEvent occurs within a modification of the Inventory,
* not all Inventory related methods are safe to use.
* <p>
- * The following should never be invoked by an EventHandler for
- * InventoryClickEvent using the HumanEntity or InventoryView associated with
- * this event:
+ * Methods that change the view a player is looking at should never be invoked
+ * by an EventHandler for InventoryClickEvent using the HumanEntity or
+ * InventoryView associated with this event.
+ * Examples of these include:
* <ul>
* <li>{@link HumanEntity#closeInventory()}
* <li>{@link HumanEntity#openInventory(Inventory)}
@@ -92,7 +96,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
/**
* Gets the ItemStack currently in the clicked slot.
*
- * @return the item in the clicked
+ * @return the item in the clicked slot
*/
@Nullable
public ItemStack getCurrentItem() {
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
index 5861247c1b8ee4fe2736fd5098e05a2ca9ab78ea..c0cc82d98348e8aae3cb56bafb2fcb590b03094f 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryCloseEvent.java
@@ -7,7 +7,26 @@ import org.bukkit.inventory.InventoryView;
import org.jetbrains.annotations.NotNull;
/**
- * Represents a player related inventory event
+ * This event is called when a player closes an inventory.
+ * <p>
+ * Because InventoryCloseEvent occurs within a modification of the Inventory,
+ * not all Inventory related methods are safe to use.
+ * <p>
+ * Methods that change the view a player is looking at should never be invoked
+ * by an EventHandler for InventoryCloseEvent using the HumanEntity or
+ * InventoryView associated with this event.
+ * Examples of these include:
+ * <ul>
+ * <li>{@link HumanEntity#closeInventory()}
+ * <li>{@link HumanEntity#openInventory(org.bukkit.inventory.Inventory)}
+ * <li>{@link HumanEntity#openWorkbench(org.bukkit.Location, boolean)}
+ * <li>{@link HumanEntity#openEnchanting(org.bukkit.Location, boolean)}
+ * <li>{@link InventoryView#close()}
+ * </ul>
+ * To invoke one of these methods, schedule a task using
+ * {@link org.bukkit.scheduler.BukkitScheduler#runTask(org.bukkit.plugin.Plugin, Runnable)}, which will run the task
+ * on the next tick. Also be aware that this is not an exhaustive list, and
+ * other methods could potentially create issues as well.
*/
public class InventoryCloseEvent extends InventoryEvent {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
index 9013d043503d175004ad276799e5935b7fa59dc4..ceae092eb782698803c6c3df41267dde20ba62b2 100644
--- a/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/InventoryOpenEvent.java
@@ -7,7 +7,7 @@ import org.bukkit.inventory.InventoryView;
import org.jetbrains.annotations.NotNull;
/**
- * Represents a player related inventory event
+ * Called when a player opens an inventory
*/
public class InventoryOpenEvent extends InventoryEvent implements Cancellable {
private static final HandlerList handlers = new HandlerList();
diff --git a/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java b/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
index 6782024735a885ba0b1b4dba4a576740c1410366..8977f7609431c3c46324a82de84d4a32f4b71c57 100644
--- a/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
+++ b/src/main/java/org/bukkit/event/inventory/PrepareAnvilEvent.java
@@ -24,6 +24,20 @@ public class PrepareAnvilEvent extends PrepareInventoryResultEvent {
return (AnvilInventory) super.getInventory();
}
+ /**
+ * {@inheritDoc}
+ *
+ * <p>
+ * Note: by default custom recipes in anvil are disabled
+ * you should define a repair cost on the anvil inventory
+ * greater or equals to zero in order to allow that.
+ *
+ * @param result result item
+ */
+ public void setResult(@Nullable ItemStack result) {
+ super.setResult(result);
+ }
+
@NotNull
@Override
public HandlerList getHandlers() {
diff --git a/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java b/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
index e4c32b21ab013703a6a1b07a1ad564d914ebe83f..e58fecf0fe54db06e0e944027923a352fd8005d8 100644
--- a/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
+++ b/src/main/java/org/bukkit/event/player/PlayerResourcePackStatusEvent.java
@@ -6,8 +6,9 @@ import org.bukkit.event.HandlerList;
import org.jetbrains.annotations.NotNull;
/**
- * Called when a player takes action on a resource pack request sent via
- * {@link Player#setResourcePack(java.lang.String)}.
+ * Called when a player takes action on a resource pack request.
+ * @see Player#setResourcePack(String, String)
+ * @see Player#setResourcePack(String, String, boolean)
*/
public class PlayerResourcePackStatusEvent extends PlayerEvent {
diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
index 0cc6e29a5af28e95f87f415d6b2424d4622a6f34..c0b749a5bbf4980d01fed74768bb61909b579cb9 100644
--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
+++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
@@ -627,7 +627,7 @@ public abstract class ChunkGenerator {
* Get the biome at x, y, z within chunk being generated
*
* @param x the x location in the chunk from 0-15 inclusive
- * @param y the y location in the chunk from minimum (inclusive) -
+ * @param y the y location in the chunk from minHeight (inclusive) -
* maxHeight (exclusive)
* @param z the z location in the chunk from 0-15 inclusive
* @return Biome value
diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
index 9adc827bc52eaa767a39c82e9cb0ff5a48e02b14..2dde946443fee1f6e79b882cbcb448549dc0c99c 100644
--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
+++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
@@ -37,9 +37,23 @@ public interface EntityEquipment {
public ItemStack getItem(@NotNull EquipmentSlot slot);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
* in their main hand.
*
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInMainHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInMainHand(); // will return a copy
+ * }
+ * }</pre>
+ *
* @return the currently held item
*/
@NotNull
@@ -61,9 +75,23 @@ public interface EntityEquipment {
void setItemInMainHand(@Nullable ItemStack item, boolean silent);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
* in their off hand.
*
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInOffHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInOffHand(); // will return a copy
+ * }
+ * }</pre>
+ *
* @return the currently held item
*/
@NotNull
@@ -85,7 +113,21 @@ public interface EntityEquipment {
void setItemInOffHand(@Nullable ItemStack item, boolean silent);
/**
- * Gets a copy of the item the entity is currently holding
+ * Gets the item the entity is currently holding
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getItemInHand(); // will return a mirror
+ * } else {
+ * equipment.getItemInHand(); // will return a copy
+ * }
+ * }</pre>
*
* @return the currently held item
* @see #getItemInMainHand()
@@ -110,11 +152,24 @@ public interface EntityEquipment {
void setItemInHand(@Nullable ItemStack stack);
/**
- * Gets a copy of the helmet currently being worn by the entity
+ * Gets the helmet currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getHelmet(); // will return a mirror
+ * } else {
+ * equipment.getHelmet(); // will return a copy
+ * }
+ * }</pre>
*
* @return The helmet being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getHelmet();
/**
@@ -133,11 +188,24 @@ public interface EntityEquipment {
void setHelmet(@Nullable ItemStack helmet, boolean silent);
/**
- * Gets a copy of the chest plate currently being worn by the entity
+ * Gets the chest plate currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getChestplate(); // will return a mirror
+ * } else {
+ * equipment.getChestplate(); // will return a copy
+ * }
+ * }</pre>
*
* @return The chest plate being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getChestplate();
/**
@@ -156,11 +224,24 @@ public interface EntityEquipment {
void setChestplate(@Nullable ItemStack chestplate, boolean silent);
/**
- * Gets a copy of the leggings currently being worn by the entity
+ * Gets the leggings currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getLeggings(); // will return a mirror
+ * } else {
+ * equipment.getLeggings(); // will return a copy
+ * }
+ * }</pre>
*
* @return The leggings being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getLeggings();
/**
@@ -179,11 +260,24 @@ public interface EntityEquipment {
void setLeggings(@Nullable ItemStack leggings, boolean silent);
/**
- * Gets a copy of the boots currently being worn by the entity
+ * Gets the boots currently being worn by the entity
+ *
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player.
+ * For stacks from players, this returns a live mirror (or null). You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getBoots(); // will return a mirror
+ * } else {
+ * equipment.getBoots(); // will return a copy
+ * }
+ * }</pre>
*
* @return The boots being worn
*/
- @Nullable
+ @org.bukkit.UndefinedNullability("not null for entities, nullable for players") // Paper
ItemStack getBoots();
/**
@@ -204,12 +298,25 @@ public interface EntityEquipment {
/**
* Gets all ItemStacks from the armor slots.
*
+ * <p>
+ * This returns a copy if this equipment instance is from a non-player,
+ * or it's an empty stack (has AIR as its type).
+ * For non-empty stacks from players, this returns a live mirror. You can check if this
+ * will return a mirror with
+ * <pre>{@code
+ * EntityEquipment equipment = entity.getEquipment();
+ * if (equipment instanceof PlayerInventory) {
+ * equipment.getArmorContents(); // will return an array of mirror
+ * } else {
+ * equipment.getArmorContents(); // will return an array of copies
+ * }
+ * }</pre>
+ *
* @return all the ItemStacks from the armor slots. Individual items can be
* null and are returned in a fixed order starting from the boots and going
* up to the helmet
*/
- @NotNull
- ItemStack[] getArmorContents();
+ @org.bukkit.UndefinedNullability("not null elements for entities, nullable elements for players") ItemStack @NotNull [] getArmorContents(); // Paper
/**
* Sets the entities armor to the provided array of ItemStacks
@@ -249,7 +356,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop killed by anything
* </ul>
*
* @return chance of the currently held item being dropped (1 for non-{@link Mob})
@@ -262,7 +370,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of the main hand item being dropped
@@ -276,7 +385,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return chance of the off hand item being dropped (1 for non-{@link Mob})
@@ -289,7 +399,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance the chance of off hand item being dropped
@@ -302,7 +413,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the helmet being dropped (1 for non-{@link Mob})
@@ -314,7 +426,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the helmet being dropped
@@ -328,7 +441,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the chest plate being dropped (1 for non-{@link Mob})
@@ -341,7 +455,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the chest plate being dropped
@@ -355,7 +470,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the leggings being dropped (1 for non-{@link Mob})
@@ -368,7 +484,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance chance of the leggings being dropped
@@ -381,7 +498,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @return the chance of the boots being dropped (1 for non-{@link Mob})
@@ -393,7 +511,8 @@ public interface EntityEquipment {
*
* <ul>
* <li>A drop chance of 0.0F will never drop
- * <li>A drop chance of 1.0F will always drop
+ * <li>A drop chance of exactly 1.0F will always drop if killed by a player
+ * <li>A drop chance of greater than 1.0F will always drop if killed by anything
* </ul>
*
* @param chance of the boots being dropped
diff --git a/src/main/java/org/bukkit/inventory/ItemFlag.java b/src/main/java/org/bukkit/inventory/ItemFlag.java
index 8453bd058d426c1088b04c55d2448d205f0a104b..1b3580d1861af402396121805715e4087b3bc587 100644
--- a/src/main/java/org/bukkit/inventory/ItemFlag.java
+++ b/src/main/java/org/bukkit/inventory/ItemFlag.java
@@ -35,7 +35,7 @@ public enum ItemFlag {
*/
HIDE_DYE,
/**
- * Setting to show/hide armor trim from leather armor.
+ * Setting to show/hide armor trim from armor.
*/
HIDE_ARMOR_TRIM;
}
diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
index f1918027c3a8735b31566856218611656b56db20..476fe14faa39f02444cab8ad95d4401033dc6938 100644
--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
+++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
@@ -160,7 +160,7 @@ public interface PlayerInventory extends Inventory {
public void setBoots(@Nullable ItemStack boots);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
* in their main hand.
*
* @return the currently held item
@@ -176,7 +176,7 @@ public interface PlayerInventory extends Inventory {
void setItemInMainHand(@Nullable ItemStack item);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
* in their off hand.
*
* @return the currently held item
@@ -192,7 +192,7 @@ public interface PlayerInventory extends Inventory {
void setItemInOffHand(@Nullable ItemStack item);
/**
- * Gets a copy of the item the player is currently holding
+ * Gets the item the player is currently holding
*
* @return the currently held item
* @see #getItemInMainHand()
diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
index a601bc38e322e5810cf883708541e2d199f09ebb..d89068a37de1dcad0b82dee09cc7829109921a05 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
@@ -24,8 +24,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
- * @see ShapedRecipe#setIngredient(char, Material, int)
- * @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
* @deprecated Recipes must have keys. Use {@link #ShapedRecipe(NamespacedKey, ItemStack)}
* instead.
@@ -44,8 +42,6 @@ public class ShapedRecipe extends CraftingRecipe {
* @param result The item you want the recipe to create.
* @see ShapedRecipe#shape(String...)
* @see ShapedRecipe#setIngredient(char, Material)
- * @see ShapedRecipe#setIngredient(char, Material, int)
- * @see ShapedRecipe#setIngredient(char, MaterialData)
* @see ShapedRecipe#setIngredient(char, RecipeChoice)
*/
public ShapedRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
index 3d50775da447175b2a94ed9056ef36aa1e69c2eb..03839302c94adc3175d0a88065cd230257ffd20d 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -30,11 +30,8 @@ public class ShapelessRecipe extends CraftingRecipe {
* @param key the unique recipe key
* @param result The item you want the recipe to create.
* @see ShapelessRecipe#addIngredient(Material)
- * @see ShapelessRecipe#addIngredient(MaterialData)
- * @see ShapelessRecipe#addIngredient(Material,int)
* @see ShapelessRecipe#addIngredient(int,Material)
- * @see ShapelessRecipe#addIngredient(int,MaterialData)
- * @see ShapelessRecipe#addIngredient(int,Material,int)
+ * @see ShapelessRecipe#addIngredient(RecipeChoice)
*/
public ShapelessRecipe(@NotNull NamespacedKey key, @NotNull ItemStack result) {
super(key, result);
@@ -174,7 +171,7 @@ public class ShapelessRecipe extends CraftingRecipe {
/**
* Removes multiple instances of an ingredient from the list. If there are
- * less instances then specified, all will be removed. Only removes exact
+ * fewer instances than specified, all will be removed. Only removes exact
* matches, with a data value of 0.
*
* @param count The number of copies to remove.
diff --git a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
index 07c3dff4d6190ef388d9c1e1c36f67f00a3e8e66..597a18a767b68b47e81454b7d44613c7178c1366 100644
--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
@@ -28,7 +28,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
- * Create a cooking recipe to craft the specified ItemStack.
+ * Create a Stonecutting recipe to craft the specified ItemStack.
*
* @param key The unique recipe key
* @param result The item you want the recipe to create.
@@ -42,7 +42,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
- * Sets the input of this cooking recipe.
+ * Sets the input of this Stonecutting recipe.
*
* @param input The input material.
* @return The changed recipe, so you can chain calls.
@@ -64,7 +64,7 @@ public class StonecuttingRecipe implements Recipe, Keyed {
}
/**
- * Sets the input of this cooking recipe.
+ * Sets the input of this Stonecutting recipe.
*
* @param input The input choice.
* @return The changed recipe, so you can chain calls.
diff --git a/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java b/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
index e7d905b1146b2bdd2da5bdeb6bf3541fb181d59e..c7d3041221742f6655155f19ef2addcaf2401015 100644
--- a/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/BlockStateMeta.java
@@ -32,6 +32,11 @@ public interface BlockStateMeta extends ItemMeta {
* @param blockState the block state to attach to the block.
* @throws IllegalArgumentException if the blockState is null
* or invalid for this item.
+ *
+ * @apiNote As of 1.20.5 the block state carries a copy of the item's data deviations.
+ * As such, setting the block state via this method will reset secondary deviations of the item meta.
+ * This can manifest in the addition to an existing lore failing or a change of a previously added display name.
+ * It is hence recommended to first mutate the block state, set it back, and then mutate the item meta.
*/
void setBlockState(@NotNull BlockState blockState);
}
diff --git a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
index 35c6594fd1040a1af1029e7260e5e3a9307b107d..d58719ee75bef8bc265bfc81bc5d88a426e01dd9 100644
--- a/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/CrossbowMeta.java
@@ -28,8 +28,7 @@ public interface CrossbowMeta extends ItemMeta {
* Removes all projectiles when given null.
*
* @param projectiles the projectiles to set
- * @throws IllegalArgumentException if one of the projectiles is not an
- * arrow or firework rocket
+ * @throws IllegalArgumentException if one of the projectiles is empty
*/
void setChargedProjectiles(@Nullable List<ItemStack> projectiles);
@@ -37,8 +36,7 @@ public interface CrossbowMeta extends ItemMeta {
* Adds a charged projectile to this item.
*
* @param item projectile
- * @throws IllegalArgumentException if the projectile is not an arrow or
- * firework rocket
+ * @throws IllegalArgumentException if the projectile is empty
*/
void addChargedProjectile(@NotNull ItemStack item);
}
diff --git a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
index cdbcc8dbab2456cc2bc1f3084cbb1ced1698b7f5..d528b066c2aaa3fb097931914ff2181f8f64e520 100644
--- a/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/FireworkMeta.java
@@ -86,8 +86,8 @@ public interface FireworkMeta extends ItemMeta {
* Sets the approximate power of the firework. Each level of power is half
* a second of flight time.
*
- * @param power the power of the firework, from 0-127
- * @throws IllegalArgumentException if {@literal height<0 or height>127}
+ * @param power the power of the firework, from 0-255
+ * @throws IllegalArgumentException if {@literal power < 0 or power > 255}
*/
void setPower(int power) throws IllegalArgumentException;
diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index 014c1a0379e532a5c924694a8e0715eb0ba50ec2..10ca843e57c74dfa32d539acd174c8867dfd56ec 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -540,7 +540,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
* The returned component is a snapshot of its current state and does not
* reflect a live view of what is on an item. After changing any value on
* this component, it must be set with
- * {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxComponent)}
+ * {@link #setJukeboxPlayable(org.bukkit.inventory.meta.components.JukeboxPlayableComponent)}
* to apply the changes.
*
* @return component
@@ -549,7 +549,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
JukeboxPlayableComponent getJukeboxPlayable();
/**
- * Sets the item tool.
+ * Sets the jukebox playable component.
*
* @param jukeboxPlayable new component
*/
@@ -576,7 +576,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
/**
* Return an immutable copy of all {@link Attribute}s and their
* {@link AttributeModifier}s for a given {@link EquipmentSlot}.<br>
- * Any {@link AttributeModifier} that does have have a given
+ * Any {@link AttributeModifier} that does have a given
* {@link EquipmentSlot} will be returned. This is because
* AttributeModifiers without a slot are active in any slot.<br>
* If there are no attributes set for the given slot, an empty map
diff --git a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
index c1676991c3cc5f8d6e3f97d8cb356d6e2aa52809..c701d5fbc5fef503f18a3a46fa54c983bf96e895 100644
--- a/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/LeatherArmorMeta.java
@@ -8,8 +8,9 @@ import org.jetbrains.annotations.Nullable;
/**
* Represents leather armor ({@link Material#LEATHER_BOOTS}, {@link
- * Material#LEATHER_CHESTPLATE}, {@link Material#LEATHER_HELMET}, or {@link
- * Material#LEATHER_LEGGINGS}) that can be colored.
+ * Material#LEATHER_LEGGINGS}, {@link Material#LEATHER_CHESTPLATE}, {@link
+ * Material#LEATHER_HELMET}, {@link Material#LEATHER_HORSE_ARMOR} or {@link
+ * Material#WOLF_ARMOR}) that can be colored.
*/
public interface LeatherArmorMeta extends ItemMeta {
@@ -18,6 +19,9 @@ public interface LeatherArmorMeta extends ItemMeta {
* be {@link ItemFactory#getDefaultLeatherColor()}.
*
* @return the color of the armor, never null
+ * @apiNote The method yielding {@link ItemFactory#getDefaultLeatherColor()} is incorrect
+ * for {@link Material#WOLF_ARMOR} as its default color differs. Generally, it is recommended to check
+ * {@link #isDyed()} to determine if this leather armor is dyed than to compare this color to the default.
*/
@NotNull
Color getColor();
@@ -25,8 +29,7 @@ public interface LeatherArmorMeta extends ItemMeta {
/**
* Sets the color of the armor.
*
- * @param color the color to set. Setting it to null is equivalent to
- * setting it to {@link ItemFactory#getDefaultLeatherColor()}.
+ * @param color the color to set.
*/
void setColor(@Nullable Color color);
diff --git a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
index 43f0df04f3cdff7d7db73321a2886f3a737e3c9f..5c741228b2338a7c4de2fe736eb789511abf4880 100644
--- a/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/OminousBottleMeta.java
@@ -3,7 +3,7 @@ package org.bukkit.inventory.meta;
import org.jetbrains.annotations.NotNull;
/**
- * Represents a map that can be scalable.
+ * Represents an ominous bottle with an amplifier of the bad omen effect.
*/
public interface OminousBottleMeta extends ItemMeta {
diff --git a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
index b84b37fe27d84574dc5897285f1d9a1437bd322c..281ae60a6be7e39aab4f27b4c7de3d49ada9a557 100644
--- a/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
+++ b/src/main/java/org/bukkit/plugin/messaging/PluginMessageRecipient.java
@@ -31,7 +31,8 @@ public interface PluginMessageRecipient {
/**
* Gets a set containing all the Plugin Channels that this client is
- * listening on.
+ * listening on. Does not contain the BungeeCord channel due to its
+ * special status.
*
* @return Set containing all the channels that this client may accept.
*/
diff --git a/src/main/java/org/bukkit/scoreboard/Objective.java b/src/main/java/org/bukkit/scoreboard/Objective.java
index 22b1dc5fd4d453161a5ee520072f8e8f955b3a80..a625bcab8e77b05b3341a52c708fae1542b7e3d5 100644
--- a/src/main/java/org/bukkit/scoreboard/Objective.java
+++ b/src/main/java/org/bukkit/scoreboard/Objective.java
@@ -86,7 +86,7 @@ public interface Objective {
*
* @return true if scores are modifiable
* @throws IllegalStateException if this objective has been unregistered
- * @see Criterias#HEALTH
+ * @see Criteria#HEALTH
*/
boolean isModifiable();
diff --git a/src/main/java/org/bukkit/scoreboard/Team.java b/src/main/java/org/bukkit/scoreboard/Team.java
index 52e8be769d2e9b69e9833bc9a7fe39afd10c5095..4d2b8e10263802432dfeac72666487f9547cd2c5 100644
--- a/src/main/java/org/bukkit/scoreboard/Team.java
+++ b/src/main/java/org/bukkit/scoreboard/Team.java
@@ -265,7 +265,7 @@ public interface Team extends net.kyori.adventure.audience.ForwardingAudience {
* Gets the Set of entries on the team
*
* @return entries on the team
- * @throws IllegalStateException if this entries has been unregistered
+ * @throws IllegalStateException if this team has been unregistered
*/
@NotNull
Set<String> getEntries();
diff --git a/src/main/java/org/bukkit/util/BoundingBox.java b/src/main/java/org/bukkit/util/BoundingBox.java
index 9883983c33fcff0f4c1e23867adafa436e2ed96f..5017b73bcec0d4d5256d89db14201c03829dc981 100644
--- a/src/main/java/org/bukkit/util/BoundingBox.java
+++ b/src/main/java/org/bukkit/util/BoundingBox.java
@@ -358,7 +358,7 @@ public class BoundingBox implements Cloneable, ConfigurationSerializable {
* <p>
* Negative values will shrink the bounding box in the corresponding
* direction. Shrinking will be limited to the point where the affected
- * opposite faces would meet if the they shrank at uniform speeds.
+ * opposite faces would meet if they shrank at uniform speeds.
*
* @param negativeX the amount of expansion in the negative x direction
* @param negativeY the amount of expansion in the negative y direction
diff --git a/src/main/java/org/bukkit/util/CachedServerIcon.java b/src/main/java/org/bukkit/util/CachedServerIcon.java
index 612958a331575d1da2715531ebdf6b1168f2e860..9a7768d41270714d4a1c89b4dcb436cc66f57545 100644
--- a/src/main/java/org/bukkit/util/CachedServerIcon.java
+++ b/src/main/java/org/bukkit/util/CachedServerIcon.java
@@ -5,7 +5,7 @@ import org.bukkit.event.server.ServerListPingEvent;
import org.jetbrains.annotations.Nullable;
/**
- * This is a cached version of a server-icon. It's internal representation
+ * This is a cached version of a server-icon. Its internal representation
* and implementation is undefined.
*
* @see Server#getServerIcon()
|