Above Ground Option Added

Author: cev-api

README.md

@@ -223,6 +223,11 @@ Examples:
 ### Larger Scan Radius
 - Extended up to 65×65 chunks for all chunk-based features.  
 
+### Above Ground (New Option)
+- ItemESP, MobSearch, ChestESP, BedESP, SignESP, PortalESP, RedstoneESP and WorkstationESP now have an adjustable Y limit (default 62 which is approximately sea level)
+- There is a global toggle and setting that can apply to all, or the user can set toggle and set them individually in the hack's settings (```.aboveground on/off```, ```.aboveground toggle```, ```.aboveground y #```)
+- This will help prevent you from detecting inaccessible mobs/items and essentially only scanning the surface of the world 
+
 ### Sticky Area (New Option)
 - Added to chunk-based ESPs (Search, Portal ESP, BedESP, SignESP, WorkstationESP, RedstoneESP, ChestESP).  
 - Keeps results anchored as you move. Default OFF.  

src/main/java/net/wurstclient/command/CmdList.java

@@ -59,6 +59,7 @@ public final class CmdList
 	public final SetColorCmd setColorCmd = new SetColorCmd();
 	public final SetModeCmd setModeCmd = new SetModeCmd();
 	public final SetSliderCmd setSliderCmd = new SetSliderCmd();
+	public final AboveGroundCmd aboveGroundCmd = new AboveGroundCmd();
 	public final SettingsCmd settingsCmd = new SettingsCmd();
 	public final NecoCmd NecoCmd = new NecoCmd();
 	public final TCmd tCmd = new TCmd();

src/main/java/net/wurstclient/commands/AboveGroundCmd.java

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2014-2025 Wurst-Imperium and contributors.
+ *
+ * This source code is subject to the terms of the GNU General Public
+ * License, version 3. If a copy of the GPL was not distributed with this
+ * file, You can obtain one at: https://www.gnu.org/licenses/gpl-3.0.txt
+ */
+package net.wurstclient.commands;
+
+import net.wurstclient.WurstClient;
+import net.wurstclient.command.CmdException;
+import net.wurstclient.command.CmdSyntaxError;
+import net.wurstclient.command.Command;
+import net.wurstclient.util.ChatUtils;
+import net.wurstclient.util.MathUtils;
+
+public final class AboveGroundCmd extends Command
+{
+	public AboveGroundCmd()
+	{
+		super("aboveground",
+			"Global above-ground ESP filter for supported hacks.",
+			".aboveground (on|off|toggle)", ".aboveground y <value>",
+			".aboveground <value>");
+	}
+	
+	@Override
+	public void call(String[] args) throws CmdException
+	{
+		if(args.length == 0)
+			throw new CmdSyntaxError();
+		String a = args[0].toLowerCase();
+		// Single-word actions
+		if(args.length == 1)
+		{
+			if(a.equals("on"))
+			{
+				WurstClient.INSTANCE.getHax().setAboveGroundFilterEnabled(true);
+				ChatUtils.message(
+					"Above-ground filter enabled for supported hacks.");
+				return;
+			}
+			if(a.equals("off"))
+			{
+				WurstClient.INSTANCE.getHax()
+					.setAboveGroundFilterEnabled(false);
+				ChatUtils.message(
+					"Above-ground filter disabled for supported hacks.");
+				return;
+			}
+			if(a.equals("toggle"))
+			{
+				// Toggle: invert by enabling when currently all disabled is
+				// unknown.
+				// We'll simply enable if arg toggled on; user can set
+				// explicitly.
+				// For simplicity, toggle will enable when called.
+				WurstClient.INSTANCE.getHax().setAboveGroundFilterEnabled(true);
+				ChatUtils.message("Above-ground filter toggled (enabled).");
+				return;
+			}
+			// numeric provided -> set Y
+			if(MathUtils.isDouble(a))
+			{
+				int y = (int)Double.parseDouble(a);
+				WurstClient.INSTANCE.getHax().setAboveGroundFilterY(y);
+				ChatUtils.message(
+					"Above-ground Y set to " + y + " for supported hacks.");
+				return;
+			}
+			throw new CmdSyntaxError();
+		}
+		
+		// Two-argument forms: "y <value>" or "on/off <value>" to enable and set
+		// Y
+		if(args.length == 2)
+		{
+			if(a.equals("y") || a.equals("set"))
+			{
+				if(!MathUtils.isDouble(args[1]))
+					throw new CmdSyntaxError("Y must be a number.");
+				int y = (int)Double.parseDouble(args[1]);
+				WurstClient.INSTANCE.getHax().setAboveGroundFilterY(y);
+				ChatUtils.message(
+					"Above-ground Y set to " + y + " for supported hacks.");
+				return;
+			}
+			if(a.equals("on") || a.equals("off"))
+			{
+				boolean enabled = a.equals("on");
+				WurstClient.INSTANCE.getHax()
+					.setAboveGroundFilterEnabled(enabled);
+				if(!MathUtils.isDouble(args[1]))
+				{
+					ChatUtils.message("Above-ground filter "
+						+ (enabled ? "enabled" : "disabled") + ".");
+					return;
+				}
+				int y = (int)Double.parseDouble(args[1]);
+				WurstClient.INSTANCE.getHax().setAboveGroundFilterY(y);
+				ChatUtils.message(
+					"Above-ground filter " + (enabled ? "enabled" : "disabled")
+						+ " and Y set to " + y + ".");
+				return;
+			}
+			throw new CmdSyntaxError();
+		}
+		throw new CmdSyntaxError();
+	}
+}

