Environment

The utils.environment module contains a small amount of wrapper functions and a few custom functions to provide a little more ease of development for things involving environmental factors.

Functions

get_weather_name()

Retrieves a human readable name for a weather type.

Function

local function get_weather_name(hash)
    local weather_names = {
        [GetHashKey('EXTRASUNNY')] = 'EXTRASUNNY',
        [GetHashKey('CLEAR')] = 'CLEAR',
        [GetHashKey('CLOUDS')] = 'CLOUDS',
        [GetHashKey('OVERCAST')] = 'OVERCAST',
        [GetHashKey('RAIN')] = 'RAIN',
        [GetHashKey('THUNDER')] = 'THUNDER',
        [GetHashKey('CLEARING')] = 'CLEARING',
        [GetHashKey('NEUTRAL')] = 'NEUTRAL',
        [GetHashKey('SNOW')] = 'SNOW',
        [GetHashKey('BLIZZARD')] = 'BLIZZARD',
        [GetHashKey('SNOWLIGHT')] = 'SNOWLIGHT',
        [GetHashKey('XMAS')] = 'XMAS'
    }
    return weather_names[hash] or 'UNKNOWN'
end

exports('environment_get_weather_name', get_weather_name)
utils.environment.get_weather_name = get_weather_name

Example

--- Retreive weather name.
local weather_name = utils.environment.get_weather_name('CLEAR')

get_game_time()

Retrieves current game time and its formatted version.

Function

local function get_game_time()
    local hour = GetClockHours()
    local minute = GetClockMinutes()
    return {
        time = {hour = hour, minute = minute},
        formatted = string.format('%02d:%02d', hour, minute)
    }
end

exports('environment_get_game_time', get_game_time)
utils.environment.get_game_time = get_game_time

Example

--- Retrieve time data.
local data = utils.environment.get_game_time()

--- Print the hour and mins.
print('Hour:', data.time.hour, 'Min:', data.time.min)

--- Print formatted game time.
print('Formatted:', data.formatted)

get_game_date()

Retrieves current game date and its formatted version.

Function

local function get_game_date()
    local day = GetClockDayOfMonth()
    local month = GetClockMonth()
    local year = GetClockYear()
    return {
        date = {day = day, month = month, year = year},
        formatted = string.format('%02d/%02d/%04d', day, month, year)
    }
end

exports('environment_get_game_date', get_game_date)
utils.environment.get_game_date = get_game_date

Example

--- Retrieve time data.
local data = utils.environment.get_game_date()

--- Print the date.
print('Day:', data.date.day, 'Month:', data.time.month, 'Year:', data.time.year)

--- Print formatted date.
print('Formatted:', data.formatted)

set_weather()

Wrapper function for set weather type native.

Function

local function set_weather(weather)
    SetWeatherTypeOvertimePersist(weather, 1.0)
end

exports('environment_set_weather', set_weather)
utils.environment.set_weather = set_weather

Example

--- Set weather to clear.
utils.environment.set_weather('CLEAR')

set_game_time()

Wrapper function for override clock time native.

Function

local function set_game_time(hour, minute)
    NetworkOverrideClockTime(hour, minute, 0)
end

exports('environment_set_game_time', set_game_time)
utils.environment.set_game_time = set_game_time

Example

--- Set game time to 12:00
utils.environment.set_game_time(12, 0)

get_wind_speed()

Wrapper function for get wind speed native.

Function

local function get_wind_speed()
    return GetWindSpeed()
end

exports('environment_get_wind_speed', get_wind_speed)
utils.environment.get_wind_speed = get_wind_speed

Example

--- Retrieve current wind direction.
local wind_direction = utils.environment.get_wind_direction()

set_wind_speed()

Wrapper function for set wind speed native.

Function

local function set_wind_speed(speed)
    SetWindSpeed(speed)
end

exports('environment_set_wind_speed', set_wind_speed)
utils.environment.set_wind_speed = set_wind_speed

Example

--- Set wind direction to provided coords.
utils.environment.set_wind_direction(vector3(1.0, 0.0, 0.0))

get_sunrise_sunset_times()

Retrieves the sunrise and sunset times based on the weather type.

These times are not 100% accurate, they can be adjusted to reflect real in game values if required.

Function

