add server-side waypoint event API

common/src/main/java/journeymap/api/v2/common/event/CommonEventRegistry.java

@@ -2,6 +2,7 @@
 
 import journeymap.api.v2.client.IClientAPI;
 import journeymap.api.v2.client.IClientPlugin;
+import journeymap.api.v2.common.event.common.DeathWaypointEvent;
 import journeymap.api.v2.common.event.common.TeleportEvent;
 import journeymap.api.v2.common.event.common.WaypointEvent;
 import journeymap.api.v2.common.event.common.WaypointGroupEvent;
@@ -36,4 +37,12 @@ public class CommonEventRegistry
      * This event fires when a waypoint is transferred from one group to another, from may be null.
      */
     public static final Event<WaypointGroupTransferEvent> WAYPOINT_GROUP_TRANSFER_EVENT = EventFactory.create(WaypointGroupTransferEvent.class);
+
+    /**
+     * Fired before a death waypoint is created. Cancellable. Fires both client-side
+     * (singleplayer or non-JM-managed servers) and server-side (JourneyMap-managed
+     * servers). The plain {@link WaypointEvent} CREATE is suppressed for death
+     * waypoints so subscribers receive exactly one notification per death.
+     */
+    public static final Event<DeathWaypointEvent> DEATH_WAYPOINT_EVENT = EventFactory.create(DeathWaypointEvent.class);
 }

common/src/main/java/journeymap/api/v2/common/event/common/DeathWaypointEvent.java

@@ -0,0 +1,62 @@
+package journeymap.api.v2.common.event.common;
+
+import com.google.common.base.MoreObjects;
+import journeymap.api.v2.common.event.impl.CommonEvent;
+import journeymap.api.v2.common.waypoint.Waypoint;
+import net.minecraft.core.BlockPos;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.Level;
+
+/**
+ * Fired before a death waypoint is created, both client-side (singleplayer or
+ * non-JM-managed servers) and server-side (JourneyMap-managed servers).
+ * Cancelling the event prevents the death waypoint from being created.
+ *
+ * <p>The plain {@link WaypointEvent} with {@link WaypointEvent.Context#CREATE}
+ * is suppressed for death waypoints so addons subscribing to either receive
+ * exactly one notification per death.</p>
+ */
+public class DeathWaypointEvent extends CommonEvent
+{
+    private final Waypoint waypoint;
+    private final BlockPos location;
+    private final ResourceKey<Level> dimension;
+
+    public DeathWaypointEvent(Waypoint waypoint, BlockPos location, ResourceKey<Level> dimension, Side side)
+    {
+        super(true, side);
+        this.waypoint = waypoint;
+        this.location = location;
+        this.dimension = dimension;
+    }
+
+    /**
+     * The death waypoint being created. Mutating fields on it before the event
+     * returns will be reflected in the persisted waypoint (if not cancelled).
+     */
+    public Waypoint getWaypoint()
+    {
+        return waypoint;
+    }
+
+    public BlockPos getLocation()
+    {
+        return location;
+    }
+
+    public ResourceKey<Level> getDimension()
+    {
+        return dimension;
+    }
+
+    @Override
+    public String toString()
+    {
+        return MoreObjects.toStringHelper(this)
+                .add("waypoint", waypoint)
+                .add("location", location)
+                .add("dimension", dimension)
+                .add("side", getSide())
+                .toString();
+    }
+}

common/src/main/java/journeymap/api/v2/common/event/common/WaypointEvent.java

@@ -24,6 +24,17 @@ public WaypointEvent(Waypoint waypoint, Context context, ResourceKey<Level> dime
         this.context = context;
     }
 
+    /**
+     * Server-side constructor. Use when firing from a server context.
+     */
+    public WaypointEvent(Waypoint waypoint, Context context, ResourceKey<Level> dimension, Side side)
+    {
+        super(context.cancelable, side);
+        this.dimension = dimension;
+        this.waypoint = waypoint;
+        this.context = context;
+    }
+
     /**
      * World dimension where event occurred.
      */

common/src/main/java/journeymap/api/v2/common/waypoint/Waypoint.java

@@ -32,6 +32,24 @@ public interface Waypoint
 
     void setName(String name);
 
