Configuration

Complete configuration reference. All settings are in config.lua and systems/shop/config.lua.

Camera

Config.Camera = {
    fov = 50.0,              -- Field of view
    easeTime = 1000,         -- Camera transition duration (ms)
    distance = 0.9,          -- Camera distance from NPC
    heightOffset = 0.5,      -- Camera height offset
    dof = {
        enabled = true,      -- Depth of field blur
        near = 1.0,
        far = 6.0,
        strength = 1.0
    }
}

Property	Type	Default	Description
`fov`	number	50.0	Camera field of view
`easeTime`	number	1000	Transition animation duration in ms
`distance`	number	0.9	Camera distance from NPC face
`heightOffset`	number	0.5	Camera height relative to NPC
`dof.enabled`	boolean	true	Enable depth of field blur
`dof.near`	number	1.0	Near DOF distance
`dof.far`	number	6.0	Far DOF distance
`dof.strength`	number	1.0	Blur intensity

Interaction

Config.InteractDistance = 2.5     -- Target/E key interaction distance
Config.DrawDistance = 10.0        -- 3D name display distance

Property	Type	Default	Description
`InteractDistance`	number	2.5	Max distance to interact with NPC
`DrawDistance`	number	10.0	Max distance to show NPC name above head

Target System

Config.TargetSystem = 'auto'

Value	Behavior
`'auto'`	Uses ox_target or qb-target if detected, otherwise falls back to E key
`'ekey'`	E key only — ignores target systems entirely
`'ox_target'`	Force ox_target (no E key)
`'qb-target'`	Force qb-target (no E key)

In 'auto' mode, if a target system is detected, E key is disabled — only the target system is used. E key only activates as a fallback when no target resource is running.

Typing Effect

Config.TypingSpeed = 80           -- ms per word

Controls how fast dialog text types out. Lower = faster. Range: 15–200.

Sound Effects

Config.Sounds = {
    open    = { name = 'BACK',                   set = 'HUD_AMMO_SHOP_SOUNDSET' },
    close   = { name = 'BACK',                   set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    select  = { name = 'SELECT',                 set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    hover   = { name = 'NAV_UP_DOWN',            set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    typing  = { name = 'HIGHLIGHT_NAV_UP_DOWN',  set = 'HUD_FRONTEND_DEFAULT_SOUNDSET' }
}

Each sound uses GTA V native PlaySoundFrontend. Set any entry to nil to disable that sound.

Pre-registered NPCs

Define NPCs directly in config. These spawn automatically on resource start.

Config.NPCs = {
    {
        id = 'mechanic',               -- Unique ID (required)
        name = 'Mechanic',             -- Display name (required)
        subtitle = 'Vehicle Repair',   -- Subtitle text (optional)
        model = 'a_m_y_mechanic_02',   -- Ped model (required)
        coords = vector4(-339.0, -134.0, 39.0, 180.0),  -- Position + heading (required)
        greeting = 'Hey! Need a repair?',                -- Dialog text (optional)

        -- Animation (choose one):
        animation = { dict = 'mini@repair', clip = 'idle_a', flag = 49 },
        -- scenario = 'WORLD_HUMAN_WELDING',

        -- Blip (optional):
        blip = {
            enabled = true,
            sprite = 446,
            color = 5,
            scale = 0.8,
            label = 'Mechanic'
        },

        -- Dialog options:
        options = {
            { label = 'Repair Vehicle', type = 'client', event = 'myresource:repair', icon = '🔧' },
            { label = 'Buy Parts',      type = 'server', event = 'myresource:buyParts', args = { 'engine' } },
            { label = 'Ask about job',  response = 'We fix cars here. Interested?' },
            { label = 'Nevermind',       type = 'close' },
        }
    }
}

NPC Properties

Property	Type	Required	Description
`id`	string	✅	Unique identifier
`name`	string	✅	Display name (shown above head & in dialog)
`model`	string	✅	Ped model name or hash
`coords`	vector4	✅	Position (x, y, z) + heading (w)
`subtitle`	string	❌	Subtitle in dialog header
`greeting`	string	❌	Initial dialog text
`animation`	table	❌	`{ dict, clip, flag }`
`scenario`	string	❌	GTA scenario name (alternative to animation)
`blip`	table	❌	`{ enabled, sprite, color, scale, label, category }`
`targetLabel`	string	❌	Custom label for target eye (default: NPC name)
`targetIcon`	string	❌	Custom icon for target eye (default: `fas fa-comment`)
`options`	table	❌	Array of dialog options

Option Properties

Property	Type	Description
`label`	string	Button text (required)
`icon`	string	Emoji or icon (optional)
`type`	string	`'client'`, `'server'`, or `'close'`
`event`	string	Event name to trigger
`args`	table	Arguments passed to the event
`response`	string	Show response text instead of triggering event
`action`	string	Custom action (e.g. `'openShop'` to open linked shop)
`close`	boolean	Set `false` to keep dialog open after event (default: `true`)

Shop System

Shop settings are in systems/shop/config.lua.

Global Settings

Config.Shop = {
    MaxBuyAmount  = 100,    -- Max quantity per purchase
    MaxSellAmount = 100,    -- Max quantity per sell
}

Shop NPCs

Define shop NPCs that spawn automatically with linked shops:

Config.ShopNPCs = {
    {
        id       = 'general_store_1',
        name     = 'Shop Clerk',
        subtitle = 'General Store',
        model    = 'mp_m_shopkeep_01',
        coords   = vector4(25.7, -1347.3, 29.5, 271.0),
        scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
        greeting = 'Welcome! Browse our goods.',
        blip = {
            enabled = true,
            sprite  = 52,
            color   = 2,
            scale   = 0.6,
            label   = 'General Store',
        },
        shop = {
            title    = 'General Store',
            subtitle = '24/7',
            buyItems = {
                { name = 'water',    label = 'Water',    price = 10 },
                { name = 'sandwich', label = 'Sandwich', price = 15 },
                { name = 'bandage',  label = 'Bandage',  price = 100 },
            },
            sellItems = {},
        },
    },
}

Shop NPC Properties

Property	Type	Required	Description
`id`	string	✅	Unique identifier (also used as shop ID)
`name`	string	✅	NPC display name
`model`	string	✅	Ped model
`coords`	vector4	✅	Position + heading
`subtitle`	string	❌	Dialog subtitle
`greeting`	string	❌	Dialog greeting text
`scenario`	string	❌	GTA scenario
`blip`	table	❌	Map blip config
`shop`	table	✅	Shop data (see below)

Shop Data Properties

Property	Type	Description
`title`	string	Shop panel title
`subtitle`	string	Shop panel subtitle
`buyItems`	table	Array of items players can buy
`sellItems`	table	Array of items players can sell

Item Properties

Property	Type	Description
`name`	string	Item spawn name (must match inventory)
`label`	string	Display name in shop UI
`price`	number	Price per unit