# Configuration

> Configuration reference for ML Climatic Vitals

Category: CLIMATIC VITALS · Source: https://miciomods.it/docs/ml-climaticvitals-configuration · Last updated: 2026-07-09

## Overview

- `shared/config.lua`: All settings in a single file

Weather temperature values define the "ambient" temperature. The "perceived" temperature is what the player feels after all modifiers stack.

## General

**shared/config.lua**

```lua
Config.Debug = false
Config.Locale = 'en'
Config.ForceShowWidget = true
Config.DefaultUnit = 'C'
Config.RequiredItem = false

Config.Widget = {
    DefaultScale = 1.0,    -- Initial scale for new players (0.5 = half, 2.0 = double)
    LockPosition = false,  -- Force one position+scale for every player
    LockedLeft   = '25px', -- CSS left when locked (px or %)
    LockedTop    = '25px', -- CSS top when locked  (px or %)
    LockedScale  = 1.0,    -- Scale when locked
}
```

- `Debug`: Prints state info to console. Enables the `/tempclothes` debug command
- `Locale`: Language code for translations
- `ForceShowWidget`: When `true` (the default), the temperature HUD stays visible even when `ml_hud` or other scripts try to hide it via the `hideweatherhud` export
- `DefaultUnit`: Default temperature unit. `'C'` for Celsius, `'F'` for Fahrenheit. Players can toggle with `/tempunit`; their choice persists via KVP
- `RequiredItem`: Item name required in inventory to see the HUD. Set to `false` for always visible. Example: `'survival_watch'`
- `Widget.DefaultScale`: Initial HUD scale for new players. `1.0` = normal, `0.5` = half, `2.0` = double
- `Widget.LockPosition`: When `true`, every player sees the HUD at the locked position/scale below and `/movetempui` is disabled
- `Widget.LockedLeft` / `Widget.LockedTop`: CSS `left`/`top` position when locked (px or %)
- `Widget.LockedScale`: HUD scale applied when `LockPosition = true`

## Commands

**shared/config.lua**

```lua
Config.Commands = {
    moveUI = 'movetempui',
    toggleUnit = 'tempunit',
    hideHud = 'hidetemphud',
    debugClothes = 'tempclothes',
}
```

- `moveUI`: Opens drag mode to reposition the HUD widget. Press ESC to save and exit
- `toggleUnit`: Toggles between Celsius and Fahrenheit. Persists per player via KVP
- `hideHud`: Toggles the temperature HUD on/off
- `debugClothes`: Prints current clothing drawable IDs and thermal bonuses to F8 console. Only active when `Config.Debug = true`

## Sync & Persistence

**shared/config.lua**

```lua
Config.SyncInterval = 30000
Config.EnableDB = true
Config.ForceLoadOnRestart = true
Config.ForceLoadTimer = 1000
Config.RequireGameplayReadyGate = false
```

- `SyncInterval`: Milliseconds between server temperature sync cycles. Keep at 30000 or higher
- `EnableDB`: Save temperature to database between restarts. Requires `oxmysql`
- `ForceLoadOnRestart`: Force player state reload when the resource restarts mid-session
- `ForceLoadTimer`: Delay in ms before checking player state on resource restart
- `RequireGameplayReadyGate`: Optional spawn gate. Leave `false` (default) and the system starts on the framework player-load event (`Bridge.IsPlayerLoaded`), which works standalone with no extra dependency. Set `true` only if your spawn resource (e.g. `ml_start`) sets the player's `gameplayReady` state after spawn; the HUD then waits for that signal instead

## Temperature & Weather

**shared/config.lua**

```lua
Config.DefaultTemperature = 22.0
Config.MinTemperature = -35.0
Config.MaxTemperature = 55.0
Config.MaxTempChangePerCycle = 0.1
Config.TempVariation = 0.05
```

