feature: Rewrite of the protocol, removal of NeoForge for now, new API reworks, better platform independent structure

.github/workflows/build.yml

@@ -4,7 +4,6 @@ on:
     push:
         branches: ["**"]
         tags-ignore: ["**"]
-    pull_request:
     release:
         types: [published]
     workflow_dispatch:
@@ -27,16 +26,12 @@ jobs:
 
             - name: Setup Gradle
               uses: gradle/actions/setup-gradle@v4
+              with:
+                cache-read-only: false
 
             - name: Gradle Build
               run: ./gradlew build
 
-            - name: Clean Up NeoForge Artifacts
-              run: rm neoforge/build/libs/*-sources.jar
-
-            - name: Clean Up Fabric Artifacts
-              run: rm fabric/build/libs/*-sources.jar
-
             - name: Upload Artifacts
               uses: actions/upload-artifact@v4
               with:
@@ -52,7 +47,7 @@ jobs:
                   fi
 
             - name: Publish Snapshot
-              if: "${{ env.STATUS != 'release' && github.event_name == 'push' && github.ref == 'refs/heads/main' }}"
+              if: "${{ env.STATUS != 'release' && github.event_name == 'push' }}"
               run: ./gradlew publish
               env:
                   NOXCREW_MAVEN_PUBLIC_USERNAME: ${{ secrets.NOXCREW_MAVEN_PUBLIC_USERNAME }}

README.md

@@ -12,7 +12,7 @@ Noxesium is directly developed by [Noxcrew](https://noxcrew.com/), creators of M
 Noxesium is also automatically included on some versions of [Lunar Client](https://www.lunarclient.com/).
 
 # Usage
-Public builds of Noxesium are available on [Modrinth](https://modrinth.com/mod/noxesium) and [CurseForge](https://www.curseforge.com/minecraft/mc-mods/noxesium). Upcoming releases can be found on the [Releases](https://github.com/Noxcrew/noxesium/releases) page here on GitHub.  Developers interested in using Noxesium as an API can find more information on the [Wiki page](https://github.com/Noxcrew/noxesium/wiki).
+Public builds of Noxesium are available on [Modrinth](https://modrinth.com/mod/noxesium) and [CurseForge](https://www.curseforge.com/minecraft/mc-mods/noxesium). Upcoming releases can be found on the [Releases](https://github.com/Noxcrew/noxesium/releases) page here on GitHub. Developers interested in using Noxesium as an API can find more information on the [Wiki page](https://github.com/Noxcrew/noxesium/wiki).
 
 # Features
 

api/README.md

@@ -0,0 +1,4 @@
+# API Module
+
+This module contains all code that does not depend on any of Minecraft's code. It contains both the api package with the API itself as well
+as a core package with base Noxesium features.

api/build.gradle.kts

@@ -1,4 +1,13 @@
+plugins {
+    id("noxesium.publishing")
+}
+
 dependencies {
-    implementation(libs.annotations)
-    implementation(libs.gson)
+    api(libs.annotations)
+    api(libs.gson)
+    api(libs.adventure.api)
+    api(libs.slf4j)
+    api(libs.guava)
+    api(libs.apache.commons)
+    api(libs.joml)
 }

api/src/main/java/com/noxcrew/noxesium/NoxesiumCapabilities.java

@@ -0,0 +1,37 @@
+package com.noxcrew.noxesium;
+
+import com.noxcrew.noxesium.api.NoxesiumReferences;
+import java.util.Collection;
+import java.util.HashSet;
+import net.kyori.adventure.key.Key;
+
+/**
+ * Holds capabilities provided by the common Noxesium Fabric mod.
+ * These can be referenced by servers to detect which major Noxesium systems
+ * and features are available for usage.
+ */
+public class NoxesiumCapabilities {
+    /**
+     * The namespace used for common Noxesium capabilities.
+     */
+    private static final String NAMESPACE = NoxesiumReferences.COMMON_ENTRYPOINT;
+
+    /**
+     * All capabilities of the common entrypoint.
+     */
+    public static final Collection<Key> ALL_CAPABILITIES = new HashSet<>();
+
+    // There are no capabilities yet because the API is brand new... But here's some examples!
+    public static final Key V3_API_SUPPORT = register("v3_api_support");
+    public static final Key ANONYMOUS_PLAYER_HEADS = register("anonymous_player_heads");
+    public static final Key FUNCTIONAL_QIB_SYSTEM = register("functional_qib_system");
+
+    /**
+     * Registers a new capability.
+     */
+    private static Key register(String id) {
+        var key = Key.key(NAMESPACE, id);
+        ALL_CAPABILITIES.add(key);
+        return key;
+    }
+}

api/src/main/java/com/noxcrew/noxesium/api/ClientNoxesiumEntrypoint.java

