Ares Hydraulics - Installation & Configuration Guide

Version: 2.0.1 Authors: Smud, Roro Framework Support: ESX, QB-Core, QBX, Standalone

---

📋 Table of Contents

• Overview

• Installation

• Dependencies

• Item Configuration

• Configuration Guide

• Vehicle Whitelist

• Usage

---

🎯 Overview

Ares Hydraulics enhances the native GTA V hydraulics system with additional features and controls. This script provides:

• Jump mechanics with customizable keybinds (default: G key)

• Item-based hydraulic control - require hydraulic kits to use the system

• Vehicle detection - automatic detection via mod slots or model whitelists

• Multi-framework support - works with ESX, QB-Core, QBX, or standalone

• Player customization - configurable jump keys per player

• Database integration - compatible with custom garage scripts

Important: This script enhances vehicles that already have hydraulics installed in GTA V. It does not add hydraulics to vehicles that don't natively support them.

---

🚀 Installation

Important Notice

The resource folder can be named anything you prefer.

Setup Steps

1. Extract the resource to your server's resources folder

2. Add items to your inventory system (see Item Configuration)

3. Add to server.cfg:

   ensure ares_hydraulics

4. Restart your server

The script uses JSON-based storage (hydraulics_data.json) which is automatically created and managed. No database setup required.

---

📦 Dependencies

Required

• ox_lib - Core library for UI and utilities

Framework (Choose One or Standalone)

• ESX (any version)

• QB-Core (any version)

• QBX Core (any version)

• Standalone (no framework required)

Optional

• ox_inventory - Recommended inventory system

• qb-inventory - QB-Core inventory support

• Custom garage scripts - Compatible with database check feature

The script automatically detects your framework and inventory system. No manual configuration needed unless you want to force a specific setup.

---

🎒 Item Configuration

For ox_inventory

Add the following item to your ox_inventory/data/items.lua file:

["hydraulic_kit"] = {
    label = "Hydraulic Kit",
    weight = 5000,
    stack = false,
    close = true,
    description = "Advanced hydraulic system for lowrider vehicles"
},

For QB-Core Inventory

Add item to your qb-core/shared/items.lua:

['hydraulic_kit'] = {
    ['name'] = 'hydraulic_kit',
    ['label'] = 'Hydraulic Kit',
    ['weight'] = 5000,
    ['type'] = 'item',
    ['image'] = 'hydraulic_kit.png',
    ['unique'] = false,
    ['useable'] = true,
    ['shouldClose'] = true,
    ['combinable'] = nil,
    ['description'] = 'Advanced hydraulic system for lowrider vehicles'
},

For ESX Legacy

Execute the following SQL command in your database:

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
('hydraulic_kit', 'Hydraulic Kit', 5000, 0, 1);

---

⚙️ Configuration Guide

All configuration is done in the config.lua file.

Framework & Inventory Settings

Config.Framework = 'auto'
Config.Inventory = 'auto'

Parameter	Type	Description	Options
Framework	string	Framework detection mode	'auto', 'esx', 'qb-core', 'qbox', 'standalone'
Inventory	string	Inventory system detection	'auto', 'ox_inventory', 'qb-inventory', 'esx'

Recommended: Leave both set to 'auto' for automatic detection.

---

Item Requirements

Config.RequireItem = true

Description: Determines whether players need a hydraulic kit item to use hydraulics. Options:

• true - Players must have hydraulic_kit in inventory to use hydraulics

• false - Standalone mode, anyone can use hydraulics on compatible vehicles

Use case: Set to false if you want free access to hydraulics without item requirements.

---

Inventory Item Aliases

Config.InventoryAliases = {
    ['hydraulic_kit'] = {
        ['ox_inventory'] = 'hydraulic_kit',
        ['qb-inventory'] = 'hydraulic_kit',
        ['esx'] = 'hydraulic_kit'
    }
}

Description: Maps logical item names to inventory-specific names. Use case: If your server uses different item names across inventory systems, configure them here.

Example with custom names:

Config.InventoryAliases = {
    ['hydraulic_kit'] = {
        ['ox_inventory'] = 'hydro_system',
        ['qb-inventory'] = 'car_hydraulics',
        ['esx'] = 'hydraulic_kit'
    }
}

---

Command & Keybind Settings

Config.Command = 'hydraulics'

Description: Command to open the hydraulics control menu. Usage: /hydraulics in-game

---

Config.JumpKey = {
    defaultKey = 'G',
    playerCanConfigure = true  
}

Parameter	Type	Description
defaultKey	string	Default keybind for hydraulic jump
playerCanConfigure	boolean	Allow players to change their jump key with /myjumpkey

Available keys: Any keyboard letter (A-Z), numbers (0-9), or function keys (F1-F12)

Example:

Config.JumpKey = {
    defaultKey = 'H',        -- Changed to H key
    playerCanConfigure = false  -- Locked to H, players can't change
}

---

Jump Cooldown