- `DefaultTemperature`: Starting temperature when the database is empty or disabled
- `MinTemperature`: Absolute minimum temperature
- `MaxTemperature`: Absolute maximum temperature
- `MaxTempChangePerCycle`: Maximum degrees the ambient temperature shifts per sync cycle. Lower = smoother transitions
- `TempVariation`: Random fluctuation added each cycle

### Weather Map

**shared/config.lua**

```lua
Config.WeatherTemperature = {
    ["EXTRASUNNY"] = { base = 32.0, min = 28.0, max = 38.0 },
    ["CLEAR"]      = { base = 26.0, min = 20.0, max = 32.0 },
    ["SMOG"]       = { base = 28.0, min = 22.0, max = 34.0 },
    ["NEUTRAL"]    = { base = 22.0, min = 15.0, max = 25.0 },
    ["CLOUDS"]     = { base = 18.0, min = 12.0, max = 22.0 },
    ["CLEARING"]   = { base = 20.0, min = 15.0, max = 24.0 },
    ["OVERCAST"]   = { base = 16.0, min = 10.0, max = 20.0 },
    ["RAIN"]       = { base = 14.0, min = 8.0, max = 18.0 },
    ["THUNDER"]    = { base = 12.0, min = 6.0, max = 16.0 },
    ["FOGGY"]      = { base = 10.0, min = 5.0, max = 15.0 },
    ["SNOWLIGHT"]  = { base = 0.0, min = -5.0, max = 5.0 },
    ["SNOW"]       = { base = -4.0, min = -10.0, max = 2.0 },
    ["XMAS"]       = { base = -6.0, min = -12.0, max = 0.0 },
    ["BLIZZARD"]   = { base = -15.0, min = -30.0, max = -5.0 },
    ["HALLOWEEN"]  = { base = 13.0, min = 5.0, max = 20.0 },
}
```

Each weather type defines:

- `base`: Target temperature the system drifts towards
- `min` / `max`: Range within which temperature fluctuates

These are ambient temperatures. Perceived temperature differs based on all player-specific modifiers.

## Damage & Survival

**shared/config.lua**

```lua
Config.EnableDamageSystem = true
Config.DamageInterval = 15000
```

- `EnableDamageSystem`: Apply health damage at extreme temperatures
- `DamageInterval`: Milliseconds between damage ticks

### Thresholds & Values

**shared/config.lua**

```lua
Config.DamageThresholds = {
    hot = 42.0,
    cold = -5.0
}

Config.DamageValues = {
    hot = 5,
    cold = 5
}
```

- `DamageThresholds.hot`: Perceived temperature above this triggers heatstroke damage
- `DamageThresholds.cold`: Perceived temperature below this triggers hypothermia damage
- `DamageValues.hot`: Health points removed per tick from heat
- `DamageValues.cold`: Health points removed per tick from cold

### Status Degradation

**shared/config.lua**

```lua
Config.StatusDamage = {
    Enabled = true,
    HungerRemoveCold = 2.0,
    ThirstRemoveCold = 0.5,
    HungerRemoveHot = 0.5,
    ThirstRemoveHot = 4.0
}
```

- `Enabled`: Drain hunger/thirst at extreme temperatures
- `HungerRemoveCold`: Hunger drain per tick in cold (body burns calories)
- `ThirstRemoveCold`: Thirst drain per tick in cold
- `HungerRemoveHot`: Hunger drain per tick in heat
- `ThirstRemoveHot`: Thirst drain per tick in heat (sweating)

Status damage is computed server-side from config values (zero-trust). Client sends only the condition string (`'hot'`/`'cold'`), server applies a 10-second per-player rate limit.

### Visual Effects

**shared/config.lua**

```lua
Config.EnableVisualEffects = true
Config.Intensity = {
    start = 0.2,
    max = 0.8,
    increment = 0.05
}
```

- `EnableVisualEffects`: Show screen vignette effects at extreme temperatures
- `Intensity.start`: Initial effect intensity when entering danger zone
- `Intensity.max`: Maximum intensity cap (0.8 keeps gameplay usable)
- `Intensity.increment`: How much intensity increases per damage tick

