===============================================================================
  BikeLife [BETA] - Motorcycle Gang Spawner with Wheelie Physics
  for Grand Theft Auto V
===============================================================================

  ** This is a BETA release. Expect bugs, unfinished features, and
     balance issues. Feedback and bug reports are welcome! **

Spawns configurable motorcycle gangs who cruise through their turf and pull
wheelies. Features realistic physics-based wheelie mechanics, zone-restricted
gang territories, time-based activity schedules, and police interactions.


===============================================================================
  REQUIREMENTS
===============================================================================

  - GTA V (latest version)
  - ScriptHookV            -> http://www.dev-c.com/gtav/scripthookv/
  - ScriptHookVDotNet v3   -> https://github.com/scripthookvdotnet/scripthookvdotnet/releases


===============================================================================
  INSTALLATION
===============================================================================

  1. Make sure ScriptHookV and ScriptHookVDotNet3 are installed in your
     GTA V root folder.
  2. Copy "Riders.dll" into your "Grand Theft Auto V/scripts/" folder.
  3. Copy "Riders.ini" into your "Grand Theft Auto V/scripts/" folder.
  4. Launch the game. You should see a green notification: "Riders: Loaded!"

  Your folder structure should look like this:

    Grand Theft Auto V/
      ScriptHookV.dll
      ScriptHookVDotNet3.dll
      scripts/
        Riders.dll
        Riders.ini


===============================================================================
  FEATURES
===============================================================================

  - GANG-BASED SPAWNING
    Define multiple rider groups tied to specific GTA V zones and active hours.
    Families ride through Chamberlain at night, Ballas cruise Davis, etc.

  - REALISTIC WHEELIE PHYSICS
    Smooth, continuous force-based system with angular velocity damping.
    No jerky pulses - bikes lift naturally and hold a stable angle.

  - PER-BIKE TUNING
    Override wheelie parameters for individual bike models (lift force,
    target pitch, drive speed, etc.) using [Bike_XXX] sections.

  - AUTOMATIC REMOUNT
    Riders who fall off their bike will get up and walk back to remount.

  - POLICE INTERACTION
    Nearby cops can chase and attempt to arrest riders (configurable).

  - NATURAL RIDER SUPPORT
    Optionally apply wheelie AI to NPC bikers already in traffic.

  - LEADER / FOLLOWER SYSTEM
    Groups ride in formation. If the leader goes down, a new one is
    automatically promoted.

  - FULLY CONFIGURABLE
    Every parameter is exposed in Riders.ini. Hot-reload with F10.

  - TEST MODE
    Force-spawn groups, clean all riders, and advance game time with
    hotkeys for easy tuning.

  - PERFORMANCE OPTIMIZED
    Wheelie physics only run when the player is within range. Riders
    further away just cruise normally.


===============================================================================
  CONFIGURATION (Riders.ini)
