Configuration

Overview

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

Debug & Language

1Config.DebugMode = false
2Config.Language = 'en'

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

Entry Messages & Loading

1Config.RandomEntryMessages = true
2Config.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

1Config.UseNativeZones = true
2Config.ZoneCooldownMinutes = 5
3Config.DisabledZones = {
4    JAIL = true,
5    CHIL = true,
6}

• 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

1Config.Theme = 'default'
2Config.AnimationStyle = 'typewriter'
3Config.ShowStreetName = true
4Config.ShowCoordinates = false
5Config.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

1Config.UseSoundEffect = true
2Config.ThemeSounds = {
3    default   = 'typewriter.mp3',
4    wasteland = 'typewriter.mp3',
5    cyberpunk = 'typewriter.mp3',
6    noir      = 'typewriter.mp3',
7    fantasy   = 'typewriter.mp3',
8}
9Config.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

1Config.ZoneSounds = {
2    BEACH = 'typewriter.mp3',
3    AIRP  = 'typewriter.mp3',
4}

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

Time Display

1Config.SeeDate = true
2Config.SeeYear = true
3Config.SeeTime = true
4Config.UseGameTime = false
5Config.TimezoneOffset = nil
6Config.FixedYear = nil
7Config.DateOffsetYears = 0
8Config.DateOffsetMonths = 0
9Config.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

1Config.EnableVisitTracking = true
2Config.ShowVisitCount = true
3Config.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

1Config.ShowPermanentSubtitleWithZone = true

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

UI Customization

1Config.UI = {
2    TextColor        = '#FFFFFF',
3    TextShadow       = true,
4    TextShadowColor  = '#000000',
5    FontFamily       = "'Courier New', Courier, monospace",
6    FontSizeLocation = '24px',
7    FontSizeDateTime = '20px',
8    FontSizeSubtitle = '18px',
9    FontWeight       = 'bold',
10    TextTransform    = 'none',
11}

• 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

1Config.CustomFontUrl = nil
2Config.EnableCustomFontUI = true
3Config.AvailableFonts = {
4    { name = 'Courier New', value = "'Courier New', Courier, monospace" },
5    { name = 'Roboto Mono', value = "'Roboto Mono', monospace" },
6    -- ...
7}

• 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

1Config.ZoneLabels = {
2    AIRP = 'Los Santos International Airport',
3    ALAMO = 'Alamo Sea',
4    ALTA = 'Alta',
5    -- 74+ zone entries
6}
7
8Config.ZoneIcons = {
9    AIRP = 'fa-plane',
10    ALAMO = 'fa-water',
11    ALTA = 'fa-building',
12    -- matching icons
13}

• 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

1Config.Locations = {
2    {
3        type = 'sphere',
4        label = 'My Custom Area',
5        coords = vector3(100.0, 200.0, 30.0),
6        radius = 30.0,
7    },
8    {
9        type = 'box',
10        label = 'Warehouse',
11        coords = vector3(500.0, -200.0, 40.0),
12        size = vector3(20.0, 30.0, 10.0),
13        rotation = 45,
14    },
15    {
16        type = 'poly',
17        label = 'Farm Area',
18        points = {
19            vec3(100.0, 100.0, 30.0),
20            vec3(200.0, 100.0, 30.0),
21            vec3(200.0, 200.0, 30.0),
22            vec3(100.0, 200.0, 30.0),
23        },
24        thickness = 5.0,
25    },
26}

• 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

1Config.CommandSettings = 'zonesettings'
2Config.CommandZoneName = 'viewzonename'
3Config.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

1Config.PlayerSettings = {
2    EnableSettingsCommand = true,
3    AllowFontChange       = true,
4    AllowAnimationChange  = true,
5    AllowSoundToggle      = true,
6    AllowStreetNameToggle = true,
7    AllowCoordsToggle     = true,
8    AllowIconToggle       = true,
9}

• 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