Examples & Docs (WIP)

Author: ItsNature

…marker/ApolloPlayerRequestPingEvent.java …rker/ApolloPlayerRequestMarkerEvent.javaapi/src/main/java/com/lunarclient/apollo/event/pingmarker/ApolloPlayerRequestPingEvent.java renamed to api/src/main/java/com/lunarclient/apollo/event/pingmarker/ApolloPlayerRequestMarkerEvent.java api/src/main/java/com/lunarclient/apollo/event/pingmarker/ApolloPlayerRequestPingEvent.java renamed to api/src/main/java/com/lunarclient/apollo/event/pingmarker/ApolloPlayerRequestMarkerEvent.java

@@ -36,44 +36,44 @@
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Represents an event that is fired when the player requests a ping.
+ * Represents an event that is fired when the player requests a ping marker.
  *
- * @since 1.1.3
+ * @since 1.1.9
  */
 @Getter
 @RequiredArgsConstructor
 @FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
-public final class ApolloPlayerRequestPingEvent implements EventCancellable {
+public final class ApolloPlayerRequestMarkerEvent implements EventCancellable {
 
     /**
      * The player sending the ping request.
      *
      * @return the source player
-     * @since 1.1.3
+     * @since 1.1.9
      */
     ApolloPlayer player;
 
     /**
      * The {@link PingMarkerType} for this request.
      *
      * @return the ping marker type
-     * @since 1.1.3
+     * @since 1.1.9
      */
     @Nullable PingMarkerType type;
 
     /**
      * The source {@link ApolloLocation} for this request.
      *
      * @return the source location
-     * @since 1.1.3
+     * @since 1.1.9
      */
     ApolloLocation source;
 
     /**
      * The target {@link ApolloLocation} for this request.
      *
      * @return the target location
-     * @since 1.1.3
+     * @since 1.1.9
      */
     ApolloLocation target;
 

api/src/main/java/com/lunarclient/apollo/module/pingmarker/PingMarker.java

@@ -35,7 +35,7 @@
 /**
  * Represents a ping marker which can be shown on the client.
  *
- * @since 1.1.3
+ * @since 1.1.9
  */
 @Getter
 @Builder
@@ -45,47 +45,47 @@ public final class PingMarker {
      * Returns the marker {@link UUID}.
      *
      * @return the ping marker id
-     * @since 1.1.3
+     * @since 1.1.9
      */
     UUID id;
 
     /**
      * Returns the {@link PingMarkerType}.
      *
      * @return the ping marker type
-     * @since 1.1.3
+     * @since 1.1.9
      */
     @Nullable PingMarkerType type;
 
     /**
      * Returns the marker {@link ApolloLocation}.
      *
      * @return the ping marker location
-     * @since 1.1.3
+     * @since 1.1.9
      */
     ApolloLocation location;
 
     /**
      * Returns the marker {@link Color}.
      *
      * @return the ping marker color
-     * @since 1.1.3
+     * @since 1.1.9
      */
     Color color;
 
     /**
      * Returns the marker {@link Duration}.
      *
      * @return the ping marker duration
-     * @since 1.1.3
+     * @since 1.1.9
      */
     Duration duration;
 
     /**
      * Returns whether the marker should animate.
      *
      * @return the ping marker focus state
-     * @since 1.1.3
+     * @since 1.1.9
      */
     boolean focus;
 
@@ -96,7 +96,7 @@ public final class PingMarker {
      * for the most common use case, use {@link com.lunarclient.apollo.common.icon.ItemStackIcon}.</p>
      *
      * @return the ping marker icon
-     * @since 1.1.3
+     * @since 1.1.9
      */
     Icon icon;
 

api/src/main/java/com/lunarclient/apollo/module/pingmarker/PingMarkerModule.java

@@ -32,7 +32,7 @@
 /**
  * Represents the ping marker module.
  *
- * @since 1.0.0
+ * @since 1.1.9
  */
 @ApiStatus.NonExtendable
 @ModuleDefinition(id = "ping_marker", name = "Ping Marker")
@@ -43,7 +43,7 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param type       the marker type
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void setMarkerType(Recipients recipients, PingMarkerType type);
 
@@ -52,7 +52,7 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param name       the marker type name
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void removeMarkerType(Recipients recipients, String name);
 
@@ -61,15 +61,15 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param type       the marker type
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void removeMarkerType(Recipients recipients, PingMarkerType type);
 
     /**
      * Resets all {@link PingMarkerType}s for the {@link Recipients}.
      *
      * @param recipients the recipients that are receiving the packet
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void resetMarkerType(Recipients recipients);
 
@@ -78,7 +78,7 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param marker     the marker
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void displayMarker(Recipients recipients, PingMarker marker);
 
@@ -87,7 +87,7 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param markerId the marker id
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void removeMarker(Recipients recipients, UUID markerId);
 
@@ -96,15 +96,15 @@ public abstract class PingMarkerModule extends ApolloModule {
      *
      * @param recipients the recipients that are receiving the packet
      * @param marker     the marker
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void removeMarker(Recipients recipients, PingMarker marker);
 
     /**
      * Resets all {@link PingMarker}s for the {@link Recipients}.
      *
      * @param recipients the recipients that are receiving the packet
-     * @since 1.1.3
+     * @since 1.1.9
      */
     public abstract void resetMarkers(Recipients recipients);
 

api/src/main/java/com/lunarclient/apollo/module/pingmarker/PingMarkerType.java

@@ -30,7 +30,7 @@
 /**
  * Represents a ping marker type which can be shown on the client.
  *
- * @since 1.1.3
+ * @since 1.1.9
  */
 @Getter
 @Builder
@@ -40,7 +40,7 @@ public final class PingMarkerType {
      * Returns the ping marker type {@link String} name.
      *
      * @return the ping marker type name
-     * @since 1.1.3
+     * @since 1.1.9
      */
     String name;
 
@@ -51,7 +51,7 @@ public final class PingMarkerType {
      * for the most common use case, use {@link com.lunarclient.apollo.common.icon.ItemStackIcon}.</p>
      *
      * @return the ping marker icon
-     * @since 1.1.3
+     * @since 1.1.9
      */
     Icon icon;
 

api/src/main/java/com/lunarclient/apollo/recipients/Recipients.java

@@ -64,7 +64,7 @@ static ForwardingRecipients ofEveryone() {
      *
      * @param player the apollo player
      * @return a {@code ForwardingRecipients} instance representing players in the world
-     * @since 1.1.3
+     * @since 1.1.9
      */
     static ForwardingRecipients ofWorld(ApolloPlayer player) {
         return () -> player.getWorld().map(ApolloWorld::getPlayers).orElseGet(() -> Apollo.getPlayerManager().getPlayers());

bukkit-example-api/src/main/java/com/lunarclient/apollo/example/api/ApolloApiExamplePlatform.java

@@ -44,6 +44,7 @@
 import com.lunarclient.apollo.example.api.module.NametagApiExample;
 import com.lunarclient.apollo.example.api.module.NickHiderApiExample;
 import com.lunarclient.apollo.example.api.module.NotificationApiExample;
+import com.lunarclient.apollo.example.api.module.PingMarkerApiExample;
 import com.lunarclient.apollo.example.api.module.RichPresenceApiExample;
 import com.lunarclient.apollo.example.api.module.ServerRuleApiExample;
 import com.lunarclient.apollo.example.api.module.StaffModApiExample;
@@ -92,6 +93,7 @@ public void registerModuleExamples() {
         this.setNametagExample(new NametagApiExample());
         this.setNickHiderExample(new NickHiderApiExample());
         this.setNotificationExample(new NotificationApiExample());
+        this.setPingMarkerExample(new PingMarkerApiExample());
         this.setRichPresenceExample(new RichPresenceApiExample());
         this.setServerRuleExample(new ServerRuleApiExample());
         this.setStaffModExample(new StaffModApiExample());

bukkit-example-api/src/main/java/com/lunarclient/apollo/example/api/listener/ApolloPlayerApiListener.java

@@ -26,12 +26,10 @@
 import com.lunarclient.apollo.event.ApolloListener;
 import com.lunarclient.apollo.event.EventBus;
 import com.lunarclient.apollo.event.Listen;
-import com.lunarclient.apollo.event.pingmarker.ApolloPlayerRequestPingEvent;
 import com.lunarclient.apollo.event.player.ApolloRegisterPlayerEvent;
 import com.lunarclient.apollo.example.ApolloExamplePlugin;
 import com.lunarclient.apollo.example.api.module.TeamApiExample;
 import com.lunarclient.apollo.player.ApolloPlayer;
-import com.lunarclient.apollo.world.ApolloWorld;
 import org.bukkit.entity.Player;
 
 public class ApolloPlayerApiListener implements ApolloListener {
@@ -65,12 +63,4 @@ private void onApolloRegister(ApolloRegisterPlayerEvent event) {
         this.example.getWaypointExample().displayWaypointExample(player);
     }
 
-    @Listen
-    private void onPingMarker(ApolloPlayerRequestPingEvent event) {
-        ApolloWorld world = event.getPlayer().getWorld().orElse(null);
-        if (world == null) return;
-
-        this.plugin.getPingMarkerExample().displayMarkerExample(event.getType(), event.getTarget(), world.getPlayers());
-    }
-
 }

bukkit-example-api/src/main/java/com/lunarclient/apollo/example/api/module/PingMarkerApiExample.java

@@ -0,0 +1,84 @@
+/*
+ * This file is part of Apollo, licensed under the MIT License.
+ *
+ * Copyright (c) 2023 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.example.api.module;
+
+import com.lunarclient.apollo.Apollo;
+import com.lunarclient.apollo.BukkitApollo;
+import com.lunarclient.apollo.common.icon.SimpleResourceLocationIcon;
+import com.lunarclient.apollo.example.module.impl.PingMarkerExample;
+import com.lunarclient.apollo.module.pingmarker.PingMarker;
+import com.lunarclient.apollo.module.pingmarker.PingMarkerModule;
+import com.lunarclient.apollo.player.ApolloPlayer;
+import com.lunarclient.apollo.recipients.Recipients;
+import java.awt.Color;
+import java.time.Duration;
+import java.util.Optional;
+import java.util.UUID;
+import org.bukkit.Location;
+import org.bukkit.block.Block;
+import org.bukkit.entity.Player;
+
+public class PingMarkerApiExample extends PingMarkerExample {
+
+    private final PingMarkerModule pingMarkerModule = Apollo.getModuleManager().getModule(PingMarkerModule.class);
+
+    @Override
+    public void displayMarkerResourceExample(Player player) {
+        Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(player.getUniqueId());
+
+        apolloPlayerOpt.ifPresent(apolloPlayer -> {
+            Location location = this.findTargetLocation(player);
+
+            if (location == null) {
+                return;
+            }
+
+            this.pingMarkerModule.displayMarker(Recipients.ofWorld(apolloPlayer), PingMarker.builder()
+                .id(UUID.randomUUID())
+                .type(null) // TODO: add another example with a specific type
+                .location(BukkitApollo.toApolloLocation(location))
+                .color(Color.WHITE)
+                .icon(SimpleResourceLocationIcon.builder()
+                    .resourceLocation("lunar:icons/fluent-black-circle-icon.svg")
+                    .size(12)
+                    .build()
+                )
+                .duration(Duration.ofSeconds(5))
+                .focus(true)
+                .build());
+        });
+
+    }
+
+    private Location findTargetLocation(Player player) {
+        Block targetBlock = player.getTargetBlockExact(30);
+
+        if (targetBlock == null) {
+            return null;
+        }
+
+        return targetBlock.getLocation().add(0.5D, 0.5D, 0.5D);
+    }
+
+}

bukkit-example-api/src/main/resources/plugin.yml

@@ -43,6 +43,8 @@ commands:
         description: "Nick Hider!"
     notification:
         description: "Notifications!"
+    pingmarker:
+        description: "Ping Marker!"
     richpresence:
         description: "Rich Presence!"
     saturation: