Map render rework: correct projection & grid, RustMaps #info map, per-server grid style

.editorconfig

@@ -392,6 +392,7 @@ roslynator_compiler_diagnostic_fixes.enabled = true
 dotnet_diagnostic.CA1002.severity = none # Do not expose generic lists — API uses List<T> intentionally for protobuf collections
 dotnet_diagnostic.CA1008.severity = none # Enums should have zero value
 dotnet_diagnostic.CA1031.severity = none # Do not catch general exception types (intentional for fail-safe CLI resilience)
+dotnet_diagnostic.CA1054.severity = none # Uri parameters should not be strings — same call as CA1056 below; RustMaps URLs travel as plain strings end to end
 dotnet_diagnostic.CA1056.severity = none # Uri properties should not be strings
 dotnet_diagnostic.CA1303.severity = none # Do not pass literals as localized parameters (literal strings in console output — CLI tool not localized)
 dotnet_diagnostic.CA1308.severity = none # Normalize strings to uppercase

Directory.Packages.props

@@ -13,8 +13,9 @@
     <PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.9" />
     <PackageVersion Include="Persistord.Core" Version="1.0.0-beta.1" />
-    <PackageVersion Include="RustPlusApi" Version="2.0.0-beta.3" />
-    <PackageVersion Include="RustPlusApi.Fcm" Version="2.0.0-beta.3" />
+    <PackageVersion Include="RustMapsApi" Version="1.0.0-beta.2" />
+    <PackageVersion Include="RustPlusApi" Version="2.0.0-beta.4" />
+    <PackageVersion Include="RustPlusApi.Fcm" Version="2.0.0-beta.4" />
     <PackageVersion Include="Serilog.Extensions.Hosting" Version="10.0.0" />
     <PackageVersion Include="Serilog.Settings.Configuration" Version="10.0.1" />
     <PackageVersion Include="Serilog.Sinks.Console" Version="6.1.1" />

RustPlusBot.slnx

@@ -21,6 +21,7 @@
   </Folder>
   <Folder Name="/tools/">
     <Project Path="tools/RustPlusBot.ItemData.Generator/RustPlusBot.ItemData.Generator.csproj" />
+    <Project Path="tools/RustPlusBot.MapParity/RustPlusBot.MapParity.csproj" />
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/RustPlusBot.Abstractions.Tests/RustPlusBot.Abstractions.Tests.csproj" />

src/RustPlusBot.Abstractions/Connections/IRustServerQuery.cs

@@ -46,6 +46,13 @@ public interface IRustServerQuery
     /// <returns>The map dimensions, or null when there is no live socket.</returns>
     Task<MapDimensions?> GetMapDimensionsAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);
 
+    /// <summary>Gets the world size and seed of a connected server, or null when unavailable.</summary>
+    /// <param name="guildId">The owning guild snowflake.</param>
+    /// <param name="serverId">The target server id.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>The world snapshot, or null.</returns>
+    Task<WorldSnapshot?> GetWorldAsync(ulong guildId, Guid serverId, CancellationToken cancellationToken);
+
     /// <summary>Gets the server's monuments, or an empty list when there is no live socket.</summary>
     /// <param name="guildId">The owning guild snowflake.</param>
     /// <param name="serverId">The target server id.</param>

src/RustPlusBot.Abstractions/Connections/MapDimensions.cs

@@ -1,7 +1,8 @@
 namespace RustPlusBot.Abstractions.Connections;
 
-/// <summary>The static-per-wipe map size needed to convert world coordinates to a grid reference.</summary>
-/// <param name="Width">Map image width.</param>
-/// <param name="Height">Map image height.</param>
-/// <param name="OceanMargin">The ocean margin around the playable area.</param>
-public sealed record MapDimensions(uint Width, uint Height, int OceanMargin);
+/// <summary>Dimensions of the server-rendered map tile plus the world size.</summary>
+/// <param name="Width">Width of the base map image, in pixels.</param>
+/// <param name="Height">Height of the base map image, in pixels.</param>
+/// <param name="OceanMargin">Ocean border baked into the base map image, in pixels.</param>
+/// <param name="WorldSize">Size of the playable world, in game units (from server info).</param>
+public sealed record MapDimensions(uint Width, uint Height, int OceanMargin, uint WorldSize);