Config.JumpCooldown = {
    enabled = true,
    duration = 3
}

Parameter	Type	Description
enabled	boolean	Enable jump cooldown system
duration	number	Cooldown duration in seconds

Description: Prevents spam jumping by adding a cooldown between jumps.

---

Jump Mechanics

Config.JumpLockMs = 900
Config.JumpResetDelayMs = 900

Parameter	Type	Description	Default
JumpLockMs	number	Time vehicle is locked during jump (milliseconds)	900
JumpResetDelayMs	number	Delay before hydraulics reset after jump (milliseconds)	900

Description: Fine-tune the timing of jump animations and vehicle behavior.

---

Config.JumpForce = 3.0
Config.VerticalBoost = 4.0
Config.VerticalBoostSpeedGate = 100.0

Parameter	Type	Description	Default
JumpForce	number	Base horizontal jump force multiplier	3.0
VerticalBoost	number	Additional vertical force when moving fast	4.0
VerticalBoostSpeedGate	number	Speed threshold (km/h) for vertical boost	100.0

Description: Controls how high and far vehicles jump.

Tuning tips:

• Increase JumpForce for longer horizontal jumps

• Increase VerticalBoost for higher jumps when moving fast

• Lower VerticalBoostSpeedGate to get vertical boost at slower speeds

Example - Higher jumps:

Config.JumpForce = 4.5           -- More horizontal distance
Config.VerticalBoost = 6.0       -- Higher vertical jumps
Config.VerticalBoostSpeedGate = 80.0  -- Boost kicks in at 80 km/h

---

Hydraulics Detection

Config.HydraulicsDetection = {
    RequireHydraulicsForUI = true,
    useModSlot38 = true,
    useModelWhitelist = true,
    modelWhitelist = {
        'faction2','buccaneer2','chino2','moonbeam2','primo2',
        'sabregt2','slamvan3','voodoo','peyote3','tornado5','minivan2','virgo2'
    },
    itemWhitelist = {
        'hydraulic_kit',
    },
    useDatabaseCheck = true,
}

Core Detection Settings

Parameter	Type	Description
RequireHydraulicsForUI	boolean	Only show UI if vehicle has hydraulics installed
useModSlot38	boolean	Check for lowrider hydraulics mod (slot 38)
useModelWhitelist	boolean	Enable model-based vehicle detection
useDatabaseCheck	boolean	Check database for hydraulic installations

Model Whitelist

Description: List of vehicle models that support hydraulics.

Pre-configured vehicles:

• faction2 - Faction Custom

• buccaneer2 - Buccaneer Custom

• chino2 - Chino Custom

• moonbeam2 - Moonbeam Custom

• primo2 - Primo Custom

• sabregt2 - Sabre Turbo Custom

• slamvan3 - Slamvan Custom

• voodoo - Voodoo

• peyote3 - Peyote Custom

• tornado5 - Tornado Custom

• minivan2 - Minivan Custom

• virgo2 - Virgo Classic Custom

Adding custom vehicles:

modelWhitelist = {
    'faction2','buccaneer2','chino2',  -- Default vehicles
    'yourvehicle1',                    -- Add your custom vehicle
    'customlowrider',                  -- Add another
}

Finding vehicle model names:

1. Use in-game /getmodel command (if available)

2. Check vehicle spawn name in your server files

3. Reference: GTA V Vehicle Models List

Item Whitelist

Description: Items that grant hydraulic control when in inventory.

Default: 'hydraulic_kit'

Use case: If you have multiple hydraulic items (basic, advanced, etc.), add them here:

itemWhitelist = {
    'hydraulic_kit',
    'advanced_hydraulics',
    'racing_hydraulics',
}

Database Check

Description: When enabled, checks if vehicle has hydraulics installed in your garage database.

When to enable:

• ✅ Using custom garage scripts (e.g., Lunar Garages, cd_garage)

• ✅ Vehicles store modification data in database

• ✅ You want persistent hydraulic installations

When to disable:

• ❌ Using standard FiveM vehicle persistence

• ❌ No custom garage script

• ❌ Hydraulics are purely item-based

Note: Leave enabled by default. It won't cause issues if no custom garage is present.

---

Notification Messages

Config.NotifyTitle = 'Ares Hydraulics'
Config.Messages = {
    notDriver = 'You must be the driver to use hydraulics.',
    noHydros  = "This vehicle doesn't have hydraulics installed.",
    usageSetKeyAdmin = 'Usage: /setjumpkey [player_id] [key]',
    usageSetKeyPlayer = 'Usage: /myjumpkey [key] (e.g., /myjumpkey H)',
    adminKeyDisabled = 'Jump key configuration is disabled for admins!',
    playerKeyDisabled = 'Jump key configuration is disabled for players!',
}

Description: Customize all notification messages shown to players.

Example customization:

Config.Messages = {
    notDriver = 'Only the driver can control hydraulics!',
    noHydros  = "This car ain't got no hydros, holmes!",
}

---

Debug Mode

