> ## 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 ambient ped manager - relationships, spawn frequencies, restrictions, and model replacements

## 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_ambientPedManager` folder to your server's `resources` directory
  </Step>

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

  <Step title="Customize">
    Edit `config.lua` to match your server logic and requirements
  </Step>
</Steps>

## Configuration

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

### Relationship types

Define the numeric values for each relationship type:

```lua theme={null}
-- Relationship type definitions
RelationshipTypes = {
    HATE = 6,
    DISLIKE = 4,
    IGNORE = 3,
    LIKE = 2,
    RESPECT = 1,
    NONE = 0
}
```

### Group relationships

Set static relationships between two AI groups:

```lua theme={null}
-- Define how AI groups interact with each other
GroupRelationships = {
    rel_civmale = {
        rel_civfemale = "LIKE",
        rel_vanhorn_citizen = "HATE"
    },
    rel_cop = {
        rel_civmale = "RESPECT",
        rel_civfemale = "RESPECT"
    }
    -- Add more group relationships as needed
}
```

### Player relations

Configure how groups behave around the player:

```lua theme={null}
-- Player relationship configuration
PlayerRelations = {
    Enabled = true,
    BehaviorAroundPlayer = {
        rel_cop = "RESPECT",
        rel_civmale = "LIKE",
        rel_civfemale = "LIKE"
    }
}
```

### Conditional rules

Dynamic rules based on game context (time, job, weather, etc.):

```lua theme={null}
-- Conditional relationship rules
ConditionalRules = {
    {
        condition = function()
            return GetClockHours() >= 20 or GetClockHours() <= 5
        end,
        between = { "player", "rel_civmale" },
        relation = "HATE"
    },
    {
        condition = function()
            return IsPedInAnyVehicle(PlayerPedId(), false)
        end,
        between = { "rel_cop", "rel_civmale" },
        relation = "RESPECT"
    }
    -- Add more conditional rules as needed
}
```

<Note>
  Use `"player"` in conditional rules to dynamically resolve the player's group. The `rel_cop` group maintains persistent relationships via a background loop.
</Note>

### Spawn frequency

Set global ambient spawn values (0.0-1.0):

```lua theme={null}
-- Global spawn frequency settings
spawnFrequency = {
    pedFrequency = 1.0,      -- General ped spawn rate
    humanFrequency = 0.5,    -- Human ped spawn rate
    animalFrequency = 1.0,   -- Animal spawn rate
    trafficFrequency = 0.0   -- Vehicle traffic spawn rate
}
```

### Location-specific spawn frequency

Area-specific spawn density overrides:

```lua theme={null}
-- Location-based spawn frequency overrides
spawnFrequencyLocations = {
    huntingEvent = {
        coords = { x = -1500.0, y = 500.0, z = 100.0 },
        radius = 1500.0,
        humanFrequency = 0.0,    -- No humans in hunting area
        animalFrequency = 1.0    -- Maximum animals for hunting
    },
    townCenter = {
        coords = { x = -300.0, y = 800.0, z = 120.0 },
        radius = 200.0,
        humanFrequency = 1.0,    -- High human activity
        animalFrequency = 0.0    -- No animals in town center
    }
    -- Add more location-specific settings
}
```

### Location restrictions

Restrict or allow ped types in volumes (box or sphere):

```lua theme={null}
-- Volume-based ped restrictions
locationRestrictions = {
    BlackWaterSaloon = {
        volumeName = "volumeBlackWaterSaloonAmbientRestriction",
        coords = { x = -800.0, y = -1300.0, z = 45.0 },
        disallowHumanPeds = { disallowAll = true },
        disallowAnimalPeds = { disallowAll = true }
    },
    HuntingZone = {
        volumeName = "volumeHuntingZoneRestriction",
        coords = { x = -1500.0, y = 500.0, z = 100.0 },
        disallowHumanPeds = { disallowAll = true },
        allowAnimalPeds = { allowAll = true }
    }
    -- Add more location restrictions
}
```

### Model replacements

Replace ped appearances visually in a zone:

