Get Started with Nexus Core

Learn how to register your first DataAddon with Nexus Core v1.5.1, send a signed request, and receive a signed response in under 10 minutes.

This guide assumes Nexus Core is already installed and running. If not, follow the Installation guide first. By the end of this page, you will have a working DataAddon registered and a signed packet flowing from a Spigot server through Redis to MongoDB and back.

Prerequisites

• Nexus Core v1.5.1 running with the web panel accessible at http://localhost:8080
• NEXUS_SIGNING_KEY set to the same value on Nexus Core and your Spigot server
• Redis and MongoDB connected (verified in the web panel)

Steps

1. Create a DataAddon class

   Create a class that extends DataAddon, implement the required methods, and annotate your document fields with @DbDataModels. The addon below stores player statistics in a player_stats MongoDB collection.

   package network.darkland.addons;
   
   import network.darkland.protocol.DataAddon;
   import network.darkland.protocol.NexusJsonDataContainer;
   import network.darkland.protocol.backup.annotations.DbDataModels;
   
   public class PlayerStatsAddon extends DataAddon {
   
       @Override
       public int addonId() {
           return 100; // Must be globally unique across all addons
       }
   
       @Override
       public String addonName() {
           return "Player Stats";
       }
   
       @Override
       public String getDatabase() {
           return "nexus_core_db";
       }
   
       @Override
       public String getCollection() {
           return "player_stats";
       }
   
       @Override
       public String cacheKeyHeaderTag() {
           return "stats"; // Redis key: "stats_<uuid>"
       }
   
       @DbDataModels(isId = true)
       private String uuid;
   
       @DbDataModels(defaultValue = "0", isId = false)
       private int kills;
   
       @DbDataModels(defaultValue = "0", isId = false)
       private int deaths;
   
       @DbDataModels(defaultValue = "0.0", isId = false)
       private double balance;
   
       @DbDataModels(defaultValue = "false", isId = false)
       private boolean isPremium;
   
       @Override
       public boolean handleRequest(String source, RequestType requestType,
                                    NexusJsonDataContainer data) {
           // Only allow deletes from the admin server
           if (requestType == RequestType.REMOVE_DATA) {
               return source.equals("admin");
           }
           return true;
       }
   }
   
2. Register the addon on startup

   Register the addon with the protocol handler during your application startup:

   NexusApplication.getInstance()
       .getProtocolHandler()
       .registerAddon(new PlayerStatsAddon());
   

   Nexus Core now routes all requests for protocol ID 100 to the player_stats collection automatically.

3. Send a signed request from your Spigot server

   On the Spigot side, construct a signed JSON packet and publish it to the Nexus Redis channel. As of v1.5.1, Nexus Core also signs its outgoing responses, so your client must be ready to verify the sig, timestamp, and nonce fields on the response.

   GET_DATA request:

   {
     "protocol": 100,
     "source": "pvp-1",
     "type": "GET_DATA",
     "data": {
       "uuid": "550e8400-e29b-41d4-a716-446655440000"
     },
     "timestamp": 1756900000000,
     "nonce": "b7f2b1b0-4b3b-4e29-9e2b-6b8f2b1b0b7f",
     "sig": "<base64-hmac-sha256>"
   }
   

   Build the sig field by computing HmacSHA256(NEXUS_SIGNING_KEY, allFieldsExceptSig) and encoding the result as Base64.

4. Receive and verify the signed response

   Nexus Core publishes the response to your server’s Redis channel. Since v1.5.1, responses also include timestamp, nonce, and sig fields. Verify the signature before trusting the data:

   {
     "protocol": 100,
     "source": "nexus",
     "type": "BROADCAST",
     "target": "pvp-1",
     "data": {
       "uuid": "550e8400-e29b-41d4-a716-446655440000",
       "kills": 142,
       "deaths": 38,
       "balance": 2500.75,
       "isPremium": true
     },
     "timestamp": 1756900000123,
     "nonce": "a1b2c3d4-...",
     "sig": "<base64-hmac-sha256>"
   }
   

Next Steps

Building Addons

Learn how to define schemas, gate requests, and build production-ready addons.

Security

Understand symmetric HMAC signing on both inbound and outbound messages.