🔋 Battery System

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

lua
Copy
-- 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.

lua
Copy
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.' },

lua
Copy
['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.

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

GetBatteryInfo()

Returns battery information.

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

Battery Control

SetBatteryLevel(level)

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

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

ChargeBattery(amount)

Adds the specified amount to current battery level.

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

Charging Control

StartCharging()

Starts the charging process.

lua
Copy
exports.yseries:StartCharging()

StopCharging()

Stops the charging process.

lua
Copy
exports.yseries:StopCharging()

Events

Client Events

Battery State Events

lua
Copy
-- 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

lua
Copy
-- 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.