Lightweight: Documentation (#172)

* Add a bunch of lightweight examples

* Add more examples

* Even more examples...

* More examples & prepare for example plugin merge

* Fix adventure usages

* Testable state

* Add more notes

* Add switch implementation command

* Finish more examples, start working on markdown

* Spotless fixes

* Update beam.mdx with new examples

* Finish team examples

* More markdown work

* Add missing import to chat.mdx

* Move builders outside tabs again

* Fix remaining serialization issues

* Add more markdown examples

* Add hologram & limb examples

* move builders inside API tab, add nametag, nickhider & notification examples

* Finish proto examples

* Remove object utils

* add temp layout

* Finish all Json Examples

* Add Tebex module locale field to lightweight examples

* The merge!

* Start lightweight.mdx rewrite

* Close tab

* Import callout

* ADd modsettings examples

* richpresence, serverrule, staffmod, stopwatch, title, tntcountdown, tranfser, vignette & waypoint markdown examples

* Protobuf Lightweight Documentation

* Minor changes

* Updating player world code & markdown, packet enrichment & minor parameter fixups

* Fix links

* Fix the fixed links

* Spotless fixes

* Add lightweight callout to intro

* add intro to meta json

* Finish JSON lightweight docs

* Remove old lightweight.mdx

* Link usage methods, add module examples note

* resolve callout issue?

* Rebuild

* Team markdown examples

* update callout

* update callout

* remove placeholder text

* Remove build status

* Replace Component#appendNewLine with Component.append(Component.newline()) for backwards compatibility

* Default implementation type to API

* Remove protobuf-java-util dependency

* Final touch-ups

* fix typo

* Wording Change

* Lightning -> Lighting

* Use Futures for Roundtrip example & implement timeout

* Mark player data fields with `@Nullable`

---------

Co-authored-by: TrentinTheKid <[email protected]>

README.md

@@ -1,5 +1,4 @@
 # Apollo
-![Build Status](https://img.shields.io/github/actions/workflow/status/LunarClient/Apollo/.github/workflows/deploy.yml)
 [![Discord](https://img.shields.io/discord/1080556677004271666?logo=discord&label=discord)](https://discord.gg/3T9Atyb6pf)
 
 Apollo is a powerful tool that allows developers to create custom integrations with Lunar Client.

api/src/main/java/com/lunarclient/apollo/player/ApolloPlayer.java

@@ -37,6 +37,7 @@
 import java.util.UUID;
 import net.kyori.adventure.audience.ForwardingAudience;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a player on Apollo.
@@ -111,37 +112,36 @@ default boolean hasPermission(Options options, Option<String, ?, ?> option) {
      */
     Object getPlayer();
 
-    // TODO: nullable or optional?
     /**
      * Returns the {@link MinecraftVersion} the player is running.
      *
      * @return the minecraft version
      * @since 1.1.5
      */
-    MinecraftVersion getMinecraftVersion();
+    @Nullable MinecraftVersion getMinecraftVersion();
 
     /**
      * Returns the {@link LunarClientVersion} the player is running.
      *
      * @return the lunar client version
      * @since 1.1.5
      */
-    LunarClientVersion getLunarClientVersion();
+    @Nullable LunarClientVersion getLunarClientVersion();
 
     /**
      * Returns a {@link List} of {@link LunarClientMod} the player has installed.
      *
      * @return the installed mods
      * @since 1.1.5
      */
-    List<LunarClientMod> getInstalledMods();
+    @Nullable List<LunarClientMod> getInstalledMods();
 
     /**
      * Returns the {@link TebexEmbeddedCheckoutSupport} type.
      *
      * @return the Tebex checkout support type
      * @since 1.1.5
      */
-    TebexEmbeddedCheckoutSupport getTebexEmbeddedCheckoutSupport();
+    @Nullable TebexEmbeddedCheckoutSupport getTebexEmbeddedCheckoutSupport();
 
 }

bukkit-example/build.gradle.kts

@@ -1,10 +1,22 @@
 plugins {
     id("apollo.base-conventions")
+    id("apollo.shadow-conventions")
 }
 
 dependencies {
     compileOnly(libs.bukkit.api)
 
+    // Used for Proto Implementation
+    api(libs.protobuf)
+
+    // Used for Proto & Json Implementation
+    api(libs.bundles.adventure) {
+        exclude("org.checkerframework")
+        exclude("net.kyori", "adventure-api")
+        exclude("net.kyori", "adventure-bom")
+    }
+
+    // Used for API Implementation
     compileOnly(project(":extra:apollo-extra-adventure4"))
     compileOnly(project(path = ":apollo-api", configuration = "bukkit"))
 }

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

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example;
+package com.lunarclient.apollo.example.api;
 
 import com.lunarclient.apollo.Apollo;
 import com.lunarclient.apollo.module.border.BorderModule;

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/BeamExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/BeamApiExample.java

@@ -21,21 +21,23 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
 import com.lunarclient.apollo.common.location.ApolloBlockLocation;
+import com.lunarclient.apollo.example.common.modules.impl.BeamExample;
 import com.lunarclient.apollo.module.beam.Beam;
 import com.lunarclient.apollo.module.beam.BeamModule;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import java.awt.Color;
 import java.util.Optional;
 import org.bukkit.entity.Player;
 
-public class BeamExample {
+public class BeamApiExample extends BeamExample {
 
     private final BeamModule beamModule = Apollo.getModuleManager().getModule(BeamModule.class);
 
+    @Override
     public void displayBeamExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -55,11 +57,13 @@ public void displayBeamExample(Player viewer) {
         });
     }
 
+    @Override
     public void removeBeamExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(apolloPlayer -> this.beamModule.removeBeam(apolloPlayer, "spawn-beacon"));
     }
 
+    @Override
     public void resetBeamsExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(this.beamModule::resetBeams);

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/BorderExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/BorderApiExample.java

@@ -21,21 +21,23 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
 import com.lunarclient.apollo.common.cuboid.Cuboid2D;
+import com.lunarclient.apollo.example.common.modules.impl.BorderExample;
 import com.lunarclient.apollo.module.border.Border;
 import com.lunarclient.apollo.module.border.BorderModule;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import java.awt.Color;
 import java.util.Optional;
 import org.bukkit.entity.Player;
 
-public class BorderExample {
+public class BorderApiExample extends BorderExample {
 
     private final BorderModule borderModule = Apollo.getModuleManager().getModule(BorderModule.class);
 
+    @Override
     public void displayBorderExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -60,11 +62,13 @@ public void displayBorderExample(Player viewer) {
         });
     }
 
+    @Override
     public void removeBorderExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(apolloPlayer -> this.borderModule.removeBorder(apolloPlayer, "pvp-tagged-spawn"));
     }
 
+    @Override
     public void resetBordersExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(this.borderModule::resetBorders);

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/ChatExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/ChatApiExample.java

@@ -21,36 +21,37 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
+import com.lunarclient.apollo.example.common.modules.impl.ChatExample;
 import com.lunarclient.apollo.module.chat.ChatModule;
 import com.lunarclient.apollo.recipients.Recipients;
-import java.util.concurrent.ThreadLocalRandom;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.NamedTextColor;
 
-public class ChatExample {
+public class ChatApiExample extends ChatExample {
 
     private final ChatModule chatModule = Apollo.getModuleManager().getModule(ChatModule.class);
 
-    private final int messageId = ThreadLocalRandom.current().nextInt(100);
     private int countdown = 5;
 
+    @Override
     public void displayLiveChatMessageExample() {
         this.chatModule.displayLiveChatMessage(Recipients.ofEveryone(),
             Component.text("Game starting in ", NamedTextColor.GREEN)
                 .append(Component.text(this.countdown, NamedTextColor.BLUE)),
-            this.messageId
+            13
         );
 
         if (--this.countdown == 0) {
             this.countdown = 5;
         }
     }
 
+    @Override
     public void removeLiveChatMessageExample() {
-        this.chatModule.removeLiveChatMessage(Recipients.ofEveryone(), this.messageId);
+        this.chatModule.removeLiveChatMessage(Recipients.ofEveryone(), 13);
     }
 
 }

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/ColoredFireExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/ColoredFireApiExample.java

@@ -21,9 +21,10 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
+import com.lunarclient.apollo.example.common.modules.impl.ColoredFireExample;
 import com.lunarclient.apollo.module.coloredfire.ColoredFireModule;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import com.lunarclient.apollo.recipients.Recipients;
@@ -32,21 +33,24 @@
 import java.util.UUID;
 import org.bukkit.entity.Player;
 
-public class ColoredFireExample {
+public class ColoredFireApiExample extends ColoredFireExample {
 
     private final ColoredFireModule coloredFireModule = Apollo.getModuleManager().getModule(ColoredFireModule.class);
 
+    @Override
     public void overrideColoredFireExample(UUID burningPlayer) {
         this.coloredFireModule.overrideColoredFire(Recipients.ofEveryone(),
             burningPlayer,
             Color.BLUE
         );
     }
 
+    @Override
     public void resetColoredFireExample(UUID burningPlayer) {
         this.coloredFireModule.resetColoredFire(Recipients.ofEveryone(), burningPlayer);
     }
 
+    @Override
     public void resetColoredFiresExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(this.coloredFireModule::resetColoredFires);

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/CombatExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/CombatApiExample.java

@@ -21,15 +21,17 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
+import com.lunarclient.apollo.example.common.modules.impl.CombatExample;
 import com.lunarclient.apollo.module.combat.CombatModule;
 
-public class CombatExample {
+public class CombatApiExample extends CombatExample {
 
     private final CombatModule combatModule = Apollo.getModuleManager().getModule(CombatModule.class);
 
+    @Override
     public void setDisableMissPenalty(boolean value) {
         this.combatModule.getOptions().set(CombatModule.DISABLE_MISS_PENALTY, value);
     }

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/CooldownExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/CooldownApiExample.java

@@ -21,22 +21,24 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
 import com.lunarclient.apollo.common.icon.ItemStackIcon;
 import com.lunarclient.apollo.common.icon.SimpleResourceLocationIcon;
+import com.lunarclient.apollo.example.common.modules.impl.CooldownExample;
 import com.lunarclient.apollo.module.cooldown.Cooldown;
 import com.lunarclient.apollo.module.cooldown.CooldownModule;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import java.time.Duration;
 import java.util.Optional;
 import org.bukkit.entity.Player;
 
-public class CooldownExample {
+public class CooldownApiExample extends CooldownExample {
 
     private final CooldownModule cooldownModule = Apollo.getModuleManager().getModule(CooldownModule.class);
 
+    @Override
     public void displayCooldownItemExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -53,6 +55,7 @@ public void displayCooldownItemExample(Player viewer) {
         });
     }
 
+    @Override
     public void displayCooldownResourceExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -70,6 +73,7 @@ public void displayCooldownResourceExample(Player viewer) {
         });
     }
 
+    @Override
     public void removeCooldownExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -79,6 +83,7 @@ public void removeCooldownExample(Player viewer) {
         });
     }
 
+    @Override
     public void resetCooldownsExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
         apolloPlayerOpt.ifPresent(this.cooldownModule::resetCooldowns);

bukkit-example/src/main/java/com/lunarclient/apollo/example/modules/EntityExample.java → bukkit-example/src/main/java/com/lunarclient/apollo/example/api/examples/EntityApiExample.java

@@ -21,10 +21,11 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package com.lunarclient.apollo.example.modules;
+package com.lunarclient.apollo.example.api.examples;
 
 import com.lunarclient.apollo.Apollo;
 import com.lunarclient.apollo.common.ApolloEntity;
+import com.lunarclient.apollo.example.common.modules.impl.EntityExample;
 import com.lunarclient.apollo.module.entity.EntityModule;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import java.util.List;
@@ -34,10 +35,11 @@
 import org.bukkit.entity.Player;
 import org.bukkit.entity.Sheep;
 
-public class EntityExample {
+public class EntityApiExample extends EntityExample {
 
     private final EntityModule entityModule = Apollo.getModuleManager().getModule(EntityModule.class);
 
+    @Override
     public void overrideRainbowSheepExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -51,6 +53,7 @@ public void overrideRainbowSheepExample(Player viewer) {
         });
     }
 
+    @Override
     public void resetRainbowSheepExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -64,6 +67,7 @@ public void resetRainbowSheepExample(Player viewer) {
         });
     }
 
+    @Override
     public void flipEntityExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
 
@@ -79,6 +83,7 @@ public void flipEntityExample(Player viewer) {
         });
     }
 
+    @Override
     public void resetFlippedEntityExample(Player viewer) {
         Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());