# Developer

> Developer API reference for ML Climatic Vitals

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

## Overview

`ml_climaticvitals` has client exports for reading temperature data and toggling the system, plus `open/` folder with empty OpenClient/OpenServer tables reserved for your own code. Vehicle climate state syncs via entity StateBags. Server-side: temperature calculation, weather sync, DB persistence, item confirmation (zero-trust, server computes all damage/stat values, never trusts client).

## Client Exports

### Temperature Data

- `GetPerceivedTemperature()`: Returns the current perceived temperature (number, Celsius). Includes all modifiers
- `GetCurrentTemperature()`: Returns the current ambient/server temperature (number, Celsius). Raw weather-based value
- `GetState()`: Returns a table with the full system state:

```lua
{
    perceived = 22.0,      -- Perceived temperature (Celsius)
    current = 20.0,        -- Ambient temperature (Celsius)
    weather = 'CLEAR',     -- Current weather type string
    nearHeat = false,      -- Near a heat/cold source object
    inVehicle = false,     -- In a vehicle with insulation
    inInterior = false,    -- Inside an MLO/interior
    wetness = 0.0,         -- Wetness level (0.0 to 1.0)
    itemBuff = 0.0,        -- Active item buff modifier
}
```

### UI Control

- `hideweatherhud(hide)`: Hide or show the temperature HUD widget. `true` = hide, `false` = show. Blocked when `Config.ForceShowWidget = true`
- `HideUi(shouldHide)`: Alias for `hideweatherhud`
- `OpenClimateMenu()`: Opens the vehicle climate control UI. Only works in a valid vehicle with the engine running

### System Control

- `SetClimaticState(state)`: Enable or disable the entire system. `true` = active, `false` = paused. When paused: HUD hides, visual effects clear, damage stops, temperature updates stop

### Buffs

- `ApplyBuff(buffAmount, durationMinutes)`: Apply a local temperature buff. `buffAmount` is degrees (positive = warm, negative = cool), `durationMinutes` is duration in minutes. Client-side only, does not sync to server

## StateBags

### Vehicle Climate State

Climate control state is stored on the vehicle entity:

```lua
Entity(vehicle).state.climateState = {
    on = true,          -- Climate system on/off
    temp = 21.0,        -- Target temperature
    fan = 1,            -- Fan speed level (0-3)
    mode = 'auto'       -- 'auto', 'heat', or 'ac'
}
```

All vehicle occupants read this StateBag. The driver sends updates to the server via `ml_climaticvitals:server:updateClimateState`. The server validates: entity existence, player proximity (10 units), data types, and clamps temp/fan/mode to valid ranges before writing the StateBag.

## Server Events

- `ml_climaticvitals:getInitialTemperature`: Client requests current temperature on join
- `ml_climaticvitals:server:setWeather`: Weather reporter client sends the current weather name. Accepted only from the assigned reporter
- `ml_climaticvitals:server:updateClimateState`: Client sends vehicle climate changes. Server validates before writing StateBag
- `ml_climaticvitals:server:ApplyStatusDamage`: Client sends condition string (`'hot'`/`'cold'`). Server computes actual hunger/thirst values from config and applies them via `Bridge.SetHunger`/`Bridge.SetThirst`. Rate-limited to 10 seconds per player
- `ml_climaticvitals:server:confirmItemUse`: Client confirms item consumption after progress bar completes. Server verifies inventory, removes 1 item, applies buff via client event. Protected with `GetInvokingResource()` check

## Client Events

- `ml_climaticvitals:updateTemperature`: Server broadcasts ambient temperature and weather type
- `ml_climaticvitals:client:setAsWeatherReporter`: Server assigns a client as weather reporter
- `ml_climaticvitals:client:useItem`: Server triggers item consumption flow. Client shows progress bar, then confirms back to server
- `ml_climaticvitals:client:applyBuff`: Server applies a buff after item confirmation. Receives `buffAmount` and `durationMs`
- `ml_climaticvitals:client:notifyItemBuff`: Server sends item notification after confirmation
- `ml_climaticvitals:client:playerReady`: Internal event fired when the player is fully loaded

All `RegisterNetEvent` handlers include `GetInvokingResource()` checks to prevent server-side event spoofing.

## Temperature Calculation

The perceived temperature formula:

```lua
basePerceived = ambient
    + zoneModifier
    + clothesThermalBonus
    + temperatureObjectBonus
    + vehicleClimateModifier
    + vehicleInsulationBonus
    + nightTimeMalus (-4 between 21:00-06:00)
    + wetnessMalus (wetness * Config.Wetness.TemperatureMalus)
    + waterMalus (Config.PlayerOnWater.TempMalus when swimming)
    + itemBuff

interiorMod = (Config.InteriorBonus.targetTemp - basePerceived) * Config.InteriorBonus.strength

perceived = basePerceived + interiorMod
```

The interior mod pulls perceived temp towards `targetTemp`: warms you if it's cold, cools you if it's hot.

## Weather Reporter System

One client is designated as the weather reporter and polls `GetPrevWeatherTypeHashName()` every 5 seconds. When the reporter disconnects, the server reassigns after 1 second. Only the assigned reporter's weather updates are accepted.

## Item Use Flow

1. Server registers all `Config.ItemBuffs` items as usable via `Bridge.BindUsableItem`
2. Player uses item → server checks `Bridge.HasItem` → triggers `ml_climaticvitals:client:useItem`
3. Client shows `lib.progressBar` with animation/prop
4. On progress bar completion → client triggers `ml_climaticvitals:server:confirmItemUse`
5. Server re-checks `Bridge.HasItem`, removes 1 item, triggers buff on client

Item is removed server-side only after client confirms progress bar completion. Cancelling the progress bar does not remove the item.

## Examples

**Read Temperature from Another Script**

```lua
-- Client-side
local state = exports.ml_climaticvitals:GetState()
print(('Perceived: %.1f, Weather: %s, Wetness: %.0f%%'):format(
    state.perceived, state.weather, state.wetness * 100
))
```

**Hide HUD During Cutscenes**

```lua
-- Client-side
exports.ml_climaticvitals:hideweatherhud(true)  -- hide
exports.ml_climaticvitals:hideweatherhud(false) -- show
```

**Pause System During Minigame**

```lua
-- Client-side
exports.ml_climaticvitals:SetClimaticState(false) -- pause
-- ...minigame logic...
exports.ml_climaticvitals:SetClimaticState(true)  -- resume
```

**Apply a Local Buff from Another Script**

```lua
-- Client-side: cool the local player by 10 degrees for 5 minutes
exports.ml_climaticvitals:ApplyBuff(-10.0, 5)
```