===============================================================================
  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 "BikeLife.dll" into your "Grand Theft Auto V/scripts/" folder.
  3. Copy "BikeLife.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/
        BikeLife.dll
        BikeLife.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
    and gravity compensation. 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 BikeLife.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 (BikeLife.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       48.0     Emergency correction angle
  MinSpeed       12.0     Min speed to wheelie (game units)

  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

  Gravity compensation is built-in: force automatically scales up at
  higher pitch angles to counteract increasing gravity torque, so
  TargetPitch actually controls the wheelie height as expected.

  --- 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 & DEBUG
===============================================================================

  Enable Test Mode with [TestMode] Enabled = true in the INI.

  --- HOTKEYS ---

    Insert     Toggle debug overlay ON/OFF
    F10        Reload configuration (hot-reload, no restart needed)
    NumPad1    Force-spawn a group near you (cycles through groups)
    NumPad0    Delete all spawned riders

  --- DEBUG OVERLAY ---

  When debug is ON (press Insert), a text overlay appears above each
  tracked rider showing their current state in real time:

    [S:BF400] Attempting 1/3 | P:38.2 Spd:35 LIFT:0.34

  Here's what each part means:

    [S:BF400]        S = Spawned rider (N = Natural traffic rider)
                     BF400 = bike model name

    Attempting 1/3   Current phase + attempt counter
                     Phases: Idle / Attempting / Sustained
                     1/3 = 1 short burst done out of 3 total

    P:38.2           Current pitch angle in degrees (0 = flat)

    Spd:35           Current speed (same game units as MinSpeed config)

    LIFT:0.34        Force being applied this frame (green text)
                     DOWN:-0.12 = correction pushing front down (red text)

  --- PHASE CYCLE ---

  The wheelie system cycles through these phases:

    Idle 0/3     Waiting for next attempt (delay timer)
    Attempting   Short wheelie burst (AttemptDurationMin..Max ms)
    Idle 1/3     Pause between bursts (AttemptDelayMin..Max ms)
    Attempting   Another short burst
    ...          Repeats until all attempts done
    Idle 3/3     All short bursts complete, about to start long one
    Sustained    Long wheelie (SustainDurationMin..Max ms)
    Idle 0/0     Cycle complete, new target will be rolled

  --- SKIP REASONS ---

  When a wheelie is not active, the overlay shows WHY in yellow:

    WAIT         Delay timer between attempts (normal)
    SLOW         Bike too slow (below MinSpeed)
    STEER        Bike turning too hard (above MaxSteeringAngle)
    BRAKE        Sudden speed loss detected
    OBSTACLE     Raycast hit something ahead (wall, vehicle, ped)
    START        Transitioning to a new phase
    COAST        In coast zone (between TargetPitch and MaxPitch)
    DONE         Phase just ended, returning to Idle

  --- DEBUG NOTIFICATIONS ---

  When debug is ON, the mod also shows ticker notifications for:

    - Spawn attempts (zone, hour, group picked, model loading)
    - Spawn success/failure
    - Remount progress (distance, task assigned)
    - Group leader changes (promotion)
    - Destination refreshes
    - Cleanup events (bike destroyed, rider released)
    - Police interactions (chase, arrest)

  --- TIPS FOR DEBUGGING ---

    1. Press Insert first to see the overlay, then NumPad1 to spawn
    2. Follow a rider to watch the phase cycle in real time
    3. If riders don't spawn, check the ticker for zone/hour mismatch
    4. If wheelies seem weak, watch the P: value — if it plateaus,
       try increasing LiftForce
    5. If riders keep getting interrupted, watch for STEER/OBSTACLE
       — you may need to increase MaxSteeringAngle or lower
       RaycastDistance
    6. Use a trainer to advance time if testing hour-restricted groups


===============================================================================
  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.

  - Wheelies too weak / bike doesn't go high enough?
    Increase LiftForce (try 0.25) and/or raise 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.

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