diff --git a/plugin/src/main/java/com/denizenscript/denizen/objects/CuboidTag.java b/plugin/src/main/java/com/denizenscript/denizen/objects/CuboidTag.java index c94c69433f..3d92a3882c 100644 --- a/plugin/src/main/java/com/denizenscript/denizen/objects/CuboidTag.java +++ b/plugin/src/main/java/com/denizenscript/denizen/objects/CuboidTag.java @@ -725,6 +725,9 @@ public static void register() { // @description // Returns a random block location within the cuboid. // (Note: random selection will not be fairly weighted for multi-member cuboids). + // @example + // # Spawns a debugblock at a random block in the cuboid "my_cuboid". + // - debugblock // --> tagProcessor.registerTag(LocationTag.class, "random", (attribute, cuboid) -> { LocationPair pair = cuboid.pairs.get(CoreUtilities.getRandom().nextInt(cuboid.pairs.size())); @@ -742,6 +745,10 @@ public static void register() { // @returns ElementTag(Number) // @description // Returns the number of cuboids defined in the CuboidTag. + // @example + // # Narrates the amount of cuboids are defined in "my_cuboid". + // # For example, if there are 3 cuboids defined in "my_cuboid", this will return "3". + // - narrate "The cuboid, 'my_cuboid', has members!" // --> tagProcessor.registerTag(ElementTag.class, "members_size", (attribute, cuboid) -> { return new ElementTag(cuboid.pairs.size()); @@ -752,6 +759,9 @@ public static void register() { // @returns ListTag(LocationTag) // @description // Returns each block location on the outline of the CuboidTag. + // @example + // # Plays the "flame" effect at the outline of the cuboid. + // - playeffect effect:flame at: offset:0.0 // --> tagProcessor.registerTag(ListTag.class, "outline", (attribute, cuboid) -> { return cuboid.getOutline(); @@ -762,6 +772,8 @@ public static void register() { // @returns ListTag(LocationTag) // @description // Returns a list of block locations along the 2D outline of this CuboidTag, at the specified Y level. + // # Plays the "flame" effect at the 2D outline of the cuboid on the player's Y level. + // - playeffect effect:flame at:]> offset:0.0 // --> tagProcessor.registerTag(ListTag.class, "outline_2d", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -777,6 +789,12 @@ public static void register() { // @returns ElementTag(Boolean) // @description // Returns whether this cuboid and another intersect. + // @example + // # Checks if the cuboid, "my_cuboid", intersects "my_second_cuboid". + // - if : + // - narrate "Both cuboids intersect each other!" + // - else: + // - narrate "These cuboids do NOT intersect each other!" // --> tagProcessor.registerTag(ElementTag.class, "intersects", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -813,6 +831,10 @@ public static void register() { // @returns ListTag(CuboidTag) // @description // Returns a list of all sub-cuboids in this CuboidTag (for cuboids that contain multiple sub-cuboids). + // @example + // # Loops through the members of the cuboid and plays a "flame" effect at their outlines. + // - foreach as:member: + // - playeffect effect:flame at:<[member].outline> offset:0.0 // --> tagProcessor.registerTag(ListTag.class, "list_members", (attribute, cuboid) -> { List pairs = cuboid.pairs; @@ -828,6 +850,9 @@ public static void register() { // @returns CuboidTag // @description // Returns a cuboid representing the one component of this cuboid (for cuboids that contain multiple sub-cuboids). + // @example + // # Displays a debugblock at the corners of the second member of "my_cuboid". + // - debugblock // --> tagProcessor.registerTag(CuboidTag.class, "get", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -890,6 +915,10 @@ public static void register() { // @mechanism CuboidTag.add_member // @description // Returns a modified copy of this cuboid, with the input cuboid(s) added at the end. + // @example + // # Creates a new cuboid named "my_third_cuboid" and adds "my_cuboid" and "my_second_cuboid" as members. + // # You can also use the "add_member" mechanism. + // - note as:my_third_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "add_member", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -906,6 +935,10 @@ public static void register() { // @mechanism CuboidTag.add_member // @description // Returns a modified copy of this cuboid, with the input cuboid(s) added at the specified index. + // @example + // # Adds "my_second_cuboid" as a member of "my_cuboid" at an index of 3. + // # You can also use the "add_member" mechanism. + // - note as:my_third_cuboid // --> if (attribute.startsWith("at", 2)) { if (!attribute.hasContext(2)) { @@ -942,6 +975,10 @@ public static void register() { // @mechanism CuboidTag.remove_member // @description // Returns a modified copy of this cuboid, with member at the input index removed. + // @example + // # Removes the third member in the cuboid "my_cuboid" and notes it as "my_new_cuboid". + // # You can also use the "remove_member" mechanism. + // - note as:my_new_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "remove_member", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -969,6 +1006,9 @@ public static void register() { // @description // Returns the location of the exact center of the cuboid. // Not valid for multi-member CuboidTags. + // @example + // # Displays a debugblock at the center of the cuboid. + // - debugblock // --> tagProcessor.registerTag(LocationTag.class, "center", (attribute, cuboid) -> { LocationPair pair; @@ -999,6 +1039,9 @@ public static void register() { // Returns the volume of the cuboid. // Effectively equivalent to: (size.x * size.y * size.z). // Not valid for multi-member CuboidTags. + // @example + // # For example, a cuboid with a size of "6,7,8" will have a volume of "336". 6 * 7 * 8 = 336. + // - narrate "The volume of the cuboid 'my_cuboid' is: !" // --> tagProcessor.registerTag(ElementTag.class, "volume", (attribute, cuboid) -> { LocationPair pair = cuboid.pairs.get(0); @@ -1013,6 +1056,9 @@ public static void register() { // Returns the size of the cuboid. // Effectively equivalent to: (max - min) + (1,1,1) // Not valid for multi-member CuboidTags. + // @example + // # For example, this can return "6,7,8", meaning the cuboid is 6 blocks wide, 7 blocks high, and 8 blocks deep. + // - narrate "The size of the cuboid 'my_cuboid' is: !" // --> tagProcessor.registerTag(LocationTag.class, "size", (attribute, cuboid) -> { LocationPair pair; @@ -1039,6 +1085,9 @@ public static void register() { // @description // Returns the highest-numbered (maximum) corner location. // Not valid for multi-member CuboidTags. + // @example + // # Displays a glowstone "block_marker" effect at maximum corner location of the cuboid. + // - playeffect effect:block_marker special_data:glowstone at: offset:0.0 // --> tagProcessor.registerTag(LocationTag.class, "max", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1062,6 +1111,9 @@ public static void register() { // @description // Returns the lowest-numbered (minimum) corner location. // Not valid for multi-member CuboidTags. + // @example + // # Displays a glowstone "block_marker" effect at minimum corner location of the cuboid. + // - playeffect effect:block_marker special_data:glowstone at: offset:0.0 // --> tagProcessor.registerTag(LocationTag.class, "min", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1087,6 +1139,9 @@ public static void register() { // The 4 low corners, then the 4 high corners. // In order X-Z-, X+Z-, X-Z+, X+Z+ // If the object is a multi-member cuboid, returns corners for all members in sequence. + // @example + // # Displays a glowstone block marker effect at each corner of the cuboid. + // - playeffect effect:block_marker special_data:glowstone at: offset:0.0 // --> tagProcessor.registerTag(ListTag.class, "corners", (attribute, cuboid) -> { ListTag output = new ListTag(); @@ -1109,6 +1164,9 @@ public static void register() { // @description // Returns a copy of this cuboid, with all members shifted by the given vector LocationTag. // For example, a cuboid from 5,5,5 to 10,10,10, shifted 100,0,100, would return a cuboid from 105,5,105 to 110,10,110. + // @example + // # Notes the cuboid "my_cuboid" as "my_shifted_cuboid" but shifted over by 25,25,25. + // - note as:my_shifted_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "shift", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1127,6 +1185,12 @@ public static void register() { // @returns CuboidTag // @description // Expands the first member of the CuboidTag to contain the given location (or entire cuboid), and returns the expanded cuboid. + // @example + // # Expands the cuboid to contain the player's location and notes it as "my_new_cuboid". + // - note ]> as:my_new_cuboid + // @example + // # Expands the cuboid to contain the cuboid "my_second_cuboid" and notes it as "my_new_cuboid". + // - note as:my_new_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "include", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1149,6 +1213,9 @@ public static void register() { // @returns CuboidTag // @description // Expands the first member of the CuboidTag to contain the given X value, and returns the expanded cuboid. + // @example + // # Expands the cuboid to include a block with an X location of 25 and notes it as "my_expanded_cuboid". + // - note as:my_expanded_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "include_x", (attribute, cuboid) -> { cuboid = cuboid.clone(); @@ -1171,6 +1238,9 @@ public static void register() { // @returns CuboidTag // @description // Expands the first member of the CuboidTag to contain the given Y value, and returns the expanded cuboid. + // @example + // # Expands the cuboid to include a block with a Y location of 25 and notes it as "my_expanded_cuboid". + // - note as:my_expanded_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "include_y", (attribute, cuboid) -> { cuboid = cuboid.clone(); @@ -1193,6 +1263,9 @@ public static void register() { // @returns CuboidTag // @description // Expands the first member of the CuboidTag to contain the given Z value, and returns the expanded cuboid. + // @example + // # Expands the cuboid to include a block with a Z location of 25 and notes it as "my_expanded_cuboid". + // - note as:my_expanded_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "include_z", (attribute, cuboid) -> { cuboid = cuboid.clone(); @@ -1219,6 +1292,11 @@ public static void register() { // and the output min will contain the old max values. // Note that this is equivalent to constructing a cuboid with the input value and the original cuboids max value. // Not valid for multi-member CuboidTags. + // @example + // # Notes a new cuboid with the player's location as the new minimum location of the cuboid. + // # For example: if "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min) and the player had a location of -5,5,-5, + // # then "my_new_cuboid" will have a minimum location of -5,5,-5. + // - note ]> as:my_new_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "with_min", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1238,6 +1316,11 @@ public static void register() { // and the output max will contain the old min values. // Note that this is equivalent to constructing a cuboid with the input value and the original cuboids min value. // Not valid for multi-member CuboidTags. + // @example + // # Notes a new cuboid with the player's location as the new maximum location of the cuboid. + // # For example: if "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min) and the player had a location of 15,10,15, + // # then "my_new_cuboid" will span from 15,10,15 (max) to 5,5,5 (min). + // - note ]> as:my_new_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "with_max", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1257,6 +1340,14 @@ public static void register() { // Supplying a negative input will therefore contract the cuboid. // Note that you can also specify a single number to expand all coordinates by the same amount (equivalent to specifying a location that is that value on X, Y, and Z). // Not valid for multi-member CuboidTags. + // @example + // # If "my_cuboid" spans from 10,10,10 to 5,5,5 and gets expanded by 15 (15,15,15), + // # then "my_expanded_cuboid" will span -10,-10,-10 (min) to 25,25,25 (max). + // - note as:my_expanded_cuboid + // @example + // # If "my_cuboid" spans from 10,10,10 to 5,5,5 and gets expanded by 15,20,25, + // # then "my_expanded_cuboid" will span -10,-15,-20 (min) to 25,30,35 (max). + // - note as:my_expanded_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "expand", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1284,6 +1375,16 @@ public static void register() { // Note that you can also specify a single number to expand all coordinates by the same amount (equivalent to specifying a location that is that value on X, Y, and Z). // Inverted by <@link tag CuboidTag.shrink_one_side> // Not valid for multi-member CuboidTags. + // @example + // # Expands the high value of the cuboid "my_cuboid" by 15,16,17 on one side and notes it as "my_expanded_cuboid". + // # If "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min), then expanding it by 15,16,17 will make "my_expanded_cuboid" + // # span from 25,26,27 (max) to 5,5,5 (min). + // - note as:my_expanded_cuboid + // @example + // # Expands the low value of the cuboid "my_cuboid" by -15 (-15,-15,-15) on one side and notes it as "my_expanded_cuboid". + // # If "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min), then shrinking it by -15 will make "my_expanded_cuboid" + // # span from 10,10,10 (max) to -10,-10,-10 (min). + // - note as:my_expanded_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "expand_one_side", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1332,6 +1433,16 @@ public static void register() { // Inverted by <@link tag CuboidTag.expand_one_side> // Not valid for multi-member CuboidTags. // If you shrink past the limits of the cuboid's size, the cuboid will flip and start expanding the opposite direction. + // @example + // # Shrinks the high value of the cuboid "my_cuboid" by 15,16,17 on one side and notes it as "my_smaller_cuboid". + // # If "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min), then shrinking it by 15,16,17 will make "my_smaller_cuboid" + // # span from 5,5,5 (max) to -5,-6,-7 (min). + // - note as:my_smaller_cuboid + // @example + // # Shrinks the low value of the cuboid "my_cuboid" by -15 (-15,-15,-15) on one side and notes it as "my_smaller_cuboid". + // # If "my_cuboid" spans from 10,10,10 (max) to 5,5,5 (min), then shrinking it by -15 will make "my_smaller_cuboid" + // # span from 20,20,20 (max) to 10,10,10 (min). + // - note as:my_smaller_cuboid // --> tagProcessor.registerTag(CuboidTag.class, "shrink_one_side", (attribute, cuboid) -> { if (!attribute.hasParam()) { @@ -1375,6 +1486,12 @@ public static void register() { // @returns ListTag(ChunkTag) // @description // Gets a list of all chunks entirely within the CuboidTag (ignoring the Y axis). + // @example + // # Loads the chunks that are fully within the cuboid "my_cuboid". + // # If "my_cuboid" spans from "15,50,15" (max) to "7,64,5" (min), then this will return an empty list and not load any chunks + // # because no chunks are fully enclosed within it. But, for example, if it spans from "21,70,21" (max) to "-10,64,-9" (min), + // # then this will return a list with chunk 0,0 and load it because the cuboid surrounds that chunk. + // - chunkload // --> tagProcessor.registerTag(ListTag.class, "chunks", (attribute, cuboid) -> { ListTag chunks = new ListTag(); @@ -1408,6 +1525,11 @@ public static void register() { // @returns ListTag(ChunkTag) // @description // Gets a list of all chunks partially or entirely within the CuboidTag. + // @example + // # Loads the chunks that are within the cuboid "my_cuboid", even if they are partially within the cuboid. + // # If "my_cuboid" spans from "15,50,15" (max) to "7,64,5" (min), then this will return a list with chunk 0,0 + // # in it, because the chunk is partially contained by the cuboid. + // - chunkload // --> tagProcessor.registerTag(ListTag.class, "partial_chunks", (attribute, cuboid) -> { ListTag chunks = new ListTag(); @@ -1428,6 +1550,10 @@ public static void register() { // @returns ElementTag // @description // Gets the name of a noted CuboidTag. If the cuboid isn't noted, this is null. + // @example + // # For example, this might return something like: + // # "The cuboid you are currently in is noted as: my_cuboid!" + // - narrate "The cuboid you are currently in is noted as: !" // --> tagProcessor.registerTag(ElementTag.class, "note_name", (attribute, cuboid) -> { String noteName = NoteManager.getSavedId(cuboid); @@ -1547,6 +1673,15 @@ public void adjust(Mechanism mechanism) { // // ]> // ].at[<#>]> + // @example + // # Adds "my_second_cuboid" as a member to "my_cuboid" and narrates a formatted list of members. + // # For example, if "my_cuboid" is "world,5,5,5,10,10,10" and "my_second_cuboid" is "world,12,12,12,22,22,22", + // # then this will narrate "world,5,5,5,10,10,10 and world,12,12,12,22,22,22". + // - adjust add_member:my_second_cuboid + // - narrate + // @example + // # Adds "my_second_cuboid" as a member to "my_cuboid" at the second index. + // - adjust add_member:2,my_second_cuboid // --> if (mechanism.matches("add_member")) { if (noteName != null) { @@ -1581,6 +1716,12 @@ public void adjust(Mechanism mechanism) { // Remove a sub-member from the cuboid at the specified index. // @tags // ]> + // @example + // # Removes the second member from "my_cuboid" and narrates a formatted list of members. + // # For example, if "my_cuboid" is "world,5,5,5,10,10,10" and it's second member is "world,12,12,12,22,22,22", + // # after the member is removed then this will narrate "world,5,5,5,10,10,10". + // - adjust remove_member:2 + // - narrate // --> if (mechanism.matches("remove_member") && mechanism.requireInteger()) { if (pairs.size() == 1) { diff --git a/plugin/src/main/java/com/denizenscript/denizen/objects/EllipsoidTag.java b/plugin/src/main/java/com/denizenscript/denizen/objects/EllipsoidTag.java index c0c064edb3..9ad0c57bb0 100644 --- a/plugin/src/main/java/com/denizenscript/denizen/objects/EllipsoidTag.java +++ b/plugin/src/main/java/com/denizenscript/denizen/objects/EllipsoidTag.java @@ -422,6 +422,9 @@ public static void register() { // @description // Returns a random decimal location within the ellipsoid. // Note that distribution of results will not be completely even. + // @example + // # Displays a debugblock at a random location within the ellipsoid "my_ellipsoid". + // - debugblock // --> tagProcessor.registerTag(LocationTag.class, "random", (attribute, object) -> { // This is an awkward hack to try to weight towards the center a bit (to counteract the weight-away-from-center that would otherwise happen). @@ -444,6 +447,9 @@ public static void register() { // @returns LocationTag // @description // Returns the center location of the ellipsoid. + // @example + // # Displays a debugblock at center location of the ellipsoid "my_ellipsoid". + // - debugblock // --> tagProcessor.registerTag(LocationTag.class, "location", (attribute, object) -> { return object.center; @@ -454,6 +460,9 @@ public static void register() { // @returns LocationTag // @description // Returns the size of the ellipsoid. + // @example + // # For example, this can return: "The size of the ellipsoid 'my_ellipsoid' is: 10,10,10!" + // - narrate "The size of the ellipsoid 'my_ellipsoid' is: !" // --> tagProcessor.registerTag(LocationTag.class, "size", (attribute, object) -> { return object.size; @@ -464,6 +473,11 @@ public static void register() { // @returns EllipsoidTag // @description // Returns a copy of this ellipsoid, shifted by the input location. + // @example + // # Shifts the ellipsoid by 10,10,10 and notes it as "my_shifted_ellipsoid". + // # For example, if "my_ellipsoid" has a location of "5,5,5", and it's added by "10,10,10", + // # "my_shifted_cuboid" will have a location of "15,15,15". + // - note as:my_shifted_ellipsoid // --> tagProcessor.registerTag(EllipsoidTag.class, "add", (attribute, object) -> { if (!attribute.hasParam()) { @@ -478,6 +492,12 @@ public static void register() { // @returns EllipsoidTag // @description // Returns a copy of this ellipsoid, with the size value adapted to include the specified world location. + // @example + // # Expands "my_ellipsoid" to include the player's location and notes it as "my_new_ellipsoid". + // # For example, if "my_ellipsoid" has a location of "5,5,5" and a size of "8,8,8", + // # and the player had a location of 20,22,24, then "my_new_ellipsoid" will have a location of + // # "5,5,5" and a size of "26,29,33" (rounded). + // - note ]> as:my_new_ellipsoid // --> tagProcessor.registerTag(EllipsoidTag.class, "include", (attribute, object) -> { if (!attribute.hasParam()) { @@ -528,6 +548,10 @@ else if (projZ >= projX && projZ >= projY) { // @returns EllipsoidTag // @description // Returns a copy of this ellipsoid, set to the specified location. + // @example + // # Sets the location of "my_ellipsoid" to be the player's location. + // # For example, if the player's location is 10,15,20, then "my_new_ellipsoid" will have a location of 10,15,20. + // - note ]> as:my_new_ellipsoid // --> tagProcessor.registerTag(EllipsoidTag.class, "with_location", (attribute, object) -> { if (!attribute.hasParam()) { @@ -542,6 +566,9 @@ else if (projZ >= projX && projZ >= projY) { // @returns EllipsoidTag // @description // Returns a copy of this ellipsoid, set to the specified size. + // @example + // # Changes the size of "my_ellipsoid" to be 20,20,20 and notes it as "my_new_ellipsoid". + // - note as:my_new_ellipsoid // --> tagProcessor.registerTag(EllipsoidTag.class, "with_size", (attribute, object) -> { if (!attribute.hasParam()) { @@ -556,6 +583,11 @@ else if (projZ >= projX && projZ >= projY) { // @returns ListTag(ChunkTag) // @description // Returns a list of all chunks that this ellipsoid touches at all (note that no valid ellipsoid tag can ever totally contain a chunk, due to vertical limits and roundness). + // @example + // # Loads the chunks that touch the ellipsoid "my_ellipsoid". + // # For example, if "my_ellipsoid" had a size of "9,4,6" and a location of "-10,70,-9", + // # this will return a list containing chunks -2,-1 and -1,-1. + // - chunkload // --> tagProcessor.registerTag(ListTag.class, "chunks", (attribute, object) -> { ListTag chunks = new ListTag(); @@ -585,6 +617,10 @@ else if (projZ >= projX && projZ >= projY) { // @returns ElementTag // @description // Gets the name of a noted EllipsoidTag. If the ellipsoid isn't noted, this is null. + // @example + // # For example, this might return something like: + // # "The ellipsoid you are currently in is noted as: my_ellipsoid!" + // - narrate "The ellipsoid you are currently in is noted as: !" // --> tagProcessor.registerTag(ElementTag.class, "note_name", (attribute, ellipsoid) -> { String noteName = NoteManager.getSavedId(ellipsoid);