# Configuration

`Hostage System` uses a configuration file located in:

* `data/config.lua`

This file controls localization, usable item settings, timers, placement distances, preview behavior, target interaction, marker settings, surrender animations, and available NPC models.

### Localization

```lua
Locale = 'en' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

To add a new language, copy `locales/en.json` and create your own language file.

***

### Main Configuration

Example:

```lua
Locale = 'pl',

ItemName = 'kartazakladnika',

StayDuration = 60,
RunDuration = 1,

PlacementDistance = 10.0,
RegisterDistance = 15.0,
ResolveDistance = 5.0,

PreviewAlpha = 200,

Target = {
    icon = 'fas fa-handcuffs',
    distance = 2.0,
},

Marker = {
    type = 28,
    scale = vec3(0.15, 0.15, 0.15),
    color = { r = 79, g = 70, b = 229, a = 180 },
},
```

***

### Usable Item

```lua
ItemName = 'kartazakladnika'
```

Defines the item required to start hostage placement mode.

This item must exist in your inventory or framework setup.

***

### Timers

#### `StayDuration`

```lua
StayDuration = 60
```

Defines how long a placed hostage remains in the world before automatic removal.

This value is measured in minutes.

#### `RunDuration`

```lua
RunDuration = 1
```

Defines how long a freed or killed hostage remains before it is removed.

This value is measured in minutes.

***

### Distances

#### `PlacementDistance`

```lua
PlacementDistance = 10.0
```

Defines the maximum raycast distance used during hostage placement preview.

This value is measured in meters.

#### `RegisterDistance`

```lua
RegisterDistance = 15.0
```

Defines the maximum allowed server-side distance between the player and the ped when confirming hostage placement.

#### `ResolveDistance`

```lua
ResolveDistance = 5.0
```

Defines the maximum allowed server-side distance between the player and the hostage when freeing it.

***

### Preview

#### `PreviewAlpha`

```lua
PreviewAlpha = 200
```

Defines the transparency of the preview ped during placement.

Supported range:

* `0` to `255`

Lower values make the preview more transparent.

***

### Target Interaction

```lua
Target = {
    icon = 'fas fa-handcuffs',
    distance = 2.0,
}
```

#### `icon`

Defines the Font Awesome icon shown in the target interaction.

#### `distance`

Defines how close the player must be to interact with a hostage.

This value is measured in meters.

***

### Placement Marker

```lua
Marker = {
    type = 28,
    scale = vec3(0.15, 0.15, 0.15),
    color = { r = 79, g = 70, b = 229, a = 180 },
}
```

#### `type`

Defines the GTA marker type used during placement preview.

#### `scale`

Defines the marker size.

#### `color`

Defines the RGBA color of the marker.

***

### Surrender Animations

Players can switch between surrender animations during placement using the arrow keys.

Example:

```lua
ArrestAnims = {
    { label = 'Surrender 1', dict = 'mp_bank_heist_1', anim = 'f_cower_02' },
    { label = 'Surrender 2', dict = 'mp_bank_heist_1', anim = 'm_cower_01' },
    { label = 'Surrender 3', dict = 'mp_bank_heist_1', anim = 'm_cower_02' },
    { label = 'Surrender 4', dict = 'random@arrests',  anim = 'kneeling_arrest_idle' },
    { label = 'Surrender 5', dict = 'rcmbarry',        anim = 'm_cower_01' },
}
```

#### Fields

* `label` — displayed animation label
* `dict` — animation dictionary
* `anim` — animation name

To add a new animation, append another entry using a valid animation dictionary and animation name.

***

### NPC Models

A random NPC model is selected each time placement mode starts.

Example:

```lua
RandomNpcs = {
    `a_m_m_golfer_01`,
    `a_m_m_prolhost_01`,
    `a_f_y_hipster_03`,
    `csb_imran`,
}
```

These models use backtick hash syntax.

You can add or remove NPC models depending on the style you want for your server.

***

### Controls

During placement mode:

* `Left / Right Arrow` — rotate the hostage
* `Up / Down Arrow` — cycle through surrender animations
* `R` — confirm placement
* `X` — cancel placement

***

### Server-side Validation

The resource validates all important hostage actions on the server.

#### Placement Validation

When registering a hostage, the server checks:

* the player exists
* the player has the required item
* the hostage ped exists
* the hostage is within `RegisterDistance`

If valid, the item is removed and the hostage is marked using a state bag.

#### Resolve Validation

When freeing a hostage, the server checks:

* the player exists
* the hostage exists
* the hostage is within `ResolveDistance`

If valid, the hostage is marked as resolved and scheduled for removal.

#### Death Detection

The server periodically checks hostage ped health.

If a hostage dies, it is marked as resolved and scheduled for cleanup automatically.

#### Persistence

Placed hostages use orphan mode so they can remain valid even if the original placing player disconnects.

***

### State Bags

This resource uses state bags for hostage state tracking.

#### `isHostage`

Set on active hostage peds.

#### `isHostageResolved`

Set once the hostage has been freed or resolved.

Other resources can also read these values through:

```lua
Entity(ped).state
```

***

### Notes

* The hostage item must exist in your inventory or framework
* `msk_bridge` handles usable item registration
* Placement preview uses a non-networked transparent ped
* Only the confirmed hostage becomes a synced entity
* Freed or killed hostages are removed automatically
* All spawned hostages are cleaned up when the resource stops


---

# 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://mskscripts.gitbook.io/mskscripts/scripts/hostages/configuration.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.