BLN Studio Docs

Appearance

✨ BLN HUD/Metabolism System ​

bln hud

📺 Preview ​

Video Preview

💰 Buy Now ​

Get it now

Introducing BLN HUD/Metabolism System - the most comprehensive and feature-rich HUD solution for RedM! This isn't just another simple status display - it's a complete immersive survival and roleplaying system that transforms how players experience your server.

✨ Why Choose BLN HUD System? ​

  • 🎯 Complete Metabolism System - Advanced hunger, thirst, and stress mechanics with realistic drain rates
  • 🌡️ Dynamic Temperature System - Weather-aware temperature with clothing modifiers and environmental effects
  • 💪 Core Management - Full player & horse health/stamina cores with golden boost system
  • 🎨 In-Game Visual Editor - Drag-and-drop positioning with live preview - no file editing needed!
  • 🔧 Advanced Usable Items - 30+ pre-configured items with custom animations and effects
  • 📊 Smart Population Display - Real-time server population indicator (OneSync compatible)
  • 🎙️ Voice Integration - Works with Mumble & SaltyChat with visual indicators
  • 🚫 Native Core Replacement - Completely replaces game's default cores for consistency
  • ⚡ Zero Performance Impact - Optimized to 0.00ms resmon usage
  • 🗃️ Database Persistence - All player stats save automatically to prevent data loss
  • 🤢 Poison & Antidote System - Snake bites, poison effects, and curing mechanics
  • 🍺 Alcohol & Intoxication - Realistic drunk effects with visual impairment
  • 🦠 Dirt & Hygiene System - Progressive dirtiness with cleaning mechanics

🎨 Visual Features ​

📱 In-Game HUD Editor ​

  • Drag & Drop Positioning - Move any element anywhere on screen
  • Live Preview - See changes in real-time as you edit
  • Size Adjustment - Individual or global size controls
  • Color Customization - Change colors for normal, danger, and gold states
  • Visibility Controls - Show/hide any HUD element
  • Admin Logo Settings - Custom server logo with URL support
  • Reset & Save Functions - Easy configuration management

🎭 Status Indicators ​

  • Player Health & Stamina - Inner/outer cores with visual states
  • Horse Health & Stamina - Full mount status display
  • Hunger & Thirst - Progressive apple and water drop icons
  • Temperature - Dynamic hot/cold visual indicators
  • Voice Status - Multi-range voice indicators with colors
  • Population Counter - Real-time player count display
  • Money Display - Configurable cash counter
  • Time & User ID - Server info elements
  • Poison Indicators - Visual warnings when poisoned
  • Dirt/Hygiene Status - Cleanliness level indicators with fly effects

🧪 Advanced Usable Items System ​

🍽️ Food & Drink Items ​

  • 30+ Pre-configured Items - Bread, apple, coffee, stew, beer, wine, and more
  • Realistic Animations - Proper eating, drinking, and smoking animations
  • Props Support - 3D props appear during consumption
  • Nutritional Values - Each item affects hunger, thirst, stress differently
  • Temperature Effects - Hot coffee warms you, cold water cools you down

💊 Medical & Consumables ​

  • Health Tonics - Boost health cores with golden effects
  • Stamina Tonics - Enhance stamina regeneration
  • Medicine & Stims - Advanced healing items
  • Antidotes - Cure poison and other ailments
  • Soap & Hygiene Items - Clean dirt and restore cleanliness
  • Alcohol & Spirits - Beer, wine, whiskey with intoxication effects
  • Custom Effects - Screen effects and visual feedback

🐎 Horse Care Items ​

  • Horse Feed - Hay, carrots, and other feed items
  • Core Restoration - Restore horse health and stamina
  • Proper Animations - Realistic horse feeding animations
  • Bonding Benefits - Enhance horse-player relationship

🔧 Developer Features ​

📚 Comprehensive API ​

  • 50+ Exports - Control every aspect of the HUD from other resources
  • Event System - React to hunger, thirst, stress, and temperature changes

⚙️ Advanced Configuration ​

  • Granular Settings - Control drain rates, thresholds, and effects
  • Custom Animations - Register your own item animations
  • Conditional Usage - Job locks, item requirements, and custom conditions
  • Return Items - Items that give back containers or byproducts

📊 Performance & Optimization ​

  • 0.00ms Resmon - Incredibly optimized with no performance impact
  • Smart Caching - Efficient data management and updates
  • Minimal Network Usage - Optimized client-server communication
  • Database Efficient - Smart saving intervals prevent database spam
  • Framework Agnostic - Works with any RedM framework