src/main/java/net/wurstclient/hack/AboveGroundFilterManager.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2014-2025 Wurst-Imperium and contributors.
+ *
+ * This source code is subject to the terms of the GNU General Public
+ * License, version 3. If a copy of the GPL was not distributed with this
+ * file, You can obtain one at: https://www.gnu.org/licenses/gpl-3.0.txt
+ */
+package net.wurstclient.hack;
+
+import java.lang.reflect.Field;
+
+import net.wurstclient.settings.CheckboxSetting;
+import net.wurstclient.settings.SliderSetting;
+
+/**
+ * Utility to toggle or set the above-ground filter settings on hacks that
+ * expose them. Uses reflection to avoid tightly coupling hack classes.
+ */
+public final class AboveGroundFilterManager
+{
+	public static void toggle(HackList hacks, boolean enabled)
+	{
+		for(Hack h : hacks.getAllHax())
+		{
+			try
+			{
+				Field f = findField(h.getClass(), "onlyAboveGround");
+				if(f != null)
+				{
+					f.setAccessible(true);
+					Object val = f.get(h);
+					if(val instanceof CheckboxSetting cs)
+						cs.setChecked(enabled);
+				}
+			}catch(Throwable ignored)
+			{}
+		}
+	}
+	
+	public static void setY(HackList hacks, int y)
+	{
+		for(Hack h : hacks.getAllHax())
+		{
+			try
+			{
+				Field f = findField(h.getClass(), "aboveGroundY");
+				if(f != null)
+				{
+					f.setAccessible(true);
+					Object val = f.get(h);
+					if(val instanceof SliderSetting ss)
+						ss.setValue(y);
+				}
+			}catch(Throwable ignored)
+			{}
+		}
+	}
+	
+	private static Field findField(Class<?> cls, String name)
+	{
+		Class<?> c = cls;
+		while(c != null && c != Object.class)
+		{
+			try
+			{
+				Field f = c.getDeclaredField(name);
+				return f;
+			}catch(NoSuchFieldException e)
+			{
+				c = c.getSuperclass();
+			}
+		}
+		return null;
+	}
+}

src/main/java/net/wurstclient/hack/HackList.java

@@ -242,6 +242,24 @@ public HackList(Path enabledHacksFile, Path favoriteHacksFile)
 		eventManager.add(UpdateListener.class, this);
 	}
 
+	/**
+	 * Toggle the per-hack "Only above ground" filter for all hacks that
+	 * expose the setting. Useful for binding to a key or calling from the
+	 * command interface.
+	 */
+	public void setAboveGroundFilterEnabled(boolean enabled)
+	{
+		AboveGroundFilterManager.toggle(this, enabled);
+	}
+	
+	/**
+	 * Set the Y threshold used by hacks that expose the above-ground filter.
+	 */
+	public void setAboveGroundFilterY(int y)
+	{
+		AboveGroundFilterManager.setY(this, y);
+	}
+	
 	@Override
 	public void onUpdate()
 	{

src/main/java/net/wurstclient/hacks/BedEspHack.java

@@ -31,6 +31,7 @@
 import net.wurstclient.settings.ChunkAreaSetting;
 import net.wurstclient.settings.ColorSetting;
 import net.wurstclient.settings.EspStyleSetting;
+import net.wurstclient.settings.SliderSetting;
 import net.wurstclient.util.RenderUtils;
 import net.wurstclient.util.chunk.ChunkSearcher.Result;
 import net.wurstclient.util.chunk.ChunkSearcherCoordinator;
@@ -61,6 +62,13 @@ public final class BedEspHack extends Hack implements UpdateListener,
 		"The area around the player to search in.\n"
 			+ "Higher values require a faster computer.");
 
