# Crowe Land Travel System

A comprehensive land travel system for RedM servers with VORP integration, allowing players to quickly travel between stagecoach stations and travel points across the map. This system was completely remade from the original boat travel system to provide an authentic Wild West stagecoach experience.

## Features

### 🎯 **Core Functionality**

* **Land 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 stagecoach departure animations for each location
* **NPC Workers**: Dynamic stagecoach drivers that spawn near travel points
* **Performance Optimized**: Intelligent NPC spawning/despawning and distance-based optimization

### 🗺️ **Travel Locations**

* **Stagecoach Stations & Travel Points**: All locations are strategically placed at major stagecoach stations
* **13 Unique Destinations**: Including major towns like Saint Denis, Blackwater, Valentine, and more
* **Scenic Spots**: Special locations like Tumbleweed, Rhodes, Strawberry, and Colter
* **All Locations Unlocked**: All destinations are available by default (no unlock requirements)

### ⚙️ **System Features**

* **Dynamic Pricing**: Each route has its own travel cost based on distance and terrain ($5-$45)
* **Cooldown System**: Configurable cooldown between 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_landtravel` to your server.cfg

## Configuration

### Basic Settings

```lua
Config.LandTravelKey = 0x760A9C6F       -- G key to open land travel menu
-- Command access (server-gated)
Config.LandTravelCommand = 'landtravel'  -- Command to open land travel menu
Config.EnableLandTravelCommand = true    -- Toggle: enable/disable the /landtravel 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 travel points
Config.UseCooldown = false               -- Enable cooldown between 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_station",
    name = "My Custom Station",
    description = "A beautiful custom location",
    coords = vector3(100.0, 200.0, 30.0),
    price = 25,
    image = "my_custom_station.jpg",
    blipColor = 2,
    requiresUnlock = false,
    spawnCoords = vector4(105.0, 205.0, 30.5, 90.0),
    npcSettings = {
        pedHash = "u_m_m_stagecoachdriver_01",
        coords = vector4(100.0, 200.0, 30.0, 180.0),
        ped = nil
    },
    cinematicScene = {
        enabled = true,
        coachModel = "coach2"
    }
}
```

## Default Locations

### **Major Cities**

* **Valentine Stagecoach Station** ($5) - Bustling frontier town with a major stagecoach hub
* **Saint Denis Stagecoach Station** ($5) - Main commercial hub with extensive stagecoach network
* **Blackwater Stagecoach Station** ($5) - Major trading hub with extensive stagecoach connections
* **Annesburg Stagecoach Station** ($5) - Northern mining town with stagecoach service to major cities

### **Scenic Locations**

* **Van Horn Stagecoach Station** ($5) - Industrial port town with stagecoach connections to the north
* **Tumbleweed Stagecoach Station** ($8) - Desert frontier town with stagecoach service to civilization
* **Rhodes Stagecoach Station** ($8) - Southern plantation town with stagecoach connections
* **Strawberry Stagecoach Station** ($8) - Mountain town with stagecoach service through scenic routes
* **Colter Stagecoach Station** ($10) - Northern mining settlement with extreme mountain terrain
* **Limpany Stagecoach Station** ($6) - Burned-out town with connections to nearby settlements
* **Armadillo Stagecoach Station** ($8) - Desert trading post with stagecoach service
* **Emerald Ranch Stagecoach Station** ($6) - Agricultural community with stagecoach connections
* **MacFarlane's Ranch Stagecoach Station** ($7) - Family ranch with stagecoach service

## Usage

### For Players

1. **At Travel Points**: Approach any stagecoach station and press **G** to open the land travel menu
2. **Command Access**: Use `/landtravel` 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 stagecoach 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 land travel locations
3. **Clear Cooldowns**: Use `/clearftcd [player_id]` to clear a player's 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

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

### Admin Commands

* `/tpft [location_id]` - Teleport to a land travel location (Admin only)
* `/listft` - List all land travel locations in console (Admin only)
* `/clearftcd [player_id]` - Clear a player's 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 `/landtravel` command with configurable toggle and access lists
* Set `Config.EnableLandTravelCommand = 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**

* **Stagecoach Departure Scenes**: Immersive stagecoach departure animations
* **Custom Camera Positions**: Unique camera angles for each location
* **Multiple Coach Models**: Different coach 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,
    coachModel = "coach2"  -- Coach model to spawn
}
```

### **NPC Workers**

Configure stagecoach drivers for each location:

```lua
npcSettings = {
    pedHash = "u_m_m_stagecoachdriver_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 stagecoach departure scenes

## License

MIT License - See LICENSE file for details

## Changelog

### Version 1.0.1

* **Expanded Location System**: Added 5 new locations (Colter, Limpany, Armadillo, Emerald Ranch, MacFarlane's Ranch)
* **Enhanced Dynamic Pricing**: Implemented route-specific pricing based on distance and terrain
* **Improved Cinematic Scenes**: Added custom camera positions and optimized stagecoach models for each location
* **Performance Enhancements**: Better NPC management and spawn detection systems
* **Bug Fixes**: Resolved initialization issues and improved resource stability

### Version 1.0.0

* Initial release of Crowe Land Travel System
* 8 pre-configured stagecoach station locations
* Full VORP integration with money system
* Responsive web UI with modern black & red theme
* Admin management commands
* Cinematic stagecoach 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-land-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.