Usable item Animations ​

There are many animation ready to be used for your usable items:

  • eat - Basic eating animation
  • stew - Stew eating animation with bowl and spoon
  • eatCan - Canned food animation
  • drink - Generic drinking animation
  • coffee - Coffee drinking animation
  • smoke - Cigarette smoking animation
  • cigar - Cigar smoking animation
  • pipe - Pipe smoking animation
  • tobacco - Chewing tobacco animation
  • alcohol - Alcohol drinking animation (includes drunk effect)
  • medicine - Medicine drinking animation
  • inject - Injection animation
  • pomade - Hair pomade application animation
  • horsefeed - Feed horse animation
  • horseinject - Horse medicine injection animation
  • horsebrush - Horse brushing animation
  • pocketwatch - Pocket watch animation.

each animation has a pre-configured prop/object modal like Bread, bottle, ...etc. Can be customized using the effects.prop in your item's settings. Everything explaing in the usables config file.

Developer API ​

Getting Started ​

lua
-- Client-side usage examples
exports.bln_hud:AddHunger(20)                    -- Add 20 to hunger
exports.bln_hud:AddThirst(15)                    -- Add 15 to thirst
exports.bln_hud:ReduceStress(10, "relaxing")     -- Reduce stress by 10

-- Server-side usage examples
exports.bln_hud:UseUsableItem(source, "bread")   -- Make player use bread
exports.bln_hud:registerUsableItem("custom_food", {
    hunger = 20,
    thirst = 5,
    effects = { enabled = true, animationName = "eat" }
})

Client Exports ​

GetHunger() ​

Returns current hunger value (0-100).

lua
local hunger = exports.bln_hud:GetHunger()

GetThirst() ​

Returns current thirst value (0-100).

lua
local thirst = exports.bln_hud:GetThirst()

SetHunger(value) ​

Set player's hunger value.

Parameters:

  • value (number): New hunger value (0-100)
lua
exports.bln_hud:SetHunger(75)

SetThirst(value) ​

Set player's thirst value.

Parameters:

  • value (number): New thirst value (0-100)
lua
exports.bln_hud:SetThirst(80)

AddHunger(amount) ​

Add to player's hunger value.

Parameters:

  • amount (number): Amount to add
lua
exports.bln_hud:AddHunger(20)

AddThirst(amount) ​

Add to player's thirst value.

Parameters:

  • amount (number): Amount to add
lua
exports.bln_hud:AddThirst(15)

IsHungry(threshold) ​

Check if player is below hunger threshold.

Parameters:

  • threshold (number, optional): Threshold to check (defaults to Config.Hunger.thresholds.low)
lua
if exports.bln_hud:IsHungry() then
    -- Player is hungry
end

IsThirsty(threshold) ​

Check if player is below thirst threshold.

Parameters:

  • threshold (number, optional): Threshold to check (defaults to Config.Thirst.thresholds.low)
lua
if exports.bln_hud:IsThirsty() then
    -- Player is thirsty
end

GetStressLevel() ​

Returns current stress level (0-100).

lua
local stress = exports.bln_hud:GetStressLevel()

GetComposureLevel() ​

Returns current composure level (inverse of stress, 0-100).

lua
local composure = exports.bln_hud:GetComposureLevel()

SetStressLevel(stressLevel) ​

Set player's stress level.

Parameters:

  • stressLevel (number): New stress level (0-100)
lua
exports.bln_hud:SetStressLevel(25)

AddStress(amount, source) ​

Add stress to player.

Parameters:

  • amount (number): Amount of stress to add
  • source (string, optional): Source/reason for the stress
lua
exports.bln_hud:AddStress(10, "combat")

ReduceStress(amount, source) ​

Reduce player's stress.

Parameters:

  • amount (number): Amount of stress to reduce
  • source (string, optional): Source/reason for the reduction
lua
exports.bln_hud:ReduceStress(15, "meditation")

GetTemperature() ​

Returns current temperature information.

lua
local temp = exports.bln_hud:GetTemperature()
-- Returns: {value = 25, valueWithFormat = "25°C"}

GetTotalTemperatureModifier() ​

Get current temperature modifier from usable items.

lua
local modifier = exports.bln_hud:GetTotalTemperatureModifier()

UpdatePlayerCoreHealth(amount, ped) ​

Modify player inner health core by increasing or decreasing its value.

