> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dietrich-development.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install and configure MapMarker - sprites, colors, compass overlay, and localization

## Installation

<Steps>
  <Step title="Download">
    Get the latest release from our [Tebex store](https://tebex.dietrich-development.com) and download it from your [Keymaster](https://portal.cfx.re/assets/granted-assets)
  </Step>

  <Step title="Extract">
    Extract the script folder to your server's `resources` directory
  </Step>

  <Step title="Configure">
    Add `ensure [script-name]` to your `server.cfg`
  </Step>

  <Step title="Customize">
    Configure the `config.lua` file to your preferences (see the configuration section below)
  </Step>
</Steps>

## Configuration

The script is configured through the `config.lua` file. Here are the main configuration options:

### General settings

```lua theme={null}
Config = Config or {}

-- General toggles
Config.debug = false

-- Enable/disable the compass overlay feature globally
Config.CompassEnabled = true

-- Optional: default compass icon (under ui/). Supports .png or .svg.
Config.CompassIconFallback = 'icons/marker.svg'

-- Keybind/command to open the UI manager
Config.OpenCommand = 'mapmarkers'

-- Max blips per player (safety)
Config.MaxBlipsPerPlayer = 50
```

### Allowed blip sprites

Configure which blip sprites players can use:

```lua theme={null}
-- Allowed blip sprites (sprite hashes). Only these can be used by players.
Config.AllowedSprites = {
    -- Hash numbers below are examples. Replace/add as needed per your server's needs
    -- Optional per-sprite icon for compass overlay, relative to ui/ (e.g. 'icons/shop.png').
    { label = 'Camp',           hash =  -1606321000, icon = "icons/blip_region_caravan.png" },
    { label = 'Shop',           hash =  1481032477, icon = "icons/blip_shop_store.png" },
    { label = 'Horse',          hash =  1938782895, icon = "icons/blip_shop_horse.png" },
    { label = 'Treasure',       hash =  -1138864184, icon = "icons/blip_chest.png" },
    { label = 'Cross',          hash =  -1489164512, icon = "icons/blip_ambient_gang_leader.png" },
    { label = 'Campfire',       hash =  1754365229, icon = "icons/blip_campfire.png" },
}
```

<Note>
  You can find more blip sprites and their hash values at: [RDR3 blip discoveries](https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/textures/blips)
</Note>

### Allowed colors

Configure available colors for blip customization:

```lua theme={null}
-- Allowed colors for UI selection. RedM blip color support is limited; some sprites ignore color.
Config.AllowedColors = {
    -- blip_style can be any style from: https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/blip_styles
    -- Use nil to apply no style (e.g., white)
    { label = 'White', value = 'white', rgb = {255,255,255}, blip_style = nil },
    { label = 'Red',   value = 'red',   rgb = {200,40,40},  blip_style = 'BLIP_STYLE_DEBUG_RED' },
    { label = 'Green', value = 'green', rgb = {56,176,74},  blip_style = 'BLIP_STYLE_DEBUG_GREEN' },
    { label = 'Blue',  value = 'blue',  rgb = {70,120,200}, blip_style = 'BLIP_STYLE_DEBUG_BLUE' },
    { label = 'Yellow',value = 'yellow',rgb = {220,180,60}, blip_style = 'BLIP_STYLE_DEBUG_YELLOW' },
}
```

<Info>
  RedM blip color support is limited. Colors will apply to the compass overlay and map blips where supported by the game engine.
</Info>

### Language localization

Customize the UI text and labels:

```lua theme={null}
-- UI language/localization (server owner can translate these)
Config.Language = {
    TitleMain = 'Map Markers',
    TitleCreate = 'Create new blip',
    TitleYour = 'Your blips',

    LabelName = 'Name',
    LabelSprite = 'Sprite',
    LabelColor = 'Color',
    LabelWhere = 'Where',
    LabelShowOnCompass = 'Show on compass',

    WhereCurrent = 'Current Position',
    WhereWaypoint = 'Waypoint',
    WhereCoord = 'Specific Coordinates',

    ButtonCreate = 'Create',
    ButtonClose = 'Close',
    ButtonCompassOn = 'Compass: On',
    ButtonCompassOff = 'Compass: Off',

    ListSetCurrent = 'Set to current',
    ListSetWaypoint = 'Set to waypoint',
    ListDelete = 'Delete',

    LabelX = 'X',
    LabelY = 'Y',
    LabelZ = 'Z',
    LabelSpriteInline = 'Sprite',
    LabelColorInline = 'Color',
    LabelCompassInline = 'Compass',

    SelectSpritePlaceholder = 'Select sprite',
}
```

## Compass overlay

The compass overlay feature provides an immersive navigation experience:

<Info>
  The compass overlay displays custom markers on the compass UI, making navigation more intuitive.
</Info>

### Compass configuration

```lua theme={null}
-- Enable/disable the compass overlay feature globally
Config.CompassEnabled = true

-- Optional: default compass icon (under ui/). Supports .png or .svg.
Config.CompassIconFallback = 'icons/marker.svg'
```

<Warning>
  Disabling the compass feature will remove the compass overlay option from the UI entirely.
</Warning>

## Customization

### Adding custom sprites

To add new blip sprites, find the hash value and add it to the `AllowedSprites` table:

```lua theme={null}
{ label = 'Your Custom Label', hash = YOUR_HASH_VALUE, icon = "icons/your_icon.png" }
```

### Adding custom colors

To add new colors, include them in the `AllowedColors` table:

```lua theme={null}
{ label = 'Purple', value = 'purple', rgb = {128,0,128}, blip_style = 'BLIP_STYLE_DEBUG_PURPLE' }
```

### Custom icons

Place custom icons in the `ui/icons/` directory. Supported formats:

* PNG files (`.png`)
* SVG files (`.svg`)

<Note>
  Icon paths in the configuration are relative to the `ui/` directory.
</Note>

## Performance considerations

<Info>
  The script is optimized for performance, but here are some tips to ensure smooth operation:
</Info>

* **Max blips per player**: The default limit of 50 blips per player helps maintain performance
* **Compass overlay**: Disable if not needed to reduce UI overhead
* **Debug mode**: Keep disabled in production for optimal performance
* **Sprite selection**: Limit the number of allowed sprites to reduce UI complexity

## Troubleshooting

<AccordionGroup>
  <Accordion title="UI not opening">
    Check if the command is properly configured in `Config.OpenCommand`, ensure the script is properly started, and verify there are no console errors.
  </Accordion>

  <Accordion title="Compass overlay not working">
    Verify `Config.CompassEnabled` is set to true, check that compass icons exist in the ui/icons directory, and ensure the UI files are properly loaded.
  </Accordion>

  <Accordion title="Blips not appearing">
    Confirm the sprite hash values are correct, check that colors are properly configured, and verify the placement coordinates are valid.
  </Accordion>

  <Accordion title="Performance issues">
    Reduce the maximum blips per player, limit the number of allowed sprites, disable debug mode, and check for conflicting scripts.
  </Accordion>
</AccordionGroup>

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  -- No additional configuration required
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  -- No additional configuration required
  ```

  ```lua Custom Framework theme={null}
  -- Set in config.lua
  Config.Framework = 'custom'

  -- Requires additional configuration in frameworkBridge.lua
  -- See framework bridge documentation for details
  ```
</CodeGroup>

## Support

If you encounter issues or need assistance:

<Columns cols={2}>
  <Card title="Discord support" icon="discord" href="https://discord.gg/4jhQsPr6pe">
    Join our Discord community for support and updates.
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Docs home - installation basics and links to every script.
  </Card>
</Columns>