## Wetness & Water

**shared/config.lua**

```lua
Config.EnableWetnessSystem = true
Config.Wetness = {
    IncreaseRate = 0.05,
    DecreaseRate = 0.005,
    HeatSourceDryRate = 0.08,
    TemperatureMalus = -8.0,
    ExposedVehicleClasses = {
        [8] = true,   -- Motorcycles
        [13] = true,  -- Cycles
        [14] = true,  -- Boats
    }
}
```

- `IncreaseRate`: How fast the player gets wet in rain
- `DecreaseRate`: Normal drying rate
- `HeatSourceDryRate`: Drying rate near fire/heat sources
- `TemperatureMalus`: Perceived temperature penalty at 100% wetness. Scales linearly
- `ExposedVehicleClasses`: Vehicle classes that do not protect from rain

### Swimming

**shared/config.lua**

```lua
Config.PlayerOnWater = {
    Enabled = true,
    TempMalus = -15.0,
    WetnessIncrease = 0.05
}
```

- `Enabled`: Apply temperature penalty when swimming
- `TempMalus`: Instant perceived temperature reduction while in water
- `WetnessIncrease`: Wetness increase rate while swimming

## Vehicle Climate Control

### Keybind

**shared/config.lua**

```lua
Config.Keybinds = {
    climateControl = {
        defaultKey = 'J',
        description = 'Open Vehicle Climate Control'
    }
}
```

- `defaultKey`: Default key to open climate panel. Rebindable via FiveM keybind settings
- `description`: Label shown in FiveM keybind menu

### Climate Settings

**shared/config.lua**

```lua
Config.VehicleClimate = {
    defaultTemp = 21.0,
    defaultMode = 'auto',
    minTemp = 16.0,
    maxTemp = 28.0,
    tempChangeStep = 0.5,
    efficiency = 1.0,
    dryingBonus = 0.08
}
```

- `defaultTemp`: Default target temperature
- `defaultMode`: Default mode: `'auto'`, `'heat'`, or `'ac'`
- `minTemp`: Minimum settable temperature
- `maxTemp`: Maximum settable temperature
- `tempChangeStep`: Temperature step per click
- `efficiency`: Climate control effectiveness. `1.0` = fast. Lower = slower
- `dryingBonus`: Extra drying speed when heater is active

### Blacklist

**shared/config.lua**

```lua
Config.VehicleClimateBlacklist = {
    classes = {
        [8] = true,   -- Motorcycles
        [13] = true,  -- Cycles
        [14] = true,  -- Boats
        [21] = true   -- Trains
    },
    models = {
        [`caddy`] = true,
        [`tractor`] = true
    }
}
```

- `classes`: Vehicle classes without climate control
- `models`: Specific vehicle model hashes without climate control

## Climate UI Themes

**shared/config.lua**

```lua
Config.ClimateThemes = {
    default = 'utility',
    classes = {
        [0] = 'utility',    -- Compacts
        [1] = 'utility',    -- Sedans
        [2] = 'utility',    -- SUVs
        [3] = 'utility',    -- Coupes
        [4] = 'retro',      -- Muscle
        [5] = 'retro',      -- Sports Classics
        [6] = 'minimal',    -- Sports
        [7] = 'luxury',     -- Super
        [9] = 'utility',    -- Off-road
        [10] = 'utility',   -- Industrial
        [11] = 'utility',   -- Utility
        [12] = 'utility',   -- Vans
        [14] = 'utility',   -- Boats
        [15] = 'utility',   -- Helicopters
        [16] = 'utility',   -- Planes
        [17] = 'utility',   -- Service
        [18] = 'utility',   -- Emergency
        [19] = 'utility',   -- Military
        [20] = 'utility',   -- Commercial
        [21] = 'utility',   -- Trains
        [22] = 'minimal'    -- Open Wheel
    },
    models = {
        [`torero`] = 'retro',
        [`zentorno`] = 'luxury',
        [`faggio`] = 'retro',
        [`neon`] = 'luxury',
        [`raiden`] = 'luxury',
        [`cyclone`] = 'luxury',
        [`voltic`] = 'luxury',
        [`tezeract`] = 'luxury',
        [`omnisegt`] = 'luxury'
    }
}
```

