> For the complete documentation index, see [llms.txt](https://kharan-studio.gitbook.io/kharanstudio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kharan-studio.gitbook.io/kharanstudio/custom-peds/the-grums.md).

# The Grums

The Grums brings a new custom creature species to RedM.  Hidden throughout the world, players can discover mysterious Grum burrows inhabited by small creatures wandering around their home. Approach on

{% embed url="<https://youtu.be/AVvNMY-3Whk>" %}

### 1. Requirements

To install KH Grums, your server must have:

* A functioning RedM server with synchronized network entity support.
* Either VORP or RSG as its framework.
* The corresponding inventory resource:
  * VORP: `vorp_inventory`
  * RSG: `rsg-inventory`

The resource does not require a separate database table for its creature populations or companions.

### 2. Installation

#### Step 1 — Install the Resource

Extract your purchased package and place the `kh_grums` directory inside your server's resources folder.

Make sure you retain the original folder name.

#### Step 2 — Configure Your Framework

Open `kh_grums/config.lua` and select your framework.

```lua
Config.Framework = 'vorp'
```

For RSG servers:

```lua
Config.Framework = 'rsg'
```

Framework selection is manual. Automatic detection is not available in version 1.0.2.

#### Step 3 — Register the Inventory Item

**VORP Installation**

Register the `grum` item in your VORP database. The following example uses common VORP item-table columns:

```sql
INSERT IGNORE INTO `items`
(`item`, `label`, `limit`, `can_remove`, `type`, `usable`)
VALUES
('grum', 'Grum', 1, 1, 'item_standard', 1);
```

Adjust this definition if your inventory version requires additional columns, such as weight or description.

If the item already exists, check that it is usable and configured with your preferred inventory limit.

**RSG Installation**

KH Grums attempts to register the inventory item automatically.

If your framework version does not support dynamic item registration, add the following definition inside `rsg-core/shared/items.lua`:

```lua
['grum'] = {
    name = 'grum',
    label = 'Grum',
    weight = 100,
    type = 'item',
    image = 'grum.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'A small captured Grum. Use it to call or dismiss your companion.'
},
```

Do not register the item twice.

**Inventory Images**

The default item icon filename is `grum.png`. You must provide your own PNG file, as this image is not included in the current package.

Common inventory image directories:

* VORP: `vorp_inventory/html/img/items/`
* RSG: `rsg-inventory/html/images/`

#### Step 4 — Start the Resource

Add the resource to your `server.cfg`, ensuring it starts after your framework and inventory.

VORP:

```cfg
ensure vorp_core
ensure vorp_inventory
ensure kh_grums
```

RSG:

```cfg
ensure rsg-core
ensure rsg-inventory
ensure kh_grums
```

Retain any additional dependencies required by your framework.

Restart the server after completing the installation.

***

### 3. Configuration Reference

All public settings are available in `kh_grums/config.lua`.

#### General Settings

| Setting            | Default  | Description                                             |
| ------------------ | -------- | ------------------------------------------------------- |
| `Config.Framework` | `'vorp'` | Selects VORP or RSG.                                    |
| `Config.Locale`    | `'en'`   | Selects the language. English and Spanish are included. |
| `Config.Debug`     | `false`  | Enables additional diagnostic console output.           |

#### Inventory Configuration

```lua
Config.Item = {
    Name = 'grum',
    Weight = 100,
    Image = 'grum.png',
    MaxAmount = 1
}
```

| Setting     | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `Name`      | Inventory item identifier. Must match the registered inventory item. |
| `Weight`    | Item weight used during automatic RSG item registration.             |
| `Image`     | Inventory image filename used for automatic RSG registration.        |
| `MaxAmount` | Maximum Grum items allowed when awarding captures through RSG.       |

**VORP note:** Weight and inventory limits are managed through VORP Inventory's item database. The RSG-specific weight and maximum-amount settings do not modify VORP item definitions.

For RSG, setting `MaxAmount` to `0` removes the script's specific item-count restriction, but standard inventory capacity restrictions still apply.

#### Audio Configuration

```lua
Config.Audio = {
    MaxDistance = 28.0,
    Volume = 0.45
}
```

| Setting       | Description                                              |
| ------------- | -------------------------------------------------------- |
| `MaxDistance` | Maximum hearing distance for Grum voices, in game units. |
| `Volume`      | Maximum audio volume, from `0.0` to `1.0`.               |

KH Grums includes 11 creature voice files.

Voices play at intermittent intervals, with their volume automatically adjusted according to the player's distance from the creature.

The audio system also recognizes Grums spawned through compatible external ped-spawning resources.

#### Capture Configuration

```lua
Config.Capture = {
    Enabled = true,
    SequenceLength = 4,
    StepTime = 850
}
```

| Setting          | Description                                  |
| ---------------- | -------------------------------------------- |
| `Enabled`        | Enables or disables the capture system.      |
| `SequenceLength` | Number of correct key presses required.      |
| `StepTime`       | Time allowed per key press, in milliseconds. |

**Difficulty examples:**

Easy:

```lua
SequenceLength = 3,
StepTime = 1200
```

Normal:

```lua
SequenceLength = 4,
StepTime = 850
```

Hard:

```lua
SequenceLength = 6,
StepTime = 600
```

Increasing the sequence length or decreasing the reaction time makes capturing a Grum more challenging.

The standard capture control is **E**.

#### Companion Configuration

```lua
Config.Pet = {
    CarryEnabled = true
}
```

`CarryEnabled` controls whether players can pick up their companion and carry it on their shoulders.

When enabled, players can approach their Grum and press **G** to pick it up. Pressing **G** again puts it down.

When disabled, the companion remains a following pet without the shoulder-carrying interaction.

#### Burrow System Configuration

```lua
Config.BurrowSystem = {
    Enabled = true,
    MinGrums = 4,
    MaxGrums = 6,

    Locations = {
        -- Configured burrow locations
    }
}
```

| Setting     | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `Enabled`   | Enables or disables the automatic wild burrow system.            |
| `MinGrums`  | Minimum Grums spawned in a populated burrow.                     |
| `MaxGrums`  | Maximum Grums spawned in a populated burrow.                     |
| `Locations` | Defines the burrow positions, rotations, and optional campfires. |

Ensure `MaxGrums` is equal to or greater than `MinGrums`.

Each burrow entry supports a name, world coordinates, quaternion rotation, and an optional campfire.

**Example location:**

```lua
{
    name = 'Burrow 1',
    coords = vector3(
        -928.018494,
        1547.476318,
        238.683151
    ),

    rotation = {
        x = 0.027621,
        y = 0.041240,
        z = 0.898820,
        w = 0.435498
    },

    campfire = {
        coords = vector3(
            -929.242249,
            1547.823853,
            237.289337
        ),

        rotation = {
            x = 0.030456,
            y = 0.049454,
            z = 0.943930,
            w = 0.324998
        }
    }
},
```

You can add, relocate, or remove burrows by editing the `Locations` table.