+    /**
+     * Optional free-form description shown in the waypoint manager tooltip.
+     * Implementations may treat values starting with {@code "jm."} as i18n keys.
+     * Default returns {@code null} for backwards compatibility with addons that
+     * implement {@link Waypoint} directly.
+     */
+    default @Nullable String getDescription()
+    {
+        return null;
+    }
+
+    /**
+     * @see #getDescription()
+     */
+    default void setDescription(@Nullable String description)
+    {
+    }
+
     void setPos(int x, int y, int z);
 
     void setBlockPos(BlockPos pos);

common/src/main/java/journeymap/api/v2/common/waypoint/WaypointFactory.java

@@ -26,6 +26,39 @@ private static WaypointFactory getInstance()
         return INSTANCE;
     }
 
+    /**
+     * Creates a Waypoint. On the client side this will be a ClientWaypoint; on the server side this
+     * will be a plain WaypointImpl.
+     *
+     * @param modId            - The modid of the mod creating the waypoint
+     * @param pos              - The BlockPos of the waypoint
+     * @param name             - The Optional Name of the waypoint. If null, it will use the coordinates as the name.
+     * @param primaryDimension - The primary dimension identifier string.
+     * @param persistent       - should the waypoint persist between sessions?
+     *                         True, JourneyMap will save this waypoint to disk and load every session it only needs to be sent once.
+     *                         False, The waypoint will be flushed when the user changes dimensions and exits the game.
+     * @return - The Waypoint with default values set.
+     */
+    public static Waypoint createWaypoint(String modId, BlockPos pos, @Nullable String name, ResourceKey<Level> primaryDimension, boolean persistent)
+    {
+        return createWaypoint(modId, pos, name, primaryDimension.location().toString(), persistent);
+    }
+
+    public static Waypoint createWaypoint(String modId, BlockPos pos, ResourceKey<Level> primaryDimension, boolean persistent)
+    {
+        return createWaypoint(modId, pos, primaryDimension.location().toString(), persistent);
+    }
+
+    public static Waypoint createWaypoint(String modId, BlockPos pos, String primaryDimension, boolean persistent)
+    {
+        return createWaypoint(modId, pos, null, primaryDimension, persistent);
+    }
+
+    public static Waypoint createWaypoint(String modId, BlockPos pos, @Nullable String name, String primaryDimension, boolean persistent)
+    {
+        return getInstance().store.createWaypoint(modId, pos, name, primaryDimension, persistent);
+    }
+
     /**
      * Creates a ClientWaypoint.
      *
@@ -38,22 +71,27 @@ private static WaypointFactory getInstance()
      *                         True, JourneyMap will save this waypoint to disk and load every session it only needs to be sent once.
      *                         False, The waypoint will be flushed when the user changes dimensions and exits the game.
      * @return - The Waypoint with default values set.
+     * @deprecated Use {@link #createWaypoint(String, BlockPos, String, String, boolean)} instead.
      */
+    @Deprecated
     public static Waypoint createClientWaypoint(String modId, BlockPos pos, @Nullable String name, ResourceKey<Level> primaryDimension, boolean persistent)
     {
         return createClientWaypoint(modId, pos, name, primaryDimension.location().toString(), persistent);
     }
 
+    @Deprecated
     public static Waypoint createClientWaypoint(String modId, BlockPos pos, ResourceKey<Level> primaryDimension, boolean persistent)
     {
         return createClientWaypoint(modId, pos, primaryDimension.location().toString(), persistent);
     }
 
+    @Deprecated
     public static Waypoint createClientWaypoint(String modId, BlockPos pos, String primaryDimension, boolean persistent)
     {
         return createClientWaypoint(modId, pos, null, primaryDimension, persistent);
     }
 
+    @Deprecated
     public static Waypoint createClientWaypoint(String modId, BlockPos pos, @Nullable String name, String primaryDimension, boolean persistent)
     {
         return getInstance().store.createClientWaypoint(modId, pos, name, primaryDimension, persistent);
@@ -78,6 +116,9 @@ public static WaypointGroup createWaypointGroup(String modId, String name)
     @ApiStatus.Internal
     public interface WaypointStore
     {
+        Waypoint createWaypoint(String modId, BlockPos pos, @Nullable String name, String primaryDimension, boolean persistent);
+
+        @Deprecated
         Waypoint createClientWaypoint(String modId, BlockPos pos, @Nullable String name, String primaryDimension, boolean persistent);
 
         Waypoint fromWaypointJsonString(String waypoint);