src/RustPlusBot.Abstractions/Connections/MapGrid.cs

@@ -0,0 +1,77 @@
+using System.Globalization;
+using System.Text;
+
+namespace RustPlusBot.Abstractions.Connections;
+
+/// <summary>
+/// Rust map grid math shared by the map renderer and grid-reference formatting.
+/// One cell is 146.25 game units; the grid is anchored at the world's NORTH-WEST corner
+/// (Rust / RustMaps / companion-app behaviour): columns are lettered west→east from A, rows are
+/// numbered north→south from 0, and the partial edge cell (when the world size is not a whole
+/// multiple of the cell size) sits along the south and east edges.
+/// </summary>
+public static class MapGrid
+{
+    /// <summary>Edge length of one (whole) grid cell, in game units.</summary>
+    public const float CellSize = 146.25f;
+
+    /// <summary>
+    /// How far south of the world's north edge the Rust+/RustMaps grid rows start, in game units.
+    /// Measured exactly (100.0) from RustMaps' own pre-rendered grid tiles across map sizes
+    /// 1500–4500; the in-game (F1) map uses no inset. Columns have no inset in either style.
+    /// </summary>
+    public const float RustPlusRowInset = 100f;
+
+    /// <summary>Gets the row inset (south of the world's north edge) for a grid style.</summary>
+    /// <param name="style">The grid style.</param>
+    /// <returns>The inset in game units.</returns>
+    public static float RowInset(MapGridStyle style) =>
+        style == MapGridStyle.RustPlus ? RustPlusRowInset : 0f;
+
+    /// <summary>
+    /// Number of grid cells per axis, covering the whole world size — <c>ceil(worldSize / CellSize)</c>.
+    /// The last cell (east-most column / south-most row) is a partial edge cell whenever the world size
+    /// is not a whole multiple of <see cref="CellSize"/>; it is still a labelled cell, matching how Rust,
+    /// the Rust+ companion app and RustMaps draw the grid. (A 1500 world → 11 cells: A–K, rows 0–10.)
+    /// </summary>
+    /// <param name="worldSize">The world size in game units.</param>
+    /// <returns>The cell count (at least 1).</returns>
+    public static int CellCount(uint worldSize)
+    {
+        var full = (int)(worldSize / CellSize);
+        var hasPartial = worldSize - (full * CellSize) > 0.5f;
+        return Math.Max(1, hasPartial ? full + 1 : full);
+    }
+
+    /// <summary>Formats a spreadsheet-style column label (0→A … 25→Z, 26→AA …).</summary>
+    /// <param name="index">The zero-based column index.</param>
+    /// <returns>The column letters.</returns>
+    public static string ColumnLetters(int index)
+    {
+        var sb = new StringBuilder();
+        var n = index;
+        do
+        {
+            sb.Insert(0, (char)('A' + (n % 26)));
+            n = (n / 26) - 1;
+        } while (n >= 0);
+
+        return sb.ToString();
+    }
+
+    /// <summary>Formats the grid label ("D7") for a world coordinate.</summary>
+    /// <param name="x">World X (west→east).</param>
+    /// <param name="y">World Y (south→north).</param>
+    /// <param name="worldSize">The world size in game units.</param>
+    /// <param name="style">Which grid convention to bin against (defaults to the in-game map).</param>
+    /// <returns>The grid label, rows numbered from the top; out-of-world coordinates clamp to the edge cell.</returns>
+    public static string LabelFor(float x, float y, uint worldSize, MapGridStyle style = MapGridStyle.InGame)
+    {
+        // Rows bin from the style's row anchor (north edge in-game; 100 units south of it for
+        // Rust+/RustMaps), not the south — with a partial edge cell the two directions disagree.
+        var cells = CellCount(worldSize);
+        var col = Math.Clamp((int)MathF.Floor(x / CellSize), 0, cells - 1);
+        var row = Math.Clamp((int)MathF.Floor((worldSize - RowInset(style) - y) / CellSize), 0, cells - 1);
+        return string.Create(CultureInfo.InvariantCulture, $"{ColumnLetters(col)}{row}");
+    }
+}

src/RustPlusBot.Abstractions/Connections/MapGridStyle.cs