```lua theme={null}
-- Visual model replacement settings
modelReplacements = {
    armadilloTownfolk = {
        coords = { x = -3500.0, y = -2000.0, z = 150.0 },
        radius = 90.0,
        targetModels = { 'A_M_M_ARMTOWNFOLK_01' },
        replacementModels = { 's_m_m_ambientsdpolice_01' }
    },
    valentineLawmen = {
        coords = { x = -300.0, y = 800.0, z = 120.0 },
        radius = 150.0,
        targetModels = { 'A_M_M_VALPROSPECTOR_01' },
        replacementModels = { 'S_M_M_VALGUNSMITH_01' }
    }
    -- Add more model replacements
}
```

<Warning>
  Model types must match (e.g., human with human, horse with horse). Model replacements only affect visual appearance, not base behavior.
</Warning>

## Advanced configuration

### Custom conditions

Define custom conditions as Lua functions directly in the config:

```lua theme={null}
-- Example custom conditions
CustomConditions = {
    isNightTime = function()
        local hour = GetClockHours()
        return hour >= 22 or hour <= 6
    end,
    
    isRaining = function()
        return GetPrevWeatherTypeHashName() == GetHashKey("RAIN")
    end,
    
    playerInVehicle = function()
        return IsPedInAnyVehicle(PlayerPedId(), false)
    end
}
```

### Debug mode

Enable verbose logging for development:

```lua theme={null}
-- Debug configuration
Config.debug = true
Config.ConditionCheckTimer = 1000  -- Check interval in milliseconds
```

## Usage examples

### Creating faction conflicts

```lua theme={null}
-- Example: Van Horn vs Saint Denis citizens
GroupRelationships = {
    rel_vanhorn_citizen = {
        rel_saintdenis_citizen = "HATE"
    },
    rel_saintdenis_citizen = {
        rel_vanhorn_citizen = "HATE"
    }
}
```

### Time-based behavior

```lua theme={null}
-- Example: Lawmen more aggressive at night
ConditionalRules = {
    {
        condition = function()
            return GetClockHours() >= 22 or GetClockHours() <= 6
        end,
        between = { "rel_cop", "player" },
        relation = "DISLIKE"
    }
}
```

### Event zones

```lua theme={null}
-- Example: Hunting event area
spawnFrequencyLocations = {
    huntingEvent = {
        coords = { x = -1500.0, y = 500.0, z = 100.0 },
        radius = 1500.0,
        humanFrequency = 0.0,
        animalFrequency = 1.0,
        pedFrequency = 0.0
    }
}
```

## Performance considerations

<Info>
  The script is optimized for performance with several key features:
</Info>

* **Conditional checking**: Configurable tick rate via `ConditionCheckTimer`
* **Volume-based restrictions**: Efficient area-based ped control
* **Selective spawning**: Location-specific spawn density management
* **Background processing**: Persistent relationship maintenance for critical groups

### Performance tips

* **Check timer**: Increase `ConditionCheckTimer` for less frequent condition checks
* **Volume optimization**: Use appropriate volume sizes for restrictions
* **Spawn limits**: Set reasonable spawn frequencies to prevent performance issues
* **Debug mode**: Disable debug mode in production for optimal performance

## Troubleshooting

<AccordionGroup>
  <Accordion title="Relationships not working">
    Verify group names are correct, check that conditional functions return proper boolean values, and ensure the script is properly started in your server.cfg.
  </Accordion>

  <Accordion title="Spawn restrictions not applying">
    Confirm volume names exist in the game map or are manually created, check coordinate accuracy, and verify spawn frequency values are between 0.0 and 1.0.
  </Accordion>

  <Accordion title="Model replacements not visible">
    Ensure model types match (human with human, animal with animal), verify coordinates and radius are correct, and check that target models exist on your server.
  </Accordion>

  <Accordion title="Performance issues">
    Reduce condition check frequency, limit the number of conditional rules, optimize volume sizes, and disable debug mode in production.
  </Accordion>

  <Accordion title="Volume restrictions not working">
    Verify volume names are valid, check coordinate positioning, and ensure the volume is properly defined in the game world or created manually.
  </Accordion>
</AccordionGroup>

## 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>

## 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>