# Crowe Fast Travel System

A comprehensive fast travel system for RedM servers with VORP integration, allowing players to quickly travel between water ports and river docks across the map.

## Features

### 🎯 **Core Functionality**

* **Fast Travel Menu**: Players can open an HTML popup UI to select destinations
* **Location Grid**: Clean grid layout displaying available travel locations with images, names, and prices
* **VORP Integration**: Money deduction and notifications using VORP Core API
* **Smart Teleportation**: Smooth teleportation with fade effects and delay
* **Modern Web Interface**: Responsive UI styled for RedM's Wild West theme
* **Cinematic Scenes**: Immersive boat departure animations for each location
* **NPC Workers**: Dynamic dock workers that spawn near fast travel points
* **Performance Optimized**: Intelligent NPC spawning/despawning and distance-based optimization

### 🗺️ **Travel Locations**

* **Water Ports & Docks**: All locations are strategically placed near water ports and river docks
* **8 Unique Destinations**: Including major towns like Saint Denis, Blackwater, Annesburg, and more
* **Scenic Spots**: Special locations like Guarma Port, Quaker's Cove, and San Luis Port
* **All Locations Unlocked**: All destinations are available by default (no unlock requirements)

### ⚙️ **System Features**

* **Dynamic Pricing**: Each location has its own travel cost ($5-$10)
* **Cooldown System**: Configurable cooldown between fast travels (currently disabled)
* **Money Validation**: Real-time money checking and insufficient funds prevention
* **Responsive Design**: UI works perfectly on all screen sizes
* **Advanced Notification System**: Support for Crowe Notification, Crowe Libs, and VORP fallback
* **Crowe Libs Integration**: Enhanced spawn detection and performance optimization

## Installation

1. **Dependencies**: Ensure you have `vorp_core` installed (optional: `crowe_libs`, `crowe_notification`)
2. **Resource Setup**: Place the resource in your `resources` folder
3. **Configuration**: Customize `config.lua` for your server's needs
4. **Start Resource**: Add `ensure crowe_fasttravel` to your server.cfg

## Configuration

### Basic Settings

```lua
Config.FastTravelKey = 0x760A9C6F       -- G key to open fast travel menu
-- Command access (server-gated)
Config.FastTravelCommand = 'fasttravel'  -- Command to open fast travel menu
Config.EnableFastTravelCommand = true    -- Toggle: enable/disable the /fasttravel command entirely
Config.CommandRequiresPermission = true  -- If true, only configured players can use the command
Config.TeleportDelay = 2000              -- Delay in ms before teleport
Config.AccessRadius = 3.0                -- Distance to interact with fast travel points
Config.UseCooldown = false               -- Enable cooldown between fast travels
Config.CooldownTime = 30                 -- Cooldown time in seconds
```

### Performance Settings

```lua
Config.npcSpawnDistance = 20.0          -- Distance to spawn NPCs
Config.npcDespawnDistance = 25.0        -- Distance to despawn NPCs
Config.sleepDistanceFar = 750            -- Sleep time when far from locations
Config.sleepDistanceClose = 100          -- Sleep time when near locations
```

### Adding Custom Locations

```lua
{
    id = "my_custom_dock",
    name = "My Custom Dock",
    description = "A beautiful custom location",
    coords = vector3(100.0, 200.0, 30.0),
    price = 25,
    image = "my_custom_dock.jpg",
    blipColor = 2,
    requiresUnlock = false,
    spawnCoords = vector4(105.0, 205.0, 30.5, 90.0),
    npcSettings = {
        pedHash = "u_m_m_nbxboatticketseller_01",
        coords = vector4(100.0, 200.0, 30.0, 180.0),
        ped = nil
    },
    cinematicScene = {
        enabled = true,
        boatModel = "boatsteam02x"
    }
}
```

## Default Locations

### **Major Ports**

* **Saint Denis Port** ($5) - Main commercial port of the bustling city
* **Blackwater Port** ($5) - Major port town on the Upper Montana River
* **Annesburg Port** ($5) - Northern mining town port on the Kamassa River
* **Van Horn Port** ($5) - Industrial port town on the Lannahechee River

### **Scenic Locations**

* **Guarma Port** ($10) - Tropical island paradise with pristine beaches
* **Quaker's Cove** ($8) - Secluded waterfront settlement with rustic charm
* **San Luis Port** ($8) - Scenic port town nestled in arid mountain terrain
* **Thieves Landing** ($8) - Misty waterfront settlement with mysterious atmosphere

## Usage

### For Players

1. **At Fast Travel Points**: Approach any dock/port and press **G** to open the fast travel menu
2. **Command Access**: Use `/fasttravel` command to open the menu from anywhere (if enabled)
3. **Select Destination**: Click on any location card in the grid
4. **Confirm Travel**: Review the cost and confirm your travel in the popup
5. **Enjoy the Journey**: Experience smooth teleportation with cinematic boat scenes

