# Configuration

> Configuration reference for ML Diary

Category: DIARY · Source: https://miciomods.it/docs/ml-diary-configuration · Last updated: 2026-07-09

## Overview

- `shared/config.lua`: General settings, mode, item names, limits, post-it colors, book content, discoverables, command names
- `shared/config.lua`: Cover, manual pages, encyclopedia categories, post-it colors
- `server/config_server.lua`: Logger backend and Discord webhook URLs

## General

**shared/config.lua**

```lua
Config.Debug = false
Config.Locale = 'en'
Config.SaveInterval = 10
Config.DiaryMode = 'metadata'
Config.DiaryItemName = 'diary'
Config.TornPageItemName = 'diary_page'
```

- `Debug`: Console output for troubleshooting
- `Locale`: Language code for translations. Falls back to `en` when missing
- `SaveInterval`: Auto-save frequency in minutes. Only writes diaries flagged as dirty
- `DiaryMode`: Storage model (see below)
- `DiaryItemName`: Inventory item name for the diary
- `TornPageItemName`: Item name for torn/shared pages

## Diary Mode

`Config.DiaryMode` controls how diary data is keyed and shared.

### `'metadata'` (default)

The diary is a transferable physical object. Each diary item carries a unique `serial` in its metadata; all data is keyed on that serial. Whoever is currently holding the item can read it, write notes, and unlock discoveries, including players who received it as a gift, looted it, or stole it. The original creator is recorded for audit only and does not gate access.

### `'license'`

The diary is bound to the player's identifier. The serial is derived as `LICENSE-<identifier>`, so any diary item the player picks up opens their personal logbook. Other players cannot read or modify it even if they hold a diary item that previously belonged to that license.

## Limits

**shared/config.lua**

```lua
Config.PersonalPageLimit = 15
Config.MaxTextSize = 8192          -- 8 KB per text note
Config.MaxDataUrlSize = 524288     -- 512 KB per drawing
Config.MaxDiaryTotalSize = 4194304 -- 4 MB total per diary
```

- `PersonalPageLimit`: Maximum number of user-written pages. Pages added by other scripts via `addPersonalNote` bypass this limit (see Developer page)
- `MaxTextSize`: Maximum byte size of a single text note's content
- `MaxDataUrlSize`: Maximum byte size of a single drawing (base64 data URL)
- `MaxDiaryTotalSize`: Hard cap on the total combined size of all notes in a single diary, enforced on every save and external add

## Admin Commands

**shared/config.lua**

```lua
Config.Commands = {
    unlockAll      = { name = 'diary_unlockall', help = '...' },
    unlock         = { name = 'diary_unlock',    help = '...' },
    unlockCategory = { name = 'diary_unlockcat', help = '...' },
    resetAll       = { name = 'diary_reset',     help = '...' },
}
```

- `unlockAll`: Unlock every entry in `Config.Discoverables` for the diary the admin is currently holding
- `unlock`: Unlock a single entry by key
- `unlockCategory`: Unlock every entry in a category
- `resetAll`: Clear every discovery for the diary the admin is currently holding

Permissions are checked via `Bridge.HasPermission(source)`, which reads the ACE group configured in `ml_bridge`. Renaming a command here also renames the in-game command, useful for avoiding collisions or matching server conventions.

## Post-It Colors

**shared/config.lua**

```lua
Config.PostItColors = {
    ['yellow'] = { background = '#fef08a', text = '#3f3931' },
    ['pink']   = { background = '#fecdd3', text = '#881337' },
    ['blue']   = { background = '#bfdbfe', text = '#1e3a8a' },
    ['green']  = { background = '#bbf7d0', text = '#14532d' },
}
```

- `background`: Background hex color
- `text`: Text hex color

## Book System

The diary contains a static manual with pre-written pages and a dynamic encyclopedia with player-unlocked discoveries.

### Cover

The front cover is configurable. Texts fall back to the locale file when left `nil`; colors accept any CSS color; each decorative element toggles independently.

**shared/config.lua**

```lua
Config.Book.cover = {
    title    = nil,            -- nil = read from locale (cover_* keys)
    subtitle = nil,            -- empty string hides it
    hint     = nil,            -- e.g. 'Click to open'

    titleColor    = '#c4a675',
    subtitleColor = '#a08565',
    ornamentColor = '#c4a675',

    showEmbossedFrame   = true,
    showStitching       = true,
    showCornerOrnaments = true,
    showSpineHighlight  = true,
    showLeatherStraps   = false,

    centerEmblem = '',         -- '' = no emblem, e.g. 'fa-skull'
}
```

- `title`, `subtitle`, `hint`: Cover texts. `nil` reads the matching `cover_*` locale key; an empty string hides the element
- `titleColor`, `subtitleColor`, `ornamentColor`: Lettering and gold-ornament colors
- `showEmbossedFrame`, `showStitching`, `showCornerOrnaments`, `showSpineHighlight`, `showLeatherStraps`: Toggle each decorative element on or off
- `centerEmblem`: Optional FontAwesome icon above the title (e.g. `'fa-skull'`). Empty string for no emblem

### Manual Pages

**shared/config.lua**

