> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dietrich-development.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install and configure the wild horse manager - blacklists, replacements, horse groups, and spawn districts

## Installation

<Steps>
  <Step title="Download">
    Get the latest release from our [Tebex store](https://tebex.dietrich-development.com) and download it from your [Keymaster](https://portal.cfx.re/assets/granted-assets)
  </Step>

  <Step title="Extract">
    Extract the `spooni_wildHorseManager` folder to your server's `resources` directory
  </Step>

  <Step title="Configure">
    Add `ensure spooni_wildHorseManager` to your `server.cfg`
  </Step>

  <Step title="Customize">
    Configure the `config.lua` file to your preferences (see the configuration section below)
  </Step>
</Steps>

## Configuration

The script is configured through the `config.lua` file. Here are the main configuration options:

### Blacklisting horses

Prevent specific horse models from spawning as wild horses:

```lua theme={null}
-- Prevent specific horse models from spawning as wild horses
Config.blackListHorses = {
    "a_c_horse_morgan_bayroan",
    "a_c_horse_arabian_white",
    -- Add more horse models as needed
}
```

### Replacing horse models

Automatically replace specific horse models with others when they spawn:

```lua theme={null}
-- Replace specific horse models with others when they spawn
Config.replaceHorse = {
    ['a_c_horse_tennesseewalker_blackrabicano'] = 'a_c_horse_mustang_grullodun',
    ['a_c_horse_arabian_white'] = 'a_c_horse_morgan_bayroan',
    -- Add more replacements as needed
}
```

### Defining horse groups

Group horses by breed for easier management:

```lua theme={null}
-- Group horses by breed for easier management
Config.horseGroups = {
    mustang = {
        'a_c_horse_mustang_goldendun',
        'a_c_horse_mustang_grullodun',
        'a_c_horse_mustang_silverbay',
        -- Add more horses to the group
    },
    thoroughbred = {
        'a_c_horse_thoroughbred_silverbay',
        'a_c_horse_thoroughbred_bloodbay',
        -- Add more horses to the group
    },
    -- Add more groups as needed
}
```

### Configuring spawn districts

Define which horse groups spawn in which regions:

```lua theme={null}
-- Define which horse groups spawn in which regions
Config.Districts = {
    ['Great Plains'] = {
        groups = {'mustang', 'thoroughbred'},
        -- Additional district-specific settings can be added here
    },
    ['Heartlands'] = {
        groups = {'thoroughbred', 'morgan'},
        -- Additional district-specific settings
    },
    -- Add more districts as needed
}
```

<Note>
  District names should match the actual region names in your RedM server. You can use the debug commands to help identify the correct district names.
</Note>

## Debugging

Enable debug mode in the config to access debugging features:

```lua theme={null}
Config.debug = true
```

### Available debug commands

<AccordionGroup>
  <Accordion title="/npcSlots">
    Shows information about ped slots that might be blocking horse spawns. This is useful for troubleshooting when horses aren't spawning in expected locations.
  </Accordion>

  <Accordion title="/findHorse">
    Toggles display of scenario points for horse spawning. This visual debug tool helps you see where horses are configured to spawn and verify your district configurations.
  </Accordion>
</AccordionGroup>

<Warning>
  Debug mode should only be enabled when troubleshooting. Disable it in production to maintain optimal performance.
</Warning>

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  -- No additional configuration required
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  -- No additional configuration required
  ```

  ```lua Custom Framework theme={null}
  -- Set in config.lua
  Config.Framework = 'custom'

  -- Requires additional configuration in frameworkBridge.lua
  -- See framework bridge documentation for details
  ```
</CodeGroup>

## Performance considerations

<Info>
  The script is optimized for performance, but here are some tips to ensure smooth operation:
</Info>

* **Limit horse groups**: Don't create too many horse groups as this can impact spawn calculations
* **Reasonable blacklists**: Keep blacklists focused on problematic horses rather than excluding large numbers
* **District optimization**: Configure districts based on actual player activity areas
* **Debug mode**: Remember to disable debug mode in production

## Troubleshooting

<AccordionGroup>
  <Accordion title="Horses not spawning">
    * **District name**: Check if the district name matches exactly (case-sensitive)
    * **Horse models**: Verify horse model names are correct
    * **Spawn points**: Use the `/findHorse` debug command to see spawn points
    * **Blacklist**: Check if horses are blacklisted
  </Accordion>

  <Accordion title="Performance issues">
    * **Debug mode**: Disable debug mode in production
    * **Horse groups**: Reduce the number of horse groups
    * **Group size**: Limit the number of horses per group
    * **Error logs**: Check the server console for error messages
  </Accordion>

  <Accordion title="Framework compatibility">
    * **Framework detection**: Ensure your framework is properly detected
    * **Custom setup**: Check frameworkBridge.lua for custom framework setup
    * **Event verification**: Verify framework events are working correctly
  </Accordion>
</AccordionGroup>

## Support

If you encounter issues or need assistance:

<Columns cols={2}>
  <Card title="Discord support" icon="discord" href="https://discord.gg/4jhQsPr6pe">
    Join our Discord community for support and updates.
  </Card>

  <Card title="Documentation" icon="book" href="/">
    Docs home - installation basics and links to every script.
  </Card>
</Columns>