# Configuration

> Configuration reference for ML Display Zone

Category: ZONE DISPLAY · Source: https://miciomods.it/docs/ml-display-zone-configuration · Last updated: 2026-07-09

## Overview

- `shared/config.lua`: All zone detection, display, audio, time, UI, and custom location settings

## Debug & Language

**shared/config.lua**

```lua
Config.DebugMode = false
Config.Language = 'en'
```

- `DebugMode`: Enables console output and the `/viewzonename` command
- `Language`: Language code for translations

## Entry Messages & Loading

**shared/config.lua**

```lua
Config.RandomEntryMessages = true
Config.ForceLoad = true
```

- `RandomEntryMessages`: Pick a random welcome line from the locale `EntryMessages` list instead of the plain zone name
- `ForceLoad`: Initialize the display even if the framework player-load event never fires

## Zone Detection

**shared/config.lua**

```lua
Config.UseNativeZones = true
Config.ZoneCooldownMinutes = 5
Config.DisabledZones = {
    JAIL = true,
    CHIL = true,
}
```

- `UseNativeZones`: Use GTA's built-in zone detection system
- `ZoneCooldownMinutes`: Minimum minutes between repeated notifications for the same zone
- `DisabledZones`: Zone codes that never trigger a notification. Key = GTA zone code, value = `true`

## Display

**shared/config.lua**

```lua
Config.Theme = 'default'
Config.AnimationStyle = 'typewriter'
Config.ShowStreetName = true
Config.ShowCoordinates = false
Config.ShowZoneIcon = true
```

- `Theme`: Visual theme. Options: `'default'`, `'wasteland'`, `'cyberpunk'`, `'noir'`, `'fantasy'`
- `AnimationStyle`: Text entrance animation. Options: `'typewriter'`, `'slideIn'`, `'fadeLetter'`, `'glitch'`, `'cinematic'`
- `ShowStreetName`: Display the street name below the zone label
- `ShowCoordinates`: Display GPS coordinates
- `ShowZoneIcon`: Display a FontAwesome icon next to the zone name

## Audio

**shared/config.lua**

```lua
Config.UseSoundEffect = true
Config.ThemeSounds = {
    default   = 'typewriter.mp3',
    wasteland = 'typewriter.mp3',
    cyberpunk = 'typewriter.mp3',
    noir      = 'typewriter.mp3',
    fantasy   = 'typewriter.mp3',
}
Config.EnableCustomZoneSounds = false
```

- `UseSoundEffect`: Play a sound effect during zone entry animation
- `ThemeSounds`: Sound file per theme. Files must exist in `web/`
- `EnableCustomZoneSounds`: Allow zone-specific sound overrides (configured per zone in `Config.Locations`)

### Per-Zone Sounds

**shared/config.lua**

```lua
Config.ZoneSounds = {
    BEACH = 'typewriter.mp3',
    AIRP  = 'typewriter.mp3',
}
```

- `ZoneSounds`: Sound file per GTA zone code, used when `EnableCustomZoneSounds = true`. Files must exist in `web/`

## Time Display

**shared/config.lua**

```lua
Config.SeeDate = true
Config.SeeYear = true
Config.SeeTime = true
Config.UseGameTime = false
Config.TimezoneOffset = nil
Config.FixedYear = nil
Config.DateOffsetYears = 0
Config.DateOffsetMonths = 0
Config.DateOffsetDays = 0
```

- `SeeDate`: Show the date portion in the notification
- `SeeYear`: Include the year in the date
- `SeeTime`: Show the time portion in the notification
- `UseGameTime`: `true` = use GTA's in-game clock, `false` = use real-world time from the server
- `TimezoneOffset`: UTC offset in hours for real-time mode. `nil` = server local time
- `FixedYear`: Force a specific year in the display. `nil` = actual year
- `DateOffsetYears`: Shift the displayed year forward/backward
- `DateOffsetMonths`: Shift the displayed month
- `DateOffsetDays`: Shift the displayed day

## Visit Tracking

**shared/config.lua**

```lua
Config.EnableVisitTracking = true
Config.ShowVisitCount = true
Config.EnableFirstVisitEffect = true
```

- `EnableVisitTracking`: Track how many times each player visits a zone (stored in KVP)
- `ShowVisitCount`: Display the visit counter on the notification
- `EnableFirstVisitEffect`: Show a special badge on the first visit to a zone

### Permanent Subtitle Behavior

**shared/config.lua**

```lua
Config.ShowPermanentSubtitleWithZone = true
```

- `ShowPermanentSubtitleWithZone`: Keep a permanent subtitle visible while a zone notification is shown. `false` hides it during zone entries

## UI Customization

**shared/config.lua**