```lua
Config.Book = {
    manual = {
        title = 'Survival Guide',
        pages = {
            {
                title = 'Welcome',
                content = {
                    { type = 'polaroid', image = 'https://...', caption = 'Your first shelter' },
                    { type = 'text', value = 'Your text here.' },
                    { type = 'text', value = 'Bold red text.', style = { 'bold', 'red' } },
                    { type = 'post-it', text = 'Tip text', color = 'yellow' },
                },
            },
        },
    },
}
```

Each page has a `title` and a `content` array of mixed blocks:

- `text`: Plain text. Optional `style` array: `'bold'`, `'italic'`, `'red'`, etc.
- `polaroid`: Image with caption
- `post-it`: Colored sticky note. `color` must match a key in `Config.PostItColors`

### Encyclopedia Categories

**shared/config.lua**

```lua
Config.Book.encyclopedia = {
    title = 'Encyclopedia',
    introText = 'Introduction text...',
    categories = {
        ['fauna']     = { label = 'cat_fauna',     icon = 'fa-dragon' },
        ['flora']     = { label = 'cat_flora',     icon = 'fa-leaf' },
        ['locations'] = { label = 'cat_locations', icon = 'fa-map-marked-alt' },
        ['items']     = { label = 'cat_items',     icon = 'fa-gem' },
        ['notes']     = { label = 'cat_notes',     icon = 'fa-scroll' },
    },
}
```

- `label`: Locale key for the category name
- `icon`: FontAwesome class for the category icon

Add or remove categories as needed. Each category collects discoverables that have a matching `collection` field.

## Discoverables

Entries that players unlock through exploration. Each key in `Config.Discoverables` is a unique identifier.

**shared/config.lua**

```lua
Config.Discoverables = {
    ['example_animal'] = {
        type        = 'model',
        model       = 'a_c_deer',
        name        = 'White-Tailed Deer',
        subTitle    = 'Forest Herbivore',
        description = 'A common deer found in forested areas...',
        collection  = 'fauna',
        icon        = 'fa-paw',
        image       = 'https://...',
        imageStyle  = 'sketch',
        layoutStyle = 'vertical',
        stats       = {
            ['TYPE']   = 'Herbivore',
            ['RARITY'] = 'Common',
        },
    },
}
```

- `type`: Detection method (see below)
- `model`: GTA model name or hash. Can be a string or array of strings to match multiple models
- `name`: Display name in the encyclopedia
- `subTitle`: Secondary label
- `description`: Full description text
- `collection`: Must match a category key in `Config.Book.encyclopedia.categories`
- `icon`: FontAwesome icon class
- `image`: Image URL displayed in the entry page
- `imageStyle`: Visual frame style: `'polaroid'`, `'taped'`, `'sketch'`, `'noir'`, `'stamp'`
- `layoutStyle`: `'vertical'` (portrait) or `'horizontal'` (landscape)
- `stats`: Key-value table displayed as a stats box

### Discovery Types

**Model detection**: Triggers when the player targets a specific prop or ped model:

**shared/config.lua**

```lua
{
    type = 'model',
    model = 'a_c_deer',
    -- or multiple: model = { 'a_c_deer', 'a_c_deer_02' },
}
```

**Sphere zone**: Triggers when the player enters a sphere zone:

**shared/config.lua**

```lua
{
    type = 'sphere',
    coords = vec3(100.0, 200.0, 30.0),
    radius = 15.0,
}
```

**Box zone**: Triggers when the player enters a box zone:

**shared/config.lua**

```lua
{
    type = 'box',
    coords = vec3(100.0, 200.0, 30.0),
    size = vec3(10.0, 10.0, 5.0),
    rotation = 45,
}
```

**Inventory item**: Triggers when the player holds a specific item. A poller checks every 5 seconds while the diary is in the inventory and stops once all item-type entries are unlocked:

**shared/config.lua**

```lua
{
    type = 'item',
    item = 'bandage',
}
```

- `item`: The item name as registered in the inventory system. The check runs through `Bridge.HasItem`, so it works on every inventory supported by `ml_bridge` (ox, qb, esx, tgiann, and others).

All four types are validated server-side: model and zone unlocks require the player to actually be in range, item unlocks require the player to actually hold the configured item. Forged attempts are rejected and logged to the exploits webhook.

## Logger Backend

**server/config_server.lua**

```lua
Config.Logger = 'discord'
```

- `'discord'`: Uses Discord webhook URLs
- `'ox_lib'`: Routes logs to DataDog, FiveManage, or Loki based on your ox_lib config

## Discord Webhooks

**server/config_server.lua**

```lua
Config.DiscordWebhook = {
    DiaryActions     = 'INSERT_WEBHOOK_LINK_HERE',
    DiscoveryActions = 'INSERT_WEBHOOK_LINK_HERE',
    PageActions      = 'INSERT_WEBHOOK_LINK_HERE',
    ExploitDetected  = 'INSERT_WEBHOOK_LINK_HERE',
}
```

- `DiaryActions`: Diary open/close events, admin command usage
- `DiscoveryActions`: Discovery unlock/remove events
- `PageActions`: Note creation, deletion, and torn page transfers
- `ExploitDetected`: Distance spoof attempts, ownership mismatches, malformed payloads

Set any webhook to `false` to disable that log entirely.