π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/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.
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.' },
Exports(client-side)
Battery Information
GetBatteryLevel()
GetBatteryLevel()
Returns the current battery percentage.
local batteryLevel = exports.yseries:GetBatteryLevel()
print("Battery: " .. batteryLevel .. "%")
GetBatteryInfo()
GetBatteryInfo()
Returns battery information.
local info = exports.yseries:GetBatteryInfo()
-- Returns: { level = 75, isCharging = false }
Battery Control
SetBatteryLevel(level)
SetBatteryLevel(level)
Sets the battery to a specific percentage (0-100).
-- Set battery to 50%
local success = exports.yseries:SetBatteryLevel(50)
ChargeBattery(amount)
ChargeBattery(amount)
Adds the specified amount to current battery level.
-- Add 25% to current battery
local success = exports.yseries:ChargeBattery(25)
Charging Control
StartCharging()
StartCharging()
Starts the charging process.
exports.yseries:StartCharging()
StopCharging()
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
Requirements: Player must have USB cable item in inventory
Vehicle Check: Player must be in a compatible vehicle with engine running
Usage: Use USB cable item to start charging
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
Use appropriate charging rates: Don't exceed realistic charging speeds (1-20% per minute)
Handle edge cases: Check for nil values when accessing battery data
Troubleshooting
Common Issues
Battery not draining: Check if
Config.Battery.Enabled
is trueVehicle charging not working: Verify USB cable item exists and vehicle types are configured
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.
Last updated