Minimap support

MinecraftClient/Commands/Minimap.cs

@@ -0,0 +1,256 @@
+using System;
+using Brigadier.NET;
+using Brigadier.NET.Builder;
+using MinecraftClient.CommandHandler;
+using MinecraftClient.Tui;
+using Avalonia.Threading;
+using static MinecraftClient.CommandHandler.CmdResult;
+
+namespace MinecraftClient.Commands
+{
+    class Minimap : Command
+    {
+        public override string CmdName => "minimap";
+        public override string CmdUsage => "minimap [on|off] | minimap zoom [in|out|<1-16>] | minimap names [players|hostile|neutral|passive] [on|off] | minimap names [all_on|all_off] | minimap position [top_left|top_right|center|bottom_left|bottom_right]";
+        public override string CmdDesc => Translations.cmd_minimap_desc;
+
+        public override void RegisterCommand(CommandDispatcher<CmdResult> dispatcher)
+        {
+            dispatcher.Register(l => l.Literal("help")
+                .Then(l => l.Literal(CmdName)
+                    .Executes(r => GetUsage(r.Source, string.Empty))
+                )
+            );
+
+            dispatcher.Register(l => l.Literal(CmdName)
+                .Executes(r => DoToggle(r.Source))
+                .Then(l => l.Literal("on")
+                    .Executes(r => DoOn(r.Source)))
+                .Then(l => l.Literal("off")
+                    .Executes(r => DoOff(r.Source)))
+                .Then(l => l.Literal("zoom")
+                    .Executes(r => DoZoomInfo(r.Source))
+                    .Then(l => l.Literal("in")
+                        .Executes(r => DoZoomIn(r.Source)))
+                    .Then(l => l.Literal("out")
+                        .Executes(r => DoZoomOut(r.Source)))
+                    .Then(l => l.Argument("level", Arguments.Integer(MinimapControl.MinZoom, MinimapControl.MaxZoom))
+                        .Executes(r => DoZoomSet(r.Source, Arguments.GetInteger(r, "level")))))
+                .Then(l => l.Literal("names")
+                    .Executes(r => DoNamesInfo(r.Source))
+                    .Then(l => l.Literal("all_on")
+                        .Executes(r => DoNamesAll(r.Source, true)))
+                    .Then(l => l.Literal("all_off")
+                        .Executes(r => DoNamesAll(r.Source, false)))
+                    .Then(l => l.Literal("players")
+                        .Executes(r => DoNamesCatInfo(r.Source, MobCategory.Player))
+                        .Then(l => l.Literal("on")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Player, true)))
+                        .Then(l => l.Literal("off")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Player, false))))
+                    .Then(l => l.Literal("hostile")
+                        .Executes(r => DoNamesCatInfo(r.Source, MobCategory.Hostile))
+                        .Then(l => l.Literal("on")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Hostile, true)))
+                        .Then(l => l.Literal("off")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Hostile, false))))
+                    .Then(l => l.Literal("neutral")
+                        .Executes(r => DoNamesCatInfo(r.Source, MobCategory.Neutral))
+                        .Then(l => l.Literal("on")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Neutral, true)))
+                        .Then(l => l.Literal("off")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Neutral, false))))
+                    .Then(l => l.Literal("passive")
+                        .Executes(r => DoNamesCatInfo(r.Source, MobCategory.Passive))
+                        .Then(l => l.Literal("on")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Passive, true)))
+                        .Then(l => l.Literal("off")
+                            .Executes(r => DoNamesCatSet(r.Source, MobCategory.Passive, false)))))
+                .Then(l => l.Literal("position")
+                    .Executes(r => DoPositionInfo(r.Source))
+                    .Then(l => l.Literal("top_left")
+                        .Executes(r => DoPositionSet(r.Source, MinimapPosition.top_left)))
+                    .Then(l => l.Literal("top_right")
+                        .Executes(r => DoPositionSet(r.Source, MinimapPosition.top_right)))
+                    .Then(l => l.Literal("center")
+                        .Executes(r => DoPositionSet(r.Source, MinimapPosition.center)))
+                    .Then(l => l.Literal("bottom_left")
+                        .Executes(r => DoPositionSet(r.Source, MinimapPosition.bottom_left)))
+                    .Then(l => l.Literal("bottom_right")
+                        .Executes(r => DoPositionSet(r.Source, MinimapPosition.bottom_right))))
+                .Then(l => l.Literal("_help")
+                    .Executes(r => GetUsage(r.Source, string.Empty))
+                    .Redirect(dispatcher.GetRoot().GetChild("help")?.GetChild(CmdName)))
+            );
+        }
+
+        private int GetUsage(CmdResult r, string _) =>
+            r.SetAndReturn(GetCmdDescTranslated());
+
+        private static MainTuiView? GetTuiView(CmdResult r)
+        {
+            if (ConsoleIO.Backend is not TuiConsoleBackend)
+            {
+                r.SetAndReturn(Status.Fail, Translations.cmd_minimap_tui_only);
+                return null;
+            }
+            return TuiConsoleBackend.Instance?.GetView();
+        }
+
+        private static int DoToggle(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            bool wasVisible = view.IsMinimapVisible;
+            Dispatcher.UIThread.Post(() => view.ToggleMinimap());
+            string msg = wasVisible
+                ? Translations.cmd_minimap_disabled
+                : Translations.cmd_minimap_enabled;
+            return r.SetAndReturn(Status.Done, msg);
+        }
+
+        private static int DoOn(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() => view.ShowMinimap());
+            return r.SetAndReturn(Status.Done, Translations.cmd_minimap_enabled);
+        }
+
+        private static int DoOff(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() => view.HideMinimap());
+            return r.SetAndReturn(Status.Done, Translations.cmd_minimap_disabled);
+        }
+
+        private static int DoZoomInfo(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            int current = view.GetMinimapZoom();
+            return r.SetAndReturn(Status.Done,
+                string.Format(Translations.cmd_minimap_zoom_current, current, MinimapControl.MaxZoom));
+        }
+
+        private static int DoZoomIn(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            int newLevel = Math.Max(view.GetMinimapZoom() - 1, MinimapControl.MinZoom);
+            Dispatcher.UIThread.Post(() => view.SetMinimapZoom(newLevel));
+            return r.SetAndReturn(Status.Done, string.Format(Translations.cmd_minimap_zoom_set, newLevel));
+        }
+
+        private static int DoZoomOut(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            int newLevel = Math.Min(view.GetMinimapZoom() + 1, MinimapControl.MaxZoom);
+            Dispatcher.UIThread.Post(() => view.SetMinimapZoom(newLevel));
+            return r.SetAndReturn(Status.Done, string.Format(Translations.cmd_minimap_zoom_set, newLevel));
+        }
+
+        private static int DoZoomSet(CmdResult r, int level)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() => view.SetMinimapZoom(level));
+            return r.SetAndReturn(Status.Done, string.Format(Translations.cmd_minimap_zoom_set, level));
+        }
+
+        private static int DoNamesInfo(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            var nc = view.GetMinimapNameConfig();
+            string status = string.Format(Translations.cmd_minimap_names_status,
+                BoolStr(nc.Players), BoolStr(nc.Hostile), BoolStr(nc.Neutral), BoolStr(nc.Passive));
+            return r.SetAndReturn(Status.Done, status);
+        }
+
+        private static int DoNamesAll(CmdResult r, bool on)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() =>
+            {
+                view.GetMinimapNameConfig().SetAll(on);
+                view.SyncMinimapNameConfig();
+            });
+            string msg = on ? Translations.cmd_minimap_names_all_on : Translations.cmd_minimap_names_all_off;
+            return r.SetAndReturn(Status.Done, msg);
+        }
+
+        private static int DoNamesCatInfo(CmdResult r, MobCategory cat)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            var nc = view.GetMinimapNameConfig();
+            bool val = cat switch
+            {
+                MobCategory.Player => nc.Players,
+                MobCategory.Hostile => nc.Hostile,
+                MobCategory.Neutral => nc.Neutral,
+                MobCategory.Passive => nc.Passive,
+                _ => false,
+            };
+            return r.SetAndReturn(Status.Done,
+                string.Format(Translations.cmd_minimap_names_cat, cat, BoolStr(val)));
+        }
+
+        private static int DoNamesCatSet(CmdResult r, MobCategory cat, bool on)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() =>
+            {
+                var nc = view.GetMinimapNameConfig();
+                switch (cat)
+                {
+                    case MobCategory.Player: nc.Players = on; break;
+                    case MobCategory.Hostile: nc.Hostile = on; break;
+                    case MobCategory.Neutral: nc.Neutral = on; break;
+                    case MobCategory.Passive: nc.Passive = on; break;
+                }
+                view.SyncMinimapNameConfig();
+            });
+            return r.SetAndReturn(Status.Done,
+                string.Format(Translations.cmd_minimap_names_cat_set, cat, BoolStr(on)));
+        }
+
+        private static int DoPositionInfo(CmdResult r)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            var pos = view.GetMinimapPosition();
+            return r.SetAndReturn(Status.Done,
+                string.Format(Translations.cmd_minimap_position_current, pos));
+        }
+
+        private static int DoPositionSet(CmdResult r, MinimapPosition pos)
+        {
+            var view = GetTuiView(r);
+            if (view is null) return (int)r.status;
+
+            Dispatcher.UIThread.Post(() => view.SetMinimapPosition(pos));
+            return r.SetAndReturn(Status.Done,
+                string.Format(Translations.cmd_minimap_position_set, pos));
+        }
+
+        private static string BoolStr(bool v) => v ? "ON" : "OFF";
+    }
+}