@@ -0,0 +1,15 @@
+namespace RustPlusBot.Abstractions.Connections;
+
+/// <summary>
+/// Which map-grid convention to use. The in-game (F1) map and the Rust+ companion app / RustMaps
+/// website disagree on where grid ROWS sit: the in-game map anchors row 0 at the world's north edge,
+/// while Rust+/RustMaps draw the rows 100 game-units further south. Columns are identical in both.
+/// </summary>
+public enum MapGridStyle
+{
+    /// <summary>Match the in-game (F1) map — grid references read exactly like in-game callouts.</summary>
+    InGame = 0,
+
+    /// <summary>Match the Rust+ companion app and rustmaps.com — rows sit 100 game-units south of in-game.</summary>
+    RustPlus = 1,
+}

src/RustPlusBot.Abstractions/Connections/MapMarkerSnapshot.cs

@@ -1,9 +1,18 @@
 namespace RustPlusBot.Abstractions.Connections;
 
+// Rotation defaults to null so existing call sites stay valid and "no heading" is distinguishable
+// from "heading north" once RustPlusApi beta.4 supplies values.
 /// <summary>One map marker observed in a <c>GetMapMarkers</c> poll.</summary>
 /// <param name="Id">The stable marker id (used to diff polls).</param>
 /// <param name="Kind">The classified marker kind.</param>
 /// <param name="X">World X coordinate.</param>
 /// <param name="Y">World Y coordinate.</param>
 /// <param name="Name">The marker name, if any.</param>
-public sealed record MapMarkerSnapshot(ulong Id, MarkerKind Kind, float X, float Y, string? Name);
+/// <param name="Rotation">Heading in degrees as sent by the server, or null when unavailable.</param>
+public sealed record MapMarkerSnapshot(
+    ulong Id,
+    MarkerKind Kind,
+    float X,
+    float Y,
+    string? Name,
+    float? Rotation = null);

src/RustPlusBot.Abstractions/Connections/MonumentSnapshot.cs

@@ -1,7 +1,7 @@
 namespace RustPlusBot.Abstractions.Connections;
 
 /// <summary>One named monument observed in a <c>GetMap</c> response.</summary>
-/// <param name="Token">The monument token (e.g. <c>oilrig_1</c>, <c>large_oil_rig</c>).</param>
+/// <param name="Token">The monument token (e.g. <c>oil_rig_small</c>, <c>large_oil_rig</c>).</param>
 /// <param name="X">World X coordinate.</param>
 /// <param name="Y">World Y coordinate.</param>
 public sealed record MonumentSnapshot(string Token, float X, float Y);

src/RustPlusBot.Abstractions/Connections/WorldSnapshot.cs

@@ -0,0 +1,6 @@
+namespace RustPlusBot.Abstractions.Connections;
+
+/// <summary>The world identity of a connected server, used to resolve external map imagery.</summary>
+/// <param name="WorldSize">Size of the playable world, in game units.</param>
+/// <param name="Seed">Procedural map generation seed.</param>
+public sealed record WorldSnapshot(uint WorldSize, uint Seed);

src/RustPlusBot.Abstractions/Events/InfoMapReadyEvent.cs

@@ -0,0 +1,6 @@
+namespace RustPlusBot.Abstractions.Events;
+
+/// <summary>Published when a server's RustMaps #info map becomes ready, so its reconciled message repaints.</summary>
+/// <param name="GuildId">The owning guild snowflake.</param>
+/// <param name="ServerId">The target server id.</param>
+public sealed record InfoMapReadyEvent(ulong GuildId, Guid ServerId);

src/RustPlusBot.Abstractions/Events/MapMarkersChangedEvent.cs

@@ -2,15 +2,17 @@
 
 namespace RustPlusBot.Abstractions.Events;
 
-/// <summary>Published when a marker poll detects markers that appeared or disappeared since the previous poll.</summary>
+/// <summary>Published when a marker poll detects markers that appeared, disappeared, or moved since the previous poll.</summary>
 /// <param name="GuildId">The owning guild snowflake.</param>
 /// <param name="ServerId">The target server id.</param>
 /// <param name="Dimensions">Map dimensions for grid-reference rendering, or null if unavailable.</param>
 /// <param name="Added">Markers present now that were absent in the previous poll.</param>
 /// <param name="Removed">Markers absent now that were present in the previous poll.</param>
