Add some small map helpers (#1756)

* feat: Add new `.GetMapCoordinates` extension method

- Used to easily resolve player-friendly map coordinates for any GameObject.

* feat: Add MapID to ClientState

- Provides easy access to the player's current map ID

Dalamud/Game/ClientState/ClientState.cs

@@ -12,6 +12,8 @@ using Dalamud.Logging.Internal;
 using Dalamud.Plugin.Services;
 using Dalamud.Utility;
 using FFXIVClientStructs.FFXIV.Client.Game;
+using FFXIVClientStructs.FFXIV.Client.UI.Agent;
+
 using Lumina.Excel.GeneratedSheets;
 
 using Action = System.Action;
@@ -89,6 +91,16 @@ internal sealed class ClientState : IInternalDisposableService, IClientState
     /// <inheritdoc/>
     public ushort TerritoryType { get; private set; }
 
+    /// <inheritdoc/>
+    public unsafe uint MapId
+    {
+        get
+        {
+            var agentMap = AgentMap.Instance();
+            return agentMap != null ? AgentMap.Instance()->CurrentMapId : 0;
+        }
+    }
+
     /// <inheritdoc/>
     public PlayerCharacter? LocalPlayer => Service<ObjectTable>.GetNullable()?[0] as PlayerCharacter;
 
@@ -237,6 +249,9 @@ internal class ClientStatePluginScoped : IInternalDisposableService, IClientStat
 
     /// <inheritdoc/>
     public ushort TerritoryType => this.clientStateService.TerritoryType;
+    
+    /// <inheritdoc/>
+    public uint MapId => this.clientStateService.MapId;
 
     /// <inheritdoc/>
     public PlayerCharacter? LocalPlayer => this.clientStateService.LocalPlayer;

Dalamud/Plugin/Services/IClientState.cs

@@ -48,6 +48,11 @@ public interface IClientState
     /// Gets the current Territory the player resides in.
     /// </summary>
     public ushort TerritoryType { get; }
+    
+    /// <summary>
+    /// Gets the current Map the player resides in.
+    /// </summary>
+    public uint MapId { get; }
 
     /// <summary>
     /// Gets the local player character, if one is present.

Dalamud/Utility/MapUtil.cs

@@ -1,5 +1,11 @@
 using System.Numerics;
 
+using Dalamud.Data;
+using Dalamud.Game.ClientState.Objects.Types;
+
+using FFXIVClientStructs.FFXIV.Client.UI.Agent;
+
+using Lumina;
 using Lumina.Excel.GeneratedSheets;
 
 namespace Dalamud.Utility;
@@ -128,4 +134,32 @@ public static class MapUtil
     {
         return WorldToMap(worldCoordinates, map.OffsetX, map.OffsetY, map.SizeFactor);
     }
+
+    /// <summary>
+    /// Extension method to get the current position of a GameObject in Map Coordinates (visible to players in the
+    /// minimap or chat). A Z (height) value will always be returned, even on maps that do not natively show one.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown if ClientState is unavailable.</exception>
+    /// <param name="go">The GameObject to get the position for.</param>
+    /// <param name="correctZOffset">Whether to "correct" a Z offset to sane values for maps that don't have one.</param>
+    /// <returns>A Vector3 that represents the X (east/west), Y (north/south), and Z (height) position of this object.</returns>
+    public static unsafe Vector3 GetMapCoordinates(this GameObject go, bool correctZOffset = false)
+    {
+        var agentMap = AgentMap.Instance();
+
+        if (agentMap == null || agentMap->CurrentMapId == 0)
+            throw new InvalidOperationException("Could not determine active map - data may not be loaded yet?");
+
+        var territoryTransient = Service<DataManager>.Get()
+                                                     .GetExcelSheet<TerritoryTypeTransient>()!
+                                                     .GetRow(agentMap->CurrentTerritoryId);
+
+        return WorldToMap(
+            go.Position,
+            agentMap->CurrentOffsetX,
+            agentMap->CurrentOffsetY,
+            territoryTransient?.OffsetZ ?? 0,
+            (uint)agentMap->CurrentMapSizeFactor,
+            correctZOffset);
+    }
 }