MinecraftClient/MinecraftClient.csproj

@@ -20,6 +20,8 @@
   </PropertyGroup>
   <ItemGroup>
     <EmbeddedResource Include="Physics\BlockShapeData.json" LogicalName="BlockShapeData.json" />
+    <EmbeddedResource Include="Tui\MinimapBlockColors.json" LogicalName="MinimapBlockColors.json" />
+    <EmbeddedResource Include="Tui\MinimapEntityCategories.json" LogicalName="MinimapEntityCategories.json" />
   </ItemGroup>
   <ItemGroup>
     <Compile Remove="Protocol\Handlers\Compression\**" />

MinecraftClient/Protocol/Handlers/DataTypes.cs

@@ -664,8 +664,10 @@ namespace MinecraftClient.Protocol.Handlers
                 }
             }
 
-            return new Entity(entityID, entityType, new Location(entityX, entityY, entityZ), entityYaw, entityPitch,
+            var entity = new Entity(entityID, entityType, new Location(entityX, entityY, entityZ), entityYaw, entityPitch,
                 data);
+            entity.UUID = entityUUID;
+            return entity;
         }
 
         /// <summary>

MinecraftClient/Resources/ConfigComments/ConfigComments.resx

@@ -933,6 +933,39 @@ Note: This does NOT require a Bot Token, only an Application ID. Discord must be
   <data name="Main.Advanced.enable_sentry" xml:space="preserve">
     <value>Set to false to opt-out of Sentry error logging.</value>
   </data>
+  <data name="Console.Minimap" xml:space="preserve">
+    <value>Settings for the TUI minimap overlay that shows terrain and entities.</value>
+  </data>
+  <data name="Console.Minimap.Enabled" xml:space="preserve">
+    <value>Whether the minimap is visible on startup in TUI mode.</value>
+  </data>
+  <data name="Console.Minimap.Zoom" xml:space="preserve">
+    <value>Blocks per pixel, 1-16. 1 = closest (1:1), 16 = farthest (16 blocks per pixel).</value>
+  </data>
+  <data name="Console.Minimap.Width" xml:space="preserve">
+    <value>Map width in pixels (characters). Range 10-120, default 40.</value>
+  </data>
+  <data name="Console.Minimap.Height" xml:space="preserve">
+    <value>Map height in pixels (must be even, uses half-block chars). Range 4-80, default 40.</value>
+  </data>
+  <data name="Console.Minimap.Position" xml:space="preserve">
+    <value>Minimap position: "top_left", "top_right", "center", "bottom_left", or "bottom_right".</value>
+  </data>
+  <data name="Console.Minimap.ShowPlayerNames" xml:space="preserve">
+    <value>Show player names on the minimap.</value>
+  </data>
+  <data name="Console.Minimap.ShowHostileNames" xml:space="preserve">
+    <value>Show hostile mob names on the minimap.</value>
+  </data>
+  <data name="Console.Minimap.ShowNeutralNames" xml:space="preserve">
+    <value>Show neutral mob names on the minimap.</value>
+  </data>
+  <data name="Console.Minimap.ShowPassiveNames" xml:space="preserve">
+    <value>Show passive mob names on the minimap.</value>
+  </data>
+  <data name="Console.Minimap.RefreshInterval" xml:space="preserve">
+    <value>Minimap refresh interval in milliseconds (200-5000, default 1000).</value>
+  </data>
   <data name="Main.General.AuthlibUser" xml:space="preserve">
     <value>Yggdrasil authlib multi-user selection.</value>
   </data>

MinecraftClient/Resources/Translations/Translations.Designer.cs

@@ -6880,5 +6880,158 @@ namespace MinecraftClient {
                 return ResourceManager.GetString("tui.crafting.grid", resourceCulture);
             }
         }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Toggle the TUI minimap overlay, or adjust its zoom level..