### For Admins

1. **Admin Teleport**: Use `/tpft [location_id]` to teleport instantly to any location
2. **List Locations**: Use `/listft` to see all available fast travel locations
3. **Clear Cooldowns**: Use `/clearftcd [player_id]` to clear a player's fast travel cooldown
4. **Configuration**: All locations, prices, and settings are in `config.lua`

## UI Features

### **Location Cards**

* **Image Previews**: Each location shows a preview image
* **Pricing Display**: Clear cost indication for each destination
* **Hover Effects**: Interactive hover animations and effects
* **Grid Layout**: Clean 3-column grid layout

### **Confirmation System**

* **Travel Confirmation**: Double-check dialog before committing to travel
* **Cost Breakdown**: Clear display of travel cost vs available money
* **Smart Validation**: Prevents travel if insufficient funds

### **Theme System**

* **Modern Black & Red Theme**: Professional dark theme with red accents
* **Responsive Design**: Works perfectly on all screen sizes
* **Smooth Animations**: Professional transitions and feedback

## Commands

### Player Commands

* `/fasttravel` - Open the fast travel menu (subject to server toggle and permissions)

### Admin Commands

* `/tpft [location_id]` - Teleport to a fast travel location (Admin only)
* `/listft` - List all fast travel locations in console (Admin only)
* `/clearftcd [player_id]` - Clear a player's fast travel cooldown (Admin only)

## Technical Details

### **Money Integration**

* Uses VORP Core's money system (`Character.money` and `Character.removeCurrency`)
* Real-time money validation before travel
* Automatic money deduction on successful travel

### **Notification System**

* **Priority Order**: Crowe Notification > Crowe Libs > VORP Toast Fallback
* **Enhanced Features**: Support for different notification types and animations
* **Automatic Detection**: Automatically detects available notification systems

### **Permissions and Command Control**

* Server-gated `/fasttravel` command with configurable toggle and access lists
* Set `Config.EnableFastTravelCommand = false` to fully disable the command
* Set `Config.CommandRequiresPermission = true` and configure:
  * `Config.Permissions.commandPermissions` (ACE groups like `group.vip`)
  * `Config.Permissions.commandIdentifiers` (specific identifiers)

### **Performance Optimization**

* **Intelligent NPC Management**: NPCs only spawn when players are nearby
* **Distance-Based Optimization**: Different sleep times based on proximity
* **Resource Cleanup**: Automatic cleanup on resource restart/stop

### **Cinematic Scene System**

* **Boat Departure Scenes**: Immersive boat departure animations
* **Custom Camera Positions**: Unique camera angles for each location
* **Multiple Boat Models**: Different boat types for different locations
* **Emergency Exit**: ESC key to exit scenes immediately

## Dependencies

* **vorp\_core** - Core framework for RedM (required)
* **crowe\_libs** - Enhanced spawn detection and performance (optional)
* **crowe\_notification** - Advanced notification system (optional)
* **Modern Browser** - For HTML UI rendering

## Customization

### **Adding Images**

1. Place location images in `web/images/` folder
2. Update the `image` field in your location config
3. Supported formats: JPG, PNG, WebP

### **Cinematic Scenes**

Each location can have a cinematic scene configuration:

```lua
cinematicScene = {
    enabled = true,
    boatModel = "boatsteam02x"  -- Boat model to spawn
}
```

### **NPC Workers**

Configure dock workers for each location:

```lua
npcSettings = {
    pedHash = "u_m_m_nbxboatticketseller_01",
    coords = vector4(x, y, z, heading),
    ped = nil  -- Will be set by client
}
```

### **Custom Unlock Logic**

Modify the `IsLocationUnlocked` function in `config.lua` to implement your custom unlock requirements:

```lua
function IsLocationUnlocked(locationId, playerData)
    -- Add your custom logic here
    -- Check player progress, completed missions, etc.
    return true -- or false
end
```

## Support

This is part of the Crowe Scripts collection. The system is designed to be:

* **Easy to Install**: Minimal setup required
* **Highly Configurable**: Extensive customization options
* **Performance Optimized**: Efficient resource usage with intelligent optimization
* **User Friendly**: Intuitive interface for players
* **Cinematic Experience**: Immersive boat departure scenes

## License

MIT License - See LICENSE file for details

## Changelog

### Version 1.0.0

* Initial release of Crowe Fast Travel System
* 8 pre-configured water port and dock locations
* Full VORP integration with money system
* Responsive web UI with modern black & red theme
* Admin management commands
* Cinematic boat departure scenes
* Dynamic NPC workers with performance optimization
* Advanced notification system with multiple fallbacks
* Crowe Libs integration for enhanced spawn detection


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crowescripts.gitbook.io/documentation/about-our-scripts/redm-script-documentation/crowe-fast-travel-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.