cleanup and addn'l documentation

Author: rfresh2

README.md

@@ -10,7 +10,7 @@ Plugins are only supported on the `java` ZenithProxy release channel (i.e. not `
 
 Place plugin jars in the `plugins` folder inside the same folder as the ZenithProxy launcher.
 
-Restart ZenithProxy to load plugins, loading after launch or hot reloading is not supported.
+Restart ZenithProxy to load plugins. Loading plugins after launch or hot reloading is not supported.
 
 ## Creating Plugins
 
@@ -41,9 +41,24 @@ I recommend looking at existing modules and commands for examples.
 
 Execute the Gradle `build` task: `./gradlew build` - or double-click the task in Intellij
 
+The built plugin jar will be in the `build/libs` directory.
+
 ### Testing Plugins
 
 Execute the `run` task: `./gradlew run` - or double-click the task in Intellij
 
 This will run ZenithProxy with your plugin loaded in the `run` directory.
 
+### New Plugin Checklist
+
+1. Edit `gradle.properties`:
+   - `plugin_name` - Name of your plugin, used in the plugin jar name (e.g. `ExamplePlugin`)
+   - `maven_group` - Java package for your project (e.g. `com.github.rfresh2`)
+1. Move files to your new corresponding package / maven group:
+   - Example: `src/main/java/org/example` -> `src/main/java/com/github/rfresh2`
+   - First create the new package in `src/main/java`. Then click and drag original subpackages/classes to your new one
+   - Do this with Intellij to avoid manually editing all the source files
+   - You must also move folders/package for the `src/main/templates` folder
+   - Also make sure to update the package import at the very top of `BuiltConstants.java`, it will not be done automatically
+1. Edit `ExamplePlugin.java`, or remove it and create a new main class
+   - Make sure to update the `@Plugin` annotation

build.gradle.kts

@@ -16,12 +16,12 @@ zenithProxyPlugin {
 
 repositories {
     mavenLocal() // if developing against a locally published zenith build
+    maven("https://maven.2b2t.vc/releases") {
+        description = "ZenithProxy Releases and Dependencies"
+    }
     maven("https://maven.2b2t.vc/remote") {
         description = "Dependencies used by ZenithProxy"
     }
-    maven("https://maven.2b2t.vc/releases") {
-        description = "ZenithProxy Releases"
-    }
 }
 
 dependencies {

gradle.properties

@@ -1,4 +1,5 @@
 plugin_version=1.0.0
+plugin_name=ZenithProxyExamplePlugin
 mc=1.21.0
 maven_group=org.example
 

settings.gradle.kts

@@ -4,3 +4,5 @@ pluginManagement {
         gradlePluginPortal()
     }
 }
+
+rootProject.name = ext.properties["plugin_name"] as String

src/main/java/org/example/ExamplePlugin.java

@@ -16,9 +16,10 @@
     url = "https://github.com/rfresh2/ZenithProxyExamplePlugin",
     authors = {"rfresh2"},
     mcVersions = {"1.21.0"} // to indicate any MC version: @Plugin(mcVersions = "*")
+                            // if you touch packet classes, you almost certainly need to pin to a single mc version
 )
 public class ExamplePlugin implements ZenithProxyPlugin {
-    // public static for easy access from modules and commands
+    // public static for simple access from modules and commands
     // or alternatively, you could pass these around in constructors
     public static ExampleConfig PLUGIN_CONFIG;
     public static Logger LOG;

src/main/java/org/example/command/ExampleCommand.java

@@ -39,22 +39,22 @@ public LiteralArgumentBuilder<CommandContext> register() {
                 // make sure to sync so the module is actually toggled
                 MODULE.get(ExampleModule.class).syncEnabledFromConfig();
                 c.getSource().getEmbed()
+                    // if no title is set, no embed response will be sent
+                    // other properties like fields can be left unset without issues
                     .title("Example Plugin " + toggleStrCaps(PLUGIN_CONFIG.exampleModule.enabled));
-                return OK;
             }))
             .then(literal("delay").then(argument("ticks", integer(0)).executes(c -> {
                 PLUGIN_CONFIG.exampleModule.delayTicks = getInteger(c, "ticks");
                 c.getSource().getEmbed()
                     .title("Delay Set");
-                return OK;
             })));
     }
 
     @Override
     public void defaultEmbed(Embed embed) {
         embed
             .primaryColor()
-            .addField("Enabled", toggleStr(PLUGIN_CONFIG.exampleModule.enabled), false)
-            .addField("Delay", PLUGIN_CONFIG.exampleModule.delayTicks + " ticks", false);
+            .addField("Enabled", toggleStr(PLUGIN_CONFIG.exampleModule.enabled))
+            .addField("Delay", PLUGIN_CONFIG.exampleModule.delayTicks + " ticks");
     }
 }

src/main/java/org/example/command/ExampleESPCommand.java

@@ -26,7 +26,9 @@ public CommandUsage commandUsage() {
             .name("esp")
             .category(CommandCategory.MODULE)
             .description("Renders the spectral effect around all entities")
-            .usageLines("on/off")
+            .usageLines(
+                "on/off"
+            )
             .build();
     }
 
@@ -37,21 +39,25 @@ public LiteralArgumentBuilder<CommandContext> register() {
                 ExamplePlugin.PLUGIN_CONFIG.esp = getToggle(c, "toggle");
                 // make sure to sync so the module is actually toggled
                 MODULE.get(ExampleESPModule.class).syncEnabledFromConfig();
-                var player = Proxy.getInstance().getActivePlayer();
-                if (player != null) {
-                    // resend all entity metadata from cache
+                // array of sessions with the controlling player and any spectators
+                var sessions = Proxy.getInstance().getActiveConnections().getArray();
+                if (sessions.length > 0) {
+                    // resend entity metadata for every cached entity
+                    // if the module is now enabled, our outbound packet handler will modify the packets and add the metadata value
+                    // otherwise, this is resyncing the original metadata to players (i.e. removing the effect)
                     CACHE.getEntityCache().getEntities().values().forEach(e -> {
                         EntityMetadata<?, ?> toSend;
                         toSend = e.getMetadata().get(0);
                         if (toSend == null)
                             toSend = new ByteEntityMetadata(0, MetadataTypes.BYTE, (byte) 0);
-                        player.sendAsync(new ClientboundSetEntityDataPacket(e.getEntityId(), Lists.newArrayList(toSend)));
+                        for (int i = 0; i < sessions.length; i++) {
+                            sessions[i].sendAsync(new ClientboundSetEntityDataPacket(e.getEntityId(), Lists.newArrayList(toSend)));
+                        }
                     });
                 }
                 c.getSource().getEmbed()
                     .title("ESP " + toggleStrCaps(ExamplePlugin.PLUGIN_CONFIG.esp))
                     .primaryColor();
-                return 1;
             }));
     }
 }

src/main/java/org/example/module/ExampleESPModule.java

@@ -45,29 +45,23 @@ public PacketHandlerCodec registerServerPacketHandlerCodec() {
     public static class GlowingEntityMetadataPacketHandler implements PacketHandler<ClientboundSetEntityDataPacket, ServerSession> {
         @Override
         public ClientboundSetEntityDataPacket apply(final ClientboundSetEntityDataPacket packet, final ServerSession session) {
-            ClientboundSetEntityDataPacket p = packet;
             var metadata = packet.getMetadata();
-            boolean edited = false;
             for (int i = 0; i < metadata.size(); i++) {
                 final EntityMetadata<?, ?> entityMetadata = metadata.get(i);
                 // https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Entity_metadata#Entity
-                if (entityMetadata.getId() == 0 && entityMetadata.getType() == MetadataTypes.BYTE) {
-                    ByteEntityMetadata byteMetadata = (ByteEntityMetadata) entityMetadata;
+                if (entityMetadata.getId() == 0 && entityMetadata instanceof ByteEntityMetadata byteMetadata) {
+                    // found the metadata id we want to edit
                     var newMetadata = new ByteEntityMetadata(0, MetadataTypes.BYTE, (byte) (byteMetadata.getPrimitiveValue() | 0x40));
+                    // copy to avoid mutating potentially cached data
                     var newMetadataList = new ArrayList<>(metadata);
                     newMetadataList.set(i, newMetadata);
-                    p = packet.withMetadata(newMetadataList);
-                    edited = true;
-                    break;
+                    return packet.withMetadata(newMetadataList);
                 }
             }
-            if (!edited) {
-                var newMetadata = new ArrayList<EntityMetadata<?, ?>>(metadata.size() + 1);
-                newMetadata.addAll(packet.getMetadata());
-                newMetadata.add(new ByteEntityMetadata(0, MetadataTypes.BYTE, (byte) 0x40));
-                p = packet.withMetadata(newMetadata);
-            }
-            return p;
+            // metadata id wasn't present, so we need to add it
+            var newMetadata = new ArrayList<>(packet.getMetadata());
+            newMetadata.addFirst(new ByteEntityMetadata(0, MetadataTypes.BYTE, (byte) 0x40));
+            return packet.withMetadata(newMetadata);
         }
     }
 }