From 475612bb498b40128e19d30b47a2eae3d90ba19a Mon Sep 17 00:00:00 2001 From: Brando! <63469489+BreadcrumbIsTaken@users.noreply.github.com> Date: Fri, 25 Nov 2022 02:54:49 -0800 Subject: [PATCH] `AreaContainmentObject` and `BiomeTag` examples (#2394) * Add `AreaContainmentObject` tag examples. Also de-dented code for 'spawnable_blocks' to make it look more uniform :) * Add `BiomeTag` tag examples. Mechanism not done as they can't be tested currently. Fixed up some funky new lines here and there. * Add better example for `` * Change `` one more time. Returns specific data, and so it should probably be shown in the example. * Update a few examples to have more clear comments. * Clean up and `BiomeTag` mech examples. --- .../objects/AreaContainmentObject.java | 73 ++++++++++++++++--- .../denizen/objects/BiomeTag.java | 38 +++++++++- 2 files changed, 97 insertions(+), 14 deletions(-) diff --git a/plugin/src/main/java/com/denizenscript/denizen/objects/AreaContainmentObject.java b/plugin/src/main/java/com/denizenscript/denizen/objects/AreaContainmentObject.java index 8a83f436ae..5746106649 100644 --- a/plugin/src/main/java/com/denizenscript/denizen/objects/AreaContainmentObject.java +++ b/plugin/src/main/java/com/denizenscript/denizen/objects/AreaContainmentObject.java @@ -96,6 +96,9 @@ static void registerTags(Class type, Objec // @description // Returns a cuboid approximately representing the maximal bounding box of the area (anything this cuboid does not contain, is also not contained by the area, but not vice versa). // For single-member CuboidTags, this tag returns a copy of the cuboid. + // @example + // # Narrates the cuboids bounding box, which is just the cuboid. + // - narrate // --> processor.registerTag(CuboidTag.class, "bounding_box", (attribute, area) -> { return area.getCuboidBoundary(); @@ -107,6 +110,8 @@ static void registerTags(Class type, Objec // @returns WorldTag // @description // Returns the area's world. + // @example + // - narrate "The cuboid, 'my_cuboid', is in world: !" // --> processor.registerTag(WorldTag.class, "world", (attribute, area) -> { return area.getWorld(); @@ -117,6 +122,10 @@ static void registerTags(Class type, Objec // @returns ListTag(PlayerTag) // @description // Gets a list of all players currently within the area. + // @example + // # Narrates a list of players' names that are within the area separated by a comma and a space. + // # For example: "List of players in 'my_cuboid': steve, alex, john, jane" + // - narrate "List of players in 'my_cuboid': " // --> processor.registerTag(ListTag.class, "players", (attribute, area) -> { ListTag result = new ListTag(); @@ -133,6 +142,10 @@ static void registerTags(Class type, Objec // @returns ListTag(NPCTag) // @description // Gets a list of all NPCs currently within the area. + // @example + // # Narrates a list of NPCs' names that are within the area separated by a comma and a space. + // # For example: "List of NPCs in 'my_cuboid': steve, alex, john, jane" + // - narrate "List of NPCs in 'my_cuboid': " // --> if (Depends.citizens != null) { processor.registerTag(ListTag.class, "npcs", (attribute, area) -> { @@ -152,6 +165,10 @@ static void registerTags(Class type, Objec // @returns ListTag(EntityTag) // @description // Gets a list of all entities currently within the area, with an optional search parameter for the entity. + // @example + // # Narrates the locations of the entities that match 'axolotl' within the area. + // - foreach as:entity: + // - narrate <[entity].location> // --> processor.registerTag(ListTag.class, "entities", (attribute, area) -> { String matcher = attribute.hasParam() ? attribute.getParam() : null; @@ -173,6 +190,10 @@ static void registerTags(Class type, Objec // @description // Gets a list of all living entities currently within the area. // This includes Players, mobs, NPCs, etc., but excludes dropped items, experience orbs, etc. + // @example + // # Narrates the name of all the living entities within the area. + // - foreach as:entity: + // - narrate <[entity].name> // --> processor.registerTag(ListTag.class, "living_entities", (attribute, area) -> { ListTag result = new ListTag(); @@ -189,6 +210,12 @@ static void registerTags(Class type, Objec // @returns ElementTag(Boolean) // @description // Returns a boolean indicating whether the specified location is inside this area. + // @example + // # Checks to see if "my_cuboid" contains the player's location. + // - if ]>: + // - narrate "It is contained within 'my_cuboid'!" + // - else: + // - narrate "It is not contained within 'my_cuboid'!" // --> processor.registerTag(ElementTag.class, LocationTag.class, "contains", (attribute, area, loc) -> { return new ElementTag(area.doesContainLocation(loc)); @@ -200,6 +227,10 @@ static void registerTags(Class type, Objec // @description // Returns each block location within the area. // Optionally, specify a material matcher to only return locations with that block type. + // @example + // # Narrates the locations of blocks that match "*planks" within the area. + // - foreach as:plank: + // - narrate <[plank]> // --> processor.registerTag(ListTag.class, "blocks", (attribute, area) -> { if (attribute.hasParam()) { @@ -223,20 +254,24 @@ static void registerTags(Class type, Objec // Returns each LocationTag within the area that is safe for players or similar entities to spawn in. // Optionally, specify a material matcher to only return locations with that block type. // Uses the same spawnable check as <@link tag LocationTag.is_spawnable> + // @example + // # Spawns a creeper at a random spawnable block within the area. + // - define block + // - spawn creeper <[block]> // --> processor.registerTag(ListTag.class, "spawnable_blocks", (attribute, area) -> { - NMSHandler.chunkHelper.changeChunkServerThread(area.getWorld().getWorld()); - try { - if (attribute.hasParam()) { - String matcher = attribute.getParam(); - Predicate predicate = (l) -> SpawnableHelper.isSpawnable(l) && new LocationTag(l.getBlock().getRelative(0, -1, 0).getLocation()).tryAdvancedMatcher(matcher); - return area.getBlocks(predicate); - } - return area.getBlocks(SpawnableHelper::isSpawnable); - } - finally { - NMSHandler.chunkHelper.restoreServerThread(area.getWorld().getWorld()); + NMSHandler.chunkHelper.changeChunkServerThread(area.getWorld().getWorld()); + try { + if (attribute.hasParam()) { + String matcher = attribute.getParam(); + Predicate predicate = (l) -> SpawnableHelper.isSpawnable(l) && new LocationTag(l.getBlock().getRelative(0, -1, 0).getLocation()).tryAdvancedMatcher(matcher); + return area.getBlocks(predicate); } + return area.getBlocks(SpawnableHelper::isSpawnable); + } + finally { + NMSHandler.chunkHelper.restoreServerThread(area.getWorld().getWorld()); + } }, "get_spawnable_blocks"); // <--[tag] @@ -245,6 +280,10 @@ static void registerTags(Class type, Objec // @description // Gets a list of all block locations with a specified flag within the area. // Searches the internal flag lists, rather than through all possible blocks. + // @example + // # Narrates the locations of blocks that are flagged "my_flag" + // - foreach as:block: + // - narrate <[block].location> // --> processor.registerTag(ListTag.class, ElementTag.class, "blocks_flagged", (attribute, area, flagName) -> { return area.getBlocksFlagged(CoreUtilities.toLowerCase(flagName.toString()), attribute); @@ -256,6 +295,9 @@ static void registerTags(Class type, Objec // @description // Returns each block location on the 3D outer shell of the area. // This tag is useful for displaying particles or blocks to mark the boundary of the area. + // @example + // # Plays the "TOTEM" effect in the shell of the area to the player. + // - playeffect effect:TOTEM at: offset:0 targets: // --> processor.registerTag(ListTag.class, "shell", (attribute, area) -> { return area.getShell(); @@ -266,6 +308,12 @@ static void registerTags(Class type, Objec // @returns ElementTag(Boolean) // @description // Returns whether this area is fully inside another cuboid. + // @example + // # Checks to see if "my_cuboid" is within "my_bigger_cuboid". + // - if ]>: + // - narrate "It is fully within 'my_bigger_cuboid'!" + // - else: + // - narrate "It is not fully within 'my_bigger_cuboid'!" // --> processor.registerTag(ElementTag.class, CuboidTag.class, "is_within", (attribute, area, cub2) -> { CuboidTag cuboid = area instanceof CuboidTag ? (CuboidTag) area : area.getCuboidBoundary(); @@ -302,6 +350,9 @@ static void registerTags(Class type, Objec // @returns AreaObject // @description // Returns a copy of the area, with the specified world. + // @example + // # Notes a copy of "my_cuboid" but with the world "world_the_end". + // - note my_new_cuboid // --> processor.registerTag(type, WorldTag.class, "with_world", (attribute, area, world) -> { return (T) area.withWorld(world); diff --git a/plugin/src/main/java/com/denizenscript/denizen/objects/BiomeTag.java b/plugin/src/main/java/com/denizenscript/denizen/objects/BiomeTag.java index 723fdcd2b0..7ef3dde66d 100644 --- a/plugin/src/main/java/com/denizenscript/denizen/objects/BiomeTag.java +++ b/plugin/src/main/java/com/denizenscript/denizen/objects/BiomeTag.java @@ -180,6 +180,9 @@ public static void registerTags() { // @description // Returns this biome's downfall type for when a world has weather. // This can be RAIN, SNOW, or NONE. + // @example + // # In a plains biome, this fills with 'RAIN'. + // - narrate "The downfall type in plains biomes is: !" // --> tagProcessor.registerTag(ElementTag.class, "downfall_type", (attribute, object) -> { return new ElementTag(object.biome.getDownfallType()); @@ -190,6 +193,9 @@ public static void registerTags() { // @returns ElementTag // @description // Returns this biome's name. + // @example + // # In a plains biome, this fills with 'plains'. + // - narrate "You are currently in a biome!" // --> tagProcessor.registerTag(ElementTag.class, "name", (attribute, object) -> { return new ElementTag(CoreUtilities.toLowerCase(object.biome.getName())); @@ -201,20 +207,28 @@ public static void registerTags() { // @mechanism BiomeTag.humidity // @description // Returns the humidity of this biome. + // @example + // # In a plains biome, this fills with '0.4'. + // - narrate "Humidity in a plains biome is ! So humid!" // --> tagProcessor.registerTag(ElementTag.class, "humidity", (attribute, object) -> { return new ElementTag(object.biome.getHumidity()); }); + // <--[tag] // @attribute // @returns ElementTag(Decimal) // @mechanism BiomeTag.temperature // @description // Returns the temperature of this biome. + // @example + // # In a plains biome, this fills with '0.8'. + // - narrate "Stay warm! In a plains biome, the temperature is !" // --> tagProcessor.registerTag(ElementTag.class, "temperature", (attribute, object) -> { return new ElementTag(object.biome.getTemperature()); }); + // <--[tag] // @attribute )]> // @returns ListTag(EntityTag) @@ -222,7 +236,11 @@ public static void registerTags() { // Returns all entities that spawn naturally in this biome. // Optionally specify a type as: AMBIENT, CREATURES, MONSTERS, WATER, or ALL. // (By default, will be "ALL"). - // + // @example + // # Narrates the types of entities of type MONSTERS that can spawn in the player's biome. + // # For example, in a plains biome this could contain "SPIDER", "ZOMBIE", "CREEPER", etc. + // - foreach as:entity: + // - narrate <[entity]> // --> tagProcessor.registerTag(ListTag.class, "spawnable_entities", (attribute, object) -> { List entityTypes; @@ -297,9 +315,13 @@ public void adjust(Mechanism mechanism) { // @description // Sets the humidity for this biome server-wide. // If this is greater than 0.85, fire has less chance - // to spread in this biome. + // to spread in this biome. Resets on server restart. // @tags // + // @example + // # Adjusts the humidity of the plains biome on server start. + // on server start: + // - adjust humidity:0.5 // --> if (mechanism.matches("humidity") && mechanism.requireFloat()) { biome.setHumidity(mechanism.getValue().asFloat()); @@ -312,8 +334,13 @@ public void adjust(Mechanism mechanism) { // @description // Sets the temperature for this biome server-wide. // If this is less than 0.15, snow will form on the ground when weather occurs in the world and a layer of ice will form over water. + // Resets on server restart. // @tags // + // @example + // # Adjusts the temperature of the plains biome on server start. + // on server start: + // - adjust temperature:0.5 // --> if (mechanism.matches("temperature") && mechanism.requireFloat()) { biome.setTemperature(mechanism.getValue().asFloat()); @@ -325,9 +352,14 @@ public void adjust(Mechanism mechanism) { // @input ElementTag // @description // Sets the downfall-type for this biome server-wide. - // This can be RAIN, SNOW, or NONE. + // This can be RAIN, SNOW, or NONE. Resets on server restart. // @tags // + // @example + // # Adjusts the downfall type of the plains biome on server start. + // on server start: + // - adjust temperature:-0.2 + // - adjust downfall_type:SNOW // --> if (mechanism.matches("downfall_type") && mechanism.requireEnum(BiomeNMS.DownfallType.class)) { biome.setPrecipitation(BiomeNMS.DownfallType.valueOf(mechanism.getValue().asString().toUpperCase()));