+/// <param name="Moved">Markers present in both polls whose position or rotation changed.</param>
 public sealed record MapMarkersChangedEvent(
     ulong GuildId,
     Guid ServerId,
     MapDimensions? Dimensions,
     IReadOnlyList<MapMarkerSnapshot> Added,
-    IReadOnlyList<MapMarkerSnapshot> Removed);
+    IReadOnlyList<MapMarkerSnapshot> Removed,
+    IReadOnlyList<MapMarkerSnapshot> Moved);

src/RustPlusBot.Abstractions/Events/RigKind.cs

@@ -3,7 +3,7 @@ namespace RustPlusBot.Abstractions.Events;
 /// <summary>Which oil rig a rig event refers to.</summary>
 public enum RigKind
 {
-    /// <summary>The small oil rig (monument token <c>oilrig_1</c>).</summary>
+    /// <summary>The small oil rig (monument token <c>oil_rig_small</c>).</summary>
     Small = 0,
 
     /// <summary>The large oil rig (monument token <c>large_oil_rig</c>).</summary>

src/RustPlusBot.Abstractions/Map/IInfoMapReadModel.cs

@@ -0,0 +1,11 @@
+namespace RustPlusBot.Abstractions.Map;
+
+/// <summary>Read seam over the RustMaps generation state, for the #info map renderer (cross-assembly).</summary>
+public interface IInfoMapReadModel
+{
+    /// <summary>The ready RustMaps map for a (size, seed), or null when it is not generated/ready yet.</summary>
+    /// <param name="size">The world size.</param>
+    /// <param name="seed">The map generation seed.</param>
+    /// <returns>The ready map view, or null.</returns>
+    InfoMapView? GetReady(int size, int seed);
+}

src/RustPlusBot.Abstractions/Map/InfoMapView.cs

@@ -0,0 +1,6 @@
+namespace RustPlusBot.Abstractions.Map;
+
+/// <summary>A ready RustMaps map for the #info map message: its hosted image URL plus its page link.</summary>
+/// <param name="ImageUrl">The RustMaps-hosted image URL (the monument-icon render).</param>
+/// <param name="RustMapsPageUrl">The RustMaps page URL for the map, when available.</param>
+public sealed record InfoMapView(string ImageUrl, string? RustMapsPageUrl);

src/RustPlusBot.Domain/Map/ServerMapSettings.cs

@@ -1,3 +1,5 @@
+using RustPlusBot.Abstractions.Connections;
+
 namespace RustPlusBot.Domain.Map;
 
 /// <summary>Per-(guild, server) rendered-map layer settings; one row per server. Layers default on.</summary>
@@ -26,4 +28,7 @@ public sealed class ServerMapSettings
 
     /// <summary>Whether oil rigs are styled by activation state.</summary>
     public bool ShowRigs { get; set; } = true;
+
+    /// <summary>Which grid convention the rendered map and event grid references use.</summary>
+    public MapGridStyle GridStyle { get; set; } = MapGridStyle.InGame;
 }

src/RustPlusBot.Features.Commands/Handlers/CargoCommandHandler.cs

@@ -3,24 +3,32 @@
 using RustPlusBot.Features.Commands.Dispatching;
 using RustPlusBot.Features.Events.State;
 using RustPlusBot.Localization;
+using RustPlusBot.Persistence.Map;
 
 namespace RustPlusBot.Features.Commands.Handlers;
 
 /// <summary>!cargo — reports the cargo ship's current grid position, if any.</summary>
 /// <param name="state">The live event state.</param>
 /// <param name="localizer">The reply localizer.</param>
 /// <param name="clock">For "how long ago".</param>
-internal sealed class CargoCommandHandler(IEventState state, ILocalizer localizer, IClock clock)
+/// <param name="mapSettings">Supplies the server's grid style.</param>
+internal sealed class CargoCommandHandler(
+    IEventState state,
+    ILocalizer localizer,
+    IClock clock,
+    IMapSettingsStore mapSettings)
     : ICommandHandler
 {
     /// <inheritdoc />
     public string Name => "cargo";
 
     /// <inheritdoc />
-    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    public async Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(context);
-        return Task.FromResult<string?>(
-            MarkerReply.For(state, context, MarkerKind.CargoShip, "command.cargo", localizer, clock));
+        return await MarkerReply
+            .ForAsync(state, context, MarkerKind.CargoShip, "command.cargo", localizer, clock, mapSettings,
+                cancellationToken)
+            .ConfigureAwait(false);
     }
 }

