Update some MC API docs

Author: PseudoKnight

src/main/java/com/laytonsmith/abstraction/enums/MCSpawnReason.java

@@ -59,6 +59,21 @@ public enum MCSpawnReason {
 	ENCHANTMENT,
 	TRIAL_SPAWNER,
 	POTION_EFFECT,
-	REHYDRATION, // Paper
-	REANIMATE, // Spigot
+	REHYDRATION("Paper"), // Happy Ghast
+	REANIMATE("Spigot"); // Copper Golem
+
+	final String mcImplementation;
+
+	MCSpawnReason() {
+		this.mcImplementation = null;
+	}
+
+	MCSpawnReason(String mcImplementation) {
+		this.mcImplementation = mcImplementation;
+	}
+
+	@Deprecated
+	public String getImplementation() {
+		return this.mcImplementation;
+	}
 }

src/main/java/com/laytonsmith/core/events/drivers/EntityEvents.java

@@ -25,7 +25,6 @@
 import com.laytonsmith.abstraction.enums.MCRemoveCause;
 import com.laytonsmith.abstraction.enums.MCSpawnReason;
 import com.laytonsmith.abstraction.enums.MCTargetReason;
-import com.laytonsmith.abstraction.enums.MCUnleashReason;
 import com.laytonsmith.abstraction.enums.MCVersion;
 import com.laytonsmith.abstraction.events.MCCreatureSpawnEvent;
 import com.laytonsmith.abstraction.events.MCEntityChangeBlockEvent;