Parameters:

  • amount (number): Amount to modify (positive to increase, negative to decrease)
  • ped (entity): Player entity
lua
exports.bln_hud:UpdatePlayerCoreHealth(15, PlayerPedId())

UpdatePlayerCoreStamina(amount, ped) ​

Modify player inner stamina core by increasing or decreasing its value.

Parameters:

  • amount (number): Amount to modify (positive to increase, negative to decrease)
  • ped (entity): Player entity
lua
exports.bln_hud:UpdatePlayerCoreStamina(10, PlayerPedId())

UpdateHorseCoreHealth(amount, horse) ​

Modify horse inner health core by increasing or decreasing its value.

Parameters:

  • amount (number): Amount to modify (positive to increase, negative to decrease)
  • horse (entity): Horse entity
lua
exports.bln_hud:UpdateHorseCoreHealth(20, myHorse)

UpdateHorseCoreStamina(amount, horse) ​

Modify horse inner stamina core by increasing or decreasing its value.

Parameters:

  • amount (number): Amount to modify (positive to increase, negative to decrease)
  • horse (entity): Horse entity
lua
exports.bln_hud:UpdateHorseCoreStamina(15, myHorse)

SetOverpower(statName, coreType, duration, ped) ​

Apply temporary boost to core stats.

Parameters:

  • statName (string): 'health' or 'stamina'
  • coreType (string): 'inner', 'outer', or 'both'
  • duration (number): Time in milliseconds
  • ped (entity): Entity to apply boost to
lua
-- Apply 30-second stamina boost
exports.bln_hud:SetOverpower('stamina', 'inner', 30000, PlayerPedId())

RegisterCustomAnimation(name, function) ​

Register a custom animation for usable items.

Parameters:

  • name (string): Animation name
  • function (function): Animation function that receives callback and optional prop model
lua
exports.bln_hud:RegisterCustomAnimation('my_custom_anim', function(callback, propModel)
    local ped = PlayerPedId()
    TaskStartScenarioInPlace(ped, GetHashKey('WORLD_HUMAN_DRINK_CHAMPAGNE'), 5000, true, false, false, false)
    Citizen.Wait(5000)
    ClearPedTasks(ped)
    if callback then callback() end
end)

Player Wash ​

Reset player's dirtiness state, Makes the player clean.

lua
exports.bln_hud:PlayerWash()

IsPoisoned() ​

Check if player is currently poisoned.

lua
local poisoned = exports.bln_hud:IsPoisoned()
if poisoned then
    print("Player is poisoned!")
end

GetPoisonLevel() ​

Returns current poison level (0-100).

lua
local level = exports.bln_hud:GetPoisonLevel()
print("Poison level: " .. level)

CurePoisoning() ​

Cure player's poisoning status.

lua
exports.bln_hud:CurePoisoning()

Server Exports ​

GetHungerThirst(source) ​

Get player's hunger and thirst values.

Parameters:

  • source (number): Player server ID
lua
local stats = exports.bln_hud:GetHungerThirst(source)
-- Returns: {hunger = 75, thirst = 80}

SetHungerThirst(source, hunger, thirst) ​

Set player's hunger and thirst values.

Parameters:

  • source (number): Player server ID
  • hunger (number): New hunger value (0-100)
  • thirst (number): New thirst value (0-100)
lua
exports.bln_hud:SetHungerThirst(source, 80, 75)

SaveHungerThirst(source) ​

Force save player's hunger and thirst to database.

Parameters:

  • source (number): Player server ID
lua
exports.bln_hud:SaveHungerThirst(source)

UseUsableItem(source, itemName) ​

Use a usable item.

Parameters:

  • source (number): Player server ID
  • itemName (string): Item name to use
lua
exports.bln_hud:UseUsableItem(source, 'bread')

registerUsableItem(itemName, itemConfig) ​

Register a new usable item.

Parameters:

  • itemName (string): Item name
  • itemConfig (table): Item configuration
lua
exports.bln_hud:registerUsableItem('my_custom_item', {
    hunger = 15,
    thirst = 5,
    stress = -10,
    player = {
        health = { 5, 0 },
    },
    effects = {
        enabled = true,
        animationName = "eat",
        prop = "p_bread05x"
    }
})

Client Events ​

bln_hud:c:hungerChange ​

Triggered when hunger value changes.

Parameters:

  • hunger (number): New hunger value
lua
AddEventHandler('bln_hud:c:hungerChange', function(hunger)
    print("Hunger changed to: " .. hunger)
end)