src/RustPlusBot.Features.Commands/Handlers/ChinookCommandHandler.cs

@@ -3,24 +3,32 @@
 using RustPlusBot.Features.Commands.Dispatching;
 using RustPlusBot.Features.Events.State;
 using RustPlusBot.Localization;
+using RustPlusBot.Persistence.Map;
 
 namespace RustPlusBot.Features.Commands.Handlers;
 
 /// <summary>!chinook — reports the Chinook helicopter's current grid position, if any.</summary>
 /// <param name="state">The live event state.</param>
 /// <param name="localizer">The reply localizer.</param>
 /// <param name="clock">For "how long ago".</param>
-internal sealed class ChinookCommandHandler(IEventState state, ILocalizer localizer, IClock clock)
+/// <param name="mapSettings">Supplies the server's grid style.</param>
+internal sealed class ChinookCommandHandler(
+    IEventState state,
+    ILocalizer localizer,
+    IClock clock,
+    IMapSettingsStore mapSettings)
     : ICommandHandler
 {
     /// <inheritdoc />
     public string Name => "chinook";
 
     /// <inheritdoc />
-    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    public async Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(context);
-        return Task.FromResult<string?>(
-            MarkerReply.For(state, context, MarkerKind.Chinook, "command.chinook", localizer, clock));
+        return await MarkerReply
+            .ForAsync(state, context, MarkerKind.Chinook, "command.chinook", localizer, clock, mapSettings,
+                cancellationToken)
+            .ConfigureAwait(false);
     }
 }

src/RustPlusBot.Features.Commands/Handlers/EventsCommandHandler.cs

@@ -3,31 +3,38 @@
 using RustPlusBot.Features.Events.Formatting;
 using RustPlusBot.Features.Events.State;
 using RustPlusBot.Localization;
+using RustPlusBot.Persistence.Map;
 
 namespace RustPlusBot.Features.Commands.Handlers;
 
 /// <summary>!events — lists the most recent live events.</summary>
 /// <param name="state">The live event state.</param>
 /// <param name="localizer">The reply localizer.</param>
-internal sealed class EventsCommandHandler(IEventState state, ILocalizer localizer) : ICommandHandler
+/// <param name="mapSettings">Supplies the server's grid style.</param>
+internal sealed class EventsCommandHandler(
+    IEventState state,
+    ILocalizer localizer,
+    IMapSettingsStore mapSettings) : ICommandHandler
 {
     /// <inheritdoc />
     public string Name => "events";
 
     /// <inheritdoc />
     /// <exception cref="ArgumentOutOfRangeException">A recent event has an unsupported <see cref="MapEventKind"/>.</exception>
-    public Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
+    public async Task<string?> ExecuteAsync(CommandContext context, CancellationToken cancellationToken)
     {
         ArgumentNullException.ThrowIfNull(context);
         var events = state.GetRecentEvents(context.GuildId, context.ServerId);
         if (events.Count == 0)
         {
-            return Task.FromResult<string?>(localizer.Get("command.events.none", context.Culture));
+            return localizer.Get("command.events.none", context.Culture);
         }
 
+        var settings = await mapSettings.GetAsync(context.GuildId, context.ServerId, cancellationToken)
+            .ConfigureAwait(false);
         var parts = events.Select(e =>
         {
-            var grid = GridReference.From(e.X, e.Y, e.Dimensions);
+            var grid = GridReference.From(e.X, e.Y, e.Dimensions, settings.GridStyle);
             var key = e.Kind switch
             {
                 MapEventKind.CargoEntered => "command.event.cargoentered",
@@ -40,7 +47,6 @@ internal sealed class EventsCommandHandler(IEventState state, ILocalizer localiz
             return localizer.Get(key, context.Culture, grid);
         });
 
-        return Task.FromResult<string?>(
-            localizer.Get("command.events.ok", context.Culture, string.Join(", ", parts)));
+        return localizer.Get("command.events.ok", context.Culture, string.Join(", ", parts));
     }
 }