AI Taxi User Guide

This guide outlines the end-to-end passenger experience with MTM-TAXI, explaining how the autonomous chauffeur interacts with the player, interprets map waypoints, and handles edge cases such as off-road destinations.

---

The Passenger Journey

[Hail Taxi] --> [Approach & Pickup] --> [Board Cab] --> [Set Map Waypoint] --> [Autonomous Ride] --> [Arrival & Exit]

---

1. Hailing the Taxi

Passengers can call an automated taxi through multiple methods depending on your server’s configuration:

• By running the chat command /calltaxi.
• By pressing a designated shortcut key if configured.
• Through a taxi or rideshare application on an in-game smartphone.

Initial Location Check

When the request is submitted, the system checks whether the player is within reachable distance of a paved road:

• Near a Road: If the player is within Config.spawnDistance (default 75 meters) of a valid road node, the driver accepts the fare. A confirmation message appears stating that the taxi is on its way.
• Too Far From a Road: If the player is located in the wilderness, on a skyscraper rooftop, or swimming in the ocean, the system informs the player that the driver cannot reach their location.

---

2. Approach and Pickup

Once dispatched:

1. The taxi spawns approximately 50 to 80 meters down the street along an existing road node.
2. If Config.showBlip is enabled, a flashing yellow taxi icon appears on the passenger’s radar and map, showing the cab’s real-time approach.
3. As the taxi approaches within 20 meters of the player, the AI driver slows down, pulls to the roadside curb, and sets the handbrake.
4. The vehicle doors unlock for passenger entry.

---

3. Boarding the Cab

Boarding is completely seamless:

• Approach the taxi and press the standard vehicle entry key (F or Y on controller).
• An intelligent entry thread automatically routes the player into the designated rear passenger seat (Config.seatUsed = 2, rear right), ensuring the driver ped is never ejected.
• Once the passenger is seated, the vehicle door shuts, the temporary map blip is cleared, and an on-screen prompt instructs the passenger to set a destination waypoint.

---

4. Setting Your Destination Waypoint

To instruct the driver where to go:

1. Press Escape or P to open the GTA V pause menu map.
2. Right-click or press the waypoint button to drop a purple destination marker on your desired location.
3. Return to the game.

The AI chauffeur detects the newly placed waypoint instantly, releases the handbrake, and begins driving along the optimal street route.

---

5. In-Transit Navigation & Off-Road Refusal

While en route, the driver utilizes GTA V’s native traffic pathfinding logic (TaskVehicleDriveToCoord with driving style 786603):

• Honors standard traffic signals and yields appropriately at intersections.
• Maneuvers smoothly around stalled or parked vehicles.
• Adjusts speed dynamically to match the flow of traffic.

How Does the Driver Handle Off-Road Destinations?

If a passenger places their waypoint on top of Mount Chiliad, in the middle of a dirt construction pit, or in the ocean:

[Waypoint Placed Off-Road] --> [Road Distance > 40m] --> [Driver Pulls Over & Halts] --> [Prompts Valid Waypoint]

1. The script measures the distance from the waypoint to the nearest drivable road node.
2. If the distance exceeds Config.maxWaypointRoadDistance (default 40 meters), the driver recognizes that the destination cannot be reached by a standard passenger car.
3. The cab safely slows down, pulls over to the side of the road, engages the handbrake, and informs the passenger:

   "I cannot drive there, please set a destination near a road."

4. The cab remains stationary until the passenger moves the map waypoint to a legitimate street or parking lot.

---

6. Arrival and Exit

When the taxi arrives within 30 meters of the destination road coordinate:

1. The driver smoothly decelerates and brings the vehicle to a full stop.
2. The handbrake is locked, and a prompt is displayed:

   "You have arrived at your destination, you can now exit."

3. The passenger presses F to step out of the cab.

---

7. Automatic Despawn & Cleanup

After the passenger exits the vehicle:

• The taxi doors lock automatically to prevent other players from stealing the vehicle.
• The AI driver resumes ambient traffic driving and wanders away smoothly.
• After a configurable delay (Config.deleteTaxiTimer, default 6 seconds), both the vehicle and driver ped entities are cleanly deleted from the world.
• All internal client states reset, freeing up memory and allowing the player to call another taxi whenever needed.