bln_hud:c:thirstChange ​

Triggered when thirst value changes.

Parameters:

  • thirst (number): New thirst value
lua
AddEventHandler('bln_hud:c:thirstChange', function(thirst)
    print("Thirst changed to: " .. thirst)
end)

bln_hud:c:stressChange ​

Triggered when stress/composure level changes.

Parameters:

  • composure (number): New composure value (0-100)
  • sources (table): Recent stress sources
lua
AddEventHandler('bln_hud:c:stressChange', function(composure, sources)
    local stress = 100 - composure
    print("Stress level is now: " .. stress)
end)

bln_hud:c:tempChange ​

Triggered when temperature changes.

Parameters:

  • tempData (string): JSON string with temperature data
lua
AddEventHandler('bln_hud:c:tempChange', function(tempData)
    local data = json.decode(tempData)
    print("Temperature is now: " .. data.valueWithFormat)
end)

bln_hud:c:useItem ​

Triggered when an item is being used.

Parameters:

  • itemName (string): Name of the item
  • itemData (table): Configuration of the item
lua
AddEventHandler('bln_hud:c:useItem', function(itemName, itemData)
    print("Using item: " .. itemName)
end)

bln_hud:c:usableItemUsed ​

Triggered after an item has been used.

Parameters:

  • itemName (string): Name of the item
  • itemData (table): Configuration of the item
lua
AddEventHandler('bln_hud:c:usableItemUsed', function(itemName, itemData)
    print("Item used: " .. itemName)
end)

bln_hud:c:getTemperature ​

Request to get temperature (uses callback).

Parameters:

  • callback (function): Function to receive temperature data
lua
TriggerEvent('bln_hud:c:getTemperature', function(temp)
    print("Current temperature: " .. temp.valueWithFormat)
end)

bln_hud:c:setTemperature ​

Set temperature value.

Parameters:

  • tempValue (number): New temperature value
lua
TriggerEvent('bln_hud:c:setTemperature', 25)

bln_hud:UseAntidote ​

Cure for snake poison.

lua
TriggerEvent('bln_hud:UseAntidote')

Server Events ​

bln_hud:s:onItemUsed ​

Triggered after an item has been used.

Parameters:

  • source (number): Player ID who used the item
  • itemName (string): Name of the item
  • itemData (table): Configuration of the item
lua
AddEventHandler('bln_hud:s:onItemUsed', function(source, itemName, itemData)
    print("Player " .. source .. " used item: " .. itemName)
end)

Dependencies ​

  • oxmysql: Database interaction
  • bln_notify: Notification system
  • bln_lib: Utility library

Installation ​

  1. Ensure all dependencies are installed
  2. Place the bln_hud folder in your resources directory
  3. Add ensure bln_hud to your server.cfg
  4. Configure the resource in the configs folder
  5. Start your server

FAQ ​

Can I change the default HUD UI settings? ​

YES. Edit defaults.cfg.lua to adjust core HUD settings:

What are the custom actions in usable items? ​

For each usable item we have custom actions, you can use them to call your custom animation or any logic you need there. This is useful to let you make anything you need with the usable item, endless possibilities!

How do I add custom animations for items? ​

TWO WAYS:

  1. Within item configuration: Using custom actions.

  2. Register custom animation via export:

lua
exports.bln_hud:RegisterCustomAnimation('drink_whiskey', function(callback, propModel)
    -- animation logic here
end)

How does the temperature system work? ​

The temperature system factors in:

  • World location - Different regions have different base temperatures
  • Time of day - Colder at night, warmer during day
  • Weather - Snow, rain, and other conditions affect temperature
  • Clothing - Proper attire provides protection from temperature extremes
  • Item effects - Tonics and food can provide temporary warming/cooling

Can I integrate the HUD with other resources? ​

YES. The resource provides exports and events for integration:

lua
-- From another resource, register items that affect HUD stats
exports.bln_hud:registerUsableItem('special_food', {
    hunger = 40,
    thirst = 10
})

-- React to hunger changes
AddEventHandler('bln_hud:c:hungerChange', function(hunger)
    if hunger < 20 then
        -- Apply custom effect when player is very hungry
    end
end)

-- Modify player status from another resource
exports.bln_hud:AddHunger(20)
exports.bln_hud:ReduceStress(15, "relaxing")

How do I show/hide specific HUD elements? ​

From defaults.cfg.lua, or in game using the hud editor.