Version - 1.2.9

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);
+
+}

api/src/main/java/com/lunarclient/apollo/module/transfer/PingRequest.java

@@ -45,4 +45,15 @@ public final class PingRequest extends ApolloRequest<PingResponse> {
      */
     List<String> serverIps;
 
+    /**
+     * Returns the timeout for ping requests, in milliseconds.
+     *
+     * @return the request timeout, in milliseconds
+     * @since 1.2.9
+     */
+    @Override
+    public long getTimeoutMillis() {
+        return 10_000L;
+    }
+
 }

api/src/main/java/com/lunarclient/apollo/module/transfer/TransferModule.java

@@ -42,6 +42,14 @@
 @ModuleDefinition(id = "transfer", name = "Transfer")
 public abstract class TransferModule extends ApolloModule {
 
+    /**
+     * The maximum amount of server IPs the client will ping
+     * for a single {@link PingRequest}.
+     *
+     * @since 1.2.9
+     */
+    public static final int MAX_PINGS_PER_PACKET = 10;
+
     @Override
     public Collection<ApolloPlatform.Kind> getSupportedPlatforms() {
         return Arrays.asList(ApolloPlatform.Kind.SERVER, ApolloPlatform.Kind.PROXY);
@@ -55,6 +63,8 @@ public Collection<ApolloPlatform.Kind> getSupportedPlatforms() {
      * @param player    the player
      * @param serverIps all server IPs to ping
      * @return future to be listened to for errors/success
+     * @throws IllegalArgumentException if no server IPs or more than
+     *         {@value #MAX_PINGS_PER_PACKET} server IPs are provided
      * @since 1.0.0
      */
     public Future<PingResponse> ping(ApolloPlayer player, List<String> serverIps) {
@@ -85,6 +95,8 @@ public Future<TransferResponse> transfer(ApolloPlayer player, String serverIp) {
      * @param player  the player
      * @param request the ping request
      * @return future to be listened to for errors/success
+     * @throws IllegalArgumentException if no server IPs or more than
+     *         {@value #MAX_PINGS_PER_PACKET} server IPs are provided
      * @since 1.0.0
      */
     public abstract Future<PingResponse> ping(ApolloPlayer player, PingRequest request);

api/src/main/java/com/lunarclient/apollo/roundtrip/ApolloRequest.java

@@ -67,4 +67,14 @@ public ApolloRequest() {
         this.sentTime = System.currentTimeMillis();
     }
 
+    /**
+     * Returns the time to wait for a response, in milliseconds.
+     *
+     * @return the request timeout, in milliseconds
+     * @since 1.2.9
+     */
+    public long getTimeoutMillis() {
+        return TIMEOUT;
+    }
+
 }

api/src/main/java/com/lunarclient/apollo/roundtrip/ApolloRoundtripManager.java

@@ -119,13 +119,14 @@ public <T extends ApolloResponse> void registerListener(ApolloRequest<T> request
                 this.paginationManager.handleTimeout(packetId);
 
                 if (listener != null) {
-                    Throwable error = new Throwable("Timeout exceeded!");
+                    Throwable error = new Throwable("Timeout exceeded! No " + request.getClass().getSimpleName()
+                        + " response received within " + request.getTimeoutMillis() + "ms");
                     future.handleFailure(error);
                 }
             } catch (Exception e) {
                 e.printStackTrace();
             }
-        }, ApolloRequest.TIMEOUT, TimeUnit.MILLISECONDS);
+        }, request.getTimeoutMillis(), TimeUnit.MILLISECONDS);
 
         this.listeners.put(packetId, (UncertainFuture<ApolloResponse>) future);
     }