PlumMinimap 🗺️

A powerful and flexible minimap system for Roblox games, originally developed by ReelPlum and enhanced by Meta Games, LLC. This system provides a real-time overhead view of your game world with support for custom blips, player tracking, and dynamic camera positioning.

🌟 Features

• Real-time Player Tracking: Automatically follows the local player with smooth camera movement
• Custom Blip System: Tag any object in your workspace to display it on the minimap
• Multi-Image Support: Support for large worlds with multiple map images
• Flexible Positioning: Configurable size, position, and anchoring options
• Border Snapping: Blips can optionally snap to minimap borders when objects are off-screen
• Rotation Support: Optional camera-relative rotation for enhanced navigation
• Customizable UI: Extensive styling options for colors, transparency, and corner rounding
• Performance Optimized: Efficient rendering with configurable distance culling

📋 Table of Contents

• Features
• Dependencies
• Installation
• Quick Start
• Configuration
• API Reference
• Examples
• Contributing
• License

🛠️ Dependencies

This system requires the following packages to function properly:

• Fusion (v0.2+) - Reactive UI state management
• Knight Framework (v1.0.6+) - Dependency injection and module management

Note: This is a bare minimap system without extended features like tooltips or advanced interaction systems. Basic programming knowledge is required for proper integration.

📦 Installation

1. Install Dependencies:

   • Add Fusion v0.2+ to your project
   • Install Knight Framework v1.0.6+

2. Add PlumMinimap:

   • Clone or download this repository
   • Place the src folder contents into your project structure
   • Ensure the minimap controller is registered with your Knight framework setup

3. Configure Your Project:

   • Set up your map images and upload them as Roblox decals
   • Configure the settings in Settings.luau to match your game world

🚀 Quick Start

Basic Setup

1. Configure Map Images:

-- In Settings.luau, update the Map section
["Map"] = {
    ["images"] = {
        {
            ["mapId"] = 1234567890,  -- Your map image ID
            ["center"] = Vector3.new(0, 0, 0),  -- World center position
            ["size"] = Vector2.new(1024, 1024),  -- Image size in pixels
        },
    },
},

2. Add Blip Tags:

-- Add custom blip types to the Tags section
{
    tagName = "Treasure",
    toolTip = "Hidden treasure location",
    iconID = 5254553771,
    color = Color3.fromRGB(255, 215, 0),
    size = UDim2.new(0, 20, 0, 20),
    snapToBorder = true,
    rotate = false,
},

3. Tag Objects in Workspace: Use Roblox's CollectionService or a tag editor plugin to tag parts in your workspace with the configured tag names.

Initialize the System

The minimap system automatically initializes through the Knight framework dependency injection system. Once properly configured, it will:

• Create a minimap camera for overhead viewing
• Render the configured map images
• Display tagged objects as blips
• Track the local player's position

⚙️ Configuration

GUI Settings

Control the visual appearance and positioning of your minimap:

["Gui"] = {
    ["mapSize"] = UDim2.new(0.25, 0, 0.25, 0),  -- Size of the minimap
    ["mapPosition"] = UDim2.new(1, -5, 1, -5),  -- Position (top-right corner)
    ["anchorPoint"] = Vector2.new(1, 1),         -- Anchor point
    ["mapColor"] = Color3.fromRGB(61, 134, 149), -- Background color
    ["mapTransparency"] = 0.5,                   -- Background transparency
    -- ... more options available
}

Technical Settings

Fine-tune performance and behavior:

["Technical"] = {
    ["onePixel"] = 1,              -- Studs per pixel ratio
    ["maxBlipDistance"] = 1000,    -- Maximum blip render distance
    ["rotation"] = true,           -- Enable camera rotation
    ["Visible"] = true,            -- Initial visibility state
}

Blip Configuration

Create custom blip types for different object categories:

{
    tagName = "SpawnPoint",               -- CollectionService tag name
    toolTip = "Player spawn location",    -- Hover tooltip text
    iconID = 1234567890,                 -- Roblox image asset ID
    color = Color3.fromRGB(0, 255, 0),   -- Blip tint color
    size = UDim2.new(0, 15, 0, 15),      -- Blip size
    snapToBorder = true,                 -- Snap to edge when off-screen
    rotate = false,                      -- Rotate with object orientation
}

📚 API Reference

ClientMinimapController

The main controller class that manages minimap functionality.

Methods

• getUIPosition(objPosition: Vector3, vps: Vector2) -> Vector2

  • Converts world position to minimap UI coordinates

• getDistanceFromPlayer(pos: Vector3) -> number

  • Calculate distance from local player to given position

• findTag(tagName: string) -> table?

  • Find tag configuration by name

Properties

• mapCamera: Camera - The overhead camera used for minimap rendering
• mapVisible: Fusion.Value<boolean> - Controls minimap visibility
• settings: table - Configuration table from Settings.luau

Settings Configuration

Detailed configuration options for customizing your minimap experience.

Tag Structure

{
    tagName: string,      -- CollectionService tag name
    toolTip: string,      -- Tooltip text (empty string to disable)
    iconID: number,       -- Roblox image asset ID
    color: Color3,        -- Blip color tint
    size: UDim2,          -- Blip dimensions
    snapToBorder: boolean,-- Enable border snapping
    rotate: boolean,      -- Enable rotation with object
}

💡 Examples

Adding a Custom Blip Type

-- 1. Add to Settings.luau Tags array
{
    tagName = "QuestGiver",
    toolTip = "Talk to receive a quest",
    iconID = 987654321,
    color = Color3.fromRGB(255, 255, 0),
    size = UDim2.new(0, 25, 0, 25),
    snapToBorder = true,
    rotate = false,
}

-- 2. Tag an NPC in workspace
local npc = workspace.QuestNPC
CollectionService:AddTag(npc, "QuestGiver")

Multi-Region Map Setup

-- Configure multiple map images for large worlds
["Map"] = {
    ["images"] = {
        {
            ["mapId"] = 1111111111,
            ["center"] = Vector3.new(-500, 0, -500),
            ["size"] = Vector2.new(1024, 1024),
        },
        {
            ["mapId"] = 2222222222,
            ["center"] = Vector3.new(500, 0, -500),
            ["size"] = Vector2.new(1024, 1024),
        },
        {
            ["mapId"] = 3333333333,
            ["center"] = Vector3.new(-500, 0, 500),
            ["size"] = Vector2.new(1024, 1024),
        },
        {
            ["mapId"] = 4444444444,
            ["center"] = Vector3.new(500, 0, 500),
            ["size"] = Vector2.new(1024, 1024),
        },
    },
}

Controlling Minimap Visibility

-- Access the controller through Knight framework
local minimapController = require("ClientMinimapController")

-- Toggle visibility
minimapController.mapVisible:set(not minimapController.mapVisible:get())

-- Hide minimap
minimapController.mapVisible:set(false)

-- Show minimap  
minimapController.mapVisible:set(true)

📄 License

This project is licensed under the terms specified in the LICENSE file.

🙏 Acknowledgments

• ReelPlum - Original minimap system creator
• EgoMoose - Viewport projection mathematics
• Meta Games, LLC - Framework integration and enhancements

---

Made with ❤️ for the Roblox development community