===============================================================================

  Press F10 in-game to hot-reload after editing.

  --- GENERAL SETTINGS ---

  Enabled              true       Enable/disable the entire mod
  MaxActiveGroups      1          Max simultaneous rider groups
  RidersPerGroupMin    2          Min riders per group
  RidersPerGroupMax    4          Max riders per group
  SpawnDistanceMin     120        Spawn distance from player (m)
  SpawnDistanceMax     150        Spawn distance from player (m)
  CleanupDistance      250        Remove riders beyond this distance (m)
  SpawnIntervalMs      15000      Time between spawn attempts (ms)
  ApplyToNaturalRiders false      Apply wheelie AI to traffic bikers
  WheelieActiveDistance 200       Wheelie physics range from player (m)

  --- RIDER GROUPS ---

  Define gangs with [Group_XXX] sections in the INI:

    [Group_Families]
    Enabled = true
    Weight = 12                   (higher = more likely to spawn)
    PedModels = g_m_y_famca_01, g_m_y_famdnf_01, g_m_y_famfor_01
    BikeModels = BF400, SANCHEZ2, BMX
    DoWheelie = true
    Zones = CHAMH, DAVIS, STRAW   (empty = spawns everywhere)
    ActiveHourStart = 18           (active from 6 PM...)
    ActiveHourEnd = 4              (...to 4 AM, wraps around midnight)

  --- WHEELIE TUNING ---

  The [DefaultWheelie] section controls physics for all bikes.
  Override per-bike with [Bike_XXX] sections.

  LiftForce      0.18     Upward force per frame (0.10=gentle, 0.30=strong)
  TorqueOffset   1.2      Lever arm in meters (higher = more rotation)
  TargetPitch    43.0     Target wheelie angle (degrees)
  MaxPitch       45.0     Emergency correction angle
  MinSpeed       12.0     Min speed to wheelie (m/s, ~43 km/h)

  How the physics work:
    0..50% of TargetPitch   -> Full lift force (dampened by rise speed)
    50%..TargetPitch        -> Force fades progressively + velocity damping
    TargetPitch..MaxPitch   -> Coast zone (no force, gravity settles)
    Above MaxPitch          -> Gentle correction pushes front back down

  --- DRIVING FLAGS ---

  Controls how riders navigate traffic:

    786603       Normal, cautious driving (RECOMMENDED)
    2883621      Mission-style driving (good compromise)
    524852       Moderate (more aggressive but still avoids)
    1074528293   Aggressive, rams everything (NOT RECOMMENDED)

  --- PED BEHAVIOR ---

  BlockNonTempEvents  true    Prevents riders from reacting to threats
  FleeAttributes      0       0 = never flees
  AllowPoliceArrest   true    Police can chase and arrest riders


===============================================================================
  TEST MODE
===============================================================================

  Enable with [TestMode] Enabled = true in the INI, then use:

    NumPad1    Force-spawn a group near you (cycles through groups)
    NumPad0    Delete all spawned riders
    NumPad2    Advance game time by 1 hour
    Insert     Toggle debug overlay (rider state, pitch, speed)
    F10        Reload configuration


===============================================================================
  ZONE REFERENCE
===============================================================================

  Common GTA V zone names for the Zones setting:

    CHAMH   Chamberlain Hills       SANDY   Sandy Shores
    DAVIS   Davis                   GRAPES  Grapeseed
    STRAW   Strawberry              PALETO  Paleto Bay
    RANCHO  Rancho                  KOREAT  Little Seoul
    LMESA   La Mesa                 VINE    Vinewood
    CYPRE   Cypress Flats           MIRR    Mirror Park
    EBURO   El Burro Heights        ROCKF   Rockford Hills
    MURRI   Murrieta Heights        DELPE   Del Perro


===============================================================================
  TROUBLESHOOTING
===============================================================================

  - Riders don't spawn?
    Check that you're in a zone listed in the group's Zones setting, and
    that the current game hour is within ActiveHourStart/ActiveHourEnd.
    Enable Debug = true and press Insert for details.

  - Riders crash into cars?
    Use DrivingFlags = 786603 (default). Never use 1074528293.

  - Wheelies too aggressive?
    Lower LiftForce (try 0.12) and/or lower TargetPitch.

  - Riders don't remount after falling?
    Increase RemountTaskCooldown (try 5000) and RemountTimeout.

  - Performance issues?
    Lower WheelieActiveDistance, reduce MaxActiveGroups, or disable
    ApplyToNaturalRiders.


===============================================================================
  CREDITS
===============================================================================

  - ScriptHookV by Alexander Blade
    http://www.dev-c.com/gtav/scripthookv/

  - ScriptHookVDotNet by crosire & community
    https://github.com/scripthookvdotnet/scripthookvdotnet


===============================================================================
  LICENSE
===============================================================================

  This mod is provided as-is for personal use. You are free to modify it
  for your own enjoyment. If you redistribute or build upon it, please
  give credit.

===============================================================================