local function get_sunrise_sunset_times(weather)
    local times = {
        CLEAR = {sunrise = '06:00', sunset = '18:00'},
        CLOUDS = {sunrise = '06:15', sunset = '17:45'},
        OVERCAST = {sunrise = '06:30', sunset = '17:30'},
        RAIN = {sunrise = '07:00', sunset = '17:00'},
        THUNDER = {sunrise = '07:00', sunset = '17:00'},
        SNOW = {sunrise = '08:00', sunset = '16:00'},
        BLIZZARD = {sunrise = '09:00', sunset = '15:00'},
    }
    return times[weather] or {sunrise = '06:00', sunset = '18:00'}
end

exports('environment_get_sunrise_sunset_times', get_sunrise_sunset_times)
utils.environment.get_sunrise_sunset_times = get_sunrise_sunset_times

Example

--- Retrieve sunrise and sunset times for next weather type.
local times = utils.environment.get_sunrise_sunset_times(GetNextWeatherTypeHashName())

--- Print times
print('Sunrise:', times.sunrise, 'Sunset:', times.sunset)

is_daytime()

Checks if current time of day is considered day time.

Function

local function is_daytime()
    local hour = GetClockHours()
    return hour >= 6 and hour < 18
end

exports('environment_is_daytime', is_daytime)
utils.environment.is_daytime = is_daytime

Example

--- Retreive boolean value for is daytime.
local is_day = utils.environment.is_daytime()

--- Print true | false result
print('Is day:', tostring(is_day))

get_current_season()

Retrieves current season based on in game date.

Function

local function get_current_season()
    local month = GetClockMonth()
    if month >= 3 and month <= 5 then
        return 'Spring'
    elseif month >= 6 and month <= 8 then
        return 'Summer'
    elseif month >= 9 and month <= 11 then
        return 'Autumn'
    else
        return 'Winter'
    end
end

exports('environment_get_current_season', get_current_season)
utils.environment.get_current_season = get_current_season

Example

--- Retrieve current season.
local season = utils.environment.get_current_season()

--- Print current season.
print('Season:', season)

get_distance_to_water()

Get distance from player to nearest body of water.

Function

local function get_distance_to_water()
    local player_coords = GetEntityCoords(PlayerPedId())
    local water_test_result, water_height = TestVerticalProbeAgainstAllWater(player_coords.x, player_coords.y, player_coords.z, 0)
    if water_test_result then
        return #(player_coords - vector3(player_coords.x, player_coords.y, water_height))
    else
        return -1
    end
end

exports('environment_get_distance_to_water', get_distance_to_water)
utils.environment.get_distance_to_water = get_distance_to_water

Example

--- Retreive distance.
local distance_to_water = utils.water.get_distance_to_water()

--- Print distance.
print('Distance:', distance_to_water)

get_water_height_at_coords()

Get the water height at a specific location.

Function

local function get_water_height_at_coords(coords)
    local water_test_result, water_height = GetWaterHeight(coords.x, coords.y, coords.z)
    if water_test_result then
        return water_height
    else
        return -1
    end
end

exports('environment_get_water_height_at_coords', get_water_height_at_coords)
utils.environment.get_water_height_at_coords = get_water_height_at_coords

Example

--- Retreive water height at specified coords.
local water_height = utils.water.get_water_height_at_coords(vector3(0, 0, 0))

--- Print water height.
print('Height:', water_height)

get_environment_details()

Retrieves comprehensive environments details.

Function

local function get_environment_details()
    local weather_hash = GetPrevWeatherTypeHashName()
    local weather_name = get_weather_name(weather_hash)
    local game_time = get_game_time()
    local game_date = get_game_date()
    local current_season = get_current_season()
    local sunrise_sunset_times = get_sunrise_sunset_times(weather_name)
    local wind_speed = get_wind_speed()
    local wind_direction = get_wind_direction()
    local is_daytime_now = is_daytime()
    local distance_to_water = get_distance_to_water()
    return {
        weather = weather_name,
        time = game_time,
        date = game_date,
        season = current_season,
        sunrise = sunrise_sunset_times.sunrise,
        sunset = sunrise_sunset_times.sunset,
        wind_speed = wind_speed,
        wind_direction = wind_direction,
        is_daytime = is_daytime_now,
        distance_to_water = distance_to_water
    }
end

exports('environment_get_environment_details', get_environment_details)
utils.environment.get_environment_details = get_environment_details

Example

--- Retrieve environment details.
local env_details = utils.environment.get_environment_details()

--- Print the entire table of data.
utils.tables.print_table(env_details)