Available themes: `'utility'`, `'minimal'`, `'luxury'`, `'retro'`

- `default`: Theme when no class or model match is found
- `classes`: Theme per vehicle class ID
- `models`: Theme override per model hash. Takes priority over class

## Interior Bonus

**shared/config.lua**

```lua
Config.InteriorBonus = {
    targetTemp = 22.0,
    strength = 0.5,
}
```

- `targetTemp`: Target temperature inside MLOs/interiors
- `strength`: Pull strength towards the target. `0.0` = no effect, `1.0` = full pull to target temperature. At `0.5`, the perceived temperature moves halfway between current and target

Works both ways, warms the player when it's cold outside, cools when it's hot.

## Temperature Objects

**shared/config.lua**

```lua
Config.TemperatureObjects = {
    ['prop_beach_fire']          = { radius = 12.0, bonus = 15.0, dynamic = true, force = 1.0 },
    ['prop_hobo_stove_01']       = { radius = 6.0,  bonus = 10.0, dynamic = true, force = 1.0 },
    ['gr_prop_gr_hobo_stove_01'] = { radius = 6.0,  bonus = 10.0, dynamic = true, force = 1.0 },
    ['prop_rub_tyre_01']         = { radius = 8.0,  bonus = 12.0, dynamic = true, force = 1.0 },
    ['prop_fan_01']              = { radius = 4.0,  bonus = -4.0, dynamic = true, force = 2.0 },
    ['v_res_coolingfan']         = { radius = 4.0,  bonus = -3.0, dynamic = true, force = 2.0 },
}
```

Each entry defines a GTA prop that radiates heat or cold:

- `radius`: Detection range in game units
- `bonus`: Temperature modifier. Positive = heat, negative = cold
- `dynamic`: Scale bonus by distance (closer = stronger). When `false`, flat bonus within radius
- `force`: Falloff exponent. Higher = steeper falloff near the edge

## Vehicle Insulation

**shared/config.lua**

```lua
Config.VehicleModifiers = {
    excludeCategories = { 8, 13 },
    categoryBonus = {
        [0] = 3,   -- Compact
        [1] = 4,   -- Sedan
        [2] = 5,   -- SUV
        [18] = 4,  -- Emergency
    },
    hashBonus = {
        [`rhino`] = 10,
        [`firetruk`] = 8,
    }
}
```

- `excludeCategories`: Vehicle classes with zero insulation (bikes, cycles)
- `categoryBonus`: Perceived temperature bonus per vehicle class
- `hashBonus`: Bonus override for specific vehicle model hashes

## Zones & Blips

### Blip Settings

**shared/config.lua**

```lua
Config.BlipSettings = {
    sprite = 441,
    color = { hot = 1, cold = 3, neutral = 2 },
    scale = 0.8,
    shortRange = true,
}
```

- `sprite`: Map blip sprite ID
- `color`: Blip color IDs for hot, cold, and neutral zones
- `scale`: Blip size
- `shortRange`: Only show blip when nearby

### Temperature Zones

**shared/config.lua**

```lua
Config.TemperatureZones = {
    {
        type = 'poly',
        modifier = -10.0,
        points = { vec3(...), vec3(...), ... },
        thickness = 20.0,
        dynamic = true,
        debug = false,
        showNotification = true,
        showBlip = false,
        blipName = "Freezing Zone"
    },
    {
        type = 'box',
        modifier = 15.0,
        coords = vec3(1093.1, -1999.5, 31.0),
        size = vec3(20.0, 20.0, 10.0),
        rotation = 0,
        dynamic = true,
        debug = false,
        showNotification = true,
        showBlip = false,
        blipName = "Heat Zone"
    }
}
```

