🔋Battery System

The YSeries battery system provides realistic phone battery simulation with automatic drain, charging capabilities. The system saves battery state to the database and persists across server restarts.

Key Features

• Realistic Battery Drain: Different drain rates for active/inactive phone states

• Vehicle Charging: Charge phones using USB cables in compatible vehicles

• Signal Management: Phone loses signal when battery dies, restores when charged

• Database Persistence: Battery levels saved and restored across sessions

• Unique Phone Support: Individual battery tracking for each phone IMEI

• Configurable Settings: Highly customizable drain rates, charging speeds, and thresholds

Configuration

config/config.battery.lua

Config.Battery = {
    Enabled = true,                    -- Enable/disable battery system
    DrainInterval = {
        Active = { 50, 60 },          -- Min/Max seconds to drain 1% when phone is open
        Inactive = { 80, 120 }        -- Min/Max seconds to drain 1% when phone is closed
    },
    DischargeWhenInactive = true,     -- Should phone drain when closed
    ShutdownThreshold = 0,            -- Phone shuts down at this percentage
    ChargingRate = 5,                 -- Default percentage per minute when charging
    
    -- Phone Battery Specifications
    PhoneCapacity = 3000,             -- Phone battery capacity in mAh
    ChargingEfficiency = 0.85,        -- 85% charging efficiency (energy loss)
    
    -- Vehicle Charging System
    VehicleCharging = {
        Enabled = true,               -- Enable vehicle charging
        RequiredItem = "usb_cable",   -- Required item to charge in vehicle
        ChargingRate = 8,             -- Percentage per minute when charging in vehicle
        EngineRequired = true,        -- Vehicle engine must be running
        MinEngineHealth = 300,        -- Minimum engine health required for charging
        VehicleTypes = {              -- Vehicle types that support charging
            [0] = true,               -- Compacts
            [1] = true,               -- Sedans
            [2] = true,               -- SUVs
            -- ... (see config file for complete list)
        }
    }
}

Inventory Item

You need this item to use the built-in charging system.

qb-inventory

usb_cable = { name = 'usb_cable ', label = 'USB Type-C', weight = 50, type = 'item', image = 'usb_cable.png', unique = true, useable = true, shouldClose = true, combinable = nil, description = 'USB cable for charging.' },

ox_inventory

['usb_cable'] = {
    label = 'USB Type-C',
    weight = 50,
    stack = true,
    close = true,
    description = 'USB cable for charging.',
    client = {
        image = 'usb_cable.png',
        export = "yseries.UseUSBCable"
    }
},

Exports(client-side)

Battery Information

GetBatteryLevel()

Returns the current battery percentage.

local batteryLevel = exports.yseries:GetBatteryLevel()
print("Battery: " .. batteryLevel .. "%")

GetBatteryInfo()

Returns battery information.

local info = exports.yseries:GetBatteryInfo()
-- Returns: { level = 75, isCharging = false }

Battery Control

SetBatteryLevel(level)

Sets the battery to a specific percentage (0-100).

-- Set battery to 50%
local success = exports.yseries:SetBatteryLevel(50)

ChargeBattery(amount)

Adds the specified amount to current battery level.

-- Add 25% to current battery
local success = exports.yseries:ChargeBattery(25)

Charging Control

StartCharging()

Starts the charging process.

exports.yseries:StartCharging()

StopCharging()

Stops the charging process.

exports.yseries:StopCharging()

Events

Client Events

Battery State Events

-- Triggered when battery level or charging state changes
RegisterNetEvent('yseries:battery:update', function(data)
    -- data = { level = 75, isCharging = false }
end)

Phone State Events

-- Device change (for unique phones)
TriggerEvent('yseries:client:device-changed', newImei)

Vehicle Charging Integration

How Vehicle Charging Works

1. Requirements: Player must have USB cable item in inventory

2. Vehicle Check: Player must be in a compatible vehicle with engine running

3. Usage: Use USB cable item to start charging

4. Automatic Stop: Charging stops when exiting vehicle or engine turns off

Database Integration

Automatic Saving

• Battery data is automatically saved every 6 updates (~30 seconds during drain)

• Immediate save on significant events (charging start/stop, manual changes)

• Data persists across server restarts and resource restarts

Performance Considerations

Best Practices

1. Use appropriate charging rates: Don't exceed realistic charging speeds (1-20% per minute)

2. Handle edge cases: Check for nil values when accessing battery data

Troubleshooting

Common Issues

1. Battery not draining: Check if Config.Battery.Enabled is true

2. Vehicle charging not working: Verify USB cable item exists and vehicle types are configured

3. Database not saving: Check database permissions and connection

This battery system provides a comprehensive and realistic phone battery experience while remaining highly customizable and extensible for your specific server needs.