Config.Debug = true

Description: Enable detailed console logging for troubleshooting. Recommended: Set to false in production for better performance.

---

🚗 Vehicle Whitelist

Default Compatible Vehicles

All GTA V lowrider vehicles with native hydraulic support are pre-configured:

Vehicle Name	Model Name	Type
Faction Custom	faction2	Muscle
Buccaneer Custom	buccaneer2	Muscle
Chino Custom	chino2	Muscle
Moonbeam Custom	moonbeam2	Van
Primo Custom	primo2	Sedan
Sabre Turbo Custom	sabregt2	Muscle
Slamvan Custom	slamvan3	Utility
Voodoo	voodoo	Muscle
Peyote Custom	peyote3	Sports Classic
Tornado Custom	tornado5	Sports Classic
Minivan Custom	minivan2	Van
Virgo Classic Custom	virgo2	Muscle

Adding Custom Vehicles

1. Find the vehicle model name (spawn name)

2. Add to modelWhitelist:

Config.HydraulicsDetection = {
    -- ... other settings
    modelWhitelist = {
        'faction2','buccaneer2','chino2',  -- Existing vehicles
        'your_custom_vehicle',             -- Add your vehicle here
    },
}

1. Ensure the vehicle has hydraulics installed in GTA V

   • The script enhances native hydraulics, it doesn't create them

   • Vehicle must support lowrider modifications

Finding Vehicle Model Names

Method 1 - In-game inspection:

-- While in vehicle, use F8 console:
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
local model = GetDisplayNameFromVehicleModel(GetEntityModel(vehicle))
print(model)  -- This is your model name

Method 2 - Documentation:

• Check vehicle spawn lists in your server files

• Reference GTA V vehicle databases online

• Use developer tools or vehicle spawner menus

---

🎮 Usage

For Players

Opening Hydraulics Menu

/hydraulics

Opens the control interface for vehicle hydraulics.

Changing Jump Key

/myjumpkey [key]

Examples:

• /myjumpkey H - Set jump to H key

• /myjumpkey F - Set jump to F key

• /myjumpkey SPACE - Set jump to spacebar

Note: Only works if Config.JumpKey.playerCanConfigure = true

Using Hydraulics

1. Enter a compatible vehicle as the driver

2. Ensure you have a hydraulic_kit item (if Config.RequireItem = true)

3. Press your jump key (default: G) to perform hydraulic jumps

4. Use /hydraulics to access advanced controls and suspension adjustments

---

📝 Quick Reference

Essential Configuration Checklist

• ✅ Set Config.RequireItem based on your server economy

• ✅ Configure Config.JumpKey.defaultKey to your preference

• ✅ Adjust Config.JumpForce and Config.VerticalBoost for desired jump behavior

• ✅ Add custom vehicles to modelWhitelist if needed

• ✅ Enable/disable playerCanConfigure for keybind customization

• ✅ Set Config.Debug = false in production

Performance Tips

• Disable Config.Debug on live servers

• Keep modelWhitelist concise - only add vehicles you actually use

• Use useModSlot38 = true for automatic detection of stock lowriders

• useDatabaseCheck only adds overhead if you have a custom garage system

Common Customizations

Disable item requirement (free hydraulics):

Config.RequireItem = false

Change default jump key:

Config.JumpKey = {
    defaultKey = 'H',
    playerCanConfigure = true
}

Increase jump height:

Config.JumpForce = 4.0
Config.VerticalBoost = 5.5

Lock jump key (prevent player changes):

Config.JumpKey = {
    defaultKey = 'G',
    playerCanConfigure = false  -- Players can't change it
}

---

🔧 Troubleshooting

Issue	Solution
Hydraulics not working	Verify vehicle is in modelWhitelist or has mod slot 38 installed
No jump happening	Check Config.RequireItem - player might need hydraulic_kit
"No hydraulics installed" message	Enable useModSlot38 or add vehicle to modelWhitelist
Jump key not responding	Check for keybind conflicts with other scripts
Custom vehicles not working	Ensure vehicle model name is spelled correctly in whitelist
Database check not working	Verify your garage script stores hydraulic data in database

---

🎯 Feature Highlights

What This Script Adds

✅ Hydraulic jump mechanics - Press G (or custom key) to make your lowrider jump ✅ Item-based control - Require players to have hydraulic kits ✅ Configurable physics - Tune jump height, distance, and speed requirements ✅ Player customization - Let players set their own jump keys ✅ Smart detection - Automatic hydraulic detection via mods or model names ✅ Multi-framework - Works with ESX, QB, QBX, or standalone ✅ Cooldown system - Prevent jump spam ✅ Database integration - Compatible with custom garage scripts

What This Script Does NOT Do

❌ Add hydraulics to non-lowrider vehicles - Only enhances vehicles with native GTA hydraulics ❌ Create visual hydraulic mods - Works with existing GTA V hydraulic systems ❌ Modify vehicle handling files - Pure script-based enhancement\