MB Dev Notes added to critical classes.

src/engine/InterestManagement/RealmMap.java

@@ -8,10 +8,6 @@
 
 package engine.InterestManagement;
 
-/* This class is the main interface for Magicbane's
- *  Interest management facilities.
- */
-
 import engine.math.Vector3fImmutable;
 import engine.mbEnums;
 import engine.net.Dispatch;
@@ -31,10 +27,17 @@ import static engine.objects.Realm.getRealm;
 
 public enum RealmMap {
 
-    REALM_MAP;
+    // MB Dev Notes:
+    // This class loads and caches realm maps used by each
+    // map set for its realm overlay.  The RealmMap loaded is
+    // controlled by config entry MB_WORLD_REALMMAP
+    //
+    // Unlike a Heightmap this is a just color lookup; identical to
+    // the old image maps used in 90s web technology.
+    //
+    // Realm Map images are stored on disk in /mb.data/realmmaps/
 
-    // Spatial hashmap.  Used for determining which Realm
+    REALM_MAP;
-    // a player is currently located within.
 
     private static final HashMap<Color, Integer> _rgbToIDMap = new HashMap<>();
     public static int[][] _realmImageMap;

src/engine/InterestManagement/Terrain.java

@@ -18,6 +18,14 @@ import java.util.HashMap;
 
 import static java.lang.Math.PI;
 
+
+// MB Dev Notes:
+// The Terrain class handles lookups into the Heightmap data.
+// It supports all current maps along with the differences in
+// their parenting configuration.
+//
+// Heightmap images are stored on disk in /mb.data/heightmaps/
+
 public class Terrain {
     public static final HashMap<Integer, short[][]> _heightmap_pixel_cache = new HashMap<>();
     public short[][] terrain_pixel_data;

src/engine/gameManager/SimulationManager.java

@@ -24,10 +24,16 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.Collection;
 
-/*
+// MB Dev Notes:
- * This class contains all methods necessary to drive periodic
+//
- * updates of the game simulation from the main _exec loop.
+// Class models timers that drive Magicbane simulation ticks used
- */
+// for movement updates, triggers and more.  Eventually we hope to
+// refactor to more of a traditional simulation appropriate for a
+// mmo with a transform class and other bells and whistles.
+//
+// Do as little as possible in here.  For any tick you do not want
+// deltaTime to approach 1.0f.
+
 public enum SimulationManager {
 
     SERVERHEARTBEAT;
@@ -35,15 +41,14 @@ public enum SimulationManager {
     private static final long CITY_PULSE = 2000;
     private static final long RUNEGATE_PULSE = 3000;
     private static final long UPDATE_PULSE = 1000;
-    private static final long FlIGHT_PULSE = 100;
+    private static final long FLIGHT_PULSE = 100;
     public static Duration executionTime = Duration.ofNanos(1);
     public static Duration executionMax = Duration.ofNanos(1);
-    private static SimulationManager instance = null;
     private long _cityPulseTime = System.currentTimeMillis() + CITY_PULSE;
     private long _runegatePulseTime = System.currentTimeMillis()
             + RUNEGATE_PULSE;
     private long _updatePulseTime = System.currentTimeMillis() + UPDATE_PULSE;
-    private long _flightPulseTime = System.currentTimeMillis() + FlIGHT_PULSE;
+    private long _flightPulseTime = System.currentTimeMillis() + FLIGHT_PULSE;
 
     private SimulationManager() {
 
@@ -181,7 +186,7 @@ public enum SimulationManager {
             player.updateFlight();
         }
 
-        _flightPulseTime = System.currentTimeMillis() + FlIGHT_PULSE;
+        _flightPulseTime = System.currentTimeMillis() + FLIGHT_PULSE;
     }
 
     private void pulseCities() {

src/engine/loot/WorkOrder.java

@@ -33,7 +33,7 @@ public class WorkOrder implements Delayed {
 
     // MB Dev notes:
     // Class defines a Forge rolling request made through a
-    // vendor and then passed to the ForgeManager singleton
+    // vendor; then passed to the ForgeManager singleton
     // for completion.
     //
     // A workOrder once created will last until all items are

src/engine/net/MessageDispatcher.java

@@ -17,29 +17,31 @@ import java.util.concurrent.LinkedBlockingQueue;
 import java.util.concurrent.atomic.LongAdder;
 import java.util.regex.Pattern;
 
-/**
+// MB Dev Notes:
- * Thread blocks until MagicBane dispatch messages are
+// All outgoing Protocol messages to the player are managed through the MessageDispatcher.class.
- * enqueued then processes them in FIFO order. The collection
+// All incoming Protocol messages from the player are managed by the Protocol.class.
- * is thread safe.
+//
- * <p>
+// A DispatchMessage is configured then wrapped in a Dispatch for a distribution list.
- * Any large messages not time sensitive such as load object
+// A Dispatch can be submitted to the Dispatcher from any thread.
- * sent to more than a single individual should be spawned
+//
- * individually on a DispatchMessageThread.
+// Dispatches are interleaved between channels.  This is to ensure
- */
+// a combat or movement message is not delayed by spam clicking a
+// larger message.  Choose your channel wisely.
 
 public class MessageDispatcher implements Runnable {
 
     // Instance variables
 
-    @SuppressWarnings("unchecked") // Cannot have arrays of generics in java.
     private static final ConcurrentLinkedQueue<Dispatch>[] _messageQueue = new ConcurrentLinkedQueue[DispatchChannel.values().length];
     private static final LinkedBlockingQueue<Boolean> _blockingQueue = new LinkedBlockingQueue<>();
 
     // Class variables
+
     public static volatile long[] messageCount = new long[DispatchChannel.values().length];
     public static LongAdder[] dispatchCount = new LongAdder[DispatchChannel.values().length];
 
     // Performance metrics
+
     public static volatile long[] maxRecipients = new long[DispatchChannel.values().length];
     public static LongAdder itemPoolSize = new LongAdder();
     private final Pattern filterPattern; // Unused, but just in case
@@ -61,39 +63,6 @@ public class MessageDispatcher implements Runnable {
 
     }
 
-    public static void send(Dispatch messageDispatch, DispatchChannel dispatchChannel) {
-
-        // Don't queue up empty dispatches!
-
-        if (messageDispatch.player == null)
-            return;
-
-        _messageQueue[dispatchChannel.getChannelID()].add(messageDispatch);
-        _blockingQueue.add(true);
-
-        // Update performance metrics
-
-        messageCount[dispatchChannel.getChannelID()]++;
-
-    }
-
-    public static String getNetstatString() {
-
-        String outString = null;
-        String newLine = System.getProperty("line.separator");
-        outString = "[LUA_NETSTA()]" + newLine;
-        outString += "poolSize: " + itemPoolSize.longValue() + '\n';
-
-        for (DispatchChannel dispatchChannel : DispatchChannel.values()) {
-
-            outString += "Channel: " + dispatchChannel.name() + '\n';
-            outString += "Dispatches: " + dispatchCount[dispatchChannel.getChannelID()].longValue() + '\n';
-            outString += "Messages: " + messageCount[dispatchChannel.getChannelID()] + '\n';
-            outString += "maxRecipients: " + maxRecipients[dispatchChannel.getChannelID()] + '\n';
-        }
-        return outString;
-    }
-
     @Override
     public void run() {
 
@@ -112,12 +81,10 @@ public class MessageDispatcher implements Runnable {
                         DispatchMessage.serializeDispatch(this.messageDispatch);
                         shouldBlock = false;
                     }
-
                 }
 
                 if (shouldBlock == true)
                     shouldBlock = _blockingQueue.take();
-
             } catch (Exception e) {
                 Logger.error(e);
             }
@@ -125,6 +92,38 @@ public class MessageDispatcher implements Runnable {
         }
     }
 
+    public static void send(Dispatch messageDispatch, DispatchChannel dispatchChannel) {
+
+        // Don't queue up empty dispatches!
+
+        if (messageDispatch.player == null)
+            return;
+
+        _messageQueue[dispatchChannel.getChannelID()].add(messageDispatch);
+        _blockingQueue.add(true);
+
+        // Update performance metrics
+
+        messageCount[dispatchChannel.getChannelID()]++;
+    }
+
+    public static String getNetstatString() {
+
+        String outString;
+        String newLine = System.getProperty("line.separator");
+        outString = "[LUA_NETSTA()]" + newLine;
+        outString += "poolSize: " + itemPoolSize.longValue() + '\n';
+
+        for (DispatchChannel dispatchChannel : DispatchChannel.values()) {
+
+            outString += "Channel: " + dispatchChannel.name() + '\n';
+            outString += "Dispatches: " + dispatchCount[dispatchChannel.getChannelID()].longValue() + '\n';
+            outString += "Messages: " + messageCount[dispatchChannel.getChannelID()] + '\n';
+            outString += "maxRecipients: " + maxRecipients[dispatchChannel.getChannelID()] + '\n';
+        }
+        return outString;
+    }
+
     // For Debugging:
     //Logger.error("MessageDispatcher", messageDispatch.msg.getOpcodeAsString() + " sent to " + messageDispatch.playerList.size() + " players");
 }

src/engine/net/Protocol.java

@@ -1,8 +1,12 @@
+// • ▌ ▄ ·.  ▄▄▄·  ▄▄ • ▪   ▄▄· ▄▄▄▄·  ▄▄▄·  ▐▄▄▄  ▄▄▄ .
+// ·██ ▐███▪▐█ ▀█ ▐█ ▀ ▪██ ▐█ ▌▪▐█ ▀█▪▐█ ▀█ •█▌ ▐█▐▌·
+// ▐█ ▌▐▌▐█·▄█▀▀█ ▄█ ▀█▄▐█·██ ▄▄▐█▀▀█▄▄█▀▀█ ▐█▐ ▐▌▐▀▀▀
+// ██ ██▌▐█▌▐█ ▪▐▌▐█▄▪▐█▐█▌▐███▌██▄▪▐█▐█ ▪▐▌██▐ █▌▐█▄▄▌
+// ▀▀  █▪▀▀▀ ▀  ▀ ·▀▀▀▀ ▀▀▀·▀▀▀ ·▀▀▀▀  ▀  ▀ ▀▀  █▪ ▀▀▀
+//      Magicbane Emulator Project © 2013 - 2022
+//                www.magicbane.com
 package engine.net;
 
-/* This class defines Magicbane's application network protocol.
--->  Name / Opcode / Message / Handler
- */
 
 import engine.net.client.handlers.*;
 import engine.net.client.msg.*;
@@ -16,6 +20,13 @@ import org.pmw.tinylog.Logger;
 import java.lang.reflect.Constructor;
 import java.util.HashMap;
 
+// MB Dev Notes:
+// This class defines the application network protocol used by SB.
+// -->  Name / Opcode / Message / Handler
+//
+// All incoming Protocol messages from the player are managed by the Protocol.class.
+// All outgoing Protocol messages to the player are managed through the MessageDispatcher.class.
+
 public enum Protocol {
 
     NONE(0x0, null, null),
@@ -286,9 +297,7 @@ public enum Protocol {
 
     public static boolean handleClientMsg(ClientNetMsg msg) {
 
-        // Main message handler for Magicbane.  All messages
+        // Process incoming Protocol message from client.
-        // incoming from the client are executed here for
-        // both the login and world servers.
 
         if (msg == null)
             return false;