# Configuration

`3D Scene Description` uses a configuration file located in:

* `data/config.lua`

This file controls general settings, rendering behavior, server cleanup, restricted zones, commands, and custom fonts.

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

***

### General Configuration

```lua
MaxDistance = 25,
DefaultText = "Sample Text",
```

#### `MaxDistance`

Defines the maximum raycast distance in meters when placing a scene.

```lua
MaxDistance = 25
```

#### `DefaultText`

Defines the placeholder text shown when the scene text is empty.

```lua
DefaultText = "Sample Text"
```

***

### Rendering Configuration

```lua
Text = {
    baseFov = 75,
    baseScale = 4,
    heightOffset = 0.0030,
    widthOffset = 0.005,
    shadow = { distance = 1, r = 0, g = 0, b = 0, a = 255 },
},
```

These settings control how scenes are rendered in the world.

#### `baseFov`

Base field of view value used for scaling.

#### `baseScale`

Base text scale used for rendering.

#### `heightOffset`

Vertical offset applied to text rendering.

#### `widthOffset`

Horizontal offset applied to text rendering.

#### `shadow`

Controls the text shadow settings.

Example:

```lua
shadow = { distance = 1, r = 0, g = 0, b = 0, a = 255 }
```

***

### Thread Configuration

```lua
Threads = {
    closestCheckInterval = 1000,
    renderSleepInterval = 1000,
    renderActiveInterval = 0,
    initializationWait = 100,
},
```

These settings control performance-related thread timing.

#### `closestCheckInterval`

How often nearby scenes are checked.

#### `renderSleepInterval`

Thread delay when there are no nearby scenes to render.

#### `renderActiveInterval`

Thread delay when scenes are actively being rendered.

#### `initializationWait`

Initial wait time used during resource startup.

***

### Server Configuration

```lua
Server = {
    expireCheckInterval = 60000,
    durationMultiplier = 3600,
    databaseTable = 'scenes',
    logName = 'opis2',
},
```

#### `expireCheckInterval`

Defines how often the server checks for expired scenes.

```lua
expireCheckInterval = 60000
```

#### `durationMultiplier`

Defines how the duration input is converted into seconds.

```lua
durationMultiplier = 3600
```

With this value, the UI duration input is treated as hours.

#### `databaseTable`

Defines the database table name used by the resource.

```lua
databaseTable = 'scenes'
```

#### `logName`

Defines the `msk_bridge` log channel used for resource logging.

```lua
logName = 'opis2'
```

***

### Restricted Zones

Restricted zones are areas where players cannot place scenes.

Example:

```lua
RestrictedZones = {
    vec4(441.2379, -982.6951, 29.7544, 50.0),
    vec4(-808.5073, -1235.9198, 5.7705, 50.0),
}
```

Each entry uses:

* `x`
* `y`
* `z`
* `radius`

This is useful for blocking scene placement in areas such as police stations, hospitals, or other protected locations.

***

### Commands

Command names and permission groups are configurable in `config.lua` under `Commands`.

#### Default Commands

* `/opis2` — open scene creation menu
* `/usunopis2 [radius]` — delete all scenes within a radius
* `/opisadmin` — open admin panel

#### Access

* `/opis2` — available for normal users if allowed
* `/usunopis2` — staff only
* `/opisadmin` — staff only

You can rename commands and change allowed groups in the config.

***

### Fonts

The resource supports both built-in GTA fonts and custom addon fonts.

#### Built-in GTA Fonts

* `4` — Chalet Comprimé
* `0` — Chalet
* `1` — Sign Painter
* `7` — Pricedown

#### Addon Fonts

Custom fonts are streamed through the `stream/` folder.

Examples:

* Arial Narrow
* Lato
* Inkfree
* Kid
* Strawberry
* Paper Daisy
* A Little Sunshine
* Write Me A Song
* Beat Street
* Dirty Lizard
* Maren
* Happy Day
* Impact Label
* Easter

#### Adding a Custom Font

Place the `.gfx` file inside `stream/` and register it in config:

```lua
AddonFonts = {
    { "MyFont", "My Font Display Name" },
}
```

Format:

* first value = file name without extension
* second value = display name shown in the UI

***

### Backgrounds

The resource includes multiple background styles for scenes.

Available styles include:

* None
* Sleek
* Simple
* Blood
* Brush
* Chain
* Metal
* Gradient
* Noise
* Note
* Spray

Background textures are stored in:

* `stream/scenes.ytd`

Custom backgrounds can be added by editing the YTD and registering them in the UI.

***

### Scene Creation

Scenes are created directly in-game.

#### Default Flow

1. Use `/opis2`
2. Aim at a wall or surface
3. Configure the text, font, background, color, size, and duration
4. Place the scene in the world

Admins can manage scenes through `/opisadmin` or remove nearby scenes with `/usunopis2`.

***

### Notes

* `msk_tokenizer` is required because server events are token-protected
* `durationMultiplier = 3600` means UI duration input is treated as hours
* Text supports inline color tags, bold text, new lines, and emojis
* Scenes expire automatically and are cleaned from the database


---

# 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/3d-scene-description/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.