FLATBED TOW v1.8 - GTA V STORY MODE / ENHANCED
==============================================

WHAT CHANGED IN v1.8
--------------------
- Added native Xbox / PlayStation controller support.
- Controller loading, unloading and adjustment use the same cab/control-panel
  distance requirement as keyboard controls.
- Added a controller modifier so the flatbed does not respond to ordinary driving.
- Added optional suppression of conflicting GTA controls only while the modifier
  is held at an accessible tow-truck control point.
- Controller bindings are editable under [Controller] in FlatbedTow.ini.
- Retains solid attached-cargo collision and every previous flatbed feature.

DEFAULT CONTROLLER CONTROLS
---------------------------
Hold LB on Xbox, or L1 on PlayStation, while using the controls below:

- LB/L1 + click R3: load or release the vehicle
- D-pad left / right: X axis left / right
- D-pad up / down: Y axis forward / backward
- RT/R2 / LT/L2: Z axis up / down
- X/Square / B/Circle: yaw left / right
- Y/Triangle / A/Cross: pitch up / down

Adjustment buttons can be tapped or held. Continuous adjustment uses the same
initial-delay, repeat-speed, movement-step and rotation-step settings as keyboard.
The controller does nothing unless you are inside the correct tow truck or beside
its configured exterior control panel.

CONTROLLER CONFIGURATION
------------------------
The [Controller] section accepts the included script-control names or numeric GTA
control indices. Default values:

Enabled=true
RequireModifier=true
SuppressGameControls=true
ControlGroup=0
Modifier=ScriptLB
Toggle=ScriptRS
MoveLeft=ScriptPadLeft
MoveRight=ScriptPadRight
MoveForward=ScriptPadUp
MoveBackward=ScriptPadDown
MoveUp=ScriptRT
MoveDown=ScriptLT
YawLeft=ScriptRLeft
YawRight=ScriptRRight
PitchUp=ScriptRUp
PitchDown=ScriptRDown

SuppressGameControls=true prevents the same buttons from accelerating, braking,
opening the weapon wheel, changing radio stations, exiting the truck, and similar
actions while you are actively operating the flatbed. Suppression ends as soon as
the modifier is released or you leave the cab/control-panel interaction zone.

INSTALLATION / UPGRADING
------------------------
Copy FlatbedTow.cs into Grand Theft Auto V\scripts\.

To preserve tuned truck offsets and control-panel positions, replace only the CS
file. Controller support uses the defaults above even when the new [Controller]
section is absent. Copy the included INI only when you want the bindings documented
and editable in your installed configuration.

WHAT CHANGED IN v1.7
--------------------
- Added solid collision to vehicles while they are attached to the flatbed.
- Attached cargo now collides with traffic, peds, props and world geometry.
- Cargo-to-flatbed collision remains disabled to prevent self-collision shaking,
  damage and launch forces.
- Collision is reasserted while attached and restored normally when released.
- Added AttachedCargoCollision and DisableCargoCarrierCollision INI settings.
- Retains the v1.6.2 modifier latch and all prior interaction-zone features.

COLLISION SETTINGS
------------------
AttachedCargoCollision=true
    Enables collision for the secured vehicle. Set false to return to the old
    visual-only/non-solid attached behavior.

DisableCargoCarrierCollision=true
    Prevents only the attached vehicle and its own tow truck from colliding.
    Leave true. Other vehicles and world objects can still strike the cargo.

ENGINE LIMITATION
-----------------
The cargo remains a rigid child attachment rather than a fully simulated vehicle.
It can block and be struck by other entities, but extreme speeds, very small props
or severe frame-rate drops can still produce occasional clipping in GTA V physics.

WHAT CHANGED IN v1.6.2
----------------------
- Fixed the regression where Shift had to be pressed again for every adjustment.
- Modifier state and direction-key state are now tracked independently.
- Hold Shift once, then tap or hold any number of adjustment keys in sequence.
- Windows' synthetic Shift-up events during numpad translation are ignored.
- Shift by itself still cannot move the cargo.
- Continuous key holding and interaction-zone restrictions remain active.

WHAT CHANGED IN v1.6.1
----------------------
- Fixed Shift by itself being interpreted as X-axis left movement.
- Direction input is now latched only after a real adjustment-key KeyDown event.
- KeyUp releases that direction, while Tick provides smooth hold-to-repeat movement.
- You can hold Shift continuously and tap or hold different numpad keys.
- Windows Shift+numpad navigation translations are still supported.
- Retains all v1.6 repeat timing and v1.5 interaction-access features.

WHAT CHANGED IN v1.6
--------------------
- Added continuous hold-to-repeat adjustment.
- The first step happens immediately; repetition starts after a configurable delay.
- Added configurable repeat speed, movement step and rotation step.