```lua
Config.UI = {
    TextColor        = '#FFFFFF',
    TextShadow       = true,
    TextShadowColor  = '#000000',
    FontFamily       = "'Courier New', Courier, monospace",
    FontSizeLocation = '24px',
    FontSizeDateTime = '20px',
    FontSizeSubtitle = '18px',
    FontWeight       = 'bold',
    TextTransform    = 'none',
}
```

- `TextColor`: Main text color (hex)
- `TextShadow`: Enable text shadow
- `TextShadowColor`: Shadow color (hex)
- `FontFamily`: CSS font-family stack
- `FontSizeLocation`: Font size for the zone name
- `FontSizeDateTime`: Font size for date/time line
- `FontSizeSubtitle`: Font size for subtitle/street name
- `FontWeight`: CSS font weight
- `TextTransform`: CSS text-transform. Options: `'none'`, `'uppercase'`, `'lowercase'`, `'capitalize'`

## Custom Fonts

**shared/config.lua**

```lua
Config.CustomFontUrl = nil
Config.EnableCustomFontUI = true
Config.AvailableFonts = {
    { name = 'Courier New', value = "'Courier New', Courier, monospace" },
    { name = 'Roboto Mono', value = "'Roboto Mono', monospace" },
    -- ...
}
```

- `CustomFontUrl`: Google Fonts CDN URL to load a custom font. `nil` = use system fonts
- `EnableCustomFontUI`: Allow players to pick a font from the settings panel
- `AvailableFonts`: List of font options shown in the player settings. Each entry has `name` (display label) and `value` (CSS font-family string)

## Zone Labels & Icons

**shared/config.lua**

```lua
Config.ZoneLabels = {
    AIRP = 'Los Santos International Airport',
    ALAMO = 'Alamo Sea',
    ALTA = 'Alta',
    -- 74+ zone entries
}

Config.ZoneIcons = {
    AIRP = 'fa-plane',
    ALAMO = 'fa-water',
    ALTA = 'fa-building',
    -- matching icons
}
```

- `ZoneLabels`: Maps GTA zone codes to display names. Add or override entries to rename zones.
- `ZoneIcons`: Maps GTA zone codes to FontAwesome icon class names. Icons appear next to zone labels when `ShowZoneIcon = true`.

## Custom Locations

**shared/config.lua**

```lua
Config.Locations = {
    {
        type = 'sphere',
        label = 'My Custom Area',
        coords = vector3(100.0, 200.0, 30.0),
        radius = 30.0,
    },
    {
        type = 'box',
        label = 'Warehouse',
        coords = vector3(500.0, -200.0, 40.0),
        size = vector3(20.0, 30.0, 10.0),
        rotation = 45,
    },
    {
        type = 'poly',
        label = 'Farm Area',
        points = {
            vec3(100.0, 100.0, 30.0),
            vec3(200.0, 100.0, 30.0),
            vec3(200.0, 200.0, 30.0),
            vec3(100.0, 200.0, 30.0),
        },
        thickness = 5.0,
    },
}
```

- `type`: Zone shape: `'sphere'`, `'box'`, or `'poly'`
- `label`: Display name for the zone notification
- `coords`: Center position (`vector3`) for sphere and box types
- `radius`: Detection radius for sphere zones
- `size`: Dimensions (`vector3`) for box zones
- `rotation`: Heading in degrees for box zones
- `points`: Vertex list (`vec3` array) for polygon zones
- `thickness`: Vertical height for polygon zones

Custom locations use `lib.zones` and trigger zone enter/exit handlers.

## Commands

**shared/config.lua**

```lua
Config.CommandSettings = 'zonesettings'
Config.CommandZoneName = 'viewzonename'
Config.SettingsKeybind = nil
```

- `CommandSettings`: Chat command to open the player settings UI
- `CommandZoneName`: Debug command to display the raw GTA zone code. Requires `DebugMode = true`
- `SettingsKeybind`: Optional keyboard key to open settings. `nil` = no keybind

## Player Settings Permissions

**shared/config.lua**

```lua
Config.PlayerSettings = {
    EnableSettingsCommand = true,
    AllowFontChange       = true,
    AllowAnimationChange  = true,
    AllowSoundToggle      = true,
    AllowStreetNameToggle = true,
    AllowCoordsToggle     = true,
    AllowIconToggle       = true,
}
```

- `EnableSettingsCommand`: Allow the `/zonesettings` command
- `AllowFontChange`: Let players change the display font
- `AllowAnimationChange`: Let players change the animation style
- `AllowSoundToggle`: Let players toggle sound effects
- `AllowStreetNameToggle`: Let players toggle street name display
- `AllowCoordsToggle`: Let players toggle coordinate display
- `AllowIconToggle`: Let players toggle zone icon display