feat(map): per-server grid style — in-game vs Rust+/RustMaps (100-unit row offset)

The in-game (F1) map and the Rust+ companion app / rustmaps.com use DIFFERENT
grid conventions: both anchor columns at the world's west edge, but
Rust+/RustMaps rows start exactly 100 game-units south of the world's north
edge (measured from RustMaps' own pre-rendered grid tiles across sizes
1500–4500), while the in-game map starts them at the edge itself. That's why
the render could never match both references at once.

Add a per-server MapGridStyle option (default: InGame) governing BOTH the
rendered #map grid and every event grid reference, so callouts read
consistently with whichever map the team uses:
- InGame — matches the F1 map; event callouts read like in-game grid refs.
- RustPlus — matches the companion app and rustmaps.com.

Plumbing:
- MapGridStyle enum + MapGrid.RowInset/LabelFor(style); MapRenderer.DrawGrid
  anchors the lattice at (worldSize − inset).
- ServerMapSettings.GridStyle + MapGridStyle EF migration; MapLayerSettings
  carries it; IMapSettingsStore.SetGridStyleAsync.
- #map control message gains a third row with the two style buttons (active
  = Primary) and a help line explaining the difference; new
  workspace:map:gridstyle:* component handled by MapComponentModule
  (ManageGuild, reconcile + repaint like the layer toggles).
- Style threads through EventRelay/EventEmbedRenderer, PlayerEventRelay/
  PlayerEventRenderer, and the !cargo/!heli/!chinook/!events handlers via
  GridReference.From(x, y, dims, style).
- Localization: map.gridstyle.{ingame,rustplus,help} EN/FR.

Full suite green (17 projects, 916 tests, 1 skipped).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: HandyS11

src/RustPlusBot.Abstractions/Connections/MapGrid.cs

@@ -15,6 +15,19 @@ 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
@@ -50,14 +63,15 @@ public static string ColumnLetters(int index)
     /// <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)
+    public static string LabelFor(float x, float y, uint worldSize, MapGridStyle style = MapGridStyle.InGame)
     {
-        // Rows bin from the NORTH edge (the grid anchor), not the south — with a partial edge cell the
-        // two disagree, and the north anchoring is what the in-game map, the app and RustMaps use.
+        // 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 - y) / 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.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));
     }
 }

src/RustPlusBot.Features.Commands/Handlers/HeliCommandHandler.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>!heli — reports the patrol 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 HeliCommandHandler(IEventState state, ILocalizer localizer, IClock clock)
+/// <param name="mapSettings">Supplies the server's grid style.</param>
+internal sealed class HeliCommandHandler(
+    IEventState state,
+    ILocalizer localizer,
+    IClock clock,
+    IMapSettingsStore mapSettings)
     : ICommandHandler
 {
     /// <inheritdoc />
     public string Name => "heli";
 
     /// <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.PatrolHelicopter, "command.heli", localizer, clock));
+        return await MarkerReply
+            .ForAsync(state, context, MarkerKind.PatrolHelicopter, "command.heli", localizer, clock, mapSettings,
+                cancellationToken)
+            .ConfigureAwait(false);
     }
 }

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

@@ -5,6 +5,7 @@
 using RustPlusBot.Features.Events.Formatting;
 using RustPlusBot.Features.Events.State;
 using RustPlusBot.Localization;
+using RustPlusBot.Persistence.Map;
 
 namespace RustPlusBot.Features.Commands.Handlers;
 
@@ -18,23 +19,29 @@ internal static class MarkerReply
     /// <param name="prefix">The localization key prefix ("command.cargo" / "command.heli" / "command.chinook").</param>
     /// <param name="localizer">The reply localizer.</param>
     /// <param name="clock">For the "how long ago" suffix.</param>
+    /// <param name="mapSettings">Supplies the server's grid style for the reference.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
     /// <returns>The localized reply.</returns>
-    public static string For(
+    public static async Task<string> ForAsync(
         IEventState state,
         CommandContext context,
         MarkerKind kind,
         string prefix,
         ILocalizer localizer,
-        IClock clock)
+        IClock clock,
+        IMapSettingsStore mapSettings,
+        CancellationToken cancellationToken)
     {
         var markers = state.GetActiveMarkers(context.GuildId, context.ServerId, kind);
         if (markers.Count == 0)
         {
             return localizer.Get($"{prefix}.none", context.Culture);
         }
 
+        var settings = await mapSettings.GetAsync(context.GuildId, context.ServerId, cancellationToken)
+            .ConfigureAwait(false);
         var m = markers[0];
-        var grid = GridReference.From(m.X, m.Y, m.Dimensions);
+        var grid = GridReference.From(m.X, m.Y, m.Dimensions, settings.GridStyle);
         var ago = DurationFormat.Compact(clock.UtcNow - m.SeenAtUtc);
         return localizer.Get($"{prefix}.ok", context.Culture, grid, ago);
     }

src/RustPlusBot.Features.Events/Formatting/GridReference.cs

@@ -10,8 +10,9 @@ public static class GridReference
     /// <param name="x">World X coordinate.</param>
     /// <param name="y">World Y coordinate.</param>
     /// <param name="dims">Map dimensions, or null when unavailable.</param>
