Change PlayEffect syntax to allow effects to not be offset

with back-compat

plugin/src/main/java/net/aufdemrand/denizen/scripts/commands/BukkitCommandRegistry.java

@@ -2741,7 +2741,7 @@ public void registerCoreMembers() {
 
         // <--[command]
         // @Name PlayEffect
-        // @Syntax playeffect [<location>|...] [effect:<name>] (data:<#.#>) (visibility:<#.#>) (quantity:<#>) (offset:<#.#>,<#.#>,<#.#>) (targets:<player>|...)
+        // @Syntax playeffect [effect:<name>] [at:<location>|...] (data:<#.#>) (visibility:<#.#>) (quantity:<#>) (offset:<#.#>,<#.#>,<#.#>) (targets:<player>|...)
         // @Required 2
         // @Stable stable
         // @Short Plays a visible or audible effect at the location.
@@ -2757,23 +2757,28 @@ public void registerCoreMembers() {
         // Everyone will see the particle effects unless a target has been specified.
         // See <@link language Particle Effects> for a list of valid effect names.
         //
+        // Version change note: The original PlayEffect command raised all location inputs 1 block-height upward to avoid effects playing underground when played at eg a player's location.
+        // This was found to cause too much confusion, so it is no longer on by default. However, it will still happen for older commands.
+        // The distinction is in whether you include the (now expected to use) "at:" prefix on your location argument.
+        // If you do not have this prefix, the system will assume your command is older, and will apply the 1-block height offset.
+        //
         // @Tags
         // None
         //
         // @Usage
         // Use to create a fake explosion.
-        // - playeffect <player.location> effect:EXPLOSION_HUGE visibility:500 quantity:10 offset:2.0
+        // - playeffect effect:EXPLOSION_HUGE at:<player.location> visibility:500 quantity:10 offset:2.0
         //
         // @Usage
         // Use to play a cloud effect.
-        // - playeffect <player.location.add[0,5,0]> effect:CLOUD quantity:20 data:1 offset:0.0
+        // - playeffect effect:CLOUD at:<player.location.add[0,5,0]> quantity:20 data:1 offset:0.0
         //
         // @Usage
         // Use to play some effects at spawn.
-        // - playeffect <w@world.spawn_location> effect:FIREWORKS_SPARK visibility:100 quantity:375 data:0 offset:50.0
+        // - playeffect effect:FIREWORKS_SPARK at:<w@world.spawn_location> visibility:100 quantity:375 data:0 offset:50.0
         // -->
         registerCoreMember(PlayEffectCommand.class,
-                "PLAYEFFECT", "playeffect [<location>|...] [effect:<name>] (data:<#.#>) (visibility:<#.#>) (qty:<#>) (offset:<#.#>,<#.#>,<#.#>) (targets:<player>|...)", 2);
+                "PLAYEFFECT", "playeffect [effect:<name>] [at:<location>|...] (data:<#.#>) (visibility:<#.#>) (qty:<#>) (offset:<#.#>,<#.#>,<#.#>) (targets:<player>|...)", 2);
 
 
         // <--[command]

plugin/src/main/java/net/aufdemrand/denizen/scripts/commands/world/PlayEffectCommand.java

@@ -65,6 +65,9 @@ public void parseArgs(ScriptEntry scriptEntry) throws InvalidArgumentsException
 
             if (!scriptEntry.hasObject("location")
                     && arg.matchesArgumentList(dLocation.class)) {
+                if (arg.matchesOnePrefix("at")) {
+                    scriptEntry.addObject("no_offset", new Element(true));
+                }
 
                 scriptEntry.addObject("location", arg.asType(dList.class).filter(dLocation.class));
             }
@@ -213,6 +216,8 @@ public void execute(ScriptEntry scriptEntry) throws CommandExecutionException {
         Element radius = scriptEntry.getElement("radius");
         Element data = scriptEntry.getElement("data");
         Element qty = scriptEntry.getElement("qty");
+        Element no_offset = scriptEntry.getElement("no_offset");
+        boolean should_offset = no_offset == null || !no_offset.asBoolean();
         dLocation offset = scriptEntry.getdObject("offset");
 
         // Report to dB
@@ -225,12 +230,15 @@ public void execute(ScriptEntry scriptEntry) throws CommandExecutionException {
                     radius.debug() +
                     data.debug() +
                     qty.debug() +
-                    offset.debug());
+                    offset.debug() +
+                    (should_offset ? aH.debugObj("note", "Location will be offset 1 block-height upward (see documentation)") : ""));
         }
 
         for (dLocation location : locations) {
-            // Slightly increase the location's Y so effects don't seem to come out of the ground
-            location = new dLocation(location.clone().add(0, 1, 0));
+            if (should_offset) {
+                // Slightly increase the location's Y so effects don't seem to come out of the ground
+                location = new dLocation(location.clone().add(0, 1, 0));
+            }
 
             // Play the Bukkit effect the number of times specified
             if (effect != null) {