Feature - Height Limit Module

api/src/main/java/com/lunarclient/apollo/module/heightlimit/HeightLimit.java

@@ -0,0 +1,70 @@
+/*
+ * This file is part of Apollo, licensed under the MIT License.
+ *
+ * Copyright (c) 2026 Moonsworth
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.lunarclient.apollo.module.heightlimit;
+
+import lombok.Builder;
+import lombok.Getter;
+import net.kyori.adventure.text.Component;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Range;
+
+/**
+ * Represents a height limit which can be shown on the client.
+ *
+ * @since 1.2.9
+ */
+@Getter
+@Builder
+public final class HeightLimit {
+
+    /**
+     * Returns the height limit {@link String} world name.
+     *
+     * @return the height limit world name
+     * @since 1.2.9
+     */
+    String world;
+
+    /**
+     * Returns the height limit {@link Integer} Y level where block placement
+     * is denied.
+     *
+     * <p>The highest buildable layer is {@code limit - 1}.</p>
+     *
+     * @return the height limit
+     * @since 1.2.9
+     */
+    @Range(from = 1, to = Integer.MAX_VALUE) int limit;
+
+    /**
+     * Returns the height limit {@link Component} display name.
+     *
+     * <p>Shown on the client's height limit HUD.</p>
+     *
+     * @return the height limit display name
+     * @since 1.2.9
+     */
+    @Nullable Component displayName;
+
+}

api/src/main/java/com/lunarclient/apollo/module/heightlimit/HeightLimitModule.java

@@ -0,0 +1,118 @@
+/*
+ * This file is part of Apollo, licensed under the MIT License.
+ *
+ * Copyright (c) 2026 Moonsworth
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.lunarclient.apollo.module.heightlimit;
+
+import com.lunarclient.apollo.module.ApolloModule;
+import com.lunarclient.apollo.module.ModuleDefinition;
+import com.lunarclient.apollo.option.ListOption;
+import com.lunarclient.apollo.option.Option;
+import com.lunarclient.apollo.recipients.Recipients;
+import io.leangen.geantyref.TypeToken;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Represents the height limit module.
+ *
+ * <p>Sets the build-height limit shown by the clients Height Limit mod
+ * (block overlay and HUD display). The client resolves the active limit
+ * against the world the player is currently in.</p>
+ *
+ * <p>This module only provides a visual indicator for the player. The
+ * server is still responsible for cancelling block placement above the
+ * height limit.</p>
+ *
+ * @since 1.2.9
+ */
+@ApiStatus.NonExtendable
+@ModuleDefinition(id = "height_limit", name = "Height Limit")
+public abstract class HeightLimitModule extends ApolloModule {
+
+    private static final HeightLimit OVERWORLD_HEIGHT_LIMIT = HeightLimit.builder()
+        .world("world")
+        .limit(200)
+        .displayName(Component.text("Overworld", NamedTextColor.GOLD))
+        .build();
+
+    /**
+     * Returns the default list of height limits to send to the player.
+     *
+     * @since 1.2.9
+     */
+    public static final ListOption<HeightLimit> DEFAULT_HEIGHT_LIMITS = Option.<HeightLimit>list()
+        .comment("Sets the default height limits to send to the player.")
+        .node("default-height-limits").type(new TypeToken<List<HeightLimit>>() {})
+        .defaultValue(new ArrayList<>(Collections.singletonList(HeightLimitModule.OVERWORLD_HEIGHT_LIMIT)))
+        .build();
+
+    protected HeightLimitModule() {
+        this.registerOptions(
+            ApolloModule.ENABLE_OPTION_OFF,
+            HeightLimitModule.DEFAULT_HEIGHT_LIMITS
+        );
+    }
+
+    /**
+     * Overrides the {@link HeightLimit} for the {@link Recipients}.
+     *
+     * <p>Sending a height limit for an already-known world replaces
+     * that worlds entry.</p>
+     *
+     * @param recipients  the recipients that are receiving the packet
+     * @param heightLimit the height limit
+     * @since 1.2.9
+     */
+    public abstract void overrideHeightLimit(Recipients recipients, HeightLimit heightLimit);
+
+    /**
+     * Removes the {@link HeightLimit} from the {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @param world      the world name
+     * @since 1.2.9
+     */
+    public abstract void removeHeightLimit(Recipients recipients, String world);
+
+    /**
+     * Removes the {@link HeightLimit} from the {@link Recipients}.
+     *
+     * @param recipients  the recipients that are receiving the packet
+     * @param heightLimit the height limit
+     * @since 1.2.9
+     */
+    public abstract void removeHeightLimit(Recipients recipients, HeightLimit heightLimit);
+
+    /**
+     * Resets all {@link HeightLimit}s for the {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @since 1.2.9
+     */
+    public abstract void resetHeightLimits(Recipients recipients);
+
+}