- `type`: Zone shape: `'poly'`, `'box'`, or `'sphere'`
- `modifier`: Temperature offset. Positive = hotter, negative = colder
- `points`: Array of vec3 vertices (poly type)
- `coords`: Center position (box/sphere types)
- `size`: Dimensions vec3 (box type)
- `radius`: Detection radius (sphere type)
- `rotation`: Box rotation in degrees
- `thickness`: Vertical thickness (poly type)
- `dynamic`: Scale modifier by distance from center (box/sphere)
- `debug`: Draw zone boundaries (ox_lib debug)
- `showNotification`: Notify player on enter/exit
- `showBlip`: Add a map blip at the zone
- `blipName`: Label for the map blip

## Usable Items

**shared/config.lua**

```lua
Config.ItemBuffs = {
    ['coffee'] = {
        buff = 8.0,
        duration = 10,
        notification = "item_buff_bag",
        progressBar = {
            duration = 5000,
            label = 'Drinking Coffee...',
            useWhileDead = false,
            canCancel = true,
            disable = { move = false, car = true, combat = true },
            anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
            prop = { model = `prop_fib_coffee`, pos = vec3(0.01, 0.01, -0.06), rot = vec3(5.0, 5.0, -180.5) }
        }
    },
    ['water'] = {
        buff = -5.0,
        duration = 5,
        notification = "item_buff_icecream",
        progressBar = {
            duration = 3000,
            label = 'Drinking Water...',
            useWhileDead = false,
            canCancel = true,
            disable = { move = false, car = true, combat = true },
            anim = { dict = 'mp_player_intdrink', clip = 'loop_bottle' },
            prop = { model = `prop_ld_flow_bottle`, pos = vec3(0.03, 0.03, 0.02), rot = vec3(0.0, 0.0, -1.5) }
        }
    },
}
```

Each item entry:

- `buff`: Temperature modifier in degrees. Positive = warming, negative = cooling
- `duration`: Buff duration in minutes
- `notification`: Locale key for the notification on buff activation
- `progressBar`: ox_lib progressBar config: `duration` (ms), `label`, `useWhileDead`, `canCancel`, `disable`, `anim`, `prop`

Items are registered as usable via `Bridge.BindUsableItem` on server start. The flow is: server triggers client → client runs progress bar → on completion, client sends `confirmItemUse` back to server → server verifies inventory, removes item, applies buff.

## Clothing Thermal Bonus

**shared/config.lua**

```lua
Config.ClothesBonus = {
    ["male"] = {
        ["hat"]    = { [3] = 1, [5] = 1, ... },
        ["torso"]  = { [17] = 8, [34] = 6, ... },
        ["pants"]  = { [4] = 2, [31] = 2, ... },
        ["shoes"]  = { [12] = 2, [14] = 1, ... },
        ["tops"]   = { [466] = 2, [497] = 7, [15] = -2, [16] = -2 },
        ["undershirt"] = {},
        ["armor"]  = {},
        ["decals"] = {},
    },
    ["female"] = {
        ["hat"] = {}, ["torso"] = {}, ["pants"] = {}, ["shoes"] = {},
        ["undershirt"] = {}, ["armor"] = {}, ["decals"] = {}, ["tops"] = {}
    }
}
```

Maps ped drawable variation IDs to temperature bonuses per clothing slot:

- Positive values = warmth (jackets, boots, winter hats)
- Negative values = cooling (tank tops, light shirts)
- Keys are the drawable variation index from `GetPedDrawableVariation`
- Slots map to ped component IDs: `hat` (0), `torso` (3), `pants` (4), `shoes` (6), `tops` (11), etc.

> **TIP:** Debug Clothes
>
> Enable `Config.Debug` and use `/tempclothes` in-game to see every drawable ID and its thermal bonus for the current ped.