@@ -741,7 +740,19 @@ public String getName() {
 
 		@Override
 		public String docs() {
-			return "{type: <macro> | reason: <macro> One of " + StringUtils.Join(MCSpawnReason.values(), ", ", ", or ", " or ") + "}"
+			StringBuilder reasons = new StringBuilder();
+			for(MCSpawnReason value : MCSpawnReason.values()) {
+				if(!reasons.isEmpty()) {
+					reasons.append(", ");
+				}
+				reasons.append(value.name());
+				if(value.getImplementation() != null) {
+					reasons.append(" (");
+					reasons.append(value.getImplementation());
+					reasons.append(")");
+				}
+			}
+			return "{type: <macro> | reason: <macro> One of: " + reasons + "}"
 					+ " Fired when a living entity spawns on the server."
 					+ " {type: the type of creature spawning | id: the entityID of the creature"
 					+ " | reason: the reason this creature is spawning | location: locationArray of the event}"
@@ -2384,8 +2395,8 @@ public String docs() {
 			return "{type: <macro> | reason: <macro>}"
 					+ " This event is called when a leash is broken."
 					+ " {id: The entityID of the entity | type: The entity type of the entity"
-					+ " | reason: The reason the leash broke. Can be one of "
-					+ StringUtils.Join(MCUnleashReason.values(), ", ", ", or ", " or ") + "}"
+					+ " | reason: The reason the leash broke. Can be one of HOLDER_GONE, PLAYER_UNLEASH, DISTANCE,"
+					+ " SHEAR (Spigot-only 1.21.6+), FIREWORK (Spigot-only 1.21.6+), UNKNOWN}"
 					+ " {}";
 		}
 

src/main/java/com/laytonsmith/core/events/drivers/InventoryEvents.java

@@ -529,13 +529,13 @@ public String docs() {
 					+ "{player: The player that enchanted the item | "
 					+ "item: The item to be enchanted | "
 					+ "inventorytype: type of inventory | "
-					+ "levels: The amount of levels the player used | "
+					+ "levels: The minimum amount of levels the player required | "
 					+ "enchants: Array of added enchantments | "
 					+ "location: Location of the used enchantment table | "
-					+ "option: The enchantment option the player clicked | "
+					+ "option: The listed option the player clicked (0-2). Can be used to get level cost. | "
 					+ "levelhint: The level displayed as a hint to the player (MC 1.20.1+) | "
 					+ "enchanthint: The enchantment displayed as a hint to the player (MC 1.20.1+)}"
-					+ "{levels: The amount of levels to use | "
+					+ "{levels: The amount of levels required | "
 					+ "item: The item to be enchanted | "
 					+ "enchants: The enchants to add to the item}"
 					+ "{}";

src/main/java/com/laytonsmith/core/functions/Commands.java

@@ -338,36 +338,37 @@ public Version since() {
 		public ExampleScript[] examples() throws ConfigCompileException {
 			return new ExampleScript[]{
 				new ExampleScript("Register the /hug <player> command.",
-				"register_command('hug', array(\n"
-				+ "\t'description': 'Spread the love!',\n"
-				+ "\t'usage': '/hug <player>',\n"
-				+ "\t'permission': 'perms.hugs',\n"
-				+ "\t'tabcompleter':\n"
-				+ "\t\tclosure(@alias, @sender, @args) {\n"
-				+ "\t\t\t// This replicates the default tabcompleter for registered commands.\n"
-				+ "\t\t\t// If no tabcompleter is set, this behavior is used.\n"
-				+ "\t\t\t@input = @args[-1];\n"
-				+ "\t\t\treturn(array_filter(all_players(), closure(@key, @value) {\n"
-				+ "\t\t\t\treturn(length(@input) <= length(@value)\n"
-				+ "\t\t\t\t\t\t&& equals_ic(@input, substr(@value, 0, length(@input))));\n"
-				+ "\t\t\t}));\n"
-				+ "\t\t},\n"
-				+ "\t'aliases': array('hugg', 'hugs'),\n"
-				+ "\t'executor':\n"
-				+ "\t\tclosure(@alias, @sender, @args) {\n"
-				+ "\t\t\tif(array_size(@args) == 1) {\n"
-				+ "\t\t\t\t@target = @args[0];\n"
-				+ "\t\t\t\tif(ponline(@target)) {\n"
-				+ "\t\t\t\t\tbroadcast(colorize('&4'.@sender.' &6hugs &4'.@target));\n"
-				+ "\t\t\t\t} else {\n"
-				+ "\t\t\t\t\tmsg(colorize('&cThe given player is not online.'));\n"
-				+ "\t\t\t\t}\n"
-				+ "\t\t\t\treturn(true);\n"
-				+ "\t\t\t}\n"
-				+ "\t\t\treturn(false); // prints usage\n"
-				+ "\t\t}\n"
-				+ "));",
-				"Registers the /hug command.")
+						"""
+								register_command('hug', array(
+									'description': 'Spread the love!',
+									'usage': '/hug <player>',
+									'permission': 'perms.hugs',
+									'aliases': array('hugg', 'hugs'),
+									'tabcompleter':
+										closure(@alias, @sender, @args) {
+											// This replicates the default tabcompleter for registered commands.
+											// If no tabcompleter is set, this behavior is used.
+											@input = @args[-1];
+											return(array_filter(all_players(), closure(@key, @value) {
+												return(length(@input) <= length(@value)
+														&& equals_ic(@input, substr(@value, 0, length(@input))));
+											}));
+										},
+									'executor':
+										closure(@alias, @sender, @args) {
+											if(array_size(@args) == 1) {
+												@target = @args[0];
+												if(ponline(@target)) {
+													broadcast(colorize('&4'.@sender.' &6hugs &4'.@target));
+												} else {
+													msg(colorize('&cThe given player is not online.'));
+												}
+												return(true);
+											}
+											return(false); // prints usage
+										}
+								));""",
+						"Registers the /hug command.")
 			};
 		}
 	}

src/main/java/com/laytonsmith/core/functions/EntityManagement.java

@@ -5872,7 +5872,7 @@ public Integer[] numArgs() {
 		@Override
 		public String docs() {
 			return """
-					void {entityUUID, pose, [fixed]} Sets an entity's pose. (only Mannequins on Spigot)
+					void {entityUUID, pose, [fixed]} Sets an entity's pose. (only Mannequins on Spigot, 1.20.1+ on Paper)
 					The fixed argument is a boolean for whether the pose should stay unless manually changed.
 					(defaults to false) While in most cases you can set any pose to any entity,
 					only certain poses will result in a noticable change for a particular entity type.

src/main/java/com/laytonsmith/core/functions/Environment.java

@@ -1589,8 +1589,7 @@ public MSVersion since() {
 
 
 	@api(environments = {CommandHelperEnvironment.class})
-	public static class spawn_particle extends AbstractFunction {
-
+	public static class spawn_particle extends AbstractFunction implements Optimizable {
 		@Override
 		public MSVersion since() {
 			return MSVersion.V3_3_3;
@@ -1633,12 +1632,12 @@ public String docs() {
 					+ "<br>BLOCK_DUST, BLOCK_CRACK, BLOCK_CRUMBLE, BLOCK_MARKER, DUST_PILLAR, and FALLING_DUST"
 					+ " particles can take a block type name parameter under the key \"block\" (default: STONE)."
 					+ "<br>ITEM_CRACK particles can take an item array or name under the key \"item\" (default: STONE)."
-					+ "<br>REDSTONE, SPELL, and SPELL_INSTANT particles take an RGB color array"
+					+ "<br>REDSTONE, SPELL (1.21.9+), and SPELL_INSTANT (1.21.9+) particles take an RGB color array"
 					+ " (each 0 - 255) or name under the key \"color\" (defaults to RED for REDSTONE, WHITE for others)."
-					+ "<br>SPELL_MOB and FLASH particles take an ARGB color array"
-					+ " (each 0 - 255) or name under the key \"color\" (defaults to opaque WHITE)."
-					+ "<br>SPELL, SPELL_INSTANT and DRAGON_BREATH particles take a \"power\" value that scales velocity."
-					+ " (defaults to 1.0)"
+					+ "<br>SPELL_MOB (1.20.6+), TINTED_LEAVES (1.20.6+) and FLASH (1.21.9+) particles take an ARGB color"
+					+ " array (each 0 - 255) or name under the key \"color\" (defaults to opaque WHITE)."
+					+ "<br>SPELL, SPELL_INSTANT and DRAGON_BREATH (1.21.9+) particles take a \"power\" value that scales"
+					+ " velocity. (defaults to 1.0)"
 					+ "<br>DUST_COLOR_TRANSITION particles take a \"tocolor\" in addition \"color\"."
 					+ "<br>VIBRATION particles take a \"destination\" location array or entity UUID."
 					+ "<br>SCULK_CHARGE particles take an \"angle\" in radians. (defaults to 0.0)"
@@ -1736,6 +1735,43 @@ public Mixed exec(Target t, com.laytonsmith.core.environments.Environment enviro
 			}
 			return CVoid.VOID;
 		}
+
+		@Override
+		public ParseTree optimizeDynamic(Target t, com.laytonsmith.core.environments.Environment env,
+				Set<Class<? extends com.laytonsmith.core.environments.Environment.EnvironmentImpl>> envs,
+				List<ParseTree> children, FileOptions fileOptions)
+				throws ConfigCompileException, ConfigRuntimeException {
+
+			if(children.size() < 2) {
+				return null;
+			}
+			ParseTree child = children.get(1);
+			if(child.getData() instanceof CFunction && (child.getData().val().equals(DataHandling.array.NAME)
+					|| child.getData().val().equals(DataHandling.associative_array.NAME))) {
+				for(ParseTree node : child.getChildren()) {
+					if(node.getData() instanceof CFunction && node.getData().val().equals(Compiler.centry.NAME)) {
+						children = node.getChildren();
+						if(children.get(0).getData().val().equals("particle")
+								&& children.get(1).getData().isInstanceOf(CString.TYPE)) {
+							try {
+								MCParticle.MCVanillaParticle.valueOf(children.get(1).getData().val().toUpperCase());
+							} catch (IllegalArgumentException ex) {
+								env.getEnv(CompilerEnvironment.class).addCompilerWarning(fileOptions,
+										new CompilerWarning(children.get(1).getData().val()
+												+ " is not a valid enum in com.commandhelper.Particle",
+												children.get(1).getTarget(), null));
+							}
+						}
+					}
+				}
+			}
+			return null;
+		}
+
+		@Override
+		public Set<OptimizationOption> optimizationOptions() {
+			return EnumSet.of(OptimizationOption.OPTIMIZE_DYNAMIC);
+		}
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})

src/main/java/com/laytonsmith/core/functions/InventoryManagement.java

@@ -19,6 +19,7 @@
 import com.laytonsmith.abstraction.blocks.MCBlockState;
 import com.laytonsmith.abstraction.enums.MCInventoryType;
 import com.laytonsmith.annotations.api;
+import com.laytonsmith.annotations.seealso;
 import com.laytonsmith.core.ArgumentValidation;
 import com.laytonsmith.core.MSVersion;
 import com.laytonsmith.core.ObjectGenerator;
@@ -73,6 +74,7 @@ public static String docs() {
 			+ " and 'meta' (an array of item meta or null if none exists; see {{function|get_itemmeta}} for details).";
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_pinv.class, ptake_item.class})
 	public static class pinv extends AbstractFunction {
 
 		@Override
@@ -433,6 +435,7 @@ public MSVersion since() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({ptake_item.class, pgive_item.class})
 	public static class set_pinv extends AbstractFunction {
 
 		@Override
@@ -610,6 +613,7 @@ public Mixed exec(Target t, Environment env, Mixed... args) throws ConfigRuntime
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({pinv.class})
 	public static class phas_item extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -861,6 +865,7 @@ public ExampleScript[] examples() throws ConfigCompileException {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_pinv.class})
 	public static class pgive_item extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -981,6 +986,7 @@ public Set<OptimizationOption> optimizationOptions() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({pinv.class})
 	public static class ptake_item extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -1119,6 +1125,7 @@ public ExampleScript[] examples() throws ConfigCompileException {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_penderchest.class})
 	public static class pgive_enderchest_item extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -1133,13 +1140,13 @@ public Integer[] numArgs() {
 
 		@Override
 		public String docs() {
-			return "int {[player], itemArray} Adds the specified item to a player's"
-					+ " enderchest. Unlike set_penderchest(), this does not specify a slot. The items are distributed"
-					+ " in the player's inventory, first filling up slots that have the same item type, up to the max"
-					+ " stack size, then fills up empty slots, until either the entire inventory is filled or the"
-					+ " entire amount has been given. If the player's enderchest is full, the number of items that were"
-					+ " not added is returned, which will be less than or equal to the quantity provided. Otherwise,"
-					+ " returns 0.";
+			return "int {[player], itemArray} Adds the specified item to a player's enderchest."
+					+ " Unlike {{function|set_penderchest}}, this does not use a specific slot. The items are"
+					+ " distributed in the player's inventory, first filling up slots that have the same items, up to"
+					+ " the max stack size, then fills up empty slots, until either the entire inventory is filled or"
+					+ " the entire amount has been given. If the player's enderchest is full, the number of items that"
+					+ " were not added is returned, which will be less than or equal to the quantity provided."
+					+ " Otherwise, returns 0.";
 		}
 
 		@Override
@@ -1236,6 +1243,7 @@ public Set<OptimizationOption> optimizationOptions() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_penderchest.class})
 	public static class ptake_enderchest_item extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -1373,6 +1381,7 @@ public ExampleScript[] examples() throws ConfigCompileException {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({penderchest.class, ptake_enderchest_item.class, pgive_enderchest_item.class})
 	public static class set_penderchest extends AbstractFunction {
 
 		@Override
@@ -1478,6 +1487,7 @@ public Mixed exec(Target t, Environment env, Mixed... args) throws ConfigRuntime
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_penderchest.class, ptake_enderchest_item.class, pgive_enderchest_item.class})
 	public static class penderchest extends AbstractFunction {
 
 		@Override
@@ -1634,6 +1644,7 @@ public MSVersion since() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_inventory_item.class, get_inventory_size.class})
 	public static class get_inventory_item extends AbstractFunction {
 
 		@Override
@@ -1697,6 +1708,7 @@ public MSVersion since() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({get_inventory_item.class, get_inventory_size.class, take_from_inventory.class, add_to_inventory.class})
 	public static class set_inventory_item extends AbstractFunction {
 
 		@Override
@@ -1816,6 +1828,7 @@ public MSVersion since() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_inventory.class, set_inventory_item.class, take_from_inventory.class, get_inventory.class})
 	public static class get_inventory_size extends AbstractFunction {
 
 		@Override
@@ -1981,6 +1994,7 @@ public MSVersion since() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_inventory.class, set_inventory_item.class, take_from_inventory.class})
 	public static class get_inventory extends AbstractFunction {
 
 		@Override
@@ -2055,6 +2069,7 @@ public Mixed exec(Target t, Environment env, Mixed... args) throws ConfigRuntime
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({get_inventory.class, get_inventory_size.class, set_inventory_item.class, add_to_inventory.class})
 	public static class set_inventory extends AbstractFunction {
 
 		@Override
@@ -2134,6 +2149,7 @@ public Mixed exec(Target t, Environment env, Mixed... args) throws ConfigRuntime
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({set_inventory_item.class})
 	public static class add_to_inventory extends AbstractFunction implements Optimizable {
 
 		@Override
@@ -2245,6 +2261,7 @@ public Set<OptimizationOption> optimizationOptions() {
 	}
 
 	@api(environments = {CommandHelperEnvironment.class})
+	@seealso({get_inventory.class})
 	public static class take_from_inventory extends AbstractFunction implements Optimizable {
 
 		@Override