🔋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

-- With these settings, a full charge will last around 2 hours.
Config.Battery = {}
Config.Battery.Enabled = false         -- Enable battery on the phone, you'll need to use the exports to charge it.
Config.Battery.DrainInterval = {
    Active = { 50, 60 },               -- Always keep 2 numbers in the array. Min and Max seconds to drain 1% of the battery.
    Inactive = { 80, 120 }             -- Always keep 2 numbers in the array. Min and Max seconds to drain 1% of the battery.
}

Config.Battery.StartingBattery = 100   -- Starting battery percentage
Config.Battery.ShutdownThreshold = 0   -- Phone shuts down at this percentage
Config.Battery.ChargingRate = 5        -- Percentage per minute when charging

-- Vehicle Charging System
Config.Battery.VehicleCharging = {
    Enabled = true,             -- Enable vehicle charging
    RequiredItem = "usb_cable", -- Required item to charge in vehicle
    ChargingRate = 8,           -- Percentage per minute when charging in vehicle(default)
    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
...
}

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

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 }
    local batteryLevel = data.level
    local isCharging = data.isCharging
end)

Phone State Events

-- Device change (for unique phones)
RegisterNetEvent('yseries:client:device-changed', function(newImei)
    -- Triggered when the player switches to a different phone device
end)

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.