WHAT CHANGED IN v1.5
--------------------
- Added an interaction-access requirement to stop tow controls from responding
  while the player is across the road or using numpad controls for another mod.
- Loading, unloading and all attached-vehicle axis adjustments now require the
  player to be either:
    1. inside the supported tow truck, or
    2. on foot beside that truck's configured exterior control-panel point.
- A player sitting in a different vehicle cannot operate the panel remotely.
- Every flatbed profile can now have its own control-panel X/Y/Z position and
  interaction radius, including replacement and add-on tow trucks.
- Existing 6- and 7-value profiles remain compatible.
- Retains the Enhanced 3.9 compile fixes, model-edge pickup/release placement,
  modifier-free XYZ controls and built-in flatbed2 support.

INSTALLATION
------------
Copy both files from this package's scripts folder into:

    Grand Theft Auto V\scripts\

Replace the previous FlatbedTow.cs and FlatbedTow.ini.

OPERATING THE FLATBED
---------------------
To load or release a vehicle with T, and to use any cargo-adjustment key, you
must be inside that specific tow truck or on foot near its exterior bed-control
point.

The included profiles place the control point on the driver's side near the
front of the bed. These positions are starting points because replacement model
geometry can differ even when the spawn name is unchanged.

CONTROLS WHILE A VEHICLE IS ATTACHED
------------------------------------
With RequireAdjustmentModifier=true, hold Shift and then hold or tap a key.
You do not need to release Shift between adjustment presses.

While inside the carrier or standing at its panel:

- Numpad 4 / 6 OR Left / Right: X axis, left / right
- Numpad 8 / 2 OR Up / Down: Y axis, forward / backward
- Numpad 9 / 3 OR Page Up / Page Down: Z axis, up / down
- Numpad 7 / 1 OR Home / End: yaw left / right
- Numpad + / -: pitch
- T: release the vehicle

The keys work with Num Lock on or off. Shift alone cannot move the cargo. Hold
Shift once, then tap or hold as many adjustment keys as needed without releasing it.
Input remains gated by the interaction-access check.

CONTROL-PANEL PROFILE FORMAT
----------------------------
The full v1.5 profile contains eleven values:

modelName=bedX,bedY,bedZ,rotX,rotY,rotZ,rearEdgeCorrection,panelX,panelY,panelZ,panelRadius

Example:

flatbed2=0.00,-2.15,1.12,0.00,0.00,0.00,0.00,-1.35,-1.15,0.70,1.85

Panel coordinates are local to the truck:

- X positive: passenger/right side
- X negative: driver/left side
- Y positive: toward the front
- Y negative: toward the rear
- Z positive: upward

For an add-on truck, start with the example profile and adjust panelX/Y/Z until
controls activate where its real control box is modeled. panelRadius is measured
in game metres; 1.5 to 2.0 is a useful starting range.

INTERACTION SETTINGS
--------------------
RequireInteractionAccess=true
    Enables the distance/cab requirement. Leave this true for compatibility.

AllowControlFromCab=true
    Allows loading, release and adjustment while seated anywhere in the carrier.
    Set false to require the exterior panel for every operation.

DefaultControlPanelX/Y/Z and DefaultControlPanelRadius
    Fallback values for old custom profiles that contain only six or seven
    numbers. New profiles should use the full eleven-value format.

SUPPORTED FLATBEDS
------------------
Built in:
- flatbed
- flatbed2 (MTL Custom Flatbed)
- slamtruck

Other replacement or add-on spawn names can be added under [Flatbeds].

REQUIREMENTS
------------
- Script Hook V compatible with the installed GTA V build.
- ScriptHookVDotNet 3.x for Legacy, or a compatible SHVDN Enhanced build.
- Do not use Story Mode scripts in GTA Online.


HOLD-TO-REPEAT SETTINGS
-----------------------
FineAdjustModifier=ShiftKey
RequireAdjustmentModifier=true
    Hold Shift while using adjustment keys. Set false for direct controls.

AdjustmentInitialDelayMs=250
    Delay after the immediate first step before continuous repetition begins.

AdjustmentRepeatMs=65
    Time between repeated steps. Lower is faster; 40-100 ms is practical.

ModifierReleaseGraceMs=250
    Filters synthetic Shift-up events created by Windows numpad translation.
    The default should normally be left unchanged.

AdjustmentMoveStep=0.05
AdjustmentRotateStep=1.0
    Distance and angle applied per step.

You may replace only FlatbedTow.cs to preserve your tuned INI profiles. If your
existing INI does not contain the new repeat settings, the script uses the
default values shown above.