@@ -0,0 +1,40 @@
+package com.noxcrew.noxesium.api;
+
+import java.util.Collection;
+import java.util.Collections;
+import net.kyori.adventure.key.Key;
+
+/**
+ * Extends the {@link NoxesiumEntrypoint} with client-sided methods.
+ * Can be defined in `fabric.mod.json` under `noxesium`.
+ */
+public interface ClientNoxesiumEntrypoint extends NoxesiumEntrypoint {
+    /**
+     * Returns the capabilities of this entrypoint. This should be a
+     * list of unique keys that the server can check against to determine
+     * if the client is capable of providing a certain feature.
+     * <p>
+     * Individual packets and registry entries are automatically synced, but
+     * this can be used for more generic concepts.
+     */
+    default Collection<Key> getCapabilities() {
+        return Collections.emptySet();
+    }
+
+    /**
+     * Returns the version of this entrypoint.
+     */
+    String getVersion();
+
+    /**
+     * Allows implementations to run pre-initialization steps such as registering
+     * serializers. This is guaranteed to run on all entrypoints before any are initialized.
+     */
+    default void preInitialize() {}
+
+    /**
+     * Allows implementations to run initialization steps like constructing feature classes.
+     * This is guaranteed to run on all entrypoints before any are registered.
+     */
+    default void initialize() {}
+}

api/src/main/java/com/noxcrew/noxesium/api/NoxesiumApi.java

@@ -0,0 +1,168 @@
+package com.noxcrew.noxesium.api;
+
+import com.noxcrew.noxesium.api.feature.NoxesiumFeature;
+import com.noxcrew.noxesium.api.network.EntrypointProtocol;
+import com.noxcrew.noxesium.api.network.PacketCollection;
+import com.noxcrew.noxesium.api.registry.NoxesiumRegistries;
+import com.noxcrew.noxesium.api.registry.NoxesiumRegistry;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Provides shared API for Noxesium's various available APIs.
+ */
+public class NoxesiumApi {
+    private static final NoxesiumApi INSTANCE = new NoxesiumApi();
+    private static final Logger logger = LoggerFactory.getLogger("Noxesium");
+
+    private final Map<Class<? extends NoxesiumFeature>, NoxesiumFeature> features = new HashMap<>();
+    private final Map<String, NoxesiumEntrypoint> entrypoints = new HashMap<>();
+    private final Set<PacketCollection> packets = new HashSet<>();
+    private final List<NoxesiumEntrypoint> activeEntrypoints = new ArrayList<>();
+    private NoxesiumSide side = NoxesiumSide.SERVER;
+
+    /**
+     * Returns the singleton instance of the Noxesium API.
+     */
+    public static NoxesiumApi getInstance() {
+        return INSTANCE;
+    }
+
+    /**
+     * Returns the logger instance to use.
+     */
+    public static Logger getLogger() {
+        return logger;
+    }
+
+    /**
+     * Returns which side Noxesium is running on.
+     */
+    public NoxesiumSide getSide() {
+        return side;
+    }
+
+    /**
+     * Sets which side Noxesium is running on.
+     */
+    public void setSide(NoxesiumSide side) {
+        this.side = side;
+    }
+
+    /**
+     * Activates the entrypoint with the given protocol.
+     */
+    public void activateEntrypoint(EntrypointProtocol protocol) {
+        var entrypoint = entrypoints.get(protocol.id());
+        if (entrypoint == null) return;
+        entrypoint.getRegistryCollections().forEach(it -> it.register(entrypoint));
+        entrypoint.getPacketCollections().forEach(it -> registerPackets(entrypoint, it));
+        activeEntrypoints.add(entrypoint);
+    }
+
+    /**
+     * Registers a new entrypoint.
+     */
+    public void registerEntrypoint(NoxesiumEntrypoint entrypoint) {
+        entrypoints.put(entrypoint.getId(), entrypoint);
+    }
+
+    /**
+     * Registers a new entrypoint and instantly activates it. Meant for the server-side
+     * where entrypoints are immediately active.
+     */
+    public void registerAndActivateEntrypoint(NoxesiumEntrypoint entrypoint) {
+        registerEntrypoint(entrypoint);
+        entrypoint.getRegistryCollections().forEach(it -> it.register(entrypoint));
+        entrypoint.getPacketCollections().forEach(it -> registerPackets(entrypoint, it));
+        entrypoint.getAllFeatures().forEach(this::registerFeature);
+        activeEntrypoints.add(entrypoint);
+    }
+
+    /**
+     * Adds a new feature to the list of features that should
+     * be registered. Usually called by the initializer.
+     */
+    public void registerFeature(NoxesiumFeature feature) {
+        if (!features.containsKey(feature.getClass())) {
+            features.put(feature.getClass(), feature);
+            feature.register();
+        }
+    }
+
+    /**
+     * Registers a new collection of packets.
+     * Usually called by the initializer.
+     */
+    public void registerPackets(NoxesiumEntrypoint entrypoint, PacketCollection collection) {
+        packets.add(collection);
+        collection.register(entrypoint);
+    }
+
+    /**
+     * Unregisters all features collections.
+     */
+    public void unregisterAll() {
+        activeEntrypoints.clear();
+        features.values().forEach(NoxesiumFeature::unregister);
+        features.clear();
+        packets.forEach(PacketCollection::unregister);
+        packets.clear();
+        NoxesiumRegistries.REGISTRIES.forEach(NoxesiumRegistry::reset);
+    }
+
+    /**
+     * Returns the feature of type [T] if one is registered, or `null` otherwise.
+     */
+    @Nullable
+    public <T extends NoxesiumFeature> T getFeatureOrNull(Class<T> clazz) {
+        return (T) features.get(clazz);
+    }
+
+    /**
+     * Returns the feature of type [T], wrapped in an optional.
+     */
+    @NotNull
+    public <T extends NoxesiumFeature> Optional<T> getFeatureOptional(Class<T> clazz) {
+        return Optional.ofNullable(getFeatureOrNull(clazz));
+    }
+
+    /**
+     * Returns all registered features.
+     */
+    public Collection<NoxesiumFeature> getAllFeatures() {
+        return features.values();
+    }
+
+    /**
+     * Returns the entrypoint with the given id.
+     */
+    @Nullable
+    public NoxesiumEntrypoint getEntrypoint(String id) {
+        return entrypoints.get(id);
+    }
+
+    /**
+     * Returns all active entrypoints.
+     */
+    public Collection<NoxesiumEntrypoint> getActiveEntrypoints() {
+        return activeEntrypoints;
+    }
+
+    /**
+     * Returns all registered entry points.
+     */
+    public Collection<NoxesiumEntrypoint> getAllEntrypoints() {
+        return entrypoints.values();
+    }
+}