+    /// <param name="style">Which grid convention to bin against (defaults to the in-game map).</param>
     /// <returns>A grid reference like "D7", or "(x, y)" when dimensions are unavailable.</returns>
-    public static string From(float x, float y, MapDimensions? dims)
+    public static string From(float x, float y, MapDimensions? dims, MapGridStyle style = MapGridStyle.InGame)
     {
         if (dims is null || dims.WorldSize == 0)
         {
@@ -20,6 +21,6 @@ public static string From(float x, float y, MapDimensions? dims)
                 $"({Math.Round(x)}, {Math.Round(y)})");
         }
 
-        return MapGrid.LabelFor(x, y, dims.WorldSize);
+        return MapGrid.LabelFor(x, y, dims.WorldSize, style);
     }
 }

src/RustPlusBot.Features.Events/Relaying/EventRelay.cs

@@ -1,11 +1,13 @@
 using Microsoft.Extensions.DependencyInjection;
+using RustPlusBot.Abstractions.Connections;
 using RustPlusBot.Abstractions.Events;
 using RustPlusBot.Features.Connections.Listening;
 using RustPlusBot.Features.Events.Classifying;
 using RustPlusBot.Features.Events.Posting;
 using RustPlusBot.Features.Events.Rendering;
 using RustPlusBot.Features.Events.State;
 using RustPlusBot.Features.Workspace.Locating;
+using RustPlusBot.Persistence.Map;
 using RustPlusBot.Persistence.Workspace;
 
 namespace RustPlusBot.Features.Events.Relaying;
@@ -48,18 +50,19 @@ public async Task RelayAsync(MapMarkersChangedEvent evt, CancellationToken cance
             return;
         }
 
-        var culture = await GetCultureAsync(evt.GuildId, cancellationToken).ConfigureAwait(false);
+        var (culture, gridStyle) = await GetRenderSettingsAsync(evt.GuildId, evt.ServerId, cancellationToken)
+            .ConfigureAwait(false);
         var channelId = await channels.Locator.GetChannelIdAsync(evt.GuildId, evt.ServerId, cancellationToken)
             .ConfigureAwait(false);
 
         foreach (var e in events)
         {
             await channels.TeamChatSender
-                .SendAsync(evt.GuildId, evt.ServerId, renderer.RenderLine(e, culture), cancellationToken)
+                .SendAsync(evt.GuildId, evt.ServerId, renderer.RenderLine(e, culture, gridStyle), cancellationToken)
                 .ConfigureAwait(false);
             if (channelId is { } id)
             {
-                await channels.Poster.PostAsync(id, renderer.Render(e, culture), cancellationToken)
+                await channels.Poster.PostAsync(id, renderer.Render(e, culture, gridStyle), cancellationToken)
                     .ConfigureAwait(false);
             }
         }
@@ -77,27 +80,33 @@ public async Task RelayRigAsync(RigStateChangedEvent evt, CancellationToken canc
             rigStore.Apply(evt);
         }
 
-        var culture = await GetCultureAsync(evt.GuildId, cancellationToken).ConfigureAwait(false);
+        var (culture, gridStyle) = await GetRenderSettingsAsync(evt.GuildId, evt.ServerId, cancellationToken)
+            .ConfigureAwait(false);
         await channels.TeamChatSender
-            .SendAsync(evt.GuildId, evt.ServerId, renderer.RenderRigLine(evt, culture), cancellationToken)
+            .SendAsync(evt.GuildId, evt.ServerId, renderer.RenderRigLine(evt, culture, gridStyle), cancellationToken)
             .ConfigureAwait(false);
 
         var channelId = await channels.Locator.GetChannelIdAsync(evt.GuildId, evt.ServerId, cancellationToken)
             .ConfigureAwait(false);
         if (channelId is { } id)
         {
-            await channels.Poster.PostAsync(id, renderer.RenderRig(evt, culture), cancellationToken)
+            await channels.Poster.PostAsync(id, renderer.RenderRig(evt, culture, gridStyle), cancellationToken)
                 .ConfigureAwait(false);
         }
     }
 
-    private async Task<string> GetCultureAsync(ulong guildId, CancellationToken cancellationToken)
+    private async Task<(string Culture, MapGridStyle GridStyle)> GetRenderSettingsAsync(ulong guildId,
+        Guid serverId,
+        CancellationToken cancellationToken)
     {
         var scope = scopeFactory.CreateAsyncScope();
         await using (scope.ConfigureAwait(false))
         {
             var store = scope.ServiceProvider.GetRequiredService<IWorkspaceStore>();
-            return await store.GetCultureAsync(guildId, cancellationToken).ConfigureAwait(false);
+            var culture = await store.GetCultureAsync(guildId, cancellationToken).ConfigureAwait(false);
+            var mapSettings = scope.ServiceProvider.GetRequiredService<IMapSettingsStore>();
+            var settings = await mapSettings.GetAsync(guildId, serverId, cancellationToken).ConfigureAwait(false);
+            return (culture, settings.GridStyle);
         }
     }
 }