+	// Above-ground filter
+	private final net.wurstclient.settings.CheckboxSetting onlyAboveGround =
+		new net.wurstclient.settings.CheckboxSetting("Above ground only",
+			"Only show beds at or above the configured Y level.", false);
+	private final SliderSetting aboveGroundY = new SliderSetting(
+		"Above ground Y", 62, 0, 255, 1, SliderSetting.ValueDisplay.INTEGER);
+	
 	private final BiPredicate<BlockPos, BlockState> query =
 		(pos, state) -> state.getBlock() instanceof BedBlock;
 
@@ -81,6 +89,8 @@ public BedEspHack()
 		addSetting(showCountInHackList);
 		addSetting(area);
 		addSetting(stickyArea);
+		addSetting(onlyAboveGround);
+		addSetting(aboveGroundY);
 	}
 
 	@Override
@@ -199,6 +209,9 @@ public String getRenderName()
 
 	private void addToGroupBoxes(Result result)
 	{
+		if(onlyAboveGround.isChecked()
+			&& result.pos().getY() < aboveGroundY.getValue())
+			return;
 		for(BedEspBlockGroup group : groups)
 		{
 			group.add(result);

src/main/java/net/wurstclient/hacks/ChestEspHack.java

@@ -33,6 +33,7 @@
 import net.wurstclient.settings.CheckboxSetting;
 import net.wurstclient.settings.ColorSetting;
 import net.wurstclient.settings.EspStyleSetting;
+import net.wurstclient.settings.SliderSetting;
 import net.wurstclient.util.RenderUtils;
 import net.wurstclient.util.chunk.ChunkUtils;
 
@@ -141,6 +142,14 @@ public class ChestEspHack extends Hack implements UpdateListener,
 
 	private int foundCount;
 
+	// Above-ground filter
+	private final CheckboxSetting onlyAboveGround =
+		new CheckboxSetting("Above ground only",
+			"Only show chests/containers at or above the configured Y level.",
+			false);
+	private final SliderSetting aboveGroundY = new SliderSetting(
+		"Above ground Y", 62, 0, 255, 1, SliderSetting.ValueDisplay.INTEGER);
+	
 	public ChestEspHack()
 	{
 		super("ChestESP");
@@ -149,6 +158,8 @@ public ChestEspHack()
 		addSetting(stickyArea);
 		groups.stream().flatMap(ChestEspGroup::getSettings)
 			.forEach(this::addSetting);
+		addSetting(onlyAboveGround);
+		addSetting(aboveGroundY);
 		addSetting(showCountInHackList);
 	}
 
@@ -182,6 +193,10 @@ public void onUpdate()
 				.collect(Collectors.toCollection(ArrayList::new));
 
 		for(BlockEntity blockEntity : blockEntities)
+		{
+			if(onlyAboveGround.isChecked()
+				&& blockEntity.getPos().getY() < aboveGroundY.getValue())
+				continue;
 			if(blockEntity instanceof TrappedChestBlockEntity)
 				trapChests.add(blockEntity);
 			else if(blockEntity instanceof ChestBlockEntity)
@@ -205,15 +220,22 @@ else if(blockEntity instanceof CrafterBlockEntity)
 			else if(blockEntity instanceof AbstractFurnaceBlockEntity)
 				furnaces.add(blockEntity);
 
+		}
+		
 		for(Entity entity : MC.world.getEntities())
+		{
+			if(onlyAboveGround.isChecked()
+				&& entity.getY() < aboveGroundY.getValue())
+				continue;
 			if(entity instanceof ChestMinecartEntity)
 				chestCarts.add(entity);
 			else if(entity instanceof HopperMinecartEntity)
 				hopperCarts.add(entity);
 			else if(entity instanceof ChestBoatEntity
 				|| entity instanceof ChestRaftEntity)
 				chestBoats.add(entity);
-			
+		}
+		
 		// compute found count from enabled groups (clamped)
 		int total = groups.stream().mapToInt(g -> g.getBoxes().size()).sum();
 		total += entityGroups.stream().mapToInt(g -> g.getBoxes().size()).sum();