Manual Transmission

📄 Config file: shared/transmission_config.lua

This file controls the manual transmission system — keybinds, clutch behaviour, shift timing, rev limiter, engine stalling, and gear-shift animations. The manual transmission replaces GTA's default automatic shifting with a realistic system where the player must manually shift gears using the clutch.

---

Keybinds

Config.ShiftUp    = 21   -- LSHIFT
Config.ShiftDown  = 36   -- LCTRL
Config.ClutchKey  = 19   -- LALT

Setting	Default Key	What it does
ShiftUp	LSHIFT	Shifts to the next higher gear (hold ALT + press).
ShiftDown	LCTRL	Shifts to the next lower gear (hold ALT + press).
ClutchKey	LALT	Holds the clutch (disengages the engine from the wheels).

The numbers are FiveM control IDs. You can find all control IDs at the FiveM Controls Reference.

How shifting works: Hold ALT (clutch), then press SHIFT or CTRL to change gear. Release ALT to engage the new gear and transfer power to the wheels. The gear sequence is: R ↔ N ↔ 1 ↔ 2 ↔ 3 ↔ 4 ↔ 5 ↔ 6.

---

General Settings

Config.ManualClutch        = true
Config.ShowUI              = true
Config.RPMWarningThreshold = 0.85
Config.RPMHysteresis       = 0.05

Setting	What it does
ManualClutch	When true, the player must hold the clutch key while changing gears. If false, gears shift without needing the clutch (simplified mode).
ShowUI	Shows a gear indicator HUD on screen (displays current gear: 1, 2, 3, N, R).
RPMWarningThreshold	RPM level (0.0–1.0) where the HUD shows a warning indicator. 0.85 = 85% RPM.
RPMHysteresis	Buffer zone to prevent rapid on/off flickering of the warning.

---

Clutch & Shifting Feel

Config.ClutchShiftSpeed     = 0.5
Config.NoClutchPenalty      = 1.0
Config.PenaliseEarlyRelease = false

Setting	What it does
ClutchShiftSpeed	Multiplier for how fast shifts complete when the clutch is held. Lower = faster shift. 0.5 = half the default shift time.
NoClutchPenalty	Additional delay multiplier when shifting without holding the clutch. Higher = slower, more punishing. 1.0 = no extra penalty.
PenaliseEarlyRelease	When true, releasing the clutch during a shift adds a delay penalty.

Shift duration is derived from the vehicle's handling data (fClutchChangeRateScaleUpShift / fClutchChangeRateScaleDownShift). Vehicles with transmission upgrades will also shift faster.

---

Rev Limiter

Config.EnableRevLimiter  = true
Config.RevLimiterRelease = 0.95

Setting	What it does
EnableRevLimiter	When true, the gas input is completely cut when the engine reaches maximum RPM (1.0). Prevents over-revving.
RevLimiterRelease	The RPM level at which the limiter releases and gas input is restored. 0.95 = 95% RPM.

---

Engine Stall & Stutter

📄 Config file: shared/stall.lua

Kartik-Mechanic features a dynamic stalling and stuttering system that responds to both poor driving technique and worn vehicle parts.

Config.StallChance             = 0.4 
Config.MissfireChance          = 0.3 
Config.FuelPumpStallChance     = 0.02
Config.FuelPumpStutterChance   = 0.15

Setting	What it does
StallChance	Base probability of the engine stalling completely when misbehaving.
MissfireChance	Base probability of the engine misfiring (stuttering) instead of stalling.
FuelPumpStallChance	Additional stall chance added when the fuel pump is heavily worn.
FuelPumpStutterChance	Additional stutter chance added when the fuel pump is heavily worn.

---

Engine Lugging

Config.LuggingThreshold        = 0.25
Config.LuggingPowerMultiplier  = 0.3
Config.LuggingStutterChance    = 0.4   
Config.GearSpeedBias           = 1.1    

Setting	What it does
LuggingThreshold	RPM threshold below which the engine starts to lug (struggle). 0.25 = 25% RPM.
LuggingPowerMultiplier	Reduces vehicle acceleration while lugging. 0.3 = 30% of normal power.
LuggingStutterChance	The probability of the engine stuttering while lugging.
GearSpeedBias	Ratio used to determine the exact speed vs gear relationship for lugging calculations.

---

Driving Behaviour

Config.PreventAutoReverse     = true
Config.TopGearSpeedCorrection = true
Config.TopGearSpeedFactor     = 0.888

Setting	What it does
PreventAutoReverse	When true, braking in a forward gear will not automatically switch to reverse. The player must manually shift to R.
TopGearSpeedCorrection	Adjusts the vehicle's maximum speed when in the highest gear to match real-world behaviour.
TopGearSpeedFactor	The multiplier applied to the vehicle's max flat velocity when in top gear. 0.888 slightly reduces top speed for realism.

---

RPM Cut (Clutch Held)

Config.RpmCut     = true
Config.RpmCutMax  = 0.8
Config.RpmCutMin  = 0.7
Config.RpmCutTime = 50

When the clutch is held down, the engine RPM bounces between RpmCutMin and RpmCutMax to simulate a realistic rev-matching effect.

Setting	What it does
RpmCut	Enable/disable the RPM cutting feature while clutch is held.
RpmCutMax	Maximum RPM during the cut cycle.
RpmCutMin	Minimum RPM during the cut cycle.
RpmCutTime	Time (in milliseconds) between RPM oscillations. Lower = faster bouncing.

---

Gear Shift Animation & Sound

Config.ShiftAnimation = true
Config.ShiftEndSound  = true

Setting	What it does
ShiftAnimation	When true, plays a hand animation (reaching for the gear stick) each time the player shifts. Detects LHD/RHD automatically.
ShiftEndSound	When true, plays a short sound effect when a gear shift completes.

---

Stall Speed Thresholds

Config.StallSpeedThresholds = {
    [1] = 0.0,      -- Gear 1: Never stalls due to low speed
    [2] = 2.0,      -- Gear 2: Stalls below 2 m/s (~7 km/h)
    [3] = 5.0,      -- Gear 3: Stalls below 5 m/s (~18 km/h)
    [4] = 10.0,     -- Gear 4: Stalls below 10 m/s (~36 km/h)
    [5] = 15.0,     -- Gear 5: Stalls below 15 m/s (~54 km/h)
    [6] = 20.0,     -- Gear 6: Stalls below 20 m/s (~72 km/h)
}

If the vehicle is in a higher gear and drops below that gear's stall speed threshold, the engine will stutter and potentially stall.

---

Gearbox Wear

Config.GearboxFailShiftThreshold = 9.9
Config.GearboxGrindChance        = 0.0

Setting	What it does
GearboxFailShiftThreshold	Wear ratio at which shift failures can start occurring. Set to 9.9 to effectively disable.
GearboxGrindChance	Probability (0–1) that a shift fails due to gearbox grinding when above the wear threshold. 0.0 = never.

These settings integrate with the main kartik-mechanic wear system. As gearbox wear increases through mileage, players may experience failed shifts and extra clutch wear.