+        /// </summary>
+        internal static string cmd_minimap_desc {
+            get {
+                return ResourceManager.GetString("cmd.minimap.desc", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Minimap enabled..
+        /// </summary>
+        internal static string cmd_minimap_enabled {
+            get {
+                return ResourceManager.GetString("cmd.minimap.enabled", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Minimap disabled..
+        /// </summary>
+        internal static string cmd_minimap_disabled {
+            get {
+                return ResourceManager.GetString("cmd.minimap.disabled", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Minimap zoom set to {0}:1 (blocks per pixel)..
+        /// </summary>
+        internal static string cmd_minimap_zoom_set {
+            get {
+                return ResourceManager.GetString("cmd.minimap.zoom_set", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Current minimap zoom: {0}:1 blocks/px (range 1-{1})..
+        /// </summary>
+        internal static string cmd_minimap_zoom_current {
+            get {
+                return ResourceManager.GetString("cmd.minimap.zoom_current", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to The minimap command is only available in TUI mode..
+        /// </summary>
+        internal static string cmd_minimap_tui_only {
+            get {
+                return ResourceManager.GetString("cmd.minimap.tui_only", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Hostile.
+        /// </summary>
+        internal static string tui_minimap_legend_hostile {
+            get {
+                return ResourceManager.GetString("tui.minimap.legend.hostile", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Passive.
+        /// </summary>
+        internal static string tui_minimap_legend_passive {
+            get {
+                return ResourceManager.GetString("tui.minimap.legend.passive", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Neutral.
+        /// </summary>
+        internal static string tui_minimap_legend_neutral {
+            get {
+                return ResourceManager.GetString("tui.minimap.legend.neutral", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Player.
+        /// </summary>
+        internal static string tui_minimap_legend_player {
+            get {
+                return ResourceManager.GetString("tui.minimap.legend.player", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Name display -- Players: {0}, Hostile: {1}, Neutral: {2}, Passive: {3}.
+        /// </summary>
+        internal static string cmd_minimap_names_status {
+            get {
+                return ResourceManager.GetString("cmd.minimap.names_status", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to All entity name labels enabled..
+        /// </summary>
+        internal static string cmd_minimap_names_all_on {
+            get {
+                return ResourceManager.GetString("cmd.minimap.names_all_on", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to All entity name labels disabled..
+        /// </summary>
+        internal static string cmd_minimap_names_all_off {
+            get {
+                return ResourceManager.GetString("cmd.minimap.names_all_off", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to {0} name display: {1}.
+        /// </summary>
+        internal static string cmd_minimap_names_cat {
+            get {
+                return ResourceManager.GetString("cmd.minimap.names_cat", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to {0} name display set to {1}..
+        /// </summary>
+        internal static string cmd_minimap_names_cat_set {
+            get {
+                return ResourceManager.GetString("cmd.minimap.names_cat_set", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Current minimap position: {0}.
+        /// </summary>
+        internal static string cmd_minimap_position_current {
+            get {
+                return ResourceManager.GetString("cmd.minimap.position_current", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Minimap position set to: {0}.
+        /// </summary>
+        internal static string cmd_minimap_position_set {
+            get {
+                return ResourceManager.GetString("cmd.minimap.position_set", resourceCulture);
+            }
+        }
     }
 }

MinecraftClient/Resources/Translations/Translations.resx

@@ -2419,4 +2419,55 @@ see item details.</value>
   <data name="tui.crafting.grid" xml:space="preserve">
     <value>Crafting</value>
   </data>
+  <data name="cmd.minimap.desc" xml:space="preserve">
+    <value>Toggle the TUI minimap overlay, or adjust its zoom level.</value>
+  </data>
+  <data name="cmd.minimap.enabled" xml:space="preserve">
+    <value>Minimap enabled.</value>
+  </data>
+  <data name="cmd.minimap.disabled" xml:space="preserve">
+    <value>Minimap disabled.</value>
+  </data>
+  <data name="cmd.minimap.zoom_set" xml:space="preserve">
+    <value>Minimap zoom set to {0}:1 (blocks per pixel).</value>
+  </data>
+  <data name="cmd.minimap.zoom_current" xml:space="preserve">
+    <value>Current minimap zoom: {0}:1 blocks/px (range 1-{1}).</value>
+  </data>
+  <data name="cmd.minimap.tui_only" xml:space="preserve">
+    <value>The minimap command is only available in TUI mode.</value>
+  </data>
+  <data name="tui.minimap.legend.hostile" xml:space="preserve">
+    <value>Hostile</value>
+  </data>
+  <data name="tui.minimap.legend.passive" xml:space="preserve">
+    <value>Passive</value>
+  </data>
+  <data name="tui.minimap.legend.neutral" xml:space="preserve">
+    <value>Neutral</value>
+  </data>
+  <data name="tui.minimap.legend.player" xml:space="preserve">
+    <value>Player</value>
+  </data>
+  <data name="cmd.minimap.names_status" xml:space="preserve">
+    <value>Name display -- Players: {0}, Hostile: {1}, Neutral: {2}, Passive: {3}</value>
+  </data>
+  <data name="cmd.minimap.names_all_on" xml:space="preserve">
+    <value>All entity name labels enabled.</value>
+  </data>
+  <data name="cmd.minimap.names_all_off" xml:space="preserve">
+    <value>All entity name labels disabled.</value>
+  </data>
+  <data name="cmd.minimap.names_cat" xml:space="preserve">
+    <value>{0} name display: {1}</value>
+  </data>
+  <data name="cmd.minimap.names_cat_set" xml:space="preserve">
+    <value>{0} name display set to {1}.</value>
+  </data>
+  <data name="cmd.minimap.position_current" xml:space="preserve">
+    <value>Current minimap position: {0}</value>
+  </data>
+  <data name="cmd.minimap.position_set" xml:space="preserve">
+    <value>Minimap position set to: {0}</value>
+  </data>
 </root>

MinecraftClient/Settings.cs

@@ -1108,6 +1108,9 @@ namespace MinecraftClient
                 [TomlPrecedingComment("$Console.CommandSuggestion$")]
                 public CommandSuggestionConfig CommandSuggestion = new();
 
+                [TomlPrecedingComment("$Console.Minimap$")]
+                public MinimapConfig Minimap = new();
+
                 public void OnSettingUpdate()
                 {
                     var backend = ConsoleIO.Backend;
@@ -1246,6 +1249,50 @@ namespace MinecraftClient
 
                 public enum ConsoleModeType { classic, tui };
                 public enum ConsoleColorModeType { disable, legacy_4bit, vt100_4bit, vt100_8bit, vt100_24bit };
+
+                [TomlDoNotInlineObject]
+                public class MinimapConfig
+                {
+                    [TomlInlineComment("$Console.Minimap.Enabled$")]
+                    public bool Enabled = false;
+
+                    [TomlInlineComment("$Console.Minimap.Zoom$")]
+                    public int Zoom = Tui.MinimapControl.DefaultZoom;
+
+                    [TomlInlineComment("$Console.Minimap.Width$")]
+                    public int Width = Tui.MinimapControl.DefaultWidth;
+
+                    [TomlInlineComment("$Console.Minimap.Height$")]
+                    public int Height = Tui.MinimapControl.DefaultHeight;
+
+                    [TomlInlineComment("$Console.Minimap.Position$")]
+                    public Tui.MinimapPosition Position = Tui.MinimapPosition.top_right;
+
+                    [TomlInlineComment("$Console.Minimap.ShowPlayerNames$")]
+                    public bool ShowPlayerNames = false;
+
+                    [TomlInlineComment("$Console.Minimap.ShowHostileNames$")]
+                    public bool ShowHostileNames = false;
+
+                    [TomlInlineComment("$Console.Minimap.ShowNeutralNames$")]
+                    public bool ShowNeutralNames = false;
+
+                    [TomlInlineComment("$Console.Minimap.ShowPassiveNames$")]
+                    public bool ShowPassiveNames = false;
+
+                    [TomlInlineComment("$Console.Minimap.RefreshInterval$")]
+                    public int RefreshInterval = Tui.MinimapControl.DefaultRefreshMs;
+
+                    public void OnSettingUpdate()
+                    {
+                        Zoom = Math.Clamp(Zoom, Tui.MinimapControl.MinZoom, Tui.MinimapControl.MaxZoom);
+                        Width = Math.Clamp(Width, 10, 120);
+                        Height = Math.Clamp(Height, 4, 80);
+                        if (Height % 2 != 0) Height++;
+                        RefreshInterval = Math.Clamp(RefreshInterval,
+                            Tui.MinimapControl.MinRefreshMs, Tui.MinimapControl.MaxRefreshMs);
+                    }
+                }
             }
         }
 

MinecraftClient/Tui/MainTuiView.cs

@@ -41,6 +41,10 @@ namespace MinecraftClient.Tui
         private long _lastLogClickTicks;
         private const int DoubleClickMsec = 500;
 
+        private readonly Border _minimapBorder;
+        private readonly MinimapControl _minimapControl;
+        private volatile bool _minimapVisible;
+
         private readonly Border _suggestionBorder;
         private readonly StackPanel _suggestionPanel;
         private CommandSuggestion[] _suggestions = Array.Empty<CommandSuggestion>();
@@ -150,6 +154,29 @@ namespace MinecraftClient.Tui
                 Margin = new Thickness(0, 0, 0, 1),
             };
 
+            var mmCfg = Settings.Config.Console.Minimap;
+            mmCfg.OnSettingUpdate();
+            _minimapControl = new MinimapControl(mmCfg.Width, mmCfg.Height);
+            _minimapControl.BlocksPerPixel = mmCfg.Zoom;
+            _minimapControl.RefreshIntervalMs = mmCfg.RefreshInterval;
+            _minimapControl.NameConfig.Players = mmCfg.ShowPlayerNames;
+            _minimapControl.NameConfig.Hostile = mmCfg.ShowHostileNames;
+            _minimapControl.NameConfig.Neutral = mmCfg.ShowNeutralNames;
+            _minimapControl.NameConfig.Passive = mmCfg.ShowPassiveNames;
+
+            var (hAlign, vAlign, margin) = GetMinimapAlignment(mmCfg.Position);
+            _minimapBorder = new Border
+            {
+                Background = new SolidColorBrush(Color.FromArgb(220, 15, 15, 15)),
+                BorderBrush = new SolidColorBrush(Color.FromRgb(80, 80, 80)),
+                BorderThickness = new Thickness(1),
+                Child = _minimapControl,
+                IsVisible = false,
+                HorizontalAlignment = hAlign,
+                VerticalAlignment = vAlign,
+                Margin = margin,
+            };
+
             _mainContent = new DockPanel
             {
                 Background = Brushes.Black,
@@ -164,11 +191,18 @@ namespace MinecraftClient.Tui
             _rootPanel = new Panel
             {
                 Background = Brushes.Black,
-                Children = { _mainContent, _notificationBorder, _suggestionBorder }
+                Children = { _mainContent, _minimapBorder, _notificationBorder, _suggestionBorder }
             };
 
             Content = _rootPanel;
 
+            if (mmCfg.Enabled)
+            {
+                _minimapVisible = true;
+                _minimapBorder.IsVisible = true;
+                _minimapControl.Start();
+            }
+
             StartStatusBarTimer();
         }
 
@@ -986,6 +1020,95 @@ namespace MinecraftClient.Tui
 
         #endregion
 
+        #region Minimap
+
+        public void ShowMinimap()
+        {
+            if (_minimapVisible) return;
+            _minimapVisible = true;
+            _minimapBorder.IsVisible = true;
+            _minimapControl.Start();
+            Settings.Config.Console.Minimap.Enabled = true;
+        }
+
+        public void HideMinimap()
+        {
+            if (!_minimapVisible) return;
+            _minimapVisible = false;
+            _minimapControl.Stop();
+            _minimapBorder.IsVisible = false;
+            Settings.Config.Console.Minimap.Enabled = false;
+        }
+
+        public void ToggleMinimap()
+        {
+            if (_minimapVisible)
+                HideMinimap();
+            else
+                ShowMinimap();
+        }
+
+        public bool IsMinimapVisible => _minimapVisible;
+
+        public void SetMinimapZoom(int level)
+        {
+            _minimapControl.BlocksPerPixel = level;
+            Settings.Config.Console.Minimap.Zoom = level;
+        }
+
+        public int GetMinimapZoom() => _minimapControl.BlocksPerPixel;
+
+        public NameDisplayConfig GetMinimapNameConfig() => _minimapControl.NameConfig;
+
+        public void SyncMinimapNameConfig()
+        {
+            var nc = _minimapControl.NameConfig;
+            var cfg = Settings.Config.Console.Minimap;
+            cfg.ShowPlayerNames = nc.Players;
+            cfg.ShowHostileNames = nc.Hostile;
+            cfg.ShowNeutralNames = nc.Neutral;
+            cfg.ShowPassiveNames = nc.Passive;
+        }
+
+        public void ResizeMinimap(int width, int height)
+        {
+            _minimapControl.Resize(width, height);
+            Settings.Config.Console.Minimap.Width = width;
+            Settings.Config.Console.Minimap.Height = height;
+        }
+
+        public void SetMinimapPosition(MinimapPosition pos)
+        {
+            var (hAlign, vAlign, margin) = GetMinimapAlignment(pos);
+            _minimapBorder.HorizontalAlignment = hAlign;
+            _minimapBorder.VerticalAlignment = vAlign;
+            _minimapBorder.Margin = margin;
+            Settings.Config.Console.Minimap.Position = pos;
+        }
+
+        public MinimapPosition GetMinimapPosition() => Settings.Config.Console.Minimap.Position;
+
+        private static (HorizontalAlignment h, VerticalAlignment v, Thickness margin) GetMinimapAlignment(MinimapPosition pos) => pos switch
+        {
+            MinimapPosition.top_left => (HorizontalAlignment.Left, VerticalAlignment.Top, new Thickness(1, 1, 0, 0)),
+            MinimapPosition.top_right => (HorizontalAlignment.Right, VerticalAlignment.Top, new Thickness(0, 1, 1, 0)),
+            MinimapPosition.center => (HorizontalAlignment.Center, VerticalAlignment.Center, new Thickness(0)),
+            MinimapPosition.bottom_left => (HorizontalAlignment.Left, VerticalAlignment.Bottom, new Thickness(1, 0, 0, 2)),
+            MinimapPosition.bottom_right => (HorizontalAlignment.Right, VerticalAlignment.Bottom, new Thickness(0, 0, 1, 2)),
+            _ => (HorizontalAlignment.Right, VerticalAlignment.Top, new Thickness(0, 1, 1, 0)),
+        };
+
+        public void ApplyMinimapConfig()
+        {
+            var cfg = Settings.Config.Console.Minimap;
+            if (cfg.Enabled && !_minimapVisible)
+                ShowMinimap();
+            else if (!cfg.Enabled && _minimapVisible)
+                HideMinimap();
+        }
+
+        #endregion
+
         #region Overlay
 
         public void ShowOverlay(Control content, Action? onClose = null)

MinecraftClient/Tui/MinimapColorMap.cs

@@ -0,0 +1,168 @@
+using System;
+using System.Collections.Frozen;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Text.Json;
+using Avalonia.Media;
+using MinecraftClient.Mapping;
+
+namespace MinecraftClient.Tui
+{
+    /// <summary>
+    /// Maps block Materials to minimap colors using data extracted from Minecraft's
+    /// official MapColor table. Colors are loaded from the embedded MinimapBlockColors.json
+    /// resource generated by tools/gen_block_color_map.py.
+    /// </summary>
+    public static class MinimapColorMap
+    {
+        public static readonly Color WaterColor = Color.FromRgb(64, 64, 255);
+        public static readonly Color IceColor = Color.FromRgb(160, 160, 255);
+        public static readonly Color LavaColor = Color.FromRgb(255, 100, 0);
+        public static readonly Color DefaultColor = Color.FromRgb(60, 60, 60);
+        public static readonly Color VoidColor = Color.FromRgb(0, 0, 0);
+
+        private static readonly FrozenDictionary<Material, Color> ColorTable;
+        private static readonly FrozenSet<Material> FullyTransparentMats;
+        private static readonly FrozenSet<Material> WaterMats;
+        private static readonly FrozenSet<Material> IceMats;
+
+        static MinimapColorMap()
+        {
+            var colors = new Dictionary<Material, Color>();
+            var transparent = new HashSet<Material>();
+            var water = new HashSet<Material>();
+            var ice = new HashSet<Material>();
+
+            try
+            {
+                using var stream = Assembly.GetExecutingAssembly()
+                    .GetManifestResourceStream("MinimapBlockColors.json");
+                if (stream is not null)
+                {
+                    using var doc = JsonDocument.Parse(stream);
+                    var root = doc.RootElement;
+
+                    if (root.TryGetProperty("colors", out var colorsEl))
+                    {
+                        foreach (var prop in colorsEl.EnumerateObject())
+                        {
+                            if (!Enum.TryParse<Material>(prop.Name, out var mat))
+                                continue;
+                            var arr = prop.Value;
+                            if (arr.GetArrayLength() < 3) continue;
+                            byte r = (byte)arr[0].GetInt32();
+                            byte g = (byte)arr[1].GetInt32();
+                            byte b = (byte)arr[2].GetInt32();
+                            colors[mat] = Color.FromRgb(r, g, b);
+                        }
+                    }
+
+                    if (root.TryGetProperty("transparent", out var transEl))
+                    {
+                        foreach (var item in transEl.EnumerateArray())
+                        {
+                            if (Enum.TryParse<Material>(item.GetString(), out var mat))
+                                transparent.Add(mat);
+                        }
+                    }
+
+                    if (root.TryGetProperty("water", out var waterEl))
+                    {
+                        foreach (var item in waterEl.EnumerateArray())
+                        {
+                            if (Enum.TryParse<Material>(item.GetString(), out var mat))
+                                water.Add(mat);
+                        }
+                    }
+
+                    if (root.TryGetProperty("ice", out var iceEl))
+                    {
+                        foreach (var item in iceEl.EnumerateArray())
+                        {
+                            if (Enum.TryParse<Material>(item.GetString(), out var mat))
+                                ice.Add(mat);
+                        }
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                ConsoleIO.WriteLineFormatted($"\u00a7e[Minimap] Failed to load color data: {ex.Message}");
+            }
+
+            if (transparent.Count == 0)
+            {
+                transparent.Add(Material.Air);
+                transparent.Add(Material.CaveAir);
+                transparent.Add(Material.VoidAir);
+            }
+            if (water.Count == 0)
+                water.Add(Material.Water);
+            if (ice.Count == 0)
+            {
+                ice.Add(Material.Ice);
+                ice.Add(Material.PackedIce);
+                ice.Add(Material.BlueIce);
+                ice.Add(Material.FrostedIce);
+            }
+
+            ColorTable = colors.ToFrozenDictionary();
+            FullyTransparentMats = transparent.ToFrozenSet();
+            WaterMats = water.ToFrozenSet();
+            IceMats = ice.ToFrozenSet();
+        }
+
+        public static bool IsFullyTransparent(Material m) => FullyTransparentMats.Contains(m);
+
+        public static bool IsWater(Material m) => WaterMats.Contains(m);
+
+        public static bool IsIce(Material m) => IceMats.Contains(m);
+
+        public static Color GetBaseColor(Material m)
+        {
+            if (m == Material.Lava)
+                return LavaColor;
+            return ColorTable.GetValueOrDefault(m, DefaultColor);
+        }
+
+        /// <summary>
+        /// Apply Minecraft-style height shading. The shade multiplier depends on
+        /// the height difference between the current block and the block to its north.
+        /// Vanilla maps use four brightness levels: LOW (180/255), NORMAL (220/255),
+        /// HIGH (255/255), and LOWEST (135/255). We use NORMAL as baseline and shift
+        /// up/down based on delta.
+        /// </summary>
+        public static Color ApplyHeightShade(Color baseColor, int heightDelta)
+        {
+            int multiplier = heightDelta switch
+            {
+                > 0 => 255,   // higher than neighbor: brightest
+                0   => 220,   // same height: normal
+                _   => 180,   // lower than neighbor: darker
+            };
+            byte r = (byte)(baseColor.R * multiplier / 255);
+            byte g = (byte)(baseColor.G * multiplier / 255);
+            byte b = (byte)(baseColor.B * multiplier / 255);
+            return Color.FromRgb(r, g, b);
+        }
+
+        public static Color BlendWaterColor(Color bottomColor, int waterDepth)
+        {
+            double alpha = Math.Min(0.85, 0.35 + waterDepth * 0.08);
+            return Blend(WaterColor, bottomColor, alpha);
+        }
+
+        public static Color BlendIceColor(Color bottomColor)
+        {
+            return Blend(IceColor, bottomColor, 0.35);
+        }
+
+        private static Color Blend(Color top, Color bottom, double topAlpha)
+        {
+            byte r = (byte)(top.R * topAlpha + bottom.R * (1.0 - topAlpha));
+            byte g = (byte)(top.G * topAlpha + bottom.G * (1.0 - topAlpha));
+            byte b = (byte)(top.B * topAlpha + bottom.B * (1.0 - topAlpha));
+            return Color.FromRgb(r, g, b);
+        }
+    }
+}

MinecraftClient/Tui/MinimapControl.cs

@@ -0,0 +1,677 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Layout;
+using Avalonia.Media;
+using Avalonia.Threading;
+using MinecraftClient.Mapping;
+
+namespace MinecraftClient.Tui
+{
+    /// <summary>
+    /// TUI minimap control rendered as a grid of TextBlocks using half-block characters.
+    /// Zoom is expressed as blocks-per-pixel (1 = 1:1, 16 = 16 blocks per pixel).
+    /// Entity names are drawn directly on the map below their icon.
+    /// </summary>
+    public class MinimapControl : UserControl
+    {
+        public const int MinZoom = 1;
+        public const int MaxZoom = 16;
+        public const int DefaultZoom = 2;
+        public const int DefaultWidth = 40;
+        public const int DefaultHeight = 40;
+        public const int DefaultRefreshMs = 1000;
+        public const int MinRefreshMs = 100;
+        public const int MaxRefreshMs = 5000;
+
+        private int _mapWidth;
+        private int _mapHeight;
+        private int _cellRows;
+
+        private int _blocksPerPixel = DefaultZoom;
+        private volatile bool _sampling;
+        private CancellationTokenSource? _cts;
+
+        private readonly NameDisplayConfig _nameConfig = new();
+
+        private TextBlock[,] _cells;
+        private readonly StackPanel _infoRow;
+        private readonly StackPanel _legendPanel;
+        private readonly Grid _mapGrid;
+        private readonly DispatcherTimer _timer;
+
+        public int BlocksPerPixel
+        {
+            get => _blocksPerPixel;
+            set => _blocksPerPixel = Math.Clamp(value, MinZoom, MaxZoom);
+        }
+
+        public NameDisplayConfig NameConfig => _nameConfig;
+
+        public int MapPixelWidth => _mapWidth;
+        public int MapPixelHeight => _mapHeight;
+
+        public int RefreshIntervalMs
+        {
+            get => (int)_timer.Interval.TotalMilliseconds;
+            set => _timer.Interval = TimeSpan.FromMilliseconds(Math.Clamp(value, MinRefreshMs, MaxRefreshMs));
+        }
+
+        public MinimapControl() : this(DefaultWidth, DefaultHeight) { }
+
+        public MinimapControl(int width, int height)
+        {
+            _mapWidth = Math.Max(10, width);
+            _mapHeight = Math.Max(4, height % 2 == 0 ? height : height + 1);
+            _cellRows = _mapHeight / 2;
+
+            _mapGrid = new Grid();
+            _cells = BuildGrid(_mapGrid, _cellRows, _mapWidth);
+
+            _infoRow = new StackPanel { Orientation = Orientation.Horizontal };
+            _legendPanel = new StackPanel { Orientation = Orientation.Horizontal };
+
+            var root = new StackPanel
+            {
+                Orientation = Orientation.Vertical,
+                Children = { _mapGrid, _infoRow, _legendPanel },
+            };
+
+            Content = root;
+
+            _timer = new DispatcherTimer
+            {
+                Interval = TimeSpan.FromMilliseconds(DefaultRefreshMs),
+            };
+            _timer.Tick += (_, _) => RequestSample();
+        }
+
+        public void Resize(int width, int height)
+        {
+            _mapWidth = Math.Max(10, width);
+            _mapHeight = Math.Max(4, height % 2 == 0 ? height : height + 1);
+            _cellRows = _mapHeight / 2;
+
+            _mapGrid.Children.Clear();
+            _mapGrid.RowDefinitions.Clear();
+            _mapGrid.ColumnDefinitions.Clear();
+            _cells = BuildGrid(_mapGrid, _cellRows, _mapWidth);
+        }
+
+        private static TextBlock[,] BuildGrid(Grid grid, int rows, int cols)
+        {
+            var cells = new TextBlock[rows, cols];
+            for (int r = 0; r < rows; r++)
+                grid.RowDefinitions.Add(new RowDefinition(GridLength.Auto));
+            for (int c = 0; c < cols; c++)
+                grid.ColumnDefinitions.Add(new ColumnDefinition(GridLength.Auto));
+
+            for (int r = 0; r < rows; r++)
+            {
+                for (int c = 0; c < cols; c++)
+                {
+                    var tb = new TextBlock
+                    {
+                        Text = "\u2580",
+                        Foreground = Brushes.Black,
+                        Background = Brushes.Black,
+                        Padding = new Thickness(0),
+                        Margin = new Thickness(0),
+                        FontSize = 1,
+                    };
+                    Grid.SetRow(tb, r);
+                    Grid.SetColumn(tb, c);
+                    grid.Children.Add(tb);
+                    cells[r, c] = tb;
+                }
+            }
+            return cells;
+        }
+
+        public void Start()
+        {
+            _cts = new CancellationTokenSource();
+            _timer.Start();
+            RequestSample();
+        }
+
+        public void Stop()
+        {
+            _timer.Stop();
+            _cts?.Cancel();
+            _cts?.Dispose();
+            _cts = null;
+        }
+
+        private void RequestSample()
+        {
+            if (_sampling) return;
+            if (McClient.Instance is not McClient client) return;
+            if (!client.GetTerrainEnabled()) return;
+
+            _sampling = true;
+            var ct = _cts?.Token ?? CancellationToken.None;
+            int bpp = _blocksPerPixel;
+            int w = _mapWidth;
+            int h = _mapHeight;
+
+            bool showPlayers = _nameConfig.Players;
+            bool showHostile = _nameConfig.Hostile;
+            bool showNeutral = _nameConfig.Neutral;
+            bool showPassive = _nameConfig.Passive;
+
+            Task.Run(() =>
+            {
+                try
+                {
+                    var result = SampleTerrain(client, bpp, w, h,
+                        showPlayers, showHostile, showNeutral, showPassive, ct);
+                    if (ct.IsCancellationRequested) return;
+
+                    Dispatcher.UIThread.Post(() =>
+                    {
+                        ApplyPixelBuffer(result, w, h);
+                        UpdateInfoBarAndLegend(client, bpp, result.VisibleCategories, w);
+                    });
+                }
+                catch (OperationCanceledException) { }
+                catch (Exception ex)
+                {
+                    ConsoleIO.WriteLineFormatted($"\u00a7e[Minimap] Sample error: {ex.Message}");
+                }
+                finally
+                {
+                    _sampling = false;
+                }
+            }, ct);
+        }
+
+        internal sealed class EntityLabel
+        {
+            public string Name = "";
+            public Color LabelColor;
+            public int PixelX;
+            public int PixelY;
+        }
+
+        private sealed class SampleResult
+        {
+            public Color[,] Pixels = null!;
+            public (char Ch, Color Fg, Color Bg)?[,] CharOverlay = null!;
+            public HashSet<MobCategory> VisibleCategories = [];
+            public int[,] Heights = null!;
+        }
+
+        private static bool ShouldShowNameLocal(MobCategory cat,
+            bool showPlayers, bool showHostile, bool showNeutral, bool showPassive)
+        {
+            return cat switch
+            {
+                MobCategory.Player => showPlayers,
+                MobCategory.Hostile => showHostile,
+                MobCategory.Neutral => showNeutral,
+                MobCategory.Passive => showPassive,
+                _ => false,
+            };
+        }
+
+        private static SampleResult SampleTerrain(McClient client, int bpp, int mapW, int mapH,
+            bool showPlayers, bool showHostile, bool showNeutral, bool showPassive,
+            CancellationToken ct)
+        {
+            var result = new SampleResult
+            {
+                Pixels = new Color[mapW, mapH],
+                CharOverlay = new (char, Color, Color)?[mapW, mapH / 2],
+                Heights = new int[mapW, mapH],
+            };
+            var world = client.GetWorld();
+            var playerLoc = client.GetCurrentLocation();
+
+            int playerBlockX = (int)Math.Floor(playerLoc.X);
+            int playerBlockZ = (int)Math.Floor(playerLoc.Z);
+            int playerBlockY = (int)Math.Floor(playerLoc.Y);
+
+            var dim = World.GetDimension();
+            int minY = dim.minY;
+            int scanTop = Math.Min(playerBlockY + 32, dim.maxY - 1);
+
+            var entities = client.GetEntityHandlingEnabled()
+                ? client.GetEntities()
+                : null;
+
+            var entityPixels = new Dictionary<(int, int), (Color Color, int Priority)>();
+            int centerX = mapW / 2;
+            int centerY = mapH / 2;
+
+            var nameLabels = new List<EntityLabel>();
+            var uuidNameMap = client.GetOnlinePlayersWithUUID();
+
+            if (entities is not null)
+            {
+                int playerEntityId = client.GetPlayerEntityID();
+                foreach (var kvp in entities)
+                {
+                    if (ct.IsCancellationRequested) return result;
+                    var entity = kvp.Value;
+                    var cat = MinimapEntityClassifier.Classify(entity.Type);
+                    if (cat == MobCategory.NonLiving) continue;
+                    if (kvp.Key == playerEntityId) continue;
+
+                    if (!MinimapEntityClassifier.ShouldDisplay(cat, playerLoc.Y, entity.Location.Y))
+                        continue;
+
+                    double relX = (entity.Location.X - playerLoc.X) / bpp;
+                    double relZ = (entity.Location.Z - playerLoc.Z) / bpp;
+                    int px = (int)Math.Floor(relX) + centerX;
+                    int py = (int)Math.Floor(relZ) + centerY;
+
+                    if (px < 0 || px >= mapW || py < 0 || py >= mapH) continue;
+
+                    var baseColor = MinimapEntityClassifier.GetBaseColor(cat);
+                    Color color;
+                    if (cat == MobCategory.Player)
+                        color = baseColor;
+                    else
+                        color = MinimapEntityClassifier.ApplyDepthFade(baseColor, playerLoc.Y, entity.Location.Y);
+                    int priority = MinimapEntityClassifier.GetPriority(cat);
+
+                    var key = (px, py);
+                    if (!entityPixels.TryGetValue(key, out var existing) || priority > existing.Priority)
+                        entityPixels[key] = (color, priority);
+
+                    result.VisibleCategories.Add(cat);
+
+                    if (ShouldShowNameLocal(cat, showPlayers, showHostile, showNeutral, showPassive))
+                    {
+                        string name = ResolveEntityName(client, entity, cat, uuidNameMap);
+                        nameLabels.Add(new EntityLabel
+                        {
+                            Name = name,
+                            LabelColor = color,
+                            PixelX = px,
+                            PixelY = py,
+                        });
+                    }
+                }
+            }
+
+            entityPixels[(centerX, centerY)] = (MinimapEntityClassifier.PlayerColor, 5);
+            result.VisibleCategories.Add(MobCategory.Player);
+
+            ChunkColumn? cachedColumn = null;
+            int cachedChunkX = int.MinValue, cachedChunkZ = int.MinValue;
+
+            for (int px = 0; px < mapW; px++)
+            {
+                for (int py = 0; py < mapH; py++)
+                {
+                    if (ct.IsCancellationRequested) return result;
+
+                    int baseX = playerBlockX + (px - centerX) * bpp;
+                    int baseZ = playerBlockZ + (py - centerY) * bpp;
+
+                    if (bpp == 1)
+                    {
+                        var (color, surfY) = SampleColumn(world, baseX, baseZ, scanTop, minY,
+                            ref cachedColumn, ref cachedChunkX, ref cachedChunkZ);
+                        result.Pixels[px, py] = color;
+                        result.Heights[px, py] = surfY;
+                    }
+                    else
+                    {
+                        var (color, surfY) = SampleAreaDominant(world, baseX, baseZ, bpp, scanTop, minY,
+                            ref cachedColumn, ref cachedChunkX, ref cachedChunkZ);
+                        result.Pixels[px, py] = color;
+                        result.Heights[px, py] = surfY;
+                    }
+                }
+            }
+
+            for (int px = 0; px < mapW; px++)
+            {
+                for (int py = 0; py < mapH; py++)
+                {
+                    if (entityPixels.ContainsKey((px, py))) continue;
+
+                    int northHeight = py > 0 ? result.Heights[px, py - 1] : result.Heights[px, py];
+                    int delta = result.Heights[px, py] - northHeight;
+                    result.Pixels[px, py] = MinimapColorMap.ApplyHeightShade(result.Pixels[px, py], delta);
+                }
+            }
+
+            foreach (var (key, info) in entityPixels)
+            {
+                var (px, py) = key;
+                if (px >= 0 && px < mapW && py >= 0 && py < mapH)
+                    result.Pixels[px, py] = info.Color;
+            }
+
+            BakeNameLabels(result, nameLabels, mapW, mapH);
+
+            return result;
+        }
+
+        private static string ResolveEntityName(McClient client, Entity entity,
+            MobCategory cat, Dictionary<string, string>? uuidNameMap)
+        {
+            if (cat == MobCategory.Player)
+            {
+                if (!string.IsNullOrWhiteSpace(entity.Name))
+                    return entity.Name;
+
+                if (entity.UUID != System.Guid.Empty)
+                {
+                    var playerInfo = client.GetPlayerInfo(entity.UUID);
+                    if (!string.IsNullOrWhiteSpace(playerInfo?.Name))
+                        return playerInfo.Name;
+
+                    if (uuidNameMap is not null &&
+                        uuidNameMap.TryGetValue(entity.UUID.ToString(), out string? mapped) &&
+                        !string.IsNullOrWhiteSpace(mapped))
+                        return mapped;
+                }
+
+                return "Player";
+            }
+
+            if (!string.IsNullOrWhiteSpace(entity.Name))
+                return entity.Name;
+
+            return entity.Type.ToString();
+        }
+
+        private static void BakeNameLabels(SampleResult result, List<EntityLabel> labels,
+            int mapW, int mapH)
+        {
+            if (labels.Count == 0) return;
+            int cellRows = mapH / 2;
+
+            var occupied = new HashSet<(int col, int row)>();
+
+            labels.Sort((a, b) =>
+            {
+                int pa = MinimapEntityClassifier.GetPriority(
+                    a.LabelColor == MinimapEntityClassifier.PlayerColor ? MobCategory.Player :
+                    a.LabelColor == MinimapEntityClassifier.HostileColor ? MobCategory.Hostile :
+                    a.LabelColor == MinimapEntityClassifier.NeutralColor ? MobCategory.Neutral : MobCategory.Passive);
+                int pb = MinimapEntityClassifier.GetPriority(
+                    b.LabelColor == MinimapEntityClassifier.PlayerColor ? MobCategory.Player :
+                    b.LabelColor == MinimapEntityClassifier.HostileColor ? MobCategory.Hostile :
+                    b.LabelColor == MinimapEntityClassifier.NeutralColor ? MobCategory.Neutral : MobCategory.Passive);
+                return pb.CompareTo(pa);
+            });
+
+            foreach (var lbl in labels)
+            {
+                int cellRow = (lbl.PixelY / 2) + 1;
+                if (cellRow >= cellRows) cellRow = lbl.PixelY / 2 - 1;
+                if (cellRow < 0 || cellRow >= cellRows) continue;
+
+                int startCol = lbl.PixelX - lbl.Name.Length / 2;
+                startCol = Math.Clamp(startCol, 0, mapW - 1);
+
+                bool fits = true;
+                int endCol = Math.Min(startCol + lbl.Name.Length, mapW);
+                for (int c = startCol; c < endCol; c++)
+                {
+                    if (occupied.Contains((c, cellRow)))
+                    {
+                        fits = false;
+                        break;
+                    }
+                }
+                if (!fits) continue;
+
+                for (int i = 0; i < lbl.Name.Length && startCol + i < mapW; i++)
+                {
+                    int col = startCol + i;
+                    occupied.Add((col, cellRow));
+
+                    var bgTop = result.Pixels[col, cellRow * 2];
+                    var bgBot = (cellRow * 2 + 1 < mapH)
+                        ? result.Pixels[col, cellRow * 2 + 1]
+                        : bgTop;
+
+                    var avgBg = Color.FromRgb(
+                        (byte)((bgTop.R + bgBot.R) / 2),
+                        (byte)((bgTop.G + bgBot.G) / 2),
+                        (byte)((bgTop.B + bgBot.B) / 2));
+
+                    result.CharOverlay[col, cellRow] = (lbl.Name[i], lbl.LabelColor, avgBg);
+                }
+            }
+        }
+
+        private static (Color color, int surfaceY) SampleColumn(World world, int x, int z,
+            int scanTop, int minY,
+            ref ChunkColumn? cachedColumn, ref int cachedChunkX, ref int cachedChunkZ)
+        {
+            int chunkX = x >> 4;
+            int chunkZ = z >> 4;
+            if (chunkX != cachedChunkX || chunkZ != cachedChunkZ)
+            {
+                cachedColumn = world[chunkX, chunkZ];
+                cachedChunkX = chunkX;
+                cachedChunkZ = chunkZ;
+            }
+
+            if (cachedColumn is null)
+                return (MinimapColorMap.VoidColor, minY);
+
+            int waterDepth = 0;
+            bool inIce = false;
+            int surfaceY = minY;
+
+            for (int y = scanTop; y >= minY; y--)
+            {
+                var loc = new Mapping.Location(x, y, z);
+                var chunk = cachedColumn.GetChunk(loc);
+                if (chunk is null) continue;
+
+                var block = chunk.GetBlock(loc);
+                var mat = block.Type;
+
+                if (MinimapColorMap.IsFullyTransparent(mat))
+                    continue;
+
+                if (MinimapColorMap.IsWater(mat))
+                {
+                    if (waterDepth == 0) surfaceY = y;
+                    waterDepth++;
+                    continue;
+                }
+
+                if (MinimapColorMap.IsIce(mat) && !inIce)
+                {
+                    if (waterDepth == 0) surfaceY = y;
+                    inIce = true;
+                    continue;
+                }
+
+                if (waterDepth == 0 && !inIce) surfaceY = y;
+
+                var baseColor = MinimapColorMap.GetBaseColor(mat);
+
+                if (waterDepth > 0)
+                    baseColor = MinimapColorMap.BlendWaterColor(baseColor, waterDepth);
+                if (inIce)
+                    baseColor = MinimapColorMap.BlendIceColor(baseColor);
+
+                return (baseColor, surfaceY);
+            }
+
+            if (waterDepth > 0)
+                return (MinimapColorMap.WaterColor, surfaceY);
+
+            return (MinimapColorMap.VoidColor, minY);
+        }
+
+        private static (Color color, int surfaceY) SampleAreaDominant(World world, int baseX, int baseZ,
+            int size, int scanTop, int minY,
+            ref ChunkColumn? cachedColumn, ref int cachedChunkX, ref int cachedChunkZ)
+        {
+            var colorCounts = new Dictionary<Color, (int Count, int SumY)>();
+
+            int step = Math.Max(1, size / 3);
+            for (int dx = 0; dx < size; dx += step)
+            {
+                for (int dz = 0; dz < size; dz += step)
+                {
+                    var (c, surfY) = SampleColumn(world, baseX + dx, baseZ + dz, scanTop, minY,
+                        ref cachedColumn, ref cachedChunkX, ref cachedChunkZ);
+
+                    if (colorCounts.TryGetValue(c, out var existing))
+                        colorCounts[c] = (existing.Count + 1, existing.SumY + surfY);
+                    else
+                        colorCounts[c] = (1, surfY);
+                }
+            }
+
+            Color best = MinimapColorMap.VoidColor;
+            int bestCount = 0;
+            int avgY = minY;
+            foreach (var kvp in colorCounts)
+            {
+                if (kvp.Value.Count > bestCount)
+                {
+                    bestCount = kvp.Value.Count;
+                    best = kvp.Key;
+                    avgY = kvp.Value.SumY / kvp.Value.Count;
+                }
+            }
+            return (best, avgY);
+        }
+
+        private void ApplyPixelBuffer(SampleResult result, int w, int h)
+        {
+            int rows = h / 2;
+            for (int row = 0; row < rows && row < _cellRows; row++)
+            {
+                for (int col = 0; col < w && col < _mapWidth; col++)
+                {
+                    var overlay = result.CharOverlay[col, row];
+                    if (overlay is not null)
+                    {
+                        var (ch, fg, bg) = overlay.Value;
+                        _cells[row, col].Text = ch.ToString();
+                        _cells[row, col].Foreground = new SolidColorBrush(fg);
+                        _cells[row, col].Background = new SolidColorBrush(bg);
+                    }
+                    else
+                    {
+                        var topColor = result.Pixels[col, row * 2];
+                        var bottomColor = result.Pixels[col, row * 2 + 1];
+
+                        _cells[row, col].Text = "\u2580";
+                        _cells[row, col].Foreground = new SolidColorBrush(topColor);
+                        _cells[row, col].Background = new SolidColorBrush(bottomColor);
+                    }
+                }
+            }
+        }
+
+        private void UpdateInfoBarAndLegend(McClient client, int bpp,
+            HashSet<MobCategory> categories, int mapW)
+        {
+            var loc = client.GetCurrentLocation();
+            float yaw = client.GetYaw();
+            string arrow = GetDirectionArrow(yaw);
+
+            int x = (int)Math.Floor(loc.X);
+            int y = (int)Math.Floor(loc.Y);
+            int z = (int)Math.Floor(loc.Z);
+
+            string coordPart = $"{x}, {y}, {z}  {arrow}  {bpp}:1";
+
+            var legendParts = new List<string>();
+            var legendColors = new List<Color>();
+
+            var sorted = categories
+                .Where(c => c != MobCategory.NonLiving)
+                .OrderByDescending(MinimapEntityClassifier.GetPriority);
+
+            int catCount = 0;
+            foreach (var cat in sorted)
+            {
+                if (catCount >= 4) break;
+                legendParts.Add(MinimapEntityClassifier.GetCategoryLabel(cat));
+                legendColors.Add(MinimapEntityClassifier.GetBaseColor(cat));
+                catCount++;
+            }
+
+            int legendLen = 0;
+            for (int i = 0; i < legendParts.Count; i++)
+                legendLen += 1 + legendParts[i].Length + (i > 0 ? 1 : 0);
+
+            bool fitsOnOneLine = legendParts.Count > 0
+                && coordPart.Length + 2 + legendLen <= mapW;
+
+            _infoRow.Children.Clear();
+            _infoRow.Children.Add(new TextBlock
+            {
+                Text = coordPart,
+                Foreground = Brushes.Gray,
+                Padding = new Thickness(0),
+            });
+
+            if (fitsOnOneLine)
+            {
+                AppendLegendItems(_infoRow, legendParts, legendColors, leftMargin: 2);
+                _legendPanel.Children.Clear();
+                _legendPanel.IsVisible = false;
+            }
+            else
+            {
+                _legendPanel.IsVisible = legendParts.Count > 0;
+                _legendPanel.Children.Clear();
+                AppendLegendItems(_legendPanel, legendParts, legendColors, leftMargin: 0);
+            }
+        }
+
+        private static void AppendLegendItems(StackPanel panel,
+            List<string> parts, List<Color> colors, int leftMargin)
+        {
+            for (int i = 0; i < parts.Count; i++)
+            {
+                int ml = i == 0 ? leftMargin : 1;
+                panel.Children.Add(new TextBlock
+                {
+                    Text = "\u25cf",
+                    Foreground = new SolidColorBrush(colors[i]),
+                    Padding = new Thickness(0),
+                    Margin = ml > 0 ? new Thickness(ml, 0, 0, 0) : new Thickness(0),
+                });
+                panel.Children.Add(new TextBlock
+                {
+                    Text = parts[i],
+                    Foreground = Brushes.Gray,
+                    Padding = new Thickness(0),
+                    Margin = new Thickness(0),
+                });
+            }
+        }
+
+        private static string GetDirectionArrow(float yaw)
+        {
+            double normalized = ((yaw % 360) + 360) % 360;
+            int index = (int)Math.Round(normalized / 45.0) % 8;
+            return index switch
+            {
+                0 => "\u2193", // S
+                1 => "\u2199", // SW
+                2 => "\u2190", // W
+                3 => "\u2196", // NW
+                4 => "\u2191", // N
+                5 => "\u2197", // NE
+                6 => "\u2192", // E
+                7 => "\u2198", // SE
+                _ => "\u2193",
+            };
+        }
+    }
+}

MinecraftClient/Tui/MinimapEntityCategories.json

@@ -0,0 +1,167 @@
+{
+  "version": "26.1-rc-2",
+  "hostile": [
+    "Blaze",
+    "Bogged",
+    "Breeze",
+    "CamelHusk",
+    "Creaking",
+    "Creeper",
+    "Drowned",
+    "ElderGuardian",
+    "EnderDragon",
+    "Endermite",
+    "Evoker",
+    "Ghast",
+    "Giant",
+    "Guardian",
+    "Hoglin",
+    "Husk",
+    "Illusioner",
+    "MagmaCube",
+    "Parched",
+    "Phantom",
+    "Piglin",
+    "PiglinBrute",
+    "Pillager",
+    "Ravager",
+    "Shulker",
+    "Silverfish",
+    "Skeleton",
+    "Slime",
+    "Stray",
+    "Vex",
+    "Vindicator",
+    "Warden",
+    "Witch",
+    "Wither",
+    "WitherSkeleton",
+    "Zoglin",
+    "Zombie",
+    "ZombieNautilus",
+    "ZombieVillager"
+  ],
+  "passive": [
+    "Allay",
+    "Armadillo",
+    "Axolotl",
+    "Bat",
+    "Camel",
+    "Cat",
+    "Chicken",
+    "Cod",
+    "Cow",
+    "Donkey",
+    "Fox",
+    "Frog",
+    "GlowSquid",
+    "HappyGhast",
+    "Horse",
+    "Mooshroom",
+    "Mule",
+    "Nautilus",
+    "Ocelot",
+    "Parrot",
+    "Pig",
+    "Pufferfish",
+    "Rabbit",
+    "Salmon",
+    "Sheep",
+    "SkeletonHorse",
+    "Sniffer",
+    "Squid",
+    "Strider",
+    "Tadpole",
+    "TropicalFish",
+    "Turtle",
+    "Villager",
+    "WanderingTrader",
+    "ZombieHorse"
+  ],
+  "neutral": [
+    "Bee",
+    "CaveSpider",
+    "CopperGolem",
+    "Dolphin",
+    "Enderman",
+    "Goat",
+    "IronGolem",
+    "Llama",
+    "Panda",
+    "PolarBear",
+    "SnowGolem",
+    "Spider",
+    "TraderLlama",
+    "Wolf",
+    "ZombifiedPiglin"
+  ],
+  "non_living": [
+    "AcaciaBoat",
+    "AcaciaChestBoat",
+    "AreaEffectCloud",
+    "ArmorStand",
+    "Arrow",
+    "BambooChestRaft",
+    "BambooRaft",
+    "BirchBoat",
+    "BirchChestBoat",
+    "BlockDisplay",
+    "BreezeWindCharge",
+    "CherryBoat",
+    "CherryChestBoat",
+    "ChestMinecart",
+    "CommandBlockMinecart",
+    "DarkOakBoat",
+    "DarkOakChestBoat",
+    "DragonFireball",
+    "Egg",
+    "EndCrystal",
+    "EnderPearl",
+    "EvokerFangs",
+    "ExperienceBottle",
+    "ExperienceOrb",
+    "EyeOfEnder",
+    "FallingBlock",
+    "Fireball",
+    "FireworkRocket",
+    "FishingBobber",
+    "FurnaceMinecart",
+    "GlowItemFrame",
+    "HopperMinecart",
+    "Interaction",
+    "Item",
+    "ItemDisplay",
+    "ItemFrame",
+    "JungleBoat",
+    "JungleChestBoat",
+    "LeashKnot",
+    "LightningBolt",
+    "LingeringPotion",
+    "LlamaSpit",
+    "MangroveBoat",
+    "MangroveChestBoat",
+    "Mannequin",
+    "Marker",
+    "Minecart",
+    "OakBoat",
+    "OakChestBoat",
+    "OminousItemSpawner",
+    "Painting",
+    "PaleOakBoat",
+    "PaleOakChestBoat",
+    "ShulkerBullet",
+    "SmallFireball",
+    "Snowball",
+    "SpawnerMinecart",
+    "SpectralArrow",
+    "SplashPotion",
+    "SpruceBoat",
+    "SpruceChestBoat",
+    "TextDisplay",
+    "Tnt",
+    "TntMinecart",
+    "Trident",
+    "WindCharge",
+    "WitherSkull"
+  ]
+}

MinecraftClient/Tui/MinimapEntityClassifier.cs

@@ -0,0 +1,178 @@
+using System;
+using System.Collections.Frozen;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Text.Json;
+using Avalonia.Media;
+using MinecraftClient.Mapping;
+
+namespace MinecraftClient.Tui
+{
+    public enum MobCategory
+    {
+        Hostile,
+        Passive,
+        Neutral,
+        Player,
+        NonLiving,
+    }
+
+    public enum MinimapPosition
+    {
+        top_left,
+        top_right,
+        center,
+        bottom_left,
+        bottom_right,
+    }
+
+    public sealed class NameDisplayConfig
+    {
+        public volatile bool Players = false;
+        public volatile bool Hostile = false;
+        public volatile bool Neutral = false;
+        public volatile bool Passive = false;
+
+        public bool AnyEnabled => Players || Hostile || Neutral || Passive;
+
+        public void SetAll(bool value)
+        {
+            Players = value;
+            Hostile = value;
+            Neutral = value;
+            Passive = value;
+        }
+
+        public bool ShouldShowName(MobCategory category) => category switch
+        {
+            MobCategory.Player => Players,
+            MobCategory.Hostile => Hostile,
+            MobCategory.Neutral => Neutral,
+            MobCategory.Passive => Passive,
+            _ => false,
+        };
+    }
+
+    /// <summary>
+    /// Classifies entities into minimap categories using data extracted from
+    /// Minecraft's MobCategory assignments. Categories are loaded from the
+    /// embedded MinimapEntityCategories.json resource generated by
+    /// tools/gen_entity_category_map.py.
+    /// </summary>
+    public static class MinimapEntityClassifier
+    {
+        public static readonly Color HostileColor = Color.FromRgb(255, 68, 68);
+        public static readonly Color PassiveColor = Color.FromRgb(68, 255, 68);
+        public static readonly Color NeutralColor = Color.FromRgb(255, 170, 0);
+        public static readonly Color PlayerColor = Color.FromRgb(255, 255, 255);
+        public static readonly Color FadedGray = Color.FromRgb(100, 100, 100);
+
+        private static readonly FrozenDictionary<EntityType, MobCategory> CategoryTable;
+
+        static MinimapEntityClassifier()
+        {
+            var table = new Dictionary<EntityType, MobCategory>();
+
+            try
+            {
+                using var stream = Assembly.GetExecutingAssembly()
+                    .GetManifestResourceStream("MinimapEntityCategories.json");
+                if (stream is not null)
+                {
+                    using var doc = JsonDocument.Parse(stream);
+                    var root = doc.RootElement;
+
+                    LoadCategory(root, "hostile", MobCategory.Hostile, table);
+                    LoadCategory(root, "passive", MobCategory.Passive, table);
+                    LoadCategory(root, "neutral", MobCategory.Neutral, table);
+                    LoadCategory(root, "non_living", MobCategory.NonLiving, table);
+                }
+            }
+            catch (Exception ex)
+            {
+                ConsoleIO.WriteLogLine($"[Minimap] Failed to load entity categories: {ex.Message}");
+            }
+
+            CategoryTable = table.ToFrozenDictionary();
+        }
+
+        private static void LoadCategory(JsonElement root, string key,
+            MobCategory category, Dictionary<EntityType, MobCategory> table)
+        {
+            if (!root.TryGetProperty(key, out var arr))
+                return;
+
+            foreach (var el in arr.EnumerateArray())
+            {
+                var name = el.GetString();
+                if (name is not null && Enum.TryParse<EntityType>(name, out var et))
+                    table.TryAdd(et, category);
+            }
+        }
+
+        public static MobCategory Classify(EntityType type)
+        {
+            if (type == EntityType.Player)
+                return MobCategory.Player;
+            return CategoryTable.GetValueOrDefault(type, MobCategory.NonLiving);
+        }
+
+        public static Color GetBaseColor(MobCategory category) => category switch
+        {
+            MobCategory.Hostile => HostileColor,
+            MobCategory.Passive => PassiveColor,
+            MobCategory.Neutral => NeutralColor,
+            MobCategory.Player => PlayerColor,
+            _ => FadedGray,
+        };
+
+        public static Color ApplyDepthFade(Color baseColor, double playerY, double entityY)
+        {
+            double depth = playerY - entityY;
+
+            if (depth <= 5.0)
+                return baseColor;
+
+            if (depth >= 15.0)
+                return FadedGray;
+
+            double t = (depth - 5.0) / 10.0;
+            return Lerp(baseColor, FadedGray, t);
+        }
+
+        public static bool ShouldDisplay(MobCategory category, double playerY, double entityY)
+        {
+            if (category == MobCategory.Player)
+                return true;
+            if (entityY >= playerY)
+                return true;
+            return playerY - entityY <= 15.0;
+        }
+
+        public static int GetPriority(MobCategory category) => category switch
+        {
+            MobCategory.Hostile => 4,
+            MobCategory.Player => 3,
+            MobCategory.Neutral => 2,
+            MobCategory.Passive => 1,
+            _ => 0,
+        };
+
+        public static string GetCategoryLabel(MobCategory category) => category switch
+        {
+            MobCategory.Hostile => Translations.tui_minimap_legend_hostile,
+            MobCategory.Passive => Translations.tui_minimap_legend_passive,
+            MobCategory.Neutral => Translations.tui_minimap_legend_neutral,
+            MobCategory.Player => Translations.tui_minimap_legend_player,
+            _ => "?",
+        };
+
+        private static Color Lerp(Color a, Color b, double t)
+        {
+            byte r = (byte)(a.R + (b.R - a.R) * t);
+            byte g = (byte)(a.G + (b.G - a.G) * t);
+            byte bl = (byte)(a.B + (b.B - a.B) * t);
+            return Color.FromRgb(r, g, bl);
+        }
+    }
+}