common/src/main/java/com/lunarclient/apollo/module/heightlimit/HeightLimitModuleImpl.java

@@ -0,0 +1,156 @@
+/*
+ * This file is part of Apollo, licensed under the MIT License.
+ *
+ * Copyright (c) 2026 Moonsworth
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.lunarclient.apollo.module.heightlimit;
+
+import com.lunarclient.apollo.ApolloManager;
+import com.lunarclient.apollo.common.ApolloComponent;
+import com.lunarclient.apollo.event.player.ApolloRegisterPlayerEvent;
+import com.lunarclient.apollo.heightlimit.v1.OverrideHeightLimitMessage;
+import com.lunarclient.apollo.heightlimit.v1.RemoveHeightLimitMessage;
+import com.lunarclient.apollo.heightlimit.v1.ResetHeightLimitsMessage;
+import com.lunarclient.apollo.option.config.Serializer;
+import com.lunarclient.apollo.player.ApolloPlayer;
+import com.lunarclient.apollo.recipients.Recipients;
+import java.lang.reflect.Type;
+import java.util.Arrays;
+import java.util.List;
+import lombok.NonNull;
+import net.kyori.adventure.text.Component;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.spongepowered.configurate.ConfigurationNode;
+import org.spongepowered.configurate.serialize.SerializationException;
+import org.spongepowered.configurate.serialize.TypeSerializer;
+
+import static com.lunarclient.apollo.util.Ranges.checkStrictlyPositive;
+
+/**
+ * Provides the height limit module.
+ *
+ * @since 1.2.9
+ */
+public final class HeightLimitModuleImpl extends HeightLimitModule implements Serializer {
+
+    /**
+     * Creates a new instance of {@link HeightLimitModuleImpl}.
+     *
+     * @since 1.2.9
+     */
+    public HeightLimitModuleImpl() {
+        super();
+        this.serializer(HeightLimit.class, new HeightLimitSerializer());
+        this.handle(ApolloRegisterPlayerEvent.class, this::onPlayerRegister);
+    }
+
+    @Override
+    public void overrideHeightLimit(@NonNull Recipients recipients, @NonNull HeightLimit heightLimit) {
+        OverrideHeightLimitMessage.Builder builder = OverrideHeightLimitMessage.newBuilder()
+            .setWorld(heightLimit.getWorld())
+            .setLimit(checkStrictlyPositive(heightLimit.getLimit(), "HeightLimit#limit"));
+
+        Component displayName = heightLimit.getDisplayName();
+        if (displayName != null) {
+            builder.setDisplayNameAdventureJsonLines(ApolloComponent.toJson(displayName));
+        }
+
+        OverrideHeightLimitMessage message = builder.build();
+        ApolloManager.getNetworkManager().sendPacket(recipients, message);
+    }
+
+    @Override
+    public void removeHeightLimit(@NonNull Recipients recipients, @NonNull String world) {
+        RemoveHeightLimitMessage message = RemoveHeightLimitMessage.newBuilder()
+            .setWorld(world)
+            .build();
+
+        ApolloManager.getNetworkManager().sendPacket(recipients, message);
+    }
+
+    @Override
+    public void removeHeightLimit(@NonNull Recipients recipients, @NonNull HeightLimit heightLimit) {
+        this.removeHeightLimit(recipients, heightLimit.getWorld());
+    }
+
+    @Override
+    public void resetHeightLimits(@NonNull Recipients recipients) {
+        ResetHeightLimitsMessage message = ResetHeightLimitsMessage.getDefaultInstance();
+        ApolloManager.getNetworkManager().sendPacket(recipients, message);
+    }
+
+    private void onPlayerRegister(ApolloRegisterPlayerEvent event) {
+        if (!this.isEnabled()) {
+            return;
+        }
+
+        ApolloPlayer player = event.getPlayer();
+        List<HeightLimit> heightLimits = this.getOptions().get(player, HeightLimitModule.DEFAULT_HEIGHT_LIMITS);
+
+        if (heightLimits != null) {
+            for (HeightLimit heightLimit : heightLimits) {
+                this.overrideHeightLimit(player, heightLimit);
+            }
+        }
+    }
+
+    private static final class HeightLimitSerializer implements TypeSerializer<HeightLimit> {
+
+        @Override
+        public HeightLimit deserialize(Type type, ConfigurationNode node) throws SerializationException {
+            HeightLimit.HeightLimitBuilder builder = HeightLimit.builder()
+                .world(this.virtualNode(node, "world").getString())
+                .limit(this.virtualNode(node, "limit").getInt());
+
+            String displayName = node.node("display-name").getString();
+            if (displayName != null) {
+                builder.displayName(ApolloComponent.fromLegacyAmpersand(displayName));
+            }
+
+            return builder.build();
+        }
+
+        @Override
+        public void serialize(Type type, @Nullable HeightLimit heightLimit, ConfigurationNode node) throws SerializationException {
+            if (heightLimit == null) {
+                node.raw(null);
+                return;
+            }
+
+            node.node("world").set(heightLimit.getWorld());
+            node.node("limit").set(heightLimit.getLimit());
+
+            Component displayName = heightLimit.getDisplayName();
+            if (displayName != null) {
+                node.node("display-name").set(ApolloComponent.toLegacyAmpersand(displayName));
+            }
+        }
+
+        private ConfigurationNode virtualNode(ConfigurationNode source, Object... path) throws SerializationException {
+            if (!source.hasChild(path)) {
+                throw new SerializationException("Required field " + Arrays.toString(path) + " not found!");
+            }
+
+            return source.node(path);
+        }
+    }
+
+}