api/src/main/java/com/noxcrew/noxesium/api/NoxesiumEntrypoint.java

@@ -0,0 +1,82 @@
+package com.noxcrew.noxesium.api;
+
+import com.noxcrew.noxesium.api.feature.NoxesiumFeature;
+import com.noxcrew.noxesium.api.network.PacketCollection;
+import com.noxcrew.noxesium.api.registry.RegistryCollection;
+import java.net.URL;
+import java.util.Collection;
+import java.util.List;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * An entrypoint for Noxesium which allows a mod or plugin to take control and register its features,
+ * registry contents, packets, and more. Each set of features implemented against Noxesium's APIs
+ * must be defined in an entrypoint.
+ * <p>
+ * All Noxesium entrypoints may provide both a private and public key. This system is used
+ * by the common module to serve as an implementation example. Of course this means that the
+ * common module's keys are all public in this repository which is intentional as it is only
+ * meant to be an example. If you make your own private implementation you should of course
+ * keep these files private and only ship the public server key with your client mod.
+ * <p>
+ * The system allows implementations to be shielded from unauthorized clients that do not have the
+ * correct private key expected by the other side of the implementation. This prevents the client from
+ * leaking any registries unless the server can correctly authenticate itself.
+ * <p>
+ * The handshake process for Noxesium runs for all entrypoints simultaneously, but includes
+ * the following steps before it can be completed:
+ * 1) The server-side implementation shares with the client that it can receive handshake packets.
+ * 2) The client-side implementation sends a handshake initiation with a series of entrypoint ids
+ * encrypted using a shared encryption key of each entrypoint when joining a server or entering the
+ * configuration phase.
+ * 3) The server-side implementation responds with an acknowledgement containing a list of entry
+ * point ids it could decrypt in plain text.
+ * 4) The client-side implementation responds with an acknowledgement containing a list of the
+ * validated entrypoints and their protocol details. It registers all packet handlers for this entrypoint.
+ * 5) The server-side implementation receives the answer, registers all plugin channels defined and
+ * performs relevant initialization steps.
+ * 6) The server-side sends all registry contents to the client. Receiving back an acknowledgement of
+ * the registry entries which existed on the client and which ones did not.
+ * 7) The server-side sends a handshake completion packet when it is fully done.
+ */
+public interface NoxesiumEntrypoint {
+    /**
+     * Returns the identifier of this entrypoint. This must be globally unique from
+     * all other installed entrypoints.
+     */
+    String getId();
+
+    /**
+     * Returns instances for all features of this entrypoint. These can be re-created on
+     * every initialization or re-used between re-initializations.
+     */
+    default Collection<NoxesiumFeature> getAllFeatures() {
+        return List.of();
+    }
+
+    /**
+     * Returns all registry collections included in this entrypoint.
+     */
+    default Collection<RegistryCollection<?>> getRegistryCollections() {
+        return List.of();
+    }
+
+    /**
+     * Returns all packet collections included in this entrypoint.
+     */
+    default Collection<PacketCollection> getPacketCollections() {
+        return List.of();
+    }
+
+    /**
+     * Returns an optional location of this entrypoint's base64 encoded AES-256 key resource to use for
+     * securely authenticating that a valid client and server implementation of the same entrypoint are present.
+     * <p>
+     * An AES key is used as it is expected that anyone in possession of either sources is allowed to communicate
+     * with the other side.
+     */
+    @Nullable
+    default URL getEncryptionKey() {
+        return null;
+    }
+}