common/src/main/java/com/lunarclient/apollo/module/packetenrichment/PacketEnrichmentImpl.java

@@ -56,6 +56,10 @@ public PacketEnrichmentImpl() {
     }
 
     private void onReceivePacket(ApolloReceivePacketEvent event) {
+        if (!this.isEnabled()) {
+            return;
+        }
+
         Options options = this.getOptions();
 
         if (options.get(PacketEnrichmentModule.PLAYER_ATTACK_EVENT)) {

common/src/main/java/com/lunarclient/apollo/module/waypoint/WaypointModuleImpl.java

@@ -110,6 +110,10 @@ public void hideWaypoint(@NonNull Recipients recipients, @NonNull String waypoin
     }
 
     private void onPlayerRegister(ApolloRegisterPlayerEvent event) {
+        if (!this.isEnabled()) {
+            return;
+        }
+
         ApolloPlayer player = event.getPlayer();
         List<Waypoint> waypoints = this.getOptions().get(player, WaypointModule.DEFAULT_WAYPOINTS);
 

docs/developers/lightweight/protobuf.mdx

@@ -26,7 +26,7 @@ Available fields for each message, including their types, are available on the B
         <dependency>
             <groupId>com.lunarclient</groupId>
             <artifactId>apollo-protos</artifactId>
-            <version>0.2.0</version>
+            <version>0.2.1</version>
         </dependency>
     </dependencies>
     ```
@@ -41,7 +41,7 @@ Available fields for each message, including their types, are available on the B
     }
 
     dependencies {
-        api 'com.lunarclient:apollo-protos:0.2.0'
+        api 'com.lunarclient:apollo-protos:0.2.1'
     }
     ```
   </Tab>
@@ -55,7 +55,7 @@ Available fields for each message, including their types, are available on the B
     }
 
     dependencies {
-        api("com.lunarclient:apollo-protos:0.2.0")
+        api("com.lunarclient:apollo-protos:0.2.